mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-02-08 05:56:45 +00:00
289 lines
7.7 KiB
Plaintext
289 lines
7.7 KiB
Plaintext
---
|
|
title: "Configure Clients"
|
|
description: "Configure Olm for connecting to Pangolin clients"
|
|
---
|
|
|
|
## Mac and Windows
|
|
|
|
Each respective client has a preferences window with all currently available configuration parameters like DNS override and preferred DNS servers. In your desktop client, click the menu bar or system tray icon, select More in the menu, and click Preferences.
|
|
|
|
<Frame caption="Screenshot of how to access preferences window on Mac client. The steps are the same on Windows.">
|
|
<img src="/images/mac-client-preferences.png" centered/>
|
|
</Frame>
|
|
|
|
## Pangolin CLI
|
|
|
|
Refer to the [documentation in the official repository](https://github.com/fosrl/cli/blob/main/docs/pangolin.md) for the available commands, default values, and more.
|
|
|
|
## Olm CLI
|
|
|
|
### Flags
|
|
|
|
<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="org" type="string">
|
|
Organization ID to connect to.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="user-token" type="string">
|
|
User authentication token.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="mtu" type="integer">
|
|
MTU for the internal WireGuard interface.
|
|
|
|
**Default**: `1280`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="dns" type="string">
|
|
DNS server to use to resolve the endpoint.
|
|
|
|
**Default**: `8.8.8.8`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="upstream-dns" type="string">
|
|
Upstream DNS server(s), comma-separated.
|
|
|
|
**Default**: `8.8.8.8:53`
|
|
</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="interface" type="string">
|
|
Name of the WireGuard interface.
|
|
|
|
**Default**: `olm`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="enable-api" type="boolean">
|
|
Enable API server for receiving connection requests.
|
|
|
|
**Default**: `false`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="http-addr" type="string">
|
|
HTTP server address (e.g., ':9452').
|
|
|
|
**Default**: `:9452`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="socket-path" type="string">
|
|
Unix socket path (or named pipe on Windows).
|
|
|
|
**Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
|
|
</ResponseField>
|
|
|
|
<ResponseField name="disable-holepunch" type="boolean">
|
|
Disable hole punching.
|
|
|
|
**Default**: `false`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="override-dns" type="boolean">
|
|
Override system DNS settings.
|
|
|
|
**Default**: `false`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="disable-relay" type="boolean">
|
|
Disable relay connections.
|
|
|
|
**Default**: `false`
|
|
</ResponseField>
|
|
|
|
### 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.
|
|
|
|
<Note>
|
|
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
|
|
</Note>
|
|
|
|
<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="ORG" type="string">
|
|
Organization ID to connect to (equivalent to `--org`)
|
|
</ResponseField>
|
|
|
|
<ResponseField name="USER_TOKEN" type="string">
|
|
User authentication token (equivalent to `--user-token`)
|
|
</ResponseField>
|
|
|
|
<ResponseField name="MTU" type="integer">
|
|
MTU for the internal WireGuard interface (equivalent to `--mtu`)
|
|
|
|
**Default**: `1280`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="DNS" type="string">
|
|
DNS server to use to resolve the endpoint (equivalent to `--dns`)
|
|
|
|
**Default**: `8.8.8.8`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="UPSTREAM_DNS" type="string">
|
|
Upstream DNS server(s), comma-separated (equivalent to `--upstream-dns`)
|
|
|
|
**Default**: `8.8.8.8:53`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="LOG_LEVEL" type="string">
|
|
Log level (equivalent to `--log-level`)
|
|
|
|
**Default**: `INFO`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="PING_INTERVAL" type="string">
|
|
Interval for pinging the server (equivalent to `--ping-interval`)
|
|
|
|
**Default**: `3s`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="PING_TIMEOUT" type="string">
|
|
Timeout for each ping (equivalent to `--ping-timeout`)
|
|
|
|
**Default**: `5s`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="INTERFACE" type="string">
|
|
Name of the WireGuard interface (equivalent to `--interface`)
|
|
|
|
**Default**: `olm`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="ENABLE_API" type="boolean">
|
|
Enable API server for receiving connection requests (equivalent to `--enable-api`)
|
|
|
|
Set to "true" to enable
|
|
|
|
**Default**: `false`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="HTTP_ADDR" type="string">
|
|
HTTP server address (equivalent to `--http-addr`)
|
|
|
|
**Default**: `:9452`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="SOCKET_PATH" type="string">
|
|
Unix socket path or Windows named pipe (equivalent to `--socket-path`)
|
|
|
|
**Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
|
|
</ResponseField>
|
|
|
|
<ResponseField name="DISABLE_HOLEPUNCH" type="boolean">
|
|
Disable hole punching (equivalent to `--disable-holepunch`)
|
|
|
|
Set to "true" to disable
|
|
|
|
**Default**: `false`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="OVERRIDE_DNS" type="boolean">
|
|
Override system DNS settings (equivalent to `--override-dns`)
|
|
|
|
Set to "true" to enable
|
|
|
|
**Default**: `false`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="DISABLE_RELAY" type="boolean">
|
|
Disable relay connections (equivalent to `--disable-relay`)
|
|
|
|
Set to "true" to disable
|
|
|
|
**Default**: `false`
|
|
</ResponseField>
|
|
|
|
<ResponseField name="CONFIG_FILE" type="string">
|
|
Set to the location of a JSON file to load secret values
|
|
</ResponseField>
|
|
|
|
### Loading secrets from files
|
|
|
|
You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
|
|
|
|
```
|
|
$ cat ~/.config/olm-client/config.json
|
|
{
|
|
"id": "spmzu8rbpzj1qq6",
|
|
"secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
|
|
"endpoint": "https://app.pangolin.net",
|
|
"org": "",
|
|
"userToken": "",
|
|
"mtu": 1280,
|
|
"dns": "8.8.8.8",
|
|
"upstreamDNS": ["8.8.8.8:53"],
|
|
"interface": "olm",
|
|
"logLevel": "INFO",
|
|
"enableApi": false,
|
|
"httpAddr": "",
|
|
"socketPath": "/var/run/olm.sock",
|
|
"pingInterval": "3s",
|
|
"pingTimeout": "5s",
|
|
"disableHolepunch": false,
|
|
"overrideDNS": false,
|
|
"disableRelay": false,
|
|
"tlsClientCert": ""
|
|
}
|
|
```
|
|
|
|
This file is also written to when olm first starts up. So you do not need to run every time with --id and secret if you have run it once!
|
|
|
|
Default locations:
|
|
|
|
- **macOS**: `~/Library/Application Support/olm-client/config.json`
|
|
- **Windows**: `%PROGRAMDATA%\olm\olm-client\config.json`
|
|
- **Linux/Others**: `~/.config/olm-client/config.json`
|
|
|
|
### API
|
|
|
|
Olm can be started with a HTTP or socket API to configure and manage it. See the [API documentation](https://github.com/fosrl/olm/blob/main/API.md) for more details. |