docs.linuxserver.io Open in urlscan Pro
2606:50c0:8002::153  Public Scan

URL: https://docs.linuxserver.io/images/docker-wireguard/
Submission: On October 06 via api from US — Scanned from DE

Form analysis 2 forms found in the DOM

<form class="md-header__option" data-md-component="palette"> <input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="purple" data-md-color-accent="indigo"
    aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_0"> <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_1"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
      <path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"></path>
    </svg> </label> <input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="purple" data-md-color-accent="indigo" aria-label="Switch to light mode" type="radio" name="__palette"
    id="__palette_1"> <label class="md-header__button md-icon" title="Switch to light mode" for="__palette_0" hidden=""> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
      <path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"></path>
    </svg> </label> </form>

Name: search

<form class="md-search__form" name="search"> <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false"
    data-md-component="search-query" required=""> <label class="md-search__icon md-icon" for="__search"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
      <path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"></path>
    </svg> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
      <path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"></path>
    </svg> </label>
  <nav class="md-search__options" aria-label="Search">
    <a href="https://docs.linuxserver.io/images/docker-wireguard/?q=" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard="" data-clipboard-text="javascript:void(0)" data-md-component="search-share" tabindex="-1"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"></path></svg> </a>
    <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
        <path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"></path>
      </svg> </button> </nav>
  <div class="md-search__suggest" data-md-component="search-suggest"></div>
</form>

Text Content

Skip to content

LinuxServer.io
wireguard

Type to start searching
linuxserver/docker-documentation
 * 157
 * 28

 * Introduction
 * How to
 * Container Images
 * Frequently Asked Questions
 * Misc

