mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-09-17 11:29:09 +02:00
Update newt to cli site connector
This commit is contained in:
Owen
@@ -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"
|
||||
---
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
Only available in [Pangolin Cloud](https://app.pangolin.net/auth/signup) and [Enterprise Edition](/self-host/enterprise-edition).
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -213,7 +213,7 @@ Almost every setting below can also be set via an environment variable (**Env va
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="health-file" type="string">
|
||||
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`
|
||||
|
||||
@@ -233,7 +233,7 @@ Almost every setting below can also be set via an environment variable (**Env va
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="blueprint-file" type="string">
|
||||
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`
|
||||
|
||||
@@ -462,18 +462,18 @@ 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 | `~/.config/pangolin/site.json` |
|
||||
| Windows | `~/.config/pangolin/site.json` |
|
||||
| Windows | `C:\Users\<Username>\.config\pangolin\site.json` |
|
||||
| Linux / others | `~/.config/pangolin/site.json` |
|
||||
|
||||
### Example
|
||||
@@ -487,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,
|
||||
|
||||
@@ -512,7 +512,7 @@ If `--config-file`/`CONFIG_FILE` isn't set, Newt reads and writes the config fil
|
||||
```
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
@@ -521,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`
|
||||
|
||||
@@ -563,12 +563,12 @@ services:
|
||||
```
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
**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
|
||||
@@ -577,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.
|
||||
|
||||
<Warning>
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
## 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"
|
||||
@@ -610,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)
|
||||
|
||||
|
||||
+89
-109
@@ -1,79 +1,83 @@
|
||||
---
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
<Note>
|
||||
Deploying Newt in Kubernetes instead? See the dedicated [Kubernetes](/manage/sites/kubernetes/helm) docs — install guides for [Helm](/manage/sites/kubernetes/helm) and [Kustomize](/manage/sites/kubernetes/kustomize), a full [Configuration](/manage/sites/kubernetes/configuration) reference, and [Troubleshooting](/manage/sites/kubernetes/troubleshooting).
|
||||
Deploying a site in Kubernetes? See the dedicated [Kubernetes](/manage/sites/kubernetes/helm) docs - install guides for [Helm](/manage/sites/kubernetes/helm) and [Kustomize](/manage/sites/kubernetes/kustomize), a full [Configuration](/manage/sites/kubernetes/configuration) reference, and [Troubleshooting](/manage/sites/kubernetes/troubleshooting).
|
||||
</Note>
|
||||
|
||||
## Binary Installation
|
||||
|
||||
### Quick Install (Recommended)
|
||||
|
||||
Use this command to automatically install Newt. It detects your system architecture automatically and always pulls the latest version, adding Newt to your PATH:
|
||||
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 Newt on Windows, use the latest installer from [GitHub releases](https://github.com/fosrl/newt/releases/latest).
|
||||
|
||||
{/* <Warning>
|
||||
If you are using Newt on Windows as a service or with clients, `wintun.dll` may be required.
|
||||
</Warning> */}
|
||||
To run a site on Windows, use the latest installer from [GitHub releases](https://github.com/fosrl/cli/releases/latest).
|
||||
|
||||
### Manual Download
|
||||
|
||||
Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/newt/releases/latest) for ARM and AMD64 (x86_64) architectures.
|
||||
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.
|
||||
|
||||
Download and install manually:
|
||||
### Running the Site
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
<Note>
|
||||
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/newt/releases) for the latest information.
|
||||
</Note>
|
||||
|
||||
### Running Newt
|
||||
|
||||
Run Newt with the configuration from Pangolin:
|
||||
|
||||
```bash
|
||||
newt \
|
||||
pangolin up site \
|
||||
--id 31frd0uzbjvp721 \
|
||||
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
||||
--endpoint https://app.pangolin.net
|
||||
```
|
||||
|
||||
### Systemd Service
|
||||
### Systemd Service (Recommended)
|
||||
|
||||
Create `/etc/newt/newt.env` with the initial values from your Pangolin site configuration:
|
||||
The CLI can install and manage the systemd service for you:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 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 +85,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,10 +98,10 @@ WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Make sure the binary exists at `/usr/local/bin/newt` before daemon reload and starting the service:
|
||||
Make sure the binary exists at `/usr/local/bin/pangolin` before daemon reload and starting the service:
|
||||
|
||||
```bash
|
||||
which newt
|
||||
which pangolin
|
||||
```
|
||||
</Warning>
|
||||
|
||||
@@ -105,11 +109,11 @@ 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 +121,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 +143,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 +169,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 +189,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 +227,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:
|
||||
<Note>
|
||||
The Kubernetes install still uses the legacy Newt for the Helm chart, namespace, and secret keys shown below.
|
||||
</Note>
|
||||
|
||||
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:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Helm" href="/manage/sites/kubernetes/helm" icon="box">
|
||||
Quick-start guide for installing Newt with Helm.
|
||||
Quick-start guide for installing a site with Helm.
|
||||
</Card>
|
||||
<Card title="Kustomize" href="/manage/sites/kubernetes/kustomize" icon="layer-group">
|
||||
Install Newt with rendered manifests and Kustomize overlays.
|
||||
Install a site with rendered manifests and Kustomize overlays.
|
||||
</Card>
|
||||
<Card title="Configuration" href="/manage/sites/kubernetes/configuration" icon="sliders">
|
||||
Full configuration reference for Helm and Kustomize workflows.
|
||||
</Card>
|
||||
<Card title="Troubleshooting" href="/manage/sites/kubernetes/troubleshooting" icon="circle-question">
|
||||
Debug Newt deployment and connection issues in Kubernetes.
|
||||
Debug site deployment and connection issues in Kubernetes.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -253,15 +262,15 @@ Container management UIs like Portainer typically allow passing commands and env
|
||||
|
||||
### Windows Service
|
||||
|
||||
On Windows, newt can be run as a service or normally as a binary in a session.
|
||||
On Windows, the site connector 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:
|
||||
If you are installing the service, we recommend writing the config into the config file location first, following the [config file format](/manage/sites/install-site#config-file-injected-as-compose-secret), with the provisioning key. Since the service runs under the `SYSTEM` account, its config lives under that account's profile at `C:\WINDOWS\system32\config\systemprofile\.config\pangolin\site.json`. Alternatively, you can install the service and start it with CLI args, which will also work. For example:
|
||||
|
||||
```
|
||||
newt install
|
||||
newt start --endpoint https://app.pangolin.net --provisioning-key <provisioning-key>
|
||||
pangolin.exe service install site
|
||||
pangolin.exe service start site --endpoint https://app.pangolin.net --provisioning-key <provisioning-key>
|
||||
```
|
||||
|
||||
This will provision a new service, start it, and create the config file for future starts.
|
||||
@@ -270,45 +279,16 @@ This will provision a new service, start it, and create the config file for futu
|
||||
|
||||
```
|
||||
# Install the service
|
||||
newt.exe install
|
||||
|
||||
# Start the service
|
||||
newt.exe start
|
||||
pangolin.exe service install site --id <id> --secret <secret> --endpoint https://app.pangolin.net
|
||||
|
||||
# Stop the service
|
||||
newt.exe stop
|
||||
pangolin.exe service logs site
|
||||
|
||||
# Check service status
|
||||
newt.exe status
|
||||
pangolin.exe service status site
|
||||
|
||||
# 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
|
||||
pangolin.exe service uninstall site
|
||||
```
|
||||
|
||||
### Advantech Router App
|
||||
@@ -318,13 +298,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.
|
||||
|
||||
<Frame caption="Screenshot of installing the router app on an Advantech router UI">
|
||||
<img src="/images/advantech_router_app_install.png" alt="Advantech router UI showing Newt router app installation" width="400" centered/>
|
||||
<img src="/images/advantech_router_app_install.png" alt="Advantech router UI showing site router app installation" width="400" centered/>
|
||||
</Frame>
|
||||
|
||||
After installation, click on the router app link at the top of the page to configure the app with your 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.
|
||||
|
||||
<Frame caption="Screenshot of configuring the router app on an Advantech router UI">
|
||||
<img src="/images/advantech_router_app_configure.png" alt="Advantech router UI showing Newt credential configuration" width="400" centered/>
|
||||
<img src="/images/advantech_router_app_configure.png" alt="Advantech router UI showing site credential configuration" width="400" centered/>
|
||||
</Frame>
|
||||
|
||||
A complete config file is located at `/etc/newt/settings` on the router. You can edit this file directly to change credentials or add additional configuration options. After making changes, restart the router app to apply the new configuration. An example settings file can be found at: https://github.com/fosrl/newt/blob/main/packages/advantech/merge/etc/defaults
|
||||
|
||||
@@ -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.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/site-provisioning-flow.png" alt="Flow: provision with pre-shared key, exchange for ID and secret, apply YAML, pending approval, admin approves" centered />
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
<Note>
|
||||
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/newt/releases) for the latest information.
|
||||
</Note>
|
||||
Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/cli/releases) and replace your existing binary.
|
||||
Reference in New Issue
Block a user