pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-02-08 05:56:45 +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

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