acsimon33/truenas-wireguard-client-app repository overview

⁠TrueNAS WireGuard Client App

A small WireGuard client container intended for running a persistent site-to-site VPN endpoint as a TrueNAS SCALE Custom App.

The container renders a wg-quick configuration from environment variables, stores changed configs as timestamped history, starts one WireGuard interface, optionally refreshes a dynamic DNS endpoint, and cleans the interface up when the app stops.

⁠Features

• Designed for TrueNAS SCALE Custom Apps
• Runs as a WireGuard client using wg-quick
• Environment-variable driven configuration
• Optional persistent config history in /config
• Optional DNS endpoint refresh for dynamic peer hostnames
• Supports PreUp, PostUp, PreDown, and PostDown hooks

⁠Important TrueNAS Requirements

To let the tunnel affect the TrueNAS host network, run the app with:

• Host Network enabled
• Privileged enabled
• Restart policy set to Unless Stopped or Always
• No port forwarding
• A persistent volume mounted at /config is recommended

Privileged mode gives the container broad host access. This is required for the simple TrueNAS Custom App setup because WireGuard interfaces, routes, iptables, and sysctl changes must happen in the host network namespace. Only run images you trust.

⁠Required Environment Variables

⁠Optional Environment Variables

Use a WG_IF name that this app owns. If another host service already uses wg0, stop that service first, choose another interface name, or set WG_REPLACE_EXISTING=true.

⁠Persistent Config History

Mount a persistent volume at:

/config

On each startup, the app renders a config from the environment.

Changed configs are saved as:

/config/wg0-YYYYMMDDTHHMMSSZ.conf

The latest config is linked as:

/config/wg0.conf

If the generated config has not changed, no duplicate history file is created.

⁠Example TrueNAS Custom App Environment

WG_ADDRESS=10.255.0.2/32
WG_PRIVATE_KEY=<site-b-private-key>
PEER_PUBLIC_KEY=<site-a-public-key>
PEER_ENDPOINT=wg.example.com:51820
PEER_ALLOWED_IPS=172.20.10.0/24,10.255.0.1/32
PEER_PERSISTENT_KEEPALIVE=25
RESOLVE_INTERVAL=300

This creates a WireGuard client tunnel from the TrueNAS host to the remote peer.

⁠Forwarding Example

If the remote site should reach hosts behind the TrueNAS system, enable forwarding and add firewall rules. Replace br0 with the actual TrueNAS LAN interface.

PRE_UP=sysctl -w net.ipv4.ip_forward=1
POST_UP=iptables -A FORWARD -i wg0 -o br0 -j ACCEPT; iptables -A FORWARD -i br0 -o wg0 -j ACCEPT
POST_DOWN=iptables -D FORWARD -i wg0 -o br0 -j ACCEPT; iptables -D FORWARD -i br0 -o wg0 -j ACCEPT

If the local router does not have a static route back to the remote tunnel/LAN networks, add masquerading:

POST_UP=iptables -A FORWARD -i wg0 -o br0 -j ACCEPT; iptables -A FORWARD -i br0 -o wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -s 172.20.10.0/24 -o br0 -j MASQUERADE; iptables -t nat -A POSTROUTING -s 10.255.0.0/24 -o br0 -j MASQUERADE
POST_DOWN=iptables -D FORWARD -i wg0 -o br0 -j ACCEPT; iptables -D FORWARD -i br0 -o wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -s 172.20.10.0/24 -o br0 -j MASQUERADE; iptables -t nat -D POSTROUTING -s 10.255.0.0/24 -o br0 -j MASQUERADE

⁠Tags

• latest
• Release tags, when published
• sha-... tags for non-release builds

⁠Source

GitHub: https://github.com/ACSimon33/truenas-wireguard-client-app⁠

⁠License

MIT