diff --git a/development/system-architecture.mdx b/development/system-architecture.mdx index f80143f..1cdffc9 100644 --- a/development/system-architecture.mdx +++ b/development/system-architecture.mdx @@ -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/manage/sites/configure-site.mdx b/manage/sites/configure-site.mdx index c077701..03230ef 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` @@ -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. @@ -453,9 +472,9 @@ If `--config-file`/`CONFIG_FILE` isn't set, Newt reads and writes the config fil | 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 | `~/.config/pangolin/site.json` | +| Linux / others | `~/.config/pangolin/site.json` | ### Example @@ -530,16 +549,16 @@ 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 ``` @@ -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 \