mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-02-27 23:36:47 +00:00
deploy
This commit is contained in:
miloschwartz
BIN
manage/.DS_Store
vendored
Normal file
BIN
manage/.DS_Store
vendored
Normal file
Binary file not shown.
50
manage/access-control/forwarded-headers.mdx
Normal file
50
manage/access-control/forwarded-headers.mdx
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: "Forwarded Headers"
|
||||
description: "Learn how Pangolin forwards user identity information to your backend applications through HTTP headers"
|
||||
---
|
||||
|
||||
Pangolin can forward user identity information to your backend applications through custom HTTP headers. This allows your applications to receive user details directly from the request headers, enabling integration with Pangolin's authentication system.
|
||||
|
||||
<Info>
|
||||
Forwarded headers are only available when using authentication methods that provide user identity information.
|
||||
</Info>
|
||||
|
||||
## Supported Headers
|
||||
|
||||
Pangolin forwards the following headers to your backend when user identity is available:
|
||||
|
||||
| Header | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `Remote-User` | Unique username or user ID | `user_123` |
|
||||
| `Remote-Email` | User's email address | `john.doe@example.com` |
|
||||
| `Remote-Name` | User's full name | `John Doe` |
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
### Headers Available
|
||||
|
||||
These authentication methods provide user identity information and will include the forwarded headers:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Single Sign-On (SSO)" icon="users">
|
||||
Full user identity information including username, email, and name.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Headers Not Available
|
||||
|
||||
These authentication methods do not provide user identity information:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="PIN Code" icon="hashtag">
|
||||
No user identity - only access control.
|
||||
</Card>
|
||||
|
||||
<Card title="Password" icon="lock">
|
||||
No user identity - only access control.
|
||||
</Card>
|
||||
|
||||
<Card title="Shareable Links" icon="link">
|
||||
No user identity - only access control.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -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
233
manage/clients/configure-client.mdx
Normal 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
|
||||
141
manage/clients/install-client.mdx
Normal file
141
manage/clients/install-client.mdx
Normal 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,0 +1,126 @@
|
||||
---
|
||||
title: "Domains"
|
||||
description: "Learn how to configure domains for your Pangolin resources and understand the different domain types available"
|
||||
---
|
||||
|
||||
Domains allow you to access your Pangolin resources through custom URLs. Pangolin supports different domain types depending on your deployment model and requirements.
|
||||
|
||||
## Getting Started
|
||||
|
||||
In Pangolin Cloud, a domain is not required. You can use our provided domain endings like `.hostlocal.app` or `.tunneled.to` for your resources.
|
||||
|
||||
## Domain Types
|
||||
|
||||
<Info>
|
||||
SSL certificates are automatically acquired and managed for both CNAME and NS domain types. No additional certificate configuration is required.
|
||||
</Info>
|
||||
|
||||
### Domain Delegation (NS Records)
|
||||
|
||||
Domain delegation gives Pangolin full DNS control over your domain:
|
||||
|
||||
- **Full Domain Control**: Includes the base domain and all subdomains
|
||||
- **NS Records**: Uses nameserver delegation for complete DNS management
|
||||
- **Automatic Subdomains**: All subdomains work automatically
|
||||
|
||||
<Tip>
|
||||
Domain delegation is ideal when you want Pangolin to manage your entire domain and all its subdomains.
|
||||
</Tip>
|
||||
|
||||
### Single Domain (CNAME Records)
|
||||
|
||||
Single domain is limited to the exact domain you specify:
|
||||
|
||||
- **Exact Domain Only**: Only the specific domain provided works
|
||||
- **CNAME Records**: Uses CNAME records pointing to Pangolin
|
||||
- **No Subdomains**: Subdomains will not work with CNAME domains
|
||||
- **External DNS**: Your domain remains controlled by your existing DNS provider
|
||||
|
||||
<Tip>
|
||||
CNAME domains are useful when your domain is already controlled by another provider but you still want to expose resources via Pangolin.
|
||||
</Tip>
|
||||
|
||||
## Adding Domains
|
||||
|
||||
### Pangolin Cloud
|
||||
|
||||
Domains can be added to an organization via the domains section of the organization settings:
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to Organization Settings">
|
||||
Go to your organization settings and select the "Domains" section.
|
||||
</Step>
|
||||
|
||||
<Step title="Choose Domain Type">
|
||||
Select either "Domain Delegation" or "Single Domain" based on your needs.
|
||||
</Step>
|
||||
|
||||
<Step title="Enter Domain">
|
||||
Provide your domain name (e.g., example.com).
|
||||
</Step>
|
||||
|
||||
<Step title="Configure DNS Records">
|
||||
Follow the provided instructions to add the required DNS records to your provider.
|
||||
</Step>
|
||||
|
||||
<Step title="Wait for Verification">
|
||||
DNS changes may take time to propagate. The domain will show as verified once propagation is complete.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Domain delegation and CNAME domains are only available in Pangolin Cloud. Self-hosted Pangolin uses different domain configuration methods.
|
||||
</Warning>
|
||||
|
||||
### Self-Hosted Pangolin
|
||||
|
||||
For self-hosted Pangolin, domains are configured differently, though you can still create domains in the UI.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="System-Wide Domains" icon="gear" href="/self-host/advanced/config-file#domain-configuration">
|
||||
Configure domains via the config file, including certificate resolver settings.
|
||||
</Card>
|
||||
|
||||
<Card title="Wildcard Domains" icon="asterisk" href="/self-host/advanced/wild-card-domains">
|
||||
Set up wildcard domains for flexible subdomain management.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Info>
|
||||
In self-hosted Pangolin, domains do not need individual verification, but you're responsible for ensuring correct DNS records point to your server.
|
||||
</Info>
|
||||
|
||||
## DNS Configuration
|
||||
|
||||
### For Domain Delegation
|
||||
|
||||
When using domain delegation, you'll need to update your domain's nameservers:
|
||||
|
||||
**Example NS Records:**
|
||||
```dns
|
||||
Type: NS
|
||||
Name: test.example.com
|
||||
Value: ns-east.fossorial.io
|
||||
Value: ns-west.fossorial.io
|
||||
```
|
||||
|
||||
### For Single Domain (CNAME)
|
||||
|
||||
When using CNAME domains, you'll need to add CNAME records:
|
||||
|
||||
**Example CNAME Records:**
|
||||
```dns
|
||||
Record 1:
|
||||
Type: CNAME
|
||||
Name: test.example.com
|
||||
Value: 0nbn5rpcq4wthq6.cname.fossorial.io
|
||||
|
||||
Record 2:
|
||||
Type: CNAME
|
||||
Name: _acme-challenge.test.example.com
|
||||
Value: _acme-challenge.0nbn5rpcq4wthq6.cname.fossorial.io
|
||||
```
|
||||
|
||||
<Check>
|
||||
Once DNS is properly configured and propagated, your domain will be verified and ready to use with your Pangolin resources.
|
||||
</Check>
|
||||
|
||||
@@ -5,17 +5,13 @@ description: "Learn about Pangolin's high availability options and how to ensure
|
||||
|
||||
Pangolin provides multiple deployment options to ensure your applications remain highly available and accessible to users worldwide.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
|
||||
Global network of points of presence with automatic failover and routing to your backend services.
|
||||
</Card>
|
||||
|
||||
<Card title="Hybrid" icon="server" href="mailto:numbat@fossorial.io">
|
||||
Host your own multiple highly available points of presence with cloud coordination and automatic failover.
|
||||
</Card>
|
||||
|
||||
<Card title="Self-Hosted" icon="server" href="/self-host/quick-install">
|
||||
Fully self-hosted, self-contained Pangolin server acting as a single point of presence.
|
||||
<Card title="Hybrid" icon="circle-nodes" href="mailto:numbat@fossorial.io">
|
||||
Host your own multiple points of presence with cloud coordination and automatic failover. Data always transits your servers.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -23,7 +19,26 @@ Pangolin provides multiple deployment options to ensure your applications remain
|
||||
|
||||
For detailed information about how points of presence work and their advantages, see our [Points of Presence](/manage/points-of-presence) documentation.
|
||||
|
||||
## Hybrid Deployment
|
||||
|
||||
The hybrid model allows you to host your own points of presence while leveraging Pangolin Cloud's coordination and failover capabilities:
|
||||
|
||||
### How It Works
|
||||
|
||||
- **You Host the Exit Node**: Manage the infrastructure for your points of presence, which connect your Newt tunnels.
|
||||
- **We Handle the Rest**: Pangolin Cloud manages the control plane, DNS, certificate management, database, and backups.
|
||||
- **Failover Made Simple**: Host multiple exit nodes with automatic failover between them. Optionally, if your nodes are unavailable, traffic automatically fails over to our cloud nodes.
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Data Control**: Traffic flows through your servers, giving you control over data transit costs, privacy, and works with your security policies.
|
||||
- **High Availability**: Eliminates the complexity of managing high availability while still owning your own infrastrcture.
|
||||
|
||||
<Tip>
|
||||
Hybrid deployment is ideal for organizations that need high availability while maintaining control over their infrastructure and data transit.
|
||||
</Tip>
|
||||
|
||||
## Contact Us
|
||||
|
||||
For hybrid deployments, points of presence, and high availability contact us:
|
||||
- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io)
|
||||
- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io)
|
||||
|
||||
@@ -5,19 +5,25 @@ description: "Learn about Pangolin's global network of points of presence and ho
|
||||
|
||||
Pangolin's points of presence (PoPs) are strategically located servers around the world that serve as entry points for user traffic to your applications. They form the foundation of Pangolin's distributed architecture, providing global high availability and optimal performance.
|
||||
|
||||
## Contact Us
|
||||
|
||||
For hybrid deployments, points of presence, and high availability contact us:
|
||||
- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io)
|
||||
|
||||
## What Are Points of Presence?
|
||||
|
||||
Points of presence are geographically distributed servers that:
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Entry Points" icon="door-open">
|
||||
Handle incoming user requests before routing them to your applications.
|
||||
</Card>
|
||||
|
||||
- **Serve as Entry Points**: Handle incoming user requests before routing them to your applications
|
||||
- **Provide Global Coverage**: Located worldwide to minimize latency for users in different regions
|
||||
- **Enable High Availability**: Multiple locations ensure your applications remain accessible even if individual locations fail
|
||||
- **Handle Authentication**: Verify user identity and enforce access policies before allowing access
|
||||
<Card title="Global Coverage" icon="globe">
|
||||
Located regionally to minimize latency for users in different regions.
|
||||
</Card>
|
||||
|
||||
<Card title="High Availability" icon="shield-check">
|
||||
Multiple locations ensure your applications remain accessible even if individual locations fail.
|
||||
</Card>
|
||||
|
||||
<Card title="Authentication" icon="key">
|
||||
Verify user identity and enforce access policies before allowing access.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Info>
|
||||
Think of points of presence as the "front doors" to your applications - users connect to the closest one, and it securely routes their requests to your backend services.
|
||||
@@ -25,92 +31,79 @@ Think of points of presence as the "front doors" to your applications - users co
|
||||
|
||||
## How Points of Presence Work
|
||||
|
||||
### Geographic Routing
|
||||
<Steps>
|
||||
<Step title="Ingress Routing">
|
||||
Request is routed to the closest available point of presence. If one goes down, there is always another point available.
|
||||
</Step>
|
||||
|
||||
When a user requests access to your application:
|
||||
<Step title="Authentication">
|
||||
User identity is verified at the point of presence before getting routed to your backend.
|
||||
</Step>
|
||||
|
||||
1. **DNS Resolution**: The user's request is automatically routed to the closest available point of presence
|
||||
2. **Authentication**: The point of presence verifies the user's identity and permissions
|
||||
3. **Tunnel Routing**: Authenticated requests are sent through secure tunnels to your applications
|
||||
4. **Response Delivery**: Responses follow the same path back to the user
|
||||
<Step title="Tunnel Selection">
|
||||
Pangolin selects the optimal tunnel route to your backend service. Site tunnel clients (Newt) connect to the optimal point of presence.
|
||||
</Step>
|
||||
|
||||
<Check>
|
||||
This routing happens automatically and transparently - users always get the best possible performance without any manual configuration.
|
||||
</Check>
|
||||
|
||||
### Automatic Failover
|
||||
|
||||
Pangolin's points of presence provide built-in high availability:
|
||||
|
||||
- **Health Monitoring**: Each point of presence continuously monitors its health and connectivity
|
||||
- **Automatic Failover**: If one location becomes unavailable, traffic automatically routes to the next closest location
|
||||
- **Load Distribution**: Traffic is automatically balanced across multiple locations to prevent overload
|
||||
- **Global Redundancy**: Multiple points of presence ensure your applications remain accessible during regional outages
|
||||
<Step title="Failover Handling">
|
||||
If the primary tunnel fails, traffic automatically switches to an alternative route.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Advantages of Points of Presence
|
||||
|
||||
### Global Performance
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Low Latency" icon="bolt">
|
||||
Users connect to the geographically closest point of presence.
|
||||
</Card>
|
||||
|
||||
- **Low Latency**: Users connect to the geographically closest point of presence
|
||||
- **Optimized Routing**: Automatic selection of the best available location
|
||||
- **Edge Computing**: Processing happens closer to users for faster response times
|
||||
<Card title="Optimized Routing" icon="route">
|
||||
Automatic selection of the best available tunnel to route to your backend services.
|
||||
</Card>
|
||||
|
||||
### High Availability
|
||||
<Card title="Edge Computing" icon="microchip">
|
||||
Provide ingress to thin-clients on private networks via tunnels.
|
||||
</Card>
|
||||
|
||||
- **Fault Tolerance**: No single point of failure - if one location goes down, others remain available
|
||||
- **Automatic Recovery**: Failed locations are automatically bypassed and traffic is rerouted
|
||||
- **Regional Redundancy**: Multiple locations per region provide additional redundancy
|
||||
<Card title="Health Monitoring" icon="heart-pulse">
|
||||
Each point of presence continuously monitors its health and connectivity to your backend.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Security and Compliance
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Global Redundancy" icon="check-double">
|
||||
Multiple points of presence ensure your applications remain accessible during regional outages.
|
||||
</Card>
|
||||
|
||||
- **Distributed Security**: Security controls are enforced at every point of presence
|
||||
- **Regional Compliance**: Points of presence can be configured to meet regional data requirements
|
||||
- **Encrypted Transit**: All traffic between points of presence and your applications is encrypted
|
||||
|
||||
### Scalability
|
||||
|
||||
- **Automatic Scaling**: New points of presence are automatically added as needed
|
||||
- **Load Balancing**: Traffic is distributed across multiple locations to handle high volumes
|
||||
- **Global Distribution**: Support for applications with users worldwide
|
||||
<Card title="Fault Tolerance" icon="shield">
|
||||
No single point of failure - if one location goes down, there is always a way back to your application.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Deployment Models
|
||||
|
||||
### Pangolin Cloud
|
||||
|
||||
Pangolin Cloud includes a global network of points of presence that provide:
|
||||
|
||||
- **Automatic Management**: Points of presence are automatically deployed, monitored, and maintained
|
||||
- **Global Coverage**: Strategic locations worldwide for optimal performance
|
||||
- **Built-in High Availability**: Multiple redundant locations ensure 99.9%+ uptime
|
||||
- **Zero Configuration**: No setup or management required on your part
|
||||
|
||||
<Card title="Try Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
|
||||
Get started with Pangolin Cloud and experience global points of presence with automatic high availability.
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
|
||||
Global network of points of presence with automatic failover and routing to your backend services.
|
||||
</Card>
|
||||
|
||||
### Self-Hosted Pangolin
|
||||
<Card title="Hybrid" icon="circle-nodes" href="mailto:numbat@fossorial.io">
|
||||
Host your own multiple points of presence with cloud coordination and automatic failover. Data always transits yours servers.
|
||||
</Card>
|
||||
|
||||
Self-hosted Pangolin operates as a single point of presence:
|
||||
|
||||
- **Single Location**: Your Pangolin instance serves as the only entry point
|
||||
- **Limited Availability**: No built-in redundancy - if your server goes down, access is lost
|
||||
- **Manual Management**: You're responsible for server maintenance and uptime
|
||||
- **Regional Limitation**: Performance depends on your server's location
|
||||
<Card title="Self-Hosted" icon="server" href="/self-host/quick-install">
|
||||
Fully self-hosted, self-contained Pangolin server acting as a single point of presence.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Warning>
|
||||
Self-hosted Pangolin provides only a single point of presence and is not highly available. Consider Pangolin Cloud or hybrid deployment for production environments requiring high availability.
|
||||
</Warning>
|
||||
|
||||
### Hybrid Deployment
|
||||
|
||||
Hybrid deployment allows you to host your own points of presence while leveraging Pangolin's cloud coordination:
|
||||
|
||||
- **Your Infrastructure**: Host points of presence on your own servers or cloud infrastructure
|
||||
- **Cloud Coordination**: Pangolin Cloud handles failover logic and coordination between your points of presence
|
||||
- **Automatic Failover**: If your points of presence go down, traffic automatically fails over to Pangolin Cloud
|
||||
- **Data Control**: Traffic flows through your servers, giving you control over data transit costs and privacy
|
||||
- **Custom Locations**: Deploy points of presence in specific regions or data centers of your choice
|
||||
|
||||
<Tip>
|
||||
Hybrid deployment is ideal for organizations that need high availability while maintaining control over their infrastructure and data transit.
|
||||
</Tip>
|
||||
|
||||
## Contact Us
|
||||
|
||||
For hybrid deployments, points of presence, and high availability contact us:
|
||||
- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io)
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Configure Newt"
|
||||
title: "Configure Site"
|
||||
description: "Configure Newt for connecting to Pangolin sites"
|
||||
---
|
||||
Newt is a fully user space [WireGuard](https://www.wireguard.com/) tunnel client and TCP/UDP proxy, designed to securely expose private resources controlled by Pangolin. By using Newt, you don't need to manage complex WireGuard tunnels and NATing.
|
||||
@@ -26,8 +26,6 @@ When Newt receives proxy control messages, it will use the information encoded t
|
||||
|
||||
## Configuration Arguments
|
||||
|
||||
### Required Arguments
|
||||
|
||||
<ResponseField name="id" type="string" required>
|
||||
Newt ID generated by Pangolin to identify the client.
|
||||
|
||||
@@ -50,8 +48,6 @@ When Newt receives proxy control messages, it will use the information encoded t
|
||||
**Example**: `https://pangolin.example.com`
|
||||
</ResponseField>
|
||||
|
||||
### Optional Arguments
|
||||
|
||||
<ResponseField name="mtu" type="integer">
|
||||
MTU for the internal WireGuard interface.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Install Newt"
|
||||
title: "Install Site"
|
||||
description: "Install Newt as a binary or Docker container"
|
||||
---
|
||||
|
||||
48
manage/sites/update-site.mdx
Normal file
48
manage/sites/update-site.mdx
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: "Update Site"
|
||||
description: "Update Newt to the latest version"
|
||||
---
|
||||
|
||||
The update process depends on how you originally installed Newt.
|
||||
|
||||
Find the lates version in the [GitHub releases](https://github.com/fosrl/newt/releases).
|
||||
|
||||
## Docker Installation
|
||||
|
||||
Update the image version in your `docker-compose.yml`:
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
newt:
|
||||
image: fosrl/newt:{version} # Replace {version} with the latest version tag
|
||||
# ... rest of config
|
||||
```
|
||||
|
||||
Then pull and restart:
|
||||
|
||||
```bash
|
||||
docker compose pull newt
|
||||
docker compose up -d newt
|
||||
```
|
||||
|
||||
## Binary Installation
|
||||
|
||||
### Auto Installer (Recommended)
|
||||
|
||||
If you used the auto installer, simply run it again.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://docs.fossorial.io/get-newt.sh | bash
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
|
||||
Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/newt/releases) and replace your existing binary.
|
||||
|
||||
```bash
|
||||
wget -O newt "https://github.com/fosrl/newt/releases/download/{version}/newt_{architecture}" && chmod +x ./newt
|
||||
```
|
||||
|
||||
<Note>
|
||||
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/newt/releases) for the latest information.
|
||||
</Note>
|
||||
Reference in New Issue
Block a user