Provided by: autopkgtest_3.20.4_all bug

NAME

       adt-virt-ssh - autopkgtest virtualisation server using SSH

SYNOPSIS

       adt-virt-ssh [options] [-- setup script options ...]

DESCRIPTION

       adt-virt-ssh provides an autopkgtest virtualisation server using SSH.

       Normally adt-virt-ssh will be invoked by adt-run.

       adt-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!  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.

REQUIREMENTS

       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.

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

       -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

              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.

NOTES

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

SETUP SCRIPT

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

SEE ALSO

       adt-run(1), /usr/share/doc/autopkgtest/, /usr/share/autopkgtest/ssh-setup/SKELETON.

AUTHORS AND COPYRIGHT

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