LinuxServer.io
linuxserver/docker-documentation
 * 157
 * 28

 * Introduction
 * How to
   How to
    * Container Execution
    * Docker Containers: 101
    * Running LinuxServer Containers
    * Customizing LinuxServer Containers
    * Docker Compose
    * Understanding PUID and PGID
    * Updating our containers
    * Volumes
    * Fleet
    * SWAG
    * How to get support
    * Split dns

 * Container Images
   Container Images
    * Images
      Images
       * adguardhome-sync
       * airsonic-advanced
       * altus
       * apprise-api
       * ardour
       * audacity
       * babybuddy
       * bambustudio
       * bazarr
       * beets
       * blender
       * boinc
       * booksonic-air
       * bookstack
       * budge
       * calibre-web
       * calibre
       * calligra
       * changedetection.io
       * chromium
       * code-server
       * cops
       * cura
       * daapd
       * darktable
       * davos
       * ddclient
       * deluge
       * digikam
       * dillinger
       * diskover
       * dokuwiki
       * domoticz
       * doplarr
       * doublecommander
       * duckdns
       * duplicati
       * emby
       * embystat
       * emulatorjs
       * endlessh
       * fail2ban
       * faster-whisper
       * feed2toot
       * ferdium
       * ffmpeg
       * filezilla
       * firefox
       * fleet
       * flexget
       * foldingathome
       * freecad
       * freetube
       * freshrss
       * gimp
       * github-desktop
       * gitqlient
       * grav
       * grocy
       * habridge
       * headphones
       * healthchecks
       * hedgedoc
       * heimdall
       * hishtory-server
       * homeassistant
       * htpcmanager
       * inkscape
       * jackett
       * jellyfin
       * kali-linux
       * kasm
       * kavita
       * kdenlive
       * keepassxc
       * kicad
       * kimai
       * kometa
       * krita
       * lazylibrarian
       * ldap-auth
       * libreoffice
       * librespeed
       * librewolf
       * lidarr
       * limnoria
       * lollypop
       * lychee
       * manyfold
       * mariadb
       * mastodon
       * mediaelch
       * medusa
       * minetest
       * minisatip
       * monica
       * msedge
       * mstream
       * mullvad-browser
       * mylar3
       * mysql-workbench
       * nano-wallet
       * nano
       * netbootxyz
       * netbox
       * nextcloud
       * nginx
       * ngircd
       * nzbget
       * nzbhydra2
       * obsidian
       * ombi
       * openssh-server
       * openvscode-server
       * opera
       * orcaslicer
       * oscam
       * overseerr
       * pairdrop
       * phpmyadmin
       * pidgin
       * piper
       * piwigo
       * planka
       * plex
       * projectsend
       * prowlarr
       * pwndrop
       * pydio-cells
       * pyload-ng
       * pylon
       * python
       * qbittorrent
       * qdirstat
       * quassel-core
       * quassel-web
       * radarr
       * raneto
       * rawtherapee
       * rdesktop
       * readarr
       * remmina
       * resilio-sync
       * rsnapshot
       * rustdesk
       * sabnzbd
       * series-troxide
       * shotcut
       * sickchill
       * sickgear
       * smokeping
       * snapdrop
       * snipe-it
       * socket-proxy
       * sonarr
       * speedtest-tracker
       * spotube
       * sqlitebrowser
       * steamos
       * swag
       * synclounge
       * syncthing
       * syslog-ng
       * tautulli
       * thelounge
       * transmission
       * tvheadend
       * ubooquity
       * ungoogled-chromium
       * unifi-network-application
       * vscodium
       * webcord
       * webgrabplus
       * webtop
       * wikijs
       * wireguard wireguard
         Table of contents
          * Supported Architectures
          * Version Tags
          * Application Setup
          * Note on iptables
          * Server Mode
          * Client Mode
          * Road warriors, roaming and returning home
          * Maintaining local access to attached services
          * Site-to-site VPN
          * Read-Only Operation
             * Caveats
         
          * Usage
             * docker-compose (recommended, click here for more info)
             * docker cli (click here for more info)
         
          * Parameters
             * Ports (-p)
             * Environment Variables (-e)
             * Volume Mappings (-v)
                * Miscellaneous Options
            
             * Portainer notice
         
          * Environment variables from files (Docker secrets)
          * Umask for running applications
          * User / Group Identifiers
          * Docker Mods
          * Support Info
          * Updating Info
             * Via Docker Compose
             * Via Docker Run
             * Image Update Notifications - Diun (Docker Image Update Notifier)
         
          * Building locally
          * Versions
      
       * wireshark
       * wps-office
       * xbackbone
       * yaak
       * your_spotify
       * znc
       * zotero
   
    * Deprecated Images
      Deprecated Images
       * airsonic
       * baseimage-alpine-python
       * baseimage-cloud9
       * baseimage-guacgui
       * baseimage-gui
       * baseimage-mono
       * baseimage-rdesktop-web
       * baseimage-rdesktop
       * booksonic
       * cardigann
       * chevereto
       * clarkson
       * cloud9
       * codiad
       * codimd
       * couchpotato
       * dillinger
       * docker-compose
       * endlessh
       * gazee
       * gmail-order-bot
       * guacd
       * hydra
       * hydra2
       * ipfs
       * kanzi
       * letsencrypt
       * libresonic
       * musicbrainz
       * muximux
       * mylar
       * nano-discord-bot
       * nntp2nntp
       * openvpn-as
       * organizr
       * paperless-ng
       * paperless-ngx
       * papermerge
       * photoshow
       * pixapop
       * plex-meta-manager
       * pydio
       * pyload
       * readme-sync
       * requestrr
       * rutorrent
       * scrutiny
       * shout-irc
       * sickrage
       * taisun
       * tester
       * unifi-controller

 * Frequently Asked Questions
 * Misc
   Misc
    * Awesome LSIO
    * Finances
    * Running Containers Read-Only
    * LinuxServer Support Policy

Table of contents
 * Supported Architectures
 * Version Tags
 * Application Setup
 * Note on iptables
 * Server Mode
 * Client Mode
 * Road warriors, roaming and returning home
 * Maintaining local access to attached services
 * Site-to-site VPN
 * Read-Only Operation
    * Caveats

 * Usage
    * docker-compose (recommended, click here for more info)
    * docker cli (click here for more info)

 * Parameters
    * Ports (-p)
    * Environment Variables (-e)
    * Volume Mappings (-v)
       * Miscellaneous Options
   
    * Portainer notice

 * Environment variables from files (Docker secrets)
 * Umask for running applications
 * User / Group Identifiers
 * Docker Mods
 * Support Info
 * Updating Info
    * Via Docker Compose
    * Via Docker Run
    * Image Update Notifications - Diun (Docker Image Update Notifier)

 * Building locally
 * Versions


