Parameters

The test configuration file is used for controlling the framework by specifying parameters for each test. The parser produces a list of dictionaries (see an explanation of the file format?), each of which specifies the parameters for a single test. Each parameter is used (read) by the test dispatching system, by the pre-processor, by the post-processor, or by the test itself.

Some parameters are required and others are optional.

Most parameters should be specified in the test configuration file by the user. Few parameters are produced automatically by the configuration file parser, so when using the parser, these must not be specified by the user. Recent kvm-autotest support passing some basic parameters through the command line?.

All parameters are strings, except depend?, which is a list of strings. depend? is automatically generated by the parser, so the user probably should not be concerned with it.

You may also want to check the complete reference documentation on parameters.

Addressing objects (VMs, images, NICs etc)

Before listing the parameters, it is important to clarify how objects like VMs should be addressed in the test parameters.

For the following example we shall assume that our system accepts a parameter vms? which lists the VM objects to be used in the current test. Typical usage of the parameter would be:

vms = vm1 second_vm another_vm

This would indicate that our test requires 3 VMs. Let us now assume that a VM object accepts a parameter mem which specifies the amount of memory to give the VM. In order to specify mem for vm1, we may write:

mem_vm1 = 512

and in order to specify it for second_vm we may write:

mem_second_vm = 1024

If we wanted to specify mem for all existing VM objects, we would write:

mem = 128

However, this would only apply to another_vm, because the previous statements, which each specify mem for a single VM, override the statement that specifies mem for all VMs. The order in which these statements are written in a configuration file is not important; statements addressing a single object always override statements addressing all objects.

Let us now further assume that a VM object accepts a parameter images, which lists the disk image objects to be used by the VM. Typical usage of images, with regard to vm1, would be:

images_vm1 = first_image image2 a_third_image yet_another_image

We shall also assume that an image object accepts two parameters: image_name, which specifies the filename of the disk image, and image_size, which specifies the size of the image (e.g. 10G). In order to specify these with regard to first_image, which is the first image of vm1, we may write:

image_name_first_image_vm1 = fc8-32-no-acpi
image_size_first_image_vm1 = 20G

Note the order in which the objects are addressed: first the parameter, then the image, then the VM. In order to specify these parameters for all images of vm1, we may write:

image_name_vm1 = fc8-32
image_size_vm1 = 10G

However, these statements would not apply to first_image of vm1, because the previous statements, which addressed this image specifically, override the statements that address all objects. If we chose to specify these parameters for all images of all VMs, we would write:

image_name = fc8-32-something
image_size = 5G

However, these would not apply to the images of vm1, because previous statements apply specifically to those images.

Parameters used by the test dispatching system

The test dispatching system consists of the control file and the framework’s main python module (currently named kvm_runtest_2.py). This system executes the proper test according to the supplied parameters.

Parameter Effect/meaning Required?
type? Specifies the type of test to run (e.g. boot, migration etc) yes
skip? If equals ‘yes’, the test will not be executed no
name? The full name (not type) of the test (e.g. qcow2.ide.Fedora.8.32.install); see test configuration file format?. This parameter is generated by the parser. yes
shortname? The short name of the test (e.g. Fedora.8.32.install); see test configuration file format?. This parameter is generated by the parser. It specifies the tag to append to the Autotest test name, so that eventually the test name becomes something like kvm_runtest_2.Fedora.8.32.install. yes
depend? The full names of the dependencies of this test (e.g. [‘qcow2.openSUSE-11.install’, ‘openSUSE-11.boot’]). This parameter is a list of strings, not a string, and is generated by the parser. The test dispatcher will not run a test if one or more of its dependencies have run and failed. yes

Parameters used by the preprocessor

The preprocessor runs before the test itself. It prepares VMs and images for the test, according to the supplied parameters.

Parameter Effect/meaning Required?
vms? Lists the VM objects to be used in the test. Listed VMs that do not exist will be created. Existing VMs that are not listed will be destroyed and removed. yes

VM preprocessor parameters

These parameters should be specified for each VM as explained above in addressing objects.

Parameter Effect/meaning Required?
start_vm? If equals ‘yes’, the VM will be started if it is down; this parameter should be set to ‘yes’, for a certain VM object, in all tests that require the VM to be up. no
restart_vm? If equals ‘yes’, the VM will be (re)started, regardless of whether it’s already up or not no
start_vm_for_migration? If equals ‘yes’, the VM will be (re)started with the -incoming option so that it accepts incoming migrations; this parameter should be set to ‘yes’ for the destination VM object in a migration test. no

The following parameters are remembered by a VM object when it is created or started. They cannot be changed while a VM is up. In order to change them, the VM must be restarted with new parameters.

