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.

       The  image  should  either provide the useradd(8) 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) 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) 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).

       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.

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.

Linux Programmer's Manual                             2015                            autopkgtest-virt-docker(1)