Provided by: autopkgtest_3.17.4_all bug

NAME

       adt-virt-ssh - autopkgtest virtualisation server using SSH

SYNOPSYS

       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.

   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.