pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-07-16 19:09:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

update ssh docs

Browse Source
This commit is contained in:
miloschwartz
2026-04-20 11:40:20 -07:00
parent 354a76382c
commit aafbc1c6d2
2 changed files with 138 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
images/auth-daemon-location.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 277 KiB

250
manage/ssh.mdx
View File

@@ -54,99 +54,135 @@ Users are provisioned **just in time** on the remote system. When you connect, P
## Setup: choose your architecture
Newt can provide SSH access for its own host, for other hosts behind it, or for both at the same time.
You can enable SSH in two ways:
Before you begin:
| Scenario | Approach |
|----------|----------|
| SSH into the **same server** that runs Newt | **Option 1**: Run Newt with auth-daemon support (built-in). |
| SSH into **other servers** on the same network as Newt | **Option 2**: Run Newt on one host (e.g. bastion) and run the auth daemon on each server you want to SSH into. |
- Install Newt on the host that will run the site connector. See [Install Site](/manage/sites/install-site).
- Install the Pangolin CLI on any machine that will initiate `pangolin ssh` sessions. See [Install Clients](/manage/clients/install-client#quick-install-recommended-—-linux-and-macos).
A single Newt instance can run as **both** the auth daemon for its own host **and** use external auth daemons.
| Layout | Use this when | Newt flags |
|--------|---------------|------------|
| **Newt host only** | Users only need SSH access to the server running Newt | `--auth-daemon` |
| **Hosts behind Newt only** | Users only need SSH access to other servers on the same network as Newt | `--ad-pre-shared-key <pre-shared-key>` |
| **Mixed deployment** | Users need SSH access to the Newt host **and** to other servers behind it | `--auth-daemon --ad-pre-shared-key <pre-shared-key>` |
Both options require the SSH server on each target host to be configured to trust the Pangolin CA and to use the auth daemon for principals (see [Configure the SSH server](#configure-the-ssh-server-on-the-host) below). You also need a **private resource** on the site for each host you want to SSH into (see below).
<Note>
You do not need to choose a single site-wide SSH mode. A single Newt instance can handle **On Site** SSH access for the Newt host and also authenticate **Remote Host** SSH access for other target hosts.
</Note>
## Create a private resource (required)
## Understand the model
SSH access in both Option 1 and Option 2 is scoped to a private resource. You must create a private resource on the site for the host (or each host) you want to SSH into, then grant access and allow TCP 22.
The easiest way to think about SSH in Pangolin is:
1. **Create a private resource** on the site in the Pangolin dashboard. The resource should target the host that will run Newt (Option 1) or the host that will run the auth daemon (Option 2). Give it a destination (IP or FQDN of the server). You can use an [alias](/manage/resources/private/alias) (e.g. `vm-01.prod.example.com`) so users connect with a friendly name: `pangolin ssh vm-01.prod.example.com`.
1. Each SSH target gets its own **private resource**.
2. That resource decides **how Pangolin reaches that host**.
3. The host itself must be configured to match that resource.
2. **Grant access** to the resource by assigning **users** or **roles** in the resource’s access settings. Only users or roles with access can obtain SSH certificates and connect.
In a mixed deployment, you will create one resource for the Newt host and separate resources for each host behind Newt.
3. **Allow TCP 22 in port restrictions.** In the private resource’s port restrictions, ensure **TCP 22** is allowed so SSH traffic is permitted through the tunnel. Without this, SSH connections to the resource will be blocked.
## Start Newt for your layout
<Warning>
If TCP 22 is not allowed in the resource’s port restrictions, users will not be able to establish SSH sessions to that resource even when the rest of the setup is correct.
</Warning>
With Newt [installed](/manage/sites/install-site), start it with the flags that match your layout:
4. **Configure the auth daemon location.** On the SSH Access tab, select where the auth daemon is running. Is it on the Newt site itself (option 1) or a remote host (option 2)?
| Layout | Command |
|--------|---------|
| Newt host only | `sudo newt --id <id> --secret <secret> --endpoint <endpoint> --auth-daemon` |
| Hosts behind Newt only | `sudo newt --id <id> --secret <secret> --endpoint <endpoint> --ad-pre-shared-key <pre-shared-key>` |
| Mixed deployment | `sudo newt --id <id> --secret <secret> --endpoint <endpoint> --auth-daemon --ad-pre-shared-key <pre-shared-key>` |
<Frame caption="SSH Access tab on the private resource.">
<img src="/images/auth-daemon-location.png" alt="Pangolin Dashboard"/>
</Frame>
Relevant environment variables:
After the resource exists and access is granted, proceed with [Option 1](#option-1-newt-as-the-auth-daemon-same-host) or [Option 2](#option-2-external-auth-daemon-different-servers) below.
| Flag | Environment variable |
|------|----------------------|
| `--id` | `NEWT_ID` |
| `--secret` | `NEWT_SECRET` |
| `--endpoint` | `PANGOLIN_ENDPOINT` |
| `--auth-daemon` | `AUTH_DAEMON_ENABLED=true` |
| `--ad-pre-shared-key` | `AD_KEY` |
## Option 1: Newt as the auth daemon (same host)
See [more environment variables](/manage/sites/configure-site#environment-variables).
Use this when the machine you want to SSH into **is** the machine running Newt (e.g. the site connector and SSH are on the same server).
```mermaid
flowchart LR
subgraph client["User machine"]
CLI[Pangolin CLI]
end
subgraph cloud["Pangolin Cloud"]
CA[Sign certificate]
end
subgraph server["Single server (site)"]
direction TB
Newt[Newt + auth-daemon]
SSHD[SSH server]
Newt --> SSHD
end
CLI -->|Request signed cert| CA
CLI -->|SSH port 22| SSHD
```
### Run Newt with auth-daemon enabled
With Newt [installed](/manage/sites/install-site), run it in auth-daemon mode so it can handle SSH on this host:
```bash
sudo newt --id <id> --secret <secret> --endpoint <endpoint> --auth-daemon
```
<Note>
Replace `<id>`, `<secret>`, and `<endpoint>` with the values from your site configuration in the Pangolin dashboard.
If you use `<pre-shared-key>`, choose a strong random value and reuse the same value on each target host running `pangolin auth-daemon`.
For example, you can generate one with:
```bash
openssl rand -hex 32
```
</Note>
## Configure SSH on the Newt host
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).
If you want SSH access to the Newt host itself, run the `newt` binary directly on that host.
Do not treat this as a normal container use case. Newt needs to work with the host's own SSH configuration and local auth-daemon state, so a standard container deployment is not suitable for this path.
## Option 2: External auth daemon (SSH on another server that doesn't run Newt)
Add or adjust these lines in `/etc/ssh/sshd_config`:
Use this when you want to SSH into servers that **do not** run Newt. One host runs Newt (e.g. as a bastion); each target server runs the Pangolin auth daemon as an extension of Newt. The client connects to the target by going **through** Newt—Newt proxies the SSH connection to the auth daemon and SSH server on each target.
```ini title="/etc/ssh/sshd_config"
TrustedUserCAKeys /etc/ssh/ca.pem
AuthorizedPrincipalsCommand /usr/local/bin/newt auth-daemon principals --username %u
AuthorizedPrincipalsCommandUser root
```mermaid
flowchart LR
subgraph client["User machine"]
CLI[Pangolin CLI]
end
subgraph cloud["Pangolin Cloud"]
CA[Sign certificate]
end
subgraph bastion["Bastion / site host"]
Newt[Newt]
end
subgraph target["Target server"]
direction TB
AuthDaemon[Auth daemon]
SSHD[SSH server]
AuthDaemon --> SSHD
end
CLI -->|Request signed cert| CA
CLI -->|SSH port 22| Newt
Newt -->|SSH to target| SSHD
Newt <-->|Extension, port 22123| AuthDaemon
```
Restart the SSH server:
### Prerequisites
- **Newt** running on one host (the “site” / bastion) with auth-daemon support and 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
Start Newt with a **pre-shared key** so external auth daemons can authenticate to it:
```bash
sudo systemctl restart ssh
sudo newt --id <id> --secret <secret> --endpoint <endpoint> --ad-pre-shared-key <pre-shared-key>
```
## Configure SSH on hosts behind Newt
<Note>
Choose a strong, random value for `<pre-shared-key>` and use the same value when starting the auth daemon on each target server.
</Note>
Do this on every target server behind Newt that should accept SSH.
### Step 2: On each server you want to SSH into
These hosts need the Pangolin CLI installed because the remote-side SSH integration is provided by `pangolin auth-daemon`. See [Install Clients](/manage/clients/install-client#quick-install-recommended-—-linux-and-macos).
### Step 1: Start the auth daemon
Run the auth daemon with the same pre-shared key used on Newt:
On every host that should accept Pangolin SSH (and is not running Newt), run the auth daemon with the same pre-shared key:
```bash
sudo pangolin auth-daemon --pre-shared-key <pre-shared-key>
```
To use a non-default port, add `--port <port>`. When you create the dashboard resource later, set the same daemon port in that resource's `SSH Access` tab. If you do not set a custom port, the default is **22123**.
To use a non-default port, add `--port <port>` and set the same port in the resource’s SSH settings in the dashboard.
#### Run as a systemd service
@@ -166,7 +202,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 Access` tab), add `--port <port>` to `ExecStart`. Then:
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:
```bash
sudo systemctl daemon-reload
@@ -175,74 +211,68 @@ sudo systemctl start pangolin-auth-daemon
sudo systemctl status pangolin-auth-daemon
```
Ensure the Pangolin CLI binary is at `/usr/local/bin/pangolin`, or update `ExecStart` to the correct path.
<Warning>
Ensure the Pangolin CLI binary is at `/usr/local/bin/pangolin` (or update `ExecStart` to its path) before creating the service.
</Warning>
### Step 2: Configure `sshd`
### Step 3: Configure the SSH server on each target host
On each of these hosts, configure the SSH server as in [Configure the SSH server on the host](#configure-the-ssh-server-on-the-host). Use the `pangolin auth-daemon principals` command in `AuthorizedPrincipalsCommand` (see that section for the exact line).
### 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**; configurable in the resource’s SSH settings and via the auth daemon’s `--port` flag).
- **Clients → SSH:** Port **22** must be open for SSH to each target server (from wherever your users connect—often only within your private network).
<Note>
To change the auth daemon port from the default 22123, configure the port in the resource’s SSH settings in Pangolin and pass the same port with `--port` when starting the auth daemon.
</Note>
<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.
</Warning>
## Configure the SSH server on the host
For both Option 1 and Option 2, the host’s SSH server must trust the Pangolin CA and use the auth daemon to resolve principals. Do the following on **every** host that will accept Pangolin SSH (the host running Newt in Option 1, or each host running the external auth daemon in Option 2).
### 1. Update `sshd_config`
Add or adjust these lines in `/etc/ssh/sshd_config`:
- **Option 1 (Newt on this host):** use `newt auth-daemon principals` in the command.
- **Option 2 (external auth daemon on this host):** use `pangolin auth-daemon principals` in the command.
Example for **Option 1** (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 **Option 2** (external auth daemon on this host):
```ini title="/etc/ssh/sshd_config"
TrustedUserCAKeys /etc/ssh/ca.pem
AuthorizedPrincipalsCommand /usr/local/bin/pangolin auth-daemon principals --username %u
AuthorizedPrincipalsCommandUser root
```
Restart the SSH server:
### 2. Restart the SSH server
```bash
sudo systemctl restart ssh
```
### Step 3: Ensure network connectivity
- **Newt → auth daemon:** Newt must be able to reach the auth daemon port on each target server (default **TCP 22123**; configurable in the resource's `SSH Access` tab and via the auth daemon's `--port` flag).
- **Clients → SSH:** Port **22** must be open for SSH to each target server from wherever your users connect.
<Note>
To change the auth daemon port from the default 22123, configure the same port in the resource's `SSH Access` tab in Pangolin and pass it with `--port` when starting the auth daemon.
The auth-daemon port only needs to be reachable by Newt inside your network. It does not need to be exposed publicly, so restrict it with a firewall or network policy as appropriate for your environment.
</Note>
## Configure resources in the dashboard
After the host-side services are running, create the corresponding private resources in Pangolin.
| Resource type | Destination | Recommended alias | SSH access policy |
|---------------|-------------|-------------------|-------------------|
| Newt host | Usually `127.0.0.1` or `localhost` on the server running Newt | `ssh.<site>.internal`, for example `ssh.prod.internal` | In `SSH Access`, set **SSH Auth Daemon Location** to **On Site** |
| Host behind Newt | The target server | `<host>.<site>.internal`, for example `db-01.prod.internal` | In `SSH Access`, set **SSH Auth Daemon Location** to **Remote Host** |
For each resource:
1. Set the destination to the IP or FQDN of the correct host. For the Newt host itself, this is typically `127.0.0.1` or `localhost`.
2. Set an [alias](/manage/resources/private/alias) using the recommended pattern above.
3. Open the resource's `SSH Access` tab and set **SSH Auth Daemon Location** to match that host:
`On Site` for the Newt host, or `Remote Host` for a host behind Newt.
4. If the resource points to a host behind Newt, set the daemon port to match that host's auth daemon. Use **22123** unless you changed it with `pangolin auth-daemon --port <port>`.
5. Grant access to the required users or roles.
6. In port restrictions, allow the host's SSH port: **TCP 22** by default, or a custom SSH port if your server uses one.
<Note>
Two ports matter here:
- The **SSH port** is the port users connect to on the target host. This is usually `22`, and it must be allowed in the resource's port restrictions.
- The **daemon port** is the port Newt uses to reach `pangolin auth-daemon` on hosts behind Newt. This is `22123` by default, or whatever you set with `--port`.
</Note>
## Connect
Once the resources and host-side SSH integrations match, users can connect with the alias or resource identifier for the specific host they want:
```bash
pangolin ssh db-01.prod.internal
```
After this, users with access to the resource in Pangolin can run `pangolin ssh <alias>` to connect.
## Signing keys for other applications
You can ask Pangolin to sign a key for a resource without starting an interactive SSH session. Useful for scripts or tools that use SSH with a specific key:
```bash
pangolin ssh sign db-01.prod.internal --key-file /path/to/public/key.pub
pangolin ssh sign vm-01.prod.example.com --key-file /path/to/public/key.pub
```
## Generating passwords for users
@@ -251,10 +281,6 @@ If you need a password to be generated for your user on the remote system (e.g.
`--generate-random-password` to have Pangolin generate a random password when users are created on the device
```bash
pangolin auth-daemon --generate-random-password
```
## FAQ
### How long are the temporary keys valid?
@@ -263,9 +289,9 @@ When the client requests a signed key from the Pangolin server, the certificate
### Is the SSH connection proxied through Newt?
If the resource points to the **Newt host itself**, no. Your client connects directly to the server running Newt.
**Option 1 (same host):** No. Your client connects directly to the server that runs Newt; SSH traffic does not go through another hop.
If the resource points to a **host behind Newt**, yes. Your client connects to Newt, and Newt proxies the SSH session to the target server. In a mixed deployment, both behaviors can exist at the same time depending on which resource the user selects.
**Option 2 (external auth daemon):** Yes. 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 and works with it to complete the connection.
### How are usernames created on the remote server?