mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-02-07 21:46:42 +00:00
234 lines
6.8 KiB
Plaintext
234 lines
6.8 KiB
Plaintext
---
|
|
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
|