Olm (Deprecated)

We recommend using the Pangolin CLI for both user and machine clients if you're looking for a CLI interface. Olm is the underlying client for the Pangolin CLI.

Olm is a command-line client for connecting machine clients in Pangolin. You can configure it using command-line flags, environment variables, or a configuration file.

Install

Binary Installation (Linux)

Quick Install (Recommended)

Use this command to automatically install Olm. It detects your system architecture automatically and always pulls the latest version, adding Olm to your PATH:

curl -fsSL https://static.pangolin.net/get-olm.sh | bash

Windows

If you would like to use Olm on Windows, wintun.dll is required. Please use latest installer from GitHub releases.

Manual Download

Binaries for Linux, macOS, and Windows are available in the GitHub releases for ARM and AMD64 (x86_64) architectures.

Download and install manually:

wget -O olm "https://github.com/fosrl/olm/releases/download/{version}/olm_{architecture}" && chmod +x ./olm

Replace {version} with the desired version and {architecture} with your architecture. Check the release notes for the latest information.

Running Olm

Run Olm with the configuration from Pangolin:

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

Systemd Service

Create a basic systemd service:

/etc/systemd/system/olm.service

[Unit]
Description=Olm
After=network.target

[Service]
ExecStart=/usr/local/bin/olm --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com
Restart=always
User=root

[Install]
WantedBy=multi-user.target

Make sure to move the binary to /usr/local/bin/olm before creating the service!

Docker

You can also run it with Docker compose. For example, a service in your docker-compose.yml might look like this using environment vars (recommended):

services:
    olm:
        image: fosrl/olm
        container_name: olm
        restart: unless-stopped
        network_mode: host
        cap_add:
            - NET_ADMIN
        devices:
            - /dev/net/tun:/dev/net/tun
        environment:
            - PANGOLIN_ENDPOINT=https://example.com
            - OLM_ID=31frd0uzbjvp721
            - OLM_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6

You can also pass the CLI args to the container:

services:
    olm:
        image: fosrl/olm
        container_name: olm
        restart: unless-stopped
        network_mode: host
        cap_add:
            - NET_ADMIN
        devices:
            - /dev/net/tun:/dev/net/tun
        command:
            - --id 31frd0uzbjvp721
            - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
            - --endpoint https://example.com

Docker Configuration Notes:

network_mode: host brings the olm network interface to the host system, allowing the WireGuard tunnel to function properly
cap_add: - NET_ADMIN is required to grant the container permission to manage network interfaces
devices: - /dev/net/tun:/dev/net/tun is required to give the container access to the TUN device for creating WireGuard interfaces

Windows Service

On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to install and run the service to function like a cli tool.

Minimum Windows version: Windows 10

Service Management Commands

# Install the service
olm.exe install

# Start the service
olm.exe start

# Stop the service
olm.exe stop

# Check service status
olm.exe status

# Remove the service
olm.exe remove

# Run in debug mode (console output) with our without id & secret
olm.exe debug

# Show help
olm.exe help

Note running the service requires credentials in %PROGRAMDATA%\olm\olm-client\config.json.

Service Configuration

When running as a service, Olm will read configuration from environment variables or you can modify the service to include command-line arguments:

Install the service: olm.exe install
Set the credentials in %PROGRAMDATA%\olm\olm-client\config.json. Hint: if you run olm once with --id and --secret this file will be populated!
Start the service: olm.exe start

Service Logs

When running as a service, logs are written to:

Windows Event Log (Application log, source: "OlmWireguardService")
Log files in: %PROGRAMDATA%\olm\logs\olm.log

You can view the Windows Event Log using Event Viewer or PowerShell:

Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10

Gotchas

Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes:

Windows: Olm will run as a service. You can use the service management commands to manage it and run it in the background.
LXC containers: Need to be configured to allow tun access. On Proxmox see below.
Linux: May require root privileges or specific capabilities to create tun interfaces.
macOS: May require additional permissions for network interface creation.

LXC Proxmox

