TESTCLOUD(1)

🌸 TESTCLOUD(1) — the testcloud manual page 🌸

okay bestie, sit down, hydrate, and let me tell you about testcloud 💖 this is the man page for testcloud, and it's genuinely one of the most useful little helpers out there, no cap.

---

✨ NAME ✨

testcloud — download qcow2 cloud images and boot them locally. 🦋

---

✨ SYNOPSIS ✨

testcloud [-h, --help] [COMMAND]... [OPTION]... [SUBCOMMAND]... [OPTION]...

---

✨ DESCRIPTION ✨

so testcloud is this small helper script that downloads and boots cloud/coreos images right on your machine, locally, like it's nothing. 💅 and it supports a wide range of distributions, which is giving versatility:

• Fedora
• Fedora CoreOS
• CentOS
• CentOS Stream
• Red Hat Enterprise Linux
• Debian
• Ubuntu

iconic lineup honestly.

testcloud can run either in system mode or in constrained user session mode, which is useful for running it, e.g., in unprivileged containers. 🫶

To run testcloud, you need to hand it the URL of a cloud image, or a string in distribution:version format — that's what it uses for booting.

If you don't have an image location of your own, no stress, you can use one of the images from the Fedora Cloud download pages at https://alt.fedoraproject.org/cloud/. 🎀

Then here's the tea: testcloud will download the image and save it in /var/lib/testcloud/backingstores/. It will use this image to create a backing store for a newly created instance, which gets placed in /var/tmp/instances/. And the best part? When the same image has been previously downloaded, testcloud will NOT download it again — it just uses the current image to create the instance. obsessed. ✨

When the new instance is created, testcloud will show its IP address, which you can use to access the running instance via ssh. The login name is fedora and the password is passw0rd. (yes really, write that down 🍓) The IP address of an instance is shown when you list the instance — see COMMANDS.

The instance can also be manipulated and controlled with virt-manager. 👑

---

✨ CONFIGURATION ✨

The default configuration should work for many people. However, if you need to override the default settings, you can do it in the settings.py file. The example file in conf/settings-example.py shows the available configuration values which you can alter to suit your needs. 🌈

The configuration file must be placed in one of the following locations in order to be recognized:

• conf/settings.py in the git checkout
• ~/.config/testcloud/settings.py
• /etc/testcloud/settings.py

bestie, if it's not in one of those three spots, it simply does not exist to testcloud. it's giving invisible. 💀

---

✨ COMMANDS ✨

• image — control and manipulate the images (see OPTIONS) for more details.

---

✨ OPTIONS ✨

• -h, --help — shows the help message and exits. 🎀
• -c CONNECTION, --connection CONNECTION — provide the URL of a remote libvirt instance to be used instead of the local one. This option can be used with the instance command only.

---

✨ SUBCOMMANDS ✨

• create — create a new instance. See the INSTANCE CREATE OPTIONS section for more details. 🌸
• list — list available running instances and images. Use the --all options to list all instances.
• start — start an existing instance.
• stop — stop a running instance.
• reboot — force the instance to reboot. 🔥
• remove — remove an instance or image. If an instance is running, it cannot be removed without the -f option.
• destroy — remove an instance or image. Deprecated, do not use. ⚠️
• clean — remove non-existing or unsynced libvirt VMs from testcloud.

---

✨ INSTANCE CREATE OPTIONS ✨

• URL — specify the URL from where testcloud should download the instance qcow2 image, or a distro:version handle. This option is compulsory. no skipping it, bestie, it's mandatory. 💅

Some examples of supported short urls:

• fedora:rawhide (latest compose), fedora:33, fedora:latest (latest Fedora GA image)
• fedora-coreos:next, fedora-coreos:testing, fedora-coreos:stable
• fedora:qa-matrix (image from https://fedoraproject.org/wiki/Test_Results:Current_Cloud_Test )
• centos:XX (eg. centos:8, centos:latest)
• centos-stream:XX (eg. centos-stream:8, centos-stream:latest)
• ubuntu:release_name (eg. ubuntu:focal, ubuntu:latest)
• debian:release_name/release_number (eg. debian:11, debian:sid, debian:latest)

• -n, --name NAME — set desired instance name. A nice and memorable name will be generated for you if not specified. 🎀 (the auto-names are cute, trust)
• --arch ARCH — set the desired guest architecture. Host arch is the default, supported are: x86_64, aarch64, ppc64le, and s390x.
• --ram RAM — set the amount of RAM that will be available to the instance's VM (in MiB).
• --vcpus VCPUS — set the number of virtual CPU cores to be assinged to the VM.
• --disksize DISKSIZE — set the disk size of the instance VM (in GiB).
• --vnc — open a VNC connection to the :1 display of the instance VM. 👀
• --no-graphic — turn off the instance VM's graphical display.
• --timeout TIMEOUT — specify the time (in seconds) to wait for the instance boot to complete. To disable waiting time (default behaviour) set to 0.
• --disk_number — to provide disk number you want
• --nic_number — to provide nic number you want
• --virtiofs — to specify a local directory to mount and mount target like <host path>:<guest path>
• --iommu — to provide virtual iommu device

🌈 ADDITIONAL COREOS OPTIONS 🌈

• --bu_file BU_FILE — to provide a bu_file you want to use
• --ign_file IGN_FILE — to provide an ign_file you want to use
• --ssh_path — to provide a ssh pubkey path you want to use

---

✨ EXAMPLES ✨

Create a new instance:

testcloud create <URL>

List all available instances:

testcloud list

Start an existing instance:

testcloud start <instance_name>

Stop an existing instance:

testcloud stop <instance_name>

Remove a running instance:

testcloud remove -f <instance_name>

---

✨ SEE ALSO ✨

testcloud's help and the Project's README.md file 🫶

---

✨ BUGS ✨

No known bugs. If you have found a bug, please report it at https://bugzilla.redhat.com. 🐛

---

✨ AUTHOR ✨

Mike Ruckman (roshi@fedoraproject.org) 👑

---

and that's the whole thing bestie, you ate that 💅 this was version 1.0, dated 11 Nov 2020 — go forth and boot some cloud images, you've got this 🌸🦋💖