diff --git a/development/system-architecture.mdx b/development/system-architecture.mdx index f80143f..8ff3564 100644 --- a/development/system-architecture.mdx +++ b/development/system-architecture.mdx @@ -64,7 +64,7 @@ The control plane writes certificates, Traefik router definitions, and WireGuard A **site connector** runs on a remote network (server, VM, container, or appliance) and is the bridge between your private LAN and the platform. For public resources it maintains persistent **outbound** connections to a Pangolin node so ingress can reverse-proxy into the LAN. For private resources, clients form a **peer-to-peer** path to the connector; the node is only in that data path as a relay when hole punching fails. -The primary connector is a **Pangolin Site**. In engineering contexts it is referred to as Newt. The site opens: +The primary connector is a **Pangolin Site**. The site opens: 1. A **WebSocket** to the control plane for configuration, health, and coordination 2. A **WireGuard** tunnel to the node's tunnel manager (Gerbil) for encrypted data traffic @@ -168,10 +168,11 @@ Pangolin's open-source repositories map to the roles above. Codenames are used t | Component | Repository | Role | | --- | --- | --- | | Pangolin | [fosrl/pangolin](https://github.com/fosrl/pangolin) | Control plane server | -| Newt | [fosrl/newt](https://github.com/fosrl/newt) | Site connector | +| Clients | [fosrl/cli](https://github.com/fosrl/cli), [fosrl/windows](https://github.com/fosrl/windows), [fosrl/apple](https://github.com/fosrl/apple), [fosrl/android](https://github.com/fosrl/android) | Endpoint agents | +| Site Connector | [fosrl/cli](https://github.com/fosrl/cli) | Connect remote networks for public and private resources | | Gerbil | [fosrl/gerbil](https://github.com/fosrl/gerbil) | Node tunnel manager and relay | | Badger | [fosrl/badger](https://github.com/fosrl/badger) | Traefik forward-auth middleware | +| Newt | [fosrl/newt](https://github.com/fosrl/newt) | Shared site networking stack | | Olm | [fosrl/olm](https://github.com/fosrl/olm) | Shared client networking stack (tunnels, NAT traversal, DNS) | -| Clients | [fosrl/cli](https://github.com/fosrl/cli), [fosrl/windows](https://github.com/fosrl/windows), [fosrl/apple](https://github.com/fosrl/apple), [fosrl/android](https://github.com/fosrl/android) | Endpoint agents | For local development setup and how these repositories interact in a dev environment, see [Contributing](/development/contributing). diff --git a/docs.json b/docs.json index 23d40fe..16734a9 100644 --- a/docs.json +++ b/docs.json @@ -2,7 +2,7 @@ "$schema": "https://mintlify.com/docs.json", "theme": "mint", "name": "Pangolin Docs", - "description": "Zero trust access to all your infrastructure, self-hosted applications, and SaaS tools. Easy to deploy and scale. Better than your existing VPN.", + "description": "Modern networking and security platform providing secure access and connectivity to apps, infrastructure, and AI workloads. Connect and protect your users.", "colors": { "primary": "#202020", "light": "#202020", @@ -399,7 +399,7 @@ "strict": true }, "banner": { - "content": "**AI Gateway** is now available. Connect with the Pangolin client to eliminate AI provider API keys, and tunnel to self-hosted models. [Get started](/manage/ai/overview)", + "content": "**AI Gateway** is now available: identity-aware access to any AI provider, eliminate API keys, and tunnel to self-hosted models. [Get started](/manage/ai/overview)", "dismissible": true }, "logo": { diff --git a/manage/blueprints.mdx b/manage/blueprints.mdx index 81fd9f8..0b61592 100644 --- a/manage/blueprints.mdx +++ b/manage/blueprints.mdx @@ -402,7 +402,7 @@ private-resources: ## Resource Labels -Attach labels to public and private resources to organize and filter them in the dashboard. These are the same labels manageable from **Settings > Labels** — not to be confused with the [Docker container labels](#container-labels-format) used to define blueprints from Compose. +Attach labels to public and private resources to organize and filter them in the dashboard. These are the same labels manageable from **Settings > Labels** - not to be confused with the [Docker container labels](#container-labels-format) used to define blueprints from Compose. ```yaml public-resources: @@ -423,7 +423,7 @@ public-resources: - Label names are matched case-insensitively against existing labels in the organization. - If a label with that name doesn't already exist yet, Pangolin creates it automatically. - Each apply replaces the resource's full label list with the list in the blueprint. -- Labels are not synced for [targets-only](#targets-only-resources) public resources — omitting `labels` on a targets-only update leaves existing labels untouched. +- Labels are not synced for [targets-only](#targets-only-resources) public resources - omitting `labels` on a targets-only update leaves existing labels untouched. ## Container Labels Format diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 120244b..ff89a0a 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -114,32 +114,18 @@ Pangolin CLI can run on Windows, but the CLI VPN functionality is not supported. Pangolin CLI supports running as user device with authentication or a machine client. - -### Quick Install (Recommended) — Linux and macOS +### Install Use this command to automatically install Pangolin CLI. It detects your system architecture automatically and always pulls the latest version, adding `pangolin` to your PATH: ```bash curl -fsSL https://static.pangolin.net/get-cli.sh | bash ``` -### Windows -Go to [GitHub releases](https://github.com/fosrl/cli/releases) and download the latest **MSI installer** or **EXE** for Windows. - -### Manual Download +On Windows, [download the latest installer](https://github.com/fosrl/cli/releases/latest/download/pangolin-cli_windows_installer.msi), or choose to install the CLI from menu bar of the desktop app by choosing the "Install Pangolin CLI" option. Binaries for all platforms are available in the [GitHub releases](https://github.com/fosrl/cli/releases) for ARM and AMD64 (x86_64) architectures. -Download and install manually: - -```bash -wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin -``` - - -Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information. - - ### Installation Steps 1. **Download and install the Pangolin client** @@ -178,6 +164,33 @@ Replace `{version}` with the desired version and `{architecture}` with your arch Pangolin CLI can be installed as a systemd service or run in a container. See the sections below for advanced setups. +## Machine Clients + +Machine clients don't require a login and are built for machines like services to be able to connect to private resources. Like sites, they have an ID and a secret. + +### Run as a Service + +The CLI can install and manage a service on your host machine for you. This supports Windows services, MacOS's launchd, and Linux's systemd to create a persistent site connection from that host. + +```bash +sudo pangolin service install client \ +--id 31frd0uzbjvp721 \ +--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ +--endpoint https://app.pangolin.net +``` + +Check the service status: + +```bash +sudo pangolin service status client +``` + +And to get the logs: + +```bash +sudo pangolin service logs client +``` + ### Systemd Service (Pangolin CLI) Create a basic systemd service for Pangolin CLI: diff --git a/manage/remote-node/backhaul.mdx b/manage/remote-node/backhaul.mdx index d4aa7d8..b9b5d97 100644 --- a/manage/remote-node/backhaul.mdx +++ b/manage/remote-node/backhaul.mdx @@ -199,7 +199,7 @@ This section uses AWS as an example, but the same steps apply to any VPC-style n - Add a route in the VPC's route table for the WireGuard overlay subnet assigned to your node (shown as the node's **Address** on its page in the [Pangolin dashboard](https://app.pangolin.net)), targeting the node's instance or network interface. This tells the rest of the VPC to send anything destined for the Pangolin overlay — other sites and clients — to the node. + Add a route in the VPC's route table for the WireGuard overlay subnet assigned to your node (shown as the node's **Address** on its page in the [Pangolin dashboard](https://app.pangolin.net)), targeting the node's instance or network interface. This tells the rest of the VPC to send anything destined for the Pangolin overlay - other sites and clients - to the node. AWS route table entry routing the overlay subnet to the node diff --git a/manage/sites/auto-update.mdx b/manage/sites/auto-update.mdx index cab9c07..59da4a4 100644 --- a/manage/sites/auto-update.mdx +++ b/manage/sites/auto-update.mdx @@ -1,27 +1,25 @@ --- title: "Automatic Site Updates" -description: "Let Newt sites check for and install updates on their own" +description: "Let sites check for and install updates on their own" --- - - Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition). -Newt sites can automatically check for new versions, download the latest release, and restart to begin using it. This is useful when you manage many remote connectors and do not want to update each one by hand. +Sites can automatically check for new versions, download the latest release, and restart to begin using it. This is useful when you manage many remote connectors and do not want to update each one by hand. ## Supported Installation Methods Automatic updates are only supported for sites installed with the [binary installation method](/manage/sites/install-site). -If you run Newt in Docker, Kubernetes, or another container orchestration platform, updates are handled by that platform. Pangolin cannot coordinate automatic updates for containerized deployments. +If you run a site in Docker, Kubernetes, or another container orchestration platform, updates are handled by that platform. Pangolin cannot coordinate automatic updates for containerized deployments. ## How It Works -When automatic updates are enabled, Newt periodically checks for a newer version. If one is available, it downloads the latest release and restarts itself. After the restart, the site reconnects to Pangolin on the new version. +When automatic updates are enabled, the site periodically checks for a newer version. If one is available, it downloads the latest release and restarts itself. After the restart, the site reconnects to Pangolin on the new version. -For safety, Pangolin waits **24 hours** after a release is published before sites pull that version. This gives time for early issues to surface before a fleet of connectors updates. +For safety, Pangolin waits **24 hours** after a release is published before sites pull that version. This gives time for early issues to surface before a fleet of sites updates. ## Enable Automatic Updates @@ -41,7 +39,7 @@ These settings work together: ## Fleet Deployments -Automatic updates are especially useful when you run many sites across edge networks. For example, if you have dozens or hundreds of Raspberry Pis or other edge devices running Newt, you would otherwise need to update each connector every time a new release ships. +Automatic updates are especially useful when you run many sites across edge networks. For example, if you have dozens or hundreds of Raspberry Pis or other edge devices running a site, you would otherwise need to update each site every time a new release ships. With automatic updates enabled, each site in the fleet checks for new versions on its own, downloads the latest release after the 24-hour safety window, restarts, and reconnects to Pangolin without manual intervention. diff --git a/manage/sites/configure-site.mdx b/manage/sites/configure-site.mdx index c077701..0655dd0 100644 --- a/manage/sites/configure-site.mdx +++ b/manage/sites/configure-site.mdx @@ -1,6 +1,6 @@ --- title: "Configure Sites" -description: "Configure Newt for connecting to Pangolin sites" +description: "Configure Pangolin site connector setting" --- @@ -12,24 +12,27 @@ Almost every setting below can also be set via an environment variable (**Env va - Newt ID generated by Pangolin to identify the client. + Site ID generated by Pangolin to identify the client. **Example**: `31frd0uzbjvp721` - **Env var**: `NEWT_ID` + **Env var**: `SITE_ID` **Config file key**: `id` + + **Legacy env var**: `NEWT_SECRET` - A unique secret used to authenticate the client ID with the websocket. + A unique secret used to authenticate the site with the websocket. **Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6` - **Env var**: `NEWT_SECRET` + **Env var**: `SITE_SECRET` **Config file key**: `secret` + **Legacy env var**: `NEWT_SECRET` Keep this secret private and secure. It's used for authentication. @@ -50,13 +53,13 @@ Almost every setting below can also be set via an environment variable (**Env va **Example**: `my-edge-site` or `'{{env.SERIAL_NUMBER}}-edge'` - **Env var**: `NEWT_NAME` + **Env var**: `SITE_NAME` **Config file key**: `name` - Path to a blueprint YAML file applied **once** at provisioning (imperative bootstrap). Unlike `--blueprint-file`, Newt does not keep reapplying it, so resources you edit in the dashboard are not overwritten on later runs. See [Site provisioning keys](/manage/sites/site-provisioning). + Path to a blueprint YAML file applied **once** at provisioning (imperative bootstrap). Unlike `--blueprint-file`, the site does not keep reapplying it, so resources you edit in the dashboard are not overwritten on later runs. See [Site provisioning keys](/manage/sites/site-provisioning). **Example**: `/path/to/bootstrap.yaml` @@ -66,25 +69,27 @@ Almost every setting below can also be set via an environment variable (**Env va - Provisioning key from Pangolin (alternative to a `provisioningKey` field inside the config file). Newt exchanges it once for site credentials, then persists `id` and `secret` to the config file and ignores the key on later runs. This flag is not written into the config file. See [Site provisioning keys](/manage/sites/site-provisioning). + Provisioning key from Pangolin (alternative to a `provisioningKey` field inside the config file). The site exchanges it once for site credentials, then persists `id` and `secret` to the config file and ignores the key on later runs. This flag is not written into the config file. See [Site provisioning keys](/manage/sites/site-provisioning). **Example**: `spk_...` - **Env var**: `NEWT_PROVISIONING_KEY` + **Env var**: `SITE_PROVISIONING_KEY` **Config file key**: `provisioningKey` + + **Legacy env var**: `NEWT_PROVISIONING_KEY` - Path to a JSON file where Newt reads and persists settings (`endpoint`, `id`, `secret`, optional `provisioningKey`, and virtually every other flag below). When you use [site provisioning](/manage/sites/site-provisioning), Newt writes `id` and `secret` into this file after a successful exchange. See [Config File](#config-file) for the default path on each platform. + Path to a JSON file where the site reads and persists settings (`endpoint`, `id`, `secret`, optional `provisioningKey`, and virtually every other flag below). When you use [site provisioning](/manage/sites/site-provisioning), the site writes `id` and `secret` into this file after a successful exchange. See [Config File](#config-file) for the default path on each platform. - **Example**: `/var/newt.json` + **Example**: `/var/site.json` **Env var**: `CONFIG_FILE` - Port for the peers to connect to Newt on. This can be used to keep a static port open in firewalls instead of default random ports. + Port for the peers to connect to the site on. This can be used to keep a static port open in firewalls instead of default random ports. **Example**: `34534` @@ -116,7 +121,7 @@ Almost every setting below can also be set via an environment variable (**Env va Name of the native main tunnel WireGuard interface (used with `--native-main`). - **Default**: `newt` + **Default**: `pangolin` **Env var**: `INTERFACE_MAIN` @@ -144,7 +149,7 @@ Almost every setting below can also be set via an environment variable (**Env va - The log level to use for Newt output. + The log level to use for the site output. **Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` @@ -180,9 +185,11 @@ Almost every setting below can also be set via an environment variable (**Env va **Default**: `90s` - **Env var**: `NEWT_UDP_PROXY_IDLE_TIMEOUT` + **Env var**: `SITE_UDP_PROXY_IDLE_TIMEOUT` **Config file key**: `udpProxyIdleTimeout` + + **Legacy env var**: `NEWT_UDP_PROXY_IDLE_TIMEOUT` @@ -196,7 +203,7 @@ Almost every setting below can also be set via an environment variable (**Env va - Validate the container target is on the same network as the Newt process. + Validate the container target is on the same network as the the site process. **Default**: `false` @@ -206,7 +213,7 @@ Almost every setting below can also be set via an environment variable (**Env va - Check if connection to WireGuard server (Pangolin) is ok. Creates a file if ok, removes it if not ok. Can be used with Docker healthcheck to restart Newt. + Check if connection to WireGuard server (Pangolin) is ok. Creates a file if ok, removes it if not ok. Can be used with Docker healthcheck to restart the site. **Example**: `/tmp/healthy` @@ -226,7 +233,7 @@ Almost every setting below can also be set via an environment variable (**Env va - Path to a blueprint file that defines Pangolin resources and settings. This mode is declarative: Newt keeps applying the file, and it remains the source of truth (dashboard changes can be overwritten on the next apply). For a one-time bootstrap blueprint with provisioning keys, use `--provisioning-blueprint-file` instead. + Path to a blueprint file that defines Pangolin resources and settings. This mode is declarative: the site keeps applying the file, and it remains the source of truth (dashboard changes can be overwritten on the next apply). For a one-time bootstrap blueprint with provisioning keys, use `--provisioning-blueprint-file` instead. **Example**: `/path/to/blueprint.yaml` @@ -268,7 +275,7 @@ Almost every setting below can also be set via an environment variable (**Env va Name of the WireGuard interface. - **Default**: `newt` + **Default**: `pangolin` **Env var**: `INTERFACE` @@ -280,9 +287,11 @@ Almost every setting below can also be set via an environment variable (**Env va **Default**: `false` - **Env var**: `NEWT_METRICS_PROMETHEUS_ENABLED` + **Env var**: `SITE_METRICS_PROMETHEUS_ENABLED` **Config file key**: `metrics` + + **Legacy env var**: `NEWT_METRICS_PROMETHEUS_ENABLED` @@ -290,9 +299,11 @@ Almost every setting below can also be set via an environment variable (**Env va **Default**: `false` - **Env var**: `NEWT_METRICS_OTLP_ENABLED` + **Env var**: `SITE_METRICS_OTLP_ENABLED` **Config file key**: `otlp` + + **Legacy env var**: `NEWT_METRICS_OTLP_ENABLED` @@ -300,9 +311,11 @@ Almost every setting below can also be set via an environment variable (**Env va **Default**: `127.0.0.1:2112` - **Env var**: `NEWT_ADMIN_ADDR` + **Env var**: `SITE_ADMIN_ADDR` **Config file key**: `metricsAdminAddr` + + **Legacy env var**: `NEWT_ADMIN_ADDR` @@ -310,9 +323,11 @@ Almost every setting below can also be set via an environment variable (**Env va **Default**: `false` - **Env var**: `NEWT_METRICS_ASYNC_BYTES` + **Env var**: `SITE_METRICS_ASYNC_BYTES` **Config file key**: `metricsAsyncBytes` + + **Legacy env var**: `NEWT_METRICS_ASYNC_BYTES` @@ -320,9 +335,11 @@ Almost every setting below can also be set via an environment variable (**Env va **Default**: `false` - **Env var**: `NEWT_PPROF_ENABLED` + **Env var**: `SITE_PPROF_ENABLED` **Config file key**: `pprof` + + **Legacy env var**: `NEWT_PPROF_ENABLED` @@ -330,9 +347,11 @@ Almost every setting below can also be set via an environment variable (**Env va **Example**: `us-west-2` - **Env var**: `NEWT_REGION` + **Env var**: `SITE_REGION` **Config file key**: `region` + + **Legacy env var**: `NEWT_REGION` @@ -424,7 +443,7 @@ Almost every setting below can also be set via an environment variable (**Env va - Print the Newt version and exit. + Print the Newt (package) version and exit. @@ -443,19 +462,19 @@ Almost every setting below can also be set via an environment variable (**Env va ## Config File -Newt can be configured entirely with a JSON config file instead of (or in addition to) CLI flags and environment variables. Almost every flag documented above has a matching camelCase key in this file — see the **Config file key** on each flag for its exact name. +The site can be configured entirely with a JSON config file instead of (or in addition to) CLI flags and environment variables. Almost every flag documented above has a matching camelCase key in this file — see the **Config file key** on each flag for its exact name. -You can use `--config-file` or the `CONFIG_FILE` environment variable to point Newt at a specific path. Newt also writes to this file: when [site provisioning](/manage/sites/site-provisioning) succeeds, the resolved `id` and `secret` are persisted here so you don't need to pass `--id`/`--secret` (or a provisioning key) on every subsequent run. +You can use `--config-file` or the `CONFIG_FILE` environment variable to point the site at a specific path. The site also writes to this file: when [site provisioning](/manage/sites/site-provisioning) succeeds, the resolved `id` and `secret` are persisted here so you don't need to pass `--id`/`--secret` (or a provisioning key) on every subsequent run. ### Default locations -If `--config-file`/`CONFIG_FILE` isn't set, Newt reads and writes the config file at a platform-specific default path: +If `--config-file`/`CONFIG_FILE` isn't set, the site reads and writes the config file at a platform-specific default path: | Platform | Default path | | --- | --- | -| macOS | `~/Library/Application Support/newt-client/config.json` | -| Windows | `%PROGRAMDATA%\newt\newt-client\config.json` | -| Linux / others | `~/.config/newt-client/config.json` | +| macOS | `~/.config/pangolin/site.json` | +| Windows | `C:\Users\\.config\pangolin\site.json` | +| Linux / others | `~/.config/pangolin/site.json` | ### Example @@ -468,7 +487,7 @@ If `--config-file`/`CONFIG_FILE` isn't set, Newt reads and writes the config fil "dns": "9.9.9.9", "logLevel": "INFO", - "interface": "newt", + "interface": "pangolin", "mtu": 1280, "port": 34534, @@ -493,7 +512,7 @@ If `--config-file`/`CONFIG_FILE` isn't set, Newt reads and writes the config fil ``` -You only need to include the keys you want to set — anything omitted falls back to an environment variable, then its built-in default. Run `newt --show-config` to see every resolved setting alongside where it came from (config file, environment, CLI, or default), which is useful for confirming what a config file actually loaded. +You only need to include the keys you want to set — anything omitted falls back to an environment variable, then its built-in default. Run `pangolin --show-config` to see every resolved setting alongside where it came from (config file, environment, CLI, or default), which is useful for confirming what a config file actually loaded. @@ -502,16 +521,16 @@ Fields like `secret`, `tlsClientKey`, and `adPreSharedKey` are sensitive. Restri ## Docker Socket Integration -Newt can integrate with the Docker socket to provide remote inspection of Docker containers. This allows Pangolin to query and retrieve detailed information about containers running on the Newt client, including metadata, network configuration, port mappings, and more. +The site can integrate with the Docker socket to provide remote inspection of Docker containers. This allows Pangolin to query and retrieve detailed information about containers running on the site, including metadata, network configuration, port mappings, and more. **Configuration:** -You can specify the Docker socket path using the `--docker-socket` CLI argument or by setting the `DOCKER_SOCKET` environment variable. If the Docker socket is not available or accessible, Newt will gracefully disable Docker integration and continue normal operation. +You can specify the Docker socket path using the `--docker-socket` CLI argument or by setting the `DOCKER_SOCKET` environment variable. If the Docker socket is not available or accessible, the site will gracefully disable Docker integration and continue normal operation. Supported values include: - Local UNIX socket (default): - >You must mount the socket file into the container using a volume, so Newt can access it. + >You must mount the socket file into the container using a volume, so the site can access it. `unix:///var/run/docker.sock` @@ -530,26 +549,26 @@ Supported values include: ```yaml services: - newt: - image: fosrl/newt - container_name: newt + pangolin-site: + image: fosrl/pangolin-cli + container_name: pangolin-site restart: unless-stopped volumes: - /var/run/docker.sock:/var/run/docker.sock:ro environment: - PANGOLIN_ENDPOINT=https://example.com - - NEWT_ID=2ix2t8xk22ubpfy - - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 + - SITE_ID=2ix2t8xk22ubpfy + - SITE_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 - DOCKER_SOCKET=unix:///var/run/docker.sock ``` -If the Docker socket is not available or accessible, Newt will gracefully disable Docker integration and continue normal operation. +If the Docker socket is not available or accessible, the site will gracefully disable Docker integration and continue normal operation. **Hostnames vs IPs** -When the Docker Socket Integration is used, depending on the network which Newt is run with, either the hostname (generally considered the container name) or the IP address of the container will be sent to Pangolin: +When the Docker Socket Integration is used, depending on the network which the site is run with, either the hostname (generally considered the container name) or the IP address of the container will be sent to Pangolin: - **Running in Network Mode 'host'**: IP addresses will be used - **Running in Network Mode 'bridge'**: IP addresses will be used @@ -558,17 +577,17 @@ When the Docker Socket Integration is used, depending on the network which Newt **Docker Enforce Network Validation** -When run as a Docker container, Newt can validate that the target being provided is on the same network as the Newt container and only return containers directly accessible by Newt. Validation will be carried out against either the hostname/IP Address and the Port number to ensure the running container is exposing the ports to Newt. +When run as a Docker container, the site can validate that the target being provided is on the same network as the site container and only return containers directly accessible by the site. Validation will be carried out against either the hostname/IP Address and the Port number to ensure the running container is exposing the ports to the site. Validation is `false` by default. It can be enabled via setting the `--docker-enforce-network-validation` CLI argument or by setting the `DOCKER_ENFORCE_NETWORK_VALIDATION` environment variable. -If the Newt container is run with a network mode of `host`, this feature will not work. Running in `host` mode causes the container to share its resources with the host machine, making it impossible to retrieve specific host container information for network validation. +If the site container is run with a network mode of `host`, this feature will not work. Running in `host` mode causes the container to share its resources with the host machine, making it impossible to retrieve specific host container information for network validation. ## Updown Scripts -You can pass in an updown script for Newt to call when it is adding or removing a target: +You can pass in an updown script for the site to call when it is adding or removing a target: ```bash --updown "python3 test.py" @@ -591,7 +610,7 @@ You can look at `updown.py` as a reference script to get started! ## mTLS Authentication -Newt supports mutual TLS (mTLS) authentication if the server is configured to request a client certificate. You can use either a PKCS12 (.p12/.pfx) file or split PEM files for the client cert, private key, and CA. +The site supports mutual TLS (mTLS) authentication if the server is configured to request a client certificate. You can use either a PKCS12 (.p12/.pfx) file or split PEM files for the client cert, private key, and CA. ### Option 1: PKCS12 (Legacy) @@ -609,7 +628,7 @@ This is the original method and still supported. **Example:** ```bash -newt \ +pangolin \ --id 31frd0uzbjvp721 \ --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ --endpoint https://example.com \ @@ -627,7 +646,7 @@ You can now provide separate files for: **Example:** ```bash -newt \ +pangolin \ --id 31frd0uzbjvp721 \ --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ --endpoint https://example.com \ diff --git a/manage/sites/install-site.mdx b/manage/sites/install-site.mdx index 677b47e..7786a15 100644 --- a/manage/sites/install-site.mdx +++ b/manage/sites/install-site.mdx @@ -1,79 +1,81 @@ --- title: "Install Sites" -description: "Install Newt as a binary or Docker container" +description: "Install the site connector as a binary or Docker container" --- -Newt can be installed as either a static binary executable or a Docker container. You must first create a site and copy the Newt config in Pangolin before running Newt. - -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). - +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 -### Quick Install (Recommended) +### Install -Use this command to automatically install Newt. It detects your system architecture automatically and always pulls the latest version, adding Newt to your PATH: +Use this command to automatically install the CLI. It detects your system architecture automatically and always pulls the latest version, adding the CLI to your PATH: ```bash -curl -fsSL https://static.pangolin.net/get-newt.sh | bash +curl -fsSL https://static.pangolin.net/get-cli.sh | bash ``` -#### Windows +To run a site on Windows, [download the latest installer](https://github.com/fosrl/cli/releases/latest/download/pangolin-cli_windows_installer.msi). -To run Newt on Windows, use the latest installer from [GitHub releases](https://github.com/fosrl/newt/releases/latest). +Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/cli/releases/latest) for ARM and AMD64 (x86_64) architectures. -{/* -If you are using Newt on Windows as a service or with clients, `wintun.dll` may be required. - */} +### Running the Site -### 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: +Run the site connector with the configuration from Pangolin: ```bash -wget -O newt "https://github.com/fosrl/newt/releases/download/{version}/newt_{architecture}" && chmod +x ./newt -``` - - -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. - - -### Running Newt - -Run Newt with the configuration from Pangolin: - -```bash -newt \ +pangolin up site \ --id 31frd0uzbjvp721 \ --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ --endpoint https://app.pangolin.net ``` -### Systemd Service +### Run as a Service -Create `/etc/newt/newt.env` with the initial values from your Pangolin site configuration: +The CLI can install and manage a service on your host machine for you. This supports Windows services, MacOS's launchd, and Linux's systemd to create a persistent site connection from that host. -```bash title="/etc/newt/newt.env" -NEWT_ID=31frd0uzbjvp721 -NEWT_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 +```bash +sudo pangolin service install site \ +--id 31frd0uzbjvp721 \ +--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ +--endpoint https://app.pangolin.net +``` + +Check the service status: + +```bash +sudo pangolin service status site +``` + +And to get the logs: + +```bash +sudo pangolin service logs site +``` + +### Manual Systemd Service + +Create `/etc/pangolin/pangolin-site.env` with the initial values from your Pangolin site configuration: + +```bash title="/etc/pangolin/pangolin-site.env" +SITE_ID=31frd0uzbjvp721 +SITE_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 +sudo install -d -m 0755 /etc/pangolin +sudo editor /etc/pangolin/pangolin-site.env +sudo chmod 600 /etc/pangolin/pangolin-site.env ``` -Then create a systemd service. Newt reads those environment variables automatically, so `ExecStart` does not need to repeat them as flags: +Then create a systemd service. The site connector reads those environment variables automatically, so `ExecStart` does not need to repeat them as flags: -```ini title="/etc/systemd/system/newt.service" +```ini title="/etc/systemd/system/pangolin-site.service" [Unit] -Description=Newt +Description=Pangolin Site Wants=network-online.target After=network-online.target @@ -81,8 +83,8 @@ After=network-online.target Type=simple User=root Group=root -EnvironmentFile=/etc/newt/newt.env -ExecStart=/usr/local/bin/newt +EnvironmentFile=/etc/pangolin/pangolin-site.env +ExecStart=/usr/local/bin/pangolin up site Restart=always RestartSec=2 UMask=0077 @@ -94,22 +96,18 @@ WantedBy=multi-user.target ``` -Make sure the binary exists at `/usr/local/bin/newt` before daemon reload and starting the service: - -```bash -which newt -``` +Make sure the binary exists at `/usr/local/bin/pangolin` before daemon reload and starting the service: `~$ which pangolin` Reload systemd and enable the service: ```bash sudo systemctl daemon-reload -sudo systemctl enable --now newt -sudo systemctl status newt +sudo systemctl enable --now pangolin-site +sudo systemctl status pangolin-site ``` -If you later change `/etc/newt/newt.env`, restart the service so Newt picks up the new values. +If you later change `/etc/pangolin/pangolin-site.env`, restart the service so the site connector picks up the new values. See [Configure Sites](/manage/sites/configure-site) for more environment variables. @@ -117,18 +115,18 @@ See [Configure Sites](/manage/sites/configure-site) for more environment variabl ### Pull the Image -Pull the latest Newt image from Docker Hub: +Pull the latest image from Docker Hub: ```bash -docker pull fosrl/newt:latest +docker pull fosrl/pangolin-cli:latest ``` ### Run with Docker -Run Newt with CLI arguments from Pangolin: +Run the site connector with CLI arguments from Pangolin: ```bash -docker run -it fosrl/newt --id 31frd0uzbjvp721 \ +docker run -dit --network host fosrl/pangolin-cli up site --id 31frd0uzbjvp721 \ --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \ --endpoint https://app.pangolin.net ``` @@ -139,26 +137,25 @@ docker run -it fosrl/newt --id 31frd0uzbjvp721 \ ```yaml title="docker-compose.yml" services: - newt: - image: fosrl/newt - container_name: newt + pangolin-site: + image: fosrl/pangolin-cli + container_name: pangolin-site restart: unless-stopped environment: - PANGOLIN_ENDPOINT=https://app.pangolin.net - - NEWT_ID=2ix2t8xk22ubpfy - - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 + - SITE_ID=2ix2t8xk22ubpfy + - SITE_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" +```json title="pangolin-site-config.secret" { "id": "2ix2t8xk22ubpfy", "secret": "nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2", "endpoint": "https://app.pangolin.net", - "tlsClientCert": "" } ``` @@ -166,18 +163,18 @@ Then register and reference the secret in your `docker-compose.yml`: ```yaml title="docker-compose.yml" services: - newt: - image: fosrl/newt - container_name: newt + pangolin-site: + image: fosrl/pangolin-cli + container_name: pangolin-site restart: unless-stopped environment: - - CONFIG_FILE=/run/secrets/newt-config + - CONFIG_FILE=/run/secrets/pangolin-site-config secrets: - - newt-config + - pangolin-site-config secrets: - newt-config: - file: ./newt-config.secret + pangolin-site-config: + file: ./pangolin-site-config.secret ``` This allows you to separate sensitive secrets from plain configuration, improving security when storing or sharing your `docker-compose.yml` anywhere else. @@ -186,18 +183,20 @@ This allows you to separate sensitive secrets from plain configuration, improvin ```yaml title="docker-compose.yml" services: - newt: - image: fosrl/newt - container_name: newt + pangolin-site: + image: fosrl/pangolin-cli + container_name: pangolin-site restart: unless-stopped command: + - up + - site - --id 31frd0uzbjvp721 - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 - --endpoint https://app.pangolin.net ``` #### Docker healthcheck -The newt cliens suports healthchecks as described in [Configure Sites](/manage/sites/configure-site#param-health-file). This file can be used to do a +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). We need to define the `HEALTH_FILE` environment variable as well as the healthcheck itself: @@ -222,20 +221,24 @@ docker compose up -d ### 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: + +The Kubernetes install still uses the legacy Newt for the Helm chart, namespace, and secret keys shown below. + + +Running a site 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: - Quick-start guide for installing Newt with Helm. + Quick-start guide for installing a site with Helm. - Install Newt with rendered manifests and Kustomize overlays. + Install a site with rendered manifests and Kustomize overlays. Full configuration reference for Helm and Kustomize workflows. - Debug Newt deployment and connection issues in Kubernetes. + Debug site deployment and connection issues in Kubernetes. @@ -247,70 +250,6 @@ Newt is available in the Unraid Community Applications store. Search for "Newt" Newt on CA -### 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-site#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 -``` - -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 the [Advantech engineering portal](https://icr.advantech.com/products/software/router-apps). @@ -318,13 +257,13 @@ Download the correct version of the router app for your device from the [GitHub 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. - Advantech router UI showing Newt router app installation + Advantech router UI showing site router app installation -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. +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. - Advantech router UI showing Newt credential configuration + Advantech router UI showing site credential configuration 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 diff --git a/manage/sites/site-provisioning.mdx b/manage/sites/site-provisioning.mdx index 913fa18..350c103 100644 --- a/manage/sites/site-provisioning.mdx +++ b/manage/sites/site-provisioning.mdx @@ -3,8 +3,6 @@ title: "Site Provisioning Keys" description: "Use long-lived provisioning tokens to bootstrap Pangolin sites at scale without pre-creating ID-secret pairs for every host" --- - - ## Why provisioning keys exist As described in [Site credentials](/manage/sites/credentials), each Pangolin site authenticates with an ID and secret (random strings you get when a site is first created) plus an endpoint pointing at your Pangolin server. That model is simple for a handful of sites, but it breaks down quickly when you must issue and distribute unique credentials for many machines. @@ -25,10 +23,10 @@ With provisioning keys, you create one long-lived token in Pangolin, embed it in You can supply the provisioning key in either of two ways: **1. Config file** -Put the key in a JSON config file in a `provisioningKey` field (the value is the key string from Pangolin, often shown with an `spk` prefix) and point Newt at that file: +Put the key in a JSON config file in a `provisioningKey` field (the value is the key string from Pangolin, often shown with an `spk` prefix) and point the site at that file: ```bash -newt --config-file /var/newt.json +pangolin up site --config-file /var/site.json ``` ```json @@ -39,15 +37,15 @@ newt --config-file /var/newt.json ``` **2. Command line** -Pass the key with **`--provisioning-key`** instead of storing it in the file. You still use **`--config-file`** so Newt has a path to write and persist settings; see [Configure Sites](/manage/sites/configure-site) for the rest): +Pass the key with **`--provisioning-key`** instead of storing it in the file. You still use **`--config-file`** so the site has a path to write and persist settings; see [Configure Sites](/manage/sites/configure-site) for the rest): ```bash -newt --config-file /var/newt.json --endpoint https://app.pangolin.net --provisioning-key 'spk_...' +pangolin up site --config-file /var/site.json --endpoint https://app.pangolin.net --provisioning-key 'spk_...' ``` -**After the site is provisioned**, Newt writes the new `id` and `secret` into that config file. On later runs, Newt uses those credentials and ignores the provisioning key (CLI flag or file field), because valid ID and secret are already present. If you used `provisioningKey` in JSON, that entry is removed when the file is updated, so the long-lived token is not left on disk. If you pass `--provisioning-key` instead, Newt does not write that key into the config file, but anything that launched Newt with the flag may still contain it. +**After the site is provisioned**, the site writes the new `id` and `secret` into that config file. On later runs, the site uses those credentials and ignores the provisioning key (CLI flag or file field), because valid ID and secret are already present. If you used `provisioningKey` in JSON, that entry is removed when the file is updated, so the long-lived token is not left on disk. If you pass `--provisioning-key` instead, the site does not write that key into the config file, but anything that launched the site with the flag may still contain it. -From there Newt authenticates over the websocket, optionally applies a blueprint if you passed one, then brings the tunnel online. The high-level sequence is summarized below. +From there the site authenticates over the websocket, optionally applies a blueprint if you passed one, then brings the tunnel online. The high-level sequence is summarized below. Flow: provision with pre-shared key, exchange for ID and secret, apply YAML, pending approval, admin approves @@ -59,24 +57,24 @@ From there Newt authenticates over the websocket, optionally applies a blueprint ### `--provisioning-blueprint-file` vs `--blueprint-file` -When you run Newt with a provisioning key, you can attach a blueprint YAML file in two different ways: +When you run a site with a provisioning key, you can attach a blueprint YAML file in two different ways: | Flag | Behavior | |------|------------| -| **`--blueprint-file`** | **Declarative.** The blueprint is the ongoing source of truth. Newt keeps applying it, and changes you make in the dashboard can be overwritten the next time the blueprint is applied. | -| **`--provisioning-blueprint-file`** | **Imperative (bootstrap only).** The file is applied once, at provisioning time. After that, Newt does not keep reapplying it. You can edit resources in the dashboard and those edits will not be overridden by that YAML on later runs. | +| **`--blueprint-file`** | **Declarative.** The blueprint is the ongoing source of truth. The site keeps applying it, and changes you make in the dashboard can be overwritten the next time the blueprint is applied. | +| **`--provisioning-blueprint-file`** | **Imperative (bootstrap only).** The file is applied once, at provisioning time. After that, the site does not keep reapplying it. You can edit resources in the dashboard and those edits will not be overridden by that YAML on later runs. | Use **`--provisioning-blueprint-file`** when you want automation to create an initial set of resources (for example from a fleet template) but you intend to manage or tune them in the UI afterward. Use `--blueprint-file` when you want the file to remain authoritative, the same as on a normal site without provisioning keys. ```bash -newt --config-file /var/newt.json --provisioning-blueprint-file /path/to/bootstrap.yaml +pangolin up site --config-file /var/site.json --provisioning-blueprint-file /path/to/bootstrap.yaml ``` If you do use blueprints together with provisioning keys, you get a repeatable pattern for large fleets: one key (with appropriate limits), a blueprint file, and optional environment-specific values so each host gets distinct resource names or domains without maintaining separate YAML per device. Pick the flag above based on whether that YAML should keep governing the site or only run at first connect. ### Blueprint example and environment templating -Blueprints can reference environment variables using `{{env.VARIABLE_NAME}}` syntax. At apply time, those placeholders are filled from the process environment running Newt (for example a serial number, hostname, or customer slug exported before start). That lets one blueprint drive many sites: each host sets `SERIAL_NUMBER`, `CUSTOMER_ID`, or similar, and the resolved YAML defines unique site names, domains, or role assignments. +Blueprints can reference environment variables using `{{env.VARIABLE_NAME}}` syntax. At apply time, those placeholders are filled from the process environment running the site (for example a serial number, hostname, or customer slug exported before start). That lets one blueprint drive many sites: each host sets `SERIAL_NUMBER`, `CUSTOMER_ID`, or similar, and the resolved YAML defines unique site names, domains, or role assignments. Below, `{{env.SERIAL_NUMBER}}` ties the private resource’s site field and the public resource’s hostname to the same per-device identity: @@ -109,14 +107,14 @@ public-resources: - user@example.com ``` -Use whatever variables match your deployment (for example asset tags or cloud instance IDs). Ensure those variables are set in the environment where Newt runs before it applies the blueprint. For more on blueprint structure and applying YAML from Newt, see the [Blueprints](/manage/blueprints) documentation. +Use whatever variables match your deployment (for example asset tags or cloud instance IDs). Ensure those variables are set in the environment where the site runs before it applies the blueprint. For more on blueprint structure and applying YAML from a site, see the [Blueprints](/manage/blueprints) documentation. ### Optional site name (`--name`) -You can pass `--name` to Newt when provisioning so the new site gets a specific name. The value supports the same `{{env.VARIABLE_NAME}}` templating as blueprints: placeholders are expanded from the environment where Newt runs before the site is created (for example per-device serials or hostnames). +You can pass `--name` to the site when provisioning so the new site gets a specific name. The value supports the same `{{env.VARIABLE_NAME}}` templating as blueprints: placeholders are expanded from the environment where the site runs before the site is created (for example per-device serials or hostnames). ```bash -newt --config-file /var/newt.json --name '{{env.SERIAL_NUMBER}}-edge' +pangolin up site --config-file /var/site.json --name '{{env.SERIAL_NUMBER}}-edge' ``` If you omit `--name`, Pangolin assigns a random animal-based name, which you can change later in the dashboard. Explicit or templated names help when your automation or blueprint references the site by a stable label. diff --git a/manage/sites/understanding-sites.mdx b/manage/sites/understanding-sites.mdx index 869e9cd..c175b9a 100644 --- a/manage/sites/understanding-sites.mdx +++ b/manage/sites/understanding-sites.mdx @@ -17,7 +17,7 @@ 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. -### Newt Site (Recommended) +### Site Connector (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. @@ -54,4 +54,4 @@ Basic WireGuard sites do not support: - Using LAN-style addresses as targets - Private resources - Health checking -- Docker socket scanning +- Docker socket scanning \ No newline at end of file diff --git a/manage/sites/update-site.mdx b/manage/sites/update-site.mdx index c0db6dd..0bcccaf 100644 --- a/manage/sites/update-site.mdx +++ b/manage/sites/update-site.mdx @@ -1,10 +1,10 @@ --- title: "Update Sites" -description: "Update Newt to the latest version" +description: "Update your site to the latest version" --- -The update process depends on how you originally installed Newt. +The update process depends on how you originally installed the site. -Find the latest version in the [GitHub releases](https://github.com/fosrl/newt/releases). +Find the latest version in the [GitHub releases](https://github.com/fosrl/cli/releases). ## Docker Installation @@ -12,16 +12,16 @@ Update the image version in your `docker-compose.yml`: ```yaml title="docker-compose.yml" services: - newt: - image: fosrl/newt:{version} # Replace {version} with the latest version tag + pangolin-site: + image: fosrl/pangolin-cli:{version} # Replace {version} with the latest version tag # ... rest of config ``` Then pull and restart: ```bash -docker compose pull newt -docker compose up -d newt +docker compose pull pangolin-site +docker compose up -d pangolin-site ``` ## Binary Installation @@ -31,17 +31,9 @@ docker compose up -d newt If you used the auto installer, simply run it again. ```bash -curl -fsSL https://static.pangolin.net/get-newt.sh | bash +curl -fsSL https://static.pangolin.net/get-cli.sh | bash ``` ### Manual Installation -Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/newt/releases) and replace your existing binary. - -```bash -wget -O newt "https://github.com/fosrl/newt/releases/download/{version}/newt_{architecture}" && chmod +x ./newt -``` - - -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. - +Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/cli/releases) and replace your existing binary. \ No newline at end of file diff --git a/manage/ssh.mdx b/manage/ssh.mdx index 4d9cb8f..d4a2126 100644 --- a/manage/ssh.mdx +++ b/manage/ssh.mdx @@ -18,7 +18,7 @@ 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 with no auth daemon, no OpenSSH reconfiguration, and no extra host setup beyond running Newt as root. With these defaults: @@ -26,9 +26,9 @@ With these defaults: 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@`—Pangolin prompts for the host password. To use a private key instead, pass it with `-i`: `pangolin ssh username@ -i `. +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@`-Pangolin prompts for the host password. To use a private key instead, pass it with `-i`: `pangolin ssh username@ -i `. -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-Newt still must run as root. With **Standard SSH Server** mode, follow the host setup sections below. ## Configuration Options @@ -38,7 +38,7 @@ 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. 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. | | **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. | @@ -84,7 +84,7 @@ 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 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. **Host setup required:** Run Newt as root on the site connector host (`sudo newt ...`). @@ -94,7 +94,7 @@ There are five valid configuration combinations. Auth daemon location is not app **Settings:** Mode = Pangolin SSH · Authentication = Automated Provisioning · Auth Daemon = On Site -**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. +**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. @@ -108,9 +108,9 @@ There are five valid configuration combinations. Auth daemon location is not app **When to use:** You need to reach an existing OpenSSH server on the network and users will authenticate with credentials already configured on that server. -**Example:** A legacy database server at `10.0.5.20` runs standard OpenSSH with per-user keys. You create a public SSH resource pointing at `10.0.5.20:22` with manual authentication. DBAs visit the resource FQDN, complete Pangolin authentication, then upload their private key in the browser form to open a terminal session. If the same host is reachable from multiple site connectors, select all applicable sites—Pangolin routes through the healthiest one automatically. +**Example:** A legacy database server at `10.0.5.20` runs standard OpenSSH with per-user keys. You create a public SSH resource pointing at `10.0.5.20:22` with manual authentication. DBAs visit the resource FQDN, complete Pangolin authentication, then upload their private key in the browser form to open a terminal session. If the same host is reachable from multiple site connectors, select all applicable sites-Pangolin routes through the healthiest one automatically. -**Host setup required:** None—use your existing OpenSSH configuration. +**Host setup required:** None-use your existing OpenSSH configuration. --- @@ -132,7 +132,7 @@ There are five valid configuration combinations. Auth daemon location is not app **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. -**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:** 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. **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). @@ -160,7 +160,7 @@ 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-no OpenSSH or auth daemon setup required on the host. Newt must still run as root. ## Host Setup @@ -175,7 +175,7 @@ Before setting up the host, create the SSH resource (public or private) in the d ## Option 1: Newt 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 @@ -214,7 +214,7 @@ Then configure the SSH server on this host as described in [Configure the SSH se ## Option 2: External auth daemon (SSH on another server that doesn't run Newt) -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 @@ -246,7 +246,7 @@ flowchart LR ### Prerequisites - **Newt** 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). +- **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 diff --git a/self-host/advanced/config-file.mdx b/self-host/advanced/config-file.mdx index fe0011e..d81650d 100644 --- a/self-host/advanced/config-file.mdx +++ b/self-host/advanced/config-file.mdx @@ -310,7 +310,7 @@ This section contains the complete reference for all configuration options in `c **Default**: `false` - **Environment Variable**: `ENABLE_AI_GATEWAY_CLIENT_IP_HEADER` + **Environment Variable**: `ENABLE_AI_GATEWAY_CLIENT_IP_HEADER` (or `ENABLE_AI_GATEWAY_CLIENT_IP_HEADER_FILE` to read the value from a file — see [Reading secrets from a file](#reading-secrets-from-a-file-_file-suffix)) Useful when an intermediary proxy sits between Traefik and the AI Gateway and overwrites `X-Forwarded-For`/`X-Real-Ip` instead of appending to them. Requires a Badger version that supports `realIpHeader`. @@ -336,7 +336,7 @@ This section contains the complete reference for all configuration options in `c Secret key for encrypting sensitive data. - **Environment Variable**: `SERVER_SECRET` + **Environment Variable**: `SERVER_SECRET` (or `SERVER_SECRET_FILE` to read the value from a file — see [Reading secrets from a file](#reading-secrets-from-a-file-_file-suffix)) **Minimum Length**: 8 characters @@ -765,7 +765,7 @@ This section contains the complete reference for all configuration options in `c SMTP username. - **Environment Variable**: `EMAIL_SMTP_USER` + **Environment Variable**: `EMAIL_SMTP_USER` (or `EMAIL_SMTP_USER_FILE` to read the value from a file — see [Reading secrets from a file](#reading-secrets-from-a-file-_file-suffix)) **Example**: `no-reply@example.com` @@ -773,7 +773,7 @@ This section contains the complete reference for all configuration options in `c SMTP password. - **Environment Variable**: `EMAIL_SMTP_PASS` + **Environment Variable**: `EMAIL_SMTP_PASS` (or `EMAIL_SMTP_PASS_FILE` to read the value from a file — see [Reading secrets from a file](#reading-secrets-from-a-file-_file-suffix)) @@ -938,6 +938,8 @@ This section contains the complete reference for all configuration options in `c PostgreSQL connection string. + **Environment Variable**: `POSTGRES_CONNECTION_STRING` (or `POSTGRES_CONNECTION_STRING_FILE` to read the value from a file — see [Reading secrets from a file](#reading-secrets-from-a-file-_file-suffix)) + **Example**: `postgresql://user:password@host:port/database` @@ -948,6 +950,8 @@ This section contains the complete reference for all configuration options in `c Read-only replica database configurations for load balancing. + **Environment Variable**: `POSTGRES_REPLICA_CONNECTION_STRINGS`, a comma-separated list of connection strings (or `POSTGRES_REPLICA_CONNECTION_STRINGS_FILE` to read the same comma-separated list from a file — see [Reading secrets from a file](#reading-secrets-from-a-file-_file-suffix)) + Connection string for the read replica database. @@ -1016,7 +1020,7 @@ This section contains the complete reference for all configuration options in `c Connection string for the dedicated logs database. - **Environment Variable**: `POSTGRES_LOGS_CONNECTION_STRING` + **Environment Variable**: `POSTGRES_LOGS_CONNECTION_STRING` (or `POSTGRES_LOGS_CONNECTION_STRING_FILE` to read the value from a file — see [Reading secrets from a file](#reading-secrets-from-a-file-_file-suffix)) **Example**: `postgresql://user:password@host:port/logs_database` @@ -1028,6 +1032,8 @@ This section contains the complete reference for all configuration options in `c Read-only replica configurations for the logs database. + **Environment Variable**: `POSTGRES_LOGS_REPLICA_CONNECTION_STRINGS`, a comma-separated list of connection strings (or `POSTGRES_LOGS_REPLICA_CONNECTION_STRINGS_FILE` to read the same comma-separated list from a file — see [Reading secrets from a file](#reading-secrets-from-a-file-_file-suffix)) + Connection string for the read replica logs database. @@ -1179,14 +1185,33 @@ The catalog feeds Known Models pickers, wildcard discovery, provider selection, Some configuration values can be set using environment variables for enhanced security: -| Name | Variable | Config | -|------|----------|--------| -| Server Secret | `SERVER_SECRET` | `server.secret` | -| Email Username | `EMAIL_SMTP_USER` | `email.smtp_user` | -| Email Password | `EMAIL_SMTP_PASS` | `email.smtp_pass` | -| PostgreSQL Connection String | `POSTGRES_CONNECTION_STRING` | `postgres.connection_string` | -| PostgreSQL Replica Connection Strings | `POSTGRES_REPLICA_CONNECTION_STRINGS` | `postgres.replicas` (comma-separated list of connection strings) | -| PostgreSQL Logs Connection String | `POSTGRES_LOGS_CONNECTION_STRING` | `postgres_logs.connection_string` | -| PostgreSQL Logs Replica Connection Strings | `POSTGRES_LOGS_REPLICA_CONNECTION_STRINGS` | `postgres_logs.replicas` (comma-separated list of connection strings) | -| Enable SQLite WAL Mode | `ENABLE_SQLITE_WAL_MODE` | *(SQLite only)* Set to `true` to enable [WAL mode](https://www.sqlite.org/wal.html) for improved SQLite concurrency | -| Enable AI Gateway Client IP Header | `ENABLE_AI_GATEWAY_CLIENT_IP_HEADER` | `server.enable_ai_gateway_client_ip_header` | \ No newline at end of file +| Name | Variable | Config | Supports `_FILE` | +|------|----------|--------|:---:| +| Server Secret | `SERVER_SECRET` | `server.secret` | YES | +| Email Username | `EMAIL_SMTP_USER` | `email.smtp_user` | YES | +| Email Password | `EMAIL_SMTP_PASS` | `email.smtp_pass` | YES | +| PostgreSQL Connection String | `POSTGRES_CONNECTION_STRING` | `postgres.connection_string` | YES | +| PostgreSQL Replica Connection Strings | `POSTGRES_REPLICA_CONNECTION_STRINGS` | `postgres.replicas` (comma-separated list of connection strings; the file, if used, should contain the same comma-separated list) | YES | +| PostgreSQL Logs Connection String | `POSTGRES_LOGS_CONNECTION_STRING` | `postgres_logs.connection_string` | YES | +| PostgreSQL Logs Replica Connection Strings | `POSTGRES_LOGS_REPLICA_CONNECTION_STRINGS` | `postgres_logs.replicas` (comma-separated list of connection strings; the file, if used, should contain the same comma-separated list) | YES | +| Enable SQLite WAL Mode | `ENABLE_SQLITE_WAL_MODE` | *(SQLite only)* Set to `true` to enable [WAL mode](https://www.sqlite.org/wal.html) for improved SQLite concurrency | YES | +| Enable AI Gateway Client IP Header | `ENABLE_AI_GATEWAY_CLIENT_IP_HEADER` | `server.enable_ai_gateway_client_ip_header` | YES | + +### Reading secrets from a file (`_FILE` suffix) + +For any variable marked "Supports `_FILE`" above, you can set `_FILE` instead of `` to a path on disk, and Pangolin will read that file and use its (trimmed) contents as the value. This is the standard way to consume [Docker/Swarm secrets](https://docs.docker.com/engine/swarm/secrets/) — for example a secret mounted at `/run/secrets/server_secret` — without ever putting the raw value in `config.yml`, a `.env` file, or the container's visible environment. + +Setting both `` and `_FILE` at the same time is an error. + +```yaml title="docker-compose.yml" +services: + pangolin: + secrets: + - server_secret + environment: + - SERVER_SECRET_FILE=/run/secrets/server_secret + +secrets: + server_secret: + file: ./secrets/server_secret.txt +``` \ No newline at end of file diff --git a/self-host/advanced/database-options.mdx b/self-host/advanced/database-options.mdx index f18ebb0..ca17084 100644 --- a/self-host/advanced/database-options.mdx +++ b/self-host/advanced/database-options.mdx @@ -119,7 +119,7 @@ postgres: #### Using Environment Variables -You can instead provide replica connection strings with the `POSTGRES_REPLICA_CONNECTION_STRINGS` environment variable, as a comma-separated list. This must be used together with `POSTGRES_CONNECTION_STRING` for the primary database — the two env vars replace the entire `postgres.connection_string` / `postgres.replicas` config as a unit. +You can instead provide replica connection strings with the `POSTGRES_REPLICA_CONNECTION_STRINGS` environment variable, as a comma-separated list. This must be used together with `POSTGRES_CONNECTION_STRING` for the primary database - the two env vars replace the entire `postgres.connection_string` / `postgres.replicas` config as a unit. ```bash title=".env" POSTGRES_CONNECTION_STRING=postgresql://:@:/ diff --git a/self-host/advanced/private-config-file.mdx b/self-host/advanced/private-config-file.mdx index 5f13ff5..cda42b2 100644 --- a/self-host/advanced/private-config-file.mdx +++ b/self-host/advanced/private-config-file.mdx @@ -106,6 +106,8 @@ This section contains the complete reference for all configuration options in `p Redis authentication password. + + **Environment Variable**: `REDIS_PASSWORD` (or `REDIS_PASSWORD_FILE` to read the value from a file — see [Reading secrets from a file](/self-host/advanced/config-file#reading-secrets-from-a-file-_file-suffix)) ```yaml redis: @@ -493,4 +495,14 @@ This section contains the complete reference for all configuration options in `p ### Branding Configuration -Please refer to the [branding configuration documentation](/manage/branding). \ No newline at end of file +Please refer to the [branding configuration documentation](/manage/branding). + +## Environment Variables + +Some configuration values can be set using environment variables for enhanced security: + +| Name | Variable | Config | Supports `_FILE` | +|------|----------|--------|:---:| +| Redis Password | `REDIS_PASSWORD` | `redis.password` | YES | + +Any variable marked "Supports `_FILE`" can also be set as `_FILE`, pointing to a file on disk whose (trimmed) contents are used as the value instead — see [Reading secrets from a file](/self-host/advanced/config-file#reading-secrets-from-a-file-_file-suffix) in the main configuration file docs for details and a Docker Compose example. \ No newline at end of file