---
title: "Configure Client"
description: "Configure Olm for connecting to Pangolin clients"
---

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

<ResponseField name="id" type="string" required>
  Olm ID generated by Pangolin to identify the client.
  
  **Example**: `31frd0uzbjvp721`
</ResponseField>

<ResponseField name="secret" type="string" required>
  A unique secret used to authenticate the client ID with the websocket.
  
  **Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`
  
  <Warning>
  Keep this secret private and secure. It's used for authentication.
  </Warning>
</ResponseField>

<ResponseField name="endpoint" type="string" required>
  The endpoint where both Gerbil and Pangolin reside for websocket connections.
  
  **Example**: `https://pangolin.example.com`
</ResponseField>

<ResponseField name="mtu" type="integer">
  MTU for the WireGuard interface.
  
  **Default**: `1280`
</ResponseField>

<ResponseField name="dns" type="string">
  DNS server to use for resolving the endpoint.
  
  **Default**: `8.8.8.8`
</ResponseField>

<ResponseField name="log-level" type="string">
  The log level to use for Olm output.
  
  **Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
  
  **Default**: `INFO`
</ResponseField>

<ResponseField name="ping-interval" type="string">
  Interval for pinging the server.
  
  **Default**: `3s`
</ResponseField>

<ResponseField name="ping-timeout" type="string">
  Timeout for each ping.
  
  **Default**: `5s`
</ResponseField>

<ResponseField name="holepunch" type="boolean">
  Enable NAT hole punching mode instead of relaying through the VPS.
  
  **Default**: `false`
  
  <Note>
  This is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying.
  </Note>
</ResponseField>

<ResponseField name="health-file" type="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`
</ResponseField>

<ResponseField name="config-file" type="string">
  Path to a configuration file containing the same arguments as command line.
  
  **Example**: `/etc/olm/config.yaml`
</ResponseField>

## Configuration Examples

### Basic Configuration

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

### With Hole Punching

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

### With Custom MTU and DNS

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

### With Health Check

```bash
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.

<ResponseField name="PANGOLIN_ENDPOINT" type="string">
  Endpoint of your Pangolin server (equivalent to `--endpoint`)
</ResponseField>

<ResponseField name="OLM_ID" type="string">
  Olm ID generated by Pangolin (equivalent to `--id`)
</ResponseField>

<ResponseField name="OLM_SECRET" type="string">
  Olm secret for authentication (equivalent to `--secret`)
</ResponseField>

<ResponseField name="OLM_MTU" type="integer">
  MTU for the WireGuard interface (equivalent to `--mtu`)
  
  **Default**: `1280`
</ResponseField>

<ResponseField name="OLM_DNS" type="string">
  DNS server to use for resolving the endpoint (equivalent to `--dns`)
  
  **Default**: `8.8.8.8`
</ResponseField>

<ResponseField name="OLM_LOG_LEVEL" type="string">
  Log level (equivalent to `--log-level`)
  
  **Default**: `INFO`
</ResponseField>

<ResponseField name="OLM_PING_INTERVAL" type="string">
  Interval for pinging the server (equivalent to `--ping-interval`)
  
  **Default**: `3s`
</ResponseField>

<ResponseField name="OLM_PING_TIMEOUT" type="string">
  Timeout for each ping (equivalent to `--ping-timeout`)
  
  **Default**: `5s`
</ResponseField>

<ResponseField name="OLM_HOLEPUNCH" type="boolean">
  Enable NAT hole punching mode (equivalent to `--holepunch`)
  
  **Default**: `false`
</ResponseField>

<ResponseField name="OLM_HEALTH_FILE" type="string">
  Path to health file for connection monitoring (equivalent to `--health-file`)
</ResponseField>

<ResponseField name="OLM_CONFIG_FILE" type="string">
  Load the config from this file instead of command line arguments (equivalent to `--config-file`)
</ResponseField>

<Note>
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
</Note>

## 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