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

deploy

Browse Source
This commit is contained in:
miloschwartz
2025-08-01 22:37:15 -07:00
parent 6d4043229a
commit 75e9d83c5a
31 changed files with 1257 additions and 286 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -0,0 +1,167 @@
---
title: "Add Client"
description: "Create a client to connect to your Pangolin network from a remote computer"
---
<Note>
This feature is only available in self-hosted Pangolin instances.
</Note>
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.
<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>
## How Clients Work
### The Connection Process
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
### What Clients Are
- 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
### What Pangolin Clients Are Not (Yet)
- A mesh VPN like Tailscale, Netbird, or Netmaker
- A slick desktop UI (coming soon)
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.
[Take a look at a quick video about clients](https://youtu.be/jg8Bb05hlnI)
## Prerequisites
Before adding a client, ensure you have:
1. **Updated Components**: Make sure you have the required versions:
- Pangolin ^1.8.0
- Gerbil ^1.1.0
- Newt ^1.4.0
2. **Site Configuration**: Your Newt site must be configured to accept clients with the `--accept-clients` flag or `ACCEPT_CLIENTS=true` environment variable.
3. **Port Configuration**: Ensure port 21820 is open on your VPS and added to your `docker-compose.yml`:
```yml title="docker-compose.yml" highlight={4}
gerbil:
ports:
- 51820:51820/udp
- 21820:21820/udp
- 443:443
- 80:80
```
## 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-olm) for detailed instructions.
</Step>
<Step title="Configure resources">
Create RAW TCP/UDP 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>
## Client Modalities
Clients have two major operation modalities:
### Relaying (Default)
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.
### NAT Hole Punching (Experimental)
<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.
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.
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 raw TCP/UDP resources in Pangolin to configure what ports clients can hit and where they should go.
For example, if you wanted to SSH into your server you could add a resource for it:
<Frame caption="Pangolin UI showing example SSH resource.">
<img src="/images/ssh_resource.png" alt="SSH Resource"/>
</Frame>
### 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
Additionally, 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 may require Linux that you have forwarding enabled:
```bash
sysctl -w net.ipv4.ip_forward=1
```
And make it persistent:
```bash
sudo nano /etc/sysctl.conf
net.ipv4.ip_forward = 1
```
## 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

233
manage/clients/configure-client.mdx Normal file
View File

@@ -0,0 +1,233 @@
---
title: "Configure Client"
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.
## How Olm Works
### Registers with Pangolin
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.
### Establishes WireGuard Tunnel
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.
### 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
<ResponseField name="id" type="string" required>
Olm ID generated by Pangolin to identify the client.
**Example**: `31frd0uzbjvp721`
</ResponseField>
<ResponseField name="secret" type="string" required>
A unique secret used to authenticate the client ID with the websocket.
**Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`
<Warning>
Keep this secret private and secure. It's used for authentication.
</Warning>
</ResponseField>
<ResponseField name="endpoint" type="string" required>
The endpoint where both Gerbil and Pangolin reside for websocket connections.
**Example**: `https://pangolin.example.com`
</ResponseField>
<ResponseField name="mtu" type="integer">
MTU for the WireGuard interface.
**Default**: `1280`
</ResponseField>
<ResponseField name="dns" type="string">
DNS server to use for resolving the endpoint.
**Default**: `8.8.8.8`
</ResponseField>
<ResponseField name="log-level" type="string">
The log level to use for Olm output.
**Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
**Default**: `INFO`
</ResponseField>
<ResponseField name="ping-interval" type="string">
Interval for pinging the server.
**Default**: `3s`
</ResponseField>
<ResponseField name="ping-timeout" type="string">
Timeout for each ping.
**Default**: `5s`
</ResponseField>
<ResponseField name="holepunch" type="boolean">
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="health-file" type="string">
Check if connection to WireGuard server (Pangolin) is ok. Creates a file if ok, removes it if not ok. Can be used with Docker healthcheck to restart Olm.
**Example**: `/tmp/olm-health`
</ResponseField>
<ResponseField name="config-file" type="string">
Path to a configuration file containing the same arguments as command line.
**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
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.
<ResponseField name="PANGOLIN_ENDPOINT" type="string">
Endpoint of your Pangolin server (equivalent to `--endpoint`)
</ResponseField>
<ResponseField name="OLM_ID" type="string">
Olm ID generated by Pangolin (equivalent to `--id`)
</ResponseField>
<ResponseField name="OLM_SECRET" type="string">
Olm secret for authentication (equivalent to `--secret`)
</ResponseField>
<ResponseField name="OLM_MTU" type="integer">
MTU for the WireGuard interface (equivalent to `--mtu`)
**Default**: `1280`
</ResponseField>
<ResponseField name="OLM_DNS" type="string">
DNS server to use for resolving the endpoint (equivalent to `--dns`)
**Default**: `8.8.8.8`
</ResponseField>
<ResponseField name="OLM_LOG_LEVEL" type="string">
Log level (equivalent to `--log-level`)
**Default**: `INFO`
</ResponseField>
<ResponseField name="OLM_PING_INTERVAL" type="string">
Interval for pinging the server (equivalent to `--ping-interval`)
**Default**: `3s`
</ResponseField>
<ResponseField name="OLM_PING_TIMEOUT" type="string">
Timeout for each ping (equivalent to `--ping-timeout`)
**Default**: `5s`
</ResponseField>
<ResponseField name="OLM_HOLEPUNCH" type="boolean">
Enable NAT hole punching mode (equivalent to `--holepunch`)
**Default**: `false`
</ResponseField>
<ResponseField name="OLM_HEALTH_FILE" type="string">
Path to health file for connection monitoring (equivalent to `--health-file`)
</ResponseField>
<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

0
manage/clients/configure-olm.mdx
View File

141
manage/clients/install-client.mdx Normal file
View File

@@ -0,0 +1,141 @@
---
title: "Install Client"
description: "Install Olm as a binary"
---
Olm can be installed as either a static binary executable or a Docker container. Configuration is passed via CLI arguments in both cases.
<Warning>
You **must first create a client and copy the Olm config** in Pangolin before running Olm.
</Warning>
## 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://docs.fossorial.io/get-olm.sh | bash
```
### 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
```
<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
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
```
### Permanent Installation
Install to your PATH (may need to run as root):
```bash
mv ./olm /usr/local/bin
```
<Note>
The quick installer will do this step for you.
</Note>
### 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
```
<Warning>
Make sure to move the binary to `/usr/local/bin/olm` before creating the service!
</Warning>
## 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
```
# 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
```
### 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. Configure the service with your credentials using Windows Service Manager or by setting system environment variables:
- `PANGOLIN_ENDPOINT=https://example.com`
- `OLM_ID=your_olm_id`
- `OLM_SECRET=your_secret`
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. See [Tailscale's guide](https://tailscale.com/kb/1130/lxc-unprivileged).
- **Linux**: May require root privileges or specific capabilities to create tun interfaces.
- **macOS**: May require additional permissions for network interface creation.

0
manage/clients/install-olm.mdx
View File