Parameter Effect/meaning Required (when creating or starting a VM)
cdrom? Specifies the name of an image file to be passed to QEMU with the -cdrom option. This is typically an ISO image file. no
md5sum? If specified, the VM will not be started (and thus the test will fail) if the MD5 sum of the cdrom image doesn’t match this parameter. This is intended to verify the identity of the image used. no
md5sum_1m? Similar to md5sum, but specifies the MD5 sum of only the first MB of the cdrom image. If specified, this parameter is used instead of md5sum. Calculating the MD5 sum of the first MB of an image is much quicker than calculating it for the entire image. no
mem Specifies the amount of memory, in MB, the VM should have yes
display Selects the rendering method to be used by the VM; valid values are ‘vnc’, ‘sdl’ and ‘nographic’. If ‘vnc’ is selected, the VM will be assigned an available VNC port automatically. no
extra_params? Specifies a string to append to the QEMU command line, e.g. ‘-snapshot’ no
use_telnet? If equals ‘yes’, communication with the guest will be done via Telnet; otherwise SSH will be used. no
ssh_port? Specifies the guest’s SSH/Telnet port; should normally be 22, unless Telnet is used, in which case this parameter should be 23. if the VM should support SSH/Telnet communication
ssh_prompt? A regular expression describing the guest’s shell prompt if the VM should support SSH/Telnet communication
username? Specifies the username with which to attempt to log into the guest whenever necessary if the VM should support SSH/Telnet communication
password? Specifies the password with which to attempt to log into the guest whenever necessary if the VM should support SSH/Telnet communication
cmd_shutdown? Specifies the shell command to be used to shut the guest down (via SSH/Telnet) whenever necessary if the VM should support being shutdown via SSH/Telnet
cmd_reboot? Specifies the shell command to be used to reboot the guest (via SSH/Telnet) whenever necessary if the VM should support rebooting via SSH/Telnet
images Lists the image objects to be used by the VM yes
nics Lists the NIC objects to be used by the VM yes

A VM will be restarted automatically if a parameter change leads to a different QEMU command line (for example, when mem changes). However, when other parameters change (such as cmd_shutdown) the VM will not be automatically restarted (unless restart_vm is set to ‘yes’), and the change will have no effect.

Image preprocessor parameters

The following parameters should be specified for each image of each VM, as explained in addressing objects.

Parameter Effect/meaning Required?
create_image If equals ‘yes’, the image file will be created using qemu-img if it doesn’t already exist no
force_create_image If equals ‘yes’, the image file will be created using qemu-img regardless of whether it already exists. If the file already exists it will be overwritten by a blank image file. no
image_name Specifies the image filename without the extension yes
image_format Specifies the format of the image to be created/used, e.g. qcow2, raw, vmdk etc yes
image_size Specifies the size of the image to be created, in a format understood by qemu-img (e.g. 10G) only when creating an image
drive_format Specifies a string to pass to QEMU as the drive’s ‘if’ parameter (e.g. ide, scsi) no
image_snapshot? If equals ‘yes’, ‘snapshot=on’ will be appended to the ‘drive’ option passed to QEMU no
image_boot? If equals ‘yes’, ‘boot=on’ will be appended to the ‘drive’ option passed to QEMU no

NIC preprocessor parameters

The following parameters should be specified for each NIC of each VM, as explained in the section “addressing objects”.

Parameter Effect/meaning Required?
nic_model? A string to pass to QEMU as the NIC’s ‘model’ parameter (e.g. e1000, virtio) no

Parameters used by the postprocessor

The postprocessor runs after the test itself. It can shut down VMs, remove image files and clean up the test’s results dir.

The suffix _on_error may be added to all parameters in this section (including VM and image parameters) to define special behavior for tests that fail or result in an error. The suffix should be added after all object addressing suffixes. If a parameter is specified without the suffix, it applies both when the test passes and when it fails. If a parameter is specified with the suffix, it applies only when the test fails, and overrides the parameter without the suffix.

For example, if we wanted the postprocessor to shut down vm1 after the test, but only if the test failed, we’d write:

kill_vm_vm1_on_error = yes

If we wanted to shut down another_vm only if the test passed, we’d write:

kill_vm_another_vm = yes
kill_vm_another_vm_on_error = no

Since PPM files are normally used for debugging test failures, it would be very reasonable to choose to keep them only if the test fails. In that case we’d write:

keep_ppm_files = no
keep_ppm_files_on_error = yes

The following parameters define the postprocessor’s behavior:

Parameter Effect/meaning Required?
vms? Lists the VM objects to be handled by the postprocessor yes
keep_ppm_files If equals ‘yes’, the PPM image files in the test’s debug directory will not be removed no

VM postprocessor parameters

These parameters should be specified for each VM as explained above in “addressing objects”.

Parameter Effect/meaning Required?
kill_vm If equals ‘yes’, the VM will be shut down after the test no
kill_vm_gracefully If equals ‘yes’, and kill_vm equals ‘yes’, the first attempt to kill the VM will be done via SSH/Telnet with a clean shutdown command (rather than a quick ‘quit’ monitor command) no
kill_vm_timeout If kill_vm equals ‘yes’, this parameter specifies the time duration (in seconds) to wait for the VM to shut itself down, before attempting to shut it down externally; if this parameter isn’t specified the VM killing procedure will start immediately following the test. This parameter is useful for tests that instruct a VM to shut down internally and need the postprocessor to shut it down only if it fails to shut itself down in a given amount of time no
images Lists the images objects, for this VM, to be handled by the postprocessor no

