Configuration Reference
onetun is configured primarily via Command Line Arguments, but all arguments can also be set via Environment Variables.
Port Forward Syntax
The positional arguments to onetun define the port forwards. You can define multiple forwards by separating them with spaces.
Syntax:
[bind_ip:]<bind_port>:<remote_ip>:<remote_port>[:PROTOCOL]
| Component | Description | Default |
|---|---|---|
bind_ip |
The local IP address onetun will listen on. |
127.0.0.1 |
bind_port |
The local port onetun will listen on. |
Required |
remote_ip |
The target IP in the WireGuard network. | Required |
remote_port |
The target port on the remote IP. | Required |
PROTOCOL |
TCP or UDP. Comma-separated for both. |
TCP |
Examples:
8080:192.168.4.2:80(Listens on localhost:8080, forwards to 192.168.4.2:80 TCP)0.0.0.0:3000:10.0.0.5:5432(Listens on all interfaces on port 3000, forwards to Postgres)[::1]:8080:192.168.4.1:80(IPv6 Listener)5353:192.168.4.5:53:UDP(UDP Forwarding for DNS)
Options
| Flag | Env Variable | Description | Required |
|---|---|---|---|
--endpoint-addr |
ONETUN_ENDPOINT_ADDR |
The public address (IP:Port) of the WireGuard server. | Yes |
--endpoint-public-key |
ONETUN_ENDPOINT_PUBLIC_KEY |
The public key of the WireGuard server. | Yes |
--private-key |
ONETUN_PRIVATE_KEY |
The private key for this client. | Yes* |
--private-key-file |
ONETUN_PRIVATE_KEY_FILE |
Path to file containing the private key. | Yes* |
--source-peer-ip |
ONETUN_SOURCE_PEER_IP |
The IP address assigned to this client inside the WireGuard network. | Yes |
--preshared-key |
ONETUN_PRESHARED_KEY |
Optional WireGuard Pre-Shared Key (PSK). | No |
--keep-alive |
ONETUN_KEEP_ALIVE |
Persistent keep-alive interval in seconds. | No |
--log |
ONETUN_LOG |
Log level (e.g., info, debug, trace). |
No (Default: info) |
--max-transmission-unit |
ONETUN_MTU |
MTU size. | No (Default: 1420) |
--endpoint-bind-addr |
ONETUN_ENDPOINT_BIND_ADDR |
Local UDP address to bind for the outgoing WireGuard connection. | No |
--pcap |
ONETUN_PCAP |
File path to write captured WireGuard packets (for debugging). | No |
* Either --private-key or --private-key-file must be provided.
Configuring via Environment Variables
Instead of passing arguments, you can use environment variables. This is especially useful for Docker.
Port Forwards via Env
To configure port forwards using environment variables (since positional arguments can't be named directly), use the pattern ONETUN_PORT_FORWARD_# where # is a number starting from 1.
export ONETUN_PORT_FORWARD_1="127.0.0.1:8080:192.168.4.2:80"
export ONETUN_PORT_FORWARD_2="127.0.0.1:3000:192.168.4.5:5432"UDP Support
UDP support is experimental. To enable it, append :UDP to your port forward string.
onetun 127.0.0.1:5000:192.168.4.2:5000:UDPYou can also support both TCP and UDP on the same port:
onetun 127.0.0.1:5353:192.168.4.2:53:UDP,TCP