- trixie 5.49
- trixie-backports 6.0~bpo13+1
- testing 6.0
- unstable 6.2
| autopkgtest-virt-docker(1) | General Commands Manual | autopkgtest-virt-docker(1) |
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) or podman(1) 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), 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), 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) with a suitable configuration.
If the image has an unprivileged user in the UID range 1000 to 59999, that user is used to run tests. Otherwise, autopkgtest creates an unprivileged user automatically.
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) 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.
- -h | --help
- Show the help message and exit.
- --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) as init, note that some of the execution environment options described in systemd.exec(5) 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):
-
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).
- --remote
- Assume that Docker or Podman is running on a remote machine, so the container cannot access the local filesystem. In this mode the scratch directory is not shared with the container through a host directory, and --shared-dir is ignored. This is enabled automatically if the CONTAINER_HOST environment variable is set (when using Podman), or if the DOCKER_HOST environment variable is set or /.dockerenv exists (when using Docker).
- Use DIR as the host directory that is shared with the container, instead of a temporary directory. The directory is bind-mounted at the same path inside the container. This is useful if the default location is not visible to the container manager, for example on CI runners where only the project directory is shared between the runner and the container manager. DIR must not exist yet: it is created when the container is started and removed when the container is cleaned up. Its name stays the same when the testbed is reverted. This option has no effect when --remote is in use.
You can pass additional options to Docker or Podman: anything after a -- gets passed verbatim to docker-run(1) or podman-run(1).
INPUT, OUTPUT AND EXIT STATUS¶
The behaviour of autopkgtest-virt-docker is as described by the AutomatedTesting virtualisation regime specification.
SECURITY WARNING¶
When the container runs on the local host (the default), the scratch directory is shared with the container through a host directory, and is made world-writable so that the host and the container can write to it and clean it up regardless of their respective UIDs. Other users on the local host can reach that directory while tests are running, and may tamper with its contents. This virtualization server is therefore not safe to use on a multi-user host.
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 --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-build-docker(1), docker-run(1), podman-run(1), /usr/share/doc/autopkgtest/.
AUTHORS AND COPYRIGHT¶
autopkgtest-virt-docker was written by Mathieu Parent <math.parent@gmail.com>.
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.
| 2015 | Linux Programmer's Manual |