---
name: "adt-virt-ssh"
section: "1"
platform: "linux"
package: "autopkgtest"
version: "3.6jessie1"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/adt-virt-ssh"
---

# adt-virt-ssh(1)

autopkgtest virtualisation server using SSH

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

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

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

- **--** *\[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

- \*

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

If the testbed can be rebooted with keeping state, the script should put "reboot" into the capabilities and implement this command.

### 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)](/adt-run/1.md), **/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.