diff --git a/docs.json b/docs.json index de2c854..4f5ada2 100644 --- a/docs.json +++ b/docs.json @@ -66,7 +66,10 @@ "pages": [ "manage/resources/private/authentication", "manage/resources/private/destinations", - "manage/resources/private/alias" + "manage/resources/private/port-restrictions", + "manage/resources/private/alias", + "manage/resources/private/private-http", + "manage/resources/private/multi-site-routing" ] } ] @@ -392,6 +395,10 @@ { "source": "manage/healthchecks-failover", "destination": "manage/resources/public/healthchecks-failover" + }, + { + "source": "/manage/resources/private/icmp-access", + "destination": "/manage/resources/private/port-restrictions" } ], "seo": { diff --git a/manage/dns-cache.mdx b/manage/dns-cache.mdx index d3195eb..ac83712 100644 --- a/manage/dns-cache.mdx +++ b/manage/dns-cache.mdx @@ -3,6 +3,10 @@ title: "DNS Cache" description: "What is a DNS cache and how to manage it with private resources" --- +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + ## What is a DNS Cache? A DNS cache is a temporary storage of DNS records that allows for faster resolution of domain names to IP addresses. When a user visits a website, their device queries the DNS server to resolve the domain name to an IP address. The DNS cache stores this information so that subsequent requests for the same domain can be resolved more quickly without needing to query the DNS server again. diff --git a/manage/resources/private/alias.mdx b/manage/resources/private/alias.mdx index f2026d0..a348b62 100644 --- a/manage/resources/private/alias.mdx +++ b/manage/resources/private/alias.mdx @@ -1,6 +1,6 @@ --- title: "Aliases" -description: "Set a friendly alias hostname that resolves to a host" +description: "Friendly names for resources, overlaps, loopback on the site host, and DNS behavior" --- import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; @@ -9,13 +9,21 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; -Aliases provide a secondary, user-friendly address for any of your Resources, allowing users to access the Resource using this alternate name in addition to the original address. +Aliases provide a secondary, user-friendly address for any of your resources, allowing users to access the resource using this alternate name in addition to the original address. -For instance, a router with the address `10.0.0.1` could be assigned the alias `router.internal`, and users could connect using either. Aliases are accessible to anyone who has access to the Resource, and they are exclusively accessible when connected with a Pangolin client, meaning they function without requiring any external DNS record setup. Furthermore, aliases are protocol agnostic, which means they will work with any network protocol, essentially acting as a pseudo-A record for an address that is only functional within the Pangolin environment. +For instance, a router with the address `10.0.0.1` could be assigned the alias `router.internal`, and users could connect using either. Aliases are accessible to anyone who has access to the resource, and they are exclusively accessible when connected with a Pangolin client, meaning they function without requiring any external DNS record setup. Furthermore, aliases are protocol agnostic, which means they will work with any network protocol, essentially acting as a pseudo-A record for an address that is only functional within the Pangolin environment. -## CIDRs Vs. IPs +## Overlapping Networks and Loopback on the Site Host -A alias can only be created for a Resource that is a single host (IP or FQDN). Aliases cannot be created for Resources that are CIDR ranges because it would be ambiguous which host within the range the alias should point to. +Several situations described on the [Destinations](/manage/resources/private/destinations) page are where an alias is especially important—either optional but strongly recommended, or effectively required. + +Overlapping IP spaces across sites are common (for example the same RFC1918 subnet behind different Pangolin sites). Pangolin helps route connections without users picking a site by hand, but raw IPs or ambiguous names can still collide across environments. Assigning a distinct alias per resource gives clients a single hostname whose DNS resolution goes through Pangolin, so traffic consistently reaches the intended resource and site instead of whichever overlapping address would otherwise win. See [Overlapping destinations across sites](/manage/resources/private/destinations#overlapping-destinations-across-sites). + +Loopback on the site host is another case: if the resource destination is `127.0.0.1` or `localhost` on the machine running the site, those strings still mean “this machine” on the user’s laptop or desktop—not the remote site. There is no safe way for users to type loopback literals and reach the service behind another host; an alias hostname is required so the client resolves the name via Pangolin and sends traffic over the tunnel to the site, which then forwards to its own loopback. See [Loopback on the site host](/manage/resources/private/destinations#loopback-on-the-site-host). + +## CIDRs vs. IPs + +An alias can only be created for a resource that is a single host (IP or FQDN). Aliases cannot be created for resources that are CIDR ranges because it would be ambiguous which host within the range the alias should point to. ## Domain Structure @@ -29,14 +37,10 @@ If you use a wildcard such as `*.proxy.internal`, it will match any hostname tha ## 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. 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 will forward request to an upstream server. By default, we use `9.9.9.9`, 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 [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. -**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 or use the --tunnel-dns flag.** Otherwise, connectivity to the server may fail when connected to the tunnel. You must also be overriding the dns of the computer (as discussed above) for this to work because the client needs to intercept the DNS request to forward it to the upstream server. - -## Disable Aliases - -If you wish to disable this behavior and prevent aliases from being resolved and leave your DNS alone, you can do so by adding `--override-dns=false` to the CLI or disable override dns 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. ## ICMP Ping -Aliases do not currently support ICMP ping requests. If you attempt to ping an alias, it will not respond, even if the underlying Resource is reachable. This is because the Pangolin client does not intercept ICMP packets for alias resolution. \ No newline at end of file +Aliases do not currently support ICMP ping requests. If you attempt to ping an alias, it will not respond, even if the underlying resource is reachable. This is because the Pangolin client does not intercept ICMP packets for alias resolution. \ No newline at end of file diff --git a/manage/resources/private/authentication.mdx b/manage/resources/private/authentication.mdx index 1132cb2..a4fefad 100644 --- a/manage/resources/private/authentication.mdx +++ b/manage/resources/private/authentication.mdx @@ -1,6 +1,6 @@ --- title: "Authentication" -description: "Only allow access to Resources to specific users, roles, and machines" +description: "Only allow access to resources to specific users, roles, and machines" --- import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; @@ -9,24 +9,12 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; -When a client connects into an organization they will **NOT** have access to any Resources by default. Access must be explicitly granted to users, roles, or machines for a WireGuard tunnel to be established to the site hosting the Resource. The Client will show no peers unless access is granted. +When a client connects into an organization they will NOT have access to any resources by default. Access must be explicitly granted to users, roles, or machines for a tunnel to be established to the site(s) hosting the resource. The client will show no sites or resources unless access is granted. Access can be granted in several ways: -* **Roles:** Assign access to Resources to specific roles. Any user or machine with that role will gain access to the Resource when they connect. -* **Users:** Assign access to Resources to specific users. Only those users will gain access to the Resource when they connect. -* **Machines:** Assign access to Resources to specific machines. Only those machines will gain access to the Resource when they connect. Note that machines can not be put into roles. +* **Roles:** Assign access to resources to specific roles. Any user with that role will gain access to the resource when they connect. +* **Users:** Assign access to resources to specific users. Only those users will gain access to the resource when they connect. +* **Machines:** Assign access to resources to specific machines. Only those machine clients will gain access to the resource when they connect. Note that machines can not be put into roles. -When removing access to a resource, the client will automatically tear down the WireGuard tunnel to that Resource if there are no other Resources accessible on that site. - - - - - -### Port Restrictions - -By default, when access to a Resource is granted, all ports on that Resource are accessible. However, you can restrict access to specific ports on a Resource by defining port restrictions. When port restrictions are defined, only the specified ports will be accessible to users, roles, or machines that have access to the Resource. To specify specific ports, enter either a single port (e.g., `80`), a comma-separated list of ports (e.g., `80,443,8080`), or a port range using a hyphen (e.g., `8000-8100`). - -### ICMP Access - -By default, ICMP (ping) access to Resources is enabled. To disable ICMP access, you can uncheck the "ICMP" option when configuring access to a Resource. This will prevent users, roles, or machines with access to the Resource to send ICMP echo requests (ping) to the Resource's destination. Currently you can not ping an alias. \ No newline at end of file +When removing access to a resource, the client will automatically tear down the tunnel to that resource if there are no other resources accessible on that site. diff --git a/manage/resources/private/destinations.mdx b/manage/resources/private/destinations.mdx index c6f8052..cb18837 100644 --- a/manage/resources/private/destinations.mdx +++ b/manage/resources/private/destinations.mdx @@ -1,41 +1,55 @@ --- title: "Destinations" -description: "Understand connection options to the remote network" +description: "What a private resource destination is and how to define it (FQDN, IP, or CIDR)" --- import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; +## What is a destination? +A destination is the network location your site can route to for a private resource: a single host IP address, an IP CIDR range, or a fully qualified domain name (FQDN). Every private resource must have a destination—it tells Pangolin where the resource lives on the remote network and how the site should reach it. -A Resource's **destination** can be defined in several ways: +When a user connects with the Pangolin client and has access to that resource, their traffic is steered toward the address or range defined by the destination. -* **Fully Qualified Domain Name (FQDN):** For example, `host.autoco.internal`. -* **IP Address:** For example, `10.1.0.35`. -* **IP CIDR Range:** For example, `10.1.0.0/16`. +That role is similar to a [target](/manage/resources/public/targets) on a public resource: both tell Pangolin where to send traffic after it enters the platform. For public resources, traffic typically arrives from the internet; for private resources, it comes from other clients already connected to your organization. -When defining a Resource with an FQDN, the Pangolin site will resolve the FQDN to an IP address on the remote network. This allows you to create Resources that point to hosts whose IP addresses may change over time, as long as the FQDN remains consistent. +You can optionally add an [alias](/manage/resources/private/alias) so people use a memorable hostname instead of the raw destination, or so overlapping IPs across sites resolve predictably (see [Overlapping destinations across sites](#overlapping-destinations-across-sites) below). In some setups an alias is required—for example when the destination is loopback on the site host ([Loopback on the site host](#loopback-on-the-site-host)). -When defining a Resource with an IP address, the Pangolin client will connect directly to that specific IP address on the remote network. It will insert routes for that single IP address into the network route table of the host when users connect with the client. +## Defining a Destination -When defining a Resource with a CIDR range, all IP addresses within that range will be accessible to users who have been granted access to the Resource. This is useful for providing access to entire subnets or network segments. It will insert routes for that single IP address into the network route table of the host when users connect with the client. +A private resource destination is always exactly one of the following: a single host IP, a CIDR range, or a FQDN. + +### IP Address + +Use a single IP address for one host on the remote network—for example, `10.1.0.35`. The Pangolin client installs a route for that host when the user connects with access to the resource, and traffic to that IP is carried over the tunnel to the site, which delivers it on the remote network. + +### Loopback on the Site Host + +If the service lives on the same machine as the Pangolin site, you can set the destination to `127.0.0.1` or `localhost`. The site then routes to its own loopback interface, which is where that process is listening. + +On the user’s machine, `localhost` and `127.0.0.1` always mean that machine, not the remote site. Telling someone to open `http://127.0.0.1:8080` in a browser would hit their laptop, not the site. + +So you must add an [alias](/manage/resources/private/alias)—for example a hostname only resolvable through Pangolin, such as `metrics.site-internal.example`—and have people use that name to connect. The client resolves the alias via Pangolin, sends traffic over the tunnel, and the site forwards it to `127.0.0.1` / `localhost` on its side. This is an example where an alias is required and where it resolves overlapping or conflicting meanings of the same address between the client and the site. + +### CIDR Range + +Use an IP CIDR range when many addresses should be reachable as one resource—for example, `10.1.0.0/16`. Any address inside the range is covered for users who have been granted access. The client installs routing for that prefix when they connect. This is the usual choice for whole subnets or segments instead of listing hosts one by one. + +### FQDN + +Use a fully qualified domain name when the resource is identified by DNS on the remote network—for example, `host.autoco.internal`. The Pangolin site resolves that hostname to an IP address on the network behind the site. That is a good fit when the host’s address can change but the name stays the same. + +Another pattern is routing traffic destined for a public SaaS hostname through a Pangolin site using the client. For example, you can configure a private resource whose destination is `google.com`. When a user with access opens `google.com` in the browser, the client sends that traffic over the tunnel to the site. Because the site treats `google.com` as the resource’s destination, it proxies that traffic out to the internet from the site’s egress. The flow is: client → tunnel → site → upstream host, instead of the client reaching the host directly on its local path. ### Additional Notes on Resource Destinations -* **Reserved IP Addresses:** The Pangolin client reserves the CGNAT subnet 100.96.128.0/24. Accessing resources via an IP address within this reserved range will be blocked by the client, though its use is uncommon. This range can be configured for newly created orgs in the self-hosted Pangolin configuration file. -* **Resource Destination Resolution:** The configured address of the Resource is resolved by the site the resource points to. Make sure the site can resolve the address correctly. +* Reserved IP Addresses: The Pangolin client reserves the CGNAT subnet 100.96.128.0/24. Accessing resources via an IP address within this reserved range will be blocked by the client, though its use is uncommon. This range can be configured for newly created orgs in the self-hosted Pangolin configuration file. +* Resource Destination Resolution: The configured address of the Resource is resolved by the site the resource points to. Make sure the site can resolve the address correctly. -### What about overlaps? +### Overlapping destinations across sites Pangolin smooths away overlapping networks and arbitrarily chooses a single site to resolve the IP address or range to. This is because we want connection requests to any Resource to be as simple as possible for the end users: when they connect to a particular IP address or FQDN, Pangolin figures out which site to send it to and the end user never needs to figure this out. -It is recommended that you create overlapping resources only if absolutely required. If you do, use [Aliases](/manage/resources/private/alias) to explicitly defined which host should be used for a given FQDN or IP address and use the alias to connect. - -### ICMP End to End? - -Pangolin supports testing connectivity to Resources using ICMP ping requests. However, it's important to note that while the Pangolin client can send ICMP echo requests to the destination, **the actual ping request is captured and replayed from the Newt binary to the actually destination**. This means that requests are not end to end but are still an effective way to test connectivity to a resource. - -### Unicast Only? - -Right now unicast TCP and UDP traffic is supported through the Pangolin client. Multicast and broadcast traffic is not supported at this time. +It is recommended that you create overlapping resources only if absolutely required. If you do, use [Aliases](/manage/resources/private/alias) to explicitly define which host should be used for a given FQDN or IP address and use the alias to connect. diff --git a/manage/resources/private/multi-site-routing.mdx b/manage/resources/private/multi-site-routing.mdx new file mode 100644 index 0000000..0f3d106 --- /dev/null +++ b/manage/resources/private/multi-site-routing.mdx @@ -0,0 +1,34 @@ +--- +title: "Multi-site Routing and High Availability" +description: "Use multiple sites on a private resource for resilient routing and failover" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + + + +When you configure a private resource, you can attach more than one site. Pangolin then chooses how to reach the resource’s destination through those sites, similar in spirit to running multiple connectors into the same network: traffic is steered toward whichever path is most suitable at the time. + +### How Routing Works + +Pangolin evaluates the sites you selected and routes client traffic through the site that is most ideal from the client’s perspective. That decision weighs factors such as latency and whether the site is reachable. If a site becomes unavailable, clients begin using the next best online site without you having to reconfigure the resource. + + +Failover may take a few seconds. The site must be registered as offline, routing changes propagated to clients, and only then can failover take effect, so a short gap while that happens is expected. + + +You are not limited to two sites. You can select as many sites as you need on a single private resource, as long as every selected site can actually reach the resource’s destination on the network. + +### Example: Redundant Office Connectors + +Suppose your office LAN is reachable from two servers, and you install a Pangolin site connector on each. Both sites act as connectors into the same office network, so either site can route to the same internal hosts. + +You create one private resource for an internal service and select both sites. While both connectors are healthy, Pangolin sends traffic through the better path. If one server or connector goes down, clients keep access to the private resource because traffic fails over to the other online site. + +### Requirements and Pitfalls + +Every site you attach must have routable access to the resource destination (same logical network, correct routes, DNS or IP resolution from that site’s perspective, and so on). The product assumes that any site in the list is a valid path to the same destination. + +If you mix sites that live on entirely different networks and one or more of them cannot reach the destination, behavior becomes unpredictable and the resource may not work reliably. Before adding a site, confirm from that site’s network that it can reach the configured destination the same way you expect the primary site to. diff --git a/manage/resources/private/port-restrictions.mdx b/manage/resources/private/port-restrictions.mdx new file mode 100644 index 0000000..80501bf --- /dev/null +++ b/manage/resources/private/port-restrictions.mdx @@ -0,0 +1,45 @@ +--- +title: "Ports and ICMP" +description: "Configure TCP and UDP port modes and ICMP (ping) for private resources" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + +For each private resource, TCP and UDP are configured separately. Each protocol uses one of three modes: All, Blocked, or Custom. ICMP (ping) is controlled on its own and does not follow those TCP/UDP modes. + +## Port restrictions + +Port settings apply to users, roles, and machines that have access to the resource. They limit which application traffic can reach the resource’s destination through Pangolin. + +### All + +All means no port filtering for that protocol: every port on the destination is reachable through the tunnel. This is the default-style behavior when you are not narrowing traffic to a subset of ports. + +Use All when the service needs arbitrary ports (for example ephemeral ports on the client side are handled by the stack, but the server listens on many ports) or when you have not yet tightened access. + +### Blocked + +Blocked means that protocol is not allowed to the destination through Pangolin: no TCP or no UDP traffic passes, depending on which row you set. The other protocol can still be All or Custom independently—for example TCP Custom (only `443`) with UDP Blocked for a HTTPS-only workload that should not receive UDP to that destination. + +Use Blocked when you want to turn off a protocol entirely for that resource. + +### Custom + +Custom means only the ports you list are allowed; every other port for that protocol is denied. Enter either: + +* a single port (e.g. `80`), +* a comma-separated list (e.g. `80,443,8080`), or +* a range with a hyphen (e.g. `8000-8100`). +* lists and ranges (e.g. `80,443,8080-8090,9000-9010`) + +Use Custom for least-privilege access: allow only the ports your application actually needs (see also [SSH](/manage/ssh) for allowing TCP `22` when using Pangolin SSH). + +## ICMP + +By default, ICMP (ping) to the resource’s destination is enabled. To turn it off, disable the ICMP option when configuring access to the resource. That stops ICMP echo requests (ping) to the destination for principals that have access. + + +ICMP ping does not work when using a resource [alias](/manage/resources/private/alias) as the target—ping applies to the resource’s configured destination (FQDN, IP, or CIDR), not to alias hostnames. + diff --git a/manage/resources/private/private-http.mdx b/manage/resources/private/private-http.mdx new file mode 100644 index 0000000..968e30a --- /dev/null +++ b/manage/resources/private/private-http.mdx @@ -0,0 +1,34 @@ +--- +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" +--- + +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). + + +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. + +## 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. + +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. + +## Destination Fields + +The destination block for a private HTTP resource is closer to a [target](/manage/resources/public/targets) on a public resource than to a plain private resource: in addition to the upstream hostname or IP, you set a destination port and a scheme (`http` or `https`). Those values are required so the site knows how to open the connection to the backend after TLS is terminated at the proxy. + +## Compared to an IP Resource and an Alias + +You can approximate private browsing with a standard private resource by pairing an IP or internal hostname with an [alias](/manage/resources/private/alias) and a port. In practice you would still visit something like `https://your-alias.example:8443/` (or HTTP without a trusted name), and the browser will not show a normal publicly trusted certificate for that pattern the way it does for a first-class HTTPS hostname. Private HTTP is meant for the case where you want a real FQDN on your Pangolin domain with valid TLS and default ports, similar to a public resource, while keeping the surface client-only. + +## Compared to a Public Resource + +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. diff --git a/manage/resources/public/wildcard-resources.mdx b/manage/resources/public/wildcard-resources.mdx index ab259aa..c46c7f1 100644 --- a/manage/resources/public/wildcard-resources.mdx +++ b/manage/resources/public/wildcard-resources.mdx @@ -1,12 +1,16 @@ --- title: "Wildcard Resources" -description: "Route every hostname at a subdomain level through one public resource" +description: "Pangolin Cloud and Enterprise: route every hostname at a subdomain level through one public resource" --- 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). + + With a wildcard public resource, one resource owns an entire subdomain level: every hostname under that level is proxied through the same Pangolin resource and tunnel so downstream systems can route further (for example another reverse proxy or Kubernetes ingress). Access rules and authentication you set on that resource apply to all hostnames matched by the wildcard. If you enable a PIN code, every hostname under the wildcard requires that PIN.