mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: add new Access Control and Logs documentation pages

Browse Source 
- Documented Access Control features (e.g., Device Approvals, Password Rotation, 2FA, Custom Login Pages).
- Added detailed descriptions for Logs & Analytics (Access Logs, Request Logs, Action Logs).
- Included configuration instructions and feature-specific notes for Pangolin Cloud and Enterprise Edition.

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
This commit is contained in:
Stefan Mogeritsch
2026-03-11 11:24:24 +01:00
parent a70f132fd9
commit aa157e82f8
87 changed files with 13163 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Configure_Clients.md
+384
View File
@@ -0,0 +1,384 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure Clients
> Configure Olm for connecting to Pangolin clients
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
## GUI Clients (Mac, Windows, Android, iOS/iPadOS)
Each respective client has a preferences window with all currently available configuration parameters. In your desktop
client, click the menu bar or system tray icon, select "More" in the menu, and click "Preferences". In the mobile apps,
navigate to the "Settings" screen.
## Preferences
The following preferences control how your client handles DNS resolution and network routing. Understanding these
settings helps you configure Pangolin to work best with your network setup.
#### Enable Aliases (Override DNS)
When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system's
default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured
Upstream DNS Server.
**When to use it**: This is required if you use aliases on resources in Pangolin. Aliases are friendly domain names
assigned to private resources. Pangolin resolves these alias addresses over a private DNS server running in your client.
**How it works**: The client loops back to itself to resolve the alias. This is why you may see your DNS server as an
unfamiliar address (often like `100.90.128.x`) when this is enabled. When a request doesn't resolve to a Pangolin
resource and is bound for another website (like `google.com`), it falls back to your configured upstream DNS server.
#### DNS Over Tunnel
When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly,
you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server.
**When to use it**: Tunnel DNS is used when you want to send all DNS queries over the tunnel to a private resource made
available in Pangolin. For example, if you host a DNS server like Pi-hole, you could define a private resource for
Pi-hole on your remote network. Then in the Pangolin client, you would enable Tunnel DNS and set the host of the Pi-hole
private resource as the tunnel DNS server.
**How it works**: When a request needs to be resolved, Pangolin sends it over the tunnel to the site of the private
resource with your DNS server. You must enable DNS Over Tunnel and also set the upstream DNS server to your private DNS
server.
This requires aliases "override DNS" to be enabled as well. This is because the client must take control of your DNS
settings to route queries through the tunnel to your private DNS server.
<Warning>
You cannot use an alias name for your DNS server. It must be the IP address of the resource. This is because it's pointing to the DNS server, so the DNS server can't resolve itself.
</Warning>
#### Primary Upstream DNS
This is the DNS server that will be used if Override DNS is enabled or DNS Over Tunnel is enabled. It serves as the
primary resolver for queries that cannot be resolved as Pangolin resources. Not used when override DNS (aliases) are
disabled.
#### Secondary Upstream DNS
This is a fallback DNS server that the system can use if the primary server is unavailable. Ordering and priority of the
server is not guaranteed, but it provides redundancy for DNS resolution. Not used when override DNS (aliases) are
disabled.
## Android Battery Optimization
To ensure Pangolin functions correctly in the background on Android devices, it's recommended to disable battery
optimization for the app. This prevents the operating system from restricting its background activities, which could
lead to disconnections.
1. Open the **Settings** app on your Android device.
2. Navigate to **Apps & notifications** (or simply **Apps** on some devices).
3. Find and select the Pangolin app from the list of installed apps.
4. Tap on **App battery usage**.
5. Select **Allow background usage** and enable if disabled.
6. From the options menu, choose **Unrestricted**.
<Frame caption="Android Battery Optimization Settings">
<img src="https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/android_battery.png?fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=100cadbbfa77478600a84cc858f222a0" alt="Android Battery Optimization Settings" style={{width: "250px", height: "auto"}} data-og-width="1080" width="1080" data-og-height="2424" height="2424" data-path="images/android_battery.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/android_battery.png?w=280&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=e508a9ce3dd5f33b56fccd3daa1927c9 280w, https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/android_battery.png?w=560&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=42d7da0325db3a16fb334e311355e2b0 560w, https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/android_battery.png?w=840&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=a409651e6935534ce7b1267b198b3abf 840w, https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/android_battery.png?w=1100&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=f241e91ed52905083869abae4ab77567 1100w, https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/android_battery.png?w=1650&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=491a492588b05d07b602654d8f4213dc 1650w, https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/android_battery.png?w=2500&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=ffada63d1b3ecc8176f18173623d7913 2500w" />
</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 (Advanced)
<Accordion title="Olm CLI (advanced use only)">
<Tip>
We recommend using the Pangolin CLI for both user and machine clients if you're looking for a CLI interface. Olm is the underlying client for the Pangolin CLI.
</Tip>
Olm is a command-line client for connecting machine clients in Pangolin. You can configure it using command-line flags,
environment variables, or a configuration file. Expand the section below to view all available configuration options.
<Accordion title="CLI Arguments and Options">
### 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">
When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system's default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured Upstream DNS Server. (default true)
**Default**: `false`
</ResponseField>
<ResponseField name="tunnel-dns" type="boolean">
When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server.
**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.
</Accordion>
</Accordion>