pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-10-06 20:59:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

update references from newt to pangolin site

Browse Source
This commit is contained in:
miloschwartz
2026-09-16 11:39:30 -04:00
parent 122f06f95a
commit 2f05e10c5d
23 changed files with 470 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files
manage/ssh.mdx
+50 -62
View File
@@ -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`.