Package: testcloud
testcloudtestcloudis a small helper script to download and boot cloud/coreos VM images
locally. Testcloud supports wide range of distributions, namely Fedora, Fedora CoreOS,
CentOS, CentOS Stream, Red Hat Enterprise Linux, Debian and Ubuntu.testcloudcan run either in system mode or in constrained user session mode,
which is useful for running testcloud and its VMs in unprivileged containers.InstallationThe following procedure should only be used to installtestcloudon
a production system. For developing purposes, you need a different kind
of installation which is described in theTestcloud Developmentsection below.To usetestcloudon a production system:Install thetestcloud.```
$ sudo dnf install testcloud
```Add yourself to thetestcloud group.$ sudo usermod -a -G testcloud $USERRestart your user session to update the group privileges, or usesu -to get a login shell for that particular user where the group
settings will be updated.$ su -i $USERNow, you are ready to usetestcloud.Using testcloudCreating a new instanceTo create a new instance, you will need to provide distribution and version you wish to use or the url of some cloud
image in theqcow2format. If you do not have an image location of
your own, you can use the image from theFedora Clouddownload pages
(https://alt.fedoraproject.org/cloud/).To create a new instance with the cloud image, run:$ testcloud create <url for qcow2 image> or <distro:version>Some examples how to create an instance with distribution:version shortcut:# Latest Fedora Release
$ testcloud create fedora# Fedora Rawhide (latest Nightly Compose)
$ testcloud create fedora:rawhide# CentOS Stream 8
$ testcloud create centos-stream:8# Ubuntu Hirsute (21.04)
$ testcloud create ubuntu:hirsute# Debian 11
$ testcloud create debian:11Supported distributions with shortcuts are: Fedora, CentOS, CentOS Stream, Ubuntu, Debian, Alma, Rocky, and Oracle.
For other distributions, you can provide link to basically any qcow2 image which has the cloud-init package included.Testcloud supports also Vagrant .box files, in a limited manner and currently only for Fedora and CentOS.testcloudwill download theqcow2image and save it in the/var/lib/testcloud/backingstores/<qcow2-filename>. It will use this
image a backing store for the newly created instance in/var/tmp/instances/<instance-name>. When the image has been already
downloaded,testcloudwill use the previously download image to
create the instance.To create a new instance with the coreos image, run:$ testcloud create fedora-coreos:<stream> or <url for qcow2 image>You will be able to see the instance using thelistcommand.$ testcloud listAlternatively, the instances can also be viewed and manipulated using
thevirt-managertool.Creating an instance with specific architectureInstances can be created with a different architecture than the host architecture. You'll need to have a proper
qemu binary installed for this to work (eg. qemu-system-aarch64-core for aarch64 on x86_64 on Fedora). Supported
architectures in testcloud are: x86_64, aarch64, ppc64le, and s390x. Any combinations of these are supported.Some examples:# Fedora aarch64 on x86_64 (or any other)
$ testcloud create fedora --arch aarch64# CentOS Stream x86_64 on aarch64 (or any other)
$ testcloud create centos-stream --arch x86_64# Fedora Rawhide ppc64le on aarch64 (or any other)
$ testcloud create fedora:rawhide --arch ppc64leStarting, stopping, and removing an instanceInstances can be started and stopped using theinstanceinterface of
thetestcloud, too:List all instances to see the correct name of the instance:```
$ testcloud list
```Start the instance:```
$ testcloud start <instance-name>
```Stop the instance:```
$ testcloud stop <instance-name>
```Remove the instance:```
$ testcloud remove <instance-name>
```Removing the instance only succeeds when the appropriate instance has
beenstoppedbefore. However, you can use the-foption to force
removing the instance.Other instance operationsReboot the instance:```
$ testcloud reboot <instance-name>
```Remove non-existing libvirt VMs from testcloud:```
$ testcloud clean
```Logging into the instanceWhen the cloud/coreos instance is created,testcloudwill return its IP address
that you can use to access the running instance viassh. The defaultlogin
nameiscloud-userand thepasswordispassw0rd. Testcloud will output info how you can connect to any of the Supported Distributions.ssh cloud-user@<instance-IP>The IP address of an instance is also shown when you list the instance
using thetestcloud listcommand. You can also control the
instance using thevirt-manager,GNOME Boxesor any other tool to manage libvirt VMs.Available options to create an instanceThere are several options (all optional) that can be used to create a
new instance usingtestcloud.-c, --connection QEMU_URI: You can specify uri to qemu you wish to use. For limited environments, you might wish to useqemu:///session. Remote connections other thanqemu:///sessionandqemu:///system(like qemu+ssh,...) are known to be problematic.--arch ARCH: To request a speciffic architecture for the guest. The default
|    is the architecture of the host system.--ram RAM: To set the amount of RAM that will be available to the virtual
machine (in MiB).--vcpus VCPUS: To set the amount of VCPUS that will be available to the virtual
machine.--no-graphic: This turns off the graphical display of the virtual machine.--vnc: To open a VNC connection at the:1display of the instance.-n, --name NAME: To specify a custom name for you instance.--timeout TIMEOUT: A time (in seconds) to wait for boot to complete. Setting to 0
(default) will disable this functionality.--disksize DISKSIZE: To set the disk size of the virtual machine (in GiB)--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 :There are several additional options that can be used to create a
new Coreos instance usingtestcloud.--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 ssh pubkey pathConfigurationThe default configuration should work for many people but those defaults
can be overridden through the use of asettings.pyfile containing the
values to use when overriding default settings. The example file inconf/settings-example.pyshows the possible configuration values which
can be changed.Note that in order for those new values to be picked up, the filename
must besettings.pyand that file must live in one of the following
locations:conf/settings.pyin the git checkout~/.config/testcloud/settings.py/etc/testcloud/settings.pyFor example, if you wanted to set up an ssh accessible root account that
uses an ssh key as the authentification method, you could provide the
following to the~/.config/testcloud/settings.py:USER_DATA = """#cloud-configusers:-default-name:rootpassword:%schpasswd:{expire:False}ssh-authorized-keys:-<my ssh pub key>"""Testcloud DevelopmentTo developtestcloud, you need to perform a more complicated process
to install all its dependencies, download the source code and perform a
set-up.To installtestcloudfor development purposes:PrerequisitesInstall the dependencies fortestcloud.```
$ sudo dnf install libvirt python3-libvirt libguestfs libguestfs-tools python3-requests python3-jinja2
```Startlibvirtd.```
$ sudo systemctl start libvirtd
```Add thetestcloudgroup to the system.```
$ sudo groupadd testcloud
```Add a user into thetestcloudgroup.```
$ sudo usermod -a -G testcloud $USER
```Log out of the system and log in again to update the group
information on your user or use a login shell on a different
terminal.```
$ su - $USER
```InstallationClone thetestcloudrepository.```
$ git clone https://pagure.io/testcloud.git
```Create the application directories.```
$ sudo mkdir -p -m 775 /var/lib/testcloud
```

```
$ sudo mkdir -p -m 775 /var/lib/testcloud/instances
```

```
$ sudo mkdir -p -m 775 /var/lib/testcloud/backingstores
```Change ownership on these directories to enable their use withtestcloud.```
$ sudo chown qemu:testcloud /var/lib/testcloud
```

```
$ sudo chown qemu:testcloud /var/lib/testcloud/instances
```

```
$ sudo chown qemu:testcloud /var/lib/testcloud/backingstores
```Copy the.rulesfile to thepolkitrules.```
$ sudo cp conf/99-testcloud-nonroot-libvirt-access.rules /etc/polkit-1/rules.d/
```Running testcloudNavigate to yourtestcloudgit repository.```
$ cd testcloud
```Execute therun_testcloud.pyscript to run thetestcloud. You
can use any options as with the regular installation, for example:```
    $ ./run_testcloud.py instance create ...
```Alternatively, you can usepipto installtestcloudonto the
system and then use it like it has been installed normally.```
$ pip3 install -e . --user
```TestingThere is a small testsuite you can run with:toxThis is a good place to contribute if you're looking to help out.Issue Tracking and RoadmapOur project tracker is on the Fedora QA-develPagureinstance.CreditThanks toOddshocksfor the koji
downloader code :)LicenseThis code is licensed GPLv2+. See the LICENSE file for details.