autopkgtest-virt-ssh(1) | General Commands Manual | autopkgtest-virt-ssh(1) |
autopkgtest-virt-ssh - autopkgtest virtualisation server using SSH
autopkgtest [...] -- ssh [options] [-- setup script options ...]
autopkgtest-virt-ssh provides an autopkgtest virtualisation server using SSH.
Normally autopkgtest-virt-ssh will be invoked by autopkgtest.
autopkgtest-virt-ssh can use an already existing ssh target, or call a setup script to create/set up a test bed and the ssh server.
WARNING! autopkgtest-virt-ssh will modify the target system by installing packages and running arbitrary test code, so you are responsible for resetting the testbed youself especially without a setup script. So use this with care.
autopkgtest-virt-ssh doesn't assume anything regarding the target host other than that the given ssh connection (and networking) stay available all the time. You can provide credententials on the command line for already working SSH hosts or use a setup script to prepare the host for the connection (see SETUP SCRIPT below for more information), for example to create a forwarding rule to access an adb host over ssh or start a cloud instance.
It can be the password in clear text or a file containing the password. This password will be used to setup $SUDO_ASKPASS in the case sudo requires a password. The runner will check if the user has sudo access with and without a password. If the check fails, the capability "root-on-testbed" will not be available. If sudo works, then tests that run as user will have $SUDO_ASKPASS in their environment so that they can run sudo -A if needed.
This is useful when running rebooting tests without a setup script (which can already declare capabilities).
WARNING: Never use this on precious testbeds, as specifying options like revert or isolation-machine can irrecoverably destroy the testbed!
If you use lots of options or hosts, you can put parts of, or the whole command line into a text file, with one line per option. E. g. you can create a file testhost.cfg with contents like
-Htest.example.com -ltestuser -Ps3kr1t
and then run
autopkgtest [...] -- ssh @testhost.cfg
The contents of the configuration file will be expanded in-place as if you would have given its contents on the command line. Please ensure that you don't place spaces between short options and their values, they would become a part of the argument value.
The behaviour of autopkgtest-virt-ssh is as described by the AutomatedTesting virtualisation regime specification.
autopkgtest does not run apt-get update at the start of a package build, which can cause a build failure if you are using a development series template. You will need to run apt-get update in the template yourself (e. g. using --setup-commands).
autopkgtest-virt-ssh accepts a setup script in argument to prepare the testbed and the ssh connection. A setup script is an executable that gets called with a command as first argument, and additional options for that command.
When called with "open", the script has to create a testbed (if necessary), configure ssh, copy ssh key into it, configure sudo, etc.
It then returns the following information on standard output with the form key=value, one line per pair. These mostly mirror the command line options when not using a script.
Required fields:
Optional fields:
If the testbed can be rebooted with keeping state, the script should advertise "reboot".
Called when closing the testbed; should revert/remove things installed in open as much as possible if the testbed is not ephemeral. This gets called with all the options that open got called with, plus extraopts.
If there is a way to reset the testbed to its pristine state (such as using VM snapshots or rebuilding ephemeral testbeds), the script should put "revert" (and if appropriate, "revert-full-system") into the capabilities and implement this command. This can optionally output some or all of the ssh config keys from open() to update the configuration, in case the hostname/IP changes.
This can be implemented if capabilities advertise "reboot" and you need to do something more elaborate than just waiting for the ssh port to go down and come back up after calling "reboot". This needs to wait for testbed to shut down, boot, and re-prepare the testbed for ssh login.
This is called when the setup script fails with nonzero or on timeouts waiting for ssh or reboot. If available, this should output some debugging information, such as the boot log from the serial console. Implementing this is optional.
autopkgtest provides setup scripts for common types of testbeds in /usr/share/autopkgtest/ssh-setup/. Please see the comments in these scripts for how to use them. Also, please consider using /usr/share/autopkgtest/ssh-setup/SKELETON as a basis for writing your own.
Run the tests of the gdk-pixbuf source package on an existing "mytesthost":
autopkgtest gdk-pixbuf -- ssh -H mytesthost -l joe -P /tmp/joe_password
Run the tests of a click package on an Ubuntu phone with an ssh connection over ADB, using the setup script, with specifying an option to the setup script to pick a particular serial ID:
autopkgtest ./ubuntu-calculator-app ./com.ubuntu.calculator_1.3.283_all.click \
-- ssh -s /usr/share/autopkgtest/ssh-setup/adb -- -s 0123456789abcdef
autopkgtest(1), /usr/share/doc/autopkgtest/, /usr/share/autopkgtest/ssh-setup/SKELETON.
autopkgtest-virt-ssh was written by Martin Pitt <martin.pitt@ubuntu.com> and Jean-Baptiste Lallement <jean.baptiste.lallement@ubuntu.com>.
This manpage is part of autopkgtest, a tool for testing Debian binary packages. autopkgtest is Copyright (C) 2006-2014 Canonical Ltd and others.
See /usr/share/doc/autopkgtest/CREDITS for the list of contributors and full copying conditions.
2014 | Linux Programmer's Manual |