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.
-
-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.
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:
- *
- 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
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
autopkgtest(1),
/usr/share/doc/autopkgtest/,
/usr/share/autopkgtest/ssh-setup/SKELETON.
autopkgtest-virt-ssh was written by Martin Pitt
<
[email protected]> and Jean-Baptiste Lallement
<
[email protected]>.
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.