Create your LXC container.
Go to the Resources tab of the container.
Select Add. Then select Device Passthrough.
On the Add Device prompt, enter dev/net/tun in the Device Path field and select Add.
If the container is running, shut it down and start it up again.

Once /dev/net/tun is available, the olm can run within the LXC.

Configure

DNS, MTU, and other preferences shared across clients are on Platforms.

Flags

idstringrequired

Olm ID generated by Pangolin to identify the client.

Example: 31frd0uzbjvp721

secretstringrequired

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.

endpointstringrequired

The endpoint where the Pangolin server resides for websocket connections.

Example: https://pangolin.example.com

orgstring

Organization ID to connect to.

user-tokenstring

User authentication token.

mtuinteger

MTU for the internal WireGuard interface.

Default: 1280

dnsstring

DNS server to use to resolve the endpoint.

Default: 8.8.8.8

upstream-dnsstring

Upstream DNS server(s), comma-separated.

Default: 8.8.8.8:53

match-domains-dnsstring

FQDN wildcard patterns (using * and ? wildcards, comma-separated, e.g. *.proxy.internal,*.host-0?.autoco.internal) to check against local records/upstream DNS. Queries for domains that don't match any pattern are sent directly to the host's own system DNS servers instead of being resolved as Pangolin resources.

Default: (empty, matches every domain)

log-levelstring

The log level to use for Olm output.

Options: DEBUG, INFO, WARN, ERROR, FATAL

Default: INFO

ping-intervalstring

Interval for pinging the server.

Default: 3s

ping-timeoutstring

Timeout for each ping.

Default: 5s

interfacestring

Name of the WireGuard interface.

Default: olm

enable-apiboolean

Enable API server for receiving connection requests.

Default: false

http-addrstring

HTTP server address (e.g., ':9452'). When unset, the HTTP API is not started and the socket API (see socket-path) is used instead.

Default: (not set)

socket-pathstring

Unix socket path (or named pipe on Windows).

Default: /var/run/olm.sock (Linux/macOS) or olm (Windows)

disable-holepunchboolean

Disable hole punching.

Default: false

override-dnsboolean

When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system's default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured Upstream DNS Server.

Default: true

tunnel-dnsboolean

When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server.

Default: false

match-domains-dnsstring

Optional comma-separated whitelist of domains sent to the configured upstream DNS server. When unset, all queries go to upstream DNS. When set, only matching queries use your Upstream DNS Server; all other requests use the system's DNS servers. Supports wildcards such as *.proxy.internal.

disable-relayboolean

Disable relay connections.

Default: false

prefer-local-routesboolean

When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel.

Default: false

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.

When both environment variables and CLI arguments are provided, CLI arguments take precedence.

PANGOLIN_ENDPOINTstring

Endpoint of your Pangolin server (equivalent to --endpoint)

OLM_IDstring

Olm ID generated by Pangolin (equivalent to --id)

OLM_SECRETstring

Olm secret for authentication (equivalent to --secret)

ORGstring

Organization ID to connect to (equivalent to --org)

USER_TOKENstring

User authentication token (equivalent to --user-token)

MTUinteger

MTU for the internal WireGuard interface (equivalent to --mtu)

Default: 1280

DNSstring

DNS server to use to resolve the endpoint (equivalent to --dns)

Default: 8.8.8.8

UPSTREAM_DNSstring

Upstream DNS server(s), comma-separated (equivalent to --upstream-dns)

Default: 8.8.8.8:53

MATCH_DOMAINS_DNSstring

FQDN wildcard patterns, comma-separated (equivalent to --match-domains-dns)

Default: (empty, matches every domain)

LOG_LEVELstring

Log level (equivalent to --log-level)

Default: INFO

PING_INTERVALstring

Interval for pinging the server (equivalent to --ping-interval)

Default: 3s

PING_TIMEOUTstring

Timeout for each ping (equivalent to --ping-timeout)

Default: 5s

INTERFACEstring

