Provided by: autopkgtest_5.32ubuntu3~23.10.1_all bug

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

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

SEE ALSO

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

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.