Ubuntu Manpage: autopkgtest-virt-ssh - autopkgtest virtualisation server using SSH

NAME

       autopkgtest-virt-ssh - autopkgtest virtualisation server using SSH

SYNOPSIS

       autopkgtest [...] -- ssh [options] [-- setup script options ...]

DESCRIPTION

       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 yourself especially without a  setup  script.
       So use this with care.

REQUIREMENTS

       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.

OPTIONS

-h|--help
Show the help message and exit

-d|--debug
Enable debugging output

-H hostname | --hostname=hostname
Connects and logs into the specified hostname or IP address

-l user | --login=user
Specifies the user to log in as on the remote machine.

-i identity | --identity=identity
Selects a file from which the identity (private key) for public key authentication is read. Should
usually be ~/.ssh/id_rsa, but you might consider using a different key for tests.

-P password | --password=password
Specifies the sudo password on the remote host.

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.

-p port | --port=port
ssh port to use to connect to the host

-o options | --options=options
Passed verbatim to ssh; see man ssh_config

-r|--reboot
Indicate that reboot can be used in the testbed. This is useful when running rebooting tests
without a setup script (which can already declare capabilities).

--capabilityCAPABILITY
Indicate that the testbed has the given capability (see README.virtualisation-server). This option
can be specified multiple times.

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!

-s setup_script | --setup-script=setup_script
Setup script to prepare testbed and ssh connection (See SETUP SCRIPT below for more information).
File names will be searched in both the current directory and in /usr/share/autopkgtest/ssh-setup/
so you do not need to give the full path for setup scripts shipped with autopkgtest.

--timeout-ssh=secs
Timeout for waiting for ssh connection, in seconds. Default is 300.

-- [setup script arguments]
All the remaining arguments following -- will be passed verbatim to the setup script to configure
the host.

CONFIGURATION FILES

       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.

INPUT, OUTPUT AND EXIT STATUS

       The behaviour of autopkgtest-virt-ssh is as  described  by  the  AutomatedTesting  virtualisation  regime
       specification.

SECURITY WARNING - USE OF ROOT

       If  autopkgtest-virt-ssh  is  used  in  a  way  that means it has root access on the testbed, the testbed
       environment must be an isolated one which does not ever run any untrusted code, or is itself not  trusted
       by anything.

       This promise is implied by user-switching capabilities that autopkgtest-virt-ssh may advertise, depending
       in a complex way on the provided configuration and command line options.

       If autopkgtest-virt-ssh only has access to a single user on the remote host, this problem does not arise.

NOTES

       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).

SETUP SCRIPT

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.

command: open
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:

* login: User name

* hostname: hostname or IP address

Optional fields:

* identity: Path to the private key

* password: sudo password for the user name to acquire root privileges. If not given, and passwordless
sudo does not work, the testbed will not have root privileges.

* port: SSH port on hostname, if different than 22

* capabilities: extra testbed capabilities such as "isolation-machine" or "revert", see
README.virtualisation-server.rst

If the testbed can be rebooted with keeping state, the script should advertise "reboot".

* options: passed verbatim to ssh, see man ssh_config

* extraopts: passed verbatim to other commands; this allows extra state (such as temporary directory
names, VM identifiers, etc.) to be passed to cleanup

command: cleanup
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.

command: revert
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.

command: wait-reboot
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.

command: debug-failure
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.

Included scripts
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.

EXAMPLES

       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

AUTHORS AND COPYRIGHT

       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.

Linux Programmer's Manual                             2014                               autopkgtest-virt-ssh(1)