Name of the WireGuard interface (equivalent to --interface)

Default: olm

ENABLE_APIboolean

Enable API server for receiving connection requests (equivalent to --enable-api)

Set to "true" to enable

Default: false

HTTP_ADDRstring

HTTP server address (equivalent to --http-addr)

Default: (not set)

SOCKET_PATHstring

Unix socket path or Windows named pipe (equivalent to --socket-path)

Default: /var/run/olm.sock (Linux/macOS) or olm (Windows)

DISABLE_HOLEPUNCHboolean

Disable hole punching (equivalent to --disable-holepunch)

Set to "true" to disable

Default: false

OVERRIDE_DNSboolean

Override system DNS settings (equivalent to --override-dns)

Set to "true" to enable

Default: true

TUNNEL_DNSboolean

Route DNS queries through the tunnel (equivalent to --tunnel-dns)

Set to "true" to enable

Default: false

MATCH_DOMAINS_DNSstring

Optional whitelist of domains sent to the configured upstream DNS server (equivalent to --match_domains_dns). When unset, all queries go to upstream DNS.

PREFER_LOCAL_ROUTESboolean

Default: false

DISABLE_RELAYboolean

Disable relay connections (equivalent to --disable-relay)

Set to "true" to disable

Default: false

CONFIG_FILEstring

Set to the location of a JSON file to load secret values

Config File

You can use CONFIG_FILE to define a location of a config file to store the credentials between runs.

$ cat ~/.config/olm-client/config.json
{
  "id": "spmzu8rbpzj1qq6",
  "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
  "endpoint": "https://app.pangolin.net",
  "org": "",
  "userToken": "",
  "mtu": 1280,
  "dns": "8.8.8.8",
  "upstreamDNS": ["8.8.8.8:53"],
  "matchDomainsDNS": [],
  "interface": "olm",
  "logLevel": "INFO",
  "enableApi": false,
  "httpAddr": "",
  "socketPath": "/var/run/olm.sock",
  "pingInterval": "3s",
  "pingTimeout": "5s",
  "disableHolepunch": false,
  "overrideDNS": true,
  "tunnelDNS": false,
  "disableRelay": false,
  "tlsClientCert": "",
  "preferLocalRoutes": false
}

This file is also written to when olm first starts up. So you do not need to run every time with --id and secret if you have run it once!

Default locations:

macOS: ~/Library/Application Support/olm-client/config.json
Windows: %PROGRAMDATA%\olm\olm-client\config.json
Linux/Others: ~/.config/olm-client/config.json

API

Olm can be started with a HTTP or socket API to configure and manage it. See the API documentation for more details.

Update

Re-run the install script to pull the latest version:

curl -fsSL https://static.pangolin.net/get-olm.sh | bash

On Windows, download the latest installer from the GitHub releases. You can also download a binary for your system from the GitHub releases and replace the existing binary.

InstallCopy Anchor Link

Binary Installation (Linux)Copy Anchor Link

Quick Install (Recommended)Copy Anchor Link

WindowsCopy Anchor Link

Manual DownloadCopy Anchor Link

Running OlmCopy Anchor Link

Systemd ServiceCopy Anchor Link

DockerCopy Anchor Link

Windows ServiceCopy Anchor Link

Service Management CommandsCopy Anchor Link

Service ConfigurationCopy Anchor Link

Service LogsCopy Anchor Link

GotchasCopy Anchor Link

LXC ProxmoxCopy Anchor Link

ConfigureCopy Anchor Link

FlagsCopy Anchor Link

Environment VariablesCopy Anchor Link

Config FileCopy Anchor Link

APICopy Anchor Link

UpdateCopy Anchor Link

On this page

Install

Binary Installation (Linux)

Quick Install (Recommended)

Windows

Manual Download

Running Olm

Systemd Service

Docker

Windows Service

Service Management Commands

Service Configuration

Service Logs

Gotchas

LXC Proxmox

Configure

Flags

Environment Variables

Config File

API

Update