LINUXSERVER/WIREGUARD¶



WireGuard® is an extremely simple yet fast and modern VPN that utilizes
state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more
useful than IPsec, while avoiding the massive headache. It intends to be
considerably more performant than OpenVPN. WireGuard is designed as a general
purpose VPN for running on embedded interfaces and super computers alike, fit
for many different circumstances. Initially released for the Linux kernel, it is
now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable. It
is currently under heavy development, but already it might be regarded as the
most secure, easiest to use, and simplest VPN solution in the industry.




SUPPORTED ARCHITECTURES¶

We utilise the docker manifest for multi-platform awareness. More information is
available from docker here and our announcement here.

Simply pulling lscr.io/linuxserver/wireguard:latest should retrieve the correct
image for your arch, but you can also pull specific arch images via tags.

The architectures supported by this image are:

Architecture Available Tag x86-64 ✅ amd64-<version tag> arm64 ✅ arm64v8-<version
tag> armhf ❌


VERSION TAGS¶

This image provides various versions that are available via tags. Please read
the descriptions carefully and exercise caution when using unstable or
development tags.

Tag Available Description latest ✅ Stable releases based on Alpine without
support for compiling Wireguard modules. legacy ✅ Stable releases with support
for compiling Wireguard modules for older kernels.


APPLICATION SETUP¶

During container start, it will first check if the wireguard module is already
installed and loaded. Kernels newer than 5.6 generally have the wireguard module
built-in (along with some older custom kernels). However, the module may not be
enabled. Make sure it is enabled prior to starting the container.

This can be run as a server or a client, based on the parameters used.


NOTE ON IPTABLES¶

Some hosts may not load the iptables kernel modules by default. In order for the
container to be able to load them, you need to assign the SYS_MODULE capability
and add the optional /lib/modules volume mount. Alternatively you can modprobe
them from the host before starting the container.


SERVER MODE¶

If the environment variable PEERS is set to a number or a list of strings
separated by comma, the container will run in server mode and the necessary
server and peer/client confs will be generated. The peer/client config qr codes
will be output in the docker log if LOG_CONFS is set to true. They will also be
saved in text and png format under /config/peerX in case PEERS is a variable and
an integer or /config/peer_X in case a list of names was provided instead of an
integer.

Variables SERVERURL, SERVERPORT, INTERNAL_SUBNET, PEERDNS, INTERFACE, ALLOWEDIPS
and PERSISTENTKEEPALIVE_PEERS are optional variables used for server mode. Any
changes to these environment variables will trigger regeneration of server and
peer confs. Peer/client confs will be recreated with existing private/public
keys. Delete the peer folders for the keys to be recreated along with the confs.

To add more peers/clients later on, you increment the PEERS environment variable
or add more elements to the list and recreate the container.

To display the QR codes of active peers again, you can use the following command
and list the peer numbers as arguments: docker exec -it wireguard /app/show-peer
1 4 5 or docker exec -it wireguard /app/show-peer myPC myPhone myTablet (Keep in
mind that the QR codes are also stored as PNGs in the config folder).

The templates used for server and peer confs are saved under /config/templates.
Advanced users can modify these templates and force conf generation by deleting
/config/wg_confs/wg0.conf and restarting the container.

The container managed server conf is hardcoded to wg0.conf. However, the users
can add additional tunnel config files with .conf extensions into
/config/wg_confs/ and the container will attempt to start them all in
alphabetical order. If any one of the tunnels fail, they will all be stopped and
the default route will be deleted, requiring user intervention to fix the
invalid conf and a container restart.


CLIENT MODE¶

Do not set the PEERS environment variable. Drop your client conf(s) into the
config folder as /config/wg_confs/<tunnel name>.conf and start the container. If
there are multiple tunnel configs, the container will attempt to start them all
in alphabetical order. If any one of the tunnels fail, they will all be stopped
and the default route will be deleted, requiring user intervention to fix the
invalid conf and a container restart.

