docs: add new Access Control and Logs documentation pages
- Documented Access Control features (e.g., Device Approvals, Password Rotation, 2FA, Custom Login Pages). - Added detailed descriptions for Logs & Analytics (Access Logs, Request Logs, Action Logs). - Included configuration instructions and feature-specific notes for Pangolin Cloud and Enterprise Edition. Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
This commit is contained in:
@@ -0,0 +1,69 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Aliases
|
||||
|
||||
> Set a friendly alias hostname that resolves to a host
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
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.
|
||||
|
||||
## CIDRs Vs. IPs
|
||||
|
||||
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`.
|
||||
|
||||
### Wildcards
|
||||
|
||||
Wildcards allow you to define aliases that match multiple hostnames using special characters in the FQDN. For example,
|
||||
in an alias like `*.host-0?.autoco.internal`, the asterisk `*` matches any sequence of characters (including none), and
|
||||
the question mark `?` matches exactly one character.
|
||||
|
||||
If you use a wildcard such as `*.proxy.internal`, it will match any hostname that ends with `.proxy.internal` and has
|
||||
something before the dot—such as `host.proxy.internal`, `longerhost.proxy.internal`, or even `sub.host.proxy.internal`.
|
||||
However, the wildcard will not match the base domain itself (`autoco.internal` without anything before the dot).
|
||||
|
||||
## 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.
|
||||
|
||||
**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.
|
||||
|
||||
## 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.
|
||||
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Authentication
|
||||
|
||||
> Only allow access to Resources to specific users, roles, and machines
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
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.
|
||||
|
||||
<Frame>
|
||||
<img src="https://mintcdn.com/fossorial/8-sG5VqN31IT-DG8/images/private_access_controls.png?fit=max&auto=format&n=8-sG5VqN31IT-DG8&q=85&s=c699bff5743c4dea68ffa2f3837c0a41" centered data-og-width="689" width="689" data-og-height="397" height="397" data-path="images/private_access_controls.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/8-sG5VqN31IT-DG8/images/private_access_controls.png?w=280&fit=max&auto=format&n=8-sG5VqN31IT-DG8&q=85&s=ea28198255feaed591591b9ee40329b1 280w, https://mintcdn.com/fossorial/8-sG5VqN31IT-DG8/images/private_access_controls.png?w=560&fit=max&auto=format&n=8-sG5VqN31IT-DG8&q=85&s=1fa3d7b9484db080e597353a3d65259b 560w, https://mintcdn.com/fossorial/8-sG5VqN31IT-DG8/images/private_access_controls.png?w=840&fit=max&auto=format&n=8-sG5VqN31IT-DG8&q=85&s=0709ed67dfef3e6f935d36c09a5ec7ab 840w, https://mintcdn.com/fossorial/8-sG5VqN31IT-DG8/images/private_access_controls.png?w=1100&fit=max&auto=format&n=8-sG5VqN31IT-DG8&q=85&s=7f64a0d604f06f747b8414219fed84f0 1100w, https://mintcdn.com/fossorial/8-sG5VqN31IT-DG8/images/private_access_controls.png?w=1650&fit=max&auto=format&n=8-sG5VqN31IT-DG8&q=85&s=2aa31d04185e15cb0639ba251a0ab25a 1650w, https://mintcdn.com/fossorial/8-sG5VqN31IT-DG8/images/private_access_controls.png?w=2500&fit=max&auto=format&n=8-sG5VqN31IT-DG8&q=85&s=bb79b98218433aeb62e50f1099f1649f 2500w" />
|
||||
</Frame>
|
||||
|
||||
### 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.
|
||||
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
> ## Documentation Index
|
||||
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
|
||||
> Use this file to discover all available pages before exploring further.
|
||||
|
||||
# Destinations
|
||||
|
||||
> Understand connection options to the remote network
|
||||
|
||||
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
|
||||
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
|
||||
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
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.
|
||||
|
||||
### 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.
|
||||
|
||||
Reference in New Issue
Block a user