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/Archiving_&_Blocking.md
+54
View File
@@ -0,0 +1,54 @@
> ## 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.
# Archiving & Blocking
> Manage clients and block unwanted connections
<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>
## Blocking Devices
To block a device that has been compromised or lost:
1. Navigate to the device in your client list
2. Click the Action Menu (three dots)
3. Select **Block**
When you block a device, it is immediately moved to a restricted list and loses access to all resources or the ability
to connect.
## Archiving Devices
Devices cannot be permanently deleted from Pangolin. Instead, you can archive devices to remove them from your active
client list.
To archive a device:
1. Navigate to the device in your client list
2. Click the Action Menu (three dots)
3. Select **Archive**
### Why Archive Instead of Delete?
Pangolin maintains a permanent audit trail of all devices that have accessed your resources. This ensures:
* Block rules remain effective even for archived devices
* Security logs and access history are preserved
Archiving keeps your interface clean by hiding inactive or duplicate devices while maintaining the integrity of your
security records.
## Filtering
You can filter your client list to show only active, blocked, or archived devices.
<Frame>
<img src="https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/device_list_filter.png?fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=5d4570c3d0c42debd73925054c943b92" alt="Client List Filters" style={{width: "400px", height: "auto"}} data-og-width="838" width="838" data-og-height="491" height="491" data-path="images/device_list_filter.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/device_list_filter.png?w=280&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=1249dd92715a3d7e87a9b4a17ff456ac 280w, https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/device_list_filter.png?w=560&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=773b193e67a7ef3788b9d4d7389c4c2a 560w, https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/device_list_filter.png?w=840&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=0620352a2db576f218da798907f0670f 840w, https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/device_list_filter.png?w=1100&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=ae23320c92734dad9e5a177502289b14 1100w, https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/device_list_filter.png?w=1650&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=a8f62d02fe70866902933c04219ecea1 1650w, https://mintcdn.com/fossorial/VqiOoRUR8g1Tf03J/images/device_list_filter.png?w=2500&fit=max&auto=format&n=VqiOoRUR8g1Tf03J&q=85&s=be72ee2093659137e196beaf2a869b64 2500w" />
</Frame>
docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Credentials.md
+74
View File
@@ -0,0 +1,74 @@
> ## 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.
# Client Credentials
> Understanding how client credentials work and how they can be rotated & regenerated
<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>
## Understanding Credentials
Every machine client is provisioned with a unique identifier (ID), secret, and endpoint. The client uses the combination
of these three to establish a secure, encrypted connection to the server.
User devices use a special combination of credentials and temporary session tokens tied to the user account. Therefore,
these credentials are obscured and can not be regenerated for user devices. To invalidate a user device, the user should
logout via the client of choice.
### ID
Example: `ln8yqs6w85la5zg`
The ID represents the client connection in the system. Every machine client has an ID.
This value is not a secret and it is okay if made publically available.
### Secret
Example: `tfpwoc580jf1l1glfagix0o97p8kirjogdflqg604n0tr3to`
The secret represents the "password" of the client. This secret must match the secret hashed in the system for the
relevant ID.
<Note>
This is a *secret*! Only share it with trusted people and be sure to store it safely and securely.
</Note>
When the client connects, it uses this secret as a first handshake with the server. The server then passes temporary
session credentials back to the site before it can initiate a websocket connection. Once the websocket connection is
established, ephemeral keys are used to establish tunnels using WireGuard.
### Endpoint
Example: `https://app.pangolin.net` or `https://pangolin.my-server.com`
The endpoint is how the client knows which server to connect to. This is the fully qualified hostname of the Pangolin
server (the URL you use to access the dashboard). For Pangolin cloud, the endpoint is `https://app.pangolin.net`. The
client uses this endpoint ot establish a websocket connection and receive control messages from the server.
## Rotating and Regenerating Credentials
<Note>
This is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
</Note>
Client credentials can be regenerated. Regenerating credentials will completely invalidate the previous ID and secret.
Use this feature if you have lost the secret and need to reset the credentials, or if you wish to rotate credentials on
a regular basis for extra security.
To regenerate credentials, visit Clients > Machines > Your Client > Credentials in the Pangolin admin dashboard.
### Regenerate vs. Regenerate and Disconnect
Regenerate simply recreates the credentials and invalidates the old ones. The client will remain connected until you
restart it with the new credentials.
Regenerate and Disconnect recreates the credentials and invalides the old ones. The client will instantly disconnect and
will require you to restart it with the new credentials.
docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Client_Fingerprinting.md
+87
View File
@@ -0,0 +1,87 @@
> ## 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.
# Client Fingerprinting
> A summary of device information that is collected during the connection
<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>
## Device Fingerprinting
Pangolin clients collect device fingerprinting information and can perform
security posture checks to help determine trusted devices. This information is
used to enforce security policies, audit device configurations, and monitor
compliance with organizational requirements. Snapshots of device information are
collected periodically on each platform when clients are connected.
## Collected Fingerprint Information
The following device attributes are collected on each device when available:
* Username
* Hostname
* OS version
* Kernel version
* Architecture
* Device model
* Serial number
## Available Posture Checks
<Note>
Posture checks are only collected on Pangolin Cloud and self-hosted [Enterprise Edition](/self-host/enterprise-edition).
</Note>
Posture checks are also collected on each platform; this is device state that
could potentially change, such as biometric availability, firewall settings, and
other related information if it is available.
Posture checks are supported on a per-platform basis.
### Windows
| Posture Check | What It Reports |
|-----------------------|-------------------------------------------------------------------|
| Hard drive encryption | Whether the system disk and other disks are encrypted (BitLocker) |
| Firewall | If the firewall (Windows or third party) is enabled |
| Antivirus | If antivirus (Windows or third party) is installed and active |
| TPM availability | If a Trusted Platform Module is available |
### macOS
| Posture Check | What It Reports |
|-----------------------------------|------------------------------------------|
| Hard drive encryption | Whether the system disk is encrypted |
| Biometric configuration | If Touch ID or Face ID is configured |
| Firewall | If the macOS firewall is enabled |
| System Integrity Protection (SIP) | Whether SIP is active |
| Gatekeeper | Whether Gatekeeper is active |
| Firewall stealth mode | Whether firewall stealth mode is enabled |
| Auto updates | If automatic updates are enabled |
### Linux
| Posture Check | What It Reports |
|-----------------------|--------------------------------------------------|
| Hard drive encryption | If LUKS devices are detected on the system |
| Firewall | Whether UFW, firewalld, or iptables are enabled |
| AppArmor | If AppArmor is active |
| SELinux | If SELinux is active |
| TPM availability | If a Trusted Platform Module device is available |
### iOS
No posture checks are currently supported on iOS.
### Android
| Posture Check | What It Reports |
|-----------------------|-------------------------------------|
| Hard drive encryption | If File-Based Encryption is enabled |
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>
docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Install_Clients.md
+474
View File
@@ -0,0 +1,474 @@
> ## 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.
# Install Clients
> Install native clients for Mac, Windows, and Linux
<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>
## Windows
* [Pangolin for Windows Installer](https://pangolin.net/downloads/windows) - This is the official page to download the
latest installer file for Windows.
* [All Versions](https://github.com/fosrl/windows/releases) - The releases section of this repository contains release
notes and download artifacts for the latest version and all older versions.
### Installation Steps
1. **Download and install the Pangolin client**
Download and install the Pangolin client using the official .msi installer from the download button above.
2. **Launch Pangolin**
Open Pangolin from the Start menu or the shortcut on your Desktop.
3. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
* Click the Pangolin icon in the task bar's system tray and select Log in.
## Mac
* [Pangolin for macOS Installer](https://pangolin.net/downloads/mac) - This is the official page to download the latest
installer file for macOS.
* [All Versions](https://github.com/fosrl/apple/releases) - The releases section of this repository contains release
notes and download artifacts for the latest version and all older versions.
### Installation Steps
1. **Download and install the Pangolin client**
Download and install the Pangolin client using the official .dmg installer from the download button above.
* Open the downloaded .dmg file
* Drag and drop Pangolin.app into your Applications folder
2. **Launch Pangolin**
Open Pangolin from your Applications folder.
3. **Install the VPN configuration**
Follow the Pangolin onboarding flow, which will guide you to install the Pangolin VPN configuration.
* Select Open System Settings on startup when it asks to install a network extension.
* In System Settings, under General > Login Items & Extension > By Category > Network Extensions, ensure that
Pangolin.app is toggled on.
* Select Allow when Pangolin asks to add a VPN configuration.
4. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
* Click the Pangolin icon in the menu bar and select Log in.
## iOS/iPadOS
* [Pangolin on the App Store](https://apps.apple.com/us/app/pangolin-client/id6757407406) - This is the official page to
download the latest Pangolin app for iOS and iPadOS.
### Installation Steps
1. **Download and install the Pangolin app**
Download and install the Pangolin app from the App Store using the link above.
2. **Launch Pangolin**
Open the Pangolin app from your home screen.
3. **Install the VPN configuration**
When prompted, allow Pangolin to add VPN configurations to your device.
You may be asked to enter your device passcode or use Face ID/Touch ID to authorize the VPN configuration.
4. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
5. **Connect to Pangolin**
Tap the Connect button to establish a VPN connection.
## Android
* [Pangolin on Google Play](https://play.google.com/store/apps/details?id=net.pangolin.Pangolin) - This is the official
page to download the latest Pangolin app for Android devices.
* [All Versions](https://github.com/fosrl/android/releases) - The releases section of this repository contains release
notes and download artifacts for the latest version and all older versions.
### Installation Steps
1. **Download and install the Pangolin app**
Download and install the Pangolin app from the Google Play Store using the link above.
2. **Launch Pangolin**
Open the Pangolin app from your app drawer or home screen.
3. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
4. **Connect to Pangolin**
Tap the Connect button to establish a VPN connection. On the first connection, you may be prompted to allow the VPN
connection.
## Pangolin CLI (Linux)
Pangolin CLI is the recommended way to run a client using a command line interface on Mac or Linux. Support for Windows
is coming soon.
Pangolin CLI supports running as user device with authentication or a machine client.
### Quick Install (Recommended)
Use this command to automatically install Pangolin CLI. It detects your system architecture automatically and always
pulls the latest version, adding `pangolin` to your PATH:
```bash theme={null}
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
```
### Manual Download
Binaries for Linux and macOS are available in the [GitHub releases](https://github.com/fosrl/cli/releases) for ARM and
AMD64 (x86\_64) architectures.
Download and install manually:
```bash theme={null}
wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin
```
<Note>
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information.
</Note>
### Installation Steps
1. **Download and install the Pangolin client**
Install Pangolin using the installation script:
```bash theme={null}
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
```
2. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance:
```bash theme={null}
pangolin login
```
3. **Start Pangolin**
When logged in as a Pangolin user, connect by running:
```bash theme={null}
pangolin up
```
To launch a machine client without logging in, use your client credentials:
```bash theme={null}
pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
```
<Tip>
The `--attach` flag runs the client in the foreground instead of spawning it as a background process.
</Tip>
Pangolin CLI can be installed as a systemd service or run in a container. See the sections below for advanced setups.
### Systemd Service (Pangolin CLI)
Create a basic systemd service for Pangolin CLI:
```ini title="/etc/systemd/system/pangolin-cli.service" theme={null}
[Unit]
Description=Pangolin CLI
After=network.target
[Service]
ExecStart=/usr/local/bin/pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
Restart=always
User=root
[Install]
WantedBy=multi-user.target
```
<Warning>
Make sure to move the binary to `/usr/local/bin/pangolin` before creating the service. Replace `{client_id}`, `{client_secret}`, and `{endpoint_url}` with your machine client credentials and endpoint.
</Warning>
### Docker (Pangolin CLI)
You can run Pangolin CLI with Docker Compose. For example, a service in your `docker-compose.yml` might look like this
using environment variables (recommended):
```yaml theme={null}
services:
pangolin-cli:
image: fosrl/pangolin-cli:latest
container_name: pangolin-cli
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
- PANGOLIN_ENDPOINT=https://app.pangolin.net
- CLIENT_ID=5n52gnzfgl3tdox
- CLIENT_SECRET=wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9
```
You can also pass the CLI args to the container:
```yaml theme={null}
services:
pangolin-cli:
image: fosrl/pangolin-cli:latest
container_name: pangolin-cli
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
command:
- up
- --id
- "5n52gnzfgl3tdox"
- --secret
- "wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9"
- --endpoint
- https://app.pangolin.net
- --attach
```
**Docker Configuration Notes:**
* `network_mode: host` brings the Pangolin CLI network interface to the host system, allowing the WireGuard tunnel to
function properly
* `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces
* `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating
WireGuard interfaces
## Olm (Advanced)
<Accordion title="Olm CLI (advanced use only)">
Olm CLI is the most basic form of a client. All other clients implement Olm under the hood in some form.
If you're looking for a CLI interface for a client, we recommend using Pangolin CLI where possible.
Olm CLI is mainly only used for machine clients. Though the Pangolin CLI can also be used for machine clients, use
Pangolin CLI if you expect to log in as a user.
### Binary Installation (Linux)
#### Quick Install (Recommended)
Use this command to automatically install Olm. It detects your system architecture automatically and always pulls the
latest version, adding Olm to your PATH:
```bash theme={null}
curl -fsSL https://static.pangolin.net/get-olm.sh | bash
```
#### Windows
If you would like to use Olm on Windows, wintun.dll is required. Please use latest installer
from [GitHub releases](https://github.com/fosrl/olm/releases/latest).
#### Manual Download
Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/olm/releases) for
ARM and AMD64 (x86\_64) architectures.
Download and install manually:
```bash theme={null}
wget -O olm "https://github.com/fosrl/olm/releases/download/{version}/olm_{architecture}" && chmod +x ./olm
```
<Note>
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/olm/releases) for the latest information.
</Note>
### Running Olm
Run Olm with the configuration from Pangolin:
```bash theme={null}
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
```
### Systemd Service
Create a basic systemd service:
```ini title="/etc/systemd/system/olm.service" theme={null}
[Unit]
Description=Olm
After=network.target
[Service]
ExecStart=/usr/local/bin/olm --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com
Restart=always
User=root
[Install]
WantedBy=multi-user.target
```
<Warning>
Make sure to move the binary to `/usr/local/bin/olm` before creating the service!
</Warning>
### Docker
You can also run it with Docker compose. For example, a service in your `docker-compose.yml` might look like this using
environment vars (recommended):
```yaml theme={null}
services:
olm:
image: fosrl/olm
container_name: olm
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
- PANGOLIN_ENDPOINT=https://example.com
- OLM_ID=31frd0uzbjvp721
- OLM_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
```
You can also pass the CLI args to the container:
```yaml theme={null}
services:
olm:
image: fosrl/olm
container_name: olm
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
command:
- --id 31frd0uzbjvp721
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
- --endpoint https://example.com
```
**Docker Configuration Notes:**
* `network_mode: host` brings the olm network interface to the host system, allowing the WireGuard tunnel to function
properly
* `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces
* `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating
WireGuard interfaces
### Windows Service
On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to
install and run the service to function like a cli tool.
Minimum Windows version: Windows 10
#### Service Management Commands
```
# Install the service
olm.exe install
# Start the service
olm.exe start
# Stop the service
olm.exe stop
# Check service status
olm.exe status
# Remove the service
olm.exe remove
# Run in debug mode (console output) with our without id & secret
olm.exe debug
# Show help
olm.exe help
```
Note running the service requires credentials in `%PROGRAMDATA%\olm\olm-client\config.json`.
#### Service Configuration
When running as a service, Olm will read configuration from environment variables or you can modify the service to
include command-line arguments:
1. Install the service: `olm.exe install`
2. Set the credentials in `%PROGRAMDATA%\olm\olm-client\config.json`. Hint: if you run olm once with --id and --secret
this file will be populated!
3. Start the service: `olm.exe start`
#### Service Logs
When running as a service, logs are written to:
* Windows Event Log (Application log, source: "OlmWireguardService")
* Log files in: `%PROGRAMDATA%\olm\logs\olm.log`
You can view the Windows Event Log using Event Viewer or PowerShell:
```powershell theme={null}
Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10
```
### Gotchas
Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes:
* **Windows**: Olm will run as a service. You can use the commands
described [Configure Client](/manage/clients/configure-client) to manage it. You can use this to run it in the
background if needed!
* **LXC containers**: Need to be configured to allow tun access. On Proxmox see below.
* **Linux**: May require root privileges or specific capabilities to create tun interfaces.
* **macOS**: May require additional permissions for network interface creation.
#### LXC Proxmox
1. Create your LXC container.
2. Go to the Resources tab of the container.
3. Select Add. Then select Device Passthrough.
4. On the Add Device prompt, enter dev/net/tun in the Device Path field and select Add.
5. If the container is running, shut it down and start it up again.
Once /dev/net/tun is available, the olm can run within the LXC.
</Accordion>
docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Understanding_Clients.md
+98
View File
@@ -0,0 +1,98 @@
> ## 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.
# Understanding Clients
> Create a client to connect to your Pangolin network from a remote computer
<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>
A client is a way to access resources on sites remotely and privately via a virtual private network. Clients are used
with private resources to faciliate zero-trust network access.
By default a client does not have access to any hosts on the local network of the site. Admins must explicitly define
resources on the site and give specific users and roles access to the resources.
Users must log in and connect from a Pangolin client available
on [Windows, Mac, Linux, iOS/iPadOS, and Android](/manage/clients/install-client). Machines (automated systems and
servers) connect with an ID and secret.
## Client Types
There are two types of clients: user devices and machines.
<CardGroup cols={2}>
<Card title="User Devices">
* Associated with a user in your Pangolin organization
* Requires login to connect (password, 2fa, etc)
* Available for download on Mac, Windows, and Linux
</Card>
<Card title="Machines">
* Represent a server or automated system instead of a user
* Connect with an ID and secret
* Available in CLI form with Pangolin CLI
</Card>
</CardGroup>
### User Devices
A user may download a client for their specific system. Before they can connect, they must select a Pangolin server to
authenticate to using their provided Pangolin account. Users can log in as a Pangolin user or with your attached
external identity provider.
Examples include:
* **SSH**: Admins and developers can connect with their client to specific hosts for SSH.
* **RDP**: Users can connect to a remote host using familiar remote desktop software.
Then, just like in the Pangolin dashboard, a user selects the organization to connect to. Once connected, all resources
made available to the user in that organization become available via the tunnel.
### Machines
Machine clients are for servers and automated systems that are not associated with a specific user.
Examples include:
* **CICD**: Access remote resources like a database in an automated deployment pipeline.
* **Servers**: Provide a VPS with access to a resource running in a different network.
Though you may connect a server via a user account using a CLI client, we recommend you specifically use a machine
client.
Machine clients authenticate with an ID and secret string. These credentials are passed via arguments into one of the
supported Pangolin CLI clients. They can be revoked and rotated.
## Client Modalities
Clients have two major operation modalities. A client will first attempt to hole punch before falling back to relaying.
### Relaying
Clients can relay traffic through a Pangolin server - through Gerbil specifically. Gerbil listens on UDP port 21820 for
new WireGuard connections and forwards the packets down the Newt site tunnels to the right peers. This means your
connections back to your site do not require firewall config and uses the existing NAT holepunching capabilities of
Newt.
### NAT Hole Punching
NAT hole punching establishes a direct peer-to-peer connection between the client and site, bypassing the need to route
traffic through the Pangolin server. The server coordinates the initial connection by helping both peers discover each
other's network addresses, allowing them to establish a direct tunnel through their respective NATs and firewalls.
If the site and client are unable to hole punch, they fall back to relaying through your Pangolin server.
Take a look at [some things you can do to improve reliability](/manage/sites/configure-site#nat-traversal-tweaks) if you
are not getting reliable hole punching.
This should help to:
* Increase performance (speed/bandwidth)
* Reduce VPS transit costs
docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Update_Clients.md
+65
View File
@@ -0,0 +1,65 @@
> ## 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.
# Update Clients
> Update your installed client to the latest version
<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>
## Mac and Windows
### Automatic Updates (Recommended)
The desktop clients for Mac and Windows will periodically check for updates in the background. When an update is
available, they will request permission to update. However, you can manually check for updates in the menu bar or system
tray menu, or by restarting the application.
Once you accept the update, these clients will automatically download the latest version and replace itself on your
computer.
### Manual Updates
* **Mac**: Find the latest version in the [GitHub releases](https://github.com/fosrl/apple/releases).
* **Windows**: Find the latest version in the [GitHub releases](https://github.com/fosrl/windows/releases).
You can download the latest installer files and restart the installation process to install the latest version.
Visit [https://pangolin.net/downloads](https://pangolin.net/downloads) to find the latest official installers for your
platform.
## Pangolin CLI
Find the latest version in the [GitHub releases](https://github.com/fosrl/cli/releases).
### Automatic Updates (Recommended)
If you already have Pangolin CLI installed, use the update command:
```bash theme={null}
pangolin update
```
Or you can re-run the installation script:
```bash theme={null}
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
```
### Manual Updates
Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/cli/releases) and replace
your existing binary.
```bash theme={null}
wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin
```
<Note>
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information.
</Note>