Olm is a WireGuard client designed to securely connect your remote computer to your Pangolin network. By using Olm, you can create a traditional VPN tunnel that allows you to access resources on your private network from anywhere.

​
How Olm Works

​
Registers with Pangolin

Using the Olm ID and a secret, the client will make HTTP requests to Pangolin to receive a session token. Using that token, it will connect to a websocket and maintain that connection. Control messages will be sent over the websocket.

​
Establishes WireGuard Tunnel

When Olm receives WireGuard control messages, it will use the information encoded (endpoint, public key) to bring up a WireGuard tunnel using native system interfaces. It will ping over the tunnel to ensure the peer on the Gerbil side is brought up.

​
Creates Virtual Network Interface

Olm creates a virtual network adapter on your computer just like a traditional VPN. This allows you to access resources on your private network as if you were physically connected to it.

​
Configuration Arguments

​
id
string
required
Olm ID generated by Pangolin to identify the client.Example: 31frd0uzbjvp721
​
secret
string
required
A unique secret used to authenticate the client ID with the websocket.Example: h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
Keep this secret private and secure. It’s used for authentication.
​
endpoint
string
required
The endpoint where both Gerbil and Pangolin reside for websocket connections.Example: https://pangolin.example.com
​
mtu
integer
MTU for the WireGuard interface.Default: 1280
​
dns
string
DNS server to use for resolving the endpoint.Default: 8.8.8.8
​
log-level
string
The log level to use for Olm output.Options: DEBUG, INFO, WARN, ERROR, FATALDefault: INFO
​
ping-interval
string
Interval for pinging the server.Default: 3s
​
ping-timeout
string
Timeout for each ping.Default: 5s
​
holepunch
boolean
Enable NAT hole punching mode instead of relaying through the VPS.Default: false
This is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying.
​
health-file
string
Check if connection to WireGuard server (Pangolin) is ok. Creates a file if ok, removes it if not ok. Can be used with Docker healthcheck to restart Olm.Example: /tmp/olm-health
​
config-file
string
Path to a configuration file containing the same arguments as command line.Example: /etc/olm/config.yaml

​
Configuration Examples

​
Basic Configuration

olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com

​
With Hole Punching

olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--holepunch

​
With Custom MTU and DNS

olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--mtu 1400 \
--dns 1.1.1.1

​
With Health Check

olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--health-file /tmp/olm-health

​
Environment Variables

All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables are particularly useful when running Olm in containerized environments.
​
PANGOLIN_ENDPOINT
string
Endpoint of your Pangolin server (equivalent to --endpoint)
​
OLM_ID
string
Olm ID generated by Pangolin (equivalent to --id)
​
OLM_SECRET
string
Olm secret for authentication (equivalent to --secret)
​
OLM_MTU
integer
MTU for the WireGuard interface (equivalent to --mtu)Default: 1280
​
OLM_DNS
string
DNS server to use for resolving the endpoint (equivalent to --dns)Default: 8.8.8.8
​
OLM_LOG_LEVEL
string
Log level (equivalent to --log-level)Default: INFO
​
OLM_PING_INTERVAL
string
Interval for pinging the server (equivalent to --ping-interval)Default: 3s
​
OLM_PING_TIMEOUT
string
Timeout for each ping (equivalent to --ping-timeout)Default: 5s
​
OLM_HOLEPUNCH
boolean
Enable NAT hole punching mode (equivalent to --holepunch)Default: false
​
OLM_HEALTH_FILE
string
Path to health file for connection monitoring (equivalent to --health-file)
​
OLM_CONFIG_FILE
string
Load the config from this file instead of command line arguments (equivalent to --config-file)
When both environment variables and CLI arguments are provided, CLI arguments take precedence.

​
Troubleshooting

​
Connection Issues

  1. Check credentials: Ensure the ID and secret are correct
  2. Verify endpoint: Make sure the endpoint URL is accessible
  3. Check firewall: Ensure port 21820 is open on your VPS
  4. Verify site configuration: Make sure your Newt site has --accept-clients enabled

​
Permission Issues

  1. Linux/macOS: Run with sudo or ensure proper capabilities
  2. Windows: Run as administrator or install as a service
  3. LXC containers: Configure tun device access

​
Performance Issues

  1. Try hole punching: Use --holepunch for better performance
  2. Adjust MTU: Try different MTU values if experiencing packet loss
  3. Check network: Ensure stable internet connection

​
Security Considerations

  • Keep your client secret secure and private
  • Use HTTPS endpoints only
  • Regularly rotate client credentials
  • Monitor client connections in the dashboard
  • Use firewall rules to restrict access to specific resources