From 92c10ae9fa33d60b69e7415c773efc5c6f18a61c Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 23 Mar 2026 11:28:17 +0000 Subject: [PATCH 01/10] docs: add machine client guides Split from #76 (https://github.com/fosrl/docs-v2/pull/76). --- docs.json | 2 + manage/clients/install-client.mdx | 282 +--------------------- manage/clients/install-machine-client.mdx | 100 ++++++++ manage/clients/manage-machine-clients.mdx | 58 +++++ manage/clients/understanding-clients.mdx | 6 +- 5 files changed, 168 insertions(+), 280 deletions(-) create mode 100644 manage/clients/install-machine-client.mdx create mode 100644 manage/clients/manage-machine-clients.mdx diff --git a/docs.json b/docs.json index 6fe199b..8d1d593 100644 --- a/docs.json +++ b/docs.json @@ -75,6 +75,8 @@ "pages": [ "manage/clients/understanding-clients", "manage/clients/install-client", + "manage/clients/manage-machine-clients", + "manage/clients/install-machine-client", "manage/clients/configure-client", "manage/clients/update-client", "manage/clients/credentials", diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index d589e18..fb76785 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -7,6 +7,8 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; +For machine and server connectivity, see [Machine Clients](/manage/clients/manage-machine-clients). + ## Windows @@ -119,8 +121,6 @@ Pangolin CLI is the recommended way to run a client using a command line interfa Pangolin CLI can run on Windows, but the CLI VPN functionality is not supported. You can still use Pangolin CLI on Windows for SSH alongside the Windows GUI client. -Pangolin CLI supports running as user device with authentication or a machine client. - ### Quick Install (Recommended) — Linux and macOS @@ -167,284 +167,10 @@ Replace `{version}` with the desired version and `{architecture}` with your arch 3. **Start Pangolin** - When logged in as a Pangolin user, connect by running: + Connect Pangolin by running: ```bash pangolin up ``` - To launch a machine client without logging in, use your client credentials: - - ```bash - pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach - ``` - - - The `--attach` flag runs the client in the foreground instead of spawning it as a background process. - - -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" -[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 -``` - - -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. - - -### 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 -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 -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) - - - -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 -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 -wget -O olm "https://github.com/fosrl/olm/releases/download/{version}/olm_{architecture}" && chmod +x ./olm -``` - - -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. - - -### Running Olm - -Run Olm with the configuration from Pangolin: - -```bash -olm \ ---id 31frd0uzbjvp721 \ ---secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ ---endpoint https://example.com -``` - -### Systemd Service - -Create a basic systemd service: - -```ini title="/etc/systemd/system/olm.service" -[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 -``` - - -Make sure to move the binary to `/usr/local/bin/olm` before creating the service! - - -### 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 -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 -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 -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. - +For machine-only installation guidance, use [Install Machine Client](/manage/clients/install-machine-client). diff --git a/manage/clients/install-machine-client.mdx b/manage/clients/install-machine-client.mdx new file mode 100644 index 0000000..2af7ae5 --- /dev/null +++ b/manage/clients/install-machine-client.mdx @@ -0,0 +1,100 @@ +--- +title: "Install Machine Client" +icon: "download" +description: "Install and run machine clients for servers and automated systems." +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + +Use this page to install and run machine clients for servers, workloads, and automation. + +Before you begin, create a machine client in Pangolin and copy its: + +- `endpoint` +- `id` +- `secret` + +## Install Pangolin CLI + +### Quick Install + +Install the latest Pangolin CLI: + +```bash +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. + +```bash +wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin +``` + + +Replace `{version}` with the release version and `{architecture}` with your platform architecture. + + +## Start a Machine Client + +Run the machine client with its generated credentials: + +```bash +pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach +``` + +`--attach` keeps the process in the foreground, which is useful for validation and debugging. + +## Run as a Service + +For long-running workloads, run the machine client under a supervisor such as `systemd`. + +```ini title="/etc/systemd/system/pangolin-cli.service" +[Unit] +Description=Pangolin machine client +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 +``` + +## Run in Docker + +You can also run a machine client in Docker: + +```yaml +services: + pangolin-cli: + image: fosrl/pangolin-cli:latest + 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=your-client-id + - CLIENT_SECRET=your-client-secret +``` + +## Common Gotchas + +- The client needs permission to create a TUN interface. +- Containers need `NET_ADMIN` and `/dev/net/tun`. +- Host networking is usually required for containerized deployments. +- If connectivity fails, verify the `endpoint`, `id`, and `secret` first. + +## Related Documentation + +- [Machine Clients](/manage/clients/manage-machine-clients) +- [Install Clients](/manage/clients/install-client) +- [Pangolin CLI Reference](https://github.com/fosrl/cli/blob/main/docs/pangolin.md) diff --git a/manage/clients/manage-machine-clients.mdx b/manage/clients/manage-machine-clients.mdx new file mode 100644 index 0000000..cc59374 --- /dev/null +++ b/manage/clients/manage-machine-clients.mdx @@ -0,0 +1,58 @@ +--- +title: "Machine Clients" +icon: "server" +description: "Create and manage non-human clients for servers, workloads, and automation." +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + +Machine clients are non-human identities used by servers, workloads, and automation to access private resources. + +They do not sign in with username and password. Instead, Pangolin generates a client `id` and `secret` for them. + +## When to Use Machine Clients + +Use machine clients when a workload needs private resource access without an interactive login flow. + +Common examples: + +- CI/CD jobs +- backend services +- scheduled automation +- servers that need private network access + +## How They Work + +1. Create a machine client in Pangolin. +2. Copy the generated `endpoint`, `id`, and `secret`. +3. Install Pangolin CLI on the target system. +4. Start the machine client with those credentials. + +## Create a Machine Client + +When you create a machine client in the dashboard, Pangolin asks for a name and then generates the credentials you need to run it: + +- `endpoint` +- `id` +- `secret` + +Copy the secret immediately and store it securely. After creation, use those values with the install and run steps on [Install Machine Client](/manage/clients/install-machine-client). + + +Treat the machine client secret like any other privileged credential. Store it in a secret manager and rotate it if it is exposed. + + +## Operational Guidance + +- Use one machine client per workload or environment. +- Avoid sharing a single machine credential across unrelated systems. +- Remove unused clients during access reviews. +- Prefer narrow private-resource access instead of broad network access. + +## Related Documentation + +- [Install Machine Client](/manage/clients/install-machine-client) +- [Install Clients](/manage/clients/install-client) +- [Understanding Clients](/manage/clients/understanding-clients) diff --git a/manage/clients/understanding-clients.mdx b/manage/clients/understanding-clients.mdx index 031f022..1b3a9e8 100644 --- a/manage/clients/understanding-clients.mdx +++ b/manage/clients/understanding-clients.mdx @@ -15,18 +15,20 @@ By default a client does not have access to any hosts on the local network of th 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. +Use [Install Clients](/manage/clients/install-client) for people logging in with accounts, and [Machine Clients](/manage/clients/manage-machine-clients) for automated systems and servers. + ## Client Types There are two types of clients: user devices and machines. - + - Associated with a user in your Pangolin organization - Requires login to connect (password, 2fa, etc) - Available for download on Mac, Windows, and Linux - + - Represent a server or automated system instead of a user - Connect with an ID and secret - Available in CLI form with Pangolin CLI From e344b32119fd0a48ab7732ef8285c3b0c9e23205 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 23 Mar 2026 11:30:07 +0000 Subject: [PATCH 02/10] docs: reduce machine client scope --- docs.json | 2 - manage/clients/install-client.mdx | 4 - manage/clients/install-machine-client.mdx | 100 ---------------------- manage/clients/manage-machine-clients.mdx | 58 ------------- manage/clients/understanding-clients.mdx | 4 +- 5 files changed, 2 insertions(+), 166 deletions(-) delete mode 100644 manage/clients/install-machine-client.mdx delete mode 100644 manage/clients/manage-machine-clients.mdx diff --git a/docs.json b/docs.json index 8d1d593..6fe199b 100644 --- a/docs.json +++ b/docs.json @@ -75,8 +75,6 @@ "pages": [ "manage/clients/understanding-clients", "manage/clients/install-client", - "manage/clients/manage-machine-clients", - "manage/clients/install-machine-client", "manage/clients/configure-client", "manage/clients/update-client", "manage/clients/credentials", diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index fb76785..50d748e 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -7,8 +7,6 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; -For machine and server connectivity, see [Machine Clients](/manage/clients/manage-machine-clients). - ## Windows @@ -172,5 +170,3 @@ Replace `{version}` with the desired version and `{architecture}` with your arch ```bash pangolin up ``` - -For machine-only installation guidance, use [Install Machine Client](/manage/clients/install-machine-client). diff --git a/manage/clients/install-machine-client.mdx b/manage/clients/install-machine-client.mdx deleted file mode 100644 index 2af7ae5..0000000 --- a/manage/clients/install-machine-client.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "Install Machine Client" -icon: "download" -description: "Install and run machine clients for servers and automated systems." ---- - -import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; - - - -Use this page to install and run machine clients for servers, workloads, and automation. - -Before you begin, create a machine client in Pangolin and copy its: - -- `endpoint` -- `id` -- `secret` - -## Install Pangolin CLI - -### Quick Install - -Install the latest Pangolin CLI: - -```bash -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. - -```bash -wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin -``` - - -Replace `{version}` with the release version and `{architecture}` with your platform architecture. - - -## Start a Machine Client - -Run the machine client with its generated credentials: - -```bash -pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach -``` - -`--attach` keeps the process in the foreground, which is useful for validation and debugging. - -## Run as a Service - -For long-running workloads, run the machine client under a supervisor such as `systemd`. - -```ini title="/etc/systemd/system/pangolin-cli.service" -[Unit] -Description=Pangolin machine client -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 -``` - -## Run in Docker - -You can also run a machine client in Docker: - -```yaml -services: - pangolin-cli: - image: fosrl/pangolin-cli:latest - 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=your-client-id - - CLIENT_SECRET=your-client-secret -``` - -## Common Gotchas - -- The client needs permission to create a TUN interface. -- Containers need `NET_ADMIN` and `/dev/net/tun`. -- Host networking is usually required for containerized deployments. -- If connectivity fails, verify the `endpoint`, `id`, and `secret` first. - -## Related Documentation - -- [Machine Clients](/manage/clients/manage-machine-clients) -- [Install Clients](/manage/clients/install-client) -- [Pangolin CLI Reference](https://github.com/fosrl/cli/blob/main/docs/pangolin.md) diff --git a/manage/clients/manage-machine-clients.mdx b/manage/clients/manage-machine-clients.mdx deleted file mode 100644 index cc59374..0000000 --- a/manage/clients/manage-machine-clients.mdx +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: "Machine Clients" -icon: "server" -description: "Create and manage non-human clients for servers, workloads, and automation." ---- - -import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; - - - -Machine clients are non-human identities used by servers, workloads, and automation to access private resources. - -They do not sign in with username and password. Instead, Pangolin generates a client `id` and `secret` for them. - -## When to Use Machine Clients - -Use machine clients when a workload needs private resource access without an interactive login flow. - -Common examples: - -- CI/CD jobs -- backend services -- scheduled automation -- servers that need private network access - -## How They Work - -1. Create a machine client in Pangolin. -2. Copy the generated `endpoint`, `id`, and `secret`. -3. Install Pangolin CLI on the target system. -4. Start the machine client with those credentials. - -## Create a Machine Client - -When you create a machine client in the dashboard, Pangolin asks for a name and then generates the credentials you need to run it: - -- `endpoint` -- `id` -- `secret` - -Copy the secret immediately and store it securely. After creation, use those values with the install and run steps on [Install Machine Client](/manage/clients/install-machine-client). - - -Treat the machine client secret like any other privileged credential. Store it in a secret manager and rotate it if it is exposed. - - -## Operational Guidance - -- Use one machine client per workload or environment. -- Avoid sharing a single machine credential across unrelated systems. -- Remove unused clients during access reviews. -- Prefer narrow private-resource access instead of broad network access. - -## Related Documentation - -- [Install Machine Client](/manage/clients/install-machine-client) -- [Install Clients](/manage/clients/install-client) -- [Understanding Clients](/manage/clients/understanding-clients) diff --git a/manage/clients/understanding-clients.mdx b/manage/clients/understanding-clients.mdx index 1b3a9e8..4f4d394 100644 --- a/manage/clients/understanding-clients.mdx +++ b/manage/clients/understanding-clients.mdx @@ -15,7 +15,7 @@ By default a client does not have access to any hosts on the local network of th 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. -Use [Install Clients](/manage/clients/install-client) for people logging in with accounts, and [Machine Clients](/manage/clients/manage-machine-clients) for automated systems and servers. +Use [Install Clients](/manage/clients/install-client) for people logging in with accounts. Automated systems and servers connect with a client ID and secret instead. ## Client Types @@ -28,7 +28,7 @@ There are two types of clients: user devices and machines. - Available for download on Mac, Windows, and Linux - + - Represent a server or automated system instead of a user - Connect with an ID and secret - Available in CLI form with Pangolin CLI From f3edc2c75ebed5486133d9ebaa650b85e3f305b8 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 23 Mar 2026 11:34:55 +0000 Subject: [PATCH 03/10] docs: restore olm guidance on install clients --- manage/clients/install-client.mdx | 192 ++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 50d748e..9f31bb3 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -170,3 +170,195 @@ Replace `{version}` with the desired version and `{architecture}` with your arch ```bash pangolin up ``` + +## Olm (Advanced) + + + +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 +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 the 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 +wget -O olm "https://github.com/fosrl/olm/releases/download/{version}/olm_{architecture}" && chmod +x ./olm +``` + + +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. + + +### Running Olm + +Run Olm with the configuration from Pangolin: + +```bash +olm \ +--id 31frd0uzbjvp721 \ +--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ +--endpoint https://example.com +``` + +### Systemd Service + +Create a basic systemd service: + +```ini title="/etc/systemd/system/olm.service" +[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 +``` + + +Make sure to move the binary to `/usr/local/bin/olm` before creating the service. + + +### Docker + +You can also run Olm with Docker Compose: + +```yaml +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 +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 + +```text +# 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 or 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 +Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10 +``` + +### Gotchas + +Olm creates a native TUN interface. This usually requires sudo or admin permissions. + +- **Windows**: Olm runs as a service. +- **LXC containers**: Need to be configured to allow TUN access. +- **Linux**: May require root privileges or specific capabilities to create network 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, Olm can run within the LXC. + + From 717b4d33bc6d6900f8108f77b8442a95878a0db1 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 23 Mar 2026 11:38:54 +0000 Subject: [PATCH 04/10] docs: split client install paths by usage --- manage/clients/install-client.mdx | 81 +++++++++++++++++++++++- manage/clients/understanding-clients.mdx | 4 +- 2 files changed, 82 insertions(+), 3 deletions(-) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 9f31bb3..23f3147 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -7,6 +7,14 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; +Clients are used in two different ways: + +- **User Devices**: A person signs in with a Pangolin account or identity provider and connects from a desktop or mobile client. +- **Automation and Machines**: A server, workload, or script connects with a client ID and secret instead of an interactive login. + + + +## User Devices ## Windows @@ -113,7 +121,7 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; 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, macOS, Windows) +## Pangolin CLI for User Devices (Linux, macOS, Windows) Pangolin CLI is the recommended way to run a client using a command line interface on Mac and Linux. @@ -171,6 +179,77 @@ Replace `{version}` with the desired version and `{architecture}` with your arch pangolin up ``` + + +## Automation and Machines + +Use this path when the client is a server, CI job, background service, or other non-human workload. + +These clients do not log in with a Pangolin account. They connect with: + +- `endpoint` +- `id` +- `secret` + +You can run automation and machine clients with either Pangolin CLI or Olm. + +### Pangolin CLI for Automation and Machines + +Install Pangolin CLI: + +```bash +curl -fsSL https://static.pangolin.net/get-cli.sh | bash +``` + +Start the machine client with its generated credentials: + +```bash +pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach +``` + +`--attach` keeps the process in the foreground, which is useful for validation and debugging. + +#### Run as a Service + +```ini title="/etc/systemd/system/pangolin-cli.service" +[Unit] +Description=Pangolin machine client +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 +``` + +#### Run in Docker + +```yaml +services: + pangolin-cli: + image: fosrl/pangolin-cli:latest + 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=your-client-id + - CLIENT_SECRET=your-client-secret +``` + +#### Common Gotchas + +- The client needs permission to create a TUN interface. +- Containers need `NET_ADMIN` and `/dev/net/tun`. +- Host networking is usually required for containerized deployments. +- If connectivity fails, verify the `endpoint`, `id`, and `secret` first. + ## Olm (Advanced) diff --git a/manage/clients/understanding-clients.mdx b/manage/clients/understanding-clients.mdx index 4f4d394..7900135 100644 --- a/manage/clients/understanding-clients.mdx +++ b/manage/clients/understanding-clients.mdx @@ -22,13 +22,13 @@ Use [Install Clients](/manage/clients/install-client) for people logging in with There are two types of clients: user devices and machines. - + - Associated with a user in your Pangolin organization - Requires login to connect (password, 2fa, etc) - Available for download on Mac, Windows, and Linux - + - Represent a server or automated system instead of a user - Connect with an ID and secret - Available in CLI form with Pangolin CLI From c7f3230766cfb2edefa4d0576796e8b354a6c2a4 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 23 Mar 2026 11:43:38 +0000 Subject: [PATCH 05/10] docs: refine client install navigation and structure --- manage/clients/install-client.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 23f3147..0eef44a 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -12,8 +12,6 @@ Clients are used in two different ways: - **User Devices**: A person signs in with a Pangolin account or identity provider and connects from a desktop or mobile client. - **Automation and Machines**: A server, workload, or script connects with a client ID and secret instead of an interactive login. - - ## User Devices @@ -179,8 +177,6 @@ Replace `{version}` with the desired version and `{architecture}` with your arch pangolin up ``` - - ## Automation and Machines Use this path when the client is a server, CI job, background service, or other non-human workload. @@ -225,6 +221,10 @@ User=root WantedBy=multi-user.target ``` + +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. + + #### Run in Docker ```yaml From 161cec50070bd0b0e02271b52bd7f8625ac05323 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 23 Mar 2026 11:44:36 +0000 Subject: [PATCH 06/10] docs: restore docker command example --- manage/clients/install-client.mdx | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 0eef44a..3680685 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -243,6 +243,30 @@ services: - CLIENT_SECRET=your-client-secret ``` +You can also pass the CLI args directly to the container: + +```yaml +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 + - "your-client-id" + - --secret + - "your-client-secret" + - --endpoint + - https://app.pangolin.net + - --attach +``` + #### Common Gotchas - The client needs permission to create a TUN interface. From e03a7b7ea4797764d8c2686737b02f475237fcd9 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 23 Mar 2026 11:45:15 +0000 Subject: [PATCH 07/10] docs: restore docker configuration notes --- manage/clients/install-client.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 3680685..27bf9b7 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -267,6 +267,12 @@ services: - --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 + #### Common Gotchas - The client needs permission to create a TUN interface. From 7cdec21e48b39a77211acad9eec819d82cf2cdc7 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 23 Mar 2026 11:45:55 +0000 Subject: [PATCH 08/10] docs: merge docker notes and gotchas --- manage/clients/install-client.mdx | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 27bf9b7..f5be367 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -267,17 +267,11 @@ services: - --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 - -#### Common Gotchas +#### Docker Notes -- The client needs permission to create a TUN interface. -- Containers need `NET_ADMIN` and `/dev/net/tun`. -- Host networking is usually required for containerized deployments. +- `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. - If connectivity fails, verify the `endpoint`, `id`, and `secret` first. ## Olm (Advanced) From 5cda8115d238b096856802fd796dfe911fc074f5 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 23 Mar 2026 11:53:17 +0000 Subject: [PATCH 09/10] docs(clients): preserve legacy install anchors --- manage/clients/install-client.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index f5be367..ecc8a69 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -119,7 +119,9 @@ Clients are used in two different ways: Tap the Connect button to establish a VPN connection. On the first connection, you may be prompted to allow the VPN connection. -## Pangolin CLI for User Devices (Linux, macOS, Windows) + + +## Pangolin CLI (Linux, macOS, Windows) Pangolin CLI is the recommended way to run a client using a command line interface on Mac and Linux. @@ -345,6 +347,8 @@ WantedBy=multi-user.target Make sure to move the binary to `/usr/local/bin/olm` before creating the service. + + ### Docker You can also run Olm with Docker Compose: From dd724d58dd0822a1522d3068d6ec690004c29ba3 Mon Sep 17 00:00:00 2001 From: Laurence Date: Mon, 23 Mar 2026 11:56:20 +0000 Subject: [PATCH 10/10] docs(clients): remove redundant install guidance --- manage/clients/understanding-clients.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/manage/clients/understanding-clients.mdx b/manage/clients/understanding-clients.mdx index 7900135..db43692 100644 --- a/manage/clients/understanding-clients.mdx +++ b/manage/clients/understanding-clients.mdx @@ -13,10 +13,6 @@ A client is a way to access resources on sites remotely and privately via a virt 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. - -Use [Install Clients](/manage/clients/install-client) for people logging in with accounts. Automated systems and servers connect with a client ID and secret instead. - ## Client Types There are two types of clients: user devices and machines.