Configuration

TunGuard is configured through environment variables.

Most installations can use the default values. Change a setting when you need a different interface, port, network, data directory, or service configuration.

Environment Variables⚓

WireGuard Settings⚓

WG_INTERFACE⚓

Controls the name of the WireGuard interface created by TunGuard.

Default:

wg0

Example:

WG_INTERFACE=wg1

WG_LISTEN_PORT⚓

Controls the UDP port used by the WireGuard server.

Default:

13231

Clients must connect to this port.

Example:

WG_LISTEN_PORT=51820

If you change this value, make sure the new UDP port is allowed through your server firewall.

WG_ADDRESS⚓

Sets the server's address on the VPN network.

Default:

10.100.0.1/24

Example:

WG_ADDRESS=10.50.0.1/24

The address must belong to the subnet configured with WG_SUBNET.

WG_SUBNET⚓

Defines the VPN network used by TunGuard clients.

Default:

10.100.0.0/24

Example:

WG_SUBNET=10.50.0.0/24

The server address configured with WG_ADDRESS must belong to this subnet.

WG_MTU⚓

Sets the WireGuard interface MTU.

Default:

1420

Example:

WG_MTU=1380

Only change the MTU when required by your network.

API and Dashboard⚓

API_LISTEN⚓

Controls where the web dashboard and API listen.

Default:

:9000

This listens on TCP port 9000 on all interfaces.

Example:

API_LISTEN=:8080

WEB_ENABLED⚓

Enables the web dashboard.

Default:

false

The dashboard can also be enabled with:

./tanguard -web

When using the normal installer, the installed service can be configured to enable the dashboard.

WEB_USERNAME⚓

Sets the initial dashboard username.

Default:

admin

This value is only used until the dashboard credentials are changed.

WEB_PASSWORD⚓

Sets the initial dashboard password.

Default:

tanguard

This value is only used until the dashboard credentials are changed.

Change the default credentials before exposing the dashboard publicly.

Data Directory⚓

DATA_DIR⚓

Controls where TunGuard stores persistent data.

Default:

.

The directory contains data such as:

• Server private key
• Peer information
• Dashboard credentials
• API key
• SSH host key
• Other persistent TunGuard state

Example:

DATA_DIR=/var/lib/tanguard

When changing this value, make sure the TunGuard process has permission to access the directory.

Network Interface⚓

EXTERNAL_NIC⚓

Specifies the external network interface used for NAT.

Default:

auto

TunGuard automatically detects the external interface.

To specify an interface manually:

EXTERNAL_NIC=eth0

This can be useful on servers with multiple network interfaces.

SSH Gateway⚓

SSH_ENABLED⚓

Enables the TunGuard SSH gateway.

Default:

false

It can also be enabled with:

./tanguard -ssh

SSH_LISTEN⚓

Controls where the SSH gateway listens.

Default:

:2222

Example:

SSH_LISTEN=:2200

If you change the port, make sure the new TCP port is allowed through your firewall.

SSH_KEY_FILE⚓

Specifies the SSH host key file.

Default:

auto

When set to auto, TunGuard generates a host key when one does not already exist.

Example:

SSH_KEY_FILE=/var/lib/tanguard/ssh_host_key

API Key⚓

The API key is not set through an environment variable. It is generated from the dashboard under Settings → API Key, or with:

curl -X POST \
  -u admin:PASSWORD \
  http://127.0.0.1:9000/api/key/regenerate

It is stored in api_key.json inside DATA_DIR, and can then be supplied with individual API requests:

curl \
  -H "X-API-Key: YOUR_API_KEY" \
  http://127.0.0.1:9000/api/peers

Regenerating the key invalidates the previous one immediately.

See the API documentation for authentication and available endpoints.

P2P Control Plane⚓

The P2P mesh runs as a second subsystem alongside WireGuard. It is enabled by default and needs no configuration, but these variables control it.

MESH_ENABLED⚓

Enables the P2P control plane.

Default:

true