If you get IPv6 related errors in the log and connection cannot be established,
edit the AllowedIPs line in your peer/client wg0.conf to include only 0.0.0.0/0
and not ::/0; and restart the container.


ROAD WARRIORS, ROAMING AND RETURNING HOME¶

If you plan to use Wireguard both remotely and locally, say on your mobile
phone, you will need to consider routing. Most firewalls will not route ports
forwarded on your WAN interface correctly to the LAN out of the box. This means
that when you return home, even though you can see the Wireguard server, the
return packets will probably get lost.

This is not a Wireguard specific issue and the two generally accepted solutions
are NAT reflection (setting your edge router/firewall up in such a way as it
translates internal packets correctly) or split horizon DNS (setting your
internal DNS to return the private rather than public IP when connecting
locally).

Both of these approaches have positives and negatives however their setup is out
of scope for this document as everyone's network layout and equipment will be
different.


MAINTAINING LOCAL ACCESS TO ATTACHED SERVICES¶

** Note: This is not a supported configuration by Linuxserver.io - use at your
own risk.

When routing via Wireguard from another container using the service option in
docker, you might lose access to the containers webUI locally. To avoid this,
exclude the docker subnet from being routed via Wireguard by modifying your
wg0.conf like so (modifying the subnets as you require):

[Interface]
PrivateKey = <private key>
Address = 9.8.7.6/32
DNS = 8.8.8.8
PostUp = DROUTE=$(ip route | grep default | awk '{print $3}'); HOMENET=192.168.0.0/16; HOMENET2=10.0.0.0/8; HOMENET3=172.16.0.0/12; ip route add $HOMENET3 via $DROUTE;ip route add $HOMENET2 via $DROUTE; ip route add $HOMENET via $DROUTE;iptables -I OUTPUT -d $HOMENET -j ACCEPT;iptables -A OUTPUT -d $HOMENET2 -j ACCEPT; iptables -A OUTPUT -d $HOMENET3 -j ACCEPT;  iptables -A OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT
PreDown = DROUTE=$(ip route | grep default | awk '{print $3}'); HOMENET=192.168.0.0/16; HOMENET2=10.0.0.0/8; HOMENET3=172.16.0.0/12; ip route del $HOMENET3 via $DROUTE;ip route del $HOMENET2 via $DROUTE; ip route del $HOMENET via $DROUTE; iptables -D OUTPUT ! -o %i -m mark ! --mark $(wg show %i fwmark) -m addrtype ! --dst-type LOCAL -j REJECT; iptables -D OUTPUT -d $HOMENET -j ACCEPT; iptables -D OUTPUT -d $HOMENET2 -j ACCEPT; iptables -D OUTPUT -d $HOMENET3 -j ACCEPT



SITE-TO-SITE VPN¶

** Note: This is not a supported configuration by Linuxserver.io - use at your
own risk.

Site-to-site VPN in server mode requires customizing the AllowedIPs statement
for a specific peer in wg0.conf. Since wg0.conf is autogenerated when server
vars are changed, it is not recommended to edit it manually.

In order to customize the AllowedIPs statement for a specific peer in wg0.conf,
you can set an env var SERVER_ALLOWEDIPS_PEER_<peer name or number> to the
additional subnets you'd like to add, comma separated and excluding the peer IP
(ie. "192.168.1.0/24,192.168.2.0/24"). Replace <peer name or number> with either
the name or number of a peer (whichever is used in the PEERS var).

For instance SERVER_ALLOWEDIPS_PEER_laptop="192.168.1.0/24,192.168.2.0/24" will
result in the wg0.conf entry AllowedIPs =
10.13.13.2,192.168.1.0/24,192.168.2.0/24 for the peer named laptop.

Keep in mind that this var will only be considered when the confs are
regenerated. Adding this var for an existing peer won't force a regeneration.
You can delete wg0.conf and restart the container to force regeneration if
necessary.

Don't forget to set the necessary POSTUP and POSTDOWN rules in your client's
peer conf for lan access.


READ-ONLY OPERATION¶

This image can be run with a read-only container filesystem. For details please
read the docs.


CAVEATS¶

 * Not supported in client mode.
 * Not supported for the legacy tag.


USAGE¶

