Base WireGuard Image

If you want to run WireGuard in a Docker (or other OCI) container, without the Pro Custodibus agent monitoring it, you can use our base WireGuard image. It contains just the core wg and wg-quick programs, plus a few core network utilities like iptables and iproute2.

To monitor a WireGuard container with Pro Custodibus, use our agent image instead.

This WireGuard-only image can be pulled from Docker Hub with the repository name procustodibus/wireguard. It supports the following platforms: linux/amd64, linux/arm64, linux/arm/v7, and linux/arm/v6. We update the latest version of this image weekly to pick up the latest security fixes to the embedded software.

To use this image, either the container’s host must be running the Linux kernel version 5.6 or newer, or the container’s host itself must have the WireGuard kernel module installed. For old kernels, this often requires compiling the WireGuard kernel module from source on the host.

This image is based on the minimal Alpine Linux image. It’s generated with the docker/wireguard.dockerfile from our agent source repository.

Docker Run

The basic pattern for running this image with the docker run command is the following:

$ sudo docker run \
    --cap-add NET_ADMIN \
    --publish 51820:51820/udp \
    --name wireguard \
    --rm \
    --volume /srv/containers/wireguard/conf:/etc/wireguard:Z \
    docker.io/procustodibus/wireguard

 * /proc is already mounted
 * /run/lock: creating directory
 * /run/lock: correcting owner
   OpenRC 0.43.3.bf57debcde is starting up Linux 5.11.0-1020-aws (x86_64) [DOCKER]

 * Caching service dependencies ... [ ok ]
 * Starting WireGuard interface wg0 ...[#] ip link add wg0 type wireguard
[#] wg setconf wg0 /dev/fd/63
[#] ip -4 address add 10.0.0.1/32 dev wg0
[#] ip link set mtu 1420 up dev wg0
[#] ip -4 route add 10.0.0.2/32 dev wg0
 [ ok ]

These are what the above command arguments do:

--cap-add NET_ADMIN: Grants the container the NET_ADMIN capability — this is required to start a WireGuard interface inside the container.
--publish 51820:51820/udp: Forwards the public 51820 UDP port on the container’s host to the container’s 51820 UDP port — make sure the latter matches the ListenPort setting in the WireGuard config file (the former can be whatever port you want to expose publicly). When running multiple WireGuard interfaces in the same container, publish one port mapping for each interface.
--name wireguard: Sets the container’s name to wireguard (you can set this to whatever name you want, or omit it entirely if you don’t care how it’s named).
--rm: Deletes the container when it’s shut down (you can omit this if you don’t want to delete the container).
--volume /srv/containers/wireguard/conf:/etc/wireguard:Z: Maps the /srv/containers/wireguard/conf directory on the container’s host to the /etc/wireguard directory within the container (you can change the host directory to whatever you want).
docker.io/procustodibus/wireguard: Runs the latest version of this image.

If you are going to run a WireGuard interface with an AllowedIPs setting of 0.0.0.0/0 (and using the default routing table), also add the following command flag:

--sysctl net.ipv4.conf.all.src_valid_mark=1

When using Podman, if the container serves as a hub or gateway to other hosts, you may also need to add the following flag:

--sysctl net.ipv4.conf.all.forwarding=1

Place your WireGuard interface configuration files in the host’s /srv/containers/wireguard/conf directory (or in whatever directory on the container’s host you choose to map to the container’s /etc/wireguard directory). Starting the container will start a WireGuard interface for each wg-quick .conf file contained in this directory.

See the WireGuard Containers guide for examples of how to run this image under a variety of different scenarios.

Docker Compose

The basic pattern for running this image with the docker-compose command is to create a docker-compose.yml file like the following:

# /srv/containers/wireguard/docker-compose.yml
services:
  wireguard:
    image: docker.io/procustodibus/wireguard
    cap_add:
    - NET_ADMIN
    ports:
    - 51820:51820/udp
    volumes:
    - ./conf:/etc/wireguard:Z

These are what the above wireguard service keys do:

image: docker.io/procustodibus/wireguard: Runs the latest version of this image.
cap_add: ['NET_ADMIN']: Grants the container the NET_ADMIN capability — this is required to start a WireGuard interface inside the container.
ports: ['51820:51820/udp']: Forwards the public 51820 UDP port on the container’s host to the container’s 51820 UDP port — make sure the latter matches the ListenPort setting in the WireGuard config file (the former can be whatever port you want to expose publicly). When running multiple WireGuard interfaces in the same container, include one port mapping for each interface.
volumes: ['./conf:/etc/wireguard:Z']: Maps the conf directory on the container’s host (sibling of the docker-compose.yml file) to the /etc/wireguard directory within the container (you can change the host directory to whatever you want).

If you are going to run a WireGuard interface with an AllowedIPs setting of 0.0.0.0/0 (and using the default routing table), also add the following sysctls entry to the wireguard service:

    sysctls:
    - net.ipv4.conf.all.src_valid_mark=1

When using Podman, if the container serves as a hub or gateway to other hosts, you may also need to add the following sysctls entry:

    - net.ipv4.conf.all.forwarding=1

If you create the docker-compose.yml file in the host’s /srv/containers/wireguard directory, create a conf subdirectory in that directory, and place your WireGuard configuration files there (or wherever you choose to map to the container’s /etc/wireguard directory).

Starting the container from the directory containing the docker-compose.yml file with the following command will start a WireGuard interface for each wg-quick .conf file contained in the conf subdirectory:

$ sudo docker-compose up
Creating network "wireguard_default" with the default driver
Creating wireguard_wireguard_1 ... done
Attaching to wireguard_wireguard_1
wireguard_1  |
wireguard_1  |  * /proc is already mounted
wireguard_1  |  * /run/lock: creating directory
wireguard_1  |  * /run/lock: correcting owner
wireguard_1  |    OpenRC 0.43.3.bf57debcde is starting up Linux 5.11.0-1020-aws (x86_64) [DOCKER]
wireguard_1  |
wireguard_1  |  * Caching service dependencies ... [ ok ]
wireguard_1  |  * Starting WireGuard interface wg0 ...[#] ip link add wg0 type wireguard
wireguard_1  | [#] wg setconf wg0 /dev/fd/63
wireguard_1  | [#] ip -4 address add 10.0.0.1/24 dev wg0
wireguard_1  | [#] ip link set mtu 1420 up dev wg0
wireguard_1  |  [ ok ]

See the WireGuard Containers guide for examples of how to run this image under a variety of different scenarios.

Docker Pull

To upgrade to the latest version of this image, pull it to the container’s host with the following command:

$ sudo docker pull procustodibus/wireguard
Using default tag: latest
latest: Pulling from procustodibus/wireguard
a9fdca298560: Pull complete
Digest: sha256:1964a71fc1e4d6856849d9f49240c5fb1317dfe86e61d38bc7af74c2bb38690e
Status: Image is up to date for procustodibus/wireguard:latest
docker.io/procustodibus/wireguard:latest

List the available versions and tags for the image with the following command:

$ sudo docker image ls procustodibus/wireguard
REPOSITORY                TAG                    IMAGE ID       CREATED       SIZE
procustodibus/wireguard   latest                  a9fdca298560   4 days ago    15.2MB
procustodibus/wireguard   v1.0.20210424           a9fdca298560   4 days ago    15.2MB
procustodibus/wireguard   v1.0.20210424-i211029   a9fdca298560   4 days ago    15.2MB
procustodibus/wireguard   v1.0.20210424-i211022   312f9e74964c   11 days ago   15.2MB

If you specified a particular tag or image ID for this image in your docker run command or docker-compose.yml config file, update it to use a tag or the ID of the latest image. Then restart the container.