mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-09-17 03:19:08 +02:00
update references from newt to pangolin site
This commit is contained in:
miloschwartz
@@ -176,6 +176,7 @@
|
||||
"group": "Organizations",
|
||||
"icon": "building",
|
||||
"pages": [
|
||||
"manage/organizations/manage-organizations",
|
||||
"manage/organizations/org-id",
|
||||
"manage/labels"
|
||||
]
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 487 KiB |
@@ -54,7 +54,7 @@ By default, when match domains are not set, all DNS queries are sent to the conf
|
||||
|
||||
#### 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 (Newt) 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.
|
||||
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.
|
||||
|
||||
@@ -5,7 +5,7 @@ description: "Improve Pangolin direct-connect success behind restrictive firewal
|
||||
|
||||
|
||||
|
||||
Most of the time, Pangolin works with existing firewall policies without any special tuning. Newt and Pangolin clients attempt NAT traversal first so traffic can flow directly between client and site. When direct connectivity cannot be established, traffic falls back to relaying through Gerbil. You can [learn more about how holepunching works here](https://pangolin.net/news/nat-holepunching).
|
||||
Most of the time, Pangolin works with existing firewall policies without any special tuning. Pangolin Sites and Pangolin Clients attempt NAT traversal first so traffic can flow directly between client and site. When direct connectivity cannot be established, traffic falls back to relaying through Gerbil. You can [learn more about how holepunching works here](https://pangolin.net/news/nat-holepunching).
|
||||
|
||||
For background on direct vs relayed paths and how to verify connection type, see [NAT Traversal](/manage/clients/nat-traversal).
|
||||
|
||||
@@ -15,9 +15,9 @@ The table below summarizes common behavior and practical mitigations reported by
|
||||
|
||||
| Firewall platform | Typical behavior with Pangolin | Practical workaround |
|
||||
| --- | --- | --- |
|
||||
| Barracuda | Often relayed | Increase available UDP session capacity; optionally allow a dedicated inbound Newt port |
|
||||
| Barracuda | Often relayed | Increase available UDP session capacity; optionally allow a dedicated inbound Pangolin Site port |
|
||||
| Check Point | Usually direct | No workaround typically required |
|
||||
| Cisco | Often relayed | Allow required UDP flows and, if needed, open a fixed Newt listening port |
|
||||
| Cisco | Often relayed | Allow required UDP flows and, if needed, open a fixed Pangolin Site listening port |
|
||||
| Cisco Umbrella Endpoint Security | Usually relayed | Endpoint filtering commonly prevents direct paths |
|
||||
| Fortinet | Often connects directly | No workaround typically required |
|
||||
| OPNsense | Often relayed by default | Disable hard NAT |
|
||||
@@ -30,7 +30,7 @@ If your firewall is not listed and connections are consistently relayed, start w
|
||||
|
||||
1. Confirm current path with `pangolin status` (CLI) or client status JSON (`isRelay`).
|
||||
2. Keep relaying enabled for reliability while testing firewall adjustments.
|
||||
3. If needed, pin Newt to a fixed listening port with `--port` / `PORT` and forward that port to the Newt host.
|
||||
3. If needed, pin the Pangolin Site to a fixed listening port with `--port` / `PORT` and forward that port to the Pangolin Site host.
|
||||
|
||||
## Platform notes
|
||||
|
||||
@@ -41,7 +41,7 @@ Barracuda environments commonly struggle with simultaneous UDP flows from multip
|
||||
What helps:
|
||||
|
||||
- Increase the firewall's maximum UDP session capacity [by increasing the max udp parameter](https://campus.barracuda.com/product/cloudgenfirewall/doc/95258827/general-firewall-configuration/?sl=AX5zwzvyOBUvMAhoTe4U&so=2)
|
||||
- If direct connectivity is still inconsistent, use a fixed Newt listening port and forward it explicitly.
|
||||
- If direct connectivity is still inconsistent, use a fixed Pangolin Site listening port and forward it explicitly.
|
||||
|
||||
### Check Point
|
||||
|
||||
|
||||
@@ -103,7 +103,7 @@ Pangolin Sites support NAT traversal so clients can connect directly without rel
|
||||
|
||||
In some environments, depending on the NAT type and firewall, you may need to tweak settings to get optimal connectivity in the firewall itself. See [Firewall Integrations](/manage/clients/firewalls) for Pangolin-specific guidance for common platforms.
|
||||
|
||||
Another option is to keep Newt listening for client connections on a static port. This allows you to open a specific port in your firewall for Newt client connections instead of random high ports. You can do this by setting the `--port` flag or `PORT` environment variable and then opening this port in your firewall to DNAT to Newt. See [Configure Sites](/manage/sites/configure-site) for the full list of Newt flags and environment variables.
|
||||
Another option is to keep the Pangolin Site listening for client connections on a static port. This allows you to open a specific port in your firewall for Pangolin Site client connections instead of random high ports. You can do this by setting the `--port` flag or `PORT` environment variable and then opening this port in your firewall to DNAT to the Pangolin Site. See [Configure Sites](/manage/sites/configure-site) for the full list of Pangolin Site flags and environment variables.
|
||||
|
||||
## FAQ
|
||||
|
||||
@@ -145,6 +145,6 @@ Another option is to keep Newt listening for client connections on a static port
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Do I need to open firewall ports for hole punching?">
|
||||
Not always. Many networks hole punch successfully without inbound rules. If punching is unreliable, try [Firewall Integrations](/manage/clients/firewalls) guidance or pin Newt to a static port with `--port` / `PORT` and DNAT that port to Newt on the site host.
|
||||
Not always. Many networks hole punch successfully without inbound rules. If punching is unreliable, try [Firewall Integrations](/manage/clients/firewalls) guidance or pin the Pangolin Site to a static port with `--port` / `PORT` and DNAT that port to the Pangolin Site host.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -24,7 +24,7 @@ Use the numeric ID when an endpoint asks for `siteId`, `resourceId`, or `siteRes
|
||||
|
||||
## Create site
|
||||
|
||||
This section assumes you're creating a **Newt** site. For all Site endpoints, see [Site API (Swagger)](https://api.pangolin.net/v1/docs/#/Site).
|
||||
This section assumes you're creating a **Pangolin Site**. For all Site endpoints, see [Site API (Swagger)](https://api.pangolin.net/v1/docs/#/Site).
|
||||
|
||||
**PUT** `/org/{orgId}/site`
|
||||
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
title: "Manage Organizations"
|
||||
description: "View every organization on a self-hosted instance from the server admin panel"
|
||||
---
|
||||
|
||||
The server admin panel is for the people who run a self-hosted Pangolin instance. It already includes a [master list of every user](/manage/access-control/create-user) on the server, across all organizations. Pangolin 1.23 adds the same kind of list for organizations.
|
||||
|
||||
## Organizations Table
|
||||
|
||||
Open **Server Admin → Organizations** to see every organization on the instance in one place. Each row shows the organization name, ID, owner, and counts for users, sites, and resources.
|
||||
|
||||
<Frame caption="Organizations table in the server admin panel, with name, ID, owner, and counts for users, sites, and resources.">
|
||||
<img src="/images/orgs-table.png" alt="Manage Organizations table in the Pangolin server admin panel" centered/>
|
||||
</Frame>
|
||||
|
||||
You can search the table and delete an organization from it.
|
||||
|
||||
## Visibility and Membership
|
||||
|
||||
Server admins can see this list even if they are not a member of an organization. That visibility is limited to the table. It does not add the server admin as a member, and it does not let them impersonate one.
|
||||
|
||||
To see an organization's contents in the dashboard, a server admin still has to be a member of that organization.
|
||||
@@ -6,10 +6,12 @@ Pangolin is multi-tenant. All sites, resources, clients, and other items belong
|
||||
|
||||
Each organization has a unique ID that Pangolin generates when you create the organization. You cannot change the ID after creation, and it is separate from the display name.
|
||||
|
||||
## Finding your organization ID
|
||||
## Finding Your Organization ID
|
||||
|
||||
You can find your organization ID in two ways:
|
||||
You can find your organization ID in these ways:
|
||||
|
||||
1. Check the general settings page for your organization. The ID appears at the top of the info card.
|
||||
|
||||
2. Check the URL path when viewing your dashboard. The org ID is the first slug in the URL. For example, in `https://app.pangolin.net/home-lab/settings/sites`, the org ID is `home-lab`.
|
||||
|
||||
3. On a self-hosted instance, as the server admin account, open the [organizations table](/manage/organizations/manage-organizations) in the server admin panel. The Organization ID column lists every org on the server.
|
||||
|
||||
@@ -231,15 +231,19 @@ This section uses AWS as an example, but the same steps apply to any VPC-style n
|
||||
|
||||
## Enable Native Routing on Your Sites
|
||||
|
||||
For the VPC and a site's network to route to each other, the tunnel needs to be a real route on the site's host, not just something Newt proxies at the application layer. Start Newt with `--native-main` so it creates the network interface and routes directly on the host:
|
||||
For the VPC and a site's network to route to each other, the tunnel needs to be a real route on the site's host, not just something the Pangolin Site proxies at the application layer. Start the site with `--native-main` so it creates the network interface and routes directly on the host:
|
||||
|
||||
```bash
|
||||
sudo newt --id 34s48my8iba5wsl --secret ts1v7480qqw01j7ba4uiw5y7l58skw7anpji2ndludhgzloh --endpoint https://app.pangolin.net --native-main
|
||||
sudo pangolin up site \
|
||||
--id 34s48my8iba5wsl \
|
||||
--secret ts1v7480qqw01j7ba4uiw5y7l58skw7anpji2ndludhgzloh \
|
||||
--endpoint https://app.pangolin.net \
|
||||
--native-main
|
||||
```
|
||||
|
||||
On Windows, set `nativeMain` in the Newt client's `config.json` instead:
|
||||
On Windows, set `nativeMain` in `C:\Users\<Username>\.config\pangolin\site.json` instead:
|
||||
|
||||
```json title="%PROGRAMDATA%/newt/newt-client/config.json"
|
||||
```json title="C:\Users\<Username>\.config\pangolin\site.json"
|
||||
{
|
||||
"id": "34s48my8iba5wsl",
|
||||
"secret": "ts1v7480qqw01j7ba4uiw5y7l58skw7anpji2ndludhgzloh",
|
||||
@@ -249,7 +253,7 @@ On Windows, set `nativeMain` in the Newt client's `config.json` instead:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
If you are using Newt on Windows `wintun.dll` is required to run in native mode. If not already provided by the installer, you can download from https://www.wintun.net/
|
||||
If you are using a Pangolin Site on Windows, `wintun.dll` is required to run in native mode. If not already provided by the installer, you can download from https://www.wintun.net/
|
||||
</Warning>
|
||||
|
||||
<Warning>
|
||||
|
||||
@@ -39,7 +39,7 @@ SSH private resources do **not** use discrete targets. Instead, you:
|
||||
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).
|
||||
**Pangolin SSH mode requires root.** The Pangolin Site must run as root on the site connector host. Use `sudo pangolin up site ...` or run the site service as root. See [Install Sites](/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).
|
||||
|
||||
@@ -35,7 +35,7 @@ SSH public resources do **not** use [targets](/manage/resources/public/targets).
|
||||
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).
|
||||
**Pangolin SSH mode requires root.** The Pangolin Site must run as root on the site connector host. Use `sudo pangolin up site ...` or run the site service as root. See [Install Sites](/manage/sites/install-site).
|
||||
</Warning>
|
||||
|
||||
Pangolin routes through the site that is online and healthiest, using the same intelligent multi-site routing model as [private resources](/manage/resources/private/multi-site-routing).
|
||||
|
||||
@@ -75,7 +75,7 @@ Load balancing between different targets only works when sites are connected to
|
||||
To ensure effective load balancing in multi-node environments:
|
||||
|
||||
```bash
|
||||
newt --prefer-endpoint <specific-endpoint> <other-args>
|
||||
pangolin up site --prefer-endpoint <specific-endpoint> <other-args>
|
||||
```
|
||||
|
||||
For a list of endpoints used on the cloud platform, take a look at `/manage/endpoints-and-pops#points-of-presence`.
|
||||
|
||||
@@ -0,0 +1,349 @@
|
||||
---
|
||||
title: "Install Newt"
|
||||
description: "Install Newt as a binary or Docker container"
|
||||
---
|
||||
|
||||
Newt is the lighter-weight site connector. It provides the same tunneling and NAT traversal as a Pangolin Site, without the rest of the [Pangolin CLI](/manage/sites/install-site) bundled in.
|
||||
|
||||
For new sites, install with the Pangolin CLI. Existing Newt deployments keep working. Leave them as they are, or switch to the CLI when you want to. Newt continues to be provided in all of its current forms. Use Newt directly when you need the smallest possible binary or container. The dashboard reports which agent a site is using, whether that is the CLI or Newt, and the version.
|
||||
|
||||
You must first create a site and copy the Newt config in Pangolin before running Newt.
|
||||
|
||||
<Note>
|
||||
Deploying Newt in Kubernetes instead? See the dedicated [Kubernetes](/manage/sites/kubernetes/helm) docs: install guides for [Helm](/manage/sites/kubernetes/helm) and [Kustomize](/manage/sites/kubernetes/kustomize), a full [Configuration](/manage/sites/kubernetes/configuration) reference, and [Troubleshooting](/manage/sites/kubernetes/troubleshooting).
|
||||
</Note>
|
||||
|
||||
## Binary Installation
|
||||
|
||||
### Quick Install (Recommended)
|
||||
|
||||
Use this command to automatically install Newt. It detects your system architecture automatically and always pulls the latest version, adding Newt to your PATH:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://static.pangolin.net/get-newt.sh | bash
|
||||
```
|
||||
|
||||
#### Windows
|
||||
|
||||
To run Newt on Windows, use the latest installer from [GitHub releases](https://github.com/fosrl/newt/releases/latest).
|
||||
|
||||
### Manual Download
|
||||
|
||||
Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/newt/releases/latest) for ARM and AMD64 (x86_64) architectures.
|
||||
|
||||
Download and install manually:
|
||||
|
||||
```bash
|
||||
wget -O newt "https://github.com/fosrl/newt/releases/download/{version}/newt_{architecture}" && chmod +x ./newt
|
||||
```
|
||||
|
||||
<Note>
|
||||
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/newt/releases) for the latest information.
|
||||
</Note>
|
||||
|
||||
### Running Newt
|
||||
|
||||
Run Newt with the configuration from Pangolin:
|
||||
|
||||
```bash
|
||||
newt \
|
||||
--id 31frd0uzbjvp721 \
|
||||
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
||||
--endpoint https://app.pangolin.net
|
||||
```
|
||||
|
||||
### Systemd Service
|
||||
|
||||
Create `/etc/newt/newt.env` with the initial values from your Pangolin site configuration:
|
||||
|
||||
```bash title="/etc/newt/newt.env"
|
||||
NEWT_ID=31frd0uzbjvp721
|
||||
NEWT_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
|
||||
PANGOLIN_ENDPOINT=https://app.pangolin.net
|
||||
```
|
||||
|
||||
Create the directory, write the file, and restrict its permissions:
|
||||
|
||||
```bash
|
||||
sudo install -d -m 0755 /etc/newt
|
||||
sudo editor /etc/newt/newt.env
|
||||
sudo chmod 600 /etc/newt/newt.env
|
||||
```
|
||||
|
||||
Then create a systemd service. Newt reads those environment variables automatically, so `ExecStart` does not need to repeat them as flags:
|
||||
|
||||
```ini title="/etc/systemd/system/newt.service"
|
||||
[Unit]
|
||||
Description=Newt
|
||||
Wants=network-online.target
|
||||
After=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=root
|
||||
Group=root
|
||||
EnvironmentFile=/etc/newt/newt.env
|
||||
ExecStart=/usr/local/bin/newt
|
||||
Restart=always
|
||||
RestartSec=2
|
||||
UMask=0077
|
||||
|
||||
PrivateTmp=true
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Make sure the binary exists at `/usr/local/bin/newt` before daemon reload and starting the service:
|
||||
|
||||
```bash
|
||||
which newt
|
||||
```
|
||||
</Warning>
|
||||
|
||||
Reload systemd and enable the service:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now newt
|
||||
sudo systemctl status newt
|
||||
```
|
||||
|
||||
If you later change `/etc/newt/newt.env`, restart the service so Newt picks up the new values.
|
||||
|
||||
See [Configure Sites](/manage/sites/configure-site) for more environment variables.
|
||||
|
||||
## Docker Installation
|
||||
|
||||
### Pull the Image
|
||||
|
||||
Pull the latest Newt image from Docker Hub:
|
||||
|
||||
```bash
|
||||
docker pull fosrl/newt:latest
|
||||
```
|
||||
|
||||
### Run with Docker
|
||||
|
||||
Run Newt with CLI arguments from Pangolin:
|
||||
|
||||
```bash
|
||||
docker run -it fosrl/newt --id 31frd0uzbjvp721 \
|
||||
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
||||
--endpoint https://app.pangolin.net
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
#### Environment Variables (Recommended)
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
newt:
|
||||
image: fosrl/newt
|
||||
container_name: newt
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- PANGOLIN_ENDPOINT=https://app.pangolin.net
|
||||
- NEWT_ID=2ix2t8xk22ubpfy
|
||||
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
|
||||
```
|
||||
|
||||
#### Config File Injected as Compose Secret
|
||||
|
||||
A safer but slightly more complex way is to use [Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/). First, create a `JSON` file containing your configuration:
|
||||
|
||||
```json title="newt-config.secret"
|
||||
{
|
||||
"id": "2ix2t8xk22ubpfy",
|
||||
"secret": "nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2",
|
||||
"endpoint": "https://app.pangolin.net",
|
||||
"tlsClientCert": ""
|
||||
}
|
||||
```
|
||||
|
||||
Then register and reference the secret in your `docker-compose.yml`:
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
newt:
|
||||
image: fosrl/newt
|
||||
container_name: newt
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- CONFIG_FILE=/run/secrets/newt-config
|
||||
secrets:
|
||||
- newt-config
|
||||
|
||||
secrets:
|
||||
newt-config:
|
||||
file: ./newt-config.secret
|
||||
```
|
||||
|
||||
This allows you to separate sensitive secrets from plain configuration, improving security when storing or sharing your `docker-compose.yml` anywhere else.
|
||||
|
||||
#### CLI Arguments
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
newt:
|
||||
image: fosrl/newt
|
||||
container_name: newt
|
||||
restart: unless-stopped
|
||||
command:
|
||||
- --id 31frd0uzbjvp721
|
||||
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
|
||||
- --endpoint https://app.pangolin.net
|
||||
```
|
||||
|
||||
#### Docker Healthcheck
|
||||
|
||||
Newt supports healthchecks as described in [Configure Sites](/manage/sites/configure-site#param-health-file). This file can be used to run a healthcheck from within Docker Compose.
|
||||
|
||||
Define the `HEALTH_FILE` environment variable as well as the healthcheck itself:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- HEALTH_FILE=/tmp/healthy
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "[ -f /tmp/healthy ]"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
start_period: 30s
|
||||
retries: 3
|
||||
```
|
||||
|
||||
Start the service:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Platform-Specific Installation
|
||||
|
||||
### Kubernetes
|
||||
|
||||
Running Newt in a Kubernetes cluster is covered separately from the Docker instructions above, since it uses a dedicated Helm chart rather than a plain `docker run` or Compose file. See:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Helm" href="/manage/sites/kubernetes/helm" icon="box">
|
||||
Quick-start guide for installing Newt with Helm.
|
||||
</Card>
|
||||
<Card title="Kustomize" href="/manage/sites/kubernetes/kustomize" icon="layer-group">
|
||||
Install Newt with rendered manifests and Kustomize overlays.
|
||||
</Card>
|
||||
<Card title="Configuration" href="/manage/sites/kubernetes/configuration" icon="sliders">
|
||||
Full configuration reference for Helm and Kustomize workflows.
|
||||
</Card>
|
||||
<Card title="Troubleshooting" href="/manage/sites/kubernetes/troubleshooting" icon="circle-question">
|
||||
Debug Newt deployment and connection issues in Kubernetes.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Unraid
|
||||
|
||||
Newt is available in the Unraid Community Applications store. Search for "Newt" and follow the installation prompts. Enter the ID, secret, and endpoint from Pangolin in the template fields.
|
||||
|
||||
<Frame caption="Newt available in Unraid Community Applications store">
|
||||
<img src="/images/unraid_store.png" alt="Newt on CA" />
|
||||
</Frame>
|
||||
|
||||
### Portainer and Other UIs
|
||||
|
||||
Container management UIs like Portainer typically allow passing commands and environment variables to containers similar to Docker Compose. Look for a commands or arguments configuration section and follow the relevant guides.
|
||||
|
||||
### Windows Service
|
||||
|
||||
On Windows, Newt can be run as a service or normally as a binary in a session.
|
||||
|
||||
When running as a binary and not installing the service, you can use the same CLI arguments as you would on any other platform.
|
||||
|
||||
If you are installing the service, we recommend writing the config into the config file location (`%PROGRAMDATA%\newt\newt-client\config.json`) first, following the [config file format](/manage/sites/install-newt#config-file-injected-as-compose-secret), with the provisioning key. Alternatively, you can install the service and start it with CLI args, which will also work. For example:
|
||||
|
||||
```
|
||||
newt install
|
||||
newt start --endpoint https://app.pangolin.net --provisioning-key <provisioning-key>
|
||||
```
|
||||
|
||||
This will provision a new service, start it, and create the config file for future starts.
|
||||
|
||||
#### Service Management Commands
|
||||
|
||||
```
|
||||
# Install the service
|
||||
newt.exe install
|
||||
|
||||
# Start the service
|
||||
newt.exe start
|
||||
|
||||
# Stop the service
|
||||
newt.exe stop
|
||||
|
||||
# Check service status
|
||||
newt.exe status
|
||||
|
||||
# Remove the service
|
||||
newt.exe remove
|
||||
|
||||
# Show help
|
||||
newt.exe service-help
|
||||
```
|
||||
|
||||
Note running the service requires credentials in `%PROGRAMDATA%\newt\newt-client\config.json`.
|
||||
|
||||
#### Service Configuration
|
||||
|
||||
When running as a service, Newt will read configuration from environment variables or you can modify the service to include command-line arguments:
|
||||
|
||||
1. Install the service: `newt.exe install`
|
||||
2. Set the credentials in `%PROGRAMDATA%\newt\newt-client\config.json`. Hint: if you run Newt once with `--id` and `--secret` this file will be populated.
|
||||
3. Start the service: `newt.exe start`
|
||||
|
||||
#### Service Logs
|
||||
|
||||
When running as a service, logs are written to:
|
||||
|
||||
- Windows Event Log (Application log, source: "newtWireguardService")
|
||||
- Log files in: `%PROGRAMDATA%\newt\logs\newt.log`
|
||||
|
||||
You can view the Windows Event Log using Event Viewer or PowerShell:
|
||||
|
||||
```powershell
|
||||
Get-EventLog -LogName Application -Source "newtWireguardService" -Newest 10
|
||||
```
|
||||
|
||||
### Advantech Router App
|
||||
|
||||
Download the correct version of the router app for your device from the [GitHub releases](https://github.com/fosrl/newt/releases/latest). You can find more information about router apps along with the right version information for your hardware on the [Advantech engineering portal](https://icr.advantech.com/products/software/router-apps).
|
||||
|
||||
To install the router app, log into your Advantech router and navigate to the Router Apps section. Upload the downloaded `.tgz` file and follow the prompts to install.
|
||||
|
||||
<Frame caption="Screenshot of installing the router app on an Advantech router UI">
|
||||
<img src="/images/advantech_router_app_install.png" alt="Advantech router UI showing Newt router app installation" width="400" centered/>
|
||||
</Frame>
|
||||
|
||||
After installation, click on the router app link at the top of the page to configure the app with your Newt credentials from Pangolin. Once you have entered the credentials, save and start the app. The router will now be connected to your Pangolin site and you can manage it like any other Newt site in the dashboard.
|
||||
|
||||
<Frame caption="Screenshot of configuring the router app on an Advantech router UI">
|
||||
<img src="/images/advantech_router_app_configure.png" alt="Advantech router UI showing Newt credential configuration" width="400" centered/>
|
||||
</Frame>
|
||||
|
||||
A complete config file is located at `/etc/newt/settings` on the router. You can edit this file directly to change credentials or add additional configuration options. After making changes, restart the router app to apply the new configuration. An example settings file can be found at: https://github.com/fosrl/newt/blob/main/packages/advantech/merge/etc/defaults
|
||||
|
||||
## Updating Newt
|
||||
|
||||
If you used the auto installer, run it again to pull the latest version:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://static.pangolin.net/get-newt.sh | bash
|
||||
```
|
||||
|
||||
For Docker, pull the latest image and recreate the container:
|
||||
|
||||
```bash
|
||||
docker pull fosrl/newt:latest
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Find release notes and manual binaries in the [GitHub releases](https://github.com/fosrl/newt/releases).
|
||||
@@ -5,7 +5,11 @@ description: "Install the site connector as a binary or Docker container"
|
||||
|
||||
The site connector can be installed as either a static binary executable or a Docker container via the CLI. You must first create a site and copy the ID and secret config from Pangolin before running it.
|
||||
|
||||
## Binary Installation
|
||||
<Note>
|
||||
The Pangolin CLI is the recommended way to install a new site. Existing Newt deployments keep working. For Newt-specific install commands, see [Install Newt](/manage/sites/install-newt).
|
||||
</Note>
|
||||
|
||||
## Binary Installation (Linux, macOS, Windows)
|
||||
|
||||
### Install
|
||||
|
||||
@@ -195,7 +199,8 @@ services:
|
||||
- --endpoint https://app.pangolin.net
|
||||
```
|
||||
|
||||
#### Docker healthcheck
|
||||
#### Docker Healthcheck
|
||||
|
||||
The site connector supports healthchecks as described in [Configure Sites](/manage/sites/configure-site#param-health-file). This file can be used to do a
|
||||
healthcheck from within docker (compose file).
|
||||
|
||||
@@ -242,28 +247,6 @@ Running a site in a Kubernetes cluster is covered separately from the Docker ins
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Unraid
|
||||
### Newt
|
||||
|
||||
Newt is available in the Unraid Community Applications store. Search for "Newt" and follow the installation prompts. Enter the ID, secret, and endpoint from Pangolin in the template fields.
|
||||
|
||||
<Frame caption="Newt available in Unraid Community Applications store">
|
||||
<img src="/images/unraid_store.png" alt="Newt on CA" />
|
||||
</Frame>
|
||||
|
||||
### Advantech Router App
|
||||
|
||||
Download the correct version of the router app for your device from the [GitHub releases](https://github.com/fosrl/newt/releases/latest). You can find more information about router apps along with the right version information for your hardware on the the [Advantech engineering portal](https://icr.advantech.com/products/software/router-apps).
|
||||
|
||||
To install the router app, log into your Advantech router and navigate to the Router Apps section. Upload the downloaded `.tgz` file and follow the prompts to install.
|
||||
|
||||
<Frame caption="Screenshot of installing the router app on an Advantech router UI">
|
||||
<img src="/images/advantech_router_app_install.png" alt="Advantech router UI showing site router app installation" width="400" centered/>
|
||||
</Frame>
|
||||
|
||||
After installation, click on the router app link at the top of the page to configure the app with your site credentials from Pangolin. Once you have entered the credentials, save and start the app. The router will now be connected to your Pangolin site and you can manage it like any other site in the dashboard.
|
||||
|
||||
<Frame caption="Screenshot of configuring the router app on an Advantech router UI">
|
||||
<img src="/images/advantech_router_app_configure.png" alt="Advantech router UI showing site credential configuration" width="400" centered/>
|
||||
</Frame>
|
||||
|
||||
A complete config file is located at `/etc/newt/settings` on the router. You can edit this file directly to change credentials or add additional configuration options. After making changes, restart the router app to apply the new configuration. An example settings file can be found at: https://github.com/fosrl/newt/blob/main/packages/advantech/merge/etc/defaults
|
||||
Unraid, Advantech routers, Windows services, and other Newt-only install methods are documented on [Install Newt](/manage/sites/install-newt). Use Newt when you want the smaller standalone connector instead of the Pangolin CLI.
|
||||
|
||||
@@ -4,7 +4,7 @@ description: "Create a site to connect to a remote network and expose resources"
|
||||
---
|
||||
A site is a connection to a network where your resources live. Pangolin uses sites to make public and private resources available to users. Every resource belongs to one or more sites.
|
||||
|
||||
A Pangolin Site is the software connector that establishes this connection and routes traffic to targets on remote networks. In engineering contexts, and in some install commands, it is sometimes referred to as Newt.
|
||||
A Pangolin Site is the software connector that establishes this connection and routes traffic to targets on remote networks. In engineering contexts, and in some install commands, it is sometimes referred to as Newt. New installs should use the [Pangolin CLI](/manage/sites/install-site). Newt remains available as a [standalone connector](/manage/sites/install-newt) if you want a smaller binary or container.
|
||||
|
||||
## The Basics
|
||||
|
||||
@@ -17,13 +17,13 @@ A Pangolin Site is the software connector that establishes this connection and r
|
||||
|
||||
Pangolin supports three different types of sites, each designed for different use cases and deployment scenarios.
|
||||
|
||||
### Site Connector (Recommended)
|
||||
### Pangolin Site (Recommended)
|
||||
|
||||
This site type exposes resources on a remote network through a managed tunnel and websocket connection. It requires the Pangolin Site connector on the remote network. This is the easiest setup and does not require NAT configuration.
|
||||
|
||||
Use Pangolin Sites in most deployments. This is the primary site type and supports the broadest feature set.
|
||||
|
||||
Pangolin Sites support:
|
||||
Pangolin Sites support (not limited to):
|
||||
- Public proxied resources
|
||||
- Protocol awareness (HTTP/HTTPS, SSH, RDP, VNC)
|
||||
- Private resources (ZTNA)
|
||||
@@ -32,7 +32,6 @@ Pangolin Sites support:
|
||||
- Docker socket scanning
|
||||
- And more
|
||||
|
||||
|
||||
### Local Site
|
||||
|
||||
Use this to expose resources on the same host as your Pangolin server (self-hosted only). No tunnels are created. Required ports must be open on the Pangolin host.
|
||||
|
||||
@@ -6,6 +6,10 @@ The update process depends on how you originally installed the site.
|
||||
|
||||
Find the latest version in the [GitHub releases](https://github.com/fosrl/cli/releases).
|
||||
|
||||
<Note>
|
||||
If you installed Newt instead of the Pangolin CLI, see [Install Newt](/manage/sites/install-newt) for Newt-specific commands.
|
||||
</Note>
|
||||
|
||||
## Docker Installation
|
||||
|
||||
Update the image version in your `docker-compose.yml`:
|
||||
|
||||
+50
-62
@@ -18,17 +18,17 @@ This page explains the configuration options shared by both resource types, give
|
||||
|
||||
## Default Configuration (Easiest)
|
||||
|
||||
When you create an SSH resource, the dashboard defaults to **Pangolin SSH** mode with **Manual Authentication**. This is the easiest path-it works out of the box with no auth daemon, no OpenSSH reconfiguration, and no extra host setup beyond running Newt as root.
|
||||
When you create an SSH resource, the dashboard defaults to **Pangolin SSH** mode with **Manual Authentication**. This is the easiest path. It works out of the box. You do not need an auth daemon, OpenSSH reconfiguration, or extra host setup beyond running the Pangolin Site as root.
|
||||
|
||||
With these defaults:
|
||||
|
||||
1. Create the SSH resource and select a site where Newt runs as root on the machine you want to access.
|
||||
1. Create the SSH resource and select a site where the Pangolin Site runs as root on the machine you want to access.
|
||||
2. Leave mode as **Pangolin SSH** and authentication as **Manual Authentication**.
|
||||
3. Users connect and authenticate with credentials that already exist on that host.
|
||||
|
||||
On a [public resource](/manage/resources/public/ssh), users visit the resource FQDN, complete Pangolin authentication, then enter their host username and password (or private key) in the browser form. On a [private resource](/manage/resources/private/ssh), users connect with the Pangolin client and run `pangolin ssh username@<alias>`-Pangolin prompts for the host password. To use a private key instead, pass it with `-i`: `pangolin ssh username@<alias> -i <key-file>`.
|
||||
|
||||
That is the entire setup for the default preset. If you need Pangolin identities provisioned automatically on the host-without password prompts-switch to **Automated Provisioning**. With **Pangolin SSH** mode, that also works without OpenSSH or auth daemon configuration-Newt still must run as root. With **Standard SSH Server** mode, follow the host setup sections below.
|
||||
That is the entire setup for the default preset. If you need Pangolin identities provisioned automatically on the host, without password prompts, switch to **Automated Provisioning**. With **Pangolin SSH** mode, that also works without OpenSSH or auth daemon configuration. The Pangolin Site still must run as root. With **Standard SSH Server** mode, follow the host setup sections below.
|
||||
|
||||
## Configuration Options
|
||||
|
||||
@@ -38,15 +38,16 @@ SSH resources are configured through three decisions in the dashboard.
|
||||
|
||||
| Option | Description |
|
||||
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Pangolin SSH (Recommended)** | Executes commands directly on the host via the site connector. No network SSH server is required, and you do not enter a host or port. Newt must run as the [binary](/manage/sites/install-site#binary-installation) on the host as root (`sudo newt ...`). Containerized installs are not supported-sessions may open the container shell instead of the host. |
|
||||
| **Pangolin SSH (Recommended)** | Executes commands directly on the host via the site connector. A network SSH server is not required, and you do not enter a host or port. The Pangolin Site must run as the [binary](/manage/sites/install-site#binary-installation) on the host as root (`sudo pangolin up site ...`). Containerized installs are not supported; sessions may open the container shell instead of the host. |
|
||||
| **Standard SSH Server** | Routes commands over the network to an SSH server such as OpenSSH. Enter the backend host and port. To use automated provisioning (PAM) with this mode, you must configure OpenSSH to accept Pangolin certificates and connections. This mode also supports a remote auth daemon for pushing users to machines on the same network as the site connector that are not running the connector itself. |
|
||||
|
||||
<Warning>
|
||||
**Pangolin SSH mode requires the Newt binary on the host.** Install Newt as
|
||||
a [binary on the site connector
|
||||
**Pangolin SSH mode requires the Pangolin Site binary on the host.** Install
|
||||
the site as a [binary on the site connector
|
||||
host](/manage/sites/install-site#binary-installation) and run it as root
|
||||
(`sudo newt ...` or a root systemd service). If Newt runs in a container,
|
||||
SSH sessions may drop you into the container shell rather than the host.
|
||||
(`sudo pangolin up site ...` or a root site service). If the site runs in a
|
||||
container, SSH sessions may drop you into the container shell rather than
|
||||
the host.
|
||||
</Warning>
|
||||
|
||||
### Authentication Method
|
||||
@@ -67,7 +68,7 @@ Only shown when **Automated Provisioning** is selected.
|
||||
|
||||
### Daemon Port
|
||||
|
||||
When the auth daemon runs on a remote host, set the port it listens on (default `22123`). This must match the `--port` flag used when starting the auth daemon. Newt and the auth daemon communicate over HTTPS on this port within your internal network.
|
||||
When the auth daemon runs on a remote host, set the port it listens on (default `22123`). This must match the `--port` flag used when starting the auth daemon. The Pangolin Site and the auth daemon communicate over HTTPS on this port within your internal network.
|
||||
|
||||
<Warning>
|
||||
Ensure your target host is properly configured to run the auth daemon before
|
||||
@@ -84,9 +85,9 @@ There are five valid configuration combinations. Auth daemon location is not app
|
||||
|
||||
**When to use:** You want the simplest setup. The site connector runs on the machine you need to access, and users already have local accounts with passwords or keys on that host.
|
||||
|
||||
**Example:** A small team exposes a staging server that runs Newt. You create a public SSH resource with Pangolin SSH and manual authentication. Developers visit `https://staging-ssh.example.com`, pass Pangolin login, then enter their existing Linux username and password in the browser form. No OpenSSH reconfiguration or auth daemon is needed on the host-run Newt as root.
|
||||
**Example:** A small team exposes a staging server that runs a Pangolin Site. You create a public SSH resource with Pangolin SSH and manual authentication. Developers visit `https://staging-ssh.example.com`, pass Pangolin login, then enter their existing Linux username and password in the browser form. OpenSSH reconfiguration and an auth daemon are not needed on the host. Run the Pangolin Site as root.
|
||||
|
||||
**Host setup required:** Run Newt as root on the site connector host (`sudo newt ...`).
|
||||
**Host setup required:** Run the Pangolin Site as root on the site connector host (`sudo pangolin up site ...`).
|
||||
|
||||
---
|
||||
|
||||
@@ -96,9 +97,9 @@ There are five valid configuration combinations. Auth daemon location is not app
|
||||
|
||||
**When to use:** The site connector runs on the machine you want to access, and you want Pangolin identities mapped to local users automatically-no password prompts and no separate SSH server routing.
|
||||
|
||||
**Example:** Your production app server runs Newt. You create a private SSH resource with an alias `prod-app.internal` and configure Pangolin SSH with automated provisioning on site. Developers connect with the Pangolin client and run `pangolin ssh prod-app.internal`. Pangolin provisions their account on the fly from their organization identity.
|
||||
**Example:** Your production app server runs a Pangolin Site. You create a private SSH resource with an alias `prod-app.internal` and configure Pangolin SSH with automated provisioning on site. Developers connect with the Pangolin client and run `pangolin ssh prod-app.internal`. Pangolin provisions their account on the fly from their organization identity.
|
||||
|
||||
**Host setup required:** Run Newt as root on the site connector host. Pangolin SSH handles provisioning through the site connector directly.
|
||||
**Host setup required:** Run the Pangolin Site as root on the site connector host. Pangolin SSH handles provisioning through the site connector directly.
|
||||
|
||||
---
|
||||
|
||||
@@ -120,9 +121,9 @@ There are five valid configuration combinations. Auth daemon location is not app
|
||||
|
||||
**When to use:** OpenSSH runs on the same machine as the site connector, but you want network SSH routing (Standard SSH Server mode) with Pangolin identity provisioning instead of Pangolin SSH mode.
|
||||
|
||||
**Example:** Newt runs on your production app server. OpenSSH also listens on that host. You create a private SSH resource with destination `localhost`, allow TCP 22 in [port restrictions](/manage/resources/private/port-restrictions), and assign an alias such as `prod-app.internal`. Configure Standard SSH Server mode pointing at `127.0.0.1:22`, automated provisioning, and auth daemon on site. Engineers run `pangolin ssh prod-app.internal` and land on the same machine running Newt with a provisioned account.
|
||||
**Example:** A Pangolin Site runs on your production app server. OpenSSH also listens on that host. You create a private SSH resource with destination `localhost`, allow TCP 22 in [port restrictions](/manage/resources/private/port-restrictions), and assign an alias such as `prod-app.internal`. Configure Standard SSH Server mode pointing at `127.0.0.1:22`, automated provisioning, and auth daemon on site. Engineers run `pangolin ssh prod-app.internal` and land on the same machine running the Pangolin Site with a provisioned account.
|
||||
|
||||
**Host setup required:** Run Newt and configure OpenSSH on the same host. Newt runs as an auth daemon by default. No extra flag is needed. See [Option 1](#option-1-newt-as-the-auth-daemon-same-host).
|
||||
**Host setup required:** Run the Pangolin Site and configure OpenSSH on the same host. The site runs as an auth daemon by default. An extra flag is not needed. See [Option 1](#option-1-pangolin-site-as-the-auth-daemon-same-host).
|
||||
|
||||
---
|
||||
|
||||
@@ -130,11 +131,11 @@ There are five valid configuration combinations. Auth daemon location is not app
|
||||
|
||||
**Settings:** Mode = Standard SSH Server · Authentication = Automated Provisioning · Auth Daemon = On Remote Host
|
||||
|
||||
**When to use:** The site connector runs on a bastion, and you need to SSH into multiple other servers on the same network that do not run Newt. This is the most common automated provisioning setup for multi-server environments.
|
||||
**When to use:** The site connector runs on a bastion, and you need to SSH into multiple other servers on the same network that do not run a Pangolin Site. This is the most common automated provisioning setup for multi-server environments.
|
||||
|
||||
**Example:** Newt runs on `bastion.corp.internal`. You have application servers `app-01` and `app-02` on the same VLAN. For `app-01`, you create a private SSH resource with destination `10.0.5.21` (the IP of the OpenSSH server on the remote host), allow TCP 22 in [port restrictions](/manage/resources/private/port-restrictions), and assign alias `app-01.corp.internal` as the domain name users connect with. Configure Standard SSH Server mode with host `10.0.5.21:22`, automated provisioning, and auth daemon on remote host (daemon port `22123`). Each app server runs `pangolin auth-daemon`. Developers run `pangolin ssh app-01.corp.internal`-the client tunnels through Newt, which proxies SSH to the OpenSSH server and coordinates with the auth daemon on that host to provision the user.
|
||||
**Example:** A Pangolin Site runs on `bastion.corp.internal`. You have application servers `app-01` and `app-02` on the same VLAN. For `app-01`, you create a private SSH resource with destination `10.0.5.21` (the IP of the OpenSSH server on the remote host), allow TCP 22 in [port restrictions](/manage/resources/private/port-restrictions), and assign alias `app-01.corp.internal` as the domain name users connect with. Configure Standard SSH Server mode with host `10.0.5.21:22`, automated provisioning, and auth daemon on remote host (daemon port `22123`). Each app server runs `pangolin auth-daemon`. Developers run `pangolin ssh app-01.corp.internal`. The client tunnels through the Pangolin Site, which proxies SSH to the OpenSSH server and coordinates with the auth daemon on that host to provision the user.
|
||||
|
||||
**Host setup required:** Newt on the bastion with a pre-shared key, auth daemon on each target host, OpenSSH configured on each target. See [Option 2: External auth daemon](#option-2-external-auth-daemon-ssh-on-another-server-that-doesnt-run-newt).
|
||||
**Host setup required:** Pangolin Site on the bastion with a pre-shared key, auth daemon on each target host, OpenSSH configured on each target. See [Option 2: External Auth Daemon](#option-2-external-auth-daemon-ssh-on-another-server-that-does-not-run-a-pangolin-site).
|
||||
|
||||
---
|
||||
|
||||
@@ -160,22 +161,22 @@ This gives short-lived, auditable access without long-lived keys on the server.
|
||||
|
||||
When using **Standard SSH Server** with automated provisioning, users are provisioned **just in time** on the remote system. When you connect, Pangolin ensures an account exists for you with the right permissions before the SSH session starts. Your Pangolin identity is mapped to a local username (derived from the part before `@` in your identity; if needed, a suffix is added for uniqueness). The account is created with a home directory and can be granted sudo access as configured.
|
||||
|
||||
With **Pangolin SSH** and automated provisioning, Pangolin handles user provisioning through the site connector directly-no OpenSSH or auth daemon setup required on the host. Newt must still run as root.
|
||||
With **Pangolin SSH** and automated provisioning, Pangolin handles user provisioning through the site connector directly. OpenSSH and auth daemon setup are not required on the host. The Pangolin Site must still run as root.
|
||||
|
||||
## Host Setup
|
||||
|
||||
Host setup is only required for **Standard SSH Server** mode with **Automated Provisioning**. **Pangolin SSH** mode (manual or automated) requires Newt to run as root on the site connector host but does not require OpenSSH or auth daemon configuration.
|
||||
Host setup is only required for **Standard SSH Server** mode with **Automated Provisioning**. **Pangolin SSH** mode (manual or automated) requires the Pangolin Site to run as root on the site connector host but does not require OpenSSH or auth daemon configuration.
|
||||
|
||||
| Configuration | Setup path |
|
||||
| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
|
||||
| Standard SSH Server + Automated + On Site | [Option 1](#option-1-newt-as-the-auth-daemon-same-host) |
|
||||
| Standard SSH Server + Automated + On Remote Host | [Option 2](#option-2-external-auth-daemon-ssh-on-another-server-that-doesnt-run-newt) |
|
||||
| Standard SSH Server + Automated + On Site | [Option 1](#option-1-pangolin-site-as-the-auth-daemon-same-host) |
|
||||
| Standard SSH Server + Automated + On Remote Host | [Option 2](#option-2-external-auth-daemon-ssh-on-another-server-that-does-not-run-a-pangolin-site) |
|
||||
|
||||
Before setting up the host, create the SSH resource (public or private) in the dashboard, grant access, and for private resources allow TCP 22 in [port restrictions](/manage/resources/private/port-restrictions).
|
||||
|
||||
## Option 1: Newt as the auth daemon (same host)
|
||||
## Option 1: Pangolin Site as the Auth Daemon (Same Host)
|
||||
|
||||
Use this for combination **4**-when the auth daemon runs on the site connector host and you are routing to OpenSSH in Standard SSH Server mode.
|
||||
Use this for combination **4**, when the auth daemon runs on the site connector host and you are routing to OpenSSH in Standard SSH Server mode.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -189,21 +190,21 @@ flowchart LR
|
||||
|
||||
subgraph server["Single server (site)"]
|
||||
direction TB
|
||||
Newt[Newt + auth-daemon]
|
||||
Site[Pangolin Site + auth-daemon]
|
||||
SSHD[SSH server]
|
||||
Newt --> SSHD
|
||||
Site --> SSHD
|
||||
end
|
||||
|
||||
CLI -->|Request signed cert| CA
|
||||
CLI -->|SSH port 22| SSHD
|
||||
```
|
||||
|
||||
### Run Newt
|
||||
### Run the Pangolin Site
|
||||
|
||||
With Newt [installed](/manage/sites/install-site), run it normally. Newt runs as an auth daemon by default:
|
||||
With the Pangolin Site [installed](/manage/sites/install-site), run it normally. The site runs as an auth daemon by default:
|
||||
|
||||
```bash
|
||||
sudo newt --id <id> --secret <secret> --endpoint <endpoint>
|
||||
sudo pangolin up site --id <id> --secret <secret> --endpoint <endpoint>
|
||||
```
|
||||
|
||||
<Note>
|
||||
@@ -212,9 +213,9 @@ Replace `<id>`, `<secret>`, and `<endpoint>` with the values from your site conf
|
||||
|
||||
Then configure the SSH server on this host as described in [Configure the SSH server on the host](#configure-the-ssh-server-on-the-host).
|
||||
|
||||
## Option 2: External auth daemon (SSH on another server that doesn't run Newt)
|
||||
## Option 2: External Auth Daemon (SSH on Another Server That Does Not Run a Pangolin Site)
|
||||
|
||||
Use this for combination **5**-when the site connector is a bastion and each target host runs its own auth daemon.
|
||||
Use this for combination **5**, when the site connector is a bastion and each target host runs its own auth daemon.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -227,7 +228,7 @@ flowchart LR
|
||||
end
|
||||
|
||||
subgraph bastion["Bastion / site host"]
|
||||
Newt[Newt]
|
||||
Site[Pangolin Site]
|
||||
end
|
||||
|
||||
subgraph target["Target server"]
|
||||
@@ -238,22 +239,22 @@ flowchart LR
|
||||
end
|
||||
|
||||
CLI -->|Request signed cert| CA
|
||||
CLI -->|SSH port 22| Newt
|
||||
Newt -->|SSH to target| SSHD
|
||||
Newt <-->|Extension, port 22123| AuthDaemon
|
||||
CLI -->|SSH port 22| Site
|
||||
Site -->|SSH to target| SSHD
|
||||
Site <-->|Extension, port 22123| AuthDaemon
|
||||
```
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Newt** running on one host (the site / bastion) with a pre-shared key for external auth daemons.
|
||||
- **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).
|
||||
|
||||
### Step 1: On the server running Newt
|
||||
### Step 1: On the Server Running the Pangolin Site
|
||||
|
||||
Start Newt with a **pre-shared key** so external auth daemons can authenticate to it:
|
||||
Start the Pangolin Site with a **pre-shared key** so external auth daemons can authenticate to it:
|
||||
|
||||
```bash
|
||||
sudo newt --id <id> --secret <secret> --endpoint <endpoint> --ad-pre-shared-key <pre-shared-key>
|
||||
sudo pangolin up site --id <id> --secret <secret> --endpoint <endpoint> --ad-pre-shared-key <pre-shared-key>
|
||||
```
|
||||
|
||||
<Note>
|
||||
@@ -262,7 +263,7 @@ Choose a strong, random value for `<pre-shared-key>` and use the same value when
|
||||
|
||||
### Step 2: On each server you want to SSH into
|
||||
|
||||
On every host that should accept Pangolin SSH (and is not running Newt), run the auth daemon with the same pre-shared key:
|
||||
On every host that should accept Pangolin SSH (and is not running a Pangolin Site), run the auth daemon with the same pre-shared key:
|
||||
|
||||
```bash
|
||||
sudo pangolin auth-daemon --pre-shared-key <pre-shared-key>
|
||||
@@ -288,7 +289,7 @@ User=root
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Replace `<pre-shared-key>` with the same value used on Newt. If you use a custom port (set in the resource's SSH settings), add `--port <port>` to `ExecStart`. Then:
|
||||
Replace `<pre-shared-key>` with the same value used on the Pangolin Site. If you use a custom port (set in the resource's SSH settings), add `--port <port>` to `ExecStart`. Then:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
@@ -308,12 +309,12 @@ On each of these hosts, configure the SSH server as in [Configure the SSH server
|
||||
|
||||
### Step 4: Ensure network connectivity
|
||||
|
||||
- **Newt → auth daemon:** Newt must be able to reach the auth daemon port on each target server (default **TCP 22123**).
|
||||
- **Pangolin Site → auth daemon:** The Pangolin Site must be able to reach the auth daemon port on each target server (default **TCP 22123**).
|
||||
- **Clients → SSH:** Port **22** must be open for SSH to each target server.
|
||||
|
||||
<Warning>
|
||||
These ports do not need to be exposed to the public internet. They only need
|
||||
to be reachable within the network where Newt and the target servers live.
|
||||
to be reachable within the network where the Pangolin Site and the target servers live.
|
||||
</Warning>
|
||||
|
||||
## Configure the SSH server on the host
|
||||
@@ -322,20 +323,7 @@ For automated provisioning, the host's SSH server must trust the Pangolin CA and
|
||||
|
||||
### 1. Update `sshd_config`
|
||||
|
||||
Add or adjust these lines in `/etc/ssh/sshd_config`:
|
||||
|
||||
- **Auth daemon on this host (Newt):** use `newt auth-daemon principals` in the command.
|
||||
- **External auth daemon on this host:** use `pangolin auth-daemon principals` in the command.
|
||||
|
||||
Example for **auth daemon on site** (Newt on same host):
|
||||
|
||||
```ini title="/etc/ssh/sshd_config"
|
||||
TrustedUserCAKeys /etc/ssh/ca.pem
|
||||
AuthorizedPrincipalsCommand /usr/local/bin/newt auth-daemon principals --username %u
|
||||
AuthorizedPrincipalsCommandUser root
|
||||
```
|
||||
|
||||
Example for **external auth daemon on this host**:
|
||||
Add or adjust these lines in `/etc/ssh/sshd_config`. Use `pangolin auth-daemon principals` whether the auth daemon is the site process on this host or a standalone auth daemon:
|
||||
|
||||
```ini title="/etc/ssh/sshd_config"
|
||||
TrustedUserCAKeys /etc/ssh/ca.pem
|
||||
@@ -392,18 +380,18 @@ You can choose weather or not to allow the user to have a home directory configu
|
||||
|
||||
When the client requests a signed key from the Pangolin server, the certificate is valid for **5 minutes**. You must start the SSH connection within that window. Once the session is established, it can stay open.
|
||||
|
||||
### Is the SSH connection proxied through Newt?
|
||||
### Is the SSH Connection Proxied Through the Pangolin Site?
|
||||
|
||||
**Pangolin SSH mode or auth daemon on site:** Your client connects directly to the server that runs Newt; SSH traffic does not go through another hop.
|
||||
**Pangolin SSH mode or auth daemon on site:** Your client connects directly to the server that runs the Pangolin Site. SSH traffic does not go through another hop.
|
||||
|
||||
**Standard SSH Server + remote auth daemon:** Your client connects to Newt, and Newt proxies the SSH session to the target server. The auth daemon on each target is an extension of Newt.
|
||||
**Standard SSH Server + remote auth daemon:** Your client connects to the Pangolin Site, and the site proxies the SSH session to the target server. The auth daemon on each target is an extension of the Pangolin Site.
|
||||
|
||||
### How are usernames created on the remote server?
|
||||
|
||||
Pangolin derives the remote username from your Pangolin identity (the part before `@`). If that name is already taken in the organization, a numeric suffix is added until it is unique.
|
||||
|
||||
### How does Newt communicate with the external auth daemon?
|
||||
### How Does the Pangolin Site Communicate With the External Auth Daemon?
|
||||
|
||||
Newt talks to the auth daemon over **HTTPS** on **TCP 22123** by default. Port 22123 only needs to be open between Newt and the auth daemon hosts on your internal network.
|
||||
The Pangolin Site talks to the auth daemon over **HTTPS** on **TCP 22123** by default. Port 22123 only needs to be open between the Pangolin Site and the auth daemon hosts on your internal network.
|
||||
|
||||
To use a different port, set the port in the resource's SSH settings and pass the same port to the auth daemon with `--port`.
|
||||
|
||||
@@ -133,7 +133,7 @@ After making these changes, restart both Traefik and Pangolin for the configurat
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If websockets are not connecting like from newt or clients, ensure that websockets are enabled in Cloudflare:
|
||||
If websockets are not connecting from sites or clients, ensure that websockets are enabled in Cloudflare:
|
||||
|
||||
<Frame>
|
||||
<img src="/images/cf_websocket_box.png" alt="Cloudflare dashboard WebSockets setting toggled on" width="600" centered/>
|
||||
|
||||
@@ -233,7 +233,7 @@ If Pangolin can't reach the local Gerbil at the address in `--reachableAt` (a lo
|
||||
</Step>
|
||||
|
||||
<Step title="Write config.yml">
|
||||
`config.yml` holds the settings that legitimately differ per node - `gerbil.base_endpoint` and `gerbil.exit_node_name` - alongside the shared PostgreSQL connection and site-type restrictions. In clustered deployments, only Newt sites are supported, so local and basic WireGuard sites are disabled.
|
||||
`config.yml` holds the settings that legitimately differ per node - `gerbil.base_endpoint` and `gerbil.exit_node_name` - alongside the shared PostgreSQL connection and site-type restrictions. In clustered deployments, only Pangolin Sites are supported, so local and basic WireGuard sites are disabled.
|
||||
|
||||
Set `app.dashboard_url` and `server.cors.origins` to your dashboard domain (the one pointed at your load balancer, not at either node) - both must match on every node.
|
||||
|
||||
|
||||
@@ -103,7 +103,7 @@ dns:
|
||||
|
||||
- **Contact email** for Let's Encrypt ACME registration
|
||||
- **GeoIP databases** - download and keep up to date the MaxMind `GeoLite2-Country.mmdb` and `GeoLite2-ASN.mmdb` databases, placed in each node's `config/` directory. See [Enable Geo-location](/self-host/advanced/enable-geolocation) and [Enable ASN Lookup](/self-host/advanced/enable-asn-lookup)
|
||||
- **Site type support** - in clustered deployments, only Newt sites are supported. Local sites and basic WireGuard sites are not supported
|
||||
- **Site type support** - in clustered deployments, only Pangolin Sites are supported. Local sites and basic WireGuard sites are not supported
|
||||
|
||||
<Card title="Deploy a Cluster" href="/self-host/clustering/deploy-a-cluster" icon="server">
|
||||
Once these requirements are met, follow the full deployment walkthrough.
|
||||
|
||||
@@ -76,7 +76,7 @@ A Pangolin cluster consists of several coordinated components that work together
|
||||
|
||||
**How It Works**:
|
||||
- Each Pangolin instance runs alongside its own Gerbil tunnel manager
|
||||
- Handles WireGuard VPN connections from site connectors (Newt)
|
||||
- Handles WireGuard VPN connections from Pangolin Site connectors
|
||||
- Site connectors can establish tunnels to any available Gerbil instance
|
||||
- Every Gerbil instance is made aware of the other trusted nodes in the cluster
|
||||
- When a request lands on the node that isn't holding the relevant tunnel, Gerbil routes it to the correct node instead of dropping it - this covers the case where DNS caching sends a client to the "wrong" node
|
||||
|
||||
@@ -77,13 +77,13 @@ Pangolin requires these ports to be open on your VPS:
|
||||
<Card title="UDP Port 51820">
|
||||
**Site Tunnels**
|
||||
|
||||
This is the default port for sites (Newt) to establish tunnels to the proxy (Gerbil).
|
||||
This is the default port for Pangolin Sites to establish tunnels to the proxy.
|
||||
</Card>
|
||||
|
||||
<Card title="UDP Port 21820">
|
||||
**Client Tunnels**
|
||||
|
||||
This is the default port for clients relaying through Gerbil to newt. This port is only required for clients.
|
||||
This is the default port for clients relaying through the server to Pangolin Sites. This port is only required for clients.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
|
||||
@@ -888,7 +888,7 @@ pangolin:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
The Pangolin server does not apply Blueprint files directly. Blueprints are applied by Newt through the Pangolin API using `--blueprint-file` or `--provisioning-blueprint-file`.
|
||||
The Pangolin server does not apply Blueprint files directly. Blueprints are applied by Pangolin Sites through the Pangolin API using `--blueprint-file` or `--provisioning-blueprint-file`.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
Reference in New Issue
Block a user