To help you get started creating a container from this image you can either use
docker-compose or the docker cli.


DOCKER-COMPOSE (RECOMMENDED, CLICK HERE FOR MORE INFO)¶

---
services:
  wireguard:
    image: lscr.io/linuxserver/wireguard:latest
    container_name: wireguard
    cap_add:
      - NET_ADMIN
      - SYS_MODULE #optional
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - SERVERURL=wireguard.domain.com #optional
      - SERVERPORT=51820 #optional
      - PEERS=1 #optional
      - PEERDNS=auto #optional
      - INTERNAL_SUBNET=10.13.13.0 #optional
      - ALLOWEDIPS=0.0.0.0/0 #optional
      - PERSISTENTKEEPALIVE_PEERS= #optional
      - LOG_CONFS=true #optional
    volumes:
      - /path/to/wireguard/config:/config
      - /lib/modules:/lib/modules #optional
    ports:
      - 51820:51820/udp
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    restart: unless-stopped



DOCKER CLI (CLICK HERE FOR MORE INFO)¶

docker run -d \
  --name=wireguard \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_MODULE `#optional` \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e SERVERURL=wireguard.domain.com `#optional` \
  -e SERVERPORT=51820 `#optional` \
  -e PEERS=1 `#optional` \
  -e PEERDNS=auto `#optional` \
  -e INTERNAL_SUBNET=10.13.13.0 `#optional` \
  -e ALLOWEDIPS=0.0.0.0/0 `#optional` \
  -e PERSISTENTKEEPALIVE_PEERS= `#optional` \
  -e LOG_CONFS=true `#optional` \
  -p 51820:51820/udp \
  -v /path/to/wireguard/config:/config \
  -v /lib/modules:/lib/modules `#optional` \
  --sysctl="net.ipv4.conf.all.src_valid_mark=1" \
  --restart unless-stopped \
  lscr.io/linuxserver/wireguard:latest



PARAMETERS¶

Containers are configured using parameters passed at runtime (such as those
above). These parameters are separated by a colon and indicate
<external>:<internal> respectively. For example, -p 8080:80 would expose port 80
from inside the container to be accessible from the host's IP on port 8080
outside the container.


PORTS (-P)¶

Parameter Function 51820/udp wireguard port


ENVIRONMENT VARIABLES (-E)¶

Env Function PUID=1000 for UserID - see below for explanation PGID=1000 for
GroupID - see below for explanation TZ=Etc/UTC specify a timezone to use, see
this list. SERVERURL=wireguard.domain.com External IP or domain name for docker
host. Used in server mode. If set to auto, the container will try to determine
and set the external IP automatically SERVERPORT=51820 External port for docker
host. Used in server mode. PEERS=1 Number of peers to create confs for. Required
for server mode. Can also be a list of names: myPC,myPhone,myTablet
(alphanumeric only) PEERDNS=auto DNS server set in peer/client configs (can be
set as 8.8.8.8). Used in server mode. Defaults to auto, which uses wireguard
docker host's DNS via included CoreDNS forward. INTERNAL_SUBNET=10.13.13.0
Internal subnet for the wireguard and server and peers (only change if it
clashes). Used in server mode. ALLOWEDIPS=0.0.0.0/0 The IPs/Ranges that the
peers will be able to reach using the VPN connection. If not specified the
default value is: '0.0.0.0/0, ::0/0' This will cause ALL traffic to route
through the VPN, if you want split tunneling, set this to only the IPs you would
like to use the tunnel AND the ip of the server's WG ip, such as 10.13.13.1.
PERSISTENTKEEPALIVE_PEERS= Set to all or a list of comma separated peers (ie.
1,4,laptop) for the wireguard server to send keepalive packets to listed peers
every 25 seconds. Useful if server is accessed via domain name and has dynamic
IP. Used only in server mode. LOG_CONFS=true Generated QR codes will be
displayed in the docker log. Set to false to skip log output.


VOLUME MAPPINGS (-V)¶

Volume Function /config Contains all relevant configuration files. /lib/modules
Host kernel modules for situations where they're not already loaded.

MISCELLANEOUS OPTIONS¶

Parameter Function --sysctl= Required for client mode.


