-
Notifications
You must be signed in to change notification settings - Fork 0
CartesianConfigParametersIntro
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.
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.
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 |
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 |
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.
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.
The following parameters should be specified for each image of each VM, as explained in addressing objects.
The following parameters should be specified for each NIC of each VM, as explained in 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 |
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:
These parameters should be specified for each VM as explained above in addressing objects.
These parameters should be specified for each image of each VM as explained above in addressing objects.
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.
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
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 **name**s of these tests. If any of these 4 tests runs and fails, the current test will be skipped.
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 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.
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.