# Olm

Olm is a [WireGuard](https://www.wireguard.com/) 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](https://docs.fossorial.io)
-   [Full Documentation](https://docs.fossorial.io)

## 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](https://github.com/WireGuard/wireguard-go/blob/master/tun/netstack/examples/http_server.go) 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:

```bash
./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):

```yaml
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:

```yaml
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

```cmd
# 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:
```cmd
# 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:
```powershell
Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10
```

## Build

### Container 

Ensure Docker is installed.

```bash
make
```

### Binary

Make sure to have Go 1.23.1 installed.

```bash
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](./CONTRIBUTING.md) in the repository for guidelines and best practices.