PORTAINER NOTICE¶

Warning

This image utilises cap_add or sysctl to work properly. This is not implemented
properly in some versions of Portainer, thus this image may not work if deployed
through Portainer.


ENVIRONMENT VARIABLES FROM FILES (DOCKER SECRETS)¶

You can set any environment variable from a file by using a special prepend
FILE__.

As an example:

-e FILE__MYVAR=/run/secrets/mysecretvariable


Will set the environment variable MYVAR based on the contents of the
/run/secrets/mysecretvariable file.


UMASK FOR RUNNING APPLICATIONS¶

For all of our images we provide the ability to override the default umask
settings for services started within the containers using the optional -e
UMASK=022 setting. Keep in mind umask is not chmod it subtracts from permissions
based on it's value it does not add. Please read up here before asking for
support.


USER / GROUP IDENTIFIERS¶

When using volumes (-v flags), permissions issues can arise between the host OS
and the container, we avoid this issue by allowing you to specify the user PUID
and group PGID.

Ensure any volume directories on the host are owned by the same user you specify
and any permissions issues will vanish like magic.

In this instance PUID=1000 and PGID=1000, to find yours use id your_user as
below:

id your_user


Example output:

uid=1000(your_user) gid=1000(your_user) groups=1000(your_user)



DOCKER MODS¶



We publish various Docker Mods to enable additional functionality within the
containers. The list of Mods available for this image (if any) as well as
universal mods that can be applied to any one of our images can be accessed via
the dynamic badges above.


SUPPORT INFO¶

 * Shell access whilst the container is running:
   
   docker exec -it wireguard /bin/bash
   

 * To monitor the logs of the container in realtime:
   
   docker logs -f wireguard
   

 * Container version number:
   
   docker inspect -f '{{ index .Config.Labels "build_version" }}' wireguard
   

 * Image version number:
   
   docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/wireguard:latest
   


UPDATING INFO¶

Most of our images are static, versioned, and require an image update and
container recreation to update the app inside. With some exceptions (noted in
the relevant readme.md), we do not recommend or support updating apps inside the
container. Please consult the Application Setup section above to see if it is
recommended for the image.

Below are the instructions for updating containers:


VIA DOCKER COMPOSE¶

 * Update images:
   
   * All images:
     
     docker-compose pull
     
   
   * Single image:
     
     docker-compose pull wireguard
     

 * Update containers:
   
   * All containers:
     
     docker-compose up -d
     
   
   * Single container:
     
     docker-compose up -d wireguard
     

 * You can also remove the old dangling images:
   
   docker image prune
   


VIA DOCKER RUN¶

 * Update the image:
   
   docker pull lscr.io/linuxserver/wireguard:latest
   

 * Stop the running container:
   
   docker stop wireguard
   

 * Delete the container:
   
   docker rm wireguard
   

 * Recreate a new container with the same docker run parameters as instructed
   above (if mapped correctly to a host folder, your /config folder and settings
   will be preserved)

 * You can also remove the old dangling images:
   
   docker image prune
   


IMAGE UPDATE NOTIFICATIONS - DIUN (DOCKER IMAGE UPDATE NOTIFIER)¶

Tip

We recommend Diun for update notifications. Other tools that automatically
update containers unattended are not recommended or supported.


BUILDING LOCALLY¶

If you want to make local modifications to these images for development purposes
or just to customize the logic:

git clone https://github.com/linuxserver/docker-wireguard.git
cd docker-wireguard
docker build \
  --no-cache \
  --pull \
  -t lscr.io/linuxserver/wireguard:latest .


The ARM variants can be built on x86_64 hardware using
multiarch/qemu-user-static

docker run --rm --privileged multiarch/qemu-user-static:register --reset


Once registered you can define the dockerfile to use with -f Dockerfile.aarch64.


