pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-02-08 05:56:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

Define resources and small formating updates

Browse Source
This commit is contained in:
Owen
2025-12-10 18:02:03 -05:00
parent ea68e3a6bc
commit de61a00717
11 changed files with 73 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
about/how-pangolin-works.mdx
View File

@@ -72,7 +72,7 @@ Clients are available for Mac, Windows, and Linux. They work transparently with
### Remote Nodes
Remote nodes are self-hosted Pangolin servers that you control while using Pangolin Cloud for management and coordination. You maintain complete control over your infrastructure and data flow, while the cloud handles the control plane, DNS, certificate management, and backups.
Remote nodes are self-hosted Pangolin servers that you control while using Pangolin Cloud or enterprise for management and coordination. You maintain complete control over your infrastructure and data flow, while the cloud handles the control plane, DNS, certificate management, and backups.
You can deploy multiple remote nodes for high availability and automatic failover. If your nodes become unavailable, traffic can optionally fail over to cloud infrastructure until you restore service.

4
docs.json
View File

@@ -53,8 +53,8 @@
{
"group": "Private Resources",
"pages": [
"manage/resources/private/host",
"manage/resources/private/cidr",
"manage/resources/private/destinations",
"manage/resources/private/access",
"manage/resources/private/alias"
]
}

14
manage/resources/private/access.mdx Normal file
View File

@@ -0,0 +1,14 @@
---
title: "Access"
description: "Only allow access to Resources to specific users, roles, and machines"
---
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.
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.
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.

16
manage/resources/private/alias.mdx
View File

@@ -7,6 +7,18 @@ Aliases provide a secondary, user-friendly address for any of your Resources, al
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.
# Disable Aliases
## CIDRs Vs. IPs
Aliases work
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.
## Domain Structure
Since aliases cannot be single-label domains, you must avoid using domain names that do not contain a dot (e.g., `pangolin`). A domain like `pangolin.net`, which includes a dot, is acceptable. Instead of a single-label domain, you should consider using a subdomain of a domain you control, such as `router.mywebsite.com`, or an existing private/internal domain name, like `router.internal` or `router.corp`.
## 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` which will forward request to an upstream server. By default, we use `9.9.9.9`, but this upstream address can be configured using [the flag](/manage/clients/configure-client) in the cli / olm or in the client settings.
## 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 [the flag](/manage/clients/configure-client) to the cli / olm or disable override dns in the client settings.

4
manage/resources/private/cidr.mdx
View File

@@ -1,4 +0,0 @@
---
title: "CIDRs"
description: "Provide access to an entire network range"
---

27
manage/resources/private/destinations.mdx Normal file
View File

