autopkgtest-virt-docker(1)

💅 autopkgtest-virt-docker — the manual page, bestie edition

okay so this is a General Commands Manual page (iykyk) for autopkgtest-virt-docker and its twin autopkgtest-virt-podman. It's giving "let me run your autopkgtest inside a container" and honestly? iconic. ✨

---

🦋 NAME 🦋

autopkgtest-virt-docker, autopkgtest-virt-podman — the autopkgtest virtualisation server that runs on Docker/Podman 🐳

---

🌸 SYNOPSIS 🌸

autopkgtest-virt-docker [options] docker-image [-- extra docker-run args...]

autopkgtest-virt-podman [options] podman-image [-- extra podman-run args...]

---

✨ DESCRIPTION ✨

So autopkgtest-virt-docker is literally an autopkgtest virtualization server, and it works with Docker or Podman. No cap. It takes everything the docker(1) or podman(1) command line can do and adapts it so autopkgtest can use it. 🫶

Normally, bestie, you're not the one calling autopkgtest-virt-docker — autopkgtest invokes it for you. Main character energy, but off-screen. 💅

---

🔥 HOST REQUIREMENTS 🔥

When you run this as autopkgtest-virt-podman, or with the --podman option (which is recommended, fr fr), this virtualization server needs podman(1) from the podman package. Also:

• Unprivileged access to user namespaces has to be enabled — and yes, that's the default in Debian 11 or later, slay 🎀
• The current user must have at least 65536 subordinate user IDs allocated in /etc/subuid
• And 65536 subordinate group IDs in /etc/subgid

For the whole tea, go read /usr/share/doc/podman/README.Debian. 📖

When you run it as autopkgtest-virt-docker, or with the --docker option, it needs docker(1) from the docker.io package. The current user must have access to the Docker daemon socket /run/docker.sock, unless you use the --sudo option.

⚠️ heads up bestie: either of those two things makes the user root-equivalent on the host system. That's a whole lot of power. Using Podman instead of Docker is recommended. 🙈

---

🎀 IMAGE REQUIREMENTS 🎀

The image must contain apt(8) with a suitable configuration. Non-negotiable.

The image should either provide the useradd(8) program — that's part of the passwd package, which is Priority: required — or it should already have an unprivileged user pre-created in the uid range 1000 to 59999. Pick your lane. ✨

When using Podman, if the image contains an init system, it should be labelled with something like:

LABEL org.debian.autopkgtest.init=systemd

This is the glow-up that lets autopkgtest-virt-podman detect the init system automatically, so you don't have to specify the --init option yourself. Commands like autopkgtest-build-podman --init=systemd add a suitable label for you, but you can totally do it manually for images that were created differently. 💖

The known values used by autopkgtest-build-podman(1) are none, systemd, sysv-rc and openrc. But here's the vibe check: any non-empty value except for none is assumed to mean 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. Turn it on when you need to see what's actually happening, bestie. 🔍
• --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, go look, I'll wait. 💖 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, and that has unclear security implications: it certainly reduces hardening between the host and the container, and it 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. When this option is used, the image will not be able to provide the isolation-container autopkgtest capability. 💀
• -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. you're 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) or podman-run(1). Periodt.

---

🌈 INPUT, OUTPUT AND EXIT STATUS 🌈

The behaviour of autopkgtest-virt-docker is as described by the AutomatedTesting virtualisation regime specification. That's the source of truth, bestie. ⭐

---

🧚 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 — valid honestly — 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/. Go read them, they're all part of the extended universe. 🌟

---

💜 AUTHORS AND COPYRIGHT 💜

autopkgtest-virt-docker was written by Mathieu Parent <math.parent@gmail.com>. Thank you for your service. 🫡

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

---

and that's the whole page bestie!! ✨💖🎀

this was autopkgtest-virt-docker(1), from the Linux Programmer's Manual, dated 2015. mwah, go run some tests, you got this 💅🦋🌸