deploy

2026-02-08 05:56:45 +00:00 · 2025-08-01 22:37:15 -07:00
parent 6d4043229a
commit 75e9d83c5a
31 changed files with 1257 additions and 286 deletions
--- a/manage/clients/configure-client.mdx
+++ b/manage/clients/configure-client.mdx
@@ -0,0 +1,233 @@
+---
+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