Provided by: autopkgtest_3.17.4_all
adt-virt-ssh - autopkgtest virtualisation server using SSH
adt-virt-ssh [options] [-- setup script options ...]
adt-virt-ssh provides an autopkgtest virtualisation server using SSH.
Normally adt-virt-ssh will be invoked by adt-run.
can use an already existing ssh target, or call a setup script to
create/set up a test bed and the ssh server.
WARNING! adt-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.
adt-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
fire-up a cloud instance.
Show the help message and exit
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
-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
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).
-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 for waiting for ssh connection, in seconds. Default is
-- [setup script arguments]
All the remaining arguments following -- will be passed verbatim
to the setup script to configure the host.
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
and then run
adt-run [...] --- adt-virt-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 adt-virt-ssh is as described by the AutomatedTesting
virtualisation regime specification.
adt-run 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).
adt-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
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.
* login: User name
* hostname: hostname or IP address
* 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
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.
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
Run the tests of the libpng source package on an existing "mytesthost":
adt-run libpng --- 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:
adt-run ./ubuntu-calculator-app ./com.ubuntu.calculator_1.3.283_all.click \
--- ssh -s /usr/share/autopkgtest/ssh-setup/adb -- -s 0123456789abcdef
adt-run(1), /usr/share/doc/autopkgtest/, /usr/share/autopkgtest/ssh-
AUTHORS AND COPYRIGHT
adt-virt-ssh was written by Martin Pitt <email@example.com> and
Jean-Baptiste Lallement <firstname.lastname@example.org>.
This manpage is part of autopkgtest, a tool for testing Debian binary
packages. autopkgtest is Copyright (C) 2006-2014 Canonical Ltd and
See /usr/share/doc/autopkgtest/CREDITS for the list of contributors and
full copying conditions.