--- name: "autopkgtest-virt-docker" section: "1" platform: "linux" package: "autopkgtest" version: "5.49" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/autopkgtest-virt-docker" --- # autopkgtest-virt-docker(1) autopkgtest virtualisation server using Docker/Podman ## NAME autopkgtest-virt-docker, autopkgtest-virt-podman - autopkgtest virtualisation server using Docker/Podman ## SYNOPSIS **autopkgtest-virt-docker** \[*options*\] *docker-image* \[*-- extra docker-run args...*\] **autopkgtest-virt-podman** \[*options*\] *podman-image* \[*-- extra podman-run args...*\] ## DESCRIPTION **autopkgtest-virt-docker** provides an autopkgtest virtualization server using Docker or Podman. It adapts the functionality provided by the [**docker**(1)](/docker/1.md) or [**podman**(1)](/podman/1.md) command line for use by autopkgtest. Normally, **autopkgtest-virt-docker** will be invoked by **autopkgtest**. ## HOST REQUIREMENTS When run as **autopkgtest-virt-podman** or with the **--podman** option (recommended), this autopkgtest virtualization server requires [**podman**(1)](/podman/1.md), from the podman package. Unprivileged access to user namespaces must be enabled (this is true by default in Debian 11 or later), and the current user must have at least 65536 subordinate user IDs allocated in **/etc/subuid** and 65536 subordinate group IDs in **/etc/subgid**. See **/usr/share/doc/podman/README.Debian** for more details. When run as **autopkgtest-virt-docker** or with the **--docker** option, this autopkgtest virtualization server requires [**docker**(1)](/docker/1.md), from the docker.io package. The current user must have access to the Docker daemon socket **/run/docker.sock**, unless the **--sudo** option is used. Note that either of these makes the user root-equivalent on the host system. Using Podman instead of Docker is recommended. ## IMAGE REQUIREMENTS The image must contain [**apt**(8)](/apt/8.md) with a suitable configuration. The image should either provide the [**useradd**(8)](/useradd/8.md) program (part of the **passwd** package, which is **Priority: required**), or have an unprivileged user pre-created in the uid range 1000 to 59999. When using Podman, if the image contains an init system, it should be labelled with, for example, **LABEL org.debian.autopkgtest.init=systemd**. This allows **autopkgtest-virt-podman** to detect the init system automatically, making it unnecessary to specify the **--init** option. A suitable label is added by commands like **autopkgtest-build-podman --init=systemd**, but can also be done for images that were created differently. The known values that are used by [**autopkgtest-build-podman**(1)](/autopkgtest-build-podman/1.md) are **none**, **systemd**, **sysv-rc** and **openrc**, but any non-empty value except for **none** is assumed to indicate that **/sbin/init** will be present and functional. ## OPTIONS - **--docker** Use Docker containers and the Docker container manager. This is the default when invoked as **autopkgtest-virt-docker**. - **--podman** Use Podman containers and the Podman container manager. This is the default when invoked as **autopkgtest-virt-podman**. - **-d** \| **--debug** Enables debugging output. - **--init** Launches the container by running **/sbin/init** as the initial command. When using Podman, the default is to use the init system if the image has been labelled as containing one: see the "Image Requirements" section above. This option is unlikely to work when using Docker. - When using [**systemd**(1)](/systemd/1.md) as init, note that some of the execution environment options described in [**systemd.exec**(5)](/systemd.exec/5.md) require the container to have **CAP\_SYS\_ADMIN**, which has unclear security implications: it certainly reduces hardening between the host and the container, and might be sufficient to allow code that runs as root in the container to compromise processes outside the container that are running under the same uid as **autopkgtest-virt-podman**, for example by unmounting filesystems that are used to "mask" security-sensitive parts of **/proc** and **/sys**. If this is consistent with your security model, it can be allowed by passing the **--cap-add=CAP\_SYS\_ADMIN** option to [**podman-run**(1)](/podman-run/1.md): - ``` autopkgtest ... -- podman --init $IMAGE -- --cap-add=CAP_SYS_ADMIN ``` - **--no-init** Launches the container by running **sleep infinity** as the initial command. This is the default for Docker, and for Podman images that have **LABEL org.debian.autopkgtest.init=none** or no **org.debian.autopkgtest.init** label at all. The image will not be able to provide the **isolation-container** autopkgtest capability when this option is used. - **-p** \| **--pull** Pulls the specified image before setting up the container. By default the image is expected to already be present. - **-s** \| **--sudo** Run Docker or Podman commands through sudo. For Podman, this is rarely useful, because Podman usually runs unprivileged. For Docker, use this option if you run autopkgtest as a normal user who does not have access to the docker daemon (i.e. is not a member of the **docker** group). You can pass additional options to Docker or Podman: anything after a **--** gets passed verbatim to [**docker-run**(1)](/docker-run/1.md) or [**podman-run**(1)](/podman-run/1.md). ## INPUT, OUTPUT AND EXIT STATUS The behaviour of **autopkgtest-virt-docker** is as described by the AutomatedTesting virtualisation regime specification. ## EXAMPLES You can create an image suitable for autopkgtest from the semi-official Debian base images, like **debian:unstable**, or from the official Ubuntu base images, like **ubuntu:bionic**: ``` autopkgtest-build-podman --image debian:sid autopkgtest hello_2.8-4.dsc -- podman localhost/autopkgtest/debian:sid ``` If you would prefer not to trust images downloaded from docker.io, an equivalent image can be built from a minbase tarball generated by [**mmdebstrap**(1)](/mmdebstrap/1.md): ``` mmdebstrap --variant=minbase sid - | autopkgtest-build-podman --release=sid --tarball=- autopkgtest hello_2.8-4.dsc -- podman localhost/autopkgtest/debian:sid ``` Alternatively, you can test a container that runs a base image directly. However, most images need **apt-get update** before **apt** will work, so calling **autopkgtest** with **--setup-commands="apt-get update"** will be needed: ``` autopkgtest hello_2.8-4.dsc --setup-commands="apt-get update" -- podman debian:sid ``` ## SEE ALSO [**autopkgtest**(1)](/autopkgtest/1.md), [**autopkgtest-build-docker**(1)](/autopkgtest-build-docker/1.md), [**docker-run**(1)](/docker-run/1.md), [**podman-run**(1)](/podman-run/1.md), **/usr/share/doc/autopkgtest/**. ## AUTHORS AND COPYRIGHT **autopkgtest-virt-docker** was written by Mathieu Parent \. This manpage is part of autopkgtest, a tool for testing Debian binary packages. autopkgtest is Copyright (C) 2006-2015 Canonical Ltd and others. See **/usr/share/doc/autopkgtest/CREDITS** for the list of contributors and full copying conditions.