CartesianConfigParametersIntro.rst

========== 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 :doc:`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.