Configure a Wireguard interface (wg): Difference between revisions

From Alpine Linux
(Adding notes about net.ipv4.ip_forward and iptables)
(1. Added stubs: 'Alternative Integrations into the Network Stack', 'Tools' and 'WireGuard Monitoring and Management'; 2. →‎See also: Added Prometheus/Grafana/Alerts setup link at medium.com.)
 
(14 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{TOC left}}
{{TOC right}}


WireGuard is a very promising VPN technology available in the community repository since Alpine 3.10.
[https://en.wikipedia.org/wiki/WireGuard WireGuard] multiple platform vpn solution. WireGuard itself is now integrated into the linux kernel since v5.6. Only the userland configuration tools are required.


There are several ways to install and configure an interface.
== Installation  ==


In order to load the WireGuard kernel module, you need a compatible kernel:
The most straightforward method to configure WireGuard is to use the tool <code>wg-quick</code> available in the package {{pkg|wireguard-tools-wg-quick}}.


* linux-lts
Install the meta package {{pkg|wireguard-tools}} to install the necessary WireGuard packages  and {{pkg|iptables}} as follows: {{Cmd|# apk add wireguard-tools iptables}}
* linux-virt


== Bringing up an interface using wg-tools ==
== Configuration ==


The most straightforward method, and the one recommended in WireGuard documentation, is to use <code>wg-quick</code>.
=== Create Server Keys and Interface Config ===


Install wireguard-tools
Create a server private and public key: {{Cmd|<nowiki># wg genkey | tee server.privatekey | wg pubkey > server.publickey</nowiki>}}


apk add wireguard-tools
Remove any permissions on the file for users and groups other than the root user to ensure that only it can access the private key: {{Cmd|<nowiki># chmod go= server.privatekey</nowiki>}}
 
Then load the module
 
modprobe wireguard
 
Add it to <code>/etc/modules</code> to automatically load it on boot.
 
Then, we need to create a private and a public key:
 
wg genkey | tee privatekey | wg pubkey > publickey


Then, we create a new config file <code>/etc/wireguard/wg0.conf</code> using those keys:
Then, we create a new config file {{Path|/etc/wireguard/wg0.conf}} using these new keys as follows:{{Cat|/etc/wireguard/wg0.conf|<nowiki>
[Interface]
Address = 192.168.2.1/24, fddd::ffff/64
ListenPort = 45340
PrivateKey = <server private key value> # the key from the previously generated privatekey file
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE;iptables -A FORWARD -o %i -j ACCEPT; ip6tables -A FORWARD -i %i -j ACCEPT; ip6tables -t nat -A POSTROUTING -o eth0 -j MASQUERADE;ip6tables -A FORWARD -o %i -j ACCEPT
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE;iptables -D FORWARD -o %i -j ACCEPT; ip6tables -D FORWARD -i %i -j ACCEPT; ip6tables -t nat -D POSTROUTING -o eth0 -j MASQUERADE;ip6tables -D FORWARD -o %i -j ACCEPT
[Peer]
PublicKey = <client public key value> # obtained from client device via wireguard connection setup process
AllowedIPs = 192.168.2.2/32, fddd::1/128</nowiki>}}


[Interface]
The PostUp and PostDown iptable rules forward traffic from the wg0 subnet (192.168.2.1/24) to the lan subnet on interface eth0. Refer to [https://github.com/pirate/wireguard-docs#user-content-config-reference this WireGuard documentation] for information on adding peers to the config file.
Address = 10.123.0.1/24
ListenPort = 45340
PrivateKey = SG1nXk2+kAAKnMkL5aX3NSFPaGjf9SQI/wWwFj9l9U4= # the key from the previously generated privatekey file
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE;iptables -A FORWARD -o %i -j ACCEPT
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE;iptables -D FORWARD -o %i -j ACCEPT


The PostUp and PostDown steps are there to ensure the interface wg0 will accept and forward traffic to eth0. The postrouting and forward to %i is not required, but it will enable "VPN mode" where users can access the internet via this server if desired.
Bring up the new {{ic|wg0}} interface:{{Cmd|# wg-quick up wg0}}
Note that this requires <code>iptables</code> installed and enabled: <code>apk add iptables && rc-update add iptables</code>.
Reference [https://github.com/pirate/wireguard-docs#user-content-config-reference this WireGuard documentation] for information on adding peers to the config file.
 
To bring up the new interface we use:
 
wg-quick up wg0


To take it down, we can use <code>wg-quick down wg0</code> which will clean up the interface and remove the iptables rules.
To take it down, we can use <code>wg-quick down wg0</code> which will clean up the interface and remove the iptables rules.
Note: If running in a Docker container, you will need to run with <code>--cap-add=NET_ADMIN</code> to modify your interfaces.


== Bringing up an interface using ifupdown-ng ==
{{Note|If running in a Docker container, you will need to run with <code>--cap-add{{=}}NET_ADMIN</code> to modify your interfaces.}}


The official documents from WireGuard show examples of how to set up an interface with the use of wg-quick.
=== Use with network interfaces ===
In this how-to, we are not going to use that utility. We'll use the plain wg command and [https://github.com/ifupdown-ng/ifupdown-ng/blob/master/doc/interfaces-wireguard.scd ifupdown-ng].


apk add wireguard-tools-wg
To enable connecting with Wireguard on boot, open your {{Path|/etc/network/interfaces}} and add this information after your auto other network interfaces as follows:{{Cat|/etc/network/interfaces|<nowiki>...
auto wg0
iface wg0 inet static
pre-up wg-quick up /etc/wireguard/wg0.conf</nowiki>}}


Now that all the tools are installed, you can setup the interface.
=== Service configuration ===
The setup of your interface config is out of the scope of this document. You should consult the [https://git.zx2c4.com/WireGuard/about/src/tools/man/wg.8 manual page of wg].


After you have finished setting up your wgX interface config, you can add it to your <code>/etc/network/interfaces</code>:
Since Alpine 3.20, {{pkg|wireguard-tools-openrc}} package provides an OpenRC initd service file.


auto wg0
To use this, install the package:{{Cmd|# apk add wireguard-tools-openrc }}
iface wg0 inet static
        requires eth0
        use wireguard
        address 192.168.42.1
        post-up iptables -A FORWARD -i wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE;iptables -A FORWARD -o wg0 -j ACCEPT
        post-down iptables -D FORWARD -i wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE;iptables -D FORWARD -o wg0 -j ACCEPT


This config will automatically:
To use the WireGuard OpenRC script with {{ic|wg-quick.wg0}}, create a symbolic link to it with the configuration name as follows:{{Cmd|# ln -s /etc/init.d/wg-quick /etc/init.d/wg-quick.wg0}}


* bring the WireGuard interface up after the eth0 interface
Add the {{ic|wg-quick.wg0}} service to the default runlevel:{{Cmd|# rc-update add wg-quick.wg0}}
* assign a config to this interface (which you have previously created)
To start|stop|restart the [[OpenRC]] service:{{Cmd|# rc-service wg-quick.wg0 start}}
* setup the interface address and netmask
* add the route once the interface is up
* remove the interface when it goes down
* enable traffic forwarding (the <code>post-up</code> and <code>post-down</code> lines; requires <code>iptables</code>) (note that this is not required unless you want peers to be able to access external resources like the internet)


To start and stop the interface, you execute:
=== Enable IP Forwarding ===


ifup wg0
With a NAT destination rule in place on your router, you should be able connect to the wireguard instance and access the host. However, if you intend for peers to be able to access external resources (including the internet), you will need to enable ip forwarding.
ifdown wg0


If your interface config is not stored under <code>/etc/wireguard/</code> you need to specify a <code>wireguard-config-path</code> as well.
Edit the file {{Path|/etc/sysctl.conf}} or a <code>.conf</code> file under {{Path|/etc/sysctl.d/}} folder add the following line as follows:{{Cat|/etc/sysctl.conf|
net.ipv4.ip_forward {{=}} 1
net.ipv6.conf.all.forwarding {{=}} 1
net.ipv6.conf.default.forwarding {{=}} 1}}




== Enable IP Forwarding ==
Add the sysctl service to run at boot:{{Cmd|# rc-update add sysctl}}


If you intend for peers to be able to access external resources (including the internet), you will need to enable forwarding.
Then either reboot or run {{ic|# sysctl -p /etc/sysctl.conf}} to reload the settings. To ensure forwarding is turned on, run {{ic|# sysctl -a | grep ip_forward}} and ensure <Code>net.ipv4.ip_forward</code> is set to <code>1</code>.
Edit the file <code>/etc/sysctl.conf</code> (or a <code>.conf</code> file under <code>/etc/sysctl.d/</code>) and add the following line.
 
net.ipv4.ip_forward = 1
 
Then either reboot or run <code>sysctl -p /etc/sysctl.conf</code> to reload the settings.
To ensure forwarding is turned on, run <code>sysctl -a | grep ip_forward</code> and ensure <code>net.ipv4.ip_forward</code> is set to <code>1</code>.
To make the change permanent across reboots, you may need to enable the <code>sysctl</code> service: <code>rc-update add sysctl</code>.


In the file {{Path|/etc/conf.d/iptables}}, Change the setting as follows:{{Cat|/etc/conf.d/iptables|...
IPFORWARD{{=}}"yes"}}


== Running with modloop ==
== Running with modloop ==


If you are running from a RAM disk, you can't modify the modloop.
If you are running [[Diskless Mode]] i.e from a RAM disk, you can't modify the modloop.  


You can get around it by unpacking the modloop, mounting the unpacked modules folder, then installing WireGuard.
You can get around it by unpacking the modloop, mounting the unpacked modules folder, then installing WireGuard.  


  #!/bin/sh
  #!/bin/sh
Line 113: Line 88:


You can repack the squash filesystem or put this script in the /etc/local.d/ path so it runs at boot-up.
You can repack the squash filesystem or put this script in the /etc/local.d/ path so it runs at boot-up.
== Preventing leaks ==
When using a private network over Wireguard, it may be desirable to prevent traffic from leaking onto other networks with the same range (e.g.: a Wi-Fi network using the same range).
Suppose we are using the network <code>fd00:feed:c0de::</code> over Wireguard. To prevent leaks using [[nftables]], use the following <code>/etc/nftables.d/private-network.nft</code>:
#!/usr/sbin/nft -f
table inet filter {
  chain output {
    type filter hook output priority 0;
    # Allow traffic to fd00:feed:c0de::1 only via wg0.
    ip6 daddr fd00:feed:c0de::1 oifname "wg0" accept
    # Drop all other attempts to reach fd00:feed:c0de::1.
    ip6 daddr fd00:feed:c0de::1 drop
  }
}
== Alternative Integrations into the Network Stack ==
{{Expand|Contributions welcome.  Thank you!}}
=== ConnMan Wireguard ===
'''{{Pkg|connman-wireguard}}''': An integration plugin enabling ConnMan management of WireGuard interfaces.
=== ifupdown-ng-wireguard ===
'''{{Pkg|ifupdown-ng-wireguard}}''': Supplies a declarative WireGuard interface for '''ifupdown-ng'''.
=== wireguard-go ===
'''{{Pkg|wireguard-go}}''': A userspace implementation of WireGuard in '''go''', not used by default in Alpine Linux except in containerized or restricted environments where kernel module loading is not possible. It can be used as a fallback on older kernels that do not offer WireGuard support.
== Tools ==
{{Expand|Contributions are encouraged.}}
=== Tailscale and NetBird ===
'''{{Pkg|tailscale}}''', '''{{Pkg|netbird}}''': Mesh VPNs built over WireGuard that streamline peer discovery and access control.
=== Rosenpass ===
'''{{Pkg|rosenpass}}''': Verified, post-quantum key exchange tool.
=== Innernet ===
'''{{Pkg|innernet}}''':  A private network based on WireGuard using centralized key management.  Currently in testing repository as of February 2026:  test by [[Repositories#Using_testing_repository|enabling and tagging the testing repository]] and installing as {{ic|innernet@testing}}. 
=== py3-wgconfig ===
'''{{Pkg|py3-wgconfig}}''':  Python library to parse and modify WireGuard config files that preserves comments.  Currently in testing repository as of February 2026:  ensure that the [[Repositories#Using_testing_repository|the testing repo is enabled and tagged]], and install as {{ic|py3-wgconfig@testing}}.
=== WireGuard Bash Completion ===
'''{{Pkg|wireguard-tools-bash-completion}}''': Enables tab completion in bash for {{Pkg|wg}} and {{Pkg|wg-quick}}.
== WireGuard Monitoring and Management ==
{{Expand|Contributions are encouraged.}}
=== Prometheus Wireguard Exporter ===
'''{{Pkg|prometheus-wireguard-exporter}}''': To monitor active peers,  traffic.  Rust-based, and must run with root privileges or with {{ic|CAP_NET_ADMIN}}.
== See also ==
* [https://github.com/pirate/wireguard-docs WireGuard documentation]
* [https://medium.com/nerd-for-tech/wireguard-vpn-monitoring-alerting-e1e1d1eaaa4e Setting up Prometheus WireGuard exporter, Grafana Dashboard, Alerts Manager.]


[[Category:Networking]]
[[Category:Networking]]

Latest revision as of 16:26, 19 February 2026

WireGuard multiple platform vpn solution. WireGuard itself is now integrated into the linux kernel since v5.6. Only the userland configuration tools are required.

Installation

The most straightforward method to configure WireGuard is to use the tool wg-quick available in the package wireguard-tools-wg-quick.

Install the meta package wireguard-tools to install the necessary WireGuard packages and iptables as follows:

# apk add wireguard-tools iptables

Configuration

Create Server Keys and Interface Config

Create a server private and public key:

# wg genkey | tee server.privatekey | wg pubkey > server.publickey

Remove any permissions on the file for users and groups other than the root user to ensure that only it can access the private key:

# chmod go= server.privatekey

Then, we create a new config file /etc/wireguard/wg0.conf using these new keys as follows:

Contents of /etc/wireguard/wg0.conf

[Interface] Address = 192.168.2.1/24, fddd::ffff/64 ListenPort = 45340 PrivateKey = <server private key value> # the key from the previously generated privatekey file PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE;iptables -A FORWARD -o %i -j ACCEPT; ip6tables -A FORWARD -i %i -j ACCEPT; ip6tables -t nat -A POSTROUTING -o eth0 -j MASQUERADE;ip6tables -A FORWARD -o %i -j ACCEPT PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE;iptables -D FORWARD -o %i -j ACCEPT; ip6tables -D FORWARD -i %i -j ACCEPT; ip6tables -t nat -D POSTROUTING -o eth0 -j MASQUERADE;ip6tables -D FORWARD -o %i -j ACCEPT [Peer] PublicKey = <client public key value> # obtained from client device via wireguard connection setup process AllowedIPs = 192.168.2.2/32, fddd::1/128

The PostUp and PostDown iptable rules forward traffic from the wg0 subnet (192.168.2.1/24) to the lan subnet on interface eth0. Refer to this WireGuard documentation for information on adding peers to the config file.

Bring up the new wg0 interface:

# wg-quick up wg0

To take it down, we can use wg-quick down wg0 which will clean up the interface and remove the iptables rules.

Note: If running in a Docker container, you will need to run with --cap-add=NET_ADMIN to modify your interfaces.

Use with network interfaces

To enable connecting with Wireguard on boot, open your /etc/network/interfaces and add this information after your auto other network interfaces as follows:

Contents of /etc/network/interfaces

... auto wg0 iface wg0 inet static pre-up wg-quick up /etc/wireguard/wg0.conf

Service configuration

Since Alpine 3.20, wireguard-tools-openrc package provides an OpenRC initd service file.

To use this, install the package:

# apk add wireguard-tools-openrc

To use the WireGuard OpenRC script with wg-quick.wg0, create a symbolic link to it with the configuration name as follows:

# ln -s /etc/init.d/wg-quick /etc/init.d/wg-quick.wg0

Add the wg-quick.wg0 service to the default runlevel:

# rc-update add wg-quick.wg0

To start|stop|restart the OpenRC service:

# rc-service wg-quick.wg0 start

Enable IP Forwarding

With a NAT destination rule in place on your router, you should be able connect to the wireguard instance and access the host. However, if you intend for peers to be able to access external resources (including the internet), you will need to enable ip forwarding.

Edit the file /etc/sysctl.conf or a .conf file under /etc/sysctl.d/ folder add the following line as follows:

Contents of /etc/sysctl.conf

net.ipv4.ip_forward = 1 net.ipv6.conf.all.forwarding = 1 net.ipv6.conf.default.forwarding = 1


Add the sysctl service to run at boot:

# rc-update add sysctl

Then either reboot or run # sysctl -p /etc/sysctl.conf to reload the settings. To ensure forwarding is turned on, run # sysctl -a and ensure net.ipv4.ip_forward is set to 1.

In the file /etc/conf.d/iptables, Change the setting as follows:

Contents of /etc/conf.d/iptables

... IPFORWARD="yes"

Running with modloop

If you are running Diskless Mode i.e from a RAM disk, you can't modify the modloop.

You can get around it by unpacking the modloop, mounting the unpacked modules folder, then installing WireGuard. 

#!/bin/sh
apk add squashfs-tools # install squashfs tools to unpack modloop
unsquashfs -d /root/squash /lib/modloop-lts # unpack modloop to root dir
umount /.modloop # unmount existing modloop
mount /root/squash/ /.modloop/ # mount unpacked modloop
apk del wireguard-lts # uninstall previous WireGuard install
apk add wireguard-lts
apk add wireguard-tools

You can repack the squash filesystem or put this script in the /etc/local.d/ path so it runs at boot-up.

Preventing leaks

When using a private network over Wireguard, it may be desirable to prevent traffic from leaking onto other networks with the same range (e.g.: a Wi-Fi network using the same range).

Suppose we are using the network fd00:feed:c0de:: over Wireguard. To prevent leaks using nftables, use the following /etc/nftables.d/private-network.nft: 

#!/usr/sbin/nft -f

table inet filter {
  chain output {
    type filter hook output priority 0;

    # Allow traffic to fd00:feed:c0de::1 only via wg0.
    ip6 daddr fd00:feed:c0de::1 oifname "wg0" accept

    # Drop all other attempts to reach fd00:feed:c0de::1.
    ip6 daddr fd00:feed:c0de::1 drop
  }
}

Alternative Integrations into the Network Stack

This material needs expanding ...

Contributions welcome. Thank you!

ConnMan Wireguard

connman-wireguard: An integration plugin enabling ConnMan management of WireGuard interfaces.

ifupdown-ng-wireguard

ifupdown-ng-wireguard: Supplies a declarative WireGuard interface for ifupdown-ng.

wireguard-go

wireguard-go: A userspace implementation of WireGuard in go, not used by default in Alpine Linux except in containerized or restricted environments where kernel module loading is not possible. It can be used as a fallback on older kernels that do not offer WireGuard support.

Tools

This material needs expanding ...

Contributions are encouraged.

Tailscale and NetBird

tailscale, netbird: Mesh VPNs built over WireGuard that streamline peer discovery and access control.

Rosenpass

rosenpass: Verified, post-quantum key exchange tool.

Innernet

innernet: A private network based on WireGuard using centralized key management. Currently in testing repository as of February 2026: test by enabling and tagging the testing repository and installing as innernet@testing.

py3-wgconfig

py3-wgconfig: Python library to parse and modify WireGuard config files that preserves comments. Currently in testing repository as of February 2026: ensure that the the testing repo is enabled and tagged, and install as py3-wgconfig@testing.

WireGuard Bash Completion

wireguard-tools-bash-completion: Enables tab completion in bash for wg and wg-quick.

WireGuard Monitoring and Management

This material needs expanding ...

Contributions are encouraged.

Prometheus Wireguard Exporter

prometheus-wireguard-exporter: To monitor active peers, traffic. Rust-based, and must run with root privileges or with CAP_NET_ADMIN.

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Configure_a_Wireguard_interface_(wg)&oldid=32078"