pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-03-03 17:26:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

many updates for 1.13

Browse Source
This commit is contained in:
miloschwartz
2025-12-10 15:20:41 -05:00
parent 5c2de2a7ab
commit c31b0cecde
36 changed files with 705 additions and 912 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
manage/clients/add-client.mdx
View File

@@ -1,180 +1,70 @@
---
title: "Add Client"
title: "Understanding Clients"
description: "Create a client to connect to your Pangolin network from a remote computer"
---
A client in Pangolin is a way to create a traditional VPN tunnel from your remote computer to your Newt site on your private network. Clients allow you to tunnel your computer back into your whole network and remotely access non-HTTP resources like file shares or use it as a bastion host to manage servers.
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.
<Note>
Client support in Pangolin is still in beta - things may not perform as expected. If you encounter bugs please report them on [GitHub in an issue](https://github.com/fosrl/pangolin).
</Note>
By default a client does not have access to any hosts on the local network of the site. Admins must explicitely define resources on the site and give specific users and roles access to the resources.
## How Clients Work
Users must log in and connect from a Pangolin client for [Window, Mac, and Linux](/manage/clients/install-client). Machine (automated systems and servers) connect with an ID and secret.
### The Connection Process
## Client Types
1. **Client Creation**: You create a client in Pangolin's dashboard
2. **Olm Registration**: Olm registers with Pangolin using the client credentials
3. **Tunnel Establishment**: Olm establishes a WireGuard tunnel to your network
4. **Resource Access**: You can access resources on your private network through the tunnel
There are two types of clients: user devices and machines.
### What Clients Are
<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>
- A way to tunnel your computer back into your whole network
- Remotely access non HTTP resources like file shares
- A bastion host or "jump box" to manage servers
<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 or Olm CLI
</Card>
</CardGroup>
### What Pangolin Clients Are Not (Yet)
### User Devices
- A mesh VPN like Tailscale, Netbird, or Netmaker
- A slick desktop UI (coming soon)
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.
You can install the [Olm](https://github.com/fosrl/olm) client on your computer and run it with the ID and secret values you generate in the dashboard. When it connects, it will create a virtual network adapter on your computer just like a traditional VPN.
Examples include:
[Take a look at a quick video about clients](https://youtu.be/jg8Bb05hlnI)
- **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.
## Prerequisites
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.
Before adding a client, ensure you have:
### Machines
1. **Updated Components**: Make sure you have the required versions:
- Pangolin ^1.8.0
- Gerbil ^1.1.0
- Newt ^1.4.0
Machine clients are for servers and automated systems that are not associated with a specific user.
2. **Site Configuration**: Your Newt site must be configured to accept clients with the `--accept-clients` flag or `ACCEPT_CLIENTS=true` environment variable.
Examples include:
3. **Port Configuration**: Ensure port 21820 is open on your VPS and added to your `docker-compose.yml`:
- **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.
```yml title="docker-compose.yml" highlight={4}
gerbil:
ports:
- 51820:51820/udp
- 21820:21820/udp
- 443:443
- 80:80
```
Though you may connect a server via a user account using a CLI client, we reccomend you specifically use a machine client.
## Adding a Client
<Steps>
<Step title="Navigate to Clients">
In the Pangolin dashboard, go to the **Clients** section and click **Add Client**.
</Step>
<Step title="Configure client details">
Configure the basic information:
- **Client Name**: A descriptive name for your client
</Step>
<Step title="Generate Olm credentials">
Pangolin will generate:
- **Client ID**: Unique identifier for the Olm client
- **Secret**: Authentication secret for secure connection
- **Endpoint**: The Pangolin server endpoint
</Step>
<Step title="Install Olm">
Use the generated credentials to install and configure Olm on your remote computer. See [Install Olm](/manage/clients/install-client) for detailed instructions.
</Step>
<Step title="Configure resources">
Create [client resources](/manage/resources/client-resources) for what you would like to access through the client. For example, to SSH into a server, create a resource like `22:localhost:22`.
</Step>
<Step title="Verify connection">
Once Olm is running, the client status should show as "Online" in the dashboard. You can then connect to your network using the site's IP address.
</Step>
</Steps>
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:
Clients have two major operation modalities. A client will first attempt to hole punch before falling back to relaying.
### Relaying (Default)
### Relaying
By default, Olm will relay traffic through your Pangolin VPS - 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.
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 (Experimental)
### NAT Hole Punching
<Note>
Right now NAT hole punching is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying. We plan to work to improve the reliability over time by implementing more methods for those behind CGNAT or hard nats.
While functional, it does not always connect reliably and can fall back to relaying. We plan to work to improve the reliability over time by implementing more methods for those behind CGNAT or hard nats.
Take a look at [Tailscale docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make to improve HP performance.
</Note>
This mode can be activated by using `--holepunch` in Olm. Instead of immediately relaying through the VPS, this will attempt to connect directly to the Newt site across NAT routers.
Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make to improve hole punch reliability and performance.
This should help to:
- Increase performance (speed/bandwidth)
- Reduce VPS transit costs
## Site Modalities
Sites have two operating modalities when accepting clients:
### Proxy Mode
When you run Newt with `--accept-clients` it will run fully in user space. This means you do not need to give the container or binary any special permissions. It will NOT create a virtual network interface on the host. Instead you should create [client resources](/manage/resources/client-resources) in Pangolin to configure what ports clients can hit and where they should go.
### Native Mode
<Note>
Right now native mode only works on Linux.
</Note>
In native mode with both `--accept-clients` and `--native`, Newt will create a native Linux tunnel interface on the host. This means that all traffic destined for the site can access anything on the host.
#### Remote Subnets
In native mode, you can add remote subnets to the site settings in Pangolin to forward remote networks through Newt. This can let Newt act as a traditional VPN server to route to anything on your local network.
<Frame caption="Pangolin UI showing remote subnets for clients.">
<img src="/images/remote_subnets.png" alt="Remote Subnets"/>
</Frame>
This will configure a route on the Olm side of the tunnel to route this subnet down the tunnel. When it reaches the other end, can be routed to the appropriate destination by the host.
This requires proper Linux routing configuration. Here's what happens in native mode:
1. **Olm forwards packets**: Your computer running Olm blindly forwards all packets destined for the remote subnet (e.g., 192.168.0.x) over the tunnel
2. **Newt receives packets**: Newt creates a WireGuard network interface on the Linux host and receives these packets
3. **Linux must route packets**: The Linux machine needs to know what to do with packets destined for 192.168.0.x
#### Required Configuration
**Enable IP forwarding:**
```bash
sudo nano /etc/sysctl.conf
net.ipv4.ip_forward = 1
```
**Setup NAT masquerading:**
```bash
sudo iptables -t nat -A POSTROUTING -j MASQUERADE
```
This rewrites the source address of packets from the tunnel to be the 192.168.0.x address of the Linux instance when packets leave the instance. This way, when devices on 192.168.0.x reply to the Olm client, they know to send the response back through the tunnel.
#### Troubleshooting Routing Issues
If you can connect to Newt (peer shows as connected in logs) but can't reach remote subnet resources:
1. **Check if packets reach the destination**: The connection to Newt is working, so this is likely a routing issue
2. **Verify forwarding is enabled**: Use `sysctl net.ipv4.ip_forward` to confirm it's set to 1
3. **Check iptables rules**: Ensure NAT masquerading is configured
4. **Consider using proxy mode**: [Client resources](/manage/resources/client-resources) can be easier as Newt handles the proxying, though you'll need to address everything as the Newt IP and assign specific ports
<Note>
NAT masquerading can affect other services on the Linux instance, so be aware of potential conflicts with existing network configurations.
</Note>
## Notes
- Clients require Olm to be running on the remote computer
- Each client can access multiple resources on the site
- Connection status is monitored automatically
- Olm creates a native tun interface and usually requires sudo/admin permissions
- On Windows: Olm will run as a service
- LXC containers need to be configured to allow tun access

107
manage/clients/configure-client.mdx
View File

@@ -1,25 +1,23 @@
---
title: "Configure Client"
title: "Configure Clients"
description: "Configure Olm for connecting to Pangolin clients"
---
Olm is a WireGuard client designed to securely connect your remote computer to your Pangolin network. By using Olm, you can create a traditional VPN tunnel that allows you to access resources on your private network from anywhere.
## Mac and Windows
## How Olm Works
Each respective client has a preferences window with all currently available configuration parameters like DNS override and preferred DNS servers. In your desktop client, click the menu bar or system tray icon, select More in the menu, and click Preferences.
### Registers with Pangolin
<Frame caption="Screenshot of how to access preferences window on Mac client. The steps are the same on Windows.">
<img src="/images/mac-client-preferences.png" centered/>
</Frame>
Using the Olm ID and a secret, the client will make HTTP requests to Pangolin to receive a session token. Using that token, it will connect to a websocket and maintain that connection. Control messages will be sent over the websocket.
## Pangolin CLI
### Establishes WireGuard Tunnel
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.
When Olm receives WireGuard control messages, it will use the information encoded (endpoint, public key) to bring up a WireGuard tunnel using native system interfaces. It will ping over the tunnel to ensure the peer on the Gerbil side is brought up.
## Olm CLI
### Creates Virtual Network Interface
Olm creates a virtual network adapter on your computer just like a traditional VPN. This allows you to access resources on your private network as if you were physically connected to it.
## Configuration Arguments
### Flags
<ResponseField name="id" type="string" required>
Olm ID generated by Pangolin to identify the client.
@@ -79,10 +77,6 @@ Olm creates a virtual network adapter on your computer just like a traditional V
Enable NAT hole punching mode instead of relaying through the VPS.
**Default**: `false`
<Note>
This is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying.
</Note>
</ResponseField>
<ResponseField name="config-file" type="string">
@@ -91,52 +85,14 @@ Olm creates a virtual network adapter on your computer just like a traditional V
**Example**: `/etc/olm/config.yaml`
</ResponseField>
## Configuration Examples
### Basic Configuration
```bash
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
```
### With Hole Punching
```bash
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--holepunch
```
### With Custom MTU and DNS
```bash
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--mtu 1400 \
--dns 1.1.1.1
```
### With Health Check
```bash
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--health-file /tmp/olm-health
```
## Environment Variables
### 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>
@@ -192,36 +148,3 @@ All CLI arguments can be set using environment variables as an alternative to co
<ResponseField name="OLM_CONFIG_FILE" type="string">
Load the config from this file instead of command line arguments (equivalent to `--config-file`)
</ResponseField>
<Note>
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
</Note>
## Troubleshooting
### Connection Issues
1. **Check credentials**: Ensure the ID and secret are correct
2. **Verify endpoint**: Make sure the endpoint URL is accessible
3. **Check firewall**: Ensure port 21820 is open on your VPS
4. **Verify site configuration**: Make sure your Newt site has `--accept-clients` enabled
### Permission Issues
1. **Linux/macOS**: Run with sudo or ensure proper capabilities
2. **Windows**: Run as administrator or install as a service
3. **LXC containers**: Configure tun device access
### Performance Issues
1. **Try hole punching**: Use `--holepunch` for better performance
2. **Adjust MTU**: Try different MTU values if experiencing packet loss
3. **Check network**: Ensure stable internet connection
## Security Considerations
- Keep your client secret secure and private
- Use HTTPS endpoints only
- Regularly rotate client credentials
- Monitor client connections in the dashboard
- Use firewall rules to restrict access to specific resources

52
manage/clients/credentials.mdx Normal file
View File

@@ -0,0 +1,52 @@
---
title: "Client Credentials"
description: "Understanding how client credentials work and how they can be rotated & regenerated"
---
## 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 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.

68
manage/clients/install-client.mdx
View File

@@ -1,25 +1,65 @@
---
title: "Install Client"
description: "Install Olm as a binary"
title: "Install Clients"
description: "Install native clients for Mac, Windows, and Linux"
---
Olm can be installed as either a static binary executable or a Docker container. Configuration is passed via CLI arguments in both cases.
## Windows
<Warning>
You **must first create a client and copy the Olm config** in Pangolin before running Olm.
</Warning>
- [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.
## Binary Installation
## 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.
## 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
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
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>
## Olm CLI
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
#### 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://pangolin.net/get-olm.sh | bash
curl -fsSL https://static.pangolin.net/get-olm.sh | bash
```
### Manual Download
#### 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.
@@ -78,11 +118,11 @@ WantedBy=multi-user.target
Make sure to move the binary to `/usr/local/bin/olm` before creating the service!
</Warning>
## Windows Service
### 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. You can also run the following:
### Service Management Commands
#### Service Management Commands
```
# Install the service
@@ -109,7 +149,7 @@ olm.exe help
Note running the service requires credentials in `%PROGRAMDATA%\olm\olm-client\config.json`.
### Service Configuration
#### 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:
@@ -117,7 +157,7 @@ When running as a service, Olm will read configuration from environment variable
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
#### Service Logs
When running as a service, logs are written to:
@@ -130,7 +170,7 @@ You can view the Windows Event Log using Event Viewer or PowerShell:
Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10
```
## Gotchas
### Gotchas
Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes:

73
manage/clients/update-client.mdx Normal file
View File

@@ -0,0 +1,73 @@
---
title: "Update Clients"
description: "Update your installed client to the latest version"
---
## 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
pangolin update
```
Or you can re-run the installation script:
```bash
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
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>
## Olm CLI
Find the latest version in the [GitHub releases](https://github.com/fosrl/olm/releases).
### Automatic Updates (Recommended)
If you used the auto installer, simply run it again:
```bash
curl -fsSL https://static.pangolin.net/get-olm.sh | bash
```
### Manual Updates
Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/olm/releases) and replace your existing binary.
```bash
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>