mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-10-12 07:39:08 +02:00
1.19 docs updates
This commit is contained in:
miloschwartz
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: "CIDR"
|
||||
description: "Route client traffic to an entire IP range on the remote network"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
A CIDR private resource exposes an entire IP range on your remote network to connected Pangolin clients. When a user connects with the Pangolin client and has access to the resource, the client installs a route for that prefix and all traffic to addresses within the range is carried over the tunnel.
|
||||
|
||||
CIDR resources are the usual choice for whole subnets or network segments instead of creating a separate host resource for every machine.
|
||||
|
||||
## Destination
|
||||
|
||||
A CIDR resource destination is an IP range in CIDR notation—for example `10.1.0.0/16`. Any address inside the range is covered for users who have been granted access.
|
||||
|
||||
The site connector must have routable access to the entire prefix. Confirm from the site's network that it can reach hosts across the range before creating the resource.
|
||||
|
||||
## Port Restrictions
|
||||
|
||||
[Port restrictions](/manage/resources/private/port-restrictions) apply to the entire CIDR range. Use Custom mode to allow only specific ports (for example `443` for HTTPS workloads across the subnet) or Blocked to disable a protocol entirely.
|
||||
|
||||
## Multi-Site Routing
|
||||
|
||||
When the same CIDR is reachable from multiple site connectors, attach all applicable sites. Pangolin [routes through the best available path](/manage/resources/private/multi-site-routing) and fails over when a site goes offline.
|
||||
|
||||
<Warning>
|
||||
Only attach sites that can actually reach the configured CIDR. Mixing sites on unrelated networks where some cannot reach the range leads to unpredictable routing.
|
||||
</Warning>
|
||||
|
||||
## Overlapping Networks
|
||||
|
||||
If the same IP range exists on multiple sites, Pangolin resolves the conflict automatically. CIDR resources cannot use [aliases](/manage/resources/private/alias)—aliases apply to individual hosts only. If you need predictable routing to a specific site, create separate [host resources](/manage/resources/private/host) for the machines you care about instead of relying on a shared CIDR range.
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: "Host"
|
||||
description: "Route client traffic to a single IP address or FQDN on the remote network"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
A host private resource exposes a single machine on your remote network to connected Pangolin clients. When a user connects with the Pangolin client and has access to the resource, traffic destined for that host is carried over the tunnel to the site, which delivers it on the remote network.
|
||||
|
||||
Host resources are the most common private resource type. They do not render in a browser—you use native applications (a database client, `curl`, an RDP client, etc.) against the destination address while the Pangolin client is connected.
|
||||
|
||||
## Destination
|
||||
|
||||
Every host resource has a [destination](/manage/resources/private/destinations): a single IP address or fully qualified domain name (FQDN).
|
||||
|
||||
| Destination type | Example | When to use |
|
||||
|------------------|---------|-------------|
|
||||
| IP address | `10.1.0.35` | A host with a stable IP on the remote network |
|
||||
| FQDN | `db.autoco.internal` | A host identified by DNS that may change IP |
|
||||
| Loopback | `127.0.0.1` | A service running on the site connector host itself |
|
||||
|
||||
### Loopback on the Site Host
|
||||
|
||||
If the service runs on the same machine as the site connector, set the destination to `127.0.0.1` or `localhost`. On the user's machine, `localhost` always refers to their own computer—not the remote site. You must add an [alias](/manage/resources/private/alias) (for example `metrics.site-internal.example`) so users connect to a name that Pangolin resolves over the tunnel.
|
||||
|
||||
## Port Restrictions
|
||||
|
||||
By default, all TCP and UDP ports on the destination are reachable. Tighten access with [port restrictions](/manage/resources/private/port-restrictions) to allow only the ports your application needs.
|
||||
|
||||
## Multi-Site Routing
|
||||
|
||||
Attach multiple sites to a host resource when the same destination is reachable from more than one connector. Pangolin [routes traffic through the best available site](/manage/resources/private/multi-site-routing) and fails over automatically when a site goes offline.
|
||||
|
||||
## Aliases
|
||||
|
||||
Optionally assign an [alias](/manage/resources/private/alias) so users connect with a memorable hostname instead of a raw IP. Aliases are required for loopback destinations and recommended when the same IP exists on overlapping networks across sites.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: "Private HTTP"
|
||||
description: "HTTPS private resources on your domain with a connected client—Pangolin Cloud and Enterprise; reverse proxy and TLS on the site"
|
||||
title: "HTTP / HTTPS"
|
||||
description: "Private reverse proxy with optional TLS termination at the site edge over the Pangolin tunnel"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
@@ -11,13 +11,17 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition).
|
||||
</Note>
|
||||
|
||||
Private HTTP is a special kind of private resource for web workloads. It behaves similarly to a [public resource](/manage/resources/understanding-resources#public-resources) in that traffic is HTTP-based and flows through a reverse proxy with a proper hostname, but it only works when the user has an active Pangolin client connection. Nothing is exposed on the public internet; access is entirely off the internet until someone is on the tunnel.
|
||||
Private HTTP/HTTPS resources expose web applications over the Pangolin tunnel with a fully qualified domain name. Unlike [public HTTP/HTTPS resources](/manage/resources/public/http-https), nothing is reachable from the public internet—a user must connect with the Pangolin client first.
|
||||
|
||||
Once connected, users open the resource in a normal web browser at a URL like `https://my-app.internal.example.com`. The Pangolin client resolves the hostname privately, traffic travels over the peer-to-peer tunnel, and the site connector terminates TLS and runs a reverse proxy to the backend.
|
||||
|
||||
For a deep dive into how private HTTPS reverse proxying works—including DNS hijacking, overlay addressing, certificate push, and the embedded edge proxy—see [Building a Peer-to-Peer Alternative to Cloudflare Tunnels](https://pangolin.net/news/building-a-peer-to-edge-peer-reverse-proxy).
|
||||
|
||||
## Hostname, DNS, and TLS
|
||||
|
||||
When you enable private HTTP, you assign a domain name to the resource. That hostname must be a domain you have already added and configured in Pangolin (see [Domains](/manage/domains)). This is analogous to an [alias](/manage/resources/private/alias) in that the client resolves the name through Pangolin and traffic is steered to the correct site, but it is not the same system: the name must be a real domain managed in your organization, not an arbitrary internal alias.
|
||||
When you create a private HTTP/HTTPS resource, you assign a domain name. That hostname must be a domain you have already added and configured in Pangolin (see [Domains](/manage/domains)). This is analogous to an [alias](/manage/resources/private/alias) in that the client resolves the name through Pangolin and traffic is steered to the correct site, but it is not the same system: the name must be a real domain managed in your organization, not an arbitrary internal alias.
|
||||
|
||||
You can enable SSL on the resource so Pangolin obtains and serves a valid certificate for that hostname. When a connected user opens the site in a browser, the request is resolved to the site the same way as with alias-style flows, but a reverse proxy running on the site terminates TLS and proxies the request downstream to your [destination](/manage/resources/private/destinations). The Pangolin control plane provisions the routing and pushes certificates to the edge where your site runs, so users get normal HTTPS without certificate warnings.
|
||||
Enable SSL on the resource so Pangolin obtains and serves a valid certificate for that hostname. When a connected user opens the site in a browser, a reverse proxy running on the site terminates TLS and proxies the request downstream to your [destination](/manage/resources/private/destinations). The Pangolin control plane provisions routing and pushes certificates to the site connector, so users get normal HTTPS without certificate warnings.
|
||||
|
||||
## Destination Fields
|
||||
|
||||
@@ -31,4 +35,4 @@ You can approximate private browsing with a standard private resource by pairing
|
||||
|
||||
A [public resource](/manage/resources/public/authentication) is reachable from the internet; Pangolin sits in front with authentication (for example platform SSO or other methods) so unauthenticated requests are blocked at the edge—the “bouncer” in front of a public site.
|
||||
|
||||
Private HTTP does not use that public forward-auth model for reachability. The hostname does not grant access from the open internet at all. The user must connect with the Pangolin client first, like a VPN, before the domain resolves and the reverse proxy will serve the app. Authentication on who may use the resource still follows your private resource access rules (users, roles, machines), but the network path is client-attached only.
|
||||
Private HTTP does not use that public forward-auth model for reachability. The hostname does not grant access from the open internet at all. The user must connect with the Pangolin client first, like a VPN, before the domain resolves and the reverse proxy will serve the app. Instead of a login page at the edge, Pangolin uses the user's active client connection to determine their identity and enforces [private resource access rules](/manage/resources/private/authentication) (users, roles, machines) from that session. The network path is client-attached only.
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: "SSH"
|
||||
description: "Connect to remote hosts over the Pangolin tunnel using the Pangolin CLI"
|
||||
---
|
||||
|
||||
import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
|
||||
|
||||
<PangolinCloudTocCta />
|
||||
|
||||
<Note>
|
||||
Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition).
|
||||
</Note>
|
||||
|
||||
Private SSH resources let users connect to remote hosts from their terminal over the Pangolin tunnel. Unlike [public SSH resources](/manage/resources/public/ssh), private SSH is **not** browser-rendered.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. The user connects with the Pangolin client (GUI or CLI).
|
||||
2. They run `pangolin ssh <alias>` where the alias matches the private resource.
|
||||
3. Pangolin checks the user's identity from the active client connection and enforces [private resource access rules](/manage/resources/private/authentication) (users, roles, machines).
|
||||
4. Depending on the SSH [configuration](/manage/ssh#configuration-options), Pangolin generates a short-lived certificate and provisions the user on the host, or the user authenticates with existing host credentials.
|
||||
5. An SSH session opens through the tunnel.
|
||||
|
||||
The Pangolin client provides the tunnel; the CLI handles certificate generation, user provisioning, and the SSH session itself. No manual SSH key distribution is required when using automated provisioning.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## Destination and Access
|
||||
|
||||
Create a private resource with a [destination](/manage/resources/private/destinations) (IP or FQDN) for the host you want to SSH into. Assign an [alias](/manage/resources/private/alias) so users have a friendly name to pass to `pangolin ssh`.
|
||||
|
||||
Grant access to users or roles and ensure **TCP 22** is allowed in [port restrictions](/manage/resources/private/port-restrictions).
|
||||
|
||||
<Warning>
|
||||
If TCP 22 is not allowed in the resource's port restrictions, users will not be able to establish SSH sessions to that resource even when the rest of the setup is correct.
|
||||
</Warning>
|
||||
|
||||
## Site and Host Configuration
|
||||
|
||||
SSH private resources do **not** use discrete targets. Instead, you:
|
||||
|
||||
1. Select which sites can route to the resource.
|
||||
2. Enter the backend host and port—unless you selected **Pangolin SSH** mode, which executes sessions on the site connector host and does not require a host or port.
|
||||
|
||||
<Warning>
|
||||
**Pangolin SSH mode requires root.** Newt must run as root on the site connector host. Use `sudo newt ...` or run the Newt systemd service as root. See [Install a site](/manage/sites/install-site).
|
||||
</Warning>
|
||||
|
||||
Pangolin routes through the site that is online and healthiest. See [Multi-site Routing](/manage/resources/private/multi-site-routing).
|
||||
|
||||
## SSH Configuration
|
||||
|
||||
The SSH settings on a private resource use the same options as [public SSH resources](/manage/resources/public/ssh). Mode, authentication method, and auth daemon location are configured identically in the dashboard.
|
||||
|
||||
See [SSH Access](/manage/ssh) for a full explanation of each option, setup instructions, and an example for every configuration combination.
|
||||
|
||||
## How Private SSH Differs from Public SSH
|
||||
|
||||
| | Private SSH | [Public SSH](/manage/resources/public/ssh) |
|
||||
|---|-------------|--------------------------------------------|
|
||||
| **Access** | Pangolin CLI: `pangolin ssh <alias>` | Web browser at a public FQDN |
|
||||
| **Client required** | Yes — user must be connected with the Pangolin client | No |
|
||||
| **Auth layer** | Identity from the active client connection; [private resource access rules](/manage/resources/private/authentication) | [Public resource authentication](/manage/resources/public/authentication) — login page, SSO, access rules |
|
||||
| **Manual auth step** | Credentials handled by the SSH client or certificate flow | Username/password or private key entered in a browser form after the public auth layer |
|
||||
| **Hostname** | [Alias](/manage/resources/private/alias) on the private resource | Public FQDN on your Pangolin domain |
|
||||
| **Port restrictions** | TCP 22 must be allowed in [port restrictions](/manage/resources/private/port-restrictions) | Not applicable |
|
||||
Reference in New Issue
Block a user