With MESH_ENABLED=false the control listener and the rendezvous hub are never started, and every /api/mesh/* endpoint returns 503 tun control plane is disabled. Starting with -mesh-only while the mesh is disabled makes the process refuse to run.

CONTROL_LISTEN⚓

The TCP address that clients dial out to. This is the port that goes in the tun <server-ip> <psk> command.

Default:

:7000

RELAY_LISTEN⚓

The UDP address of the rendezvous hub, where clients register their public endpoint and discover each other.

Default:

:7001

Both ports must be reachable from the internet. If the hub port is unreachable, clients still connect and appear online but never discover each other, so no link can go direct.

CONTROL_TIMEOUT_S⚓

How long, in seconds, a client has to complete its handshake after connecting.

Default:

10

MESH_DATA_DIR⚓

Where the mesh node registry is stored.

Default:

(the value of DATA_DIR)

Domain Proxy⚓

The HTTPS domain proxy publishes an internal service on a public domain with an automatic Let's Encrypt certificate. It is on by default but does nothing until the first mapping is added.

DOMAIN_ENABLED⚓

Enables the HTTPS domain proxy.

Default:

true

The proxy binds no ports and makes no certificate request until a mapping is configured. Set it to false to disable entirely.

DOMAIN_HTTP_PORT⚓

Default:

80

The public HTTP port, used for the HTTP-01 challenge and the HTTP→HTTPS redirect.

DOMAIN_HTTPS_PORT⚓

Default:

443

The public HTTPS port of the domain proxy.

DOMAIN_CHALLENGE_PORT⚓

Default:

8100

The loopback-only port where the Let's Encrypt HTTP-01 challenge answers, before a managed webserver (nginx, Apache, Caddy, Traefik) proxies it to the public HTTP port.

See Domains & HTTPS Proxy for how to manage mappings.

AdGuard Home⚓

TunGuard can manage an AdGuard Home instance for DNS filtering. It is enabled by default and starts with TunGuard; devices in an AdGuard-enabled policy group have their port-53 DNS redirected to it.

ADGUARD_ENABLED⚓

Runs the managed AdGuard Home instance.

Default:

true

ADGUARD_BINARY⚓

Path or name of the AdGuard Home binary.

Default:

adguardhome

When missing, TunGuard looks next to its own executable, in DATA_DIR, in the working directory, /usr/local/bin, and /usr/bin, then downloads the official release for the architecture.

ADGUARD_DATA_DIR⚓

Where AdGuard's configuration and data live.

Default:

(the value of DATA_DIR)

ADGUARD_DNS_LISTEN⚓

The address AdGuard's DNS service binds.

Default:

(the tunnel IP from WG_ADDRESS, port 53)

For example, with WG_ADDRESS=10.100.0.1/24 the DNS service listens on 10.100.0.1:53. If WG_ADDRESS cannot be parsed it falls back to 127.0.0.1:5353.

ADGUARD_WEB_LISTEN⚓

The loopback address of the AdGuard admin UI.

Default:

127.0.0.1:1116

Remote access goes through the authenticated /adguard-ui/ proxy on the dashboard port.

ADGUARD_UPSTREAM⚓

The upstream resolver AdGuard queries.

Default:

1.1.1.1

ADGUARD_UPSTREAM_FAMILY⚓

The upstream used while the adult-content filter is on.

Default:

1.1.1.2

ADGUARD_FILTER_ADULT⚓

Switches AdGuard to family-mode filtering.

Default:

false

See AdGuard DNS Filtering for the full feature guide.

Example Configuration⚓

A typical server configuration could look like:

WG_INTERFACE=wg0
WG_LISTEN_PORT=13231
WG_ADDRESS=10.100.0.1/24
WG_SUBNET=10.100.0.0/24
WG_MTU=1420

API_LISTEN=:9000
DATA_DIR=/var/lib/tanguard
EXTERNAL_NIC=auto

WEB_ENABLED=true

SSH_ENABLED=true
SSH_LISTEN=:2222
SSH_KEY_FILE=auto

MESH_ENABLED=true
CONTROL_LISTEN=:7000
RELAY_LISTEN=:7001

Not every variable needs to be configured. TunGuard uses the defaults when a variable is not provided.