diff --git a/.gitignore b/.gitignore deleted file mode 100644 index 99e83f361c..0000000000 --- a/.gitignore +++ /dev/null @@ -1,65 +0,0 @@ -*.o -*.lo -*.la -#*# -.*.rej -*.rej -.*~ -*~ -.#* -.DS_Store. -*.pyc -*.orig -*.bak -*.project -*.pydevproject -*.so -.settings -shared/data -shared/deps/cpuid_test_kernel/cpuid_dump_kernel.bin -qemu/env -logs -qemu/unittests -qemu/cfg/base.cfg -qemu/cfg/cdkeys.cfg -qemu/cfg/guest-hw.cfg -qemu/cfg/guest-os.cfg -qemu/cfg/machines.cfg -qemu/cfg/subtests.cfg -qemu/cfg/virtio-win.cfg -libvirt/cfg/base.cfg -libvirt/cfg/cdkeys.cfg -libvirt/cfg/guest-hw.cfg -libvirt/cfg/guest-os.cfg -libvirt/cfg/machines.cfg -libvirt/cfg/subtests.cfg -libvirt/cfg/virtio-win.cfg -libvirt/env -lvsb/cfg/subtests.cfg -lvsb/env -v2v/cfg/base.cfg -v2v/cfg/cdkeys.cfg -v2v/cfg/guest-hw.cfg -v2v/cfg/guest-os.cfg -v2v/cfg/machines.cfg -v2v/cfg/subtests.cfg -v2v/cfg/virtio-win.cfg -openvswitch/cfg/base.cfg -openvswitch/cfg/cdkeys.cfg -openvswitch/cfg/guest-hw.cfg -openvswitch/cfg/guest-os.cfg -openvswitch/cfg/machines.cfg -openvswitch/cfg/subtests.cfg -openvswitch/cfg/virtio-win.cfg -libguestfs/cfg/base.cfg -libguestfs/cfg/cdkeys.cfg -libguestfs/cfg/guest-hw.cfg -libguestfs/cfg/guest-os.cfg -libguestfs/cfg/machines.cfg -libguestfs/cfg/subtests.cfg -libguestfs/cfg/virtio-win.cfg -tools/github/*cache -tmp -.*.swp -.idea -RELEASE-VERSION diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/.nose.cfg b/.nose.cfg deleted file mode 100644 index c55477c843..0000000000 --- a/.nose.cfg +++ /dev/null @@ -1,8 +0,0 @@ -[nosetests] -verbosity=2 -cover-erase=1 -cover-package=virttest -with-xunit=1 -xunit-file=xunit.xml -with-xcoverage=1 -xcoverage-file=coverage.xml diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 3fa97f47f0..0000000000 --- a/.travis.yml +++ /dev/null @@ -1,32 +0,0 @@ -language: python -python: - - "2.7" - -branches: - only: - - master - -virtualenv: - system_site_packages: true - -before_script: - - echo "deb http://ppa.launchpad.net/lmr/autotest/ubuntu utopic main" | sudo tee -a /etc/apt/sources.list - - sudo apt-get update -q - - sudo apt-get -y --force-yes install autotest - -install: - - pip install sphinx tox simplejson MySQL-python pylint autopep8 - - pip install inspektor - - pip install -r requirements.txt - -script: - - ./tools/run_unittests_nose.py -c .nose.cfg -s virttest - - inspekt lint - - inspekt style - - ./tools/build_docs.py - -notifications: - irc: - channels: "irc.oftc.net#virt-test" - template: - - "%{repository}@%{branch}: %{message} (%{build_url})" diff --git a/CODING_STYLE b/CODING_STYLE deleted file mode 100644 index 81325786db..0000000000 --- a/CODING_STYLE +++ /dev/null @@ -1,210 +0,0 @@ -These rules are fairly standard and boring. People will bitch about something -in here, no doubt. Get over it. Much of this was stolen from the Linux Kernel -coding style, because most of it makes good sense. If you disagree, that's OK, -but please stick to the rules anyway ;-) - - -Language - -Please use Python where possible. It's not the ideal language for everything, -but it's pretty good, and consistency goes a long way in making the project -maintainable. (Obviously using C or whatever for writing tests is fine). - - -Base coding style - -When writing python code, unless otherwise stated, stick to the python style -guide (http://www.python.org/dev/peps/pep-0008/). We now ship a script, -run_pep8.py, that can verify non compliances to the PEP8, with some of -the few exceptions we allow people to do. If you see that the script -finds problems with your code, we expect you to fix them before you -send pull requests. In order for the script to be useful you'll have to -use the tools provided by your distro to install the programs 'pep8' and -'autopep8'. - - -Indentation & whitespace - -Format your code for an 80 character wide screen. - -Indentation is now 4 spaces, as opposed to hard tabs (which it used to be). -This is the Python standard. - -Don't leave trailing whitespace, or put whitespace on blank lines. - - -Variable names and UpPeR cAsE - -Use descriptive variable names where possible - it helps to make the code -self documenting. - -Don't use CamelCaps style in most places - use underscores to separate parts -of your variable_names please. - -Importing modules - -The order of imports should be as follows: - -Standard python modules -Non-standard python modules -Autotest modules - -Within one of these three sections, all module imports using the from -keyword should appear after regular imports. -Modules should be lumped together on the same line. -Wildcard imports (from x import *) should be avoided if possible. - -Classes should not be imported from modules, but modules may be imported - from packages, i.e.: -from shared import error -and not -from shared.error import AutoservError - -For example: -import os -import pickle -import random -import re -import select -import shutil -import signal -import StringIO -import subprocess -import sys -import time -import urllib -import urlparse -import MySQLdb -try: - import autotest.common -except ImportError: - import common # Magic autotest module and sys.path setup code. -import MySQLdb # After common so that we check our site-packages first. -from shared import error - -Testing None - -Use "is None" rather than "== None" and "is not None" rather than "!= None". -This way you'll never run into a case where someone's __eq__ or __ne__ -method do the wrong thing - - -Comments - -Generally, you want your comments to tell WHAT your code does, not HOW. -We can figure out how from the code itself (or if not, your code needs fixing). - -Try to describle the intent of a function and what it does in a triple-quoted -(multiline) string just after the def line. We've tried to do that in most -places, though undoubtedly we're not perfect. A high level overview is -incredibly helpful in understanding code. - - -Docstrings - -Docstrings are important to keep our code self documenting. While it's not -necessary to overdo documentation, we ask you to be sensible and document any -nontrivial function. When creating docstrings, please add a newline at the -beginning of your triple quoted string and another newline at the end of it. If -the docstring has multiple lines, please include a short summary line followed -by a blank line before continuing with the rest of the description. Please -capitalize and punctuate accordingly the sentences. If the description has -multiple lines, put two levels of indentation before proceeding with text. An -example docstring: - -def foo(param1, param2): - """ - Summary line. - - Long description of method foo. - - :param param1: A thing called param1 that is used for a bunch of stuff - that has methods bar() and baz() which raise SpamError if - something goes awry. - :type param1: :class:`Thing` - :param param2: The number of :class:`thingies ` that foo will handle - :type param2: integer - :return: a list of integers describing changes in a source tree - :rtype: list of integers - """ - -The docstring can hold any form of reStructuredText. For a brief intro, check: - - http://docutils.sourceforge.net/rst.html - -More specifically, Autotest docs are now based on the Sphinx documentation -framework: - - http://sphinx-doc.org - -So you can use not only use the basic reStructuredText tags, but also any other -tag that Sphinx makes available. When documenting functions and methods, you -probably want to use one of the tags exemplified here: - - http://sphinx-doc.org/domains.html#info-field-lists - -:param - Parameter description -:returns - Return value description -:raises - If the function can throw an exception, this tag documents the -possible exception types. - -The existing docstrings are being converted into reStructuredText, so don't -worry if you find docstrings that don't conform to the example given here. -When in doubt, please refer to the Sphinx documentation. - -Simple code - -Keep it simple; this is not the right place to show how smart you are. We -have plenty of system failures to deal with without having to spend ages -figuring out your code, thanks ;-) Readbility, readability, readability. -I really don't care if other things are more compact. - -"Debugging is twice as hard as writing the code in the first place. Therefore, -if you write the code as cleverly as possible, you are, by definition, not -smart enough to debug it." Brian Kernighan - - -Function length - -Please keep functions short, under 30 lines or so if possible. Even though -you are amazingly clever, and can cope with it, the rest of us are all stupid, -so be nice and help us out. To quote the Linux Kernel coding style: - -Functions should be short and sweet, and do just one thing. They should -fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, -as we all know), and do one thing and do that well. - - -Exceptions - -When raising exceptions, the preferred syntax for it is: - -raise FooException('Exception Message') - -Please don't raise string exceptions, as they're deprecated and will be removed -from future versions of python. If you're in doubt about what type of exception -you will raise, please look at http://docs.python.org/lib/module-exceptions.html -and client/shared/error.py, the former is a list of python built in -exceptions and the later is a list of autotest/autoserv internal exceptions. Of -course, if you really need to, you can extend the exception definitions on -client/shared/error.py. - - -Submitting patches - -Nowadays, the projects uses the github (http://github.com/ infrastructure, -and we ask contributors to send patches as github pull requests, rather than -to the mailing list. How to do that is covered on github's documentation: - -https://help.github.com/articles/using-pull-requests - - -Catching Exceptions - -Older python cannot support the full exception syntax. The accepted formats -for exception catching are: - - try...except... - try...finally... - try...except...else... - try...finally...else... diff --git a/MAINTAINERS b/MAINTAINERS deleted file mode 100644 index 3e86748d33..0000000000 --- a/MAINTAINERS +++ /dev/null @@ -1,56 +0,0 @@ -Virt-Test Maintainers -==================== - -The intention of this file is not to establish who owns what portions of the -code base, but to provide a set of names that developers can consult when they -have a question about a particular subset and also to provide a set of names -you can look for on github for any pull requests you might want to get approved. - -In general, if you have a question, you should send an email to the Virt Test -development mailing list and not any specific individual privately. - - -Pull request maintenance - QEMU subtests ----------------------------------------- - -M: Lucas Meneghel Rodrigues -M: Cleber Rosa -M: Jiri Zupka -M: Lukas Doktor -M: Yiqiao Pu -M: Feng Yang - - -Pull request maintenance - Libvirt subtests -------------------------------------------- - -M: Christopher Evich -M: Yu Mingfei -M: Yang Dongsheng -M: Li Yang - - - -Pull request maintenance - LVSB subtests -------------------------------------------- - -M: Christopher Evich - - -Pull request maintenance - Libguestfs -------------------------------------- - -M: Yu Mingfei - - -Pull request maintenance - v2v subtests ---------------------------------------- - -M: Alex Jia - - -Pull request maintenance - openvswitch subtests ------------------------------------------------- - -M: Jiri Zupka - diff --git a/README.rst b/README.rst deleted file mode 100644 index 71006b7da4..0000000000 --- a/README.rst +++ /dev/null @@ -1,196 +0,0 @@ -====================================== -Linux Virtualization Tests (virt-test) -====================================== - -Really quick start guide ------------------------- - -The most convenient distro to run virt-test on is Fedora, -since we have autotest libs officially packaged on this distro [1]. - -It is similarly easy to set things up on a RHEL box, but then -you need to enable the EPEL repos [2] to install the needed packages. - -The most recent addition to this list is Ubuntu/Debian. New repos were -set with a new autotest package. Learn how to add the proper repos and -install your packages on [3]. - - -Install dependencies --------------------- - -Install the p7zip file archiver so you can uncompress the JeOS [4] image. - -Red Hat based:: - -# yum install p7zip - -Debian based:: - -# apt-get install p7zip-full - -Install the autotest-framework package, to provide the needed autotest libs. - -Red Hat based:: - -# yum install autotest-framework - -Debian based (needs to enable repo, see [3]):: - -# apt-get install autotest - -Some tests might need some other dependencies, such as the migrate -using file descriptors, that requires a working toolchain and python-devel, -and generating VM videos, that requires python-gstreamer. - -For such cases, it is best that you refer to the more complete documentation: - -http://virt-test.readthedocs.org/en/latest/basic/InstallPrerequesitePackages.html - -http://virt-test.readthedocs.org/en/latest/basic/InstallPrerequesitePackagesDebian.html - - -Execute the bootstrap script ------------------------- - -Let's say you're interested in the qemu tests:: - -./run -t qemu --bootstrap - -The script can help you to setup a data dir, copy the sample config files -to actual config files, and download the JeOS image. - -Execute the runner script -------------------------- - -You can execute the main runner script, called run. The script offers you -some options, all explained in the script help. A really really simple execution -of the script for qemu tests is:: - -./run -t qemu - -This will execute a subset of the tests available. - -Note: If you execute the runner before the bootstrap, things will work, -but then you won't get prompted and the runner will download the JeOS -automatically. - -Writing your first test ------------------------ - -http://virt-test.readthedocs.org/en/latest/basic/WritingSimpleTests.html - -Is your tutorial to write your first test. Alternatively, you -can copy the simple template test we have under the samples -directory to the appropriate test directory, and start hacking -from there. Example: You want to create a qemu specific test -for the jelly functionality. You have to do:: - -$ cp samples/template.py qemu/tests/jelly.py - -And then edit the template file accordingly. - -[1] If you want to use it without the packaged rpm, you need to have a clone -of the autotest code (git://github.com/autotest/autotest.git) and set the -env variable AUTOTEST_PATH pointing to the path of the clone. We do have -plans to package the libs to more distributions. - -[2] http://fedoraproject.org/wiki/EPEL/FAQ#How_can_I_install_the_packages_from_the_EPEL_software_repository.3F - -[3] https://github.com/autotest/virt-test/wiki/InstallPrerequesitePackagesDebian - -[4] JeOS: Minimal guest OS image (x86_64) - - -Description ------------ - -virt-test is a Linux virtualization test suite, intended to be used in -conjunction with the autotest framework [1], although it can be also used -separately, on a virt developer's machine, to run tests quicker and smaller -in scope, as an auxiliary tool of the development process. - -This test suite aims to have test tools for a wide range of testing scenarios: - -- Guest OS install, for both Windows (WinXP - Win7) and Linux (RHEL, - Fedora, OpenSUSE) and any generic one, through a 'step engine' mechanism. -- Serial output for Linux guests -- Migration, networking, timedrift and other types of tests -- Monitor control for both human and QMP protocols -- Build and use qemu using various methods (source tarball, git repo, - rpm) -- Performance testing -- Call other kvm test projects, such as kvm-unit-tests - -We support x86\_64 hosts with hardware virtualization support (AMD and -Intel), and Intel 32 and 64 bit guest operating systems, and work is underway -to support PPC hosts. - -[1] http://autotest.github.com/ - Autotest is a project that aims to -provide tools and libraries to perform automated testing on the linux -platform. Autotest is a modular framework, and this suite can be used as -a submodule of the client module. If you do not want to use or know about -autotest, this is fine too, and we'll provide documentation and tools to -perform development style testing with it. - - -Basic Troubleshooting ---------------------- - -If you have problems with the basic usage described here, it's possible -that there's some local change in your working copy of virt-test. These -changes can come in (at least) two different categories: - -- Code changes, which you can check with the git tools (try "git diff" - and "git branch" first) -- Configuration changes that can you reset with "update_config.py" - -If you find that you have local changes in the code, please try to reset -your checked out copy to upstream's master by running:: - -$ git checkout master -$ git pull - -You can also update your tests (both qemu, libvirt and others) by doing:: - -$ ./run -t qemu --bootstrap --update-providers - -And then, reset you configuration. If you're going to run qemu tests, run:: - -$ ./run -t qemu --update-config - -If you're still having problems after these basic troubleshoot steps, -please contact us! - - -Documentation -------------- - -Virt Test comes with in tree documentation, that can be built with ``sphinx``. -A publicly available build of the latest master branch documentation and -releases can be seen on `read the docs `__: - -http://virt-test.readthedocs.org/en/latest/index.html - -If you want to build the documentation, here are the instructions: - -1) Make sure you have the package ``python-sphinx`` installed. For Fedora:: - - $ sudo yum install python-sphinx - -2) For Ubuntu/Debian:: - - $ sudo apt-get install python-sphinx - -3) Optionally, you can install the read the docs theme, that will make your - in-tree documentation to look just like in the online version:: - - $ sudo pip install sphinx_rtd_theme - -4) Build the docs:: - - $ make -C documentation html - -5) Once done, point your browser to:: - - $ [your-browser] docs/build/html/index.html diff --git a/avocado-vt/LICENSE b/avocado-vt/LICENSE deleted file mode 100644 index 88820ef5d5..0000000000 --- a/avocado-vt/LICENSE +++ /dev/null @@ -1,344 +0,0 @@ -Unless explicitly otherwise stated, all files in the avocado-vt repository -are covered by the GPLv2+ (i.e: v2, or any later version). - - - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. diff --git a/documentation/Makefile b/documentation/Makefile deleted file mode 100644 index 3f20ab7203..0000000000 --- a/documentation/Makefile +++ /dev/null @@ -1,153 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/VirtTest.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/VirtTest.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/VirtTest" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/VirtTest" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/documentation/build/.gitignore b/documentation/build/.gitignore deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/documentation/source/_static/.gitignore b/documentation/source/_static/.gitignore deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/documentation/source/_templates/.gitignore b/documentation/source/_templates/.gitignore deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/documentation/source/advanced/BuildingTestApplications.rst b/documentation/source/advanced/BuildingTestApplications.rst deleted file mode 100644 index 5f61e83667..0000000000 --- a/documentation/source/advanced/BuildingTestApplications.rst +++ /dev/null @@ -1,75 +0,0 @@ -Building test applications -========================== - -This is a description of how to build test applications from a test case. - -Dependencies ------------- - -If you write an application that is supposed to be run on the test-target, -place it in the directory `../deps//` relative to where your test case is -placed. The easiest way to obtain the full path to this directory is by calling -`data_dir.get_deps_dir("")`. Don't forget to add `from virttest import -data_dir` to your test case. - -Besides the source file, create a Makefile that will be used to build your test -application. The below example shows a Makefile for the application for the -timedrift test cases. The `remote_build` module requires that a Makefile is -included with all test applications. - -:: - - CFLAGS+=-Wall - LDLIBS+=-lrt - - .PHONY: clean - - all: clktest get_tsc - - clktest: clktest.o - - get_tsc: get_tsc.o - - clean: - rm -f clktest get_tsc - -remote_build ------------- - -To simplfy the building of applications on target, and to simplify avoiding the -building of applications on target when they are installed pre-built, use the -`remote_build` module. This module handles both the transfer of files, and -running `make` on target. - -A simple example: - -:: - - address = vm.get_address(0) - source_dir = data_dir.get_deps_dir("") - builder = remote_build.Builder(params, address, source_dir) - full_build_path = builder.build() - -In this case, we utilize the `.build()` method, which execute the neccessary -methods in `builder` to copy all files to target and run make (if needed). When -done, `.build()` will return the full path on target to the application that -was just built. Be sure to use this path when running your test application, as -the path is changed if the parameters of the build is changed. For example: - -:: - - session.cmd_status(%s --test" % os.path.join(full_build_path, "testapp")) - -The `remote_build.Builder` class can give you fine-grained control over your -build process as well. Another way to write the above `.build()` invocation -above is: - -:: - - builder = remote_build.Builder(params, address, source_dir) - if builder.sync_directories(): - builder.make() - full_build_path = builder.full_build_path - -This pattern can be useful if you e.g. would like to add an additonal command -to run before `builder.make()`, perhaps to install some extra dependencies. diff --git a/documentation/source/advanced/MultiHostMigration.rst b/documentation/source/advanced/MultiHostMigration.rst deleted file mode 100644 index 4aec161010..0000000000 --- a/documentation/source/advanced/MultiHostMigration.rst +++ /dev/null @@ -1,266 +0,0 @@ -========================== -Multi Host Migration Tests -========================== - -Running Multi Host Migration Tests -================================== - -virt-test is our test suite, but for simplicity purposes it can only run on -a single host. For multi host tests, you'll need the full autotest + virt-test -package, and the procedure is more complex. We'll try to keep this procedure -as objective as possible. - -Prerequesites -============= - -This guide assumes that: - -1) You have at least 2 virt capable machines that have shared storage setup - in [insert specific path]. Let's call them ``host1.foo.com`` and ``host2.foo.com``. -2) You can ssh into both of those machines without a password (which means - there is an SSH key setup with the account you're going to use to run - the tests) as root. -3) The machines should be able to communicate freely, so beware of the potential - firewall complications. On each of those machines you need a specific NFS mount setup: - -* /var/lib/virt_test/isos -* /var/lib/virt_test/steps_data -* /var/lib/virt_test/gpg - -They all need to be backed by an NFS share read only. Why read only? Because -it is safer, we exclude the chance to delete this important data by accident. -Besides the data above is only needed in a read only fashion. -fstab example:: - - myserver.foo.com:/virt-test/iso /var/lib/virt_test/isos nfs ro,nosuid,nodev,noatime,intr,hard,tcp 0 0 - myserver.foo.com:/virt-test/steps_data /var/lib/virt_test/steps_data nfs rw,nosuid,nodev,noatime,intr,hard,tcp 0 0 - myserver.foo.com:/virt-test/gpg /var/lib/virt_test/gpg nfs rw,nosuid,nodev,noatime,intr,hard,tcp 0 0 - -* /var/lib/virt_test/images -* /var/lib/virt_test/images_archive - -Those all need to be backed by an NFS share read write (or any other shared -storage you might have). This is necessary because both hosts need to see -the same coherent storage. fstab example:: - - myserver.foo.com:/virt-test/images_archive /var/lib/virt_test/images_archive nfs rw,nosuid,nodev,noatime,intr,hard,tcp 0 0 - myserver.foo.com:/virt-test/images /var/lib/virt_test/images nfs rw,nosuid,nodev,noatime,intr,hard,tcp 0 0 - -The images dir must be populated with the installed guests you want to run -your tests on. They must match the file names used by guest OS in virt-test. -For example, for RHEL 6.4, the image name virt-test uses is:: - - rhel64-64.qcow2 - -double check your files are there:: - - $ ls /var/lib/virt_test/images - $ rhel64-64.qcow2 - - -Setup step by step -================== - -First, clone the autotest repo recursively. It's a repo with lots of -submodules, so you'll see a lot of output:: - - $ git clone --recursive https://github.com/autotest/autotest.git - ... lots of output ... - -Then, edit the global_config.ini file, and change the key:: - - serve_packages_from_autoserv: True - -to:: - - serve_packages_from_autoserv: False - -Then you need to update virt-test's config files and sub tests (that live in -separate repositories that are not git submodules). You don't need to download -the JeOS file in this step, so simply answer 'n' to the quest - -Note: The bootstrap procedure described below will be performed automatically -upon running the autoserv command that triggers the test. The problem is that -then you will not be able to see the config files and modify filters prior -to actually running the test. Therefore this documentation will instruct you -to run the steps below manually. - -:: - - $ export AUTOTEST_PATH=.;client/tests/virt/run -t qemu --bootstrap --update-providers - 16:11:14 INFO | qemu test config helper - 16:11:14 INFO | - 16:11:14 INFO | 1 - Updating all test providers - 16:11:14 INFO | Fetching git [REP 'git://github.com/autotest/tp-qemu.git' BRANCH 'master'] -> /var/tmp/autotest/client/tests/virt/test-providers.d/downloads/io-github-autotest-qemu - 16:11:17 INFO | git commit ID is 6046958afa1ccab7f22bb1a1a73347d9c6ed3211 (no tag found) - 16:11:17 INFO | Fetching git [REP 'git://github.com/autotest/tp-libvirt.git' BRANCH 'master'] -> /var/tmp/autotest/client/tests/virt/test-providers.d/downloads/io-github-autotest-libvirt - 16:11:19 INFO | git commit ID is edc07c0c4346f9029930b062c573ff6f5433bc53 (no tag found) - 16:11:20 INFO | - 16:11:20 INFO | 2 - Checking the mandatory programs and headers - 16:11:20 INFO | /usr/bin/7za - 16:11:20 INFO | /usr/sbin/tcpdump - 16:11:20 INFO | /usr/bin/nc - 16:11:20 INFO | /sbin/ip - 16:11:20 INFO | /sbin/arping - 16:11:20 INFO | /usr/bin/gcc - 16:11:20 INFO | /usr/include/bits/unistd.h - 16:11:20 INFO | /usr/include/bits/socket.h - 16:11:20 INFO | /usr/include/bits/types.h - 16:11:20 INFO | /usr/include/python2.6/Python.h - 16:11:20 INFO | - 16:11:20 INFO | 3 - Checking the recommended programs - 16:11:20 INFO | Recommended command missing. You may want to install it if not building it from source. Aliases searched: ('qemu-kvm', 'kvm') - 16:11:20 INFO | Recommended command qemu-img missing. You may want to install it if not building from source. - 16:11:20 INFO | Recommended command qemu-io missing. You may want to install it if not building from source. - 16:11:20 INFO | - 16:11:20 INFO | 4 - Verifying directories - 16:11:20 INFO | - 16:11:20 INFO | 5 - Generating config set - 16:11:20 INFO | - 16:11:20 INFO | 6 - Verifying (and possibly downloading) guest image - 16:11:20 INFO | File JeOS 19 x86_64 not present. Do you want to download it? (y/n) n - 16:11:30 INFO | - 16:11:30 INFO | 7 - Checking for modules kvm, kvm-amd - 16:11:30 WARNI| Module kvm is not loaded. You might want to load it - 16:11:30 WARNI| Module kvm-amd is not loaded. You might want to load it - 16:11:30 INFO | - 16:11:30 INFO | 8 - If you wish, take a look at the online docs for more info - 16:11:30 INFO | - 16:11:30 INFO | https://github.com/autotest/virt-test/wiki/GetStarted - -Then you need to copy the multihost config file to the appropriate place:: - - cp client/tests/virt/test-providers.d/downloads/io-github-autotest-qemu/qemu/cfg/multi-host-tests.cfg client/tests/virt/backends/qemu/cfg/ - -Now, edit the file:: - - server/tests/multihost_migration/control.srv - -In there, you have to change the EXTRA_PARAMS to restrict the number of guests -you want to run the tests on. On this example, we're going to restrict our tests -to RHEL 6.4. The particular section of the control file should look like:: - - EXTRA_PARAMS = """ - only RHEL.6.4.x86_64 - """ - -It is important to stress that the guests must be installed for this to work -smoothly. Then the last step would be to run the tests. Using the same convention -for the machine hostnames, here's the command you should use:: - - server/autotest-remote -m host1.foo.com,host2.foo.com server/tests/multihost_migration/control.srv - -Now, you'll see a boatload of output from the autotest remote output. This is -normal, and you should be patient until all the tests are done. - - -.. _multihost_migration: - -Writing Multi Host Migration tests ----------------------------------- - -Scheme: -~~~~~~~ - -.. figure:: MultiHostMigration/multihost-migration.png - -:download:`Source file for the diagram above (LibreOffice file) ` - - -Example: -~~~~~~~~ - -:: - - class TestMultihostMigration(virt_utils.MultihostMigration): - def __init__(self, test, params, env): - super(testMultihostMigration, self).__init__(test, params, env) - - def migration_scenario(self): - srchost = self.params.get("hosts")[0] - dsthost = self.params.get("hosts")[1] - - def worker(mig_data): - vm = env.get_vm("vm1") - session = vm.wait_for_login(timeout=self.login_timeout) - session.sendline("nohup dd if=/dev/zero of=/dev/null &") - session.cmd("killall -0 dd") - - def check_worker(mig_data): - vm = env.get_vm("vm1") - session = vm.wait_for_login(timeout=self.login_timeout) - session.cmd("killall -9 dd") - - # Almost synchronized migration, waiting to end it. - # Work is started only on first VM. - - self.migrate_wait(["vm1", "vm2"], srchost, dsthost, - worker, check_worker) - - # Migration started in different threads. - # It allows to start multiple migrations simultaneously. - - # Starts one migration without synchronization with work. - mig1 = self.migrate(["vm1"], srchost, dsthost, - worker, check_worker) - - time.sleep(20) - - # Starts another test simultaneously. - mig2 = self.migrate(["vm2"], srchost, dsthost) - # Wait for mig2 finish. - mig2.join() - mig1.join() - - mig = TestMultihostMigration(test, params, env) - # Start test. - mig.run() - -When you call: - -:: - - mig = TestMultihostMigration(test, params, env): - -What happens is - -1. VM's disks will be prepared. -2. The synchronization server will be started. -3. All hosts will be synchronized after VM create disks. - -When you call the method: - -:: - - migrate(): - -What happens in a diagram is: - -+------------------------------------------+-----------------------------------+ -| source | destination | -+==========================================+===================================+ -| It prepare VM if machine is not started. | -+------------------------------------------+-----------------------------------+ -| Start work on VM. | | -+------------------------------------------+-----------------------------------+ -| ``mig.migrate_vms_src()`` | ``mig.migrate_vms_dest()`` | -+------------------------------------------+-----------------------------------+ -| | Check work on VM after migration. | -+------------------------------------------+-----------------------------------+ -| Wait for finish migration on all hosts. | -+------------------------------------------+-----------------------------------+ - -It's important to note that the migrations are made using the ``tcp`` protocol, -since the others don't support multi host migration. - -:: - - def migrate_vms_src(self, mig_data): - vm = mig_data.vms[0] - logging.info("Start migrating now...") - vm.migrate(mig_data.dst, mig_data.vm_ports) - - -This example migrates only the first machine defined in migration. Better example -is in ``virt_utils.MultihostMigration.migrate_vms_src``. This function migrates -all machines defined for migration. diff --git a/documentation/source/advanced/MultiHostMigration/multihost-migration.odg b/documentation/source/advanced/MultiHostMigration/multihost-migration.odg deleted file mode 100644 index 20239a7330..0000000000 Binary files a/documentation/source/advanced/MultiHostMigration/multihost-migration.odg and /dev/null differ diff --git a/documentation/source/advanced/MultiHostMigration/multihost-migration.png b/documentation/source/advanced/MultiHostMigration/multihost-migration.png deleted file mode 100644 index a758973902..0000000000 Binary files a/documentation/source/advanced/MultiHostMigration/multihost-migration.png and /dev/null differ diff --git a/documentation/source/advanced/Networking.rst b/documentation/source/advanced/Networking.rst deleted file mode 100644 index d90732ee13..0000000000 --- a/documentation/source/advanced/Networking.rst +++ /dev/null @@ -1,112 +0,0 @@ -========== -Networking -========== - -Here we have notes about networking setup in virt-test. - -Configuration -------------- - -How to configure to allow all the traffic to be forwarded across the virbr0 bridge: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - echo "-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT" > /etc/sysconfig/iptables-forward-bridged - lokkit --custom-rules=ipv4:filter:/etc/sysconfig/iptables-forward-bridged - service libvirtd reload - - -How to configure Static IP address in virt-test -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sometimes, we need to test with guest(s) which have static ip address(es). - -- eg. No real/emulated DHCP server in test environment. -- eg. Test with old image we don't want to change the net config. -- eg. Test when DHCP exists problem. - -Create a bridge (for example, 'vbr') in host, configure its ip to 192.168.100.1, guest -can access host by it. And assign nic(s)' ip in tests.cfg, and execute test as usual. - -tests.cfg: - -:: - - ip_nic1 = 192.168.100.119 - nic_mac_nic1 = 11:22:33:44:55:67 - bridge = vbr - -TestCases ---------- - -Ntttcp -~~~~~~ - -The Nttcp test suite is a network performance test for windows, developed by -Microsoft. It is *not* a freely redistributable binary, so you must download -it from the website, here's the direct link for download (keep in mind it might -change): - -http://download.microsoft.com/download/f/1/e/f1e1ac7f-e632-48ea-83ac-56b016318735/NT%20Testing%20TCP%20Tool.msi - -The knowledge base article associated with it is: - -http://msdn.microsoft.com/en-us/windows/hardware/gg463264 - -You need to add the package to winutils.iso, the iso with utilities used to -test windows. First, download the iso. :doc:`The get started documentation <../basic/GetStarted>` -can help you out with downloading if you like it, but the direct download -link is here: - -http://lmr.fedorapeople.org/winutils/winutils.iso - -You need to put all its contents on a folder and create a new iso. Let's say you -want to download the iso to ``/home/kermit/Downloads/winutils.iso``. -You can create the directory, go to it: - -:: - - mkdir -p /home/kermit/Downloads - cd /home/kermit/Downloads - -Download the iso, create 2 directories, 1 for the mount, another for the -contents: - -:: - - wget http://people.redhat.com/mrodrigu/kvm/winutils.iso - mkdir original - sudo mount -o loop winutils.iso original - mkdir winutils - -Copy all contents from the original cd to the new structure: - -:: - - cp -r original/* winutils/ - -Create the destination nttcp directory on that new structure: - -:: - - mkdir -p winutils/NTttcp - -Download the installer and copy autoit script to the new structure, unmount the orginal mount: - -:: - - cd winutils/NTttcp - wget http://download.microsoft.com/download/f/1/e/f1e1ac7f-e632-48ea-83ac-56b016318735/NT%20Testing%20TCP%20Tool.msi -O "winutils/NTttcp/NT Testing TCP Tool.msi" - cp /usr/local/autotest/client/virt/scripts/ntttcp.au3 ./ - sudo umount original - -Backup the old winutils.iso and create a new winutils.iso using mkisofs: - -:: - - sudo mv winutils.iso winutils.iso.bak - mkisofs -o winutils.iso -max-iso9660-filenames -relaxed-filenames -D --input-charset iso8859-1 winutils - -And that is it. Don't forget to keep winutils in an appropriate location that -can be seen by virt-test. diff --git a/documentation/source/advanced/PerformanceTesting.rst b/documentation/source/advanced/PerformanceTesting.rst deleted file mode 100644 index deecf96c77..0000000000 --- a/documentation/source/advanced/PerformanceTesting.rst +++ /dev/null @@ -1,182 +0,0 @@ -=================== -Performance Testing -=================== - -Performance subtests --------------------- - -network -~~~~~~~ - -- `netperf (linux and windows) `_ -- `ntttcp (windows) `_ - -block -~~~~~ - -- `iozone (linux) `_ -- `iozone (windows) `_ (iozone has its own result analysis module) -- iometer (windows) (not push upstream) -- `ffsb (linux) `_ -- `qemu_iotests (host) `_ -- `fio (linux) `_ - -Environment setup ------------------ - - Autotest already supports prepare environment for performance testing, guest/host need to be reboot for some configuration. - `setup script `_ - -Autotest supports to numa pining. Assign "numanode=-1" in tests.cfg, then vcpu threads/vhost_net threads/VM memory will be pined to last numa node. If you want to pin other processes to numa node, you can use numctl and taskset. - -:: - - memory: numactl -m $n $cmdline - cpu: taskset $node_mask $thread_id - -The following content is manual guide. - -:: - - 1.First level pinning would be to use numa pinning when starting the guest. - e.g numactl -c 1 -m 1 qemu-kvm -smp 2 -m 4G <> (pinning guest memory and cpus to numa-node 1) - - 2.For a single instance test, it would suggest trying a one to one mapping of vcpu to pyhsical core. - e.g - get guest vcpu threads id - #taskset -p 40 $vcpus1 (pinning vcpu1 thread to pyshical cpu #6 ) - #taskset -p 80 $vcpus2 (pinning vcpu2 thread to physical cpu #7 ) - - 3.To pin vhost on host. get vhost PID and then use taskset to pin it on the same soket. - e.g - taskset -p 20 $vhost (pinning vcpu2 thread to physical cpu #5 ) - - 4.In guest,pin the IRQ to one core and the netperf to another. - 1) make sure irqbalance is off - `service irqbalance stop` - 2) find the interrupts - `cat /proc/interrupts` - 3) find the affinity mask for the interrupt(s) - `cat /proc/irq//smp_affinity` - 4) change the value to match the proper core.make sure the vlaue is cpu mask. - e.g pin the IRQ to first core. - echo 01>/proc/irq/$virti0-input/smp_affinity - echo 01>/proc/irq/$virti0-output/smp_affinity - 5)pin the netserver to another core. - e.g - taskset -p 02 netserver - - 5.For host to guest scenario. to get maximum performance. make sure to run netperf on different cores on the same numa node as the guest. - e.g - numactl -m 1 netperf -T 4 (pinning netperf to physical cpu #4) - -Execute testing ---------------- - -- Submit jobs in Autotest server, only execute netperf.guset_exhost for three times. - -``tests.cfg``: - -:: - - only netperf.guest_exhost - variants: - - repeat1: - - repeat2: - - repeat3: - # vbr0 has a static ip: 192.168.100.16 - bridge=vbr0 - # virbr0 is created by libvirtd, guest nic2 get ip by dhcp - bridge_nic2 = virbr0 - # guest nic1 static ip - ip_nic1 = 192.168.100.21 - # external host static ip: - client = 192.168.100.15 - - -Result files: - -:: - - # cd /usr/local/autotest/results/8-debug_user/192.168.122.1/ - # find .|grep RHS - kvm.repeat1.r61.virtio_blk.smp2.virtio_net.RHEL.6.1.x86_64.netperf.exhost_guest/results/netperf-result.RHS - kvm.repeat2.r61.virtio_blk.smp2.virtio_net.RHEL.6.1.x86_64.netperf.exhost_guest/results/netperf-result.RHS - kvm.repeat3.r61.virtio_blk.smp2.virtio_net.RHEL.6.1.x86_64.netperf.exhost_guest/results/netperf-result.RHS - -- Submit same job in another env (different packages) with same configuration - -Result files: - -:: - - # cd /usr/local/autotest/results/9-debug_user/192.168.122.1/ - # find .|grep RHS - kvm.repeat1.r61.virtio_blk.smp2.virtio_net.RHEL.6.1.x86_64.netperf.exhost_guest/results/netperf-result.RHS - kvm.repeat2.r61.virtio_blk.smp2.virtio_net.RHEL.6.1.x86_64.netperf.exhost_guest/results/netperf-result.RHS - kvm.repeat3.r61.virtio_blk.smp2.virtio_net.RHEL.6.1.x86_64.netperf.exhost_guest/results/netperf-result.RHS - -Analysis result ---------------- - -- Config file: perf.conf - -:: - - [ntttcp] - result_file_pattern = .*.RHS - ignore_col = 1 - avg_update = - - [netperf] - result_file_pattern = .*.RHS - ignore_col = 2 - avg_update = 4,2,3|14,5,12|15,6,13 - - [iozone] - result_file_pattern = - -- Execute regression.py to compare two results: - -:: - - login autotest server - # cd /usr/local/autotest/client/tools - # python regression.py netperf /usr/local/autotest/results/8-debug_user/192.168.122.1/ /usr/local/autotest/results/9-debug_user/192.168.122.1/ - -- T-test: - -scipy: http://www.scipy.org/ -t-test: http://en.wikipedia.org/wiki/Student's_t-test -Two python modules (scipy and numpy) are needed. -Script to install numpy/scipy on rhel6 automatically: -https://github.com/kongove/misc/blob/master/scripts/install-numpy-scipy.sh -Unpaired T-test is used to compare two samples, user can check p-value to know if regression bug exists. If the difference of two samples is considered to be not statistically significant(p <= 0.05), it will add a '+' or '-' before p-value. ('+': avg_sample1 < avg_sample2, '-': avg_sample1 > avg_sample2) -"- only over 95% confidence results will be added "+/-" in "Significance" part. -"+" for cpu-usage means regression, "+" for throughput means improvement." - - -Regression results - - -`netperf.exhost_guest.html `_ -`fio.html `_ -- Every Avg line represents the average value based on *$n* repetitions of the same test, and the following SD line represents the Standard Deviation between the *$n* repetitions. -- The Standard deviation is displayed as a percentage of the average. -- The significance of the differences between the two averages is calculated using unpaired T-test that takes into account the SD of the averages. -- The paired t-test is computed for the averages of same category. -- only over 95% confidence results will be added "+/-" in "Significance" part. "+" for cpu-usage means regression, "+" for throughput means improvement. - - -Highlight HTML result -o green/red --> good/bad -o Significance is larger than 0.95 --> green -dark green/red --> important (eg: cpu) -light green/red --> other -o test time -o version (only when diff) -o other: repeat time, title -o user light green/red to highlight small (< %5) DIFF -o highlight Significance with same color in one raw -o add doc link to result file, and describe color in doc - - -`netperf.avg.html `_ -- Raw data that the averages are based on. diff --git a/documentation/source/advanced/Profiling.rst b/documentation/source/advanced/Profiling.rst deleted file mode 100644 index 0b4d2225db..0000000000 --- a/documentation/source/advanced/Profiling.rst +++ /dev/null @@ -1,83 +0,0 @@ -========= -Profiling -========= - -What is profiling ------------------ - -Profiling, by its definition (see `this wikipedia -article `_ -for a non formal introduction), is to run an analysis tool to inspect -the behavior of a certain property of the system (be it memory, CPU -consumption or any other). - -How autotest can help with profiling? -------------------------------------- - -Autotest provides support for running profilers during the execution of -tests, so we know more about a given system resource. For the ``kvm`` -test, our first idea of profiling usage was to run the kvm_stat -program, that usually ships with kvm, to provide data useful for -debugging. kvm_stat provides the number of relevant kvm events every -time it is called, so by the end of a virt-test test we end up with a -long list of information like this one: - -:: - - kvm_ack_i kvm_age_p kvm_apic kvm_apic_ kvm_apic_ kvm_async kvm_async kvm_async kvm_async kvm_cpuid kvm_cr kvm_emula kvm_entry kvm_exit kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_exit( kvm_fpu kvm_hv_hy kvm_hyper kvm_inj_e kvm_inj_v kvm_invlp kvm_ioapi kvm_mmio kvm_msi_s kvm_msr kvm_neste kvm_neste kvm_neste kvm_neste kvm_neste kvm_page_ kvm_pic_s kvm_pio kvm_set_i kvm_skini kvm_try_a kvm_users - 1 54 11 5 0 0 0 0 0 0 3 15 28 28 11 0 3 0 0 0 1 2 5 0 0 5 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 4 0 0 0 5 0 2 11 0 0 0 0 0 0 0 0 2 5 2 0 0 5 - -How to control the execution of profilers ? -------------------------------------------- - -Profiling in virt-test is controlled through configuration files. You -can set the profilers that are going to run by setting the variable -``profilers``. On ``tests_base.cfg.sample``, the section of the file -that sets the profilers that run by default looks like this: - -:: - - # Profilers. You can add more autotest profilers (see list on client/profilers) - # to the line below. You can also choose to remove all profilers so no profiling - # will be done at all. - profilers = kvm_stat - -How to add a profiler? ----------------------- - -So, say you want to run the perf profiler in addition to kvm_stat. You -can just edit that place and put 'perf' right next to it: - -:: - - # Profilers. You can add more autotest profilers (see list on client/profilers) - # to the line below. You can also choose to remove all profilers so no profiling - # will be done at all. - profilers = kvm_stat perf - -How to remove all profilers (including kvm_stat)? --------------------------------------------------- - -If you want no profiling at all for your tests, profilers can be changed -to be an empty string: - -:: - - # Profilers. You can add more autotest profilers (see list on client/profilers) - # to the line below. You can also choose to remove all profilers so no profiling - # will be done at all. - profilers = - -Of course, the config system makes it easy to override the value of -*any* param for your test variable, so you can have fine grained -control of things. Say you don't want to run profilers on your new -'crazy_test' variant, which you have developed. Easy: - -:: - - - crazy_test: - type = crazy_test - profilers = - -So this will turn of profilers just for this particular test of yours. - diff --git a/documentation/source/advanced/RunTestsExistingGuest.rst b/documentation/source/advanced/RunTestsExistingGuest.rst deleted file mode 100644 index 65164a08c2..0000000000 --- a/documentation/source/advanced/RunTestsExistingGuest.rst +++ /dev/null @@ -1,352 +0,0 @@ -======================================== -Running tests on an existing guest image -======================================== - -virt-test knows how to install guests, and that's all fine, but most -of the time, users already have a guest image they are working on, and -just want to tell virt-test to use it. Also, virt-test is a large -piece of infrastructure, and it's not really obvious how all the pieces -fit together, so some help is required to dispose the available pieces -conveniently, so users can accomplish their own testing goals. So, let's -get started. - -A bit of context on how autotest works --------------------------------------- - -The default upstream configuration file instructs autotest to perform -the following tasks: - -#. Install a Linux guest, on this case, Fedora 15, due to the fact it is - publicly available, so *everybody* can try it out. The hardware - configuration for the VM: - - - one qcow2 image on an ide bus - - one network card, model rtl8139 - - two cpus - - no pci hotplug devices will be attached to this vm - - Also, the VM is not going to use hugepage memory explicitly - -#. Run a boot test. -#. Run a shutdown test. - -:: - - # Runs qemu-kvm, f15 64 bit guest OS, install, boot, shutdown - - @qemu_kvm_f15_quick: - # We want qemu-kvm for this run - qemu_binary = /usr/bin/qemu-kvm - qemu_img_binary = /usr/bin/qemu-img - only qcow2 - only rtl8139 - only ide - only smp2 - only no_pci_assignable - only smallpages - only Fedora.15.64 - only unattended_install.cdrom, boot, shutdown - -This is defined in such a way that the kvm test config system will -generate only 3 tests. Let's see at the tests generated. On the kvm test -dir ``$AUTOTEST_ROOT/client/tests/kvm``, you can call the configuration -parser: - -:: - - [lmr@freedom kvm]$ ../../common_lib/cartesian_config.py tests.cfg - dict 1: smp2.Fedora.15.64.unattended_install.cdrom - dict 2: smp2.Fedora.15.64.boot - dict 3: smp2.Fedora.15.64.shutdown - -You can see on top of the file tests.cfg some *includes* that point us -from where all the test information comes from: - -:: - - # Copy this file to tests.cfg and edit it. - # - # This file contains the test set definitions. Define your test sets here. - include tests_base.cfg - include cdkeys.cfg - include virtio-win.cfg - -tests_base.cfg is a pretty large file, that contains a lot of -*variants*, that are blocks defining tests, vm hardware and pre/post -processing directives that control autotest infrastructure behavior. You -can check out the definition of each of the variants restricting the -test sets (qcow2, rtl8139, smp2, no_pci_assignable, smallpages, Fedora -15.64, unattended_install.cdrom, boot, shutdown) on tests_base.cfg. - -About guest install -------------------- - -It is no mystery that for a good deal of the virtualization tests we are -going to execute, a guest with an *operating system* on its disk image -is needed. To get this OS there, we have some methods defined: - -#. Install the VM with the OS CDROM through an engine that interacts - with the VM using VNC, simulating a human being, called *step - engine*. This engine works surprisingly well, frequently yielding - successful installations. However, each *step* is a point of failure - of the whole process, so we moved towards handing the dirty install - control to the guest OS itself, as many of them have this capacity. -#. Install the VM using the automated install mechanisms provided by the - guest OS itself. In windows, we have a mechanism called *answer - files*, for Fedora and RHEL we have *kickstarts*, and for OpenSUSE we - have *autoyast*. Of course, other OS, such as debian, also have their - own mechanism, however they are not currently implemented in autotest - (hint, hint). - -And then an even simpler alternative: - -#. Just copy a known good guest OS image, that was already installed, - and use it. This tends to be faster and less error prone, since the - install *is already done*, so we don't need to work on failures on - this step. The inevitable question that arises: - -- *Q. Hey, why don't you just go with that on the first place?* -- *A. Because installing a guest exercises several aspects of the VM, - such as disk, network, hardware probing, so on and so forth, so it's - a good functional test by itself. Also, installing manually a guest - may work well for a single developer working on his/her patches, but - certainly does not scale if you need fully automated test done on a - regular basis, as there is the need of someone going there and making - the install, which seriously, is a waste of human resources. KVM - autotest is also a tool for doing such a massively automated test on - a regular basis.* - -Also, this method assumes the least possible for the person running the -tests, as they won't need to have preinstalled guests, and because we -*always get* the same vm, with the same capabilities and same -configuration. Now that we made this point clear, let's explain how to -use your preinstalled guest. - -Needed setup for a typical linux guest --------------------------------------- - -virt-test relies heavily on *cartesian config files*. Those files use -a flexible file format, defined on :doc:`the file format documentation <../advanced/cartesian/CartesianConfigParametersIntro>` -If you are curious about the -defaults assumed for Linux or Windows guests, you can always check the -file base.cfg.sample, which contains all our guest definitions -(look at the Linux or Windows variant). Without diving too much into it, -it's sufficient to say that you need a guest to have a root password of -123456 and an enabled ssh daemon which will allow you to log in as root. -The password can be also configured through the config files. - -Before you start ----------------- - -#. Make sure you have the appropriate packages installed. You can read - :doc:`the install prerequesite packages (client section) <../basic/InstallPrerequesitePackages>` for more - information. For this how to our focus is not to build kvm from git - repos, so we are assuming you are going to use the default qemu - installed in the system. However, if you are interested in doing so, - you might want to recap our docs on :doc:`building qemu-kvm and running unittests <../extra/RunQemuUnittests>`. - -Step by step procedure ----------------------- - -#. Git clone autotest to a convenient location, say $HOME/Code/autotest. - See :doc:`the download source documentation <../contributing/DownloadSource>`. - Please do use git and clone the repo to the location mentioned. -#. Execute the ``./run -t qemu --bootstrap`` command (see `the get started documentation `. Since we are going to - boot our own guests, you can safely skip each and every iso download - possible. -#. Edit the file ``tests.cfg``. You can see we have a session overriding - Custom Guest definitions present on ``tests_base.cfg``. If you want to - use a raw block device (see - :doc:`image_raw_device <../advanced/cartesian/CartesianConfigReference-KVM-image_raw_device>`), - you can uncomment the lines mentioned on the comments. When - ``image_raw_device = yes``, virt-test will not append a '.qcow2' - extension to the image name. **Important:** If you opt for a raw - device, you must comment out the line that appends a base path to - image names (one that looks like - ``image_name(_.*)? ?<= /tmp/kvm_autotest_root/images/``) - - :: - - CustomGuestLinux: - # Here you can override the default login credentials for your custom guest - username = root - password = 123456 - image_name = custom_image_linux - image_size = 10G - # If you want to use a block device as the vm disk, uncomment the 2 lines - # below, pointing the image name for the device you want - #image_name = /dev/mapper/vg_linux_guest - #image_raw_device = yes - -#. Some lines below, you will also find this config snippet. This is for - the case where you want to specify new base directories for kvm - autotest to look images, cdroms and floppies. - - :: - - # Modify/comment the following lines if you wish to modify the paths of the - # image files, ISO files or qemu binaries. - # - # As for the defaults: - # * qemu and qemu-img are expected to be found under /usr/bin/qemu-kvm and - # /usr/bin/qemu-img respectively. - # * All image files are expected under /tmp/kvm_autotest_root/images/ - # * All install iso files are expected under /tmp/kvm_autotest_root/isos/ - # * The parameters cdrom_unattended, floppy, kernel and initrd are generated - # by virt-test, so remember to put them under a writable location - # (for example, the cdrom share can be read only) - image_name(_.*)? ?<= /tmp/kvm_autotest_root/images/ - cdrom(_.*)? ?<= /tmp/kvm_autotest_root/ - floppy ?<= /tmp/kvm_autotest_root/ - -#. Change the fields ``image_name``, ``image_size`` to your liking. Now, the - **example** test set that uses custom guest configuration can be - found some lines below: - - :: - - # Runs your own guest image (qcow2, can be adjusted), all migration tests - # (on a core2 duo laptop with HD and 4GB RAM, F15 host took 3 hours to run) - # Be warned, disk stress + migration can corrupt your image, so make sure - # you have proper backups - - @qemu_kvm_custom_migrate: - # We want qemu-kvm for this run - qemu_binary = /usr/bin/qemu-kvm - qemu_img_binary = /usr/bin/qemu-img - only qcow2 - only rtl8139 - only ide - only smp2 - only no_pci_assignable - only smallpages - only CustomGuestLinux - only migrate - -#. Since we want to execute this custom migrate test set, we need to - look at the last couple of lines of the configuration file: - - :: - - # Choose your test list from the testsets defined - only qemu_kvm_f15_quick - -#. This line needs to become - - :: - - # Choose your test list from the testsets defined - only qemu_kvm_custom_migrate - -#. Now, if you haven't changed any of the settings of the previous - blocks, now our configuration system will run tests with the - following expectations: - -- qemu-kvm and qemu are under ``/usr/bin/qemu-kvm`` and - ``/usr/bin/qemu-kvm``, respectively. *Please remember RHEL installs - qemu-kvm under ``/usr/libexec``*. -- Our guest image is under - ``/tmp/kvm_autotest_root/images/custom_image_linux.qcow2``, since the - test set specifies ``only qcow2``. -- All current combinations for our migrate tests variant will be - executed with your custom image. It is never enough to remember that - some of the tests can corrupt your qcow2 (or raw) image. - -#. If you want to verify all tests that the config system will generate, - you can run the parser to tell you that. This set took 3 hours to run - on my development laptop setup. - - :: - - [lmr@freedom kvm]$ ../../common_lib/cartesian_config.py tests.cfg - dict 1: smp2.CustomGuestLinux.migrate.tcp - dict 2: smp2.CustomGuestLinux.migrate.unix - dict 3: smp2.CustomGuestLinux.migrate.exec - dict 4: smp2.CustomGuestLinux.migrate.mig_cancel - dict 5: smp2.CustomGuestLinux.migrate.with_set_speed.tcp - dict 6: smp2.CustomGuestLinux.migrate.with_set_speed.unix - dict 7: smp2.CustomGuestLinux.migrate.with_set_speed.exec - dict 8: smp2.CustomGuestLinux.migrate.with_set_speed.mig_cancel - dict 9: smp2.CustomGuestLinux.migrate.with_reboot.tcp - dict 10: smp2.CustomGuestLinux.migrate.with_reboot.unix - dict 11: smp2.CustomGuestLinux.migrate.with_reboot.exec - dict 12: smp2.CustomGuestLinux.migrate.with_reboot.mig_cancel - dict 13: smp2.CustomGuestLinux.migrate.with_file_transfer.tcp - dict 14: smp2.CustomGuestLinux.migrate.with_file_transfer.unix - dict 15: smp2.CustomGuestLinux.migrate.with_file_transfer.exec - dict 16: smp2.CustomGuestLinux.migrate.with_file_transfer.mig_cancel - dict 17: smp2.CustomGuestLinux.migrate.with_autotest.dbench.tcp - dict 18: smp2.CustomGuestLinux.migrate.with_autotest.dbench.unix - dict 19: smp2.CustomGuestLinux.migrate.with_autotest.dbench.exec - dict 20: smp2.CustomGuestLinux.migrate.with_autotest.dbench.mig_cancel - dict 21: smp2.CustomGuestLinux.migrate.with_autotest.stress.tcp - dict 22: smp2.CustomGuestLinux.migrate.with_autotest.stress.unix - dict 23: smp2.CustomGuestLinux.migrate.with_autotest.stress.exec - dict 24: smp2.CustomGuestLinux.migrate.with_autotest.stress.mig_cancel - dict 25: smp2.CustomGuestLinux.migrate.with_autotest.monotonic_time.tcp - dict 26: smp2.CustomGuestLinux.migrate.with_autotest.monotonic_time.unix - dict 27: smp2.CustomGuestLinux.migrate.with_autotest.monotonic_time.exec - dict 28: smp2.CustomGuestLinux.migrate.with_autotest.monotonic_time.mig_cancel - -#. If you want to make sure virt-test is assigning images to the - right places, you can tell the config system to print the params - contents for each test. - - :: - - [lmr@freedom kvm]$ ../../common_lib/cartesian_config.py -c tests.cfg | less - ... lots of output ... - -#. In any of the dicts you should be able to see an ``image_name`` key - that has something like the below. virt-test will only append - 'image_format' to this path and then use it, so in the case - mentioned, - '/tmp/kvm_autotest_root/images/custom_image_linux.qcow2' - - :: - - image_name = /tmp/kvm_autotest_root/images/custom_image_linux - -#. After you have verified things, you can run autotest using the - command line ``get_started.py`` has informed you: - - :: - - $AUTOTEST_ROOT/client/bin/autotest $AUTOTEST_ROOT/client/tests/kvm/control - -#. Profit! - -Common questions ----------------- - -- Q: How do I restrict the test set so it takes less time to run? -- A: You can look at the output of the cartesian config parser and - check out the test combinations. If you look at the output above, and - say you want to run only migration + file transfer tests, your test - set would look like the below snippet. Make sure you validate your - changes calling the parser again. - - :: - - # Runs your own guest image (qcow2, can be adjusted), all migration tests - # (on a core2 duo laptop with HD and 4GB RAM, F15 host took 3 hours to run) - # Be warned, disk stress + migration can corrupt your image, so make sure - # you have proper backups - - @qemu_kvm_custom_migrate: - # We want qemu-kvm for this run - qemu_binary = /usr/bin/qemu-kvm - qemu_img_binary = /usr/bin/qemu-img - only qcow2 - only rtl8139 - only ide - only smp2 - only no_pci_assignable - only smallpages - only CustomGuestLinux - only migrate.with_file_transfer - - :: - - [lmr@freedom kvm]$ ../../common_lib/cartesian_config.py tests.cfg - dict 1: smp2.CustomGuestLinux.migrate.with_file_transfer.tcp - dict 2: smp2.CustomGuestLinux.migrate.with_file_transfer.unix - dict 3: smp2.CustomGuestLinux.migrate.with_file_transfer.exec - dict 4: smp2.CustomGuestLinux.migrate.with_file_transfer.mig_cancel - diff --git a/documentation/source/advanced/VirtTestDocumentation.rst b/documentation/source/advanced/VirtTestDocumentation.rst deleted file mode 100644 index 85729c6ab5..0000000000 --- a/documentation/source/advanced/VirtTestDocumentation.rst +++ /dev/null @@ -1,1912 +0,0 @@ -.. contents:: - -================ -Virt Test Primer -================ - -Autotest -======== -.. _autotest_introduction: - -Introduction ----------------------- - -It is critical for any project to maintain a high level of software -quality, and consistent interfaces to other software that it uses or -uses it. Autotest is a framework for fully automated testing, that is -designed primarily to test the Linux kernel, though is useful for many -other functions too. It includes a client component for executing tests -and gathering results, and a completely optional server component for -managing a grid of client systems. - - -.. _server: - -Server ------- - -Job data, client information, and results are stored in a MySQL -database, either locally or on a remote system. The Autotest server -manages each client and it’s test jobs with individual “autoserv” -processes (one per client). A dispatcher process “monitor\_db”, starts -the autoserv processes to service requests based on database content. -Finally, both command-line and a web-based graphical interface is -available. - - -.. _client: - -Client ------- - -The Autotest client can run either standalone or within a server -harness. It is not tightly coupled with the Autotest server, though they -are designed to work together. Primary design drivers include handling -errors implicitly, producing consistent results, ease of installation, -and maintenance simplicity. - - -.. _virtualization_test: - -Virtualization Test ----------------------- - -The virtualization tests are sub-modules of the Autotest client that utilize -it's modular framework, The entire suite of top-level autotest tests are also -available within virtualized guests. In addition, many specific sub-tests are -provided within the virtualization sub-test framework. Some of the sub-tests -are shared across virtualization technologies, while others are specific. - -Control over the virtualization sub-tests is provided by the test-runner (script) -and/or a collection of configuration files. The configuration file format is -highly specialized (see section cartesian_configuration_). However, by using -the test-runner, little (if any) knowledge of the configuration file format is -required. Utilizing the test-runner is the preferred method for individuals and -developers to execute stand-alone virtualization testing. - - -.. _virtualization_tests: - -Virtualization Tests -======================= - -.. _virtualization_tests_introduction: - -Introduction -====================== - -The virt-test suite helps exercise virtualization features -with help from qemu, libvirt, and other related tools and facilities. -However, due to it's scope and complexity, this aspect of Autotest -has been separated into the dedicated 'virt-test' suite. This suite -includes multiple packages dedicated to specific aspects of virtualization -testing. - -Within each virt-test package, are a collection of independent sub-test -modules. These may be addressed individually or as part of a sequence. -In order to hide much of the complexity involved in virtualization -testing and development, a dedicated test-runner is included with -the virt-test suite (see section test_runner_). - - -.. _quickstart: - -Quickstart ------------ - - -.. _pre-requisites: - -Pre-requisites -~~~~~~~~~~~~~~~~~~~~~ - -#. A supported host platforms: Red Hat Enterprise Linux (RHEL) or Fedora. - OpenSUSE should also work, but currently autotest is still - not packaged for it, which means you have to clone autotest and put its path - in an env variable so virt tests can find the autotest libs. - Debian/Ubuntu now have a new experimental package that allows one to run - the virt tests in a fairly straight forward way. - -#. :doc:`Install software packages (RHEL/Fedora) <../basic/InstallPrerequesitePackages>` -#. :doc:`Install software packages (Debian/Ubuntu) <../basic/InstallPrerequesitePackagesDebian>` -#. A copy of the :doc:`virt test source <../contributing/DownloadSource>` - - -.. _clone: - -Clone -~~~~~~~~ - -#. Clone the virt test repo - -:: - - git clone git://github.com/autotest/virt-test.git - - -#. Change into the repository directory - -:: - - cd virt-test - - -.. _run_bootstrap: - -``./run -t --bootstrap`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Where ```` is the virtualization test type you want to setup, for example -``"qemu"``. Explicitly using ``--bootstrap`` causes setup to run interactively -and is highly recommended. Otherwise, the test runner will execute the same -operations non-interactively. Running it interactively allows for choice and -modification of to the environment to suit specific testing or setup needs. - -The setup process includes checks for the minimum host software requirements and -sets up a directory tree to hold data. It also downloads a minimal guest OS image -(about 180 MB) called JeOS (based on Fedora). This is the default guest used -when a full-blown build from an automated install is not required. - -When executed as a non-root user, ``./run -t --bootstrap`` will create -and use ``$HOME/virt_test`` as the data directory to hold OS images, logs, -temporary files, etc. Whereas for ``root``, the system-wide location -``/var/lib/virt-test`` will be used. However it is invoked, as user, root, -interactive, or not, a symbolic link to the data directory will be created -``virt-test/shared/data`` (i.e. under the directory the repository was -cloned in). - -Interactive ``--bootstrap`` may be run at any time, for example to re-generate -the default configuration after pulling down a new release. Note that the -``-t `` argument is crucial. Any subdirectory of ``virt-test`` which -contains a file named ``control`` is a candidate ````. Also, each -```` has different requirements. For example, the libguestfs tests -have different software requirements than the qemu tests. - -.. _run_default_tests: - - -Run default tests -~~~~~~~~~~~~~~~~~~~~~~ - - -For qemu and libvirt subtests, the default test set does not require -root. However, other tests might fail due to lack of privileges. - -:: - - ./run -t qemu - -or - -:: - - ./run -t libvirt - - -.. _run_different_tests: - -Running different tests -~~~~~~~~~~~~~~~~~~~~~~~ - -You can list the available tests with the --list-tests parameter. - -:: - - $ ./run -t qemu --list-tests - (will print a numbered list of tests, with a pagination) - -Then, pass test `names` as a quote-protected, space-separated list to the --tests -parameter. For example: - -#. For qemu testing:: - - $ ./run -t qemu --tests "migrate time-drift file_transfer" - -#. Many libvirt tests require the ``virt-test-vm1`` guest exists, and assume it is - removed or restored to prestine state at the end. However, when running a - custom set of tests this may not be the case. In this case, you may need - to use the ``--install`` and/or ``--remove`` options to the test runner. - For example:: - - # ./run -t libvirt --install --remove --tests "reboot" - - -.. _checking_results: - -Checking the results -~~~~~~~~~~~~~~~~~~~~ - -The test runner will produce a debug log, that will be useful to debug -problems: - -:: - - [lmr@localhost virt-test.git]$ ./run -t qemu --tests boot_with_usb - SETUP: PASS (1.20 s) - DATA DIR: /path/to/virt_test - DEBUG LOG: /path/to/virt-test.git/logs/run-2012-12-12-01.39.34/debug.log - TESTS: 10 - boot_with_usb.ehci: PASS (18.34 s) - boot_with_usb.keyboard.uhci: PASS (21.57 s) - boot_with_usb.keyboard.xhci: PASS (24.56 s) - boot_with_usb.mouse.uhci: PASS (21.59 s) - boot_with_usb.mouse.xhci: PASS (23.11 s) - boot_with_usb.usb_audio: PASS (20.99 s) - boot_with_usb.hub: PASS (22.12 s) - boot_with_usb.storage.uhci: PASS (21.61 s) - boot_with_usb.storage.ehci: PASS (23.27 s) - boot_with_usb.storage.xhci: PASS (25.03 s) - -For convenience, the most recent debug log is pointed to by the ``logs/latest/debug.log`` symlink. - -.. _utilities: - -Utilities ----------- - -A number of helpful command-line utilities are provided along with the -Autotest client. Depending on the installation, they could be located in -various places. The table below outlines some of them along with a brief -description. - -+-------------------------+------------------------------------------------------------------------------+ -| Name | Description | -+=========================+==============================================================================+ -| ``autotest-local`` | The autotest command-line client. | -+-------------------------+------------------------------------------------------------------------------+ -| ``cartesian_config.py`` | Test matrix configuration parser module and command-line display utility. | -+-------------------------+------------------------------------------------------------------------------+ -| ``scan_results.py`` | Check for and pretty-print current testing status and/or results. | -+-------------------------+------------------------------------------------------------------------------+ -| ``html_report.py`` | Command-line HTML index and test result presentation utility. | -+-------------------------+------------------------------------------------------------------------------+ -| ``run`` | Test runner for virt-test suite. | -+-------------------------+------------------------------------------------------------------------------+ - -For developers, there are a separate set of utilities to help with -writing, debugging, and checking code and/or tests. Please see section -development_tools_ for more detail. - - -.. _test_execution: - -Detailed Test Execution -======================== - -Tests are executed from a copy of the Autotest client code, typically on -separate hardware from the Autotest server (if there is one). Executing -tests directly from a clone of the git repositories or installed Autotest -is possible. The tree is configured such that test results and local configuration -changes are kept separate from test and Autotest code. - -For virtualization tests, variant selection(s) and configuration(s) is required either -manually through specification in tests.cfg (see section tests_cfg_) or automatically -by using the test-runner (see section run_different_tests_). The test-runner is nearly -trivial to use, but doesn't offer the entire extent of test customization. See the virt_test_runner -section for more information. - - -.. _autotest_command_line: - -Autotest Command Line ----------------------- - -Several Autotest-client command-line options and parameters are -available. Running the ‘autotest’ command with the ‘``-h``’ or -‘``--help``’ parameters will display the online help. The only required -parameters are a path to the autotest control file which is detailed -elsewhere in the autotest documentation. - - -.. _output: - -Output -~~~~~~~ - -Options for controlling client output are the most frequently used. The -client process can "in a terminal, or placed in the background. -Synchronous output via stdout/stderr is provided, however full-verbosity -logs and test results are maintained separate from the controlling -terminal. This allows users to respond to test output immediately, -and/or an automated framework (such as the autotest server) to collect -it later. - - -.. _verbosity: - -Verbosity -~~~~~~~~~~ - -Access to the highest possible detail level is provided when the -‘``--verbose’`` option is used. There are multiple logging/message -levels used within autotest, from DEBUG, to INFO, and ERROR. While all -levels are logged individually, only INFO and above are displayed from -the autotest command by default. Since DEBUG is one level lower than -INFO, there are no provisions provided more granularity in terminal -output. - - -.. _job_names_tags: - -Job Names and Tags -~~~~~~~~~~~~~~~~~~~~~ - -The ‘``-t``’, or ‘``--tag``’ parameter is used to specify the TAG name -that will be appended to the name of every test. JOBNAMEs come from the -autotest server, and scheduler for a particular client. When running the -autotest client stand-alone from the command line, it’s not possible to -set the JOBNAME. However, TAGs are a way of differentiating one test -execution from another within a JOB. For example, if the same test is -run multiple times with slight variations in parameters. TAGS are also a -mechanism available on the stand-alone command line to differentiate -between executions. - - -.. _sub_commands: - -Autotest client sub-commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sub-commands are a shortcut method for performing various client tasks. -They are evaluated separately from the main command-line options. To use -them, simply append them after any standard parameters on the client -command line. - -.. _help: - -``help`` -^^^^^^^^^^^^ - -The ``help`` sub-command prints out all sub-commands along with a short -description of their use/purpose. This help output is in addition to the -standard client command-line help output. - -.. _list: - -``list`` -^^^^^^^^^^^^^^^^^^ - -The ``list`` sub-command searches for and displays a list of test names -that contain a valid control file. The list includes a short description -of each test and is sent to the default pager (i.e. more or less) for -viewing. - -.. _run: - -``run`` -^^^^^^^^^^^^^^^ - -The ``run`` sub-command complements ``list``, but as a shortcut for -executing individual tests. Only the name of the test sub-directory is -needed. For example, to execute sleeptest, the -``bin/autotest-local run sleeptest`` command may be used. - - -.. _results: - -Results -~~~~~~~~ - -On the client machine, results are stored in a ‘results’ sub-directory, -under the autotest client directory (AUTODIR). Within the ‘results’ -sub-directory, data is grouped based on the autotest server-supplied -job-name (JOBNAME). Variant shortnames (see section variants_) -represent the value used when results are recorded. -When running a stand-alone client, or if unspecified, JOBNAME is 'default'. - -+--------------------------------------------------+----------------------------------------------+ -| Relative Directory or File | Description | -+==================================================+==============================================+ -| ``/results/JOBNAME/`` | Base directory for JOBNAME(‘default’) | -+-+------------------------------------------------+----------------------------------------------+ -| | ``sysinfo`` | Overall OS-level data from client system | -+-+------------------------------------------------+----------------------------------------------+ -| | ``control`` | Copy of control file used to execute job | -+-+------------------------------------------------+----------------------------------------------+ -| | ``status`` | Overall results table for each TAGged test | -+-+------------------------------------------------+----------------------------------------------+ -| | ``sysinfo/`` | Test-centric OS-level data | -+-+------------------------------------------------+----------------------------------------------+ -| | ``debug/`` | Client execution logs, See section | -| | | verbosity_. | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``Client.DEBUG, client.INFO,`` | Client output at each verbosity level. Good | -| | | ``client.WARNING, client.ERROR`` | place to start debugging any problems. | -+-+-+----------------------------------------------+----------------------------------------------+ -| | ``/`` | Base directory of results from a specific | -| | | test | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``status`` | Test start/end time and status report table | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``keyval`` | Key / value parameters for test | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``results/`` | Customized and/or nested-test results | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``profiling/`` | Data from profiling tools during testing | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``debug/`` | Client test output at each verbosity level | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``build/`` | Base directory for tests that build code | -+-+-+-+--------------------------------------------+----------------------------------------------+ -| | | | ``status`` | Overall build status | -+-+-+-+--------------------------------------------+----------------------------------------------+ -| | | | ``src/`` | Source code used in a build | -+-+-+-+--------------------------------------------+----------------------------------------------+ -| | | | ``build/`` | Compile output / build scratch directory | -+-+-+-+--------------------------------------------+----------------------------------------------+ -| | | | ``patches/`` | Patches to apply to source code | -+-+-+-+--------------------------------------------+----------------------------------------------+ -| | | | ``config/`` | Config. Used during & for build | -+-+-+-+--------------------------------------------+----------------------------------------------+ -| | | | ``debug/`` | Build output and logs | -+-+-+-+--------------------------------------------+----------------------------------------------+ -| | | | ``summary`` | Info. About build test/progress. | -+-+-+-+--------------------------------------------+----------------------------------------------+ - - -.. _test_runner: - -Virt-test runner ------------------- - -Within the root of the virt-test sub-directory (``autotest/client/tests/virt/``, -``virt-test``, or wherever you cloned the repository) is ``run``. This is an -executable python script which provides a single, simplified interface for running -tests. The list of available options and arguments is provided by the ``-h`` or -``--help``. - -This interface also provides for initial and subsequent, interactive setup -of the various virtualization sub-test types. Even if not, the setup will -still be executed non-interactivly before testing begins. See the section -run_bootstrap_ for more infomration on initial setup. - -To summarize it's use, execute ``./run`` with the subtest type as an argument -to ``-t`` (e.g. ``qemu``, ``libvirt``, etc.), guest operating system with -``-g`` (e.g. ``RHEL.6.5.x86_64``), and a quoted, space-separated list of -test names with ``--tests``. Everything except ``-t `` is optional. - - -.. _test_runner_output: - -Virt-test runner output -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Assuming the ``-v`` verbose option is not used, the test runner will produce simple, -colorized pass/fail output. Some basic statistics are provided at the end of all tests, such -as pass/fail count, and total testing time. Full debug output is available by specifying -the ``-v`` option, or by observing ``logs/latest/debug.log`` - - -.. _test_runner_results: - -Virt-test runner results -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When utilizing the test runner, results are logged slightly different from the -autotest client. Each run logs output and results to a date & time stamped -sub-directory beneith the ``logs/`` directory. For convenience, there is a ``latest`` -symbolic link which always points at the previous run sub-directory. This makes it -handy for tailing a currently running test in another terminal. - -+--------------------------------------------------+----------------------------------------------+ -| Relative Directory or File | Description | -+==================================================+==============================================+ -| ``logs/run-YYYY-MM-DD-HH.MM.SS/`` | Results for a single run. | -+-+------------------------------------------------+----------------------------------------------+ -| | ``debug.log`` | Debug-level output for entire run. | -+-+------------------------------------------------+----------------------------------------------+ -| | ``test.cartesian.short.name/`` | Results from individual test in run | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``debug.log`` | Debug-level output from individual test | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``keyval`` | Key / value parameters for test | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``session-VM_NAME.log`` | Remote ssh session log to VM_NAME guest. | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``VM_NAME-0.webm`` | 5-second screenshot video of VM_NAME guest | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``results/`` | Customized and/or nested-test results | -+-+-+----------------------------------------------+----------------------------------------------+ -| | | ``profiling/`` | Data from profiling tools (if configured) | -+-+-+----------------------------------------------+----------------------------------------------+ - - -.. _file_directory_layout: - -File/Directory Layout ------------------------ - -.. _file_directory_layout_overview: - -Overview -~~~~~~~~~~ - -The autotest source tree is organized in a nested structure from server, -to client, to tests. The final tests element is further divided between all -the independant autotest tests, and the virt test suite. This layouy is -intended to support easy customization at the lowest levels, while keeping -the framework, tests, and configurations separated from eachother. - -Traditionally, each of these elements would be nested within eachother like so: - -+------------------------+---------------------------+ -| Relative directory | Description | -+========================+===========================+ -| ``autotest/`` | Autotest server | -+-+----------------------+---------------------------+ -| | ``client/`` | Autotest client | -+-+-+--------------------+---------------------------+ -| | | ``tests/`` | Test sub-directories | -+-+-+-+------------------+---------------------------+ -| | | | ``virt/`` | virt-test subdirectories | -+-+-+-+------------------+---------------------------+ - -However, for development and simple testing purposes, none of the server -components is required, and nearly all activity will occur under the client -and tests sub-directories. Further, depending on your operating environment, -the client components may be available as the "autotest-framework" package. -When installed, work may be solely concentrated within or beneith the ``tests`` -sub-directory. For exclusivle virtualization testing, only the `virt` -sub-directory of the ``tests`` directory is required. - - -.. _file_directory_layout_details: - -Virt-test Details -~~~~~~~~~~~~~~~~~ - -Traditionally the virtualization tests directory tree would be rooted at -``autotest/client/tests/virt``. However, when utilizing the autotest-framework -package, it commonly resides under a ``virt-test`` directory, -which may be located anywhere convenient (including your home directory). - -+------------------------------------------------+-----------------------------------------------+ -| Relative directory | Description | -+================================================+===============================================+ -| ``run.py`` | The test-runner script. (see section | -| | (test_runner_) | -+------------------------------------------------+-----------------------------------------------+ -| ``virt.py`` | Module used by the autotest framework to | -| | define the ``test.test`` subclass and methods | -| | needed for test execution. This is utilized | -| | when tests are executed from the autotest | -| | client. | -+------------------------------------------------+-----------------------------------------------+ -| ``logs/`` | Logs and test results when utilizing the test | -| | runner (see section test_runner_results_) | -+------------------------------------------------+-----------------------------------------------+ -| ``virttest/`` | Modules for host, guest, and test utilities | -| | shared by nearly all the virt-test sub-test. | -| | The scope spans multiple virtualization | -| | hypervisors, technologies, libraries and | -| | tracking facilities. Not every component is | -| | required for every test, but all | -| | virtualization tests consume multiple modules | -| | within this tree. | -+-+----------------------------------------------+-----------------------------------------------+ -| | ``common.py`` | Central autotest framework module utilized by | -| | | nearly all other modules. It creates the | -| | | top-level namespaces under which the entirety | -| | | of the autotest client framework packages are | -| | | made available as | -| | | ``autotest.client`` | -+-+----------------------------------------------+-----------------------------------------------+ -| | ``data_dir.py`` | Provides a centralized interface for virt-test| -| | | code and tests to access runtime test data | -| | | (os images, iso images, boot files, etc.) | -+-+----------------------------------------------+-----------------------------------------------+ -| | ``standalone_test.py`` | Stand-in for the autotest-framework needed by | -| | | the test runner. Takes the place of the | -| | | ``test.test`` class. Also provides other | -| | | test-runner specific classes and functions. | -+-+----------------------------------------------+-----------------------------------------------+ -| ``tests/`` | Shared virtualization sub-test modules. The | -| | largest and most complex is the unattended | -| | install test. All test modules in this | -| | directory are virtualization technology | -| | agnostic. Most of the test modules are simple | -| | and well commented. They are an excellent | -| | reference for test developers starting to | -| | write a new test. | -+------------------------------------------------+-----------------------------------------------+ -| ``qemu``, ``libvirt``, ``libguestfs``, etc. | Technology-specific trees organizing both | -| | test-modules and configuration. | -+-+----------------------------------------------+-----------------------------------------------+ -| | ``cfg`` | Runtime virt test framework and test Cartesian| -| | | configuration produced by | -| | | ``./run --bootstrap`` | -| | | and consumed by both the autotest-client and | -| | | standalone test-runner. (See section | -| | | default_configuration_files_) | -+-+----------------------------------------------+-----------------------------------------------+ -| ``shared/`` | Runtime data shared amung all | -| | virtualization tests. | -+-+----------------------------------------------+-----------------------------------------------+ -| | ``cfg/`` | Persistent Cartesian configuration source for | -| | | derriving technology-specific runtime | -| | | configuration and definition (See section | -| | | default_configuration_files_) | -+-+----------------------------------------------+-----------------------------------------------+ -| | ``unattended/`` | Data specific to the unattended install test. | -| | | Kickstart, answer-files, as well as other | -| | | data utilized during the unattended install | -| | | process. Most of the files contain placeholder| -| | | keywords which are substituted with actual | -| | | values at run-time | -+-+----------------------------------------------+-----------------------------------------------+ -| | ``control/`` | Autotest test control files used when | -| | | executing autotest tests within a guest | -| | | virtual machine. | -+-+----------------------------------------------+-----------------------------------------------+ -| | ``data/`` | A symlink to dynamic runtime data shared amung| -| | | all virtualization tests. The destination and| -| | | control over this location is managed by the | -| | | ``virttest/data_dir.py`` module referenced | -| | | above. | -+-+-+--------------------------------------------+-----------------------------------------------+ -| | | ``boot/`` | Files required for starting a virtual machine | -| | | | (i.e. kernel and initrd images) | -+-+-+--------------------------------------------+-----------------------------------------------+ -| | | ``images/`` | Virtual machine disk images and related files | -+-+-+--------------------------------------------+-----------------------------------------------+ -| | | ``isos/`` | Location for installation disc images | -+-+-+--------------------------------------------+-----------------------------------------------+ - - -.. _cartesian_configuration: - -Cartesian Configuration ------------------------- - -Cartesian Configuration is a highly specialized way of providing lists -of key/value pairs within combination's of various categories. The -format simplifies and condenses highly complex multidimensional arrays -of test parameters into a flat list. The combinatorial result can be -filtered and adjusted prior to testing, with filters, dependencies, and -key/value substitutions. - -The parser relies on indentation, and is very sensitive to misplacement -of tab and space characters. It’s highly recommended to edit/view -Cartesian configuration files in an editor capable of collapsing tab -characters into four space characters. Improper attention to column -spacing can drastically affect output. - - -.. _keys_and_values: - -Keys and values -~~~~~~~~~~~~~~~~~~ - -Keys and values are the most basic useful facility provided by the -format. A statement in the form `` = `` sets ```` to -````. Values are strings, terminated by a linefeed, with -surrounding quotes completely optional (but honored). A reference of -descriptions for most keys is included in section Configuration Parameter -Reference. -The key will become part of all lower-level (i.e. further indented) variant -stanzas (see section variants_). -However, key precedence is evaluated in top-down or ‘last defined’ -order. In other words, the last parsed key has precedence over earlier -definitions. - - -.. _variants: - -Variants -~~~~~~~~~~~ - -A ‘variants’ stanza is opened by a ‘variants:’ statement. The contents -of the stanza must be indented further left than the ‘variants:’ -statement. Each variant stanza or block defines a single dimension of -the output array. When a Cartesian configuration file contains -two variants stanzas, the output will be all possible combination's of -both variant contents. Variants may be nested within other variants, -effectively nesting arbitrarily complex arrays within the cells of -outside arrays. For example:: - - variants: - - one: - key1 = Hello - - two: - key2 = World - - three: - variants: - - four: - key3 = foo - - five: - key3 = bar - - six: - key1 = foo - key2 = bar - -While combining, the parser forms names for each outcome based on -prepending each variant onto a list. In other words, the first variant -name parsed will appear as the left most name component. These names can -become quite long, and since they contain keys to distinguishing between -results, a 'short-name' key is also used. For example, running -``cartesian_config.py`` against the content above produces the following -combinations and names:: - - dict 1: four.one - dict 2: four.two - dict 3: four.three - dict 4: five.one - dict 5: five.two - dict 6: five.three - dict 7: six.one - dict 8: six.two - dict 9: six.three - -Variant shortnames represent the value used when results are -recorded (see section Job Names and Tags. For convenience -variants who’s name begins with a ‘``@``’ do not prepend their name to -'short-name', only 'name'. This allows creating ‘shortcuts’ for -specifying multiple sets or changes to key/value pairs without changing -the results directory name. For example, this is often convenient for -providing a collection of related pre-configured tests based on a -combination of others (see section tests_). - - -Named variants -~~~~~~~~~~~~~~ - -Named variants allow assigning a parseable name to a variant set. This enables -an entire variant set to be used for in filters_. All output combinations will -inherit the named varient key, along with the specific variant name. For example:: - - variants var1_name: - - one: - key1 = Hello - - two: - key2 = World - - three: - variants var2_name: - - one: - key3 = Hello2 - - two: - key4 = World2 - - three: - - only (var2_name=one).(var1_name=two) - -Results in the following outcome when parsed with ``cartesian_config.py -c``:: - - dict 1: (var2_name=one).(var1_name=two) - dep = [] - key2 = World # variable key2 from variants var1_name and variant two. - key3 = Hello2 # variable key3 from variants var2_name and variant one. - name = (var2_name=one).(var1_name=two) - shortname = (var2_name=one).(var1_name=two) - var1_name = two # variant name in same namespace as variables. - var2_name = one # variant name in same namespace as variables. - -Named variants could also be used as normal variables.:: - - variants guest_os: - - fedora: - - ubuntu: - variants disk_interface: - - virtio: - - hda: - -Which then results in the following:: - - dict 1: (disk_interface=virtio).(guest_os=fedora) - dep = [] - disk_interface = virtio - guest_os = fedora - name = (disk_interface=virtio).(guest_os=fedora) - shortname = (disk_interface=virtio).(guest_os=fedora) - dict 2: (disk_interface=virtio).(guest_os=ubuntu) - dep = [] - disk_interface = virtio - guest_os = ubuntu - name = (disk_interface=virtio).(guest_os=ubuntu) - shortname = (disk_interface=virtio).(guest_os=ubuntu) - dict 3: (disk_interface=hda).(guest_os=fedora) - dep = [] - disk_interface = hda - guest_os = fedora - name = (disk_interface=hda).(guest_os=fedora) - shortname = (disk_interface=hda).(guest_os=fedora) - dict 4: (disk_interface=hda).(guest_os=ubuntu) - dep = [] - disk_interface = hda - guest_os = ubuntu - name = (disk_interface=hda).(guest_os=ubuntu) - shortname = (disk_interface=hda).(guest_os=ubuntu) - - -.. _dependencies: - -Dependencies -~~~~~~~~~~~~~~~ - -Often it is necessary to dictate relationships between variants. In this -way, the order of the resulting variant sets may be influenced. This is -accomplished by listing the names of all parents (in order) after the -child’s variant name. However, the influence of dependencies is ‘weak’, -in that any later defined, lower-level (higher indentation) definitions, -and/or filters (see section filters_) can remove or modify dependents. For -example, if testing unattended installs, each virtual machine must be booted -before, and shutdown after: - -:: - - variants: - - one: - key1 = Hello - - two: one - key2 = World - - three: one two - -Results in the correct sequence of variant sets: one, two, *then* three. - - -.. _filters: - -Filters -~~~~~~~~~~ - -Filter statements allow modifying the resultant set of keys based on the -name of the variant set (see section variants_). Filters can be used in 3 ways: -Limiting the set to include only combination names matching a pattern. -Limiting the set to exclude all combination names not matching a -pattern. Modifying the set or contents of key/value pairs within a -matching combination name. - -Names are matched by pairing a variant name component with the -character(s) ‘,’ meaning OR, ‘..’ meaning AND, and ‘.’ meaning -IMMEDIATELY-FOLLOWED-BY. When used alone, they permit modifying the list -of key/values previously defined. For example: - -:: - - Linux..OpenSuse: - initrd = initrd - -Modifies all variants containing ‘Linux’ followed anywhere thereafter -with ‘OpenSuse’, such that the ‘initrd’ key is created or overwritten -with the value ‘initrd’. - -When a filter is preceded by the keyword ‘only’ or ‘no’, it limits the -selection of variant combination's This is used where a particular set -of one or more variant combination's should be considered selectively or -exclusively. When given an extremely large matrix of variants, the -‘only’ keyword is convenient to limit the result set to only those -matching the filter. Whereas the ‘no’ keyword could be used to remove -particular conflicting key/value sets under other variant combination -names. For example: - -:: - - only Linux..Fedora..64 - -Would reduce an arbitrarily large matrix to only those variants who’s -names contain Linux, Fedora, and 64 in them. - -However, note that any of these filters may be used within named -variants as well. In this application, they are only evaluated when that -variant name is selected for inclusion (implicitly or explicitly) by a -higher-order. For example: - -:: - - variants: - - one: - key1 = Hello - variants: - - two: - key2 = Complicated - - three: one two - key3 = World - variants: - - default: - only three - key2 = - - only default - -Results in the following outcome: - -:: - - name = default.three.one - key1 = Hello - key2 = - key3 = World - - -.. _value_substitutions: - -Value Substitutions -~~~~~~~~~~~~~~~~~~~~~~ - -Value substitution allows for selectively overriding precedence and -defining part or all of a future key’s value. Using a previously defined -key, it’s value may be substituted in or as a another key’s value. The -syntax is exactly the same as in the bash shell, where as a key’s value -is substituted in wherever that key’s name appears following a ‘$’ -character. When nesting a key within other non-key-name text, the name -should also be surrounded by ‘{‘, and ‘}’ characters. - -Replacement is context-sensitive, thereby if a key is redefined within -the same, or, higher-order block, that value will be used for future -substitutions. If a key is referenced for substitution, but hasn’t yet -been defined, no action is taken. In other words, the $key or ${key} -string will appear literally as or within the value. Nesting of -references is not supported (i.e. key substitutions within other -substitutions. - -For example, if ``one = 1, two = 2, and three = 3``; then, -``order = ${one}${two}${three}`` results in ``order = 123``. This is -particularly handy for rooting an arbitrary complex directory tree -within a predefined top-level directory. - -An example of context-sensitivity, - -:: - - key1 = default value - key2 = default value - - sub = "key1: ${key1}; key2: ${key2};" - - variants: - - one: - key1 = Hello - sub = "key1: ${key1}; key2: ${key2};" - - two: one - key2 = World - sub = "key1: ${key1}; key2: ${key2};" - - three: one two - sub = "key1: ${key1}; key2: ${key2};" - -Results in the following, - -:: - - dict 1: one - dep = [] - key1 = Hello - key2 = default value - name = one - shortname = one - sub = key1: Hello; key2: default value; - dict 2: two - dep = ['one'] - key1 = default value - key2 = World - name = two - shortname = two - sub = key1: default value; key2: World; - dict 3: three - dep = ['one', 'two'] - key1 = default value - key2 = default value - name = three - shortname = three - sub = key1: default value; key2: default value; - - -.. _key_sub_arrays: - -Key sub-arrays -~~~~~~~~~~~~~~~~~ - -Parameters for objects like VM’s utilize array’s of keys specific to a -particular object instance. In this way, values specific to an object -instance can be addressed. For example, a parameter ‘vms’ lists the VM -objects names to instantiate in in the current frame’s test. Values -specific to one of the named instances should be prefixed to the name: - -:: - - vms = vm1 second_vm another_vm - mem = 128 - mem_vm1 = 512 - mem_second_vm = 1024 - -The result would be, three virtual machine objects are create. The third -one (another\_vm) receives the default ‘mem’ value of 128. The first two -receive specialized values based on their name. - -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. Note: This is contrary to the way the -Cartesian configuration file as a whole is parsed (top-down). - - -.. _include_statements: - -Include statements -~~~~~~~~~~~~~~~~~~~~~ - -The ‘``include``’ statement is utilized within a Cartesian configuration -file to better organize related content. When parsing, the contents of -any referenced files will be evaluated as soon as the parser encounters -the ``include`` statement. The order in which files are included is -relevant, and will carry through any key/value substitutions -(see section key_sub_arrays_) as if parsing a complete, flat file. - - -.. _combinatorial_outcome: - -Combinatorial outcome -~~~~~~~~~~~~~~~~~~~~~~~~ - -The parser is available as both a python module and command-line tool -for examining the parsing results in a text-based listing. To utilize it -on the command-line, run the module followed by the path of the -configuration file to parse. For example, -``common_lib/cartesian_config.py tests/libvirt/tests.cfg``. - -The output will be just the names of the combinatorial result set items -(see short-names, section Variants). However, -the ‘``--contents``’ parameter may be specified to examine the output in -more depth. Internally, the key/value data is stored/accessed similar to -a python dictionary instance. With the collection of dictionaries all -being part of a python list-like object. Irrespective of the internals, -running this module from the command-line is an excellent tool for both -reviewing and learning about the Cartesian Configuration format. - -In general, each individual combination of the defined variants provides -the parameters for a single test. Testing proceeds in order, through -each result, passing the set of keys and values through to the harness -and test code. When examining Cartesian configuration files, it’s -helpful to consider the earliest key definitions as “defaults”, then -look to the end of the file for other top-level override to those -values. If in doubt of where to define or set a key, placing it at the -top indentation level, at the end of the file, will guarantee it is -used. - - -.. _formal_definition: - -Formal definition -~~~~~~~~~~~~~~~~~~~~ -- A list of dictionaries is referred to as a frame. - -- The parser produces a list of dictionaries (dicts). Each dictionary - contains a set of key-value pairs. - -- Each dict contains at least three keys: name, shortname and depend. - The values of name and shortname are strings, and the value of depend - is a list of strings. - -- The initial frame contains a single dict, whose name and shortname - are empty strings, and whose depend is an empty list. - -- Parsing dict contents - - - The dict parser operates on a frame, referred to as the current frame. - - - A statement of the form = sets the value of to - in all dicts of the current frame. If a dict lacks , - it will be created. - - - A statement of the form += appends to the - value of in all dicts of the current frame. If a dict lacks - , it will be created. - - - A statement of the form <= pre-pends to the - value of in all dicts of the current frame. If a dict lacks - , it will be created. - - - A statement of the form ?= sets the value of - to , in all dicts of the current frame, but only if - exists in the dict. The operators ?+= and ?<= are also supported. - - - A statement of the form no removes from the current frame - all dicts whose name field matches . - - - A statement of the form only removes from the current - frame all dicts whose name field does not match . - -- Content exceptions - - - Single line exceptions have the format : - where is any of the operators listed above - (e.g. =, +=, ?<=). The statement following the regular expression - will apply only to the dicts in the current frame whose - name partially matches (i.e. contains a substring that - matches ). - - - A multi-line exception block is opened by a line of the format - :. The text following this line should be indented. The - statements in a multi-line exception block may be assignment - statements (such as = ) or no or only statements. - Nested multi-line exceptions are allowed. - -- Parsing Variants - - - A variants block is opened by a ``variants:`` statement. The indentation - level of the statement places the following set within the outer-most - context-level when nested within other ``variant:`` blocks. The contents - of the ``variants:`` block must be further indented. - - - A variant-name may optionally follow the ``variants`` keyword, before - the ``:`` character. That name will be inherited by and decorate all - block content as the key for each variant contained in it's the - block. - - - The name of the variants are specified as ``- :``. - Each name is pre-pended to the name field of each dict of the variant's - frame, along with a separator dot ('.'). - - - The contents of each variant may use the format `` ``. - They may also contain further ``variants:`` statements. - - - If the name of the variant is not preceeded by a @ (i.e. - - @:), it is pre-pended to the shortname field of - each dict of the variant's frame. In other words, if a variant's - name is preceeded by a @, it is omitted from the shortname field. - - - Each variant in a variants block inherits a copy of the frame in - which the variants: statement appears. The 'current frame', which - may be modified by the dict parser, becomes this copy. - - - The frames of the variants defined in the block are - joined into a single frame. The contents of frame replace the - contents of the outer containing frame (if there is one). - -- Filters - - - Filters can be used in 3 ways: - - - :: - - only - - - :: - - no - - - :: - - : (starts a conditional block, see 4.4 Filters) - - - Syntax: - -:: - - .. means AND - . means IMMEDIATELY-FOLLOWED-BY - -- Example: - - :: - - qcow2..Fedora.14, RHEL.6..raw..boot, smp2..qcow2..migrate..ide - -:: - - means match all dicts whose names have: - (qcow2 AND (Fedora IMMEDIATELY-FOLLOWED-BY 14)) OR - ((RHEL IMMEDIATELY-FOLLOWED-BY 6) AND raw AND boot) OR - (smp2 AND qcow2 AND migrate AND ide) - -- Note: - - :: - - 'qcow2..Fedora.14' is equivalent to 'Fedora.14..qcow2'. - -:: - - 'qcow2..Fedora.14' is not equivalent to 'qcow2..14.Fedora'. - 'ide, scsi' is equivalent to 'scsi, ide'. - - -.. _examples_cartesian: - -Examples -~~~~~~~~~~~~ - -- A single dictionary:: - - key1 = value1 - key2 = value2 - key3 = value3 - - Results in the following:: - - Dictionary #0: - depend = [] - key1 = value1 - key2 = value2 - key3 = value3 - name = - shortname = - -- Adding a variants block:: - - key1 = value1 - key2 = value2 - key3 = value3 - - variants: - - one: - - two: - - three: - - Results in the following:: - - Dictionary #0: - depend = [] - key1 = value1 - key2 = value2 - key3 = value3 - name = one - shortname = one - Dictionary #1: - depend = [] - key1 = value1 - key2 = value2 - key3 = value3 - name = two - shortname = two - Dictionary #2: - depend = [] - key1 = value1 - key2 = value2 - key3 = value3 - name = three - shortname = three - -- Modifying dictionaries inside a variant:: - - key1 = value1 - key2 = value2 - key3 = value3 - - variants: - - one: - key1 = Hello World - key2 <= some_prefix_ - - two: - key2 <= another_prefix_ - - three: - - Results in the following:: - - Dictionary #0: - depend = [] - key1 = Hello World - key2 = some_prefix_value2 - key3 = value3 - name = one - shortname = one - Dictionary #1: - depend = [] - key1 = value1 - key2 = another_prefix_value2 - key3 = value3 - name = two - shortname = two - Dictionary #2: - depend = [] - key1 = value1 - key2 = value2 - key3 = value3 - name = three - shortname = three - -- Adding dependencies:: - - key1 = value1 - key2 = value2 - key3 = value3 - - variants: - - one: - key1 = Hello World - key2 <= some_prefix_ - - two: one - key2 <= another_prefix_ - - three: one two - - Results in the following:: - - Dictionary #0: - depend = [] - key1 = Hello World - key2 = some_prefix_value2 - key3 = value3 - name = one - shortname = one - Dictionary #1: - depend = ['one'] - key1 = value1 - key2 = another_prefix_value2 - key3 = value3 - name = two - shortname = two - Dictionary #2: - depend = ['one', 'two'] - key1 = value1 - key2 = value2 - key3 = value3 - name = three - shortname = three - -- Multiple variant blocks:: - - key1 = value1 - key2 = value2 - key3 = value3 - - variants: - - one: - key1 = Hello World - key2 <= some_prefix_ - - two: one - key2 <= another_prefix_ - - three: one two - - variants: - - A: - - B: - - Results in the following:: - - Dictionary #0: - depend = [] - key1 = Hello World - key2 = some_prefix_value2 - key3 = value3 - name = A.one - shortname = A.one - Dictionary #1: - depend = ['A.one'] - key1 = value1 - key2 = another_prefix_value2 - key3 = value3 - name = A.two - shortname = A.two - Dictionary #2: - depend = ['A.one', 'A.two'] - key1 = value1 - key2 = value2 - key3 = value3 - name = A.three - shortname = A.three - Dictionary #3: - depend = [] - key1 = Hello World - key2 = some_prefix_value2 - key3 = value3 - name = B.one - shortname = B.one - Dictionary #4: - depend = ['B.one'] - key1 = value1 - key2 = another_prefix_value2 - key3 = value3 - name = B.two - shortname = B.two - Dictionary #5: - depend = ['B.one', 'B.two'] - key1 = value1 - key2 = value2 - key3 = value3 - name = B.three - shortname = B.three - -- Filters, ``no`` and ``only``:: - - key1 = value1 - key2 = value2 - key3 = value3 - - variants: - - one: - key1 = Hello World - key2 <= some_prefix_ - - two: one - key2 <= another_prefix_ - - three: one two - - variants: - - A: - no one - - B: - only one,three - - Results in the following:: - - Dictionary #0: - depend = ['A.one'] - key1 = value1 - key2 = another_prefix_value2 - key3 = value3 - name = A.two - shortname = A.two - Dictionary #1: - depend = ['A.one', 'A.two'] - key1 = value1 - key2 = value2 - key3 = value3 - name = A.three - shortname = A.three - Dictionary #2: - depend = [] - key1 = Hello World - key2 = some_prefix_value2 - key3 = value3 - name = B.one - shortname = B.one - Dictionary #3: - depend = ['B.one', 'B.two'] - key1 = value1 - key2 = value2 - key3 = value3 - name = B.three - shortname = B.three - -- Short-names:: - - key1 = value1 - key2 = value2 - key3 = value3 - - variants: - - one: - key1 = Hello World - key2 <= some_prefix_ - - two: one - key2 <= another_prefix_ - - three: one two - - variants: - - @A: - no one - - B: - only one,three - - Results in the following:: - - Dictionary #0: - depend = ['A.one'] - key1 = value1 - key2 = another_prefix_value2 - key3 = value3 - name = A.two - shortname = two - Dictionary #1: - depend = ['A.one', 'A.two'] - key1 = value1 - key2 = value2 - key3 = value3 - name = A.three - shortname = three - Dictionary #2: - depend = [] - key1 = Hello World - key2 = some_prefix_value2 - key3 = value3 - name = B.one - shortname = B.one - Dictionary #3: - depend = ['B.one', 'B.two'] - key1 = value1 - key2 = value2 - key3 = value3 - name = B.three - shortname = B.three - -- Exceptions:: - - key1 = value1 - key2 = value2 - key3 = value3 - - variants: - - one: - key1 = Hello World - key2 <= some_prefix_ - - two: one - key2 <= another_prefix_ - - three: one two - - variants: - - @A: - no one - - B: - only one,three - - three: key4 = some_value - - A: - no two - key5 = yet_another_value - - Results in the following:: - - Dictionary #0: - depend = ['A.one', 'A.two'] - key1 = value1 - key2 = value2 - key3 = value3 - key4 = some_value - key5 = yet_another_value - name = A.three - shortname = three - Dictionary #1: - depend = [] - key1 = Hello World - key2 = some_prefix_value2 - key3 = value3 - name = B.one - shortname = B.one - Dictionary #2: - depend = ['B.one', 'B.two'] - key1 = value1 - key2 = value2 - key3 = value3 - key4 = some_value - name = B.three - shortname = B.three - - -.. _default_configuration_files: - -Default Configuration Files ----------------------------- - -The test configuration files are used for controlling the framework, by -specifying parameters for each test. The parser produces a list of -key/value sets, each set pertaining to a single test. Variants are -organized into separate files based on scope and/or applicability. For -example, the definitions for guest operating systems is sourced from a -shared location since all virtualization tests may utilize them. - -For each set/test, keys are interpreted by the test dispatching system, -the pre-processor, the test module itself, then by the post-processor. -Some parameters are required by specific sections and others are -optional. When required, parameters are often commented with possible -values and/or their effect. There are select places in the code where -in-memory keys are modified, however this practice is discouraged unless -there’s a very good reason. - -When ``./run --bootstrap`` executed (see section run_bootstrap_), copies of the -sample configuration files are copied for use under the ``cfg`` subdirectory of -the virtualization technology-specific directory. For example, ``qemu/cfg/base.cfg``. -These copies are the versions used by the framework for both the autotest client -and test-runner. - -+-----------------------------+-------------------------------------------------+ -| Relative Directory or File | Description | -+-----------------------------+-------------------------------------------------+ -| cfg/tests.cfg | The first file read that includes all other | -| | files, then the master set of filters to select | -| | the actual test set to be run. Normally | -| | this file never needs to be modified unless | -| | precise control over the test-set is needed | -| | when utilizing the autotest-client (only). | -+-----------------------------+-------------------------------------------------+ -| cfg/tests-shared.cfg | Included by ``tests.cfg`` to indirectly | -| | reference the remaining set of files to include | -| | as well as set some global parameters. | -| | It is used to allow customization and/or | -| | insertion within the set of includes. Normally | -| | this file never needs to be modified. | -+-----------------------------+-------------------------------------------------+ -| cfg/base.cfg | Top-level file containing important parameters | -| | relating to all tests. All keys/values defined | -| | here will be inherited by every variant unless | -| | overridden. This is the *first* file to check | -| | for settings to change based on your environment| -+-----------------------------+-------------------------------------------------+ -| cfg/build.cfg | Configuration specific to pre-test code | -| | compilation where required/requested. Ignored | -| | when a client is not setup for build testing. | -+-----------------------------+-------------------------------------------------+ -| cfg/subtests.cfg | Automatically generated based on the test | -| | modules and test configuration files found | -| | when the ``./run --bootstrap`` is used. | -| | Modifications are discourraged since they will | -| | be lost next time ``--bootstrap`` is used. | -+-----------------------------+-------------------------------------------------+ -| cfg/guest-os.cfg | Automatically generated from | -| | files within ``shared/cfg/guest-os/``. Defines | -| | all supported guest operating system | -| | types, architectures, installation images, | -| | parameters, and disk device or image names. | -+-----------------------------+-------------------------------------------------+ -| cfg/guest-hw.cfg | All virtual and physical hardware related | -| | parameters are organized within variant names. | -| | Within subtest variants or the top-level test | -| | set definition, hardware is specified by | -| | Including, excluding, or filtering variants and | -| | keys established in this file. | -+-----------------------------+-------------------------------------------------+ -| cfg/cdkeys.cfg | Certain operating systems require non-public | -| | information in order to operate and or install | -| | properly. For example, installation numbers and | -| | license keys. None of the values in this file | -| | are populated automatically. This file should | -| | be edited to supply this data for use by the | -| | unattended install test. | -+-----------------------------+-------------------------------------------------+ -| cfg/virtio-win.cfg | Paravirtualized hardware when specified for | -| | Windows testing, must have dependent drivers | -| | installed as part of the OS installation | -| | process. This file contains mandatory variants | -| | and keys for each Windows OS version, | -| | specifying the host location and installation | -| | method for each driver. | -+-----------------------------+-------------------------------------------------+ - - -.. _configuration_file_details: - -Configuration file details -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. _base_cfg: - -Base -^^^^^^^^^ - -Nearly as important as tests.cfg, since it's the first file processed. -This file is responsible for defining all of the top-level default -settings inherited by all hardware, software, subtest, and run-time -short-name variants. It's critical for establishing the default -networking model of the host system, pathnames, and the virtualization -technology being tested. It also contains guest options that don't fit -within the context of the other configuration files, such as default -memory size, console video creation for tests, and guest console display -options (for human monitoring). When getting started in virtualization -autotest, or setting up on a new host, this is usually the file to edit -first. - -.. _tests_cfg: - -tests -^^^^^^^^^^^^ - -The ``tests.cfg`` file is responsible for acting on the complete -collection of variants available and producing a useful result. -In other words, all other configuration files (more or less) -define “what is possible”, ``tests.cfg`` defines what will -actually happen. - -In the order they appear, there are three essential sections: - -- A set of pre-configured example short-name variants for several OS's, - hypervisor types, and virtual hardware configurations. They can be - used directly, and/or copied and modified as needed. - -- An overriding value-filter set, which adjusts several key path-names - and file locations that are widely applicable. - -- The final top-level scoping filter set for limiting the tests to run, - among the many available. - -The default configuration aims to support the quick-start (see section run_) -with a simple and minimal test set that's easy to get running. It calls on -a variant defined within the pre-configured example set as described above. It -also provides the best starting place for exploring the configuration format -and learning about how it's used to support virtualization testing. - - -.. _cdkeys_virtio_cfg: - -cdkeys and windows virtio -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This is the least-accessed among the configuration files. It exists -because certain operating systems require non-public information in -order to operate and or install properly. Keeping this data stored in a -special purpose file, keeps the data allows it's privacy level to be -controlled. None of the values in this file are populated automatically. -This file should be hand-edited to supply this data for use by the -autotest client. It is not required for the default test configured in -``tests.cfg.`` - -The windows-centric ``virtio-win.cfg`` file is similar in that it is -only applicable to windows guest operating systems. It supplements -windows definitions from ``guest-os.cfg`` with configuration needed to -ensure the virtio drivers are available during windows installation. - -To install the virtio drivers during guest install, virtualization -autotest has to inform the windows install programs \*where\* to find -the drivers. Virtualization autotest uses a boot floppy with a Windows -answer file in order to perform unattended install of windows guests. -For winXP and win2003, the unattended files are simple ``.ini`` files, -while for win2008 and later, the unattended files are XML files. -Therefor, it makes the following assumptions: - -- An iso file is available that contains windows virtio drivers (inf - files) for both netkvm and viostor. - -- For WinXP or Win2003, a a pre-made floppy disk image is available - with the virtio drivers and a configuration file the Windows - installer will read, to fetch the right drivers. - -- Comfort and familiarity editing and working with the Cartesian - configuration file format, setting key values and using filters to - point virtualization autotest at host files. - - -.. _guest_hw_os: - -guest hw & guest os -^^^^^^^^^^^^^^^^^^^^^^ - -Two of the largest and most complex among the configuration files, this -pair defines a vast number of variants and keys relating purely to guest -operating system parameters and virtual hardware. Their intended use is -from within ``tests.cfg`` (see section tests_). Within ``tests.cfg`` short-name -variants, filters are used for both OS and HW variants in these files to -choose among the many available sets of options. - -For example if a test requires the virtio network driver is used, it -would be selected with the filter '``only virtio_net``'. This filter -means content of the virtio\_net variant is included from -``guest-hw.cfg``, which in turn results in the '``nic_model = virtio``' -definition. In a similar manner, all guest installation methods (with -the exception of virtio for Windows) and operating system related -parameters are set in ``guest-os.cfg``. - - -.. _sub_tests_cfg: - -Sub-tests -^^^^^^^^^^^ - -The third most complex of the configurations, ``subtests.cfg`` holds -variants defining all of the available virtualization sub-tests -available. They include definitions for running nested -non-virtualization autotest tests within guests. For example, the -simplistic 'sleeptest' may be run with the filter -'``only autotest.sleeptest``'. - -The ``subtests.cfg`` file is rarely edited directly, instead it's -intended to provide a reasonable set of defaults for testing. If -particular test keys need customization, this should be done within the -short-name variants defined or created in ``tests.cfg`` (see section tests_). -However, available tests and their options are commented within -``subtests.cfg``, so it is often referred to as a source for available tests -and their associated controls. - -.. _config_usage_details: - -Configuration usage details -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. _default_test_set: - -For a complete reference, refer to -:doc:`the cartesian config params documentation <../advanced/cartesian/CartesianConfigParametersIntro>` - - -.. _preserving_installed_guest_images: - -Preserving installed Guest images -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -See :doc:`Run tests on an existing guest <../advanced/RunTestsExistingGuest>` - - -.. _specialized_networking: - -Specialized Networking -^^^^^^^^^^^^^^^^^^^^^^^^ - -See :doc:`Autotest networking documentation ` - - -.. _using_virtio_drivers_windows: - -Using virtio drivers with windows -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Required items include access to the virtio driver installation image, -the Windows ISO files, and the ``winutils.iso`` CD (See section -run_bootstrap_) . Every effort is made to standardize on files -available from MSDN. For example, using the Windows7 64 bit -(non SP1) requires the CD matching: - -- :: - - cdrom_cd1 = isos/windows/en_windows_7_ultimate_x86_dvd_x15-65921.iso - -- :: - - sha1sum_cd1 = 5395dc4b38f7bdb1e005ff414deedfdb16dbf610 - -This file can be downloaded from the MSDN site then it’s ``SHA1`` -verified. - -Next, place the windows media image (creating directory if needed) in -``shared/data/isos/windows/``. Edit the ``cfg/cdkeys.cfg`` file to supply -license information if required. - -Finally, if not using the test runner, set up ``cfg/tests.cfg`` to include the -``windows_quick`` short-name variant (see section tests_). Modify the -network and block device filters to use '``virtio_net``' and '``virtio-blk``' -instead. - - -.. _development_tools: - -Development tools / utilities --------------------------------- - -A number of utilities are available for the autotest core, client, -and/or test developers. Depending on your installation type, these may be -located in different sub-directories of the tree. - -+-------------------------------------------+--------------------------------------------------+ -| Name | Description | -+===========================================+==================================================+ -| ``run_pylint.py`` | Wrapper is required to run pylint due to the | -| | way imports have been implemented. | -+-------------------------------------------+--------------------------------------------------+ -| ``check_patch.py`` | Help developers scan code tree and display or fix| -| | problems | -+-------------------------------------------+--------------------------------------------------+ -| ``reindent.py`` | Help developers fix simple indentation | -| | problems | -+-------------------------------------------+--------------------------------------------------+ - - -Contributions ---------------- - - -.. _code_contributions: - -Code -~~~~~~~~ - -Contributions of additional tests and code are always welcome. If in -doubt, and/or for advice on approaching a particular problem, please -contact the projects members (see section _collaboration) Before submitting code, -please review the `git repository configuration guidelines `_. - -To submit changes, please follow `these instructions `_. -Please allow up to two weeks for a maintainer to pick -up and review your changes. Though, if you'd like help at any stage, feel free to post on the mailing -lists and reference your pull request. - -.. _docs_contribution: - -Docs -~~~~~~~~ - -Please edit the documentation directly to correct any minor inaccuracies -or to clarify items. The preferred markup syntax is -`ReStructuredText `_, -keeping with the conventions and style found in existing documentation. -For any graphics or diagrams, web-friendly formats should be used, such as -PNG or SVG. - -Avoid using 'you', 'we', 'they', as they can be ambiguous in reference -documentation. It works fine in conversation and e-mail, but looks weird -in reference material. Similarly, avoid using 'unnecessary', off-topic, or -extra language. For example in American English, `"Rinse and repeat" -`_ is a funny phrase, -but could cause problems when translated into other languages. Basically, -try to avoid anything that slows the reader down from finding facts. - -For major documentation work, it’s more convenient to use a different -approach. The autotest wiki is stored on github as a separate repository -from the project code. The wiki repository contains all the files, and -allows for version control over them. To clone the wiki repository, click -the ``Clone URL`` button on the wiki page (next to ``Page History``. - -When working with the wiki repository, it’s sometimes convenient to -render the wiki pages locally while making and committing changes. The -gollum ruby gem may be installed so you can view the wiki locally. -See `the gollum wiki readme `_ for -more details. - -_contact_info: - -Contact Info. -~~~~~~~~~~~~~ - -`Please refer to this page `_ \ No newline at end of file diff --git a/documentation/source/advanced/VirtualEnvMultihost.rst b/documentation/source/advanced/VirtualEnvMultihost.rst deleted file mode 100644 index 58d769b4b5..0000000000 --- a/documentation/source/advanced/VirtualEnvMultihost.rst +++ /dev/null @@ -1,117 +0,0 @@ -================================================ -Setup a virtual environment for multi host tests -================================================ - -Problem: --------- - -For multi-host tests multiple physical systems are often required. It is possible to use -two virtual guests for most of autotest tests except for virt-tests -(kvm, libvirt, ...). - -However, It is possible to use Nested Virtualization to serve as first level (L0) -guests and run nested guests inside them. - -This page explains, how to setup (Fedora/RHEL) and use single computer with -nested virtualization for such cases. Be careful that nested virtualization -works usually right, but there are cases where it might lead to hidden problems. -Do not use nested virtualization for production testing. - -Nested Virtualization: ----------------------- - -1. **Emulated:** - * **qemu** very slow - -2. **hardware accelerated:** - * **Hardware for the accelerated nested virtualization** - - AMD Phenom and never core extension (smv, NPT) - Intel Nehalem and never core extension (vmx, EPT) - * **Software which supports the accelerated nested virtualization** - - kvm, xen, vmware, .... - almost the same speed like native guest (1.0-0.1 of native quest performance). Performance - depends on the type of load. IO load could be quite slow. Without vt-d or AMD-Vi and network - device pass through. - -.. _nested_virt: - -Configuration for multi-host virt tests: ----------------------------------------- - -.. figure:: VirtualEnvMultihost/nested-virt.png - -### Config of host system - -* Intel CPU - - `options kvm_intel nested=1` to the end of some modules config file /etc/modprobe.d/modules.conf - -* AMD CPU - - `options kvm_amd nested=1` to the end of some modules config file /etc/modprobe.d/modules.conf - -### Config of Guest L0 - -* Intel CPU - * **Virtual manager** - `Procesor config->CPU Features->vmx set to require` - * **Native qemu-kvm** - `qemu-kvm -cpu core2duo,+vmx -enable-kvm .....` - -* AMD CPU - * **Virtual manager** - `Procesor config->CPU Features->svm set to require` - * **Native qemu-kvm** - `qemu-kvm -cpu qemu64,+svm -enable-kvm .....` - -### Config of Guest L0 System -Connect to host bridge with guest L0 bridge without DHCP (dhcp collision with host system dhcp). - -1. Destroy libvirt bridge which contain dhcp. -2. Enable network service systemctl enable network.service -3. Add new bridge `virbr0` manually and insert to them L0 network adapter `eth0` which is connected to host bridge - -:: - - #interface connected to host system bridge - vi /etc/sysconfig/network-scripts/ifcfg-eth0 - NM_CONTROLLED="no" - DEVICE="eth0" - ONBOOT="yes" - BRIDGE=virbr0 - - #Bridge has name virbr0 for compatibility with standard autotest settings. - vi /etc/sysconfig/network-scripts/ifcfg-virbr0 - DHCP_HOSTNAME="atest-guest" - NM_CONTROLLED="no" - BOOTPROTO="dhcp" - ONBOOT="yes" - IPV6INIT="no" - DEVICE=virbr0 - TYPE=Bridge - DELAY=0 - -and for sure disable NetworkManager `systemctl disable NetworkManager.service` - -### Check Guest L0 System - -`modprobe kvm-intel` or `modprobe kvm-amd` should work - -Start for multi-host virt tests: --------------------------------- -### Manually from host machine - - cd autotest/client/tests/virt/qemu/ - sudo rm -rf results.*; sudo ../../../../server/autoserv -m guestL0_1,guestL0_2 multi_host.srv - -### From autotest gui - -1. Start autotest frontend RPC or WEB interface https://github.com/autotest/autotest/wiki/SysAdmin -2. Select multi_host test from pull-request https://github.com/autotest/autotest-server-tests/pull/1 - -More details: -------------- - -Set up/configuration, the root directory (of this git repo) also has simple scripts to create L1 and L2 guests. And reference of L1, L2 libvirt files are also added -- https://github.com/kashyapc/nvmx-haswell/blob/master/SETUP-nVMX.rst \ No newline at end of file diff --git a/documentation/source/advanced/VirtualEnvMultihost/nested-virt.png b/documentation/source/advanced/VirtualEnvMultihost/nested-virt.png deleted file mode 100644 index 65b23cfe75..0000000000 Binary files a/documentation/source/advanced/VirtualEnvMultihost/nested-virt.png and /dev/null differ diff --git a/documentation/source/advanced/cartesian/CartesianConfigParametersIntro.rst b/documentation/source/advanced/cartesian/CartesianConfigParametersIntro.rst deleted file mode 100644 index 05eed198e4..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigParametersIntro.rst +++ /dev/null @@ -1,473 +0,0 @@ -========== -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. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-bridge.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-bridge.rst deleted file mode 100644 index 91df0a91c0..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-bridge.rst +++ /dev/null @@ -1,39 +0,0 @@ - -bridge -====== - -Description ------------ - -Sets the name of the bridge to which a VM nic will be added to. This -only applies to scenarios where 'nic\_mode' is set to 'tap'. - -It can be set as a default to all nics: - -:: - - bridge = virbr0 - -Or to a specific nic, by prefixing the parameter key with the nic name, -that is for attaching 'nic1' to bridge 'virbr1': - -:: - - bridge_nic1 = virbr1 - -Defined On ----------- - -- `client/tests/kvm/tests\_base.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ -- `client/virt/virt\_utils.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-cd_format.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-cd_format.rst deleted file mode 100644 index a73a0e33b7..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-cd_format.rst +++ /dev/null @@ -1,42 +0,0 @@ - -cd\_format -========== - -Description ------------ - -Sets the format for a given cdrom drive. This directive exists to do -some special magic for cd drive formats 'ahci' and 'usb2' (see -`client/virt/kvm\_vm.py `_ -for more information). - -Currently used options in virt-test are: ahci and usb2. - -Example: - -:: - - variants: - - usb.cdrom: - cd_format = usb2 - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See also --------- - -- `drive\_format `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-cdroms.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-cdroms.rst deleted file mode 100644 index ed2151f7da..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-cdroms.rst +++ /dev/null @@ -1,52 +0,0 @@ - -cdroms -====== - -Description ------------ - -Sets the list of cdrom devices that a VM will have. - -Usually a VM will start with a single cdrom, named 'cd1'. - -:: - - cdroms = cd1 - -But a VM can have other cdroms such as 'unattended' for unattended -installs: - -:: - - variants: - - @Linux: - unattended_install: - cdroms += " unattended" - -And 'winutils' for Microsoft Windows VMs: - -:: - - variants: - - @Windows: - unattended_install.cdrom, whql.support_vm_install: - cdroms += " winutils" - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/guest-os.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ -- `client/tests/kvm/virtio-win.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-check_image.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-check_image.rst deleted file mode 100644 index 631bfa78e3..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-check_image.rst +++ /dev/null @@ -1,46 +0,0 @@ - -check\_image -============ - -Description ------------ - -Configures if we want to run a check on the image files during post -processing. A check usually means running 'qemu-img info' and 'qemu-img -check'. - -This is currently only enabled when `image\_format `_ -is set to 'qcow2'. - -:: - - variants: - - @qcow2: - image_format = qcow2 - check_image = yes - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `images `_ -- `image\_name `_ -- `image\_format `_ -- `create\_image `_ -- `remove\_image `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-convert_ppm_files_to_png.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-convert_ppm_files_to_png.rst deleted file mode 100644 index 59132368ad..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-convert_ppm_files_to_png.rst +++ /dev/null @@ -1,43 +0,0 @@ - -convert\_ppm\_files\_to\_png -============================ - -Description ------------ - -Configures whether files generated from screenshots in `PPM -format `_ should be -automatically converted to -`PNG `_ files. - -:: - - convert_ppm_files_to_png = yes - -Usually we're only interested in spending time converting files for -easier viewing on situations with failures: - -:: - - convert_ppm_files_to_png_on_error = yes - -Defined On ----------- - -The stock configuration key (without suffix) is not currently defined on -any sample cartesian configuration file. - -The configuration key with the 'on\_error' suffix is defined on: - -- `client/tests/kvm/base.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-create_image.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-create_image.rst deleted file mode 100644 index 6d385a1207..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-create_image.rst +++ /dev/null @@ -1,44 +0,0 @@ - -create\_image -============= - -Description ------------ - -Configures if we want to create an image file during pre processing, if -it does **not** already exists. To force the creation of the image file -even if it already exists, use -`force\_create\_image `_. - -To create an image file if it does **not** already exists: - -:: - - create_image = yes - -Defined On ----------- - -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/tests/kvm/tests/qemu\_img.py `_ -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `images `_ -- `image\_name `_ -- `image\_format `_ -- `create\_image `_ -- `force\_create\_image `_ -- `remove\_image `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-display.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-display.rst deleted file mode 100644 index 9f4854c495..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-display.rst +++ /dev/null @@ -1,55 +0,0 @@ - -display -======= - -Description ------------ - -Sets the VM display type. Of course, only one display type is allowed, -and current valid options are: vnc, sdl, spice and nographic. - -:: - - display = vnc - -For VNC displays, the port number is dynamically allocated within the -5900 - 6100 range. - -:: - - display = sdl - -An SDL display does not use a port, but simply behaves as an X client. -If you want to send the SDL display to a different X Server, see -x11\_display? - -:: - - display = spice - -For spice displays, the port number is dynamically allocated within the -8000 - 8100 range. - -:: - - display = nographic - -nographic for qemu/kvm means that the VM will have no graphical display -and that serial I/Os will be redirected to console. - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/unittests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_cache.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_cache.rst deleted file mode 100644 index 77354203e3..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_cache.rst +++ /dev/null @@ -1,38 +0,0 @@ - -drive\_cache -============ - -Description ------------ - -Sets the caching mode a given drive. Currently the valid values are: -writethrough, writeback, none and unsafe. - -Example: - -:: - - drive_cache = writeback - -This option can also be set specifically to a drive: - -:: - - drive_cache_cd1 = none - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_format.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_format.rst deleted file mode 100644 index 0305be39f0..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_format.rst +++ /dev/null @@ -1,43 +0,0 @@ - -drive\_format -============= - -Description ------------ - -Sets the format for a given drive. - -Usually this passed directly to qemu 'if' sub-option of '-drive' command -line option. But in some special cases, such as when drive\_format is -set to 'ahci' or 'usb2', some special magic happens (see -`client/virt/kvm\_vm.py `_ -for more information). - -Currently available options in qemu include: ide, scsi, sd, mtd, floppy, -pflash, virtio. - -Currently used options in virt-test are: ide, scsi, virtio, ahci, -usb2. - -Example: - -:: - - drive_format = ide - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_index.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_index.rst deleted file mode 100644 index 373bc17066..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_index.rst +++ /dev/null @@ -1,38 +0,0 @@ - -drive\_index -============ - -Description ------------ - -Sets the index, that is, ordering precedence of a given drive. Valid -values are integers starting with 0. - -Example: - -:: - - drive_index_image1 = 0 - drive_index_cd1 = 1 - -This will make the drive that has 'image1' appear before the drive that -has 'cd1'. - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/guest-os.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ -- `client/tests/kvm/virtio-win.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_serial.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_serial.rst deleted file mode 100644 index ec71264727..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_serial.rst +++ /dev/null @@ -1,25 +0,0 @@ - -drive\_serial -============= - -Description ------------ - -Sets the serial number to assign to the drive device. - -Defined On ----------- - -This configuration key is not currently defined on any sample cartesian -configuration file. - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_werror.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_werror.rst deleted file mode 100644 index eb18fe817e..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-drive_werror.rst +++ /dev/null @@ -1,34 +0,0 @@ - -drive\_werror -============= - -Description ------------ - -Sets the behavior for the VM when a drive encounters a read or write -error. This is passed to QEMU 'werror' sub-option of the '-drive' -command line option. - -Valid for QEMU are: ignore, stop, report, enospc. - -Example: - -:: - - drive_werror = stop - -Defined On ----------- - -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-file_transfer_client.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-file_transfer_client.rst deleted file mode 100644 index 1fda20211e..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-file_transfer_client.rst +++ /dev/null @@ -1,50 +0,0 @@ - -file\_transfer\_client -====================== - -Description ------------ - -Sets the kind of application, thus protocol, that will be spoken when -transfering files to and from the guest. - -virt-test currently allows for two options: 'scp' or 'rss'. - -For Linux VMs, we default to SSH: - -:: - - variants: - - @Linux: - file_transfer_client = scp - -And for Microsoft Windows VMs we default to rss: - -:: - - variants: - - @Windows: - file_transfer_client = rss - -Defined On ----------- - -- `client/tests/kvm/guest-os.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `redirs `_ -- `file\_transfer\_port `_ -- `guest\_port\_file\_transfer `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-file_transfer_port.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-file_transfer_port.rst deleted file mode 100644 index e912ec132a..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-file_transfer_port.rst +++ /dev/null @@ -1,51 +0,0 @@ - -file\_transfer\_port -==================== - -Description ------------ - -Sets the port on which the application used to transfer files to and -from the guest will be listening on. - -When `file\_transfer\_client `_ is scp, this -is by default 22: - -:: - - variants: - - @Linux: - file_transfer_client = scp - file_transfer_port = 22 - -And for rss, the default is port 10023: - -:: - - variants: - - @Windows: - file_transfer_client = rss - file_transfer_port = 10023: - -Defined On ----------- - -- `client/tests/kvm/guest-os.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `redirs `_ -- `file\_transfer\_client `_ -- `guest\_port\_file\_transfer `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-force_create_image.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-force_create_image.rst deleted file mode 100644 index e973ad6d75..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-force_create_image.rst +++ /dev/null @@ -1,42 +0,0 @@ - -force\_create\_image -==================== - -Description ------------ - -Configures if we want to create an image file during pre processing, -**even if it already exists**. To create an image file only if it **does -not** exist, use `create\_image `_ instead. - -To create an image file **even if it already exists**: - -:: - - force_create_image = yes - -Defined On ----------- - -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `images `_ -- `image\_name `_ -- `image\_format `_ -- `create\_image `_ -- `check\_image `_ -- `remove\_image `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port.rst deleted file mode 100644 index 353a1a079a..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port.rst +++ /dev/null @@ -1,33 +0,0 @@ - -guest\_port -=========== - -Description ------------ - -guest\_port is not a configuration item itself, but the basis (prefix) -of other real configuration items such as: - -- `guest\_port\_remote\_shell `_ -- `guest\_port\_file\_transfer `_ -- `guest\_port\_unattended\_install `_ - -Defined On ----------- - -Variations of guest\_port are defined on the following files: - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/guest-os.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See also --------- - -- `redirs `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port_file_transfer.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port_file_transfer.rst deleted file mode 100644 index c97128a66d..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port_file_transfer.rst +++ /dev/null @@ -1,58 +0,0 @@ - -guest\_port\_file\_tranfer -========================== - -Description ------------ - -Sets the port of the server application running inside guests that will -be used for transferring files to and from this guest. - -On Linux VMs, the `file\_transfer\_client `_ -is set by default to 'scp', and this the port is set by default to the -standard SSH port (22). - -For Windows guests, the -`file\_transfer\_client `_ is set by default -to 'rss', and the port is set by default to 10023. - -This is a specialization of the `guest\_port `_ -configuration entry. - -Example, default entry: - -:: - - guest_port_file_transfer = 22 - -Overridden on Windows variants: - -:: - - variants: - - @Windows: - guest_port_file_transfer = 10023 - -Defined On ----------- - -- `client/tests/kvm/guest-os.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ -- `client/virt/virt\_utils.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `redirs `_ -- `file\_transfer\_port `_ -- `file\_transfer\_client `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port_remote_shell.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port_remote_shell.rst deleted file mode 100644 index 7d970b63e7..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port_remote_shell.rst +++ /dev/null @@ -1,51 +0,0 @@ - -guest\_port\_remote\_shell -========================== - -Description ------------ - -Sets the port of the remote shell server that runs inside guests. On -Linux VMs, this is the set by default to the standard SSH port (22), and -for Windows guests, set by default to port 10022. - -This is a specialization of the `guest\_port `_ -configuration entry. - -Example, default entry: - -:: - - guest_port_remote_shell = 22 - -Overridden on Windows variants: - -:: - - variants: - - @Windows: - guest_port_remote_shell = 10022 - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/guest-os.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ -- `client/virt/virt\_utils.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `redirs `_ -- shell\_port? - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port_unattended_install.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port_unattended_install.rst deleted file mode 100644 index 21e8f89ac0..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-guest_port_unattended_install.rst +++ /dev/null @@ -1,53 +0,0 @@ - -guest\_port\_unattended\_install -================================ - -Description ------------ - -Sets the port of the helper application/script running inside guests -that will be used for flagging the end of the unattended install. - -Both on Linux and Windows VMs, the default value is 12323: - -:: - - guest_port_unattended_install = 12323 - -This must match with the port number on unattended install files. On -Linux VMs, this is hardcoded on kickstart files '%post' section: - -:: - - %post --interpreter /usr/bin/python - ... - server = socket.socket(socket.AF_INET, socket.SOCK_STREAM) - server.bind(('', 12323)) - server.listen(1) - (client, addr) = server.accept() - client.send("done") - client.close() - -This is a specialization of the `guest\_port `_ -configuration entry. - -Defined On ----------- - -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/tests/kvm/tests/unattended\_install.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `redirs `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_format.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_format.rst deleted file mode 100644 index dc602e7d59..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_format.rst +++ /dev/null @@ -1,57 +0,0 @@ - -image\_format -============= - -Description ------------ - -Sets the format of the backing image file for a given drive. - -The value of this configuration key is usually passed verbatim to image -creation commands. It's worth noticing that QEMU has support for many -formats, while virt-test currently plays really well only with -**qcow2** and **raw**. - -You can also use **vmdk**, but it's considered 'not supported', at least -on image conversion tests. - -To set the default image format: - -:: - - image_format = qcow2 - -To set the image format for another image: - -:: - - # Tests - variants: - - block_hotplug: install setup image_copy unattended_install.cdrom - images += " stg" - image_format_stg = raw - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_vm.py `_ -- `client/tests/kvm/tests/qemu\_img.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `images `_ -- `image\_name `_ -- `image\_size `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_name.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_name.rst deleted file mode 100644 index 9adeae14e4..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_name.rst +++ /dev/null @@ -1,71 +0,0 @@ - -image\_name -=========== - -Description ------------ - -Sets the name of an image file. - -If the image file is not a block device (see -`image\_raw\_device `_) the actual file created -will be named accordingly (together with the extension, according to -`image\_format `_). - -When this configuration key is used without a suffix, it's setting the -name of all images without a specific name. The net effect is that it -sets the name of the 'default' image. Example: - -:: - - # Guests - variants: - - @Linux: - variants: - - Fedora: - variants: - - 15.64: - image_name = f15-64 - -This example means that when a Fedora 15 64 bits is installed, and has a -backing image file created, it's going to be named starting with -'f15-64'. If the `image\_format `_ specified is -'qcow2', then the complete filename will be 'f15-64.qcow2'. - -When this configuration key is used with a suffix, it sets the name of a -specific image. Example: - -:: - - # Tests - variants: - - block_hotplug: install setup image_copy unattended_install.cdrom - images += " stg" - image_name_stg = storage - -Defined On ----------- - -- `client/tests/kvm/guest-os.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ -- `client/tests/kvm/tests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ -- `client/tests/kvm/tests/qemu\_img.py `_ - -Referenced By -------------- - -- `How to run virt-test tests on an existing guest - image? <../../RunTestsExistingGuest>`_ - -See Also --------- - -- `images `_ -- `image\_format `_ -- `image\_raw\_device `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_raw_device.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_raw_device.rst deleted file mode 100644 index e7ead5004e..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_raw_device.rst +++ /dev/null @@ -1,42 +0,0 @@ - -image\_raw\_device -================== - -Description ------------ - -Flags whether the backing image for a given drive is a block device -instead of a regular file. - -By default we assume all images are backed by files: - -:: - - image_raw_device = no - -But suppose you define a new variant, for another guest, that will have -a disk backed by a block device (say, an LVM volume): - -:: - - CustomGuestLinux: - image_name = /dev/vg/linux_guest - image_raw_device = yes - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/tests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -- `How to run virt-test tests on an existing guest - image? <../../RunTestsExistingGuest>`_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_size.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_size.rst deleted file mode 100644 index 7f1ad7b301..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-image_size.rst +++ /dev/null @@ -1,56 +0,0 @@ - -image\_size -=========== - -Description ------------ - -Sets the size of image files. This applies to images creation and also -validation tests (when checking that a image was properly created -according to what was requested). - -By default the image size is set to 10G: - -:: - - image_size = 10G - -But a VM can have other drives, backed by other image files (or block -devices), with different sizes: - -:: - - # Tests - variants: - - block_hotplug: install setup image_copy unattended_install.cdrom - images += " stg" - boot_drive_stg = no - image_name_stg = storage - image_size_stg = 1G - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/guest-os.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ -- `client/tests/kvm/tests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ -- `client/tests/kvm/tests/qemu\_img.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `images `_ -- `image\_name `_ -- `image\_format `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-images.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-images.rst deleted file mode 100644 index daeea4cf17..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-images.rst +++ /dev/null @@ -1,48 +0,0 @@ - -images -====== - -Description ------------ - -Sets the list of disk devices (backed by a image file or device) that a -VM will have. - -Usually a VM will start with a single image, named image1: - -:: - - images = image1 - -But a VM can have other images. One example is when we test the maximum -number of disk devices supported on a VM: - -:: - - # Tests - variants: - - multi_disk: install setup image_copy unattended_install.cdrom - variants: - - max_disk: - images += " stg stg2 stg3 stg4 stg5 stg6 stg7 stg8 stg9 stg10 stg11 stg12 stg13 stg14 stg15 stg16 stg17 stg18 stg19 stg20 stg21 stg22 stg23" - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/guest-os.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ -- `virt\_env\_process.py `_ -- `client/tests/kvm/tests/enospc.py `_ -- `client/tests/kvm/tests/image\_copy.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-images_good.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-images_good.rst deleted file mode 100644 index 55101b7f0b..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-images_good.rst +++ /dev/null @@ -1,35 +0,0 @@ - -images\_good -============ - -Description ------------ - -Sets the URI of a NFS server that hosts "good" (think "golden") images, -that will be copied to the local system prior to running other tests. - -The act of copying of "good" images is an alternative to installing a VM -from scratch before running other tests. - -The default value is actually an invalid value that must be changed if -you intend to use this feature: - -:: - - images_good = 0.0.0.0:/autotest/images_good - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ - -Used By -------- - -- `client/virt/tests/image\_copy.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-keep_ppm_files.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-keep_ppm_files.rst deleted file mode 100644 index 86e763cf03..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-keep_ppm_files.rst +++ /dev/null @@ -1,43 +0,0 @@ - -keep\_ppm\_files -================ - -Description ------------ - -Configures whether should we keep the original screedump files in -`PPM `_ format when -converting them to -`PNG `_, according to -`convert\_ppm\_files\_to\_png `_ - -To keep the PPM files: - -:: - - keep_ppm_files = yes - -To keep the PPM files only on situations with failures: - -:: - - keep_ppm_files_on_error = yes - -Defined On ----------- - -This configuration key is not currently defined on any sample cartesian -configuration file, but a sample (commented out) appears on: - -- `client/tests/kvm/base.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-keep_screendumps.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-keep_screendumps.rst deleted file mode 100644 index 990b352633..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-keep_screendumps.rst +++ /dev/null @@ -1,43 +0,0 @@ - -keep\_screendumps -================= - -Description ------------ - -Flags whether screendumps (screenshots of the VM console) should be kept -or delete during post processing. - -To keep the screendumps: - -:: - - keep_screendumps = yes - -Usually we're only interested in keeping screendumps on situations with -failures, to ease the debugging: - -:: - - keep_screendumps_on_error = yes - -Defined On ----------- - -The stock configuration key (without suffix) is not currently defined on -any sample cartesian configuration file. - -The configuration key with the 'on\_error' suffix is defined on: - -- `client/tests/kvm/base.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_unresponsive_vms.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_unresponsive_vms.rst deleted file mode 100644 index 009338b0a2..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_unresponsive_vms.rst +++ /dev/null @@ -1,40 +0,0 @@ - -kill\_unresponsive\_vms -======================= - -Description ------------ - -Configures whether VMs that are running, but do not have a responsive -session (for example via SSH), should be destroyed (of course, not -`gracefully `_) during post processing. - -This behavior is enabled by default. To turn it off and leave -unresponsive VMs lying around (usually **not** recommended): - -:: - - kill_unresponsive_vms = no - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See also --------- - -- `kill\_vm `_ -- `kill\_vm\_timeout `_ -- `kill\_vm\_gracefully `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_vm.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_vm.rst deleted file mode 100644 index cc8cc3ffff..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_vm.rst +++ /dev/null @@ -1,43 +0,0 @@ - -kill\_vm -======== - -Description ------------ - -Configures whether a VM should be shutdown during post processing. How -exactly the VM will be shutdown is configured by other parameters such -as `kill\_vm\_gracefully `_ and -`kill\_vm\_timeout `_. - -To force shutdown during post processing: - -:: - - kill_vm = yes - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/guest-os.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ -- `client/tests/kvm/unittests.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See also --------- - -- `kill\_vm\_timeout `_ -- `kill\_vm\_gracefully `_ -- `kill\_unresponsive\_vms `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_vm_gracefully.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_vm_gracefully.rst deleted file mode 100644 index 5adb655078..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_vm_gracefully.rst +++ /dev/null @@ -1,46 +0,0 @@ - -kill\_vm\_gracefully -==================== - -Description ------------ - -Flags whether a graceful shutdown command should be sent to the VM guest -OS before attempting to either halt the VM at the hypervisor side -(sending an appropriate command to QEMU or even killing its process). - -Of course, this is only valid when `kill\_vm `_ is set to -'yes'. - -To force killing VMs without using a graceful shutdown command (such as -'shutdown -h now'): - -:: - - kill_vm_gracefully = no - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/guest-os.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ -- `client/tests/kvm/unittests.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See also --------- - -- `kill\_vm `_ -- `kill\_vm\_timeout `_ -- `kill\_unresponsive\_vms `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_vm_timeout.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_vm_timeout.rst deleted file mode 100644 index 4d9d673e8f..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-kill_vm_timeout.rst +++ /dev/null @@ -1,42 +0,0 @@ - -kill\_vm\_timeout -================= - -Description ------------ - -Configures the amount of time, in seconds, to wait for VM shutdown -during the post processing. - -This is only relevant if `kill\_vm `_ is actually set to -'yes'. - -To set the timeout to one minute: - -:: - - kill_vm_timeout = 60 - -Defined On ----------- - -- `client/tests/kvm/guest-os.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See also --------- - -- `kill\_vm `_ -- `kill\_vm\_gracefully `_ -- `kill\_unresponsive\_vms `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-login_timeout.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-login_timeout.rst deleted file mode 100644 index 811640d58b..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-login_timeout.rst +++ /dev/null @@ -1,90 +0,0 @@ - -login\_timeout -============== - -Description ------------ - -Sets the amount of time, in seconds, to wait for a session -(SSH/Telnet/Netcat) with the VM. - -To set the timeout to 6 minutes: - -:: - - login_timeout = 360 - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/tests/autotest.py `_ -- `client/virt/tests/boot.py `_ -- `client/virt/tests/clock\_getres.py `_ -- `client/virt/tests/ethtool.py `_ -- `client/virt/tests/file\_transfer.py `_ -- `client/virt/tests/fillup\_disk.py `_ -- `client/virt/tests/guest\_s4.py `_ -- `client/virt/tests/guest\_test.py `_ -- `client/virt/tests/iofuzz.py `_ -- `client/virt/tests/ioquit.py `_ -- `client/virt/tests/iozone\_windows.py `_ -- `client/virt/tests/jumbo.py `_ -- `client/virt/tests/kdump.py `_ -- `client/virt/tests/linux\_s3.py `_ -- `client/virt/tests/lvm.py `_ -- `client/virt/tests/mac\_change.py `_ -- `client/virt/tests/multicast.py `_ -- `client/virt/tests/netperf.py `_ -- `client/virt/tests/nicdriver\_unload.py `_ -- `client/virt/tests/nic\_promisc.py `_ -- `client/virt/tests/ping.py `_ -- `client/virt/tests/shutdown.py `_ -- `client/virt/tests/softlockup.py `_ -- `client/virt/tests/stress\_boot.py `_ -- `client/virt/tests/vlan.py `_ -- `client/virt/tests/watchdog.py `_ -- `client/virt/tests/whql\_client\_install.py `_ -- `client/virt/tests/whql\_submission.py `_ -- `client/virt/tests/yum\_update.py `_ -- `client/tests/kvm/tests/balloon\_check.py `_ -- `client/tests/kvm/tests/cdrom.py `_ -- `client/tests/kvm/tests/cpu\_hotplug.py `_ -- `client/tests/kvm/tests/enospc.py `_ -- `client/tests/kvm/tests/floppy.py `_ -- `client/tests/kvm/tests/hdparm.py `_ -- `client/tests/kvm/tests/migration\_multi\_host.py `_ -- `client/tests/kvm/tests/migration.py `_ -- `client/tests/kvm/tests/migration\_with\_file\_transfer.py `_ -- `client/tests/kvm/tests/migration\_with\_reboot.py `_ -- `client/tests/kvm/tests/multi\_disk.py `_ -- `client/tests/kvm/tests/nic\_bonding.py `_ -- `client/tests/kvm/tests/nic\_hotplug.py `_ -- `client/tests/kvm/tests/nmi\_watchdog.py `_ -- `client/tests/kvm/tests/pci\_hotplug.py `_ -- `client/tests/kvm/tests/physical\_resources\_check.py `_ -- `client/tests/kvm/tests/qemu\_img.py `_ -- `client/tests/kvm/tests/set\_link.py `_ -- `client/tests/kvm/tests/smbios\_table.py `_ -- `client/tests/kvm/tests/stop\_continue.py `_ -- `client/tests/kvm/tests/system\_reset\_bootable.py `_ -- `client/tests/kvm/tests/timedrift.py `_ -- `client/tests/kvm/tests/timedrift\_with\_migration.py `_ -- `client/tests/kvm/tests/timedrift\_with\_reboot.py `_ -- `client/tests/kvm/tests/timedrift\_with\_stop.py `_ -- `client/tests/kvm/tests/trans\_hugepage\_defrag.py `_ -- `client/tests/kvm/tests/trans\_hugepage.py `_ -- `client/tests/kvm/tests/trans\_hugepage\_swapping.py `_ -- `client/tests/kvm/tests/usb.py `_ -- `client/tests/kvm/tests/vmstop.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-main_monitor.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-main_monitor.rst deleted file mode 100644 index 564fc1a6a8..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-main_monitor.rst +++ /dev/null @@ -1,45 +0,0 @@ - -main\_monitor -============= - -Description ------------ - -Sets the default monitor for a VM, meaning that when a test accesses the -**monitor** property of a **VM** class instance, that one monitor will -be returned. - -Usually a VM will have a single monitor, and that will be a regular -Human monitor: - -:: - - main_monitor = humanmonitor1 - -If a **main\_monitor** is not defined, the **monitor** property of a -**VM** class instance will assume that the first monitor set in the -`monitors `_ list is the main monitor. - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/unittests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `monitors `_ -- `monitor\_type `_ -- `client/virt/kvm\_monitor.py `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-main_vm.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-main_vm.rst deleted file mode 100644 index 3b7ce20e3a..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-main_vm.rst +++ /dev/null @@ -1,31 +0,0 @@ - -main\_vm -======== - -Description ------------ - -Sets name of the main VM. - -There's nothing special about this configuration item, except that most -tests will also reference its value when fetching a VM from the -Environment (see class **Env** on file -`client/virt/virt\_utils.py `_). - -The default name of the main VM is **vm1**: - -:: - - main_vm = vm1 - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/unittests.cfg.sample `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-mem.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-mem.rst deleted file mode 100644 index 23fdbd2b95..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-mem.rst +++ /dev/null @@ -1,38 +0,0 @@ - -mem -=== - -Description ------------ - -Sets the amount of memory (in MB) a VM will have. - -The amount of memory a VM will have for most tests is of the main VM is -1024: - -:: - - mem = 1024 - -But for running KVM unittests, we currently set that to 512: - -:: - - mem = 512 - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/unittests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-migration_mode.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-migration_mode.rst deleted file mode 100644 index d71b957c99..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-migration_mode.rst +++ /dev/null @@ -1,35 +0,0 @@ - -migration\_mode -=============== - -Description ------------ - -If migration mode is specified, the VM will be started in incoming mode -for migration. Valid modes for migration are: **tcp**, **unix** and -**exec**. - -To start a VM in incoming mode for receiving migration data via tcp: - -:: - - migration_mode = tcp - -A port will be allocated from the range 5200 to 6000. - -Defined On ----------- - -This configuration item is currently not defined on a sample cartesian -configuration file. - -Used By -------- - -- `client/tests/kvm/migration\_control.srv `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-monitor_type.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-monitor_type.rst deleted file mode 100644 index 19dfdf174f..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-monitor_type.rst +++ /dev/null @@ -1,51 +0,0 @@ - -monitor\_type -============= - -Description ------------ - -Sets the type of the -`monitor `_. -QEMU has two types of monitors: - -- The regular, also known as Human monitor, intended for interaction - with people (but also very much used by other tools, Autotest - inclusive) -- The QMP monitor, a monitor that speaks the - `QMP `_ protocol. - -To set the default monitor type to be a -`QMP `_ monitor: - -:: - - monitor_type = qmp - -To set the type of a specific monitor use: - -:: - - monitor_type_humanmonitor1 = human - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/unittests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `client/virt/kvm\_monitor.py `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-monitors.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-monitors.rst deleted file mode 100644 index 307d862f57..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-monitors.rst +++ /dev/null @@ -1,99 +0,0 @@ - -monitors -======== - -Description ------------ - -Sets the list of -`monitors `_ -that a VM currently has running. See [ QEMU has two types of monitors: - -- The regular, also known as Human monitor, intended for interaction - with people (but also very much used by other tools, Autotest - inclusive) -- The QMP monitor, a monitor that speaks the - `QMP `_ protocol. - -Usually a VM will have a single monitor, and that will be a regular -Human monitor: - -:: - - monitors = humanmonitor1 - main_monitor = humanmonitor1 - monitor_type_humanmonitor1 = human - monitor_type = human - -The monitor type is defined by `monitor\_type `_. - -Here's a more detailed exaplanation of the configuration snippet above: - -:: - - monitors = humanmonitor1 - -The default VM will have only one monitor, named **humanmonitor1**. - -:: - - main_monitor = humanmonitor1 - -The main monitor will also be **humanmonitor1**. When a test has to talk -to a monitor, it usually does so through the main monitor. - -:: - - monitor_type_humanmonitor1 = human - -This configuration sets the specific type of the **humanmonitor1** to be -**human**. - -:: - - monitor_type = human - -And finally this configuration sets the default monitor type also to be -**human**. - -Suppose you define a new monitor for your VMs: - -:: - - monitors += ' monitor2' - -Unless you also define: - -:: - - monitor_type_monitor2 = qmp - -**monitor2** will also be a human monitor. - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/unittests.cfg.sample `_ - -Used By -------- - -- `client/tests/kvm/kvm.py `_ -- `client/virt/kvm\_vm.py `_ -- `client/virt/virt\_test\_utils.py `_ - -Note: most tests that interact with the monitor do so through the -**monitor** property of the **VM** class, and not by evaluating this -parameter value. This is usally only done by the **VM** class. - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `client/virt/kvm\_monitor.py `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-nic_mode.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-nic_mode.rst deleted file mode 100644 index 5aa6823222..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-nic_mode.rst +++ /dev/null @@ -1,50 +0,0 @@ - -nic\_mode -========= - -Description ------------ - -Configures the mode of a Network Interface Card. - -Suitable values for this configuration item are either **user** or -**tap**. - -`User -mode `_ -networking is the default **on QEMU**, but `Tap -mode `_ is the -current default in Autotest: - -:: - - nic_mode = tap - -When **nic\_mode** is set to -`Tap `_ you should -also set a `bridge `_. - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ -- `client/tests/kvm/migration\_control.srv `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ -- `client/tests/kvm/tests/physical\_resources\_check.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `bridge `_ -- `redirs `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-nics.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-nics.rst deleted file mode 100644 index aa6cf12afc..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-nics.rst +++ /dev/null @@ -1,46 +0,0 @@ - -nics -==== - -Description ------------ - -Sets the list of network interface cards that a VM will have. - -Usually a VM will start with a single nic, named nic1: - -:: - - nics = nic1 - -But a VM can have other nics. Some tests (usually network related) add -other nics. One obvious example is the -`bonding `_ -test: - -:: - - # Tests - variants: - - nic_bonding: install setup image_copy unattended_install.cdrom - nics += ' nic2 nic3 nic4' - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_vm.py `_ -- `client/virt/kvm\_vm.py `_ -- `client/tests/kvm/tests/nic\_bonding.py `_ -- `client/tests/kvm/tests/physical\_resources\_check.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-post_command.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-post_command.rst deleted file mode 100644 index 910ec9347f..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-post_command.rst +++ /dev/null @@ -1,36 +0,0 @@ - -post\_command -============= - -Description ------------ - -Configures a command to be executed during post processing. - -The pre processing code will execute the given command, waiting for an -amount of `time `_ and failing the test -unless the command is considered -`noncritical `_. - -Defined On ----------- - -This configuration key is not currently defined on any sample cartesian -configuration file in its stock format. - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `post\_command\_timeout `_ -- post\_command\_non\_critical? - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-post_command_noncritical.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-post_command_noncritical.rst deleted file mode 100644 index 3d5df33599..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-post_command_noncritical.rst +++ /dev/null @@ -1,33 +0,0 @@ - -post\_command\_noncritical -========================== - -Description ------------ - -Flags if the `command `_ configured to to be executed -during pre processing, is not critical, that is, if an error during its -execution should only logged or fail the test. - -Defined On ----------- - -This configuration key is not currently defined on any sample cartesian -configuration file in its stock format. - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `post\_command `_ -- `post\_command\_timeout `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-post_command_timeout.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-post_command_timeout.rst deleted file mode 100644 index f4b78b1805..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-post_command_timeout.rst +++ /dev/null @@ -1,32 +0,0 @@ - -post\_command\_timeout -====================== - -Description ------------ - -Configures the amount of time to wait while executing a -`command `_ during post processing. - -Defined On ----------- - -This configuration key is not currently defined on any sample cartesian -configuration file in its stock format. - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `post\_command `_ -- post\_command\_non\_critical? - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-pre_command.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-pre_command.rst deleted file mode 100644 index f171b64e2c..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-pre_command.rst +++ /dev/null @@ -1,35 +0,0 @@ - -pre\_command -============ - -Description ------------ - -Configures a command to be executed during pre processing. - -The pre processing code will execute the given command, waiting for an -amount of `time `_ and failing the test unless -the command is considered `noncritical `_. - -Defined On ----------- - -This configuration key is not currently defined on any sample cartesian -configuration file in its stock format. - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `pre\_command\_timeout `_ -- pre\_command\_non\_critical? - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-pre_command_noncritical.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-pre_command_noncritical.rst deleted file mode 100644 index 83a10309b4..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-pre_command_noncritical.rst +++ /dev/null @@ -1,33 +0,0 @@ - -pre\_command\_noncritical -========================= - -Description ------------ - -Flags if the `command `_ configured to to be executed -during pre processing, is not critical, that is, if an error during its -execution should only logged or fail the test. - -Defined On ----------- - -This configuration key is not currently defined on any sample cartesian -configuration file in its stock format. - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `pre\_command `_ -- `pre\_command\_timeout `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-pre_command_timeout.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-pre_command_timeout.rst deleted file mode 100644 index cca24ac096..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-pre_command_timeout.rst +++ /dev/null @@ -1,32 +0,0 @@ - -pre\_command\_timeout -===================== - -Description ------------ - -Configures the amount of time to wait while executing a -`command `_ during pre processing. - -Defined On ----------- - -This configuration key is not currently defined on any sample cartesian -configuration file in its stock format. - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `pre\_command `_ -- pre\_command\_non\_critical? - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-profilers.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-profilers.rst deleted file mode 100644 index f86bee7456..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-profilers.rst +++ /dev/null @@ -1,41 +0,0 @@ - -profilers -========= - -Description ------------ - -Sets the list of Autotest profilers to be enabled during the test run -(they're removed from the job's list of profilers when the test -finishes). - -This is commonly used to enable the -`kvm\_stat `_ -profiler: - -:: - - profilers = kvm_stat - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/subtests.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_utils.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `Setting up profiling on virt-test <../../Profiling>`_ -- `Using and developing job profilers <../../../AddingProfiler>`_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qemu_binary.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qemu_binary.rst deleted file mode 100644 index 2fdef73937..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qemu_binary.rst +++ /dev/null @@ -1,44 +0,0 @@ - -qemu\_binary -============ - -Description ------------ - -Sets either the name or full path for the QEMU binary. - -By default this is as simple as possible: - -:: - - qemu_binary = qemu - -But while testing the qemu-kvm userspace, one could use: - -:: - - qemu_binary = /usr/bin/qemu-kvm - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/tests.cfg.sample `_ -- `client/tests/kvm/unittests.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `qemu\_img\_binary `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qemu_img_binary.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qemu_img_binary.rst deleted file mode 100644 index b2274ac026..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qemu_img_binary.rst +++ /dev/null @@ -1,38 +0,0 @@ - -qemu\_img\_binary -================= - -Description ------------ - -Sets either the name or full path for the **qemu-img** binary. - -By default this is as simple as possible: - -:: - - qemu_img_binary = qemu-img - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ -- `client/tests/kvm/tests.cfg.sample `_ -- `client/tests/kvm/unittests.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_vm.py `_ -- `client/tests/kvm/tests/qemu\_img.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `qemu\_binary `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qxl.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qxl.rst deleted file mode 100644 index 9cc25f0777..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qxl.rst +++ /dev/null @@ -1,40 +0,0 @@ - -qxl -=== - -Description ------------ - -Flags if the -`VGA `_ -device should be an of type **qxl**. - -The default configuration enables a **qxl** VGA: - -:: - - qxl = on - -Note that if vga? is also set, **qxl** takes precedence over it. - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `qxl\_dev\_nr `_ -- vga? - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qxl_dev_nr.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qxl_dev_nr.rst deleted file mode 100644 index 99d0743147..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-qxl_dev_nr.rst +++ /dev/null @@ -1,53 +0,0 @@ - -qxl\_dev\_nr -============ - -Description ------------ - -Sets the number of display devices available through -`SPICE `_. This is only valid when -`qxl `_ is set. - -The default configuration enables a single display device: - -:: - - qxl_dev_nr = 1 - -Note that due to a limitation in the current Autotest code (see -`client/virt/kvm\_vm.py `_) -this setting is only applied when the QEMU syntax is: - -:: - - # qemu -qxl 2 - -and not applied when the syntax is: - -:: - - # qemu -vga qxl - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `qxl `_ -- vga? -- `display `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-redirs.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-redirs.rst deleted file mode 100644 index 4a6c21b533..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-redirs.rst +++ /dev/null @@ -1,42 +0,0 @@ - -redirs -====== - -Description ------------ - -Sets the network redirections between host and guest. These are only -used and necessary when using 'user' mode network. - -Example: - -:: - - redirs = remote_shell - guest_port_remote_shell = 22 - -A port will be allocated on the host, usually within the range -5000-6000, and all traffic to/from this port will be redirect to guest's -port 22. - -Defined On ----------- - -- `client/tests/kvm/tests\_base.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See also --------- - -- `guest\_port `_ -- `guest\_port\_remote\_shell `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-remove_image.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-remove_image.rst deleted file mode 100644 index a08b9c5fa0..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-remove_image.rst +++ /dev/null @@ -1,47 +0,0 @@ - -remove\_image -============= - -Description ------------ - -Configures if we want to remove image files during post processing. - -To keep all images after running tests: - -:: - - remove_image = no - -On a test with multiple transient images, to remove all but the main -image (**image1**), use: - -:: - - remove_image = yes - remove_image_image1 = no - -Defined On ----------- - -- `client/tests/kvm/tests\_base.cfg.sample `_ - -Used By -------- - -- `client/virt/virt\_env\_process.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `images `_ -- `image\_name `_ -- `image\_format `_ -- `create\_image `_ -- `force\_create\_image `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-spice.rst b/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-spice.rst deleted file mode 100644 index 54d7611faa..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference-KVM-spice.rst +++ /dev/null @@ -1,42 +0,0 @@ - -spice -===== - -Description ------------ - -Sets extra arguments to be passed to the QEMU **-spice** command line -argument. - -Note that there's no need to pass a port number, as this will be -automatically allocated from the 8000 - 8100 range. - -By default, the extra arguments disable authentication: - -:: - - spice = disable-ticketing - -Defined On ----------- - -- `client/tests/kvm/base.cfg.sample `_ - -Used By -------- - -- `client/virt/kvm\_vm.py `_ - -Referenced By -------------- - -No other documentation currently references this configuration key. - -See Also --------- - -- `qxl `_ -- `qxl\_dev\_nr `_ -- vga? -- `display `_ - diff --git a/documentation/source/advanced/cartesian/CartesianConfigReference.rst b/documentation/source/advanced/cartesian/CartesianConfigReference.rst deleted file mode 100644 index 35b2bad9d8..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigReference.rst +++ /dev/null @@ -1,62 +0,0 @@ -========================== -Cartesian Config Reference -========================== - -.. toctree:: - :maxdepth: 2 - - - CartesianConfigReference-KVM-bridge - CartesianConfigReference-KVM-cdroms - CartesianConfigReference-KVM-cd_format - CartesianConfigReference-KVM-check_image - CartesianConfigReference-KVM-convert_ppm_files_to_png - CartesianConfigReference-KVM-create_image - CartesianConfigReference-KVM-display - CartesianConfigReference-KVM-drive_cache - CartesianConfigReference-KVM-drive_format - CartesianConfigReference-KVM-drive_index - CartesianConfigReference-KVM-drive_werror - CartesianConfigReference-KVM-drive_serial - CartesianConfigReference-KVM-file_transfer_client - CartesianConfigReference-KVM-file_transfer_port - CartesianConfigReference-KVM-force_create_image - CartesianConfigReference-KVM-guest_port - CartesianConfigReference-KVM-guest_port_remote_shell - CartesianConfigReference-KVM-guest_port_file_transfer - CartesianConfigReference-KVM-guest_port_unattended_install - CartesianConfigReference-KVM-images - CartesianConfigReference-KVM-images_good - CartesianConfigReference-KVM-image_format - CartesianConfigReference-KVM-image_name - CartesianConfigReference-KVM-image_raw_device - CartesianConfigReference-KVM-image_size - CartesianConfigReference-KVM-keep_ppm_files - CartesianConfigReference-KVM-keep_screendumps - CartesianConfigReference-KVM-kill_unresponsive_vms - CartesianConfigReference-KVM-kill_vm - CartesianConfigReference-KVM-kill_vm_gracefully - CartesianConfigReference-KVM-kill_vm_timeout - CartesianConfigReference-KVM-login_timeout - CartesianConfigReference-KVM-main_monitor - CartesianConfigReference-KVM-main_vm - CartesianConfigReference-KVM-mem - CartesianConfigReference-KVM-migration_mode - CartesianConfigReference-KVM-monitors - CartesianConfigReference-KVM-monitor_type - CartesianConfigReference-KVM-nic_mode - CartesianConfigReference-KVM-nics - CartesianConfigReference-KVM-pre_command - CartesianConfigReference-KVM-pre_command_timeout - CartesianConfigReference-KVM-pre_command_noncritical - CartesianConfigReference-KVM-profilers - CartesianConfigReference-KVM-post_command - CartesianConfigReference-KVM-post_command_timeout - CartesianConfigReference-KVM-post_command_noncritical - CartesianConfigReference-KVM-qemu_binary - CartesianConfigReference-KVM-qemu_img_binary - CartesianConfigReference-KVM-qxl_dev_nr - CartesianConfigReference-KVM-qxl - CartesianConfigReference-KVM-redirs - CartesianConfigReference-KVM-remove_image - CartesianConfigReference-KVM-spice diff --git a/documentation/source/advanced/cartesian/CartesianConfigTricks.rst b/documentation/source/advanced/cartesian/CartesianConfigTricks.rst deleted file mode 100644 index 8062eb5ecf..0000000000 --- a/documentation/source/advanced/cartesian/CartesianConfigTricks.rst +++ /dev/null @@ -1,80 +0,0 @@ -======================= -Cartesian Config Tricks -======================= - -Changing test order -=================== - -The Cartesian Config system implemented in virt-test does have some limitations - -for example, the order of tests is dependent on the order on which each variant -is defined on the config files, making executing tests on a different order a -daunting prospect. - -In order to help people with this fairly common use case, we'll demonstrate how -to use some of the cartesian config features to accomplish executing your tests -in the order you need. In this example, we're going to execute the `unix` migration -mode tests before the `tcp` one. In the actual cartesian config file, `tcp` is always -going to be executed before `unix` on a normal virt-test execution. - -Create a custom config ----------------------- - -For the sake of simplicity, we'll create the file under `backends/qemu/cfg/custom.cfg`:: - - $ touch backends/qemu/cfg/custom.cfg - -Then, let's add the following text to it (please keep in mind that our maintainers -are constantly adding new variants to the base virt-test config, so you might need -to tweak the contents to match the current state of the config):: - - include tests-shared.cfg - - variants: - - @custom_base: - only JeOS.20 - only i440fx - only smp2 - only qcow2 - only virtio_net - only virtio_blk - no hugepages - no 9p_export - no gluster - no pf_assignable - no vf_assignable - no rng_random - no rng_egd - variants: - - @custom_1: - only migrate.default.unix - - @custom_2: - only migrate.default.tcp - -There you go. Note that you are not obligated to use `@` at your variant names, it's -just for the sake of not polluting the tag namespace too much. Now, let's test to -see if this config file is generating us just the 2 tests we actually want:: - - $ virttest/cartesian_config.py backends/qemu/cfg/custom.cfg - dict 1: qcow2.virtio_blk.smp2.virtio_net.JeOS.20.x86_64.io-github-autotest-qemu.migrate.unix - dict 2: qcow2.virtio_blk.smp2.virtio_net.JeOS.20.x86_64.io-github-autotest-qemu.migrate.tcp - -There you go. Now, you can simply execute this command line with:: - - ./run -t qemu -c backends/qemu/cfg/custom.cfg - -And then you'll see your tests executed in the correct order:: - - $ ./run -t qemu -c backends/qemu/cfg/custom.cfg - SETUP: PASS (2.31 s) - DATA DIR: /home/user/virt_test - DEBUG LOG: /home/user/Code/virt-test.git/logs/run-2014-12-19-12.12.29/debug.log - TESTS: 2 - (1/2) qcow2.virtio_blk.smp2.virtio_net.JeOS.20.x86_64.io-github-autotest-qemu.migrate.unix: PASS (31.05 s) - (2/2) qcow2.virtio_blk.smp2.virtio_net.JeOS.20.x86_64.io-github-autotest-qemu.migrate.tcp: PASS (22.10 s) - TOTAL TIME: 53.25 s - TESTS PASSED: 2 - TESTS FAILED: 0 - SUCCESS RATE: 100.00 % - -This is the base idea - you can extend and filter variants on a cartesian config set as -much as you'd like, and tailor it to your needs. diff --git a/documentation/source/advanced/cartesian/index.rst b/documentation/source/advanced/cartesian/index.rst deleted file mode 100644 index 95fe068747..0000000000 --- a/documentation/source/advanced/cartesian/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -================ -Cartesian Config -================ - -Reference documentation of the cartesian config format. - -Contents: - -.. toctree:: - :maxdepth: 2 - - CartesianConfigParametersIntro - CartesianConfigReference - CartesianConfigTricks diff --git a/documentation/source/advanced/index.rst b/documentation/source/advanced/index.rst deleted file mode 100644 index 5a2e2fa2a3..0000000000 --- a/documentation/source/advanced/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -============= -Advanced docs -============= - -Dive into fully detailed descriptions of virt test functionality, such as -the cartesian config file structure. - -Contents: - -.. toctree:: - :maxdepth: 2 - - VirtTestDocumentation - BuildingTestApplications - RunTestsExistingGuest - Profiling - Networking - PerformanceTesting - VirtualEnvMultihost - MultiHostMigration - cartesian/index diff --git a/documentation/source/api/.gitignore b/documentation/source/api/.gitignore deleted file mode 100644 index 30d85567b5..0000000000 --- a/documentation/source/api/.gitignore +++ /dev/null @@ -1 +0,0 @@ -*.rst diff --git a/documentation/source/basic/DefiningNewGuests.rst b/documentation/source/basic/DefiningNewGuests.rst deleted file mode 100644 index f1e2f8a140..0000000000 --- a/documentation/source/basic/DefiningNewGuests.rst +++ /dev/null @@ -1,103 +0,0 @@ -Defining New Guests -=================== - -Let's say you have a guest image that you've carefully prepared, and the JeOS -just doesn't cut it. Here's how you add new guests: - -Linux Based Custom Guest ------------------------- - -If your guest is Linux based, you can add a config file snippet describing -your test (We have a bunch of pre-set values for linux in the default config). - -The drop in directory is - -:: - - shared/cfg/guest-os/Linux/LinuxCustom - -You can add, say, foo.cfg to that dir with the content: - -:: - - FooLinux: - image_name = images/foo-linux - -Which would make it possible to specify this custom guest using - -:: - - ./run -t qemu -g LinuxCustom.FooLinux - -Provided that you have a file called images/foo-linux.qcow2, if using the -qcow2 format image. If you wish to provide a raw image file, you must use - -:: - - ./run -t qemu -g LinuxCustom.FooLinux --image-type raw - - -Other useful params to set (not an exaustive list): - -:: - - # shell_prompt is a regexp used to match the prompt on aexpect. - # if your custom os is based of some distro listed in the guest-os - # dir, you can look on the files and just copy shell_prompt - shell_prompt = [*]$ - # If you plan to use a raw device, set image_device = yes - image_raw_device = yes - # Password of your image - password = 123456 - # Shell client used (may be telnet or ssh) - shell_client = ssh - # Port were the shell client is running - shell_port = 22 - # File transfer client - file_transfer_client = scp - # File transfer port - file_transfer_port = 22 - -Windows Based Custom Guest --------------------------- - -If your guest is Linux based, you can add a config file snippet describing -your test (We have a bunch of pre-set values for linux in the default config). - -The drop in directory is - -:: - - shared/cfg/guest-os/Windows/WindowsCustom - -You can add, say, foo.cfg to that dir with the content: - -:: - - FooWindows: - image_name = images/foo-windows - -Which would make it possible to specify this custom guest using - -:: - - ./run -t qemu -g WindowsCustom.FooWindows - -Provided that you have a file called images/foo-windows.qcow2, if using the -qcow2 format image. If you wish to provide a raw image file, you must use - -:: - - ./run -t qemu -g WindowsCustom.FooWindows --image-type raw - -Other useful params to set (not an exaustive list): - -:: - - # If you plan to use a raw device, set image_device = yes - image_raw_device = yes - # Attention: Changing the password in this file is not supported, - # since files in winutils.iso use it. - username = Administrator - password = 1q2w3eP - diff --git a/documentation/source/basic/DevelEnvSetup.rst b/documentation/source/basic/DevelEnvSetup.rst deleted file mode 100644 index 01836bd695..0000000000 --- a/documentation/source/basic/DevelEnvSetup.rst +++ /dev/null @@ -1,47 +0,0 @@ -Development workflow after the Repository Split -=============================================== - -1) Clone virt-test -2) `Fork the test provider you want to contribute to in github ` -3) Clone the forked repository. In this example, we'll assume you cloned the forked repo to - -:: - - /home/user/code/tp-libvirt - -4) Add a file in virt-test/test-providers.d, with a name you like. We'll assume you chose - -:: - - user-libvirt.ini - -5) Contents of user-libvirt.ini: - -:: - - [provider] - uri: file:///home/user/code/tp-qemu - [libvirt] - subdir: libvirt/ - [libguestfs] - subdir: libguestfs/ - [lvsb] - subdir: lvsb/ - [v2v] - subdir: v2v/ - -6) This should be enough. Now, when you use --list-tests, you'll be able to see entries like: - -:: - - ... - 1 user-libvirt.unattended_install.cdrom.extra_cdrom_ks.default_install.aio_native - 2 user-libvirt.unattended_install.cdrom.extra_cdrom_ks.default_install.aio_threads - 3 user-libvirt.unattended_install.cdrom.extra_cdrom_ks.perf.aio_native - ... - -7) Modify tests, or add new ones to your heart's content. When you're happy with your changes, you may create branches and `send us pull requests `__. - -That should be it. Let us know if you have any doubts about the process through -:doc:`the mailing list <../contributing/ContactInfo>` or -`opening an issue `__. diff --git a/documentation/source/basic/GetStarted.rst b/documentation/source/basic/GetStarted.rst deleted file mode 100644 index 14efd9afe5..0000000000 --- a/documentation/source/basic/GetStarted.rst +++ /dev/null @@ -1,121 +0,0 @@ -=============== -Getting Started -=============== - -Pre-requisites --------------- - -#. A supported host platforms: Red Hat Enterprise Linux (RHEL) or Fedora. - OpenSUSE should also work, but currently autotest is still - not packaged for it, which means you have to clone autotest and put its path - in an env variable so virt tests can find the autotest libs. - Debian/Ubuntu now have a new experimental package that allows one to run - the virt tests in a failry straight forward way. - -#. :doc:`Install software packages (RHEL/Fedora) <../basic/InstallPrerequesitePackages>` -#. :doc:`Install software packages (Debian/Ubuntu) <../basic/InstallPrerequesitePackagesDebian>` -#. A copy of the :doc:`virt test source <../contributing/DownloadSource>` - -For the impatient ------------------ - -1) Clone the virt test repo - -:: - - git clone git://github.com/autotest/virt-test.git - - -2) Get into the base dir - -:: - - cd virt-test - -3) Run the bootstrap procedure. For example, if you want to run - the qemu subtest, you will run: - -:: - - ./run -t qemu --bootstrap - -This script will check if you have the minimum requirements for the test -(required commands and includes), and download the JeOS image. You can omit -running this script, since the code of this script also gets to run when you -call the test runner, but it is discouraged. Explicitly running get_started.py -first is iteractive, and gives you a better idea of what is going on. - - -4) For qemu and libvirt subtests, the default test set does not require - root. However, other tests might fail due to lack of privileges. - -:: - - $ ./run -t qemu - -or - -:: - - # ./run -t libvirt - - -If you ran get_started.py, the test runner should just run the test. If you -didn't, the runner will trigger the environment setup procedure: - -1) Create the /var/tmp/libvirt_test dir to hold images and isos -2) Download the JeOS image (180 MB, takes about 3 minutes on a fast connection) - and uncompress it (takes about a minute on an HDD laptop). p7ip has to - be present. -3) Run a predefined set of tests. - - -Running different tests ------------------------ - -You can list the available tests to run by using the flag --list-tests - -:: - - $ ./run -t qemu --list-tests - (will print a numbered list of tests, with a paginator) - -Then you can pass tests that interest you with --tests "list of tests", for -example: - -1) qemu - -:: - - $ ./run -t qemu --tests "migrate timedrift file_transfer" - -2) Libvirt requires first importing the JeOS image. However, this cannot be done - if the guest already exists. Therefore, it's wise to also conclude a set with the - remove_guest.without_disk test. - -:: - - # ./run -t libvirt --tests "unattended_install.import.import boot reboot remove_guest.without_disk" - - -Checking the results --------------------- - -The test runner will produce a debug log, that will be useful to debug -problems: - -:: - - $ ./run -t qemu --tests usb - Running setup. Please wait... - SETUP: PASS (13.52 s) - DATA DIR: /home/lmr/virt_test - DEBUG LOG: /home/lmr/Code/virt-test.git/logs/run-2014-01-27-14.25.31/debug.log - TESTS: 203 - (1/203) type_specific.io-github-autotest-qemu.usb.usb_boot.usb_kbd.without_usb_hub.uhci: PASS (25.47 s) - (2/203) type_specific.io-github-autotest-qemu.usb.usb_boot.usb_kbd.without_usb_hub.ehci: PASS (23.53 s) - (3/203) type_specific.io-github-autotest-qemu.usb.usb_boot.usb_kbd.without_usb_hub.xhci: PASS (24.34 s) - ... - -Here you can see that the debug log is in `/home/lmr/Code/virt-test.git/logs/run-2014-01-27-14.25.31/debug.log`. -For convenience, the most recent log is pointed to by the `logs/latest` symlink. diff --git a/documentation/source/basic/InstallPrerequesitePackages.rst b/documentation/source/basic/InstallPrerequesitePackages.rst deleted file mode 100644 index 29bbc91bf1..0000000000 --- a/documentation/source/basic/InstallPrerequesitePackages.rst +++ /dev/null @@ -1,160 +0,0 @@ -Install prerequesite packages -=================================================== - -We need git and autotest, not available on RHEL repos. So, on RHEL hosts run first: - -:: - - rpm -ivh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm - -To install `EPEL `_ repos. It is -important to note that EPEL is needed with the sole purpose of providing -a git RHEL package. If you can manage to install git from somewhere -else, then this is not necessary. Check -`here `_ -for up to date EPEL RPM repo location. - -Install the following packages: - -#. Install a toolchain in your host, which you can do with Fedora and RHEL with: - -:: - - yum groupinstall "Development Tools" - -#. Install tcpdump, necessary to determine guest IPs automatically - -:: - - yum install tcpdump - -#. Install nc, necessary to get output from the serial device and other - qemu devices - -:: - - yum install nmap-ncat - - -#. Install the p7zip file archiver so you can uncompress the JeOS [2] image. - -:: - - yum install p7zip - -#. Install the autotest-framework package, to provide the needed autotest libs. - -:: - - yum install --enablerepo=updates-testing autotest-framework - -#. Install the fakeroot package, if you want to install from the CD Ubuntu and -Debian servers without requiring root: - -:: - - yum install fakeroot - - -*If* you don't install the autotest-framework package (say, your distro still -doesn't have autotest packages, or you don't want to install the rpm), -you'll have to clone an autotest tree and export this path as the -AUTOTEST_PATH variable, both as root and as your regular user. One could put the -following on their ~/.bashrc file: - -:: - - export AUTOTEST_PATH="/path/to/autotest" - -where this AUTOTEST_PATH will guide the run script to set up the needed -libraries for all tests to work. - - -For other packages: - -:: - - yum install git - -So you can checkout the source code. If you want to test the distro provided -qemu-kvm binary, you can install: - -:: - - yum install qemu-kvm qemu-kvm-tools - - -To run libvirt tests, it's required to install the virt-install utility, for the basic purpose of building and cloning virtual machines. - -:: - - yum install virt-install - -To run all tests that involve filedescriptor passing, you need python-devel. -The reason is, this test suite is compatible with python 2.4, whereas a -std lib to pass filedescriptors was only introduced in python 3.2. Therefore, -we had to introduce a C python extension that is compiled on demand. - -:: - - yum install python-devel. - - -It's useful to also install: - -:: - - yum install python-imaging - -Not vital, but very handy to do imaging conversion from ppm to jpeg and -png (allows for smaller images). - - - -Tests that are not part of the default JeOS set ------------------------------------------------ - -If you want to run guest install tests, you need to be able to -create floppies and isos to hold kickstart files: - -:: - - yum install mkisofs - -For newer distros, such as Fedora, you'll need: - -:: - - yum install genisoimage - -Both packages provide the same functionality, needed to create iso -images that will be used during the guest installation process. You can -also execute - - -Network tests -------------- - -Last bug not least, now we depend on libvirt to provide us a stable, working bridge. -* By default, the kvm test uses user networking, so this is not entirely -necessary. However, non root and user space networking make a good deal -of the hardcode networking tests to not work. If you might want to use -bridges eventually: - -:: - - yum install libvirt bridge-utils - -Make sure libvirtd is started: - -:: - - [lmr@freedom autotest.lmr]$ service libvirtd start - -Make sure the libvirt bridge shows up on the output of brctl show: - -:: - - [lmr@freedom autotest.lmr]$ brctl show - bridge name bridge id STP enabled interfaces - virbr0 8000.525400678eec yes virbr0-nic diff --git a/documentation/source/basic/InstallPrerequesitePackagesDebian.rst b/documentation/source/basic/InstallPrerequesitePackagesDebian.rst deleted file mode 100644 index 37ffaafc88..0000000000 --- a/documentation/source/basic/InstallPrerequesitePackagesDebian.rst +++ /dev/null @@ -1,160 +0,0 @@ -Install prerequesite packages - Debian -=================================================== - -Keep in mind that the current autotest package is a work in progress. For the -purposes of running virt-tests it is fine, but it needs a lot of improvements -until it can become a more 'official' package. - -The autotest debian package repo can be found at https://launchpad.net/~lmr/+archive/autotest, -and you can add the repos on your system putting the following on /etc/apt/sources.list: - -:: - - deb http://ppa.launchpad.net/lmr/autotest/ubuntu raring main - deb-src http://ppa.launchpad.net/lmr/autotest/ubuntu raring main - -Then update your software list: - -:: - - apt-get update - -This has been tested with Ubuntu 12.04, 12.10 and 13.04. - -Install the following packages: - - -#. Install the autotest-framework package, to provide the needed autotest libs. - -:: - - apt-get install autotest - - -#. Install the p7zip file archiver so you can uncompress the JeOS [2] image. - -:: - - apt-get install p7zip-full - - -#. Install tcpdump, necessary to determine guest IPs automatically - -:: - - apt-get install tcpdump - -#. Install nc, necessary to get output from the serial device and other - qemu devices - -:: - - apt-get install netcat-openbsd - - -#. Install a toolchain in your host, which you can do on Debian and Ubuntu with: - -:: - - apt-get install build-essential - -#. Install fakeroot if you want to install from CD debian and ubuntu, not -requiring root: - -:: - - apt-get install fakeroot - -So you install the core autotest libraries to run the tests. - -*If* you don't install the autotest-framework package (say, your distro still -doesn't have autotest packages, or you don't want to install the rpm), -you'll have to clone an autotest tree and export this path as the -AUTOTEST_PATH variable, both as root and as your regular user. One could put the -following on their ~/.bashrc file: - -:: - - export AUTOTEST_PATH="/path/to/autotest" - -where this AUTOTEST_PATH will guide the run script to set up the needed -libraries for all tests to work. - - -For other packages: - -:: - - apt-get install git - -So you can checkout the source code. If you want to test the distro provided -qemu-kvm binary, you can install: - -:: - - apt-get install qemu-kvm qemu-utils - -To run libvirt tests, it's required to install the virt-install utility, for the basic purpose of building and cloning virtual machines. - -:: - - apt-get install virtinst - -To run all tests that involve filedescriptor passing, you need python-all-dev. -The reason is, this test suite is compatible with python 2.4, whereas a -std lib to pass filedescriptors was only introduced in python 3.2. Therefore, -we had to introduce a C python extension that is compiled on demand. - -:: - - apt-get install python-all-dev. - - -It's useful to also install: - -:: - - apt-get install python-imaging - -Not vital, but very handy to do imaging conversion from ppm to jpeg and -png (allows for smaller images). - - - -Tests that are not part of the default JeOS set ------------------------------------------------ - -If you want to run guest install tests, you need to be able to -create floppies and isos to hold kickstart files: - -:: - - apt-get install genisoimage - - -Network tests -------------- - -Last bug not least, now we depend on libvirt to provide us a stable, working bridge. -* By default, the kvm test uses user networking, so this is not entirely -necessary. However, non root and user space networking make a good deal -of the hardcode networking tests to not work. If you might want to use -bridges eventually: - -:: - - apt-get install libvirt-bin python-libvirt bridge-utils - -Make sure libvirtd is started: - -:: - - [lmr@freedom autotest.lmr]$ service libvirtd start - -Make sure the libvirt bridge shows up on the output of brctl show: - -:: - - [lmr@freedom autotest.lmr]$ brctl show - bridge name bridge id STP enabled interfaces - virbr0 8000.525400678eec yes virbr0-nic diff --git a/documentation/source/basic/Introduction.rst b/documentation/source/basic/Introduction.rst deleted file mode 100644 index 78f5f88dee..0000000000 --- a/documentation/source/basic/Introduction.rst +++ /dev/null @@ -1,36 +0,0 @@ -========================= -Introduction to Virt Test -========================= - -Virt-test's main purpose is to serve as an automated regression testing tool -for virt developers, and for doing regular automated testing of virt technologies -(provided you use it with the server testing infrastructure). - -Autotest is a project that aims to provide tools and libraries to -perform automated testing on the linux platform. `virt-test` is a -subproject under the autotest umbrella. For more information on -autotest, see `the autotest home page `_. - -`virt-test` aims to be a centralizing project for most of the virt -functional and performance testing needs. We cover: - -- Guest OS install, for both Windows (WinXP - Win7) and Linux (RHEL, - Fedora, OpenSUSE and others through step engine mechanism) -- Serial output for Linux guests -- Migration, networking, timedrift and other types of tests - -For the qemu subtests, we can do things like: - -- Monitor control for both human and QMP protocols -- Build and use qemu using various methods (source tarball, git repo, - rpm) -- Some level of performance testing can be made. -- The KVM unit tests can be run comfortably from inside virt-test, - we do have full integration with the unittest execution - -We support x86\_64 hosts with hardware virtualization support (AMD and -Intel), and Intel 32 and 64 bit guest operating systems. - -For an overview about virt-test, how this project was created, its -goals, structure, and how to develop simple tests, you can refer to the -`KVM forum 2010 slides `_. diff --git a/documentation/source/basic/Introduction/Introduction/2010-forum-Kvm-autotest.pdf b/documentation/source/basic/Introduction/Introduction/2010-forum-Kvm-autotest.pdf deleted file mode 100644 index 0adaa2659e..0000000000 Binary files a/documentation/source/basic/Introduction/Introduction/2010-forum-Kvm-autotest.pdf and /dev/null differ diff --git a/documentation/source/basic/SourceStructure.rst b/documentation/source/basic/SourceStructure.rst deleted file mode 100644 index f4a5506446..0000000000 --- a/documentation/source/basic/SourceStructure.rst +++ /dev/null @@ -1,275 +0,0 @@ - -Virt test source structure -========================== - -When starting to contribute to a project, a high level description of the -directory structure is frequently useful. In virt-tests, at the time of -this writing (01-09-2013), the output of the command `tree` for this structure -looks like: - -:: - - . - |-- libvirt - | |-- cfg - | `-- tests - | `-- cfg - |-- openvswitch - | |-- cfg - | `-- tests - | `-- cfg - |-- qemu - | |-- cfg - | `-- tests - | `-- cfg - |-- shared - | |-- autoit - | |-- blkdebug - | |-- cfg - | | `-- guest-os - | | |-- Linux - | | | |-- Fedora - | | | |-- JeOS - | | | |-- LinuxCustom - | | | |-- OpenSUSE - | | | |-- RHEL - | | | |-- SLES - | | | `-- Ubuntu - | | `-- Windows - | | |-- Win2000 - | | |-- Win2003 - | | |-- Win2008 - | | |-- Win7 - | | |-- WindowsCustom - | | |-- WinVista - | | `-- WinXP - | |-- control - | |-- deps - | | |-- test_clock_getres - | | `-- test_cpu_flags - | |-- download.d - | |-- scripts - | |-- steps - | `-- unattended - |-- tests - | `-- cfg - |-- tools - |-- v2v - | |-- cfg - | `-- tests - | `-- cfg - `-- virttest - - -Talking about the top level directories: - -Subtest dirs ------------- - -Those directories hold specific test code for different virtualization types. -Originally, virt-tests started as a set of tests for kvm, project that was -known as virt-test. The request to support other virt backends, such as -libvirt made us to generalize the tests infrastructure and support other -backends. As of the timeof this writing, we have 4 main backends, which we -expect to grow: - -1) qemu (used to be known as kvm) -2) libvirt -3) openvswitch (bridge technology testing) -4) v2v (testing of tools used to migrate vms from 1 technlogy to another) - -Inside a subtest dir, the structure is, usually: - -:: - - |-- qemu - | |-- cfg -> Config files that will be parsed by the test runner/autotest - | `-- tests -> Holds the tests specific to that backend - | `-- cfg -> Holds config snippets for the tests - -The test runner, for example, will parse the top level config file -``qemu/cfg/tests.cfg``. This file includes a number of other files, and will -generate a large set of dictionaries, with all variations of a given set of -parameters. - -Not all virt tests require config snippets, but some might want to make use of -the features of the [CartesianConfigReference | Cartesian files] and make one -test source to generate several different tests. If you don't want to use that, -no sweat, you're not obligated. - -The snippets in tests/cfg will be used to generate subtests.cfg, a listing of -all tests available for that particular backend. - -Shared tests ------------- - -Some tests in virt-tests are generic enough that they might run in more than one -virt backend. For example, if one virt test uses guests, but does not use the -qemu monitor interface (vm.monitor), it's likely that it belongs to the shared -test dir (toplevel tests). The structure for it is simple: - -:: - - |-- tests -> Tests that are shared by more than one virt backend - | `-- cfg -> Holds config snippets for the tests - -Shared resources dir --------------------- - -The virt tests often need a number of resources, be it a: - - - Disk image - - Operating System CD - - Scripts and executables to run in the guest - - OEM installer files (kickstarts, windows answer files, among others) - -We concentrate all those resources in the shared dir. If you look at its -structure, you'll see: - -:: - - |-- shared - | |-- autoit -> Windows specific automation files - | |-- blkdebug -> QEMU blkdebug config files - | |-- cfg -> Holds base config files - | | `-- guest-os -> Holds a number of guest OS config snippets that'll create guest-os.cfg - | | |-- Linux - | | | |-- Fedora - | | | |-- JeOS - | | | |-- LinuxCustom - | | | |-- OpenSUSE - | | | |-- RHEL - | | | |-- SLES - | | | `-- Ubuntu - | | `-- Windows - | | |-- Win2000 - | | |-- Win2003 - | | |-- Win2008 - | | |-- Win7 - | | |-- WindowsCustom - | | |-- WinVista - | | `-- WinXP - | |-- control -> Holds autotest control files to run in the guest - | |-- deps -> C programs that need to be compiled in the guest - | | |-- test_clock_getres - | | `-- test_cpu_flags - | |-- download.d -> Holds resource files, that can be used to download disks - | |-- scripts -> Holds python scripts to be executed in the guest - | |-- steps -> Recordings of guest interaction that can be replayed - | `-- unattended -> OEM install files (kickstarts, windows answer files) - -Tools dir ---------- - -The tools dir contains a bunch of useful tools for test writers and virt-test -maintainers. Specially useful are the tools to run the unittests available -for virt-test, and run_pylint.py, which runs pylint in any python file you -might want, which helps to capture silly mistakes before they go public. - -:: - - tools/ - |-- cd_hash.py -> Calculates MD5 and SHA1 for ISOS (in fact, for any file) - |-- check_patch.py -> Verify whether a github or patchwork patch is OK - |-- common.py - |-- common.pyc - |-- download_manager.py -> Download resources, such as ISOS and guest images - |-- koji_pkgspec.py -> Get info about packages in Koji or Brew - |-- parallel.py - |-- parallel.pyc - |-- perf.conf - |-- regression.py -> Compare virt test jobs performance data - |-- reindent.py -> Fix indentation mistakes on your python files - |-- run_pylint.py -> Static source checker for python - |-- run_unittests.py -> Run all available virttest unittests - |-- tapfd_helper.py -> Paste a qemu cmd line produced by autotest and run it - `-- virt_disk.py -> Create floppy images and iso files - -Virttest dir ------------- - -In this dir, goes most of the library code of virt test. Over the years, the -number of libraries grew quite a bit. Inside test code, those libraries are -usually imported like: - -:: - - from virttest import [library name] - -Here's a listing with high level descriptions of each file: - -:: - - virttest - |-- aexpect.py -> Controls subprocesses interactively - |-- base_installer.py -> Base code for virt software install - |-- bootstrap.py -> Functions to prepare environment previous to test exec - |-- build_helper.py -> Code with rules to build software - |-- cartesian_config.py -> The parser of the cartesian file format - |-- common.py - |-- data_dir.py -> Finds/sets the main data file - |-- ElementPath.py -> Library to manipulate XML - |-- ElementTree.py -> Library to manipulate XML - |-- env_process.py -> Handles setup/cleanup pre/post tests - |-- guest_agent.py -> Controls the qemu guest agent - |-- http_server.py -> Simple server for kickstart installs - |-- __init__.py - |-- installer.py -> Code for virt software install - |-- installer_unittest.py - |-- iscsi.py -> Code to handle vm images in iscsi disks - |-- iscsi_uinttest.py - |-- libvirt_storage.py -> Create images for libvirt tests - |-- libvirt_vm.py -> VM class for libvirt backend - |-- libvirt_xml.py -> High level XML manipulation for libvirt test purposes - |-- libvirt_xml_unittest.py - |-- openvswitch.py -> Functions to deal with openvswitch network technology - |-- ovirt.py -> Library to handle an ovirt server - |-- ovs_utils.py -> Utils for the openvswitch test - |-- passfd.c -> Python c library for filedescriptor passing - |-- passfd.py -> Library for filedescriptor passing (python interface) - |-- passfd_setup.py -> Compiles the passfd library - |-- postprocess_iozone.py -> Code to analyze iozone results - |-- ppm_utils.py -> Code to handle QEMU screenshot file format - |-- propcan.py -> Class to handle sets of config values - |-- propcan_unittest.py - |-- qemu_installer.py -> Class to install qemu (git, rpm, etc) - |-- qemu_io.py -> Code to call qemu-io, for testing - |-- qemu_monitor.py -> Handles the qemu monitor interfaces (HMP and QMP) - |-- qemu_qtree.py -> Creates a data structure representation of qemu qtree output - |-- qemu_qtree_unittest.py - |-- qemu_storage.py -> Handles image creation for the qemu test - |-- qemu_virtio_port.py -> Code for dealing with qemu virtio ports - |-- qemu_vm.py -> VM class for the qemu test - |-- remote.py -> Functions to handle logins and remote transfers - |-- rss_client.py -> Client for the windows shell tool developed for virt-tests - |-- scheduler.py -> Functions for parallel testing - |-- standalone_test.py -> Implements a small test harness for execution independent of autotest - |-- step_editor.py -> Code for recording interaction with guests and replay them - |-- storage.py -> Base code for disk image creation - |-- syslog_server.py -> Simple syslog server to capture messages from OS installs - |-- test_setup.py -> Tests prep code (Hugepages setup, among others) - |-- utils_cgroup.py -> Utils to create and manipulate cgroups - |-- utils_disk.py -> Utils to create ISOS and floppy images - |-- utils_env.py -> Contains the class that holds the VM instances and other persistent info - |-- utils_env_unittest.py - |-- utils_koji.py -> Utils to interact with the Koji and Brew Buildsystems - |-- utils_misc.py -> Utils that don't fit in broader categories - |-- utils_misc_unittest.py - |-- utils_net.py -> VM and Host network utils - |-- utils_net_unittest.py - |-- utils_params.py -> Contains the class that holds test config data - |-- utils_spice.py -> Contains utils for spice testing - |-- utils_test.py -> Contains high level common utilities for testing - |-- utils_v2v.py -> Contains utilities for v2v testing - |-- versionable_class.py -> Classes with multiple ancestors, for openvswitch testing - |-- versionable_class_unittest.py - |-- video_maker.py -> Creates a ogg/webm video from vm screenshots - |-- virsh.py -> Calls and tests the virsh utility - |-- virsh_unittest.py - |-- virt_vm.py -> Base VM class, from where the specific tests derive from - |-- xml_utils.py -> Utils for XML manipulation - |-- xml_utils_unittest.py - `-- yumrepo.py -> Lib to create yum repositories, test helper - -As you can see, there's quite a lot of code. We try to keep it as organized as -possible, but if you have any problems just let us know (see ContactInfo). \ No newline at end of file diff --git a/documentation/source/basic/TestProviders.rst b/documentation/source/basic/TestProviders.rst deleted file mode 100644 index 6ef8736764..0000000000 --- a/documentation/source/basic/TestProviders.rst +++ /dev/null @@ -1,133 +0,0 @@ -Test Providers -============== - -Test providers are the conjunction of a loadable module mechanism -inside virt-test that can pull a directory that will provide tests, config -files and any dependencies, and those directories. The design goals behind -test providers are: - -* Make it possible for other organizations to maintain test repositories, in other arbitrary git repositories. - -* Stabilize API and enforce separation of core virt-test functionality and tests. - -The test provider spec is divided in Provider Layout and Definition files. - -Test Provider Layout --------------------- - -:: - - . - |-- backend_1 -> Backend name. The actual name doesn't matter. - | |-- cfg -> Test config directory. Holds base files for the test runner. - | |-- deps -> Auxiliary files such as ELF files, Windows executables, images that tests need. - | |-- provider_lib -> Shared libraries among tests. - | `-- tests -> Python test files. - | `-- cfg -> Config files for tests. - `-- backend_2 - |-- cfg - |-- deps - |-- provider_lib - `-- tests - `-- cfg - - -In fact, virt-test libraries are smart enough to support arbitrary organization -of python and config files inside the 'tests' directory. You don't need to name -the top level sub directories after backend names, although that certainly makes -things easier. The term 'backend' is used to refer to the supported virtualization -technologies by virt-test. As of this writing, the backends known by virt-test -are: - -* generic (tests that run in multiple backends) -* qemu -* openvswitch -* libvirt -* v2v -* libguestfs -* lvsb - -The reason why you don't need to name the directories after the backend names -is that you can configure a test definition file to point out any dir name. We'll -get into - -Types of Test Providers ------------------------ - -Each test provider can be either a local filesystem directory, or a subdirectory -of a git repository. Of course, the git repo subdirectory can be the repo root -directory, but one of the points of the proposal is that people can hold -virt-test providers inside git repos of other projects. Say qemu wants to -maintain its own provider, they can do this by holding the tests, say, inside -a tests/virt-test subdirectory inside qemu.git. - -Test Provider definition file ------------------------------ - -The main virt-test suite needs a way to know about test providers. It does that -by scanning definition files inside the 'test-providers.d' sub directory. -Definition files are `config parser files ` -that encode information from a test provider. Here's an example structure of a -test provider file: - -:: - - [provider] - - # Test provider URI (default is a git repository, fallback to standard dir) - uri: git://git-provider.com/repo.git - #uri: /path-to-my-git-dir/repo.git - #uri: http://bla.com/repo.git - #uri: file://usr/share/tests - - # Optional git branch (for git repo type) - branch: master - - # Optionall git commit reference (tag or sha1) - ref: e44231e88300131621586d24c07baa8e627de989 - - # Pubkey: File containing public key for signed tags (git) - pubkey: example.pub - - # What follows is a sequence of sections for any backends that this test - # provider implements tests for. You must specify the sub directories of - # each backend dir, reason why the subdir names can be arbitrary. - - [qemu] - # Optional subdir (place inside repo where the actual tests are) - # This is useful for projects to keep virt tests inside their - # (larger) test repos. Defaults to ''. - subdir: src/tests/qemu/ - - [agnostic] - # For each test backend, you may have different sub directories - subdir: src/tests/generic/ - -Example of a default virt-test provider file: - -:: - - [provider] - uri: https://github.com/autotest/tp-qemu.git - [generic] - subdir: generic/ - [qemu] - subdir: qemu/ - [openvswitch] - subdir: openvswitch/ - -Let's say you want to use a directory in your file system -(/usr/share/tests/virt-test): - -:: - - [provider] - uri: file://usr/share/tests/ - [generic] - subdir: virt-test/generic/ - [qemu] - subdir: virt-test/qemu/ - [openvswitch] - subdir: virt-test/openvswitch/ - -Any doubts about the specification, let me know - Email lmr AT redhat DOT com. diff --git a/documentation/source/basic/TestRunner.rst b/documentation/source/basic/TestRunner.rst deleted file mode 100644 index 37ea6531a7..0000000000 --- a/documentation/source/basic/TestRunner.rst +++ /dev/null @@ -1,125 +0,0 @@ -================ -Virt Test Runner -================ - -As you probably know, virt tests was derived from a set of tests written -for the autotest testing framework. Therefore, the test suite depended -entirely on autotest for libraries *and* the autotest test harness to -execute the test code. - -However, autotest is a large framework, that forced a steep learning curve -for people and a lot of code download (the autotest git repo is quite large -these days, due to more than 6 years of history). - -Due to this, virt tests was separated to its own test suite project, that -still can run fine under autotest (in fact, it is what we use to do daily -fully automated testing of KVM and QEMU), but that can be executed separately, -depending only on a handful of autotest libraries. - -This doc assumes you already read the introductory GetStarted documentation. -This extra doc is just to teach you some useful tricks when using the runner. - -Getting Help -============ - -The best way to get help from the command line options is the --help flag: - -:: - - ./run --help - - -General Flow -============ - -The test runner is nothing more than a very simple test harness, that replaces -the autotest harness, and a set of options, that will trigger actions to -create a test list and execute it. The way the tests work is: - -1) Get a dict with test parameters -2) Based on these params, prepare the environment - create or destroy vm - instances, create/check disk images, among others -3) Execute the test itself, that will use several of the params defined to - carry on with its operations, that usually involve: -4) If a test did not raise an exception, it PASSed -5) If a test raised an exception it FAILed -6) Based on what happened during the test, perform cleanup actions, such as - killing vms, and remove unused disk images. - -The list of parameters is obtained by parsing a set of configuration files, -present inside the SourceStructure. The command line options usually modify -even further the parser file, so we can introduce new data in the config -set. - -Common Operations -- Listing guests -=================================== - -If you want to see all guests defined, you can use - -:: - - ./run -t [test type] --list-guests - - -This will generate a list of possible guests that can be used for tests, -provided that you have an image with them. The list will show which guests -don't have an image currently available. If you did perform the usual -bootstrap procedure, only JeOS.17.64 will be available. - -Now, let's assume you have the image for another guest. Let's say you've -installed Fedora 17, 64 bits, and that --list-guests shows it as downloaded - -:: - - ./run -t qemu --list-guests - ... snip... - 16 Fedora.17.32 (missing f17-32.qcow2) - 17 Fedora.17.64 - 18 Fedora.8.32 (missing f8-32.qcow2) - -You can list all the available tests for Fedora.17.64 (you must use the exact -string printed by the test, minus obviously the index number, that's there -only for informational purposes: - -:: - - ./run -t qemu -g Fedora.17.64 --list-tests - ... snip ... - 26 balloon_check.base - 27 balloon_check.balloon-migrate - 28 balloon_check.balloon-shutdown_enlarge - 29 balloon_check.balloon-shutdown_evict - 30 block_mirror - 31 block_stream - ... snip ... - -Then you can execute one in particular. It's the same idea, just copy the -individual test you want and run it: - -:: - - ./run -t qemu -g Fedora.17.64 --tests balloon_check.balloon-migrate - -And it'll run that particular test. - -*Tip:* By the rules of the cartesian config files, you can use: - -:: - - ./run -t qemu -g Fedora.17.64 --tests balloon_check - -And it'll run all tests from 26-29. Very useful for large sets, such as -virtio_console and usb - You can just do a: - -:: - - ./run -t qemu --tests virtio_console - ... 118 tests ... - -:: - - ./run -t qemu --tests usb - ... 64 tests ... - -Note that in the examples above, the fact I didn't provide -g means that we're -using the default guest OS, that is, JeOS. diff --git a/documentation/source/basic/WritingAdvancedTests.rst b/documentation/source/basic/WritingAdvancedTests.rst deleted file mode 100644 index 1cadb3a479..0000000000 --- a/documentation/source/basic/WritingAdvancedTests.rst +++ /dev/null @@ -1,35 +0,0 @@ - -Writing a more advanced test -============================ - -Now that you wrote your first simple test, we'll try some more involved -examples. First, let's talk about some useful APIs and concepts: - -As virt-tests evolved, a number of libraries were written to help test writers. -Let's see what some of them can do: - -1) virttest.data_dir -> Has functions to get paths for resource files. One of the - most used functions is data_dir.get_data_dir(), that returns the path - shared/data, which helps you to get files. - -:: - - from virttest import data_dir - -What's available upfront ------------------------- - -Very frequently we may get values from the config -set. All virt tests take 3 params: - - test -> Test object - params -> Dict with current test params - env -> Environment file being used for the test job - -You might pick any parameter using - -:: - - variable_name = params.get("param_name", default_value) - -You can update the parameters using \ No newline at end of file diff --git a/documentation/source/basic/WritingSimpleTests.rst b/documentation/source/basic/WritingSimpleTests.rst deleted file mode 100644 index dbb37b6c5a..0000000000 --- a/documentation/source/basic/WritingSimpleTests.rst +++ /dev/null @@ -1,362 +0,0 @@ - -Writing your own virt test -================================== - -In this article, we'll talk about: - -#. Where the test files are located -#. Write a simple test file -#. Try out your new test, send it to the mailing list - - -Where the virt test files are located ? ---------------------------------------- - -The subtests can be located in 2 subdirs: - -- tests - These tests are written in a fairly virt - technology agnostic way, so they can be used by other virt - technologies testing. More specifically, they do not use the vm - monitor. - - :: - - $ ls - autotest_control.py fail.py iofuzz.py module_probe.py ping.py shutdown.py vlan.py - boot.py file_transfer.py ioquit.py multicast.py pxe.py skip.py warning.py - boot_savevm.py fillup_disk.py iozone_windows.py netperf.py rv_connect.py softlockup.py watchdog.py - build.py fullscreen_setup.py jumbo.py netstress_kill_guest.py rv_copyandpaste.py stress_boot.py whql_client_install.py - cfg guest_s4.py kdump.py nfs_corrupt.py rv_disconnect.py trans_hugepage_defrag.py whql_submission.py - clock_getres.py guest_test.py linux_s3.py nicdriver_unload.py rv_fullscreen.py trans_hugepage.py yum_update.py - dd_test.py image_copy.py lvm.py nic_promisc.py rv_input.py trans_hugepage_swapping.py - ethtool.py __init__.py mac_change.py ntttcp.py save_restore.py unattended_install.py - -- qemu/tests - These are tests that do use - specific qemu infrastructure, specifically the qemu monitor. other - virt technologies can't use it so they go here. - - :: - - $ ls - 9p.py __init__.py multi_disk.py qemu_io_blkdebug.py timedrift.py - balloon_check.py kernel_install.py negative_create.py qemu_iotests.py timedrift_with_migration.py - block_mirror.py ksm_overcommit.py nic_bonding.py qmp_basic.py timedrift_with_reboot.py - block_stream.py migration_multi_host_cancel.py nic_hotplug.py qmp_basic_rhel6.py timedrift_with_stop.py - cdrom.py migration_multi_host_downtime_and_speed.py nmi_bsod_catch.py seabios.py time_manage.py - cfg migration_multi_host_ping_pong.py nmi_watchdog.py set_link.py unittest_qemuctl.py - cgroup.py migration_multi_host.py pci_hotplug.py smbios_table.py unittest.py - cpuflags.py migration_multi_host_with_file_transfer.py perf_qemu.py sr_iov_hotplug.py usb.py - cpu_hotplug.py migration_multi_host_with_speed_measurement.py performance.py sr_iov_hotunplug.py virtio_console.py - enospc.py migration.py physical_resources_check.py stepmaker.py vmstop.py - floppy.py migration_with_file_transfer.py qemu_guest_agent.py steps.py - getfd.py migration_with_reboot.py qemu_guest_agent_snapshot.py stop_continue.py - hdparm.py migration_with_speed_measurement.py qemu_img.py system_reset_bootable.py - -So the thumb rule is, if it uses the qemu monitor, you stick it into qemu/tests, -if it doesn't, you can stick it into the tests/ dir. - -Write our own, drop-in 'uptime' test - Step by Step procedure -------------------------------------------------------------- - -Now, let's go and write our uptime test, which only purpose in life is -to pick up a living guest, connect to it via ssh, and return its uptime. - -#. Git clone virt_test.git to a convenient location, say $HOME/Code/virt-test. - See `the download source documentation <../contributing/DownloadSource>`. - Please do use git and clone the repo to the location mentioned. - -#. Our uptime test won't need any qemu specific feature. Thinking about - it, we only need a vm object and stablish an ssh session to it, so we - can run the command. So we can store our brand new test under - ``tests``. At the autotest root location: - - :: - - [lmr@freedom virt-test.git]$ touch tests/uptime.py - [lmr@freedom virt-test.git]$ git add tests/uptime.py - -#. Ok, so that's a start. So, we have *at least* to implement a - function ``run_uptime``. Let's start with it and just put the keyword - pass, which is a no op. Our test will be like: - - :: - - def run_uptime(test, params, env): - """ - Docstring describing uptime. - """ - pass - -#. Now, what is the API we need to grab a VM from our test environment? - Our env object has a method, ``get_vm``, that will pick up a given vm - name stored in our environment. Some of them have aliases. ``main_vm`` - contains the name of the main vm present in the environment, which - is, most of the time, ``vm1``. ``env.get_vm`` returns a vm object, which - we'll store on the variable vm. It'll be like this: - - :: - - def run_uptime(test, params, env): - """ - Docstring describing uptime. - """ - vm = env.get_vm(params["main_vm"]) - -#. A vm object has lots of interesting methods, which we plan on documenting - them more thoroughly, but for - now, we want to ensure that this VM is alive and functional, at least - from a qemu process standpoint. So, we'll call the method - ``verify_alive()``, which will verify whether the qemu process is - functional and if the monitors, if any exist, are functional. If any - of these conditions are not satisfied due to any problem, an - exception will be thrown and the test will fail. This requirement is - because sometimes due to a bug the vm process might be dead on the - water, or the monitors are not responding. - - :: - - def run_uptime(test, params, env): - """ - Docstring describing uptime. - """ - vm = env.get_vm(params["main_vm"]) - vm.verify_alive() - -#. Next step, we want to log into the vm. the vm method that does return - a remote session object is called ``wait_for_login()``, and as one of - the parameters, it allows you to adjust the timeout, that is, the - time we want to wait to see if we can grab an ssh prompt. We have top - level variable ``login_timeout``, and it is a good practice to - retrieve it and pass its value to ``wait_for_login()``, so if for - some reason we're running on a slower host, the increase in one - variable will affect all tests. Note that it is completely OK to just - override this value, or pass nothing to ``wait_for_login()``, since - this method does have a default timeout value. Back to business, - picking up login timeout from our dict of parameters: - - :: - - def run_uptime(test, params, env): - """ - Docstring describing uptime. - """ - vm = env.get_vm(params["main_vm"]) - vm.verify_alive() - timeout = float(params.get("login_timeout", 240)) - - -#. Now we'll call ``wait_for_login()`` and pass the timeout to it, - storing the resulting session object on a variable named session. - - :: - - def run_uptime(test, params, env): - """ - Docstring describing uptime. - """ - vm = env.get_vm(params["main_vm"]) - vm.verify_alive() - timeout = float(params.get("login_timeout", 240)) - session = vm.wait_for_login(timeout=timeout) - - -#. The qemu test will do its best to grab this session, if it can't due - to a timeout or other reason it'll throw a failure, failing the test. - Assuming that things went well, now you have a session object, that - allows you to type in commands on your guest and retrieve the - outputs. So most of the time, we can get the output of these commands - throught the method ``cmd()``. It will type in the command, grab the - stdin and stdout, return them so you can store it in a variable, and - if the exit code of the command is != 0, it'll throw a - aexpect.ShellError?. So getting the output of the unix command uptime - is as simple as calling ``cmd()`` with 'uptime' as a parameter and - storing the result in a variable called uptime: - - :: - - def run_uptime(test, params, env): - """ - Docstring describing uptime. - """ - vm = env.get_vm(params["main_vm"]) - vm.verify_alive() - timeout = float(params.get("login_timeout", 240)) - session = vm.wait_for_login(timeout=timeout) - uptime = session.cmd('uptime') - -#. If you want to just print this value so it can be seen on the test - logs, just log the value of uptime using the logging library. Since - that is all we want to do, we may close the remote connection, to - avoid ssh/rss sessions lying around your test machine, with the - method ``close()``. Now, note that all failures that might happen - here are implicitly handled by the methods called. If a test - went from its beginning to its end without unhandled exceptions, - autotest assumes the test automatically as PASSed, *no need to mark a - test as explicitly passed*. If you have explicit points of failure, - for more complex tests, you might want to add some exception raising. - - :: - - def run_uptime(test, params, env): - """ - Docstring describing uptime. - """ - vm = env.get_vm(params["main_vm"]) - vm.verify_alive() - timeout = float(params.get("login_timeout", 240)) - session = vm.wait_for_login(timeout=timeout) - uptime = session.cmd("uptime") - logging.info("Guest uptime result is: %s", uptime) - session.close() - -#. Now, I deliberately introduced a bug on this code just to show you - guys how to use some tools to find and remove trivial bugs on your - code. I strongly encourage you guys to check your code with the - script called run_pylint.py, located at the utils directory at the - top of your $AUTOTEST_ROOT. This tool calls internally the other - python tool called pylint to catch bugs on autotest code. I use it so - much the utils dir of my devel autotest tree is on my $PATH. So, to - check our new uptime code, we can call (important, if you don't have - pylint install it with ``yum install pylint`` or equivalent for your - distro): - - :: - - [lmr@freedom virt-test.git]$ tools/run_pylint.py tests/uptime.py -q - ************* Module virt-test.git.tests.uptime - E0602: 10,4:run_uptime: Undefined variable 'logging' - - -#. Ouch. So there's this undefined variable called logging on line 10 of - the code. It's because I forgot to import the logging library, which - is a python library to handle info, debug, warning messages. Let's Fix it - and the code becomes: - - :: - - import logging - - def run_uptime(test, params, env): - """ - Docstring describing uptime. - """ - vm = env.get_vm(params["main_vm"]) - vm.verify_alive() - timeout = float(params.get("login_timeout", 240)) - session = vm.wait_for_login(timeout=timeout) - uptime = session.cmd("uptime") - logging.info("Guest uptime result is: %s", uptime) - session.close() - -#. Let's re-run ``run_pylint.py`` to see if it's happy with the code - generated: - - :: - - [lmr@freedom virt-test.git]$ tools/run_pylint.py tests/uptime.py -q - [lmr@freedom virt-test.git]$ - -#. So we're good. Nice! Now, as good indentation does matter to python, - we have another small utility called reindent.py, that will fix - indentation problems, and cut trailing whitespaces on your code. Very - nice for tidying up your test before submission. - - :: - - [lmr@freedom virt-test.git]$ tools/reindent.py tests/uptime.py - -#. I also use run_pylint with no -q catch small things such as wrong spacing - around operators and other subtle issues that go against PEP 8 and - the `coding style - document `_. - Please take pylint's output with a *handful* of salt, you don't need - to work each and every issue that pylint finds, I use it to find - unused imports and other minor things. - - :: - - [lmr@freedom virt-test.git]$ tools/run_pylint.py tests/uptime.py - ************* Module virt-test.git.tests.uptime - C0111: 1,0: Missing docstring - C0103: 7,4:run_uptime: Invalid name "vm" (should match [a-z_][a-z0-9_]{2,30}$) - W0613: 3,15:run_uptime: Unused argument 'test' - -#. These other complaints you don't really need to fix. Due to the tests - design, they all use 3 arguments, 'vm' is a shorthand that we have been - using for a long time as a variable name to hold a VM object, and the only - docstring we'd like you to fill is the one in the run_uptime function. - -#. Now, you can test your code. When listing the qemu tests your new test should - appear in the list: - - - :: - - ./run -t qemu --list-tests - - -#. Now, you can run your test to see if everything went good. - - :: - - [lmr@freedom virt-test.git]$ ./run -t qemu --tests uptime - SETUP: PASS (1.10 s) - DATA DIR: /home/lmr/virt_test - DEBUG LOG: /home/lmr/Code/virt-test.git/logs/run-2012-11-28-13.13.29/debug.log - TESTS: 1 - (1/1) uptime: PASS (23.30 s) - -#. Ok, so now, we have something that can be git commited and sent to - the mailing list - - :: - - diff --git a/tests/uptime.py b/tests/uptime.py - index e69de29..65d46fa 100644 - --- a/tests/uptime.py - +++ b/tests/uptime.py - @@ -0,0 +1,13 @@ - +import logging - + - +def run_uptime(test, params, env): - + """ - + Docstring describing uptime. - + """ - + vm = env.get_vm(params["main_vm"]) - + vm.verify_alive() - + timeout = float(params.get("login_timeout", 240)) - + session = vm.wait_for_login(timeout=timeout) - + uptime = session.cmd("uptime") - + logging.info("Guest uptime result is: %s", uptime) - + session.close() - -#. Oh, we forgot to add a decent docstring description. So doing it: - - :: - - import logging - - def run_uptime(test, params, env): - - """ - Uptime test for virt guests: - - 1) Boot up a VM. - 2) Stablish a remote connection to it. - 3) Run the 'uptime' command and log its results. - - :param test: QEMU test object. - :param params: Dictionary with the test parameters. - :param env: Dictionary with test environment. - """ - - vm = env.get_vm(params["main_vm"]) - vm.verify_alive() - timeout = float(params.get("login_timeout", 240)) - session = vm.wait_for_login(timeout=timeout) - uptime = session.cmd("uptime") - logging.info("Guest uptime result is: %s", uptime) - session.close() - -#. git commit signing it, put a proper description, then send it with - git send-email. Profit! diff --git a/documentation/source/basic/WritingTests.rst b/documentation/source/basic/WritingTests.rst deleted file mode 100644 index 27b8fbfd1d..0000000000 --- a/documentation/source/basic/WritingTests.rst +++ /dev/null @@ -1,18 +0,0 @@ -Writing Virt Tests -================== - -This documentation aims to help you write virt tests of your own. It's organized -to explain briefly the source structure, then writing simple tests, then doing -more complex stuff, such as defining custom guests. - -Contents: - -.. toctree:: - :maxdepth: 2 - - SourceStructure - TestProviders - DevelEnvSetup - WritingSimpleTests - DefiningNewGuests - WritingAdvancedTests diff --git a/documentation/source/basic/index.rst b/documentation/source/basic/index.rst deleted file mode 100644 index 501581bde6..0000000000 --- a/documentation/source/basic/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -==================== -Getting started docs -==================== - -Virt Test is a complex project, with a lot of code and conventions to learn. -Here we explain how to run your first test jobs and to write your first tests. - -Contents: - -.. toctree:: - :maxdepth: 2 - - Introduction - GetStarted - TestRunner - InstallPrerequesitePackages - InstallPrerequesitePackagesDebian - WritingTests \ No newline at end of file diff --git a/documentation/source/conf.py b/documentation/source/conf.py deleted file mode 100644 index 225cf19496..0000000000 --- a/documentation/source/conf.py +++ /dev/null @@ -1,268 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Virt Test documentation build configuration file, created by -# sphinx-quickstart on Mon Apr 14 20:17:08 2014. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import sys -import os - - -class DocBuildError(Exception): - pass - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -root_path = os.path.abspath(os.path.join("..", "..")) -sys.path.insert(0, root_path) -import commands -_sphinx_apidoc = commands.getoutput('which sphinx-apidoc').strip() -_output_dir = os.path.join(root_path, 'documentation', 'source', 'api') -_api_dir = os.path.join(root_path, 'virttest') -_status, _output = commands.getstatusoutput("%s -o %s %s" % (_sphinx_apidoc, _output_dir, _api_dir)) -if _status: - raise DocBuildError("API rst auto generation failed: %s" % _output) - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Virt Test' -copyright = u'2009-2014, Virt Test Team' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. - -from virttest.version import get_version - -# The short X.Y version. -version = get_version() -# The full version, including alpha/beta/rc tags. -release = get_version() - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = [] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------------- - -# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - -if not on_rtd: # only import and set the theme if we're building docs locally - try: - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - except ImportError: - html_theme = 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'VirtTestdoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - #'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'VirtTest.tex', u'Virt Test Documentation', - u'Virt Test Team', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'virttest', u'Virt Test Documentation', - [u'Virt Test Team'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'VirtTest', u'Virt Test Documentation', - u'Virt Test Team', 'VirtTest', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/documentation/source/contributing/ContactInfo.rst b/documentation/source/contributing/ContactInfo.rst deleted file mode 100644 index c374dfd479..0000000000 --- a/documentation/source/contributing/ContactInfo.rst +++ /dev/null @@ -1,6 +0,0 @@ -=================== -Contact information -=================== - -- `Virt-test-devel mailing list (new mailing list hosted by red hat) `_ -- `IRC channel: irc.oftc.net #virt-test `_ diff --git a/documentation/source/contributing/DevelopmentWorkflow.rst b/documentation/source/contributing/DevelopmentWorkflow.rst deleted file mode 100644 index f17c739a24..0000000000 --- a/documentation/source/contributing/DevelopmentWorkflow.rst +++ /dev/null @@ -1,8 +0,0 @@ -============================== -Virt Test Development Workflow -============================== - -As this is a generic procedure we use among autotest subprojects, -relevant documentation can be seen on our main wiki: - -https://github.com/autotest/autotest/wiki/DevelopmentWorkflow diff --git a/documentation/source/contributing/DownloadSource.rst b/documentation/source/contributing/DownloadSource.rst deleted file mode 100644 index c6847e8762..0000000000 --- a/documentation/source/contributing/DownloadSource.rst +++ /dev/null @@ -1,13 +0,0 @@ -====================== -Downloading the Source -====================== - -The main source is maintained on git and may be cloned as below: - -:: - - git clone git://github.com/autotest/virt-test.git - -If you want to learn how to use git as an effective contribution tool, consider -reading `the git workflow autotest docs `_ - diff --git a/documentation/source/contributing/SubmissionChecklist.rst b/documentation/source/contributing/SubmissionChecklist.rst deleted file mode 100644 index 8ce69af251..0000000000 --- a/documentation/source/contributing/SubmissionChecklist.rst +++ /dev/null @@ -1,9 +0,0 @@ -========================== -Code Submission Check List -========================== - -As this is a procedure shared among autotest -managed projects, we hereby link the docs to -the main autotest wiki: - -https://github.com/autotest/autotest/wiki/SubmissionChecklist diff --git a/documentation/source/contributing/index.rst b/documentation/source/contributing/index.rst deleted file mode 100644 index 52786884e8..0000000000 --- a/documentation/source/contributing/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -================= -Contribution docs -================= - -This section documents the procedures necessary to contribute to virt-test. -Much of the development workflow comes from the parent project autotest. - -Contents: - -.. toctree:: - :maxdepth: 2 - - ContactInfo - DownloadSource - DevelopmentWorkflow - SubmissionChecklist \ No newline at end of file diff --git a/documentation/source/extra/DownloadableImages.rst b/documentation/source/extra/DownloadableImages.rst deleted file mode 100644 index 19545e8ca2..0000000000 --- a/documentation/source/extra/DownloadableImages.rst +++ /dev/null @@ -1,40 +0,0 @@ -Links with downloadable images for virt tests ---------------------------------------------- - -This is a central location that we aim to keep -up to date with locations of iso files that -might be needed for testing. - -Update: Now we have a central location to define -such downloads. In the source tree: - -:: - - shared/download.d/ - -Contains a bunch of .ini files, each one with -download definitions. It is expected that this -will be more up to date than this page. You can -see the available downloads and download the files -using: - - -:: - - tools/download_manager.py - - -Winutils ISO ------------- - -http://lmr.fedorapeople.org/winutils/winutils.iso - -JeOS image ----------- - -You can find the JeOS images here: - -http://lmr.fedorapeople.org/jeos/ - -You'll find .7za (p7zipped) files for versions of -the JeOS available, as well as their MD5SUM files. diff --git a/documentation/source/extra/GlusterFs.rst b/documentation/source/extra/GlusterFs.rst deleted file mode 100644 index e9377d32d5..0000000000 --- a/documentation/source/extra/GlusterFs.rst +++ /dev/null @@ -1,79 +0,0 @@ -================= -GlusterFS support -================= - -GlusterFS is an open source, distributed file system capable of scaling to several petabytes (actually, 72 brontobytes!) and handling thousands of clients. GlusterFS clusters together storage building blocks over Infiniband RDMA or TCP/IP interconnect, aggregating disk and memory resources and managing data in a single global namespace. GlusterFS is based on a stackable user space design and can deliver exceptional performance for diverse workloads. - -More details of GlusterFS can be found under - -http://www.gluster.org/about/ - -GlusterFS is added as a new block backend for qemu and to make use of this feature we require the following components. - -More details of GlusterFS-QEMU Integration can be found under - -http://raobharata.wordpress.com/2012/10/29/qemu-glusterfs-native-integration/ - -1. Qemu- 1.3, 03Dec2012 -2. GlusterFS-3.4 -3. Libvirt-1.0.1, 15Dec2012 - -How to use in virt-test ------------------------ - -You can use virt-test to test GlusterFS support with following steps. - -1) Edit qemu/cfg/tests.cfg with following changes, - -:: - - only glusterfs_support - remove ‘only no_glusterfs_support’ line from the file - -2) Optionally, edit shared/cfg/guest-hw.cfg for the gluster volume name and brick path, -default is going to be, - -:: - - gluster_volume_name = test-vol - gluster_brick = /tmp/gluster - -How to use manually -------------------- - -The following is just an example to show how we create gluster volume and run a guest on that volume manually. - -Starting Gluster daemon ------------------------ - -:: - - service glusterd start - - -Gluster volume creation ------------------------ - -:: - - gluster volume create [volume-name] [hostname/host_ip]:/[brick_path] - -E:g: `gluster volume create test-vol satheesh.ibm.com://home/satheesh/images_gluster` - - -Qemu Img creation ------------------ - -:: - - qemu-img create gluster://[hostname]:0/[volume-name]/[image-name] [size] - -E:g: `qemu-img create gluster://satheesh.ibm.com:0/test-vol/test_gluster.img 10G` - - -Example of qemu cmd Line ------------------------- - -:: - - qemu-system-x86_64 --enable-kvm -smp 4 -m 2048 -drive file=gluster://satheesh.ibm.com/test-vol/test_gluster.img,if=virtio -net nic,macaddr=52:54:00:09:0a:0b -net tap,script=/path/to/qemu-ifupVirsh diff --git a/documentation/source/extra/InstallWinVirtio.rst b/documentation/source/extra/InstallWinVirtio.rst deleted file mode 100644 index aaf2242e5a..0000000000 --- a/documentation/source/extra/InstallWinVirtio.rst +++ /dev/null @@ -1,187 +0,0 @@ -================================================ -Installing Windows virtio drivers with virt-test -================================================ - -So, you want to use virt-test to install windows guests. You also -want them to be installed with the paravirtualized drivers developed for -windows. You have come to the right place. - -A bit of context on windows virtio drivers install --------------------------------------------------- - -This method of install so far covers the storage (viostor) and network -(NetKVM) drivers. virt-test uses a boot floppy with a Windows answer -file in order to perform unattended install of windows guests. For winXP -and win2003, the unattended files are simple .ini files, while for -win2008 and later, the unattended files are XML files. - -In order to install the virtio drivers during guest install, KVM -autotest has to inform the windows install programs \*where\* to find -the drivers. So, we work from the following assumptions: - -#. You already have an iso file that contains windows virtio drivers - (inf files) for both netkvm and viostor. If you are unsure how to - generate that iso, there's an example script under contrib, inside - the kvm test directory. Here is an example of how the files inside - this cd would be organized, assuming the iso image is mounted under - ``/tmp/virtio-win`` (the actual cd has more files, but we took only - the parts that concern to the example, win7 64 bits). - -:: - - /tmp/virtio-win/ - /tmp/virtio-win/vista - /tmp/virtio-win/vista/amd64 - /tmp/virtio-win/vista/amd64/netkvm.cat - /tmp/virtio-win/vista/amd64/netkvm.inf - /tmp/virtio-win/vista/amd64/netkvm.pdb - /tmp/virtio-win/vista/amd64/netkvm.sys - /tmp/virtio-win/vista/amd64/netkvmco.dll - /tmp/virtio-win/vista/amd64/readme.doc - /tmp/virtio-win/win7 - /tmp/virtio-win/win7/amd64 - /tmp/virtio-win/win7/amd64/balloon.cat - /tmp/virtio-win/win7/amd64/balloon.inf - /tmp/virtio-win/win7/amd64/balloon.pdb - /tmp/virtio-win/win7/amd64/balloon.sys - /tmp/virtio-win/win7/amd64/blnsvr.exe - /tmp/virtio-win/win7/amd64/blnsvr.pdb - /tmp/virtio-win/win7/amd64/vioser.cat - /tmp/virtio-win/win7/amd64/vioser.inf - /tmp/virtio-win/win7/amd64/vioser.pdb - /tmp/virtio-win/win7/amd64/vioser.sys - /tmp/virtio-win/win7/amd64/vioser-test.exe - /tmp/virtio-win/win7/amd64/vioser-test.pdb - /tmp/virtio-win/win7/amd64/viostor.cat - /tmp/virtio-win/win7/amd64/viostor.inf - /tmp/virtio-win/win7/amd64/viostor.pdb - /tmp/virtio-win/win7/amd64/viostor.sys - /tmp/virtio-win/win7/amd64/wdfcoinstaller01009.dll - ... - -If you are planning on installing WinXP or Win2003, you should also have -a pre-made floppy disk image with the virtio drivers \*and\* a -configuration file that the installer program will read to fetch the -right drivers from it. Unfortunately, I don't have much info on how to -build that file, you probably would have the image already assembled if -you are willing to test those guest OS. - -So you have to map the paths of your cd containing the drivers on the -config variables. We hope to improve this in cooperation with the virtio -drivers team. - -Step by step procedure ----------------------- - -We are assuming you already have the virtio cd properly assembled with -you, as well as windows iso files that \*do match the ones provided in -our test\_base.cfg.sample\*. Don't worry though, we try as much as -possible to use files from MSDN, to standardize. - -We will use win7 64 bits (non sp1) as the example, so the CD you'd need -is: - -:: - - cdrom_cd1 = isos/windows/en_windows_7_ultimate_x86_dvd_x15-65921.iso - sha1sum_cd1 = 5395dc4b38f7bdb1e005ff414deedfdb16dbf610 - -This file can be downloaded from the MSDN site, so you can verify the -SHA1 sum of it matches. - -#. Git clone autotest to a convenient location, say $HOME/Code/autotest. - See :doc:`the download source documentation <../contributing/DownloadSource>` - Please do use git and clone the repo to the location mentioned. -#. Execute the ``get_started.py`` script (see the get started documentation <../basic/GetStarted>`. - It will create the - directories where we expect the cd files to be available. You don't - need to download the Fedora 14 DVD, but you do need to download the - winutils.iso cd (on the example below, I have skipped the download - because I do have the file, so I can copy it to the expected - location, which is in this case - ``/tmp/kvm_autotest_root/isos/windows``). Please, do read the - documentation mentioned on the script to avoid missing packages - installed and other misconfiguration. -#. Create a windows dir under ``/tmp/kvm_autotest_root/isos`` -#. Copy your windows 7 iso to ``/tmp/kvm_autotest_root/isos/windows`` -#. Edit the file cdkeys.cfg and put the windows 7 64 bit key on that - file -#. Edit the file win-virtio.cfg and verify if the paths are correct. You - can see that by looking this session: - - :: - - 64: - unattended_install.cdrom, whql.support_vm_install: - # Look at your cd structure and see where the drivers are - # actually located (viostor and netkvm) - virtio_storage_path = 'F:\win7\amd64' - virtio_network_path = 'F:\vista\amd64' - - # Uncomment if you have a nw driver installer on the iso - #virtio_network_installer_path = 'F:\RHEV-Network64.msi' - -#. If you are using the cd with the layout mentioned on the beginning of - this article, the paths are already correct. However, if they're - different (more likely), you have to adjust paths. Don't forget to - read and do all the config on win-virtio.cfg file as instructed by - the comments. -#. On tests.cfg, you have to enable virtio install of windows 7. On the - block below, you have to change ``only rtl8139`` to - ``only virtio_net`` and ``only ide`` to ``only virtio-blk``. You are - informing autotest that you only want a vm with virtio hard disk and - network device installed. - - :: - - # Runs qemu-kvm, Windows Vista 64 bit guest OS, install, boot, shutdown - - @qemu_kvm_windows_quick: - # We want qemu-kvm for this run - qemu_binary = /usr/bin/qemu-kvm - qemu_img_binary = /usr/bin/qemu-img - # Only qcow2 file format - only qcow2 - # Only rtl8139 for nw card (default on qemu-kvm) - only rtl8139 - # Only ide hard drives - only ide - # qemu-kvm will start only with -smp 2 (2 processors) - only smp2 - # No PCI assignable devices - only no_pci_assignable - # No large memory pages - only smallpages - # Operating system choice - only Win7.64 - # Subtest choice. You can modify that line to add more subtests - only unattended_install.cdrom, boot, shutdown - -#. You have to change the bottom of tests.cfg to look like the below, - Which means you are informing autotest to only run the test set - mentioned above, rather than the default, that installs Fedora 15. - - :: - - only qemu_kvm_windows_quick - -#. As informed on the output of ``get_started.py``, the command you can - execute to run autotest is (please run this AS ROOT or sudo) - - :: - - $HOME/Code/autotest/client/bin/autotest $HOME/Code/autotest/client/tests/kvm/control - -#. Profit! You automated install of Windows 7 with the virtio drivers - will be carried out. - -If you want to install other guests, as you might imagine, you can -change ``only Win7.64`` with other guests, say ``only Win2008.64.sp2``. -Now, during the first time you perform your installs, it's good to watch -the installation to see if there aren't problems such as a **wrong cd -key** preventing your install from happening. virt-test prints the -qemu command line used, so you can see which vnc display you can connect -to to watch your vm being installed. - -Please give us feedback on whether this procedure was helpful - email me -at lmr AT redhat DOT com. - diff --git a/documentation/source/extra/RegressionTestFarm.rst b/documentation/source/extra/RegressionTestFarm.rst deleted file mode 100644 index eb7ee980cb..0000000000 --- a/documentation/source/extra/RegressionTestFarm.rst +++ /dev/null @@ -1,356 +0,0 @@ -Setting up a Regression Test Farm for KVM -========================================= - -You have all upstream code, and you're wondering if the internal Red Hat -testing of KVM has a lot of internal 'secret sauce'. No, it does not. - -However, it is a complex endeavor, since there are *lots* of details involved. -The farm setup and maintenance is not easy, given the large amounts of things -that can fail (machines misbehave, network problems, git repos unavailable, -so on and so forth). *You have been warned*. - -With all that said, we'll share what we have been doing. We did clean up our -config files and extensions and released them upstream, together with this -procedure, that we hope it will be useful to you guys. Also, this will cover -KVM testing on a single host, as tests involving multiple hosts and Libvirt -testing are a work in progress. - -The basic steps are: - -1) Install an autotest server. -2) Add machines to the server (test nodes). Those machines are the virt hosts - that will be tested. -3) Prepare the virt test jobs and schedule them. -4) Set up cobbler in your environment so you can install hosts. -5) Lots of trial and error until you get all little details sorted out. - -We took years repeating all the steps above and perfecting the process, and we -are willing to document it all to the best extent possible. I'm afraid however, -that you'll have to do your homework and adapt the procedure to your environment. - -Some conventions ----------------- - -We are assuming you will install autotest to its default upstream location - -/usr/local/autotest - -Therefore a lot of paths referred here will have this as the base dir. - -CLI vs Web UI --------------- - -During this text, we'll use frequently the terms CLI and Web UI. - -By CLI we mean specifically the program: - -/usr/local/autotest/cli/autotest-rpc-client - -That is located in the autotest code checkout. - -By Web UI, we mean the web interface of autotest, that can be accessed through - -http://your-autotest-server.com/afe - - -Step 1 - Install an autotest server ------------------------------------ - -Provided that you have internet on your test lab, this should be the easiest -step. Pick up either a VM accessible in your lab, or a bare metal machine -(it really doesn't make a difference, we use a VM here). We'll refer -it from now on as the "Server" box. - - -The hard drive of the Server should hold enough room for test results. We found -out that at least 250 GB holds data for more than 6 months, provided that -QEMU doesn't crash a lot. - -You'll follow the procedure described on - -https://github.com/autotest/autotest/wiki/AutotestServerInstallRedHat - -for Red Hat derivatives (such as Fedora and RHEL), and - -https://github.com/autotest/autotest/wiki/AutotestServerInstall - -for Debian derivatives (Debian, Ubuntu). - -Note that using the install script referred right in the beginning of the -documentation is the preferred method, and should work pretty well if you have -internet on your lab. In case you don't have internet there, you'd need to -follow the instructions after the 'installing with the script' instructions. -Let us know if you have any problems. - -Step 2 - Add test machines --------------------------- - -It should go without saying, but the machines you have to add have to be -virtualization capable (support KVM). - -You can add machines either by using the CLI or the Web UI, following -the documentation: - -https://github.com/autotest/autotest/wiki/ConfiguringHosts - -If you don't want to read that, I'll try to write a quick howto. - -Say you have two x86_64 hosts, one AMD and the other, Intel. Their hostnames are: - -foo-amd.bazcorp.com -foo-intel.bazcorp.com - -I would create 2 labels, amd64 and intel64, I would also create a label to -indicate the machines can be provisioned by cobbler. This is because you -can tell autotest to run a job in any machine that matches a given label. - -Logged as the autotest user: - -:: - - $ /usr/local/autotest/cli/autotest-rpc-client label create -t amd64 - Created label: - 'amd64' - $ /usr/local/autotest/cli/autotest-rpc-client label create -t intel64 - Created label: - 'intel64' - $ /usr/local/autotest/cli/autotest-rpc-client label create hostprovisioning - Created label: - 'hostprovisioning' - -Then I'd create each machine with the appropriate labels - -:: - - $ /usr/local/autotest/cli/autotest-rpc-client host create -t amd64 -b hostprovisioning foo-amd.bazcorp.com - Added host: - foo-amd.bazcorp.com - - $ /usr/local/autotest/cli/autotest-rpc-client host create -t amd64 -b hostprovisioning foo-intel.bazcorp.com - Added host: - foo-amd.bazcorp.com - - -Step 3 - Prepare the test jobs ------------------------------- - -Now you have to copy the plugin we have developed to extend the CLI to parse -additional information for the virt jobs: - -:: - - cp /usr/local/autotest/contrib/virt/site_job.py /usr/local/autotest/cli/ - -This should be enough to enable all the extra functionality. - -You also need to copy the site-config.cfg file that we published as a reference, -to the qemu config module: - -:: - - cp /usr/local/autotest/contrib/virt/site-config.cfg /usr/local/autotest/client/tests/virt/qemu/cfg - -Be aware that you *need* to read this file well, and later, configure it to your -testing needs. We specially stress that you might want to create private git -mirrors of the git repos you want to test, so you tax the upstream mirrors -less, and have increased reliability. - -Right now it is able to run regression testing on Fedora 18, and upstream kvm, -provided that you have a cobbler instance functional, with a profile called -f18-autotest-kvm that can be properly installed on your machines. Having that -properly set up may open another can of worms. - -One simple way to schedule the jobs, that we does use at our server, is to -use cron to schedule daily testing jobs of the things you want to test. Here -is an example that should work 'out of the box'. Provided that you have an -internal mailing list that you created with the purpose of receiving email -notifications, called autotest-virt-jobs@foocorp.com, you can stick that -on the crontab of the user autotest in the Server: - -:: - - 07 00 * * 1-7 /usr/local/autotest/cli/autotest-rpc-client job create -B never -a never -s -e autotest-virt-jobs@foocorp.com -f "/usr/local/autotest/contrib/virt/control.template" -T --timestamp -m '1*hostprovisioning' -x 'only qemu-git..sanity' "Upstream qemu.git sanity" - 15 00 * * 1-7 /usr/local/autotest/cli/autotest-rpc-client job create -B never -a never -s -e autotest-virt-jobs@foocorp.com -f "/usr/local/autotest/contrib/virt/control.template" -T --timestamp -m '1*hostprovisioning' -x 'only f18..sanity' "Fedora 18 koji sanity" - 07 01 * * 1-7 /usr/local/autotest/cli/autotest-rpc-client job create -B never -a never -s -e autotest-virt-jobs@foocorp.com -f "/usr/local/autotest/contrib/virt/control.template" -T --timestamp -m '1*hostprovisioning' -x 'only qemu-git..stable' "Upstream qemu.git stable" - 15 01 * * 1-7 /usr/local/autotest/cli/autotest-rpc-client job create -B never -a never -s -e autotest-virt-jobs@foocorp.com -f "/usr/local/autotest/contrib/virt/control.template" -T --timestamp -m '1*hostprovisioning' -x 'only f18..stable' "Fedora 18 koji stable" - -That should be enough to have one sanity and stable job for: - -* Fedora 18. -* qemu.git userspace and kvm.git kernel. - -What does these 'stable' and 'sanity' jobs do? In short: - -* Host OS (Fedora 18) installation through cobbler -* Latest kernel for the Host OS installation (either the last kernel update build for fedora, or check out, compile and install kvm.git). - -sanity job ----------- - -* Install latest Fedora 18 qemu-kvm, or compiles the latest qemu.git -* Installs a VM with Fedora 18, boots, reboots, does simple, single host migration with all supported protocols -* Takes about two hours. In fact, internally we test more guests, but they are not widely available (RHEL 6 and Windows 7), so we just replaced them with Fedora 18. - -stable job ----------- - -* Same as above, but many more networking, timedrift and other tests - -Setup cobbler to install hosts ------------------------------- - -Cobbler is an installation server, that control DHCP and/or PXE boot for your -x86_64 bare metal virtualization hosts. You can learn how to set it up in the -following resource: - -https://github.com/cobbler/cobbler/wiki/Start%20Here - -You will set it up for simple installations, and you probably just need to -import a Fedora 18 DVD into it, so it can be used to install your hosts. -Following the import procedure, you'll have a 'profile' created, which is a -label that describes an OS that can be installed on your virtualization host. -The label we chose, as already mentioned is f18-autotest-kvm. If you want to -change that name, you'll have to change site-config.cfg accordingly. - -Also, you will have to add your test machines to your cobbler server, and -will have to set up remote control (power on/off) for them. - -The following is important: - -*The hostname of your machine in the autotest server has to be the name of your system in cobbler*. - -So, for the hypothetical example you'll have to have set up -systems with names foo-amd.bazcorp.com foo-intel.bazcorp.com in cobbler. That's -right, the 'name' of the system has to be the 'hostname'. Otherwise, autotest -will ask cobbler and cobbler will not know which machine autotest is taking about. - -Other assumptions we have here: - -1) We have a (read only, to avoid people deleting isos by mistake) NFS share -that has the Fedora 18 DVD and other ISOS. The structure for the base dir -could look something like: - -:: - - . - |-- linux - | `-- Fedora-18-x86_64-DVD.iso - `-- windows - |-- en_windows_7_ultimate_x64_dvd_x15-65922.iso - |-- virtio-win.iso - `-- winutils.iso - -This is just in case you are legally entitled to download and use Windows 7, -for example. - -2) We have another NFS share with space for backups of qcow2 images that got -corrupted during testing, and you want people to analyze them. The structure -would be: - -:: - - . - |-- foo-amd - `-- bar-amd - -That is, one directory for each host machine you have on your grid. Make sure they -end up being properly configured in the kickstart. - -Now here is one excerpt of kickstart with some of the gotchas we learned -with experience. Some notes: - -* This is not a fully formed, functional kickstart, just in case you didn't notice. -* This is provided in the hopes you read it, understand it and adapt things to your needs. If you paste this into your kickstart and tell me it doesn't work, I WILL silently ignore your email, and if you insist, your emails will be filtered out and go to the trash can. - - -:: - - install - - text - reboot - lang en_US - keyboard us - rootpw --iscrypted [your-password] - firewall --disabled - selinux --disabled - timezone --utc America/New_York - firstboot --disable - services --enabled network --disabled NetworkManager - bootloader --location=mbr - ignoredisk --only-use=sda - zerombr - clearpart --all --drives=sda --initlabel - autopart - network --bootproto=dhcp --device=eth0 --onboot=on - - %packages - @core - @development-libs - @development-tools - @virtualization - wget - dnsmasq - genisoimage - python-imaging - qemu-kvm-tools - gdb - iasl - libvirt - python-devel - ntpdate - gstreamer-plugins-good - gstreamer-python - dmidecode - popt-devel - libblkid-devel - pixman-devel - mtools - koji - tcpdump - bridge-utils - dosfstools - %end - - %post - - echo "[nfs-server-that-holds-iso-images]:[nfs-server-that-holds-iso-images]/base_path/iso /var/lib/virt_test/isos nfs ro,defaults 0 0" >> /etc/fstab - echo "[nfs-server-that-holds-iso-images]:[nfs-server-that-holds-iso-images]/base_path/steps_data /var/lib/virt_test/steps_data nfs rw,nosuid,nodev,noatime,intr,hard,tcp 0 0" >> /etc/fstab - echo "[nfs-server-that-has-lots-of-space-for-backups]:/base_path/[dir-that-holds-this-hostname-backups] /var/lib/virt_test/images_archive nfs rw,nosuid,nodev,noatime,intr,hard,tcp 0 0" >> /etc/fstab - mkdir -p /var/lib/virt_test/isos - mkdir -p /var/lib/virt_test/steps_data - mkdir -p /var/lib/virt_test/images - mkdir -p /var/lib/virt_test/images_archive - - mkdir --mode=700 /root/.ssh - echo 'ssh-dss [the-ssh-key-of-the-Server-autotest-user]' >> /root/.ssh/authorized_keys - chmod 600 /root/.ssh/authorized_keys - - ntpdate [your-ntp-server] - hwclock --systohc - - systemctl mask tmp.mount - %end - -Painful trial and error process to adjust details -------------------------------------------------- - -After all that, you can start running your test jobs and see what things will -need to be fixed. You can run your jobs easily by logging into your Server, with -the autotest user, and use the command: - -:: - - /usr/local/autotest/cli/autotest-rpc-client job create -B never -a never -s -e autotest-virt-jobs@foocorp.com -f "/usr/local/autotest/contrib/virt/control.template" -T --timestamp -m '1*hostprovisioning' -x 'only f18..sanity' "Fedora 18 koji sanity" - -As you might have guessed, this will schedule a Fedora 18 sanity job. So go -through it and fix things step by step. If anything, you can take a look at -this: - -https://github.com/autotest/autotest/wiki/DiagnosingFailures - -And see if it helps. You can also ask on the mailing list, but *please*, -*pretty please* do your homework before you ask us to guide you through all -the process step by step. This is already a step by step procedure. - -All right, good luck, and happy testing! diff --git a/documentation/source/extra/RunQemuUnittests.rst b/documentation/source/extra/RunQemuUnittests.rst deleted file mode 100644 index db6dae3abd..0000000000 --- a/documentation/source/extra/RunQemuUnittests.rst +++ /dev/null @@ -1,261 +0,0 @@ -===================================== -Running QEMU unittests with virt-test -===================================== - -For a while now, qemu-kvm does contain a unittest suite that can be used -to assess the behavior of some KVM subsystems. Ideally, they are -supposed to PASS, provided you are running both the latest qemu-kvm and -the latest linux Avi's tree. virt-test for quite a long time has -support for running them in an automated way. It's a good opportunity to -put your git branch to unittest, starting from a clean state (KVM -autotest will fetch from your git tree, leaving your actual development -tree intact and doing things from scratch, and that is less likely to -mask problems). - -A bit of context on virt-test build tests ------------------------------------------ - -People usually don't know that virt-test has support to build and -install QEMU/KVM for testing purposes, from many different software sources. -You can: - -#. Build qemu-kvm from a git repo (most common choice for developers - hacking on code) -#. Install qemu-kvm from an rpm file (people testing a newly built rpm - package) -#. Install qemu-kvm straight from the Red Hat build systems (Koji is the - instance of the build system for Fedora, Brew is the same, but for - RHEL. With this we can perform quality control on both Fedora and - RHEL packages, trying to anticipate breakages before the packages hit - users) - -For this article, we are going to focus on git based builds. Also, we -are focusing on Fedora and RHEL. We'll try to write the article in a -pretty generic fashion, you are welcome to improve this with details on -how to do the same on your favorite linux distribution. - -Before you start ----------------- - -You need to verify that you can actually build qemu-kvm from source, as -well as the unittest suite. - -#. Make sure you have the appropriate packages installed. You can read - :doc:`the install prerequesite packages (client) section <../basic/InstallPrerequesitePackages>` for more - information. - -Step by step procedure ----------------------- - -#. Git clone autotest to a convenient location, say ``$HOME/Code/autotest``. - See :doc:`the download source documentation <../contributing/DownloadSource>` - Please do use git and clone the repo to the location mentioned. -#. Execute the ``get_started.py`` script (see - :doc:`the get started documentation <../basic/GetStarted>`. If you just want - to run - unittests, you can safely skip each and every iso download possible, - as *qemu-kvm will straight boot small kernel images (the unittests)* - rather than full blown OS installs. -#. As running unittests is something that's fairly independent of other - virt-test testing you can do, and it's something people are - interested in, we prepared a *special control file* and a *special - configuration file* for it. On the kvm directory, you can see the - files ``unittests.cfg`` ``control.unittests``. You only need to edit - ``unittests.cfg``. -#. The file ``unittests.cfg`` is a stand alone configuration for running - unittests. It is comprised by a build variant and a unittests - variant. Edit the file, it'll look like: - - :: - - ... bunch of params needed for the virt-test preprocessor - # Tests - variants: - - build: - type = build - vms = '' - start_vm = no - # Load modules built/installed by the build test? - load_modules = no - # Save the results of this build on test.resultsdir? - save_results = no - variants: - - git: - mode = git - user_git_repo = git://git.kernel.org/pub/scm/virt/kvm/qemu-kvm.git - user_branch = next - user_lbranch = next - test_git_repo = git://git.kernel.org/pub/scm/virt/kvm/kvm-unit-tests.git - - - unittest: - type = unittest - vms = '' - start_vm = no - unittest_timeout = 600 - testdev = yes - extra_params += " -S" - # In case you want to execute only a subset of the tests defined on the - # unittests.cfg file on qemu-kvm, uncomment and edit test_list - #test_list = idt_test hypercall vmexit realmode - - only build.git unittest - -#. As you can see above, you have places to specify both the userspace - git repo and the unittest git repo. You are then free to replace - ``user_git_repo`` with your own git repo. It can be a remote git - location, or it can simply be the path to a cloned tree inside your - development machine. -#. As of Fedora 15, that ships with gcc 4.6.0, the compilation is more - strict, so things such as an unused variable in the code \*will\* - lead to a build failure. You can disable that level of strictness by - providing *extra configure script options* to your qemu-kvm userspace - build. Right below the ``user_git_repo line``, you can set the - variable ``extra_configure_options`` to include ``--disable-werror``. - Let's say you also want virt-test to fetch from my local tree, - ``/home/lmr/Code/qemu-kvm``, master branch, same for the - kvm-unit-tests repo. If you make those changes, your build variant - will look like: - - :: - - - git: - mode = git - user_git_repo = /home/lmr/Code/qemu-kvm - extra_configure_options = --disable-werror - user_branch = master - user_lbranch = master - test_git_repo = /home/lmr/Code/kvm-unit-tests - -#. Now you can just run virt-test as usual, you just have to change - the main control file (called ``control`` with the unittest one - ``control.unittests`` - - :: - - $HOME/Code/autotest/client/bin/autotest $HOME/Code/autotest/client/tests/kvm/control.unittests - -#. The output of a typical unittest execution looks like. Notice that - autotest informs you where the logs of each individual unittests are - located, so you can check that out as well. - - :: - - 07/14 18:49:44 INFO | unittest:0052| Running apic - 07/14 18:49:44 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/apic.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S -cpu qemu64,+x2apic - 07/14 18:49:46 INFO | unittest:0096| Waiting for unittest apic to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 18:59:46 ERROR| unittest:0108| Exception happened during apic: Timeout elapsed (600s) - 07/14 18:59:46 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/apic.log - 07/14 18:59:46 INFO | unittest:0052| Running smptest - 07/14 19:00:15 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:00:16 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/smptest.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:00:17 INFO | unittest:0096| Waiting for unittest smptest to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:00:17 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:00:18 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/smptest.log - 07/14 19:00:18 INFO | unittest:0052| Running smptest3 - 07/14 19:00:18 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 3 -kernel '/usr/local/autotest/tests/kvm/unittests/smptest.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:00:19 INFO | unittest:0096| Waiting for unittest smptest3 to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:00:19 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:00:20 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/smptest3.log - 07/14 19:00:20 INFO | unittest:0052| Running vmexit - 07/14 19:00:20 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/vmexit.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:00:21 INFO | unittest:0096| Waiting for unittest vmexit to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:00:31 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:00:31 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/vmexit.log - 07/14 19:00:31 INFO | unittest:0052| Running access - 07/14 19:00:31 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/access.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:00:32 INFO | unittest:0096| Waiting for unittest access to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:01:02 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:01:03 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/access.log - 07/14 19:01:03 INFO | unittest:0052| Running emulator - 07/14 19:01:03 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/emulator.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:01:05 INFO | unittest:0096| Waiting for unittest emulator to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:01:06 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:01:07 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/emulator.log - 07/14 19:01:07 INFO | unittest:0052| Running hypercall - 07/14 19:01:07 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/hypercall.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:01:08 INFO | unittest:0096| Waiting for unittest hypercall to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:01:08 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:01:09 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/hypercall.log - 07/14 19:01:09 INFO | unittest:0052| Running idt_test - 07/14 19:01:09 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/idt_test.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:01:10 INFO | unittest:0096| Waiting for unittest idt_test to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:01:10 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:01:11 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/idt_test.log - 07/14 19:01:11 INFO | unittest:0052| Running msr - 07/14 19:01:11 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/msr.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:01:12 INFO | unittest:0096| Waiting for unittest msr to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:01:13 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:01:13 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/msr.log - 07/14 19:01:13 INFO | unittest:0052| Running port80 - 07/14 19:01:13 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/port80.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:01:14 INFO | unittest:0096| Waiting for unittest port80 to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:01:31 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:01:32 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/port80.log - 07/14 19:01:32 INFO | unittest:0052| Running realmode - 07/14 19:01:32 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/realmode.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:01:33 INFO | unittest:0096| Waiting for unittest realmode to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:01:33 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:01:34 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/realmode.log - 07/14 19:01:34 INFO | unittest:0052| Running sieve - 07/14 19:01:34 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/sieve.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:01:35 INFO | unittest:0096| Waiting for unittest sieve to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:02:05 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:02:05 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/sieve.log - 07/14 19:02:05 INFO | unittest:0052| Running tsc - 07/14 19:02:05 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/tsc.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:02:06 INFO | unittest:0096| Waiting for unittest tsc to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:02:06 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:02:07 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/tsc.log - 07/14 19:02:07 INFO | unittest:0052| Running xsave - 07/14 19:02:07 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/xsave.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:02:08 INFO | unittest:0096| Waiting for unittest xsave to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:02:09 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:02:09 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/xsave.log - 07/14 19:02:09 INFO | unittest:0052| Running rmap_chain - 07/14 19:02:09 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/rmap_chain.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S - 07/14 19:02:11 INFO | unittest:0096| Waiting for unittest rmap_chain to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:02:12 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:02:13 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/rmap_chain.log - 07/14 19:02:13 INFO | unittest:0052| Running svm - 07/14 19:02:13 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/svm.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S -enable-nesting -cpu qemu64,+svm - 07/14 19:02:13 INFO | aexpect:0783| (qemu) qemu: -enable-nesting: invalid option - 07/14 19:02:13 INFO | aexpect:0783| (qemu) (Process terminated with status 1) - 07/14 19:02:13 ERROR| unittest:0108| Exception happened during svm: VM creation command failed: "/usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/svm.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S -enable-nesting -cpu qemu64,+svm" (status: 1, output: 'qemu: -enable-nesting: invalid option\n') - 07/14 19:02:13 ERROR| unittest:0115| Not possible to collect logs - 07/14 19:02:13 INFO | unittest:0052| Running svm-disabled - 07/14 19:02:13 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/svm.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S -cpu qemu64,-svm - 07/14 19:02:14 INFO | unittest:0096| Waiting for unittest svm-disabled to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:02:15 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:02:16 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/svm-disabled.log - 07/14 19:02:16 INFO | unittest:0052| Running kvmclock_test - 07/14 19:02:16 INFO | kvm_vm:0782| Running qemu command: - /usr/local/autotest/tests/kvm/qemu -name 'vm1' -nodefaults -vga std -monitor unix:'/tmp/monitor-humanmonitor1-20110714-184944-6ms0',server,nowait -qmp unix:'/tmp/monitor-qmpmonitor1-20110714-184944-6ms0',server,nowait -serial unix:'/tmp/serial-20110714-184944-6ms0',server,nowait -m 512 -smp 2 -kernel '/usr/local/autotest/tests/kvm/unittests/kvmclock_test.flat' -vnc :0 -chardev file,id=testlog,path=/tmp/testlog-20110714-184944-6ms0 -device testdev,chardev=testlog -S --append "10000000 `date +%s`" - 07/14 19:02:17 INFO | unittest:0096| Waiting for unittest kvmclock_test to complete, timeout 600, output in /tmp/testlog-20110714-184944-6ms0 - 07/14 19:02:33 INFO | aexpect:0783| (qemu) (Process terminated with status 0) - 07/14 19:02:34 INFO | unittest:0113| Unit test log collected and available under /usr/local/autotest/results/default/kvm.qemu-kvm-git.unittests/debug/kvmclock_test.log - 07/14 19:02:34 ERROR| kvm:0094| Test failed: TestFail: Unit tests failed: apic svm - -You might take a look at the ``unittests.cfg`` config file options to do -some tweaking you might like, such as making the timeout to consider a -unittest as failed smaller and other things. - -Please give us feedback on whether this procedure was helpful - email me -at lmr AT redhat DOT com. - diff --git a/documentation/source/extra/index.rst b/documentation/source/extra/index.rst deleted file mode 100644 index 4491f435e6..0000000000 --- a/documentation/source/extra/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -========== -Extra docs -========== - -Extra information that does not quite fit in other areas of the docs. - -Contents: - -.. toctree:: - :maxdepth: 2 - - DownloadableImages - GlusterFs - RegressionTestFarm - InstallWinVirtio - RunQemuUnittests \ No newline at end of file diff --git a/documentation/source/index.rst b/documentation/source/index.rst deleted file mode 100644 index 4d9e6e3001..0000000000 --- a/documentation/source/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -Welcome to Virt Test's documentation! -===================================== - -``virt-test`` is a suite of tests made to exercise different linux virtualization -hypervisors and related tools. Although many people make this mistake, *this -test suite is not autotest*. Autotest is a larger test framework on which -``virt-test`` is built. - -If you need information about autotest, `you should check out its project -page `_. - -Contents: - -.. toctree:: - :maxdepth: 2 - - contributing/index - basic/index - advanced/index - extra/index - api/modules - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/documentation/source/requirements.txt b/documentation/source/requirements.txt deleted file mode 100644 index 4dbb9a7780..0000000000 --- a/documentation/source/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -autotest diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 055e52d670..0000000000 --- a/requirements.txt +++ /dev/null @@ -1,6 +0,0 @@ -Sphinx==1.2b1 -coverage==3.6 -nose==1.3.0 -nosexcover==1.0.8 -tox==1.5.0 -virtualenv==1.9.1