VERSIONS¶

 * 13.08.24: - Add errors plugin to default Corefile.
 * 23.07.24: - Install kmod from alpine repository.
 * 24.05.24: - Rebase to Alpine 3.20, install wireguard-tools from Alpine repo.
 * 10.03.24: - Use iptables-legacy on Alpine 3.19.
 * 05.03.24: - Rebase master to Alpine 3.19.
 * 03.10.23: - Potentially Breaking Change: Support for multiple interfaces
   added. Wireguard confs moved to /config/wg_confs/. Any file with a .conf
   extension in that folder will be treated as a live tunnel config and will be
   attempted to start. If any of the tunnels fail, all tunnels will be stopped.
   Tunnels are started in alphabetical order. Managed server conf will continue
   to be hardcoded to wg0.conf.
 * 28.06.23: - Rebase master to Alpine 3.18 again.
 * 26.06.23: - Revert master to Alpine 3.17, due to issue with openresolv.
 * 24.06.23: - Rebase master to Alpine 3.18, deprecate armhf as per
   https://www.linuxserver.io/armhf.
 * 26.04.23: - Rework branches. Swap alpine and ubuntu builds.
 * 29.01.23: - Rebase to alpine 3.17.
 * 10.01.23: - Add new var to add PersistentKeepalive to server config for
   select peers to survive server IP changes when domain name is used.
 * 26.10.22: - Better handle unsupported peer names. Improve logging.
 * 12.10.22: - Add Alpine branch. Optimize wg and coredns services.
 * 04.10.22: - Rebase to Jammy. Upgrade to s6v3.
 * 16.05.22: - Improve NAT handling in server mode when multiple ethernet
   devices are present.
 * 23.04.22: - Add pre-shared key support. Automatically added to all new peer
   confs generated, existing ones are left without to ensure no breaking
   changes.
 * 10.04.22: - Rebase to Ubuntu Focal. Add LOG_CONFS env var. Remove deprecated
   add-peer command.
 * 28.10.21: - Add site-to-site vpn support.
 * 11.02.21: - Fix bug related to changing internal subnet and named peer confs
   not updating.
 * 06.10.20: - Disable CoreDNS in client mode, or if port 53 is already in use
   in server mode.
 * 04.10.20: - Allow to specify a list of names as PEERS and add ALLOWEDIPS
   environment variable. Also, add peer name/id to each one of the peer sections
   in wg0.conf. Important: Existing users need to delete
   /config/templates/peer.conf and restart
 * 27.09.20: - Cleaning service binding example to have accurate PreDown script.
 * 06.08.20: - Replace resolvconf with openresolv due to dns issues when a
   client based on this image is connected to a server also based on this image.
   Add IPv6 info to readme. Display kernel version in logs.
 * 29.07.20: - Update Coredns config to detect dns loops (existing users need to
   delete /config/coredns/Corefile and restart).
 * 27.07.20: - Update Coredns config to prevent issues with non-user-defined
   bridge networks (existing users need to delete /config/coredns/Corefile and
   restart).
 * 05.07.20: - Add Debian updates and security repos for headers.
 * 25.06.20: - Simplify module tests, prevent iptables issues from resulting in
   false negatives.
 * 19.06.20: - Add support for Ubuntu Focal (20.04) kernels. Compile wireguard
   tools and kernel module instead of using the ubuntu packages. Make module
   install optional. Improve verbosity in logs.
 * 29.05.20: - Add support for 64bit raspbian.
 * 28.04.20: - Add Buster/Stretch backports repos for Debian. Tested with OMV 5
   and OMV 4 (on kernel 4.19.0-0.bpo.8-amd64).
 * 20.04.20: - Fix typo in client mode conf existence check.
 * 13.04.20: - Fix bug that forced conf recreation on every start.
 * 08.04.20: - Add arm32/64 builds and enable multi-arch (rpi4 with ubuntu and
   raspbian buster tested). Add CoreDNS for PEERDNS=auto setting. Update the
   add-peer/show-peer scripts to utilize the templates and the INTERNAL_SUBNET
   var (previously missed, oops).
 * 05.04.20: - Add INTERNAL_SUBNET variable to prevent subnet clashes. Add
   templates for server and peer confs.
 * 01.04.20: - Add show-peer script and include info on host installed headers.
 * 31.03.20: - Initial Release.

October 3, 2024 March 31, 2020
Back to top
Previous
wikijs
Next
wireshark

Copyright © 2024 LinuxServer.io
Made with Material for MkDocs