pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-10-01 10:19:23 +02:00
Code Issues Packages Projects Releases Wiki Activity

consolidate client platforms

Browse Source
This commit is contained in:
miloschwartz
2026-09-30 13:50:05 -04:00
parent 05d6fcc499
commit 03b60177a4
43 changed files with 1573 additions and 1372 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/docs/manage/access-control/forwarded-headers.mdx
+1 -1
View File
@@ -59,6 +59,6 @@ These authentication methods do not provide user identity information:
- A public resource called with an [identity key](/manage/ai/virtual-api-keys#identity-keys)
- A public resource called with a [manual key](/manage/ai/virtual-api-keys#manual-keys) attributed to a user
- A private AI Gateway resource called from a connected [Pangolin client](/manage/clients/install-client)
- A private AI Gateway resource called from a connected [Pangolin client](/manage/clients/platforms)
An unattributed manual key authenticates without sending these headers. Details are in [Identity Headers](/manage/ai/providers/configuration#identity-headers).
content/docs/manage/ai/configure-ai-clients/claude.mdx
+1 -1
View File
@@ -12,7 +12,7 @@ You'll need the resource's URL (its `<endpoint>`) and its API key (`<key>`). Bot
## Fastest: Pangolin CLI
[Install the Pangolin CLI](/manage/clients/install-client#quick-install-recommended) if you don't have it, then log in:
[Install the Pangolin CLI](/manage/clients/platforms/cli#install) if you don't have it, then log in:
```bash
pangolin login
content/docs/manage/ai/configure-ai-clients/codex.mdx
+1 -1
View File
@@ -12,7 +12,7 @@ You'll need the resource's URL (its `<endpoint>`) and its API key (`<key>`). Bot
## Fastest: Pangolin CLI
[Install the Pangolin CLI](/manage/clients/install-client#quick-install-recommended) if you don't have it, then log in:
[Install the Pangolin CLI](/manage/clients/platforms/cli#install) if you don't have it, then log in:
```bash
pangolin login
content/docs/manage/ai/configure-ai-clients/gemini.mdx
+1 -1
View File
@@ -12,7 +12,7 @@ You'll need the resource's URL (its `<endpoint>`) and its API key (`<key>`). Bot
## Fastest: Pangolin CLI
[Install the Pangolin CLI](/manage/clients/install-client#quick-install-recommended) if you don't have it, then log in:
[Install the Pangolin CLI](/manage/clients/platforms/cli#install) if you don't have it, then log in:
```bash
pangolin login
content/docs/manage/ai/configure-ai-clients/opencode.mdx
+1 -1
View File
@@ -12,7 +12,7 @@ You'll need the resource's URL (its `<endpoint>`) and its API key (`<key>`). Bot
## Fastest: Pangolin CLI
[Install the Pangolin CLI](/manage/clients/install-client#quick-install-recommended) if you don't have it, then log in:
[Install the Pangolin CLI](/manage/clients/platforms/cli#install) if you don't have it, then log in:
```bash
pangolin login
content/docs/manage/ai/overview.mdx
+1 -1
View File
@@ -37,7 +37,7 @@ How a client authenticates depends on whether the resource is public or private.
### Private Resources
Reachable only on devices connected with the [Pangolin client](/manage/clients/install-client). Identity comes from that connection, so you do not issue a [virtual API key](/manage/ai/virtual-api-keys). The desktop client already proved who is calling. Details are on the [private AI Gateway](/manage/resources/private/ai-gateway) resource page.
Reachable only on devices connected with the [Pangolin client](/manage/clients/platforms). Identity comes from that connection, so you do not issue a [virtual API key](/manage/ai/virtual-api-keys). The desktop client already proved who is calling. Details are on the [private AI Gateway](/manage/resources/private/ai-gateway) resource page.
### Public Resources
content/docs/manage/ai/providers/configuration.mdx
+1 -1
View File
@@ -86,7 +86,7 @@ The user is known when:
- A public resource is called with an [identity key](/manage/ai/virtual-api-keys#identity-keys)
- A public resource is called with a [manual key](/manage/ai/virtual-api-keys#manual-keys) attributed to a user
- A private AI Gateway resource is called from a connected [Pangolin client](/manage/clients/install-client), and that client maps to a user
- A private AI Gateway resource is called from a connected [Pangolin client](/manage/clients/platforms), and that client maps to a user
An unattributed manual key still authenticates, but these headers are omitted. Empty values are omitted rather than sent blank.
content/docs/manage/ai/virtual-api-keys.mdx
+1 -1
View File
@@ -23,7 +23,7 @@ Logging into Pangolin in a browser is how you **retrieve** a key. Model calls st
## Public Resources Only
Virtual keys apply to **public** AI Gateway resources. [Private resources](/manage/resources/understanding-resources) are reached through the [Pangolin client](/manage/clients/install-client), so the gateway does not check a key. Clients still need a placeholder in the key field; use the literal string `none`. Deleting the field usually breaks the client.
Virtual keys apply to **public** AI Gateway resources. [Private resources](/manage/resources/understanding-resources) are reached through the [Pangolin client](/manage/clients/platforms), so the gateway does not check a key. Clients still need a placeholder in the key field; use the literal string `none`. Deleting the field usually breaks the client.
## Authentication Is Always On
content/docs/manage/clients/client-logs.mdx
+1 -1
View File
@@ -52,7 +52,7 @@ sudo pangolin up --attach
## Android
Turn on **Enable Log Collection** under **Preferences**. Tunnel logs are then saved to a file you can download from the app. You can also view logs under **Preferences > Logs**. See [Configure Clients](/manage/clients/configure-client).
Turn on **Enable Log Collection** under **Preferences**. Tunnel logs are then saved to a file you can download from the app. You can also view logs under **Preferences > Logs**. See [Android](/manage/clients/platforms/android).
## iOS
content/docs/manage/clients/configure-client.mdx
-762
View File
@@ -1,762 +0,0 @@
---
title: "Configure Clients"
description: "Configure Pangolin clients to work best with your network setup"
---
## GUI Clients (Mac, Windows, Android, iOS/iPadOS)
Each client has a preferences window. On Mac and Windows, click the menu bar or system tray icon and select "Preferences". In the mobile apps, open the "Preferences" screen.
The preferences in the next section are shared across platforms. Each platform section after that covers settings that exist only on that client. When a client has a config file, that file is documented in an **Advanced** subsection of the platform.
To troubleshoot connection or configuration issues, see [Client Logs](/manage/clients/client-logs) for how to view logs on each platform.
## Shared Preferences
The following preferences control how your client handles DNS resolution and network routing. They are available on Mac, Windows, Android, and iOS/iPadOS.
### Enable Aliases (Override DNS)
When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system's default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured Upstream DNS Server.
**When to use it**: This is required if you use aliases on resources in Pangolin. Aliases are friendly domain names assigned to private resources. Pangolin resolves these alias addresses over a private DNS server running in your client.
**How it works**: The client loops back to itself to resolve the alias. This is why you may see your DNS server as an unfamiliar address (often like `100.90.128.x`) when this is enabled. When a request doesn't resolve to a Pangolin resource and is bound for another website (like `google.com`), it falls back to your configured upstream DNS server.
### DNS Over Tunnel
When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server.
**When to use it**: Tunnel DNS is used when you want to send all DNS queries over the tunnel to a private resource made available in Pangolin. For example, if you host a DNS server like Pi-hole, you could define a private resource for Pi-hole on your remote network. Then in the Pangolin client, you would enable Tunnel DNS and set the host of the Pi-hole private resource as the tunnel DNS server.
**How it works**: When a request needs to be resolved, Pangolin sends it over the tunnel to the site of the private resource with your DNS server. You must enable DNS Over Tunnel and also set the upstream DNS server to your private DNS server.
This requires aliases "override DNS" to be enabled as well. This is because the client must take control of your DNS settings to route queries through the tunnel to your private DNS server.
<Warning>
You cannot use an alias name for your DNS server. It must be the IP address
of the resource. This is because it's pointing to the DNS server, so the DNS
server can't resolve itself.
</Warning>
### Primary Upstream DNS
This is the DNS server used to resolve queries that are not bound to a Pangolin alias when Override DNS or DNS Over Tunnel is enabled.
When left blank, **System DNS** is used. This pulls the existing configured system DNS settings and applies them to the tunnel. If Tunnel DNS is enabled and System DNS is used, requests will likely fail if the DNS server is not accessible over the tunnel.
### Secondary Upstream DNS
This is a fallback DNS server used to resolve queries that are not bound to a Pangolin alias when the primary server is unavailable. Ordering and priority of the server is not guaranteed, but it provides redundancy for DNS resolution. When left blank, **System DNS** is used, same as Primary Upstream DNS.
### Match Domains
By default, when match domains are not set, all DNS queries are sent to the configured upstream DNS server. Match domains let you whitelist which domains should be sent to the upstream DNS server. When match domains are set, only matching queries go to upstream DNS; all other requests use the system's DNS servers.
**When to use it**: When you have a private or corporate DNS server for specific domains (for example, `*.proxy.internal` or `corp.example.com`) and want everything else resolved by the system DNS as usual.
**How it works**: With no match domains configured, every query is forwarded to your Upstream DNS Server. With match domains set, only queries that match the list are forwarded upstream; the rest use the system's default DNS servers.
### Exit Nodes Take Precedence Over Resources
By default this is disabled. When a client is connected using an exit node other Pangolin resources will still be accessible and resolvable even on other sites not designated on the exit node resource. In this way Pangolin is still split tunneling these destinations. By enabling this setting, you are configuring Pangolin to ignore other resources outside of the exit node. All traffic will flow to and through the exit node resource and DNS aliases and subnets on other resources will no longer function.
### MTU
You can set the maximum transmission unit (MTU) for the client’s internal WireGuard interface. This value is client-wide: every site the client connects to must use the same MTU on the site side, or you can see fragmentation, failed handshakes, or unstable tunnels. See the **mtu** option on [Configure Sites](/manage/sites/configure-site) and set the same value on each of those sites.
<Warning>
Changing MTU is advanced and not recommended for most users. Only change it
when you have a specific, well-understood reason (for example, a constrained
network path or a requirement from your infrastructure team). If you do
change it, you must update every connected site to the identical value.
</Warning>
## Windows
### Start at Login
When enabled, Pangolin starts when you sign in to Windows.
### Connect at Start
When enabled, the tunnel connects whenever Pangolin starts. This also opens Pangolin at sign-in.
### Advanced
On Windows, the Pangolin GUI reads configuration from two `pangolin.json` files:
- User config: `%LOCALAPPDATA%\Pangolin\pangolin.json` (for example, `C:\Users\USER\AppData\Local\Pangolin\pangolin.json`)
- Global config: `%ProgramData%\Pangolin\pangolin.json`
Most keys in the `Config` object below can be set in either file. If the same key exists in both places, the user config value overrides the global value. This lets administrators define global defaults while still allowing per-user overrides when needed. Keys marked **Global only** must be set in `%ProgramData%\Pangolin\pangolin.json`; restart the Pangolin manager/UI after changing them.
<ResponseField name="Config" type="object">
JSON configuration for the Windows Pangolin client stored in `pangolin.json`.
<Expandable title="Config">
<ResponseField name="dnsOverride" type="boolean">
When true, matches the **Enable Aliases (Override DNS)** preference and lets the client take over DNS resolution for Pangolin resources.
</ResponseField>
<ResponseField name="dnsTunnel" type="boolean">
When true, matches the **DNS Over Tunnel** preference and sends DNS queries through the Pangolin tunnel.
</ResponseField>
<ResponseField name="primaryDNS" type="string">
Primary upstream DNS server used when override/tunnel DNS is enabled.
</ResponseField>
<ResponseField name="secondaryDNS" type="string">
Optional secondary upstream DNS server used as a fallback when the primary is unavailable.
</ResponseField>
<ResponseField name="dnsMatchDomains" type="array of strings">
Optional whitelist of domains sent to the configured upstream DNS server. When unset, all queries go to upstream DNS. When set, only matching queries use your Upstream DNS Server; all other requests use the system's DNS servers. Supports wildcards such as `*.proxy.internal`.
</ResponseField>
<ResponseField name="defaultServerURL" type="string">
When set, skips the deployment option screen during login; all login flows start directly with this server URL.
</ResponseField>
<ResponseField name="authPath" type="string">
Optional path appended to the server URL for authentication, for example `/auth/org/my-org` to always send users to a specific organization or branded login page. Most deployments should leave this unset.
</ResponseField>
<ResponseField name="userSettingsDisabled" type="boolean">
When true, hides and disables the settings form in the GUI so users cannot change these values themselves.
</ResponseField>
<ResponseField name="openStatusTabOnConnect" type="boolean">
When true, opens the Status tab immediately after clicking Connect so users can watch connection feedback while the tunnel is starting.
</ResponseField>
<ResponseField name="mtu" type="integer">
MTU for the internal WireGuard interface. Changing this is advanced and not recommended unless you have a clear reason; if you set a non-default value, configure the same MTU on every site this client connects to—see [Configure Sites](/manage/sites/configure-site).
</ResponseField>
<ResponseField name="preferLocalRoutes" type="boolean">
When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel.
</ResponseField>
<ResponseField name="exitNodeTakesPrecedence" type="boolean">
When true, matches the **Exit Nodes Take Precedence Over Resources** preference. While connected through an exit node, routes for other resources are not added and their aliases are not resolved, so all traffic flows through the exit node. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="openUIAtLogin" type="boolean">
When true, matches the **Start at Login** preference and starts Pangolin when you sign in to Windows. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="autoConnectAtLogin" type="boolean">
When true, matches the **Connect at Start** preference. The tunnel connects whenever Pangolin starts, and Pangolin also opens at sign-in, regardless of `openUIAtLogin`. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="autoUpdateChecksEnabled" type="boolean">
**Global only.** When true, periodically check for updates in the background. When false, automatic checks are off; users can still use **Check for Updates** unless that button is also disabled. If omitted, the default is `true`. Enabling checks surfaces the update UI when a new version exists (tray “Pangolin Update Available” and the update prompt). Intended for org admins / MDM so config is the source of truth.
</ResponseField>
<ResponseField name="updateCheckIntervalSeconds" type="integer">
**Global only.** How often automatic checks run, in seconds. Values below `3600` (1 hour) are clamped to `3600`. Only matters when `autoUpdateChecksEnabled` is true. If omitted, the default is `86400` (24 hours). The client applies a small amount of jitter around this interval.
</ResponseField>
<ResponseField name="checkForUpdatesButtonEnabled" type="boolean">
**Global only.** When true, show **Check for Updates** in the system tray More menu. When false, hide that menu item. If omitted, the default is `true`. Manual checks always perform a live network lookup when the button is used. This is independent of `autoUpdateChecksEnabled`.
</ResponseField>
<ResponseField name="logLevel" type="string">
**Global only.** Controls client log verbosity. Supported values include `debug` and `info`. If omitted, the default is `info`.
</ResponseField>
<ResponseField name="sessionCookieName" type="string">
Overrides the cookie name the session token is sent and read under. Most deployments should leave this unset.
</ResponseField>
</Expandable>
</ResponseField>
As a system administrator, you can script placing `pangolin.json` in `%ProgramData%\Pangolin\` to set global defaults, and/or in each user's `%LOCALAPPDATA%\Pangolin\` folder for per-user overrides and targeted rollout behavior.
<Tip>
For enterprise customers, contact us if you need a custom MSI installer with
baked-in configuration; we can maintain custom installers as an add-on to
your enterprise license.
</Tip>
## Mac
### Start at Login
When enabled, Pangolin opens automatically when you log in to your Mac.
### Connect Automatically On
Choose when Pangolin may connect automatically. **Connect** enables on-demand for that interface; **Disconnect** disables it.
**Ethernet** connects automatically while the Mac is on Ethernet.
**Wi-Fi** connects automatically while the Mac is on Wi-Fi. You can limit which networks that applies to:
- **Any Wi-Fi Network** connects on every Wi-Fi network.
- **Only these Wi-Fi Networks** connects only on the networks you list.
- **Except these Wi-Fi Networks** connects on every network except the ones you list.
### Advanced
On Mac, the Pangolin GUI reads configuration from `~/Library/Application Support/Pangolin/pangolin.json`. Restart Pangolin after editing for changes to apply.
<ResponseField name="Config" type="object">
JSON configuration for the Mac Pangolin client stored in `pangolin.json`.
<Expandable title="Config">
<ResponseField name="dnsOverrideEnabled" type="boolean">
When true, matches the **Enable Aliases (Override DNS)** preference and lets the client take over DNS resolution for Pangolin resources.
</ResponseField>
<ResponseField name="dnsTunnelEnabled" type="boolean">
When true, matches the **DNS Over Tunnel** preference and sends DNS queries through the Pangolin tunnel.
</ResponseField>
<ResponseField name="primaryDNSServer" type="string">
Primary upstream DNS server used when override/tunnel DNS is enabled.
</ResponseField>
<ResponseField name="secondaryDNSServer" type="string">
Optional secondary upstream DNS server used as a fallback when the primary is unavailable.
</ResponseField>
<ResponseField name="dnsMatchDomains" type="array of strings">
Optional whitelist of domains sent to the configured upstream DNS server. When unset, all queries go to upstream DNS. When set, only matching queries use your Upstream DNS Server; all other requests use the system's DNS servers. Supports wildcards such as `*.proxy.internal`.
</ResponseField>
<ResponseField name="exitNodeTakesPrecedence" type="boolean">
When true, matches the **Exit Nodes Take Precedence Over Resources** preference. While connected through an exit node, routes for other resources are not added and their aliases are not resolved, so all traffic flows through the exit node. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="tunnelMTU" type="integer">
MTU for the internal WireGuard interface. Changing this is advanced and not recommended unless you have a clear reason; if you set a non-default value, configure the same MTU on every site this client connects to. See [Configure Sites](/manage/sites/configure-site).
</ResponseField>
<ResponseField name="onDemandWiFiEnabled" type="boolean">
When true, matches the **Wi-Fi** option under **Connect Automatically On** and connects on demand whenever the Mac is on Wi-Fi. Use `onDemandSSIDOption` and `onDemandSSIDs` to limit this to specific networks. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="onDemandNonWiFiEnabled" type="boolean">
When true, matches the **Ethernet** option under **Connect Automatically On** and connects on demand whenever the Mac is on Ethernet. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="onDemandSSIDOption" type="string">
Which Wi-Fi networks on-demand applies to when `onDemandWiFiEnabled` is true. Supported values are `any` (**Any Wi-Fi Network**), `only` (**Only these Wi-Fi Networks**, the names in `onDemandSSIDs`), and `except` (**Except these Wi-Fi Networks**). If omitted, or if `onDemandSSIDs` is empty, the default is `any`.
</ResponseField>
<ResponseField name="onDemandSSIDs" type="array of strings">
Wi-Fi network names (SSIDs) used by the `only` and `except` modes of `onDemandSSIDOption`.
</ResponseField>
<ResponseField name="autoUpdateChecksEnabled" type="boolean">
When true, periodically check for updates in the background. When false, automatic checks are off; users can still use **Check for Updates**. If omitted, the client default applies (may prompt the user on second launch). Enabling checks without `autoDownloadUpdatesEnabled` still surfaces the update UI when a new version exists. Intended for admin / MDM provisioning so config stays the source of truth over user toggles.
</ResponseField>
<ResponseField name="autoDownloadUpdatesEnabled" type="boolean">
When true, download updates silently when found and stage install for quit/relaunch. When false, show the normal update dialog instead of silent download. Silent download does not replace the running app mid-session; the update installs on quit (and relaunches), so long-running menu bar sessions may keep a staged update until quit. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="updateCheckIntervalSeconds" type="integer">
How often automatic checks run, in seconds. Values below `3600` (1 hour) are clamped to `3600`. Only matters when `autoUpdateChecksEnabled` is true. If omitted, the default is `86400` (24 hours).
</ResponseField>
<ResponseField name="sessionCookieName" type="string">
Overrides the cookie name the session token is sent and read under. Most deployments should leave this unset.
</ResponseField>
</Expandable>
</ResponseField>
## iOS/iPadOS
### Dynamic Island and Live Activity
When enabled, Pangolin shows connection status in the Dynamic Island and on the Lock Screen.
### Connect Automatically On
Choose when Pangolin may connect automatically. Tap **Connect** to enable on-demand for that interface; **Disconnect** disables it.
**Cellular** connects automatically while the device is on cellular.
**Wi-Fi** connects automatically while the device is on Wi-Fi. You can limit which networks that applies to:
- **Any Wi-Fi Network** connects on every Wi-Fi network.
- **Only these Wi-Fi Networks** connects only on the networks you list.
- **Except these Wi-Fi Networks** connects on every network except the ones you list.
## Android
### Show Persistent VPN Notification
When enabled, Pangolin keeps a status notification while connected. A temporary notification may still appear when connecting or recovering. Android's own VPN indicators are unaffected.
Leaving this on makes it less likely that Android will stop the connection while the app is in the background.
### Enable Log Collection
When enabled, tunnel logs are saved to a file that can be downloaded for troubleshooting. See [Client Logs](/manage/clients/client-logs).
### Battery Optimization
To ensure Pangolin functions correctly in the background on Android devices, it's recommended to disable battery optimization for the app. This prevents the operating system from restricting its background activities, which could lead to disconnections.
1. Open the **Settings** app on your Android device.
2. Navigate to **Apps & notifications** (or simply **Apps** on some devices).
3. Find and select the Pangolin app from the list of installed apps.
4. Tap on **App battery usage**.
5. Select **Allow background usage** and enable if disabled.
6. From the options menu, choose **Unrestricted**.
<Frame caption="Android Battery Optimization Settings">
<img
src="/images/android_battery.png"
alt="Android Battery Optimization Settings"
style={{ width: "250px", height: "auto" }}
/>
</Frame>
## Pangolin CLI
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.
### Config File
The Pangolin CLI stores persistent settings in `~/.config/pangolin/config.json` on every platform. When the CLI is run with `sudo`, it uses the home directory of the user who invoked `sudo`, so the same file applies with and without it. Run `pangolin config path` to print the exact location.
<ResponseField name="Config" type="object">
JSON configuration for the Pangolin CLI stored in `config.json`.
<Expandable title="Config">
<ResponseField name="log_level" type="string">
Controls CLI log verbosity. Supported values are `debug` and `info`. If omitted, the default is `info`.
</ResponseField>
<ResponseField name="log_file" type="string">
Path of the client log file. If omitted, the default is `~/.config/pangolin/logs/client.log`. This key can only be changed by editing the file; it is not available through `pangolin config set`.
</ResponseField>
<ResponseField name="disable_update_check" type="boolean">
When true, the CLI does not check for new versions. If omitted, the default is `false`, except in builds distributed through a package manager, where it is `true`.
</ResponseField>
<ResponseField name="disable_companion_mode" type="boolean">
When true, the CLI uses its own standalone authentication instead of companion mode, where login, accounts, organizations, and exit node selection are managed by the Pangolin desktop app. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="companion_app_data_dirs" type="object">
Overrides where the CLI looks for the desktop app's data directory in companion mode. Accepts a `windows` and a `darwin` path. Most installations should leave this unset. This key can only be changed by editing the file.
</ResponseField>
<ResponseField name="session_cookie_name" type="string">
Overrides the cookie name used for the CLI's session token. Most deployments should leave this unset.
</ResponseField>
<ResponseField name="up.override_dns" type="boolean">
Default for `--override-dns`. When true, matches the **Enable Aliases (Override DNS)** preference and lets the client take over DNS resolution for Pangolin resources. If omitted, the default is `true`.
</ResponseField>
<ResponseField name="up.tunnel_dns" type="boolean">
Default for `--tunnel-dns`. When true, matches the **DNS Over Tunnel** preference and sends DNS queries through the Pangolin tunnel. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="up.upstream_dns" type="array of strings">
Default for `--upstream-dns`. Upstream DNS servers used when override/tunnel DNS is enabled. With `pangolin config set`, pass a comma-separated list such as `10.0.0.53,10.0.0.54`.
</ResponseField>
<ResponseField name="up.match_domains_dns" type="array of strings">
Default for `--match-domains`. Optional whitelist of domains sent to the configured upstream DNS server. When unset, all queries go to upstream DNS. When set, only matching queries use your Upstream DNS Server; all other requests use the system's DNS servers. Supports wildcards such as `*.proxy.internal`. With `pangolin config set`, pass a comma-separated list.
</ResponseField>
<ResponseField name="up.prefer_local_routes" type="boolean">
Default for `--prefer-local-routes`. When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="up.exit_node_takes_precedence" type="boolean">
Default for `--exit-node-takes-precedence`. When true, matches the **Exit Nodes Take Precedence Over Resources** preference. While connected through an exit node, routes for other resources are not added and their aliases are not resolved, so all traffic flows through the exit node. If omitted, the default is `false`.
</ResponseField>
</Expandable>
</ResponseField>
## Olm (Advanced, Deprecated)
<Accordion title="Olm CLI (advanced use only)">
<Tip>
We recommend using the Pangolin CLI for both user and machine clients if
you're looking for a CLI interface. Olm is the underlying client for the
Pangolin CLI.
</Tip>
Olm is a command-line client for connecting machine clients in Pangolin. You can configure it using command-line flags, environment variables, or a configuration file. Expand the section below to view all available configuration options.
<Accordion title="CLI Arguments and Options">
### Flags
<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 the Pangolin server resides for websocket connections.
**Example**: `https://pangolin.example.com`
</ResponseField>
<ResponseField name="org" type="string">
Organization ID to connect to.
</ResponseField>
<ResponseField name="user-token" type="string">
User authentication token.
</ResponseField>
<ResponseField name="mtu" type="integer">
MTU for the internal WireGuard interface.
**Default**: `1280`
</ResponseField>
<ResponseField name="dns" type="string">
DNS server to use to resolve the endpoint.
**Default**: `8.8.8.8`
</ResponseField>
<ResponseField name="upstream-dns" type="string">
Upstream DNS server(s), comma-separated.
**Default**: `8.8.8.8:53`
</ResponseField>
<ResponseField name="match-domains-dns" type="string">
FQDN wildcard patterns (using `*` and `?` wildcards, comma-separated, e.g. `*.proxy.internal,*.host-0?.autoco.internal`) to check against local records/upstream DNS. Queries for domains that don't match any pattern are sent directly to the host's own system DNS servers instead of being resolved as Pangolin resources.
**Default**: (empty, matches every domain)
</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="interface" type="string">
Name of the WireGuard interface.
**Default**: `olm`
</ResponseField>
<ResponseField name="enable-api" type="boolean">
Enable API server for receiving connection requests.
**Default**: `false`
</ResponseField>
<ResponseField name="http-addr" type="string">
HTTP server address (e.g., ':9452'). When unset, the HTTP API is not started and the socket API (see `socket-path`) is used instead.
**Default**: (not set)
</ResponseField>
<ResponseField name="socket-path" type="string">
Unix socket path (or named pipe on Windows).
**Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
</ResponseField>
<ResponseField name="disable-holepunch" type="boolean">
Disable hole punching.
**Default**: `false`
</ResponseField>
<ResponseField name="override-dns" type="boolean">
When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system's default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured Upstream DNS Server.
**Default**: `true`
</ResponseField>
<ResponseField name="tunnel-dns" type="boolean">
When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server.
**Default**: `false`
</ResponseField>
<ResponseField name="match-domains-dns" type="string">
Optional comma-separated whitelist of domains sent to the configured
upstream DNS server. When unset, all queries go to upstream DNS. When set,
only matching queries use your Upstream DNS Server; all other requests use
the system's DNS servers. Supports wildcards such as `*.proxy.internal`.
</ResponseField>
<ResponseField name="disable-relay" type="boolean">
Disable relay connections.
**Default**: `false`
</ResponseField>
<ResponseField name="prefer-local-routes" type="boolean">
When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel.
**Default**: `false`
</ResponseField>
### 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>
<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="ORG" type="string">
Organization ID to connect to (equivalent to `--org`)
</ResponseField>
<ResponseField name="USER_TOKEN" type="string">
User authentication token (equivalent to `--user-token`)
</ResponseField>
<ResponseField name="MTU" type="integer">
MTU for the internal WireGuard interface (equivalent to `--mtu`)
**Default**: `1280`
</ResponseField>
<ResponseField name="DNS" type="string">
DNS server to use to resolve the endpoint (equivalent to `--dns`)
**Default**: `8.8.8.8`
</ResponseField>
<ResponseField name="UPSTREAM_DNS" type="string">
Upstream DNS server(s), comma-separated (equivalent to `--upstream-dns`)
**Default**: `8.8.8.8:53`
</ResponseField>
<ResponseField name="MATCH_DOMAINS_DNS" type="string">
FQDN wildcard patterns, comma-separated (equivalent to `--match-domains-dns`)
**Default**: (empty, matches every domain)
</ResponseField>
<ResponseField name="LOG_LEVEL" type="string">
Log level (equivalent to `--log-level`)
**Default**: `INFO`
</ResponseField>
<ResponseField name="PING_INTERVAL" type="string">
Interval for pinging the server (equivalent to `--ping-interval`)
**Default**: `3s`
</ResponseField>
<ResponseField name="PING_TIMEOUT" type="string">
Timeout for each ping (equivalent to `--ping-timeout`)
**Default**: `5s`
</ResponseField>
<ResponseField name="INTERFACE" type="string">
Name of the WireGuard interface (equivalent to `--interface`)
**Default**: `olm`
</ResponseField>
<ResponseField name="ENABLE_API" type="boolean">
Enable API server for receiving connection requests (equivalent to `--enable-api`)
Set to "true" to enable
**Default**: `false`
</ResponseField>
<ResponseField name="HTTP_ADDR" type="string">
HTTP server address (equivalent to `--http-addr`)
**Default**: (not set)
</ResponseField>
<ResponseField name="SOCKET_PATH" type="string">
Unix socket path or Windows named pipe (equivalent to `--socket-path`)
**Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
</ResponseField>
<ResponseField name="DISABLE_HOLEPUNCH" type="boolean">
Disable hole punching (equivalent to `--disable-holepunch`)
Set to "true" to disable
**Default**: `false`
</ResponseField>
<ResponseField name="OVERRIDE_DNS" type="boolean">
Override system DNS settings (equivalent to `--override-dns`)
Set to "true" to enable
**Default**: `true`
</ResponseField>
<ResponseField name="TUNNEL_DNS" type="boolean">
Route DNS queries through the tunnel (equivalent to `--tunnel-dns`)
Set to "true" to enable
**Default**: `false`
</ResponseField>
<ResponseField name="MATCH_DOMAINS_DNS" type="string">
Optional whitelist of domains sent to the configured upstream DNS server
(equivalent to `--match_domains_dns`). When unset, all queries go to
upstream DNS.
</ResponseField>
<ResponseField name="PREFER_LOCAL_ROUTES" type="boolean">
When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel.
**Default**: `false`
</ResponseField>
<ResponseField name="DISABLE_RELAY" type="boolean">
Disable relay connections (equivalent to `--disable-relay`)
Set to "true" to disable
**Default**: `false`
</ResponseField>
<ResponseField name="CONFIG_FILE" type="string">
Set to the location of a JSON file to load secret values
</ResponseField>
### Loading secrets from files
You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
```
$ cat ~/.config/olm-client/config.json
{
"id": "spmzu8rbpzj1qq6",
"secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
"endpoint": "https://app.pangolin.net",
"org": "",
"userToken": "",
"mtu": 1280,
"dns": "8.8.8.8",
"upstreamDNS": ["8.8.8.8:53"],
"matchDomainsDNS": [],
"interface": "olm",
"logLevel": "INFO",
"enableApi": false,
"httpAddr": "",
"socketPath": "/var/run/olm.sock",
"pingInterval": "3s",
"pingTimeout": "5s",
"disableHolepunch": false,
"overrideDNS": true,
"tunnelDNS": false,
"disableRelay": false,
"tlsClientCert": "",
"preferLocalRoutes": false
}
```
This file is also written to when olm first starts up. So you do not need to run every time with --id and secret if you have run it once!
Default locations:
- **macOS**: `~/Library/Application Support/olm-client/config.json`
- **Windows**: `%PROGRAMDATA%\olm\olm-client\config.json`
- **Linux/Others**: `~/.config/olm-client/config.json`
### API
Olm can be started with a HTTP or socket API to configure and manage it. See the [API documentation](https://github.com/fosrl/olm/blob/main/API.md) for more details.
</Accordion>
</Accordion>
content/docs/manage/clients/credentials.mdx
+5 -5
View File
@@ -1,12 +1,12 @@
---
title: "Client Credentials"
description: "Understanding how client credentials work and how they can be rotated & regenerated"
title: "Machine Client Credentials"
description: "How machine clients authenticate with an ID and secret, and how to rotate or regenerate those credentials"
---
## 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.
Machine client credentials are only for [machine clients](/manage/clients/understanding-clients#machines): servers and automated systems that connect without a person present. Each machine client is provisioned with a unique identifier (ID), secret, and endpoint. The client uses those three values 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.
User devices do not use machine client credentials. A person logs in with their Pangolin user credentials, or with an external identity provider, through the web login flow in the client. That login creates a session tied to their account. The session is not shown in the dashboard and cannot be regenerated. To disconnect a user device, have the user log out in the client.
### ID
@@ -40,7 +40,7 @@ The endpoint is how the client knows which server to connect to. This is the ful
This is an [Enterprise Edition](/self-host/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.
Machine 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.
content/docs/manage/clients/fingerprinting.mdx
+1 -1
View File
@@ -1,5 +1,5 @@
---
title: 'Client Fingerprinting'
title: 'Client Fingerprinting and Posture'
description:
'A summary of device information that is collected during the connection'
---
content/docs/manage/clients/install-client.mdx
-460
View File
@@ -1,460 +0,0 @@
---
title: "Install Clients"
description: "Install native clients for Mac, Windows, and Linux"
---
## Windows
- [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.
### Installation Steps
1. **Download and install the Pangolin client**
Download and install the Pangolin client using the official .msi installer from the download button above.
2. **Launch Pangolin**
Open Pangolin from the Start menu or the shortcut on your Desktop.
3. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
- Click the Pangolin icon in the task bar's system tray and select Log in.
## Mac
- [Pangolin for macOS Installer](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.
### Installation Steps
1. **Download and install the Pangolin client**
Download and install the Pangolin client using the official .dmg installer from the download button above.
- Open the downloaded .dmg file
- Drag and drop Pangolin.app into your Applications folder
2. **Launch Pangolin**
Open Pangolin from your Applications folder.
3. **Install the VPN configuration**
Follow the Pangolin onboarding flow, which will guide you to install the Pangolin VPN configuration.
- Select Open System Settings on startup when it asks to install a network extension.
- In System Settings, under General > Login Items & Extension > By Category > Network Extensions, ensure that Pangolin.app is toggled on.
- Select Allow when Pangolin asks to add a VPN configuration.
4. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
- Click the Pangolin icon in the menu bar and select Log in.
## iOS/iPadOS
- [Pangolin on the App Store](https://apps.apple.com/us/app/pangolin-client/id6757407406) - This is the official page to download the latest Pangolin app for iOS and iPadOS.
### Installation Steps
1. **Download and install the Pangolin app**
Download and install the Pangolin app from the App Store using the link above.
2. **Launch Pangolin**
Open the Pangolin app from your home screen.
3. **Install the VPN configuration**
When prompted, allow Pangolin to add VPN configurations to your device.
You may be asked to enter your device passcode or use Face ID/Touch ID to authorize the VPN configuration.
4. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
5. **Connect to Pangolin**
Tap the Connect button to establish a VPN connection.
## Android
- [Pangolin on Google Play](https://play.google.com/store/apps/details?id=net.pangolin.Pangolin) - This is the official page to download the latest Pangolin app for Android devices.
- [All Versions](https://github.com/fosrl/android/releases) - The releases section of this repository contains release notes and download artifacts for the latest version and all older versions.
### Installation Steps
1. **Download and install the Pangolin app**
Download and install the Pangolin app from the Google Play Store using the link above.
2. **Launch Pangolin**
Open the Pangolin app from your app drawer or home screen.
3. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
4. **Connect to Pangolin**
Tap the Connect button to establish a VPN connection. On the first connection, you may be prompted to allow the VPN connection.
## Pangolin CLI (Linux, macOS, Windows)
Pangolin CLI is the recommended way to run a client using a command line interface on Mac and Linux.
Pangolin CLI can run on Windows, but the CLI VPN functionality is not supported. You can still use Pangolin CLI on Windows for SSH alongside the Windows GUI client.
Pangolin CLI supports running as user device with authentication or a machine client.
### Install
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
```
On Windows, [download the latest installer](https://github.com/fosrl/cli/releases/latest/download/pangolin-cli_windows_installer.msi), or choose to install the CLI from menu bar of the desktop app by choosing the "Install Pangolin CLI" option.
Binaries for all platforms are available in the [GitHub releases](https://github.com/fosrl/cli/releases) for ARM and AMD64 (x86_64) architectures.
### Installation Steps
1. **Download and install the Pangolin client**
Install Pangolin using the installation script:
```bash
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
```
2. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance:
```bash
pangolin login
```
3. **Start Pangolin**
When logged in as a Pangolin user, connect by running:
```bash
pangolin up
```
To launch a machine client without logging in, use your client credentials:
```bash
pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
```
<Tip>
The `--attach` flag runs the client in the foreground instead of spawning it as a background process.
</Tip>
Pangolin CLI can be installed as a systemd service or run in a container. See the sections below for advanced setups.
## Machine Clients
Machine clients don't require a login and are built for machines like services to be able to connect to private resources. Like sites, they have an ID and a secret.
### Run as a Service
The CLI can install and manage a service on your host machine for you. This supports Windows services, MacOS's launchd, and Linux's systemd to create a persistent site connection from that host.
```bash
sudo pangolin service install client \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://app.pangolin.net
```
Check the service status:
```bash
sudo pangolin service status client
```
And to get the logs:
```bash
sudo pangolin service logs client
```
### Systemd Service (Pangolin CLI)
Create a basic systemd service for Pangolin CLI:
```ini title="/etc/systemd/system/pangolin-cli.service"
[Unit]
Description=Pangolin CLI
After=network.target
[Service]
ExecStart=/usr/local/bin/pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
Restart=always
User=root
[Install]
WantedBy=multi-user.target
```
<Warning>
Make sure to move the binary to `/usr/local/bin/pangolin` before creating the service. Replace `{client_id}`, `{client_secret}`, and `{endpoint_url}` with your machine client credentials and endpoint.
</Warning>
### Docker (Pangolin CLI)
You can run Pangolin CLI with Docker Compose. For example, a service in your `docker-compose.yml` might look like this using environment variables (recommended):
```yaml
services:
pangolin-cli:
image: fosrl/pangolin-cli:latest
container_name: pangolin-cli
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
- PANGOLIN_ENDPOINT=https://app.pangolin.net
- CLIENT_ID=5n52gnzfgl3tdox
- CLIENT_SECRET=wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9
```
You can also pass the CLI args to the container:
```yaml
services:
pangolin-cli:
image: fosrl/pangolin-cli:latest
container_name: pangolin-cli
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
command:
- up
- --id
- "5n52gnzfgl3tdox"
- --secret
- "wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9"
- --endpoint
- https://app.pangolin.net
- --attach
```
**Docker Configuration Notes:**
- `network_mode: host` brings the Pangolin CLI network interface to the host system, allowing the WireGuard tunnel to function properly
- `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces
- `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces
<Note>
Deploying in Kubernetes? See [Kubernetes Deployment](/manage/clients/kubernetes/deployment) for a basic guide, including how to run the client as a sidecar container.
</Note>
## Olm (Advanced)
<Accordion title="Olm CLI (advanced use only)">
Olm CLI is the most basic form of a client. All other clients implement Olm under the hood in some form.
If you're looking for a CLI interface for a client, we recommend using Pangolin CLI where possible.
Olm CLI is mainly only used for machine clients. Though the Pangolin CLI can also be used for machine clients, use Pangolin CLI if you expect to log in as a user.
### Binary Installation (Linux)
#### Quick Install (Recommended)
Use this command to automatically install Olm. It detects your system architecture automatically and always pulls the latest version, adding Olm to your PATH:
```bash
curl -fsSL https://static.pangolin.net/get-olm.sh | bash
```
#### Windows
If you would like to use Olm on Windows, wintun.dll is required. Please use latest installer from [GitHub releases](https://github.com/fosrl/olm/releases/latest).
#### 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
```
### 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>
### Docker
You can also run it with Docker compose. For example, a service in your `docker-compose.yml` might look like this using environment vars (recommended):
```yaml
services:
olm:
image: fosrl/olm
container_name: olm
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
- PANGOLIN_ENDPOINT=https://example.com
- OLM_ID=31frd0uzbjvp721
- OLM_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
```
You can also pass the CLI args to the container:
```yaml
services:
olm:
image: fosrl/olm
container_name: olm
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
command:
- --id 31frd0uzbjvp721
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
- --endpoint https://example.com
```
**Docker Configuration Notes:**
- `network_mode: host` brings the olm network interface to the host system, allowing the WireGuard tunnel to function properly
- `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces
- `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces
### Windows Service
On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to install and run the service to function like a cli tool.
Minimum Windows version: Windows 10
#### Service Management Commands
```
# Install the service
olm.exe install
# Start the service
olm.exe start
# Stop the service
olm.exe stop
# Check service status
olm.exe status
# Remove the service
olm.exe remove
# Run in debug mode (console output) with our without id & secret
olm.exe debug
# Show help
olm.exe help
```
Note running the service requires credentials in `%PROGRAMDATA%\olm\olm-client\config.json`.
#### Service Configuration
When running as a service, Olm will read configuration from environment variables or you can modify the service to include command-line arguments:
1. Install the service: `olm.exe install`
2. Set the credentials in `%PROGRAMDATA%\olm\olm-client\config.json`. Hint: if you run olm once with --id and --secret this file will be populated!
3. Start the service: `olm.exe start`
#### Service Logs
When running as a service, logs are written to:
- Windows Event Log (Application log, source: "OlmWireguardService")
- Log files in: `%PROGRAMDATA%\olm\logs\olm.log`
You can view the Windows Event Log using Event Viewer or PowerShell:
```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. On Proxmox see below.
- **Linux**: May require root privileges or specific capabilities to create tun interfaces.
- **macOS**: May require additional permissions for network interface creation.
#### LXC Proxmox
1. Create your LXC container.
2. Go to the Resources tab of the container.
3. Select Add. Then select Device Passthrough.
4. On the Add Device prompt, enter dev/net/tun in the Device Path field and select Add.
5. If the container is running, shut it down and start it up again.
Once /dev/net/tun is available, the olm can run within the LXC.
</Accordion>
content/docs/manage/clients/kubernetes/deployment.mdx
+9 -9
View File
@@ -17,10 +17,10 @@ This is useful when a workload running in your cluster (a batch job, an internal
## Prerequisites
- A machine client created in Pangolin, with its `Client ID` and `Client Secret`. See [Install Clients](/manage/clients/install-client).
- A machine client created in Pangolin, with its `Client ID` and `Client Secret`. See [Pangolin CLI](/manage/clients/platforms/cli#machine-clients).
- A Kubernetes cluster where you can grant the `NET_ADMIN` capability and access to `/dev/net/tun`.
## Step 1: Create a Secret for client credentials
## Step 1: Create a Secret for machine client credentials
```bash
kubectl create secret generic pangolin-client \
@@ -77,7 +77,7 @@ spec:
Setting `restartPolicy: Always` on the container makes it a [native sidecar](https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/) on Kubernetes 1.29+. It starts before the main container and Kubernetes keeps it running for the life of the Pod. On older clusters, omit `restartPolicy` and the container runs as a regular container instead — the tunnel still comes up, but startup ordering isn't guaranteed.
</Note>
The `pangolin-cli` image runs `pangolin up --attach` by default, which launches the client as a machine client using the `CLIENT_ID`/`CLIENT_SECRET` from the Secret and keeps it in the foreground so the container stays alive. See [Install Clients](/manage/clients/install-client#pangolin-cli-linux-macos-windows) for the full list of environment variables and flags.
The `pangolin-cli` image runs `pangolin up --attach` by default, which launches the client as a machine client using the `CLIENT_ID`/`CLIENT_SECRET` from the Secret and keeps it in the foreground so the container stays alive. See [Pangolin CLI](/manage/clients/platforms/cli#docker-pangolin-cli) for the environment variables and flags.
## Step 3: Apply and verify
@@ -114,13 +114,13 @@ Each Pod running the sidecar connects as the same machine client. If you scale a
## Next steps
<CardGroup cols={2}>
<Card title="Install Clients" href="/manage/clients/install-client" icon="download">
Review Pangolin CLI and Olm installation options, including Docker.
<Card title="Pangolin CLI" href="/manage/clients/platforms/cli" icon="terminal">
Install, configure, and run the CLI, including Docker.
</Card>
<Card title="Configure Clients" href="/manage/clients/configure-client" icon="sliders">
Review client configuration options.
<Card title="Platforms" href="/manage/clients/platforms" icon="sliders">
Shared client preferences for DNS and routing.
</Card>
<Card title="Credentials" href="/manage/clients/credentials" icon="key">
Manage machine client credentials.
<Card title="Machine Client Credentials" href="/manage/clients/credentials" icon="key">
Rotate and regenerate the ID and secret used by a machine client.
</Card>
</CardGroup>
content/docs/manage/clients/nat-traversal.mdx
+16 -43
View File
@@ -37,52 +37,25 @@ If you use [Pangolin Cloud](https://app.pangolin.net/auth/signup) and want relay
## Check Whether a Site Is Relayed
You can confirm whether a connection is direct or relayed from the client.
You can confirm whether a connection is direct or relayed from the client. GUI clients and the CLI both report a connection value:
- `Direct`: hole-punched connection to the site
- `Relay`: traffic is relayed through your Pangolin server
- `Local`: the site is on the same local network as the client
### GUI clients
In a GUI client (Mac, Windows, Android, or iOS/iPadOS), open **Preferences**, go to the **Status** tab, and switch to the **JSON** view. Under each connected site in the `peers` object, check `isRelay` and `isLocal`:
In a GUI client (Mac, Windows, Android, or iOS/iPadOS), open **Preferences** and go to the **Status** tab. The formatted view lists each site and its status. Click a site to open its details and read **Connection**.
- `isRelay: false` — direct hole-punched connection to the site
- `isRelay: true` — traffic is relayed through your Pangolin server
- `isLocal: true` — the site is on the same local network as the client
- `isLocal: false` — the site is on a different network
<Frame caption="Site details from the Status tab. Connection is Relay for this site.">
<img src="/images/client-site-status.png" alt="Site details for Prod VPC Bastion us-east-1 showing Status Connected and Connection Relay" />
</Frame>
Example (values obfuscated):
```json
{
"agent": "Pangolin macOS",
"connected": true,
"orgId": "org_example123",
"peers": {
"1001": {
"connected": true,
"endpoint": "203.0.113.10:51820",
"isRelay": false,
"isLocal": true,
"name": "Office Network",
"siteId": 1001
},
"1002": {
"connected": true,
"endpoint": "198.51.100.5:21820",
"isRelay": true,
"isLocal": false,
"name": "Remote Lab",
"siteId": 1002
}
},
"registered": true,
"version": "0.8.4"
}
```
In this example, **Office Network** is connected directly (`isRelay: false`) and **Remote Lab** is relayed (`isRelay: true`).
In this example, **Prod VPC Bastion us-east-1** is connected through the relay.
### CLI
On Linux or when using [Pangolin CLI](/manage/clients/install-client), run `pangolin status`. The **CONNECTION** column shows whether each site is connected directly (`Direct`) or via relay (`Relay`):
On Linux or when using [Pangolin CLI](/manage/clients/platforms/cli), run `pangolin status`. The **CONNECTION** column shows the same value for each site:
```bash
pangolin status
@@ -92,7 +65,7 @@ Pangolin CLI 0.10.1 Connected org_example123
SITE ENDPOINT STATUS LAST SEEN CONNECTION
Office Network 203.0.113.10:51820 Connected 1s ago Direct
Remote Lab 198.51.100.5:21820 Connected 1s ago Relay
Worklab Lab 192.168.1.33:23423 Connected 1s ago Local
Worklab Lab 192.168.1.33:23423 Connected 1s ago Local
```
Use either view when troubleshooting hole punching or verifying that configuration changes took effect.
@@ -117,9 +90,9 @@ Another option is to keep the Pangolin Site listening for client connections on
</Accordion>
<Accordion title="How do I check whether a site is relayed?">
**GUI clients:** Open **Preferences**, go to the **Status** tab, and switch to the **JSON** view. Each entry under `peers` includes an `isRelay` field—`false` for direct, `true` when relayed.
**GUI clients:** Open **Preferences**, go to the **Status** tab, and click a site. **Connection** is `Relay` when the site is relayed, and `Direct` or `Local` when the path is direct.
**CLI:** Run `pangolin status` and check the **RELAY** column for each site.
**CLI:** Run `pangolin status` and check the **CONNECTION** column for each site.
See [Check Whether a Site Is Relayed](#check-whether-a-site-is-relayed) for examples.
</Accordion>
@@ -133,11 +106,11 @@ Another option is to keep the Pangolin Site listening for client connections on
</Accordion>
<Accordion title="Can I force direct connections only?">
You can disable relaying with `disable-relay` in the client config or `--disable-relay` / `DISABLE_RELAY=true` on CLI clients. If hole punching fails, the client will not fall back to a relay and the site may not connect. See [Configure Clients](/manage/clients/configure-client) for details.
You can disable relaying with `disable-relay` in the client config or `--disable-relay` / `DISABLE_RELAY=true` on CLI clients. If hole punching fails, the client will not fall back to a relay and the site may not connect. See [Olm](/manage/clients/platforms/olm) for details.
</Accordion>
<Accordion title="Can I always relay and skip hole punching?">
Yes. Set `disable-holepunch` in the client config or use `--disable-holepunch` / `DISABLE_HOLEPUNCH=true` on CLI clients to skip hole punching and connect through the relay path. See [Configure Clients](/manage/clients/configure-client) for details.
Yes. Set `disable-holepunch` in the client config or use `--disable-holepunch` / `DISABLE_HOLEPUNCH=true` on CLI clients to skip hole punching and connect through the relay path. See [Olm](/manage/clients/platforms/olm) for details.
</Accordion>
<Accordion title="Does relayed traffic go through Pangolin Cloud?">
content/docs/manage/clients/platforms/android.mdx
+66
View File
@@ -0,0 +1,66 @@
---
title: "Android"
description: "Install, configure, and update the Pangolin app for Android"
---
## Install
- [Pangolin on Google Play](https://play.google.com/store/apps/details?id=net.pangolin.Pangolin) - This is the official page to download the latest Pangolin app for Android devices.
- [All Versions](https://github.com/fosrl/android/releases) - The releases section of this repository contains release notes and download artifacts for the latest version and all older versions.
### Installation Steps
1. **Download and install the Pangolin app**
Download and install the Pangolin app from the Google Play Store using the link above.
2. **Launch Pangolin**
Open the Pangolin app from your app drawer or home screen.
3. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
4. **Connect to Pangolin**
Tap the Connect button to establish a VPN connection. On the first connection, you may be prompted to allow the VPN connection.
## Configure
<Note>
DNS, MTU, and other preferences shared across clients are on [Platforms](/manage/clients/platforms#shared-preferences).
</Note>
### Show Persistent VPN Notification
When enabled, Pangolin keeps a status notification while connected. A temporary notification may still appear when connecting or recovering. Android's own VPN indicators are unaffected.
Leaving this on makes it less likely that Android will stop the connection while the app is in the background.
### Enable Log Collection
When enabled, tunnel logs are saved to a file that can be downloaded for troubleshooting. See [Client Logs](/manage/clients/client-logs).
### Battery Optimization
To ensure Pangolin functions correctly in the background on Android devices, it's recommended to disable battery optimization for the app. This prevents the operating system from restricting its background activities, which could lead to disconnections.
1. Open the **Settings** app on your Android device.
2. Navigate to **Apps & notifications** (or simply **Apps** on some devices).
3. Find and select the Pangolin app from the list of installed apps.
4. Tap on **App battery usage**.
5. Select **Allow background usage** and enable if disabled.
6. From the options menu, choose **Unrestricted**.
<Frame caption="Android Battery Optimization Settings">
<img
src="/images/android_battery.png"
alt="Android Battery Optimization Settings"
style={{ width: "250px", height: "auto" }}
/>
</Frame>
## Update
Updates are delivered through the Google Play Store. Release notes and older builds are in the [GitHub releases](https://github.com/fosrl/android/releases).
content/docs/manage/clients/platforms/cli.mdx
+331
View File
@@ -0,0 +1,331 @@
---
title: "Pangolin CLI"
description: "Install, configure, and update Pangolin CLI on Linux, macOS, and Windows"
---
Pangolin CLI is the recommended way to run a client using a command line interface on Mac and Linux.
Pangolin CLI can run on Windows, but the CLI VPN functionality is not supported. With [companion mode](#companion-mode), connect in the Windows app and use the CLI for commands such as SSH, on the same account, without a second login.
Pangolin CLI supports running as a user device with authentication or a machine client.
The CLI stores its own defaults in a config file.
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.
## Install
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
```
On Windows, [download the latest installer](https://github.com/fosrl/cli/releases/latest/download/pangolin-cli_windows_installer.msi), or choose to install the CLI from menu bar of the desktop app by choosing the "Install Pangolin CLI" option.
Binaries for all platforms are available in the [GitHub releases](https://github.com/fosrl/cli/releases) for ARM and AMD64 (x86_64) architectures.
### Installation Steps
1. **Download and install the Pangolin client**
Install Pangolin using the installation script:
```bash
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
```
2. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance:
```bash
pangolin login
```
3. **Start Pangolin**
When logged in as a Pangolin user, connect by running:
```bash
pangolin up
```
To launch a machine client without logging in, use your client credentials:
```bash
pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
```
<Tip>
The `--attach` flag runs the client in the foreground instead of spawning it as a background process.
</Tip>
### Machine Clients
Machine clients don't require a login and are built for machines like services to be able to connect to private resources. Like sites, they have an ID and a secret.
#### Run as a Service
The CLI can install and manage a service on your host machine for you. This supports Windows services, MacOS's launchd, and Linux's systemd to create a persistent site connection from that host.
```bash
sudo pangolin service install client \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://app.pangolin.net
```
Check the service status:
```bash
sudo pangolin service status client
```
And to get the logs:
```bash
sudo pangolin service logs client
```
#### Systemd Service (Pangolin CLI)
Create a basic systemd service for Pangolin CLI:
```ini title="/etc/systemd/system/pangolin-cli.service"
[Unit]
Description=Pangolin CLI
After=network.target
[Service]
ExecStart=/usr/local/bin/pangolin up --id {client_id} --secret {client_secret} --endpoint {endpoint_url} --attach
Restart=always
User=root
[Install]
WantedBy=multi-user.target
```
<Warning>
Make sure to move the binary to `/usr/local/bin/pangolin` before creating the service. Replace `{client_id}`, `{client_secret}`, and `{endpoint_url}` with your machine client credentials and endpoint.
</Warning>
#### Docker (Pangolin CLI)
You can run Pangolin CLI with Docker Compose. For example, a service in your `docker-compose.yml` might look like this using environment variables (recommended):
```yaml
services:
pangolin-cli:
image: fosrl/pangolin-cli:latest
container_name: pangolin-cli
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
- PANGOLIN_ENDPOINT=https://app.pangolin.net
- CLIENT_ID=5n52gnzfgl3tdox
- CLIENT_SECRET=wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9
```
You can also pass the CLI args to the container:
```yaml
services:
pangolin-cli:
image: fosrl/pangolin-cli:latest
container_name: pangolin-cli
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
command:
- up
- --id
- "5n52gnzfgl3tdox"
- --secret
- "wyael1dhftekp0ii2ni0ym6xczwjnwmucy2vr6u9kgkp8tw9"
- --endpoint
- https://app.pangolin.net
- --attach
```
**Docker Configuration Notes:**
- `network_mode: host` brings the Pangolin CLI network interface to the host system, allowing the WireGuard tunnel to function properly
- `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces
- `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces
<Note>
Deploying in Kubernetes? See [Kubernetes Deployment](/manage/clients/kubernetes/deployment) for a basic guide, including how to run the client as a sidecar container.
</Note>
## Companion Mode
Companion mode lets Pangolin CLI use the [Windows desktop app](/manage/clients/platforms/windows#companion-mode) for authentication and the tunnel. Log in and connect in the desktop app, then run CLI commands as that same account. You do not run `pangolin login` separately.
Companion mode is available on Windows only, and it requires Pangolin for Windows 0.11.0 or later. On macOS and Linux the CLI keeps its own login, and `pangolin companion` is not available. On Windows, companion mode is on by default.
### SSH through the desktop connection
1. Log in and connect with the Windows client.
2. SSH to a [private SSH resource](/manage/resources/private/ssh):
```bash
pangolin ssh username@alias
```
The CLI uses the desktop app's session and the tunnel that app already opened. `pangolin scp` works the same way.
### Commands
Enable companion mode. This takes effect on the next `pangolin` command:
```bash
pangolin companion enable
```
Turn it off and go back to a standalone CLI login:
```bash
pangolin companion disable
```
Check whether the desktop app session is ready:
```bash
pangolin companion status
```
When the desktop app is logged in, status looks like this:
```text
Companion mode: enabled
Client: Pangolin Windows
Ready: yes
```
If the desktop app is not logged in, status reports `Ready: no` and tells you to open Pangolin and log in.
With companion mode off, status reports:
```text
Companion mode: disabled
Auth source: standalone CLI
```
### What stays in the desktop app
While companion mode is on, the CLI reads accounts, the active organization, and exit node selection from the desktop app. Change those in the app.
These commands are blocked. The CLI tells you to use the desktop app, or to run `pangolin companion disable`:
- `pangolin login`
- `pangolin logout`
- `pangolin select account`
- `pangolin select org`
- `pangolin select exit-node`
Other commands, including `pangolin ssh` and `pangolin scp`, run with the desktop app's session. The desktop app has to be open and logged in. If it is not, the CLI asks you to start Pangolin for Windows 0.11.0 or later and log in.
You can also set `disable_companion_mode` in the [CLI config file](#config-file). `true` matches `pangolin companion disable`.
## Configure
<Note>
DNS, MTU, and other preferences shared across clients are on [Platforms](/manage/clients/platforms#shared-preferences).
</Note>
### Config File
The Pangolin CLI stores persistent settings in `~/.config/pangolin/config.json` on every platform. When the CLI is run with `sudo`, it uses the home directory of the user who invoked `sudo`, so the same file applies with and without it. Run `pangolin config path` to print the exact location.
<ResponseField name="Config" type="object">
JSON configuration for the Pangolin CLI stored in `config.json`.
<Expandable title="Config">
<ResponseField name="log_level" type="string">
Controls CLI log verbosity. Supported values are `debug` and `info`. If omitted, the default is `info`.
</ResponseField>
<ResponseField name="log_file" type="string">
Path of the client log file. If omitted, the default is `~/.config/pangolin/logs/client.log`. This key can only be changed by editing the file; it is not available through `pangolin config set`.
</ResponseField>
<ResponseField name="disable_update_check" type="boolean">
When true, the CLI does not check for new versions. If omitted, the default is `false`, except in builds distributed through a package manager, where it is `true`.
</ResponseField>
<ResponseField name="disable_companion_mode" type="boolean">
When true, the CLI uses its own standalone authentication instead of [companion mode](#companion-mode), where login, accounts, organizations, and exit node selection are managed by the Pangolin desktop app. If omitted, the default is `false`, so companion mode is on. This only applies on Windows.
</ResponseField>
<ResponseField name="companion_app_data_dirs" type="object">
Overrides where the CLI looks for the desktop app's data directory in companion mode. Accepts a `windows` and a `darwin` path. Most installations should leave this unset. This key can only be changed by editing the file.
</ResponseField>
<ResponseField name="session_cookie_name" type="string">
Overrides the cookie name used for the CLI's session token. Most deployments should leave this unset.
</ResponseField>
<ResponseField name="up.override_dns" type="boolean">
Default for `--override-dns`. When true, matches the [Enable Aliases (Override DNS)](/manage/clients/platforms#enable-aliases-override-dns) preference and lets the client take over DNS resolution for Pangolin resources. If omitted, the default is `true`.
</ResponseField>
<ResponseField name="up.tunnel_dns" type="boolean">
Default for `--tunnel-dns`. When true, matches the [DNS Over Tunnel](/manage/clients/platforms#dns-over-tunnel) preference and sends DNS queries through the Pangolin tunnel. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="up.upstream_dns" type="array of strings">
Default for `--upstream-dns`. Upstream DNS servers used when override/tunnel DNS is enabled. With `pangolin config set`, pass a comma-separated list such as `10.0.0.53,10.0.0.54`.
</ResponseField>
<ResponseField name="up.match_domains_dns" type="array of strings">
Default for `--match-domains`. Optional whitelist of domains sent to the configured upstream DNS server. When unset, all queries go to upstream DNS. When set, only matching queries use your Upstream DNS Server; all other requests use the system's DNS servers. Supports wildcards such as `*.proxy.internal`. With `pangolin config set`, pass a comma-separated list.
</ResponseField>
<ResponseField name="up.prefer_local_routes" type="boolean">
Default for `--prefer-local-routes`. When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="up.exit_node_takes_precedence" type="boolean">
Default for `--exit-node-takes-precedence`. When true, matches the [Exit Nodes Take Precedence Over Resources](/manage/clients/platforms#exit-nodes-take-precedence-over-resources) preference. While connected through an exit node, routes for other resources are not added and their aliases are not resolved, so all traffic flows through the exit node. If omitted, the default is `false`.
</ResponseField>
</Expandable>
</ResponseField>
## Update
Find the latest version in the [GitHub releases](https://github.com/fosrl/cli/releases).
### Automatic Updates
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>
content/docs/manage/clients/platforms/index.mdx
+92
View File
@@ -0,0 +1,92 @@
---
title: "Platforms"
description: "Install, configure, and update Pangolin clients, and shared DNS and routing preferences"
---
Each client has a preferences window. On Mac and Windows, click the menu bar or system tray icon and select "Preferences". In the mobile apps, open the "Preferences" screen.
The preferences below are shared across GUI clients. Install steps, settings that exist only on one client, and updates are documented on that client's page.
To troubleshoot connection or configuration issues, see [Client Logs](/manage/clients/client-logs) for how to view logs on each platform.
<CardGroup cols={2}>
<Card title="Windows" icon="windows" href="/manage/clients/platforms/windows">
Install the Windows client, set preferences, and update.
</Card>
<Card title="Mac" icon="apple" href="/manage/clients/platforms/mac">
Install the Mac client, set preferences, and update.
</Card>
<Card title="iOS/iPadOS" icon="apple" href="/manage/clients/platforms/ios">
Install the iOS app, set preferences, and update from the App Store.
</Card>
<Card title="Android" icon="android" href="/manage/clients/platforms/android">
Install the Android app, set preferences, and update from Google Play.
</Card>
<Card title="Pangolin CLI" icon="terminal" href="/manage/clients/platforms/cli">
Install the CLI on Linux, macOS, and Windows, including machine clients.
</Card>
<Card title="Olm" icon="terminal" href="/manage/clients/platforms/olm">
Deprecated command-line client. Use the Pangolin CLI instead.
</Card>
</CardGroup>
## Shared Preferences
The following preferences control how your client handles DNS resolution and network routing. They are available on Mac, Windows, Android, and iOS/iPadOS.
### Enable Aliases (Override DNS)
When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system's default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured Upstream DNS Server.
**When to use it**: This is required if you use aliases on resources in Pangolin. Aliases are friendly domain names assigned to private resources. Pangolin resolves these alias addresses over a private DNS server running in your client.
**How it works**: The client loops back to itself to resolve the alias. This is why you may see your DNS server as an unfamiliar address (often like `100.90.128.x`) when this is enabled. When a request doesn't resolve to a Pangolin resource and is bound for another website (like `google.com`), it falls back to your configured upstream DNS server.
### DNS Over Tunnel
When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server.
**When to use it**: Tunnel DNS is used when you want to send all DNS queries over the tunnel to a private resource made available in Pangolin. For example, if you host a DNS server like Pi-hole, you could define a private resource for Pi-hole on your remote network. Then in the Pangolin client, you would enable Tunnel DNS and set the host of the Pi-hole private resource as the tunnel DNS server.
**How it works**: When a request needs to be resolved, Pangolin sends it over the tunnel to the site of the private resource with your DNS server. You must enable DNS Over Tunnel and also set the upstream DNS server to your private DNS server.
This requires aliases "override DNS" to be enabled as well. This is because the client must take control of your DNS settings to route queries through the tunnel to your private DNS server.
<Warning>
You cannot use an alias name for your DNS server. It must be the IP address
of the resource. This is because it's pointing to the DNS server, so the DNS
server can't resolve itself.
</Warning>
### Primary Upstream DNS
This is the DNS server used to resolve queries that are not bound to a Pangolin alias when Override DNS or DNS Over Tunnel is enabled.
When left blank, **System DNS** is used. This pulls the existing configured system DNS settings and applies them to the tunnel. If Tunnel DNS is enabled and System DNS is used, requests will likely fail if the DNS server is not accessible over the tunnel.
### Secondary Upstream DNS
This is a fallback DNS server used to resolve queries that are not bound to a Pangolin alias when the primary server is unavailable. Ordering and priority of the server is not guaranteed, but it provides redundancy for DNS resolution. When left blank, **System DNS** is used, same as Primary Upstream DNS.
### Match Domains
By default, when match domains are not set, all DNS queries are sent to the configured upstream DNS server. Match domains let you whitelist which domains should be sent to the upstream DNS server. When match domains are set, only matching queries go to upstream DNS; all other requests use the system's DNS servers.
**When to use it**: When you have a private or corporate DNS server for specific domains (for example, `*.proxy.internal` or `corp.example.com`) and want everything else resolved by the system DNS as usual.
**How it works**: With no match domains configured, every query is forwarded to your Upstream DNS Server. With match domains set, only queries that match the list are forwarded upstream; the rest use the system's default DNS servers.
### Exit Nodes Take Precedence Over Resources
By default this is disabled. When a client is connected using an exit node other Pangolin resources will still be accessible and resolvable even on other sites not designated on the exit node resource. In this way Pangolin is still split tunneling these destinations. By enabling this setting, you are configuring Pangolin to ignore other resources outside of the exit node. All traffic will flow to and through the exit node resource and DNS aliases and subnets on other resources will no longer function.
### MTU
You can set the maximum transmission unit (MTU) for the client’s internal WireGuard interface. This value is client-wide: every site the client connects to must use the same MTU on the site side, or you can see fragmentation, failed handshakes, or unstable tunnels. See the **mtu** option on [Configure Sites](/manage/sites/configure-site) and set the same value on each of those sites.
<Warning>
Changing MTU is advanced and not recommended for most users. Only change it
when you have a specific, well-understood reason (for example, a constrained
network path or a requirement from your infrastructure team). If you do
change it, you must update every connected site to the identical value.
</Warning>
content/docs/manage/clients/platforms/ios.mdx
+58
View File
@@ -0,0 +1,58 @@
---
title: "iOS/iPadOS"
description: "Install, configure, and update the Pangolin app for iOS and iPadOS"
---
## Install
- [Pangolin on the App Store](https://apps.apple.com/us/app/pangolin-client/id6757407406) - This is the official page to download the latest Pangolin app for iOS and iPadOS.
### Installation Steps
1. **Download and install the Pangolin app**
Download and install the Pangolin app from the App Store using the link above.
2. **Launch Pangolin**
Open the Pangolin app from your home screen.
3. **Install the VPN configuration**
When prompted, allow Pangolin to add VPN configurations to your device.
You may be asked to enter your device passcode or use Face ID/Touch ID to authorize the VPN configuration.
4. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
5. **Connect to Pangolin**
Tap the Connect button to establish a VPN connection.
## Configure
<Note>
DNS, MTU, and other preferences shared across clients are on [Platforms](/manage/clients/platforms#shared-preferences).
</Note>
### Dynamic Island and Live Activity
When enabled, Pangolin shows connection status in the Dynamic Island and on the Lock Screen.
### Connect Automatically On
Choose when Pangolin may connect automatically. Tap **Connect** to enable on-demand for that interface; **Disconnect** disables it.
**Cellular** connects automatically while the device is on cellular.
**Wi-Fi** connects automatically while the device is on Wi-Fi. You can limit which networks that applies to:
- **Any Wi-Fi Network** connects on every Wi-Fi network.
- **Only these Wi-Fi Networks** connects only on the networks you list.
- **Except these Wi-Fi Networks** connects on every network except the ones you list.
## Update
Updates are delivered through the App Store.
content/docs/manage/clients/platforms/mac.mdx
+143
View File
@@ -0,0 +1,143 @@
---
title: "Mac"
description: "Install, configure, and update the Pangolin client for Mac"
---
## Install
- [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.
### Installation Steps
1. **Download and install the Pangolin client**
Download and install the Pangolin client using the official .dmg installer from the download button above.
- Open the downloaded .dmg file
- Drag and drop Pangolin.app into your Applications folder
2. **Launch Pangolin**
Open Pangolin from your Applications folder.
3. **Install the VPN configuration**
Follow the Pangolin onboarding flow, which will guide you to install the Pangolin VPN configuration.
- Select Open System Settings on startup when it asks to install a network extension.
- In System Settings, under General > Login Items & Extension > By Category > Network Extensions, ensure that Pangolin.app is toggled on.
- Select Allow when Pangolin asks to add a VPN configuration.
4. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
- Click the Pangolin icon in the menu bar and select Log in.
## Configure
<Note>
DNS, MTU, and other preferences shared across clients are on [Platforms](/manage/clients/platforms#shared-preferences).
</Note>
### Start at Login
When enabled, Pangolin opens automatically when you log in to your Mac.
### Connect Automatically On
Choose when Pangolin may connect automatically. **Connect** enables on-demand for that interface; **Disconnect** disables it.
**Ethernet** connects automatically while the Mac is on Ethernet.
**Wi-Fi** connects automatically while the Mac is on Wi-Fi. You can limit which networks that applies to:
- **Any Wi-Fi Network** connects on every Wi-Fi network.
- **Only these Wi-Fi Networks** connects only on the networks you list.
- **Except these Wi-Fi Networks** connects on every network except the ones you list.
### Config File
On Mac, the Pangolin GUI reads configuration from `~/Library/Application Support/Pangolin/pangolin.json`. Restart Pangolin after editing for changes to apply.
<ResponseField name="Config" type="object">
JSON configuration for the Mac Pangolin client stored in `pangolin.json`.
<Expandable title="Config">
<ResponseField name="dnsOverrideEnabled" type="boolean">
When true, matches the [Enable Aliases (Override DNS)](/manage/clients/platforms#enable-aliases-override-dns) preference and lets the client take over DNS resolution for Pangolin resources.
</ResponseField>
<ResponseField name="dnsTunnelEnabled" type="boolean">
When true, matches the [DNS Over Tunnel](/manage/clients/platforms#dns-over-tunnel) preference and sends DNS queries through the Pangolin tunnel.
</ResponseField>
<ResponseField name="primaryDNSServer" type="string">
Primary upstream DNS server used when override/tunnel DNS is enabled.
</ResponseField>
<ResponseField name="secondaryDNSServer" type="string">
Optional secondary upstream DNS server used as a fallback when the primary is unavailable.
</ResponseField>
<ResponseField name="dnsMatchDomains" type="array of strings">
Optional whitelist of domains sent to the configured upstream DNS server. When unset, all queries go to upstream DNS. When set, only matching queries use your Upstream DNS Server; all other requests use the system's DNS servers. Supports wildcards such as `*.proxy.internal`.
</ResponseField>
<ResponseField name="exitNodeTakesPrecedence" type="boolean">
When true, matches the [Exit Nodes Take Precedence Over Resources](/manage/clients/platforms#exit-nodes-take-precedence-over-resources) preference. While connected through an exit node, routes for other resources are not added and their aliases are not resolved, so all traffic flows through the exit node. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="tunnelMTU" type="integer">
MTU for the internal WireGuard interface. Changing this is advanced and not recommended unless you have a clear reason; if you set a non-default value, configure the same MTU on every site this client connects to. See [Configure Sites](/manage/sites/configure-site).
</ResponseField>
<ResponseField name="onDemandWiFiEnabled" type="boolean">
When true, matches the **Wi-Fi** option under **Connect Automatically On** and connects on demand whenever the Mac is on Wi-Fi. Use `onDemandSSIDOption` and `onDemandSSIDs` to limit this to specific networks. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="onDemandNonWiFiEnabled" type="boolean">
When true, matches the **Ethernet** option under **Connect Automatically On** and connects on demand whenever the Mac is on Ethernet. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="onDemandSSIDOption" type="string">
Which Wi-Fi networks on-demand applies to when `onDemandWiFiEnabled` is true. Supported values are `any` (**Any Wi-Fi Network**), `only` (**Only these Wi-Fi Networks**, the names in `onDemandSSIDs`), and `except` (**Except these Wi-Fi Networks**). If omitted, or if `onDemandSSIDs` is empty, the default is `any`.
</ResponseField>
<ResponseField name="onDemandSSIDs" type="array of strings">
Wi-Fi network names (SSIDs) used by the `only` and `except` modes of `onDemandSSIDOption`.
</ResponseField>
<ResponseField name="autoUpdateChecksEnabled" type="boolean">
When true, periodically check for updates in the background. When false, automatic checks are off; users can still use **Check for Updates**. If omitted, the client default applies (may prompt the user on second launch). Enabling checks without `autoDownloadUpdatesEnabled` still surfaces the update UI when a new version exists. Intended for admin / MDM provisioning so config stays the source of truth over user toggles.
</ResponseField>
<ResponseField name="autoDownloadUpdatesEnabled" type="boolean">
When true, download updates silently when found and stage install for quit/relaunch. When false, show the normal update dialog instead of silent download. Silent download does not replace the running app mid-session; the update installs on quit (and relaunches), so long-running menu bar sessions may keep a staged update until quit. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="updateCheckIntervalSeconds" type="integer">
How often automatic checks run, in seconds. Values below `3600` (1 hour) are clamped to `3600`. Only matters when `autoUpdateChecksEnabled` is true. If omitted, the default is `86400` (24 hours).
</ResponseField>
<ResponseField name="sessionCookieName" type="string">
Overrides the cookie name the session token is sent and read under. Most deployments should leave this unset.
</ResponseField>
</Expandable>
</ResponseField>
## Update
### Automatic Updates
The Mac client periodically checks for updates in the background. When an update is available, it requests permission to update. You can also check for updates from the menu bar, or by restarting the application.
Once you accept the update, the client downloads the latest version and replaces itself.
### Manual Updates
Find the latest version in the [GitHub releases](https://github.com/fosrl/apple/releases).
You can download the latest installer and run it again to install the latest version. Visit [https://pangolin.net/downloads](https://pangolin.net/downloads) for the official installer.
content/docs/manage/clients/platforms/olm.mdx
+570
View File
@@ -0,0 +1,570 @@
---
title: "Olm (Deprecated)"
description: "Deprecated command-line client for machine connections"
---
<Tip>
We recommend using the Pangolin CLI for both user and machine clients if
you're looking for a CLI interface. Olm is the underlying client for the
Pangolin CLI.
</Tip>
Olm is a command-line client for connecting machine clients in Pangolin. You can configure it using command-line flags, environment variables, or a configuration file.
## Install
### Binary Installation (Linux)
#### Quick Install (Recommended)
Use this command to automatically install Olm. It detects your system architecture automatically and always pulls the latest version, adding Olm to your PATH:
```bash
curl -fsSL https://static.pangolin.net/get-olm.sh | bash
```
#### Windows
If you would like to use Olm on Windows, wintun.dll is required. Please use latest installer from [GitHub releases](https://github.com/fosrl/olm/releases/latest).
#### 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
```
### 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>
### Docker
You can also run it with Docker compose. For example, a service in your `docker-compose.yml` might look like this using environment vars (recommended):
```yaml
services:
olm:
image: fosrl/olm
container_name: olm
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
- PANGOLIN_ENDPOINT=https://example.com
- OLM_ID=31frd0uzbjvp721
- OLM_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
```
You can also pass the CLI args to the container:
```yaml
services:
olm:
image: fosrl/olm
container_name: olm
restart: unless-stopped
network_mode: host
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
command:
- --id 31frd0uzbjvp721
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
- --endpoint https://example.com
```
**Docker Configuration Notes:**
- `network_mode: host` brings the olm network interface to the host system, allowing the WireGuard tunnel to function properly
- `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces
- `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces
### Windows Service
On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to install and run the service to function like a cli tool.
Minimum Windows version: Windows 10
#### Service Management Commands
```
# Install the service
olm.exe install
# Start the service
olm.exe start
# Stop the service
olm.exe stop
# Check service status
olm.exe status
# Remove the service
olm.exe remove
# Run in debug mode (console output) with our without id & secret
olm.exe debug
# Show help
olm.exe help
```
Note running the service requires credentials in `%PROGRAMDATA%\olm\olm-client\config.json`.
#### Service Configuration
When running as a service, Olm will read configuration from environment variables or you can modify the service to include command-line arguments:
1. Install the service: `olm.exe install`
2. Set the credentials in `%PROGRAMDATA%\olm\olm-client\config.json`. Hint: if you run olm once with --id and --secret this file will be populated!
3. Start the service: `olm.exe start`
#### Service Logs
When running as a service, logs are written to:
- Windows Event Log (Application log, source: "OlmWireguardService")
- Log files in: `%PROGRAMDATA%\olm\logs\olm.log`
You can view the Windows Event Log using Event Viewer or PowerShell:
```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 [service management commands](#service-management-commands) to manage it and run it in the background.
- **LXC containers**: Need to be configured to allow tun access. On Proxmox see below.
- **Linux**: May require root privileges or specific capabilities to create tun interfaces.
- **macOS**: May require additional permissions for network interface creation.
#### LXC Proxmox
1. Create your LXC container.
2. Go to the Resources tab of the container.
3. Select Add. Then select Device Passthrough.
4. On the Add Device prompt, enter dev/net/tun in the Device Path field and select Add.
5. If the container is running, shut it down and start it up again.
Once /dev/net/tun is available, the olm can run within the LXC.
## Configure
<Note>
DNS, MTU, and other preferences shared across clients are on [Platforms](/manage/clients/platforms#shared-preferences).
</Note>
### Flags
<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 the Pangolin server resides for websocket connections.
**Example**: `https://pangolin.example.com`
</ResponseField>
<ResponseField name="org" type="string">
Organization ID to connect to.
</ResponseField>
<ResponseField name="user-token" type="string">
User authentication token.
</ResponseField>
<ResponseField name="mtu" type="integer">
MTU for the internal WireGuard interface.
**Default**: `1280`
</ResponseField>
<ResponseField name="dns" type="string">
DNS server to use to resolve the endpoint.
**Default**: `8.8.8.8`
</ResponseField>
<ResponseField name="upstream-dns" type="string">
Upstream DNS server(s), comma-separated.
**Default**: `8.8.8.8:53`
</ResponseField>
<ResponseField name="match-domains-dns" type="string">
FQDN wildcard patterns (using `*` and `?` wildcards, comma-separated, e.g. `*.proxy.internal,*.host-0?.autoco.internal`) to check against local records/upstream DNS. Queries for domains that don't match any pattern are sent directly to the host's own system DNS servers instead of being resolved as Pangolin resources.
**Default**: (empty, matches every domain)
</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="interface" type="string">
Name of the WireGuard interface.
**Default**: `olm`
</ResponseField>
<ResponseField name="enable-api" type="boolean">
Enable API server for receiving connection requests.
**Default**: `false`
</ResponseField>
<ResponseField name="http-addr" type="string">
HTTP server address (e.g., ':9452'). When unset, the HTTP API is not started and the socket API (see `socket-path`) is used instead.
**Default**: (not set)
</ResponseField>
<ResponseField name="socket-path" type="string">
Unix socket path (or named pipe on Windows).
**Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
</ResponseField>
<ResponseField name="disable-holepunch" type="boolean">
Disable hole punching.
**Default**: `false`
</ResponseField>
<ResponseField name="override-dns" type="boolean">
When enabled, the client uses custom DNS servers to resolve internal resources and aliases. This overrides your system's default DNS settings. Queries that cannot be resolved as a Pangolin resource will be forwarded to your configured Upstream DNS Server.
**Default**: `true`
</ResponseField>
<ResponseField name="tunnel-dns" type="boolean">
When enabled, DNS queries are routed through the tunnel for remote resolution. To ensure queries are tunneled correctly, you must define the DNS server as a Pangolin resource and enter its address as an Upstream DNS Server.
**Default**: `false`
</ResponseField>
<ResponseField name="match-domains-dns" type="string">
Optional comma-separated whitelist of domains sent to the configured
upstream DNS server. When unset, all queries go to upstream DNS. When set,
only matching queries use your Upstream DNS Server; all other requests use
the system's DNS servers. Supports wildcards such as `*.proxy.internal`.
</ResponseField>
<ResponseField name="disable-relay" type="boolean">
Disable relay connections.
**Default**: `false`
</ResponseField>
<ResponseField name="prefer-local-routes" type="boolean">
When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel.
**Default**: `false`
</ResponseField>
### 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>
<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="ORG" type="string">
Organization ID to connect to (equivalent to `--org`)
</ResponseField>
<ResponseField name="USER_TOKEN" type="string">
User authentication token (equivalent to `--user-token`)
</ResponseField>
<ResponseField name="MTU" type="integer">
MTU for the internal WireGuard interface (equivalent to `--mtu`)
**Default**: `1280`
</ResponseField>
<ResponseField name="DNS" type="string">
DNS server to use to resolve the endpoint (equivalent to `--dns`)
**Default**: `8.8.8.8`
</ResponseField>
<ResponseField name="UPSTREAM_DNS" type="string">
Upstream DNS server(s), comma-separated (equivalent to `--upstream-dns`)
**Default**: `8.8.8.8:53`
</ResponseField>
<ResponseField name="MATCH_DOMAINS_DNS" type="string">
FQDN wildcard patterns, comma-separated (equivalent to `--match-domains-dns`)
**Default**: (empty, matches every domain)
</ResponseField>
<ResponseField name="LOG_LEVEL" type="string">
Log level (equivalent to `--log-level`)
**Default**: `INFO`
</ResponseField>
<ResponseField name="PING_INTERVAL" type="string">
Interval for pinging the server (equivalent to `--ping-interval`)
**Default**: `3s`
</ResponseField>
<ResponseField name="PING_TIMEOUT" type="string">
Timeout for each ping (equivalent to `--ping-timeout`)
**Default**: `5s`
</ResponseField>
<ResponseField name="INTERFACE" type="string">
Name of the WireGuard interface (equivalent to `--interface`)
**Default**: `olm`
</ResponseField>
<ResponseField name="ENABLE_API" type="boolean">
Enable API server for receiving connection requests (equivalent to `--enable-api`)
Set to "true" to enable
**Default**: `false`
</ResponseField>
<ResponseField name="HTTP_ADDR" type="string">
HTTP server address (equivalent to `--http-addr`)
**Default**: (not set)
</ResponseField>
<ResponseField name="SOCKET_PATH" type="string">
Unix socket path or Windows named pipe (equivalent to `--socket-path`)
**Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
</ResponseField>
<ResponseField name="DISABLE_HOLEPUNCH" type="boolean">
Disable hole punching (equivalent to `--disable-holepunch`)
Set to "true" to disable
**Default**: `false`
</ResponseField>
<ResponseField name="OVERRIDE_DNS" type="boolean">
Override system DNS settings (equivalent to `--override-dns`)
Set to "true" to enable
**Default**: `true`
</ResponseField>
<ResponseField name="TUNNEL_DNS" type="boolean">
Route DNS queries through the tunnel (equivalent to `--tunnel-dns`)
Set to "true" to enable
**Default**: `false`
</ResponseField>
<ResponseField name="MATCH_DOMAINS_DNS" type="string">
Optional whitelist of domains sent to the configured upstream DNS server
(equivalent to `--match_domains_dns`). When unset, all queries go to
upstream DNS.
</ResponseField>
<ResponseField name="PREFER_LOCAL_ROUTES" type="boolean">
When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel.
**Default**: `false`
</ResponseField>
<ResponseField name="DISABLE_RELAY" type="boolean">
Disable relay connections (equivalent to `--disable-relay`)
Set to "true" to disable
**Default**: `false`
</ResponseField>
<ResponseField name="CONFIG_FILE" type="string">
Set to the location of a JSON file to load secret values
</ResponseField>
### Config File
You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
```
$ cat ~/.config/olm-client/config.json
{
"id": "spmzu8rbpzj1qq6",
"secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
"endpoint": "https://app.pangolin.net",
"org": "",
"userToken": "",
"mtu": 1280,
"dns": "8.8.8.8",
"upstreamDNS": ["8.8.8.8:53"],
"matchDomainsDNS": [],
"interface": "olm",
"logLevel": "INFO",
"enableApi": false,
"httpAddr": "",
"socketPath": "/var/run/olm.sock",
"pingInterval": "3s",
"pingTimeout": "5s",
"disableHolepunch": false,
"overrideDNS": true,
"tunnelDNS": false,
"disableRelay": false,
"tlsClientCert": "",
"preferLocalRoutes": false
}
```
This file is also written to when olm first starts up. So you do not need to run every time with --id and secret if you have run it once!
Default locations:
- **macOS**: `~/Library/Application Support/olm-client/config.json`
- **Windows**: `%PROGRAMDATA%\olm\olm-client\config.json`
- **Linux/Others**: `~/.config/olm-client/config.json`
### API
Olm can be started with a HTTP or socket API to configure and manage it. See the [API documentation](https://github.com/fosrl/olm/blob/main/API.md) for more details.
## Update
Re-run the install script to pull the latest version:
```bash
curl -fsSL https://static.pangolin.net/get-olm.sh | bash
```
On Windows, download the latest installer from the [GitHub releases](https://github.com/fosrl/olm/releases/latest). You can also download a binary for your system from the [GitHub releases](https://github.com/fosrl/olm/releases) and replace the existing binary.
content/docs/manage/clients/platforms/windows.mdx
+173
View File
@@ -0,0 +1,173 @@
---
title: "Windows"
description: "Install, configure, and update the Pangolin client for Windows"
---
## Install
- [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.
### Installation Steps
1. **Download and install the Pangolin client**
Download and install the Pangolin client using the official .msi installer from the download button above.
2. **Launch Pangolin**
Open Pangolin from the Start menu or the shortcut on your Desktop.
3. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
- Click the Pangolin icon in the task bar's system tray and select Log in.
## Companion Mode
Companion mode lets [Pangolin CLI](/manage/clients/platforms/cli) use this app's login and tunnel. Sign in and connect here, then run CLI commands as that same account. You do not run `pangolin login` again.
Companion mode is available on Windows only. It requires Pangolin for Windows 0.11.0 or later, and it is on by default once the CLI is installed.
1. Log in with the Windows client and connect.
2. Install Pangolin CLI if it is not already installed. From the Pangolin menu bar, choose **Install Pangolin CLI**, or follow the [CLI install steps](/manage/clients/platforms/cli).
3. Run CLI commands in a terminal. For example, open SSH to a [private SSH resource](/manage/resources/private/ssh):
```bash
pangolin ssh username@alias
```
The CLI follows the account, organization, and exit node selected in the desktop app. Change those in the app. While companion mode is on, `pangolin login`, `pangolin logout`, and `pangolin select` for account, organization, or exit node are blocked.
The desktop app has to be open and logged in. If it is not, the CLI asks you to start Pangolin and log in.
Commands to check status or turn companion mode off are on the [CLI companion mode section](/manage/clients/platforms/cli#companion-mode).
## Configure
<Note>
DNS, MTU, and other preferences shared across clients are on [Platforms](/manage/clients/platforms#shared-preferences).
</Note>
### Start at Login
When enabled, Pangolin starts when you sign in to Windows.
### Connect at Start
When enabled, the tunnel connects whenever Pangolin starts. This also opens Pangolin at sign-in.
### Config File
On Windows, the Pangolin GUI reads configuration from two `pangolin.json` files:
- User config: `%LOCALAPPDATA%\Pangolin\pangolin.json` (for example, `C:\Users\USER\AppData\Local\Pangolin\pangolin.json`)
- Global config: `%ProgramData%\Pangolin\pangolin.json`
Most keys in the `Config` object below can be set in either file. If the same key exists in both places, the user config value overrides the global value. This lets administrators define global defaults while still allowing per-user overrides when needed. Keys marked **Global only** must be set in `%ProgramData%\Pangolin\pangolin.json`; restart the Pangolin manager/UI after changing them.
<ResponseField name="Config" type="object">
JSON configuration for the Windows Pangolin client stored in `pangolin.json`.
<Expandable title="Config">
<ResponseField name="dnsOverride" type="boolean">
When true, matches the [Enable Aliases (Override DNS)](/manage/clients/platforms#enable-aliases-override-dns) preference and lets the client take over DNS resolution for Pangolin resources.
</ResponseField>
<ResponseField name="dnsTunnel" type="boolean">
When true, matches the [DNS Over Tunnel](/manage/clients/platforms#dns-over-tunnel) preference and sends DNS queries through the Pangolin tunnel.
</ResponseField>
<ResponseField name="primaryDNS" type="string">
Primary upstream DNS server used when override/tunnel DNS is enabled.
</ResponseField>
<ResponseField name="secondaryDNS" type="string">
Optional secondary upstream DNS server used as a fallback when the primary is unavailable.
</ResponseField>
<ResponseField name="dnsMatchDomains" type="array of strings">
Optional whitelist of domains sent to the configured upstream DNS server. When unset, all queries go to upstream DNS. When set, only matching queries use your Upstream DNS Server; all other requests use the system's DNS servers. Supports wildcards such as `*.proxy.internal`.
</ResponseField>
<ResponseField name="defaultServerURL" type="string">
When set, skips the deployment option screen during login; all login flows start directly with this server URL.
</ResponseField>
<ResponseField name="authPath" type="string">
Optional path appended to the server URL for authentication, for example `/auth/org/my-org` to always send users to a specific organization or branded login page. Most deployments should leave this unset.
</ResponseField>
<ResponseField name="userSettingsDisabled" type="boolean">
When true, hides and disables the settings form in the GUI so users cannot change these values themselves.
</ResponseField>
<ResponseField name="openStatusTabOnConnect" type="boolean">
When true, opens the Status tab immediately after clicking Connect so users can watch connection feedback while the tunnel is starting.
</ResponseField>
<ResponseField name="mtu" type="integer">
MTU for the internal WireGuard interface. Changing this is advanced and not recommended unless you have a clear reason; if you set a non-default value, configure the same MTU on every site this client connects to—see [Configure Sites](/manage/sites/configure-site).
</ResponseField>
<ResponseField name="preferLocalRoutes" type="boolean">
When true, prioritizes local routes over remote ones by adding an arbitrary metric to the WireGuard routes. This is useful when you want to ensure that local network traffic (for example, to a printer or NAS) is not routed through the Pangolin tunnel.
</ResponseField>
<ResponseField name="exitNodeTakesPrecedence" type="boolean">
When true, matches the [Exit Nodes Take Precedence Over Resources](/manage/clients/platforms#exit-nodes-take-precedence-over-resources) preference. While connected through an exit node, routes for other resources are not added and their aliases are not resolved, so all traffic flows through the exit node. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="openUIAtLogin" type="boolean">
When true, matches the **Start at Login** preference and starts Pangolin when you sign in to Windows. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="autoConnectAtLogin" type="boolean">
When true, matches the **Connect at Start** preference. The tunnel connects whenever Pangolin starts, and Pangolin also opens at sign-in, regardless of `openUIAtLogin`. If omitted, the default is `false`.
</ResponseField>
<ResponseField name="autoUpdateChecksEnabled" type="boolean">
**Global only.** When true, periodically check for updates in the background. When false, automatic checks are off; users can still use **Check for Updates** unless that button is also disabled. If omitted, the default is `true`. Enabling checks surfaces the update UI when a new version exists (tray “Pangolin Update Available” and the update prompt). Intended for org admins / MDM so config is the source of truth.
</ResponseField>
<ResponseField name="updateCheckIntervalSeconds" type="integer">
**Global only.** How often automatic checks run, in seconds. Values below `3600` (1 hour) are clamped to `3600`. Only matters when `autoUpdateChecksEnabled` is true. If omitted, the default is `86400` (24 hours). The client applies a small amount of jitter around this interval.
</ResponseField>
<ResponseField name="checkForUpdatesButtonEnabled" type="boolean">
**Global only.** When true, show **Check for Updates** in the system tray More menu. When false, hide that menu item. If omitted, the default is `true`. Manual checks always perform a live network lookup when the button is used. This is independent of `autoUpdateChecksEnabled`.
</ResponseField>
<ResponseField name="logLevel" type="string">
**Global only.** Controls client log verbosity. Supported values include `debug` and `info`. If omitted, the default is `info`.
</ResponseField>
<ResponseField name="sessionCookieName" type="string">
Overrides the cookie name the session token is sent and read under. Most deployments should leave this unset.
</ResponseField>
</Expandable>
</ResponseField>
As a system administrator, you can script placing `pangolin.json` in `%ProgramData%\Pangolin\` to set global defaults, and/or in each user's `%LOCALAPPDATA%\Pangolin\` folder for per-user overrides and targeted rollout behavior.
<Tip>
For enterprise customers, contact us if you need a custom MSI installer with
baked-in configuration; we can maintain custom installers as an add-on to
your enterprise license.
</Tip>
## Update
### Automatic Updates
The Windows client periodically checks for updates in the background. When an update is available, it requests permission to update. You can also check for updates from the system tray menu, or by restarting the application.
Once you accept the update, the client downloads the latest version and replaces itself.
### Manual Updates
Find the latest version in the [GitHub releases](https://github.com/fosrl/windows/releases).
You can download the latest installer and run it again to install the latest version. Visit [https://pangolin.net/downloads](https://pangolin.net/downloads) for the official installer.
content/docs/manage/clients/subnet-router.mdx
+4 -4
View File
@@ -7,7 +7,7 @@ A subnet router lets devices that can't run the Pangolin client access Pangolin
<Note>
Subnet routing currently only works on Linux with the [Pangolin
CLI](/manage/clients/install-client#pangolin-cli-linux-macos-windows).
CLI](/manage/clients/platforms/cli).
</Note>
Installing the Pangolin client on a device gives you end-to-end encryption and the best performance, so do that whenever you can. Often you can't. Printers usually can't run the client, and in a large AWS VPC or a legacy network that is being modernized step by step, touching every endpoint isn't realistic.
@@ -59,7 +59,7 @@ The host must run Linux. Install the CLI with:
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
```
When you run the CLI with `--subnet-router`, it enables forwarding and manages the nftables backend for you. See [Install Clients](/manage/clients/install-client#pangolin-cli-linux-macos-windows) for other install options.
When you run the CLI with `--subnet-router`, it enables forwarding and manages the nftables backend for you. See [Pangolin CLI](/manage/clients/platforms/cli) for other install options.
<Warning>
@@ -77,7 +77,7 @@ Restart Docker after changing this file. For background on running Docker on a r
### Log in or create a machine client
A machine client is the usual choice for a router, since it isn't tied to a user account. In the dashboard, go to Clients > Machines and create one. Copy its ID, secret, and endpoint. See [Credentials](/manage/clients/credentials).
A machine client is the usual choice for a router, since it isn't tied to a user account. In the dashboard, go to Clients > Machines and create one. Copy its ID, secret, and endpoint. See [Machine Client Credentials](/manage/clients/credentials).
You can also log in as a user with `pangolin login` and run `pangolin up`, but a machine client is better suited to a long-running service.
@@ -94,7 +94,7 @@ sudo pangolin up client \
--attach
```
`--attach` keeps the client in the foreground. To keep it running across reboots, install it as a service instead. See [Run as a Service](/manage/clients/install-client#run-as-a-service).
`--attach` keeps the client in the foreground. To keep it running across reboots, install it as a service instead. See [Run as a Service](/manage/clients/platforms/cli#run-as-a-service).
### Check the firewall and NAT rules
content/docs/manage/clients/understanding-clients.mdx
+5 -5
View File
@@ -6,7 +6,7 @@ A client is a way to access resources on sites remotely and privately via a virt
By default a client does not have access to any hosts on the local network of the site. Admins must explicitly define resources on the site and give specific users and roles access to the resources.
Users must log in and connect from a Pangolin client available on [Windows, Mac, Linux, iOS/iPadOS, and Android](/manage/clients/install-client). Machines (automated systems and servers) connect with an ID and secret.
Users must log in and connect from a Pangolin client available on [Windows, Mac, Linux, iOS/iPadOS, and Android](/manage/clients/platforms). They sign in with their user credentials through a web login flow. Machines (automated systems and servers) connect with [machine client credentials](/manage/clients/credentials): an ID, secret, and endpoint.
## Client Types
@@ -15,20 +15,20 @@ There are two types of clients: user devices and machines.
<CardGroup cols={2}>
<Card title="User Devices">
- Associated with a user in your Pangolin organization
- Requires login to connect (password, 2fa, etc)
- Logs in with user credentials through a web login flow (password, 2FA, or an identity provider)
- Available for download on Mac, Windows, and Linux
</Card>
<Card title="Machines">
- Represent a server or automated system instead of a user
- Connect with an ID and secret
- Connect with machine client credentials (ID and secret)
- Available in CLI form with Pangolin CLI
</Card>
</CardGroup>
### User Devices
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.
A user may download a client for their specific system. Before they can connect, they select a Pangolin server and log in with their user credentials through the web login flow. Users can log in as a Pangolin user or with your attached external identity provider.
Examples include:
@@ -48,7 +48,7 @@ Examples include:
Though you may connect a server via a user account using a CLI client, we recommend you specifically use a machine client.
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.
Machine clients authenticate with [machine client credentials](/manage/clients/credentials): an ID and secret. These are passed as arguments to the Pangolin CLI. They can be revoked and rotated. User devices never use these credentials.
## Client Modalities
content/docs/manage/clients/update-client.mdx
-48
View File
@@ -1,48 +0,0 @@
---
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>
content/docs/manage/resource-launcher.mdx
+1 -1
View File
@@ -25,7 +25,7 @@ Selecting a resource always expands a details panel. The panel shows what matter
<img src="/images/resource-launcher-expanded.png" alt="Resource Launcher detail panel showing a private SSH resource as an example."/>
</Frame>
From a card, list row, or the panel you can open HTTP-style resources in a new tab (HTTP/HTTPS, SSH, RDP, VNC, AI Gateway) or copy the access string. Private resources remind you to connect with a [Pangolin client](/manage/clients/install-client).
From a card, list row, or the panel you can open HTTP-style resources in a new tab (HTTP/HTTPS, SSH, RDP, VNC, AI Gateway) or copy the access string. Private resources remind you to connect with a [Pangolin client](/manage/clients/platforms).
For [AI Gateway](/manage/ai/overview) resources, the panel also lists available models, [virtual API keys](/manage/ai/virtual-api-keys), and copy-paste setup for coding agents. Public gateways use your API key. Private gateways use the connected client as the credential.
content/docs/manage/resources/private/ai-gateway.mdx
+1 -1
View File
@@ -3,7 +3,7 @@ title: "AI Gateway"
description: "Reach an AI API over the Pangolin tunnel using the connected client's identity"
---
A private AI Gateway resource exposes an AI API only to devices connected with the [Pangolin client](/manage/clients/install-client). Nothing is reachable from the public internet. Unlike [public AI Gateway](/manage/resources/public/ai-gateway), the gateway does not check a virtual API key. Identity comes from the active client connection.
A private AI Gateway resource exposes an AI API only to devices connected with the [Pangolin client](/manage/clients/platforms). Nothing is reachable from the public internet. Unlike [public AI Gateway](/manage/resources/public/ai-gateway), the gateway does not check a virtual API key. Identity comes from the active client connection.
This page covers how the **resource** works: reachability, access, and what you attach. Providers, model routing, the catalog, and client setup live in [AI Gateway](/manage/ai/overview).
content/docs/manage/resources/private/alias.mdx
+2 -2
View File
@@ -34,6 +34,6 @@ The `.local` TLD is reserved for local networking and multicast DNS (mDNS). mDNS
## Custom Upstream DNS
Aliases work by overriding the DNS of your computer running the client so that all DNS requests are sent to the Pangolin client for resolution. That behavior is controlled by the Enable Aliases (Override DNS) preference; see [Configure Clients](/manage/clients/configure-client#enable-aliases-override-dns). The DNS server on your computer is typically `100.96.128.1` (the first address inside of your utility subnet on the org) when connected to the tunnel, which forwards requests to an upstream server. By default, we use `1.1.1.1`, but this upstream address can be configured in the CLI or in the client settings.
Aliases work by overriding the DNS of your computer running the client so that all DNS requests are sent to the Pangolin client for resolution. That behavior is controlled by the Enable Aliases (Override DNS) preference; see [Platforms](/manage/clients/platforms#enable-aliases-override-dns). The DNS server on your computer is typically `100.96.128.1` (the first address inside of your utility subnet on the org) when connected to the tunnel, which forwards requests to an upstream server. By default, we use `1.1.1.1`, but this upstream address can be configured in the CLI or in the client settings.
**If you are attempting to set an upstream DNS server that is only accessible via the tunnel, ensure that you create a resource and check the tunnel DNS option in the client configuration settings.** Otherwise, connectivity to the server may fail when connected to the tunnel. Enable Aliases (Override DNS) must also be on—see [Configure Clients](/manage/clients/configure-client#enable-aliases-override-dns)—so the client can intercept DNS and forward queries to the upstream server.
**If you are attempting to set an upstream DNS server that is only accessible via the tunnel, ensure that you create a resource and check the tunnel DNS option in the client configuration settings.** Otherwise, connectivity to the server may fail when connected to the tunnel. Enable Aliases (Override DNS) must also be on—see [Platforms](/manage/clients/platforms#enable-aliases-override-dns)—so the client can intercept DNS and forward queries to the upstream server.
content/docs/manage/resources/private/destinations.mdx
+1 -1
View File
@@ -60,4 +60,4 @@ If a resource's destination overlaps with the user's local subnet, the client ca
**To fix it**, have the user check their local IP and subnet (`ipconfig` on Windows, `ifconfig`/`ip addr` on macOS/Linux), then compare it against your resource destinations. The recommended solution is to use more specific routes for your resources to prevent routing conflicts. For example instead of using a whole CIDR, use only host resources, or use more specific CIDRs like a /30 instead of a /24. Clients will always route to more specific routes over less specific ones. This way resource access is still controlled by Pangolin while the user's local and internet traffic is undisturbed.
If the above does not work, on Windows and Linux you can update the Pangolin client configuration to add a `prefer local routes` entry for the user's local subnet. This will tell the client to leave that traffic on the local network instead of routing it over the tunnel. See the [Configure Clients](/manage/clients/configure-client) page.
If the above does not work, on Windows and Linux you can update the Pangolin client configuration to add a `prefer local routes` entry for the user's local subnet. This will tell the client to leave that traffic on the local network instead of routing it over the tunnel. See [Windows](/manage/clients/platforms/windows) and the [Pangolin CLI](/manage/clients/platforms/cli).
content/docs/manage/resources/private/exit-node.mdx
+1 -1
View File
@@ -80,7 +80,7 @@ To confirm routing works, look up your public IP address with an online tool. It
## Other Resources When Connected
When a client is connected using an exit node other Pangolin resources will still be accessible and resolvable - even on other sites not designated on the exit node resource. In this way Pangolin is still split tunneling these destinations. If you would like to disable this, set the [Exit Nodes Take Precedence Over Resources](/manage/clients/configure-client#exit-nodes-take-precedence-over-resources) setting on. By enabling this setting, you are configuring Pangolin to ignore other resources outside of the exit node - all traffic will flow to and through the exit node resource and DNS aliases and subnets on other resources will no longer function.
When a client is connected using an exit node other Pangolin resources will still be accessible and resolvable - even on other sites not designated on the exit node resource. In this way Pangolin is still split tunneling these destinations. If you would like to disable this, set the [Exit Nodes Take Precedence Over Resources](/manage/clients/platforms#exit-nodes-take-precedence-over-resources) setting on. By enabling this setting, you are configuring Pangolin to ignore other resources outside of the exit node - all traffic will flow to and through the exit node resource and DNS aliases and subnets on other resources will no longer function.
## Logging
content/docs/manage/resources/private/ssh.mdx
+1 -1
View File
@@ -19,7 +19,7 @@ The Pangolin client provides the tunnel; the CLI handles certificate generation,
pangolin ssh <resource-alias>
```
The tunnel can be provided by the CLI or by another Pangolin client (for example the macOS app). You can run the GUI for the tunnel and use the CLI only for SSH.
The tunnel can be provided by the CLI or by another Pangolin client (for example the macOS app). You can run the GUI for the tunnel and use the CLI only for SSH. On Windows, [companion mode](/manage/clients/platforms/windows#companion-mode) uses the desktop app's login and connection, so `pangolin ssh` runs as the account you already signed in with.
## Destination and Access
content/docs/manage/ssh.mdx
+1 -1
View File
@@ -247,7 +247,7 @@ flowchart LR
### Prerequisites
- **Pangolin Site** running on one host (the site / bastion) with a pre-shared key for external auth daemons.
- **Pangolin CLI** installed on each server where you will run the auth daemon. See [Install Clients - Quick Install (Recommended)](/manage/clients/install-client#quick-install-recommended).
- **Pangolin CLI** installed on each server where you will run the auth daemon. See [Pangolin CLI](/manage/clients/platforms/cli#install).
### Step 1: On the Server Running the Pangolin Site