Image postprocessor parameters

These parameters should be specified for each image of each VM as explained above in “addressing objects”.

Parameter Effect/meaning Required?
remove_image If equals ‘yes’, the image file will be removed after the test no

Test parameters

Any number of additional parameters may be specified for each test, and they will be available for the test to use. See the tests? page for a list of tests and the parameters they use.

Real world example

The following example dictionary is taken from a dictionary list used in actual tests. The list was generated by the config file parser.

Dictionary #363:
    cmd_reboot = shutdown -r now
    cmd_shutdown = shutdown -h now
    depend = ['custom.qcow2.ide.default.up.Linux.Fedora.9.32.e1000.install',
         'custom.qcow2.ide.default.up.Linux.Fedora.9.32.e1000.setup',
         'custom.qcow2.ide.default.up.Linux.Fedora.9.32.default_nic.install',
         'custom.qcow2.ide.default.up.Linux.Fedora.9.32.default_nic.setup']
    drive_format = ide
    image_boot = yes
    image_format = qcow2
    image_name = fc9-32
    image_size = 10G
    images = image1
    keep_ppm_files = no
    keep_ppm_files_on_error = yes
    kill_vm = no
    kill_vm_gracefully = yes
    kill_vm_on_error = yes
    main_vm = vm1
    mem = 512
    migration_dst = dst
    migration_src = vm1
    migration_test_command = help
    name = custom.qcow2.ide.default.up.Linux.Fedora.9.32.e1000.migrate.1
    nic_model = e1000
    nics = nic1
    password = 123456
    shortname = Fedora.9.32.e1000.migrate.1
    ssh_port = 22
    ssh_prompt = \[root@.{0,50}][\#\$]
    start_vm = yes
    start_vm_for_migration_dst = yes
    type = migration
    username = root
    vms = vm1 dst

The test dispatching system

This test’s name is a rather long string that indicates all the variants this test belongs to; its shortname, however, is much shorter: Fedora.9.32.e1000.migrate.1.

The test depends on 4 other tests, as indicated by the depend? parameter. The listed strings are the names of these tests. If any of these 4 tests runs and fails, the current test will be skipped.

Preprocessing

This test requires two VMs as indicated by the vms? parameter: one will be called vm1 and the other dst. The parameter start_vm, which lacks a VM suffix and therefore applies to both VMs, indicates that if any of these VM objects does not exist or is not up, it will be started. However, start_vm_for_migration_dst = yes indicates that the VM dst should be started with the -incoming option so that it accepts an incoming migration.

The images parameter indicates that a single image object will be used by each VM, and they will both be called image1. This poses no problem because an image object only exists within the scope of its owner VM. However, both image objects actually point to the same image file, as indicated by image_name = fc9-32. If image_name appeared with some suffix (e.g. image_name_image1_vm1 or image_name_vm1) it would be attributed to a single VM, not both. image_format = qcow2 indicates that this is a qcow2 image file, so the actual filename becomes fc9-32.qcow2. image_boot = yes instructs the preprocessor to add ‘,boot=on’ to the -drive option in the QEMU command line. drive_format = ide adds ‘,if=ide’. No image file is created during the preprocessing phase of this test because both create_image and force_create_image are not specified.

The nics parameter indicates that each VM should be equipped with a single NIC object named nic1. nic_model = e1000 indicates that all NICs (due to the lack of a suffix) should be of the e1000 model. If one wished to specify a different NIC model for each VM, one could specify, for example, nic_model_vm1 = e1000 and nic_model_dst = rtl8139.

The parameters mem, ssh_port?, ssh_prompt?, username?, password?, cmd_reboot? and cmd_shutdown? apply to both VMs. See #VM preprocessor parameters for an explanation of these parameters.

The test itself

The parameters migration_src?, migration_dst? and migration_test_command? are used by the migration test. They instruct it to migrate from vm1 to dst and use the shell command help to test that the VM is alive following the migration.

The parameter main_vm happens to be specified because the format of the configuration file makes it easy to set a parameter for a large group of tests. However, in the case of a migration test, this parameter is not used and its presence is harmless.

Postprocessing

keep_ppm_files = no and keep_ppm_files_on_error = yes? indicate that normally the PPM files (images left in the test’s ‘debug’ directory) will not be kept; however, if the test fails, they will. This makes sense because the PPM files take quite a lot of hard drive space, and they are mostly useful to debug failures.

kill_vm = no indicates that normally both VMs should be left alone following the test.

kill_vm_on_error = yes? indicates that in the case of a failure, both VMs should be destroyed. This makes sense because if a migration test fails, the VMs involved may not be functional for the next test, thus causing it to fail.

If they are killed by the postprocessor, the preprocessor of the next test will automatically start them, assuming start_vm = yes? is specified for the next test. The parameter kill_vm_gracefully indicates that if a VM is to be killed, it should first be attempted via SSH/Telnet with a shutdown shell command, specified by the cmd_shutdown? parameter.