meldestelle/docs/01_Architecture/Pangolin/Mange_Pangolin/Clients/Install_Clients.md

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

Fastest way to get started with Pangolin using the hosted control plane. No credit card required.

Windows

• Pangolin for Windows Installer - This is the official page to download the latest installer file for Windows.
• All Versions - 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 - This is the official page to download the latest installer file for macOS.
• All Versions - 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 - 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 - This is the official page to download the latest Pangolin app for Android devices.
• All Versions - 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:

curl -fsSL https://static.pangolin.net/get-cli.sh | bash

Manual Download

Binaries for Linux and macOS are available in the GitHub releases for ARM and AMD64 (x86_64) architectures.

Download and install manually:

wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin

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.

Installation Steps

1. Download and install the Pangolin client

   Install Pangolin using the installation script:

   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:

   pangolin login
   

3. Start Pangolin

   When logged in as a Pangolin user, connect by running:

   pangolin up
   

   To launch a machine client without logging in, use your client credentials:

   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:

[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):

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:

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:

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.

Manual Download

Binaries for Linux, macOS, and Windows are available in the GitHub releases for ARM and AMD64 (x86_64) architectures.

Download and install manually:

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:

olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com

Systemd Service

Create a basic systemd 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):

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:

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:

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