Skip to main content

Try free on Pangolin Cloud

Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
Only available in Pangolin Cloud and Enterprise Edition.

​
Overview

Pangolin includes a built-in SSH client so you can connect to remote servers and manage them directly from the terminal. You use your existing Pangolin identity—no separate SSH keys to create or copy. Pangolin generates and signs temporary access keys, pushes them to the remote server, and creates or updates your user account there. All of this happens automatically when you start a connection. You can SSH into any Pangolin site or private resource. Two components handle SSH on the server side:

Newt Host

Runs as a daemon and handles SSH for the host it runs on. Use this when the machine you want to SSH into is the same server running Newt.

Hosts Behind Newt

Handles SSH for other servers on the same network. Run the auth daemon on each target host; Newt on a bastion proxies connections to them.
You connect using the Pangolin CLI as the SSH client. The tunnel can be provided by the CLI or by another Pangolin client (e.g. the macOS app); you can run the GUI for the tunnel and use the CLI only for SSH if you prefer.

​
How certificates work

Each organization has a certificate authority (CA) used to sign temporary SSH keys.
  1. When you run pangolin ssh <alias>, the Pangolin client generates a temporary key pair.
  2. It sends the public key to the Pangolin server with your identity and the target resource.
  3. The server checks that you are allowed to access that resource, then signs the public key with the organization CA and returns it. The CA public key is also sent to the remote server and trusted there.
  4. The client connects to the remote host using the temporary private key. The host verifies the certificate with the CA and uses principals in the certificate for access control.
This gives short-lived, auditable access without long-lived keys on the server.

​
How users and access are managed

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.

​
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. Before you begin:
  • Install Newt on the host that will run the site connector. See Install Site.
  • Install the Pangolin CLI on any machine that will initiate pangolin ssh sessions. See Install Clients.
LayoutUse this whenNewt flags
Newt host onlyUsers only need SSH access to the server running Newt--auth-daemon
Hosts behind Newt onlyUsers only need SSH access to other servers on the same network as Newt--ad-pre-shared-key <pre-shared-key>
Mixed deploymentUsers need SSH access to the Newt host and to other servers behind it--auth-daemon --ad-pre-shared-key <pre-shared-key>
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.

​
Understand the model

The easiest way to think about SSH in Pangolin is:
  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.
In a mixed deployment, you will create one resource for the Newt host and separate resources for each host behind Newt.

​
Start Newt for your layout

With Newt installed, start it with the flags that match your layout:
LayoutCommand
Newt host onlysudo newt --id <id> --secret <secret> --endpoint <endpoint> --auth-daemon
Hosts behind Newt onlysudo newt --id <id> --secret <secret> --endpoint <endpoint> --ad-pre-shared-key <pre-shared-key>
Mixed deploymentsudo newt --id <id> --secret <secret> --endpoint <endpoint> --auth-daemon --ad-pre-shared-key <pre-shared-key>
Relevant environment variables:
FlagEnvironment variable
--idNEWT_ID
--secretNEWT_SECRET
--endpointPANGOLIN_ENDPOINT
--auth-daemonAUTH_DAEMON_ENABLED=true
--ad-pre-shared-keyAD_KEY
See more environment variables.
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:
openssl rand -hex 32

​
Configure SSH on the Newt 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. Add or adjust these lines in /etc/ssh/sshd_config:
/etc/ssh/sshd_config
TrustedUserCAKeys /etc/ssh/ca.pem
AuthorizedPrincipalsCommand /usr/local/bin/newt auth-daemon principals --username %u
AuthorizedPrincipalsCommandUser root
Restart the SSH server: 
sudo systemctl restart ssh

​
Configure SSH on hosts behind Newt

Do this on every target server behind Newt that should accept SSH. These hosts need the Pangolin CLI installed because the remote-side SSH integration is provided by pangolin auth-daemon. See Install Clients.

​
Step 1: Start the auth daemon

Run the auth daemon with the same pre-shared key used on Newt: 
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.

​
Run as a systemd service

Create a systemd unit so the auth daemon runs on boot:
/etc/systemd/system/pangolin-auth-daemon.service
[Unit]
Description=Pangolin SSH auth daemon
After=network.target

[Service]
ExecStart=/usr/local/bin/pangolin auth-daemon --pre-shared-key <pre-shared-key>
Restart=always
User=root

[Install]
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: 
sudo systemctl daemon-reload
sudo systemctl enable pangolin-auth-daemon
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.

​
Step 2: Configure sshd

Add or adjust these lines in /etc/ssh/sshd_config:
/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: 
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.
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.

​
Configure resources in the dashboard

After the host-side services are running, create the corresponding private resources in Pangolin.
Resource typeDestinationRecommended aliasSSH access policy
Newt hostUsually 127.0.0.1 or localhost on the server running Newtssh.<site>.internal, for example ssh.prod.internalIn SSH Access, set SSH Auth Daemon Location to On Site
Host behind NewtThe target server<host>.<site>.internal, for example db-01.prod.internalIn 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 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.
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.

​
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: 
pangolin ssh db-01.prod.internal

​
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: 
pangolin ssh sign db-01.prod.internal --key-file /path/to/public/key.pub

​
Generating passwords for users

If you need a password to be generated for your user on the remote system (e.g. for sudo access or if you have passwords required in your sshd config), you can use: --generate-random-password to have Pangolin generate a random password when users are created on the device 
pangolin auth-daemon --generate-random-password

​
FAQ

​
How long are the temporary keys valid?

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; the certificate is only needed for the initial authentication.

​
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. 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.

​
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. The user is created with a home directory and can be added to sudoers as configured by your organization.

​
How does Newt communicate with the external auth daemon?

Newt talks to the auth daemon over HTTPS. TCP 22123 is used by default. When you SSH into a server that uses the external auth daemon, Newt calls the auth daemon on that host to create or update your user and resolve principals. Port 22123 only needs to be open between Newt and the auth daemon hosts on your internal network; it should not be exposed to the internet. To use a different port, set the port in the resource’s SSH settings in the Pangolin dashboard and pass the same port to the auth daemon with the --port flag (e.g. pangolin auth-daemon --pre-shared-key <key> --port 22124). Newt and the auth daemon must use the same port.