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/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>