olm/README.md

Olm

Olm is a WireGuard tunnel manager designed to securely connect to private resources. By using Olm, you don't need to manage complex WireGuard tunnels.

Installation and Documentation

Olm is used with Pangolin and Newt as part of the larger system. See documentation below:

• Installation Instructions
• Full Documentation

Key Functions

Registers with Pangolin

Using the Olm ID and a secret, the olm 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.

Receives WireGuard Control Messages

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

Receives Proxy Control Messages

When Olm receives WireGuard control messages, it will use the information encoded to create a local low level TCP and UDP proxies attached to the virtual tunnel in order to relay traffic to programmed targets.

CLI Args

• endpoint: The endpoint where both Gerbil and Pangolin reside in order to connect to the websocket.
• id: Olm ID generated by Pangolin to identify the olm.
• secret: A unique secret (not shared and kept private) used to authenticate the olm ID with the websocket in order to receive commands.
• dns: DNS server to use to resolve the endpoint
• log-level (optional): The log level to use. Default: INFO

Example:

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

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
    environment:
      - PANGOLIN_ENDPOINT=https://example.com
      - OLM_ID=2ix2t8xk22ubpfy 
      - OLM_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 

You can also pass the CLI args to the container:

services:
  olm:
    image: fosrl/olm
    container_name: olm
    restart: unless-stopped
    command:
        - --id 31frd0uzbjvp721
        - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
        - --endpoint https://example.com

Finally a basic systemd service:

[Unit]
Description=Olm VPN 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 mv ./olm /usr/local/bin/olm!

Windows Service

On Windows, Olm can be installed and run as a Windows service. This allows it to start automatically at boot and run in the background.

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)
olm.exe debug

# Show help
olm.exe help

Helper Scripts: For easier service management, you can use the provided helper scripts:

• olm-service.bat - Batch script (requires Administrator privileges)
• olm-service.ps1 - PowerShell script with better error handling

Example using the batch script:

# Run as Administrator
olm-service.bat install
olm-service.bat start
olm-service.bat status

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:

1. Install the service: olm.exe install
2. Configure the service with your credentials using Windows Service Manager or by setting system environment variables:
   • PANGOLIN_ENDPOINT=https://example.com
   • OLM_ID=your_olm_id
   • OLM_SECRET=your_secret
3. 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

Build

Container

Ensure Docker is installed.

make

Binary

Make sure to have Go 1.23.1 installed.

make local

Licensing

Olm is dual licensed under the AGPLv3 and the Fossorial Commercial license. For inquiries about commercial licensing, please contact us.

Contributions

Please see CONTRIBUTIONS in the repository for guidelines and best practices.