@@ -0,0 +1,27 @@
---
title: "Destinations"
description: "Understand connection options to the remote network"
---
A Resource's **destination** can be defined in several ways:
* **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`.
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.
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.
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.
### 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.
### What about overlaps?
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.

15
manage/resources/private/host.mdx
View File

@@ -1,15 +0,0 @@
---
title: "Hosts"
description: "Provide access to a specific host on the network"
---
### What about overlaps?
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.

4
manage/resources/private/overview.mdx
View File

@@ -1,4 +0,0 @@
---
title: "Overview"
description: "Private resources are only accessible when connected with a Pangolin client"
---

2
manage/resources/understanding-resources.mdx
View File

@@ -41,7 +41,7 @@ HTTP resources are also identity and context aware, meaning you can create polic
Raw resources are a way to proxy any TCP and UDP traffic through the Pangolin reverse proxy. Instead of a fully qualified domain name and certificate, these resources are bound to one or more ports on the Pangolin host.
Since these resources are not protocol aware and are publically proxied, they do not support identity and context policies and rules.
Since these resources are not protocol aware and are publicly proxied, they do not support identity and context policies and rules.
### Private Resources

20
manage/sites/configure-site.mdx
View File

@@ -351,7 +351,7 @@ Default locations:
- **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json`
- **Linux/Others**: `~/.config/newt-client/config.json`
### Docker Socket Integration
## Docker Socket Integration
Newt can integrate with the Docker socket to provide remote inspection of Docker containers. This allows Pangolin to query and retrieve detailed information about containers running on the Newt client, including metadata, network configuration, port mappings, and more.
@@ -398,7 +398,7 @@ services:
If the Docker socket is not available or accessible, Newt will gracefully disable Docker integration and continue normal operation.
</Note>
#### Hostnames vs IPs
**Hostnames vs IPs**
When the Docker Socket Integration is used, depending on the network which Newt is run with, either the hostname (generally considered the container name) or the IP address of the container will be sent to Pangolin:
@@ -407,19 +407,17 @@ When the Docker Socket Integration is used, depending on the network which Newt
- **Running in docker-compose without a network specification**: Docker compose creates a network for the compose by default, hostnames will be used
- **Running on docker-compose with defined network**: Hostnames will be used
#### Docker Enforce Network Validation
**Docker Enforce Network Validation**
When run as a Docker container, Newt can validate that the target being provided is on the same network as the Newt container and only return containers directly accessible by Newt. Validation will be carried out against either the hostname/IP Address and the Port number to ensure the running container is exposing the ports to Newt.
Validation is `false` by default. It can be enabled via setting the `--docker-enforce-network-validation` CLI argument or by setting the `DOCKER_ENFORCE_NETWORK_VALIDATION` environment variable.
<Warning>
If the Newt container is run with a network mode of `host`, this feature will not work. Running in `host` mode causes the container to share its resources with the host machine, making it impossible to retrieve specific host container information for network validation.
</Warning>
**Configuration:**
Validation is `false` by default. It can be enabled via setting the `--docker-enforce-network-validation` CLI argument or by setting the `DOCKER_ENFORCE_NETWORK_VALIDATION` environment variable.
### Updown Scripts
## Updown Scripts
You can pass in an updown script for Newt to call when it is adding or removing a target:
@@ -442,11 +440,11 @@ Returning a string from the script in the format of a target (`ip:dst` so `10.0.
You can look at `updown.py` as a reference script to get started!
</Note>
### mTLS Authentication
## mTLS Authentication
Newt supports mutual TLS (mTLS) authentication if the server is configured to request a client certificate. You can use either a PKCS12 (.p12/.pfx) file or split PEM files for the client cert, private key, and CA.
#### Option 1: PKCS12 (Legacy)
### Option 1: PKCS12 (Legacy)
<Note>
This is the original method and still supported.
@@ -469,7 +467,7 @@ newt \
--tls-client-cert ./client.p12
```
#### Option 2: Split PEM Files (Preferred)
### Option 2: Split PEM Files (Preferred)
You can now provide separate files for:

10
manage/sites/install-site.mdx
View File

@@ -37,7 +37,7 @@ Run Newt with the configuration from Pangolin:
newt \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
--endpoint https://app.pangolin.net
```
<Note>
The quick installer will do this step for you.
@@ -53,7 +53,7 @@ Description=Newt
After=network.target
[Service]
ExecStart=/usr/local/bin/newt --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com
ExecStart=/usr/local/bin/newt --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://app.pangolin.net
Restart=always
User=root
@@ -82,7 +82,7 @@ Run Newt with CLI arguments from Pangolin:
```bash
docker run -it fosrl/newt --id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
--endpoint https://app.pangolin.net
```
### Docker Compose
@@ -109,7 +109,7 @@ A safer but slightly more complex way is to use [Compose Secrets](https://docs.d
{
"id": "2ix2t8xk22ubpfy",
"secret": "nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2",
"endpoint": "https://example.com",
"endpoint": "https://app.pangolin.net",
"tlsClientCert": ""
}
```
@@ -145,7 +145,7 @@ services:
command:
- --id 31frd0uzbjvp721
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
- --endpoint https://example.com
- --endpoint https://app.pangolin.net
```
Start the service: