mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: add new Access Control and Logs documentation pages

Browse Source 
- Documented Access Control features (e.g., Device Approvals, Password Rotation, 2FA, Custom Login Pages).
- Added detailed descriptions for Logs & Analytics (Access Logs, Request Logs, Action Logs).
- Included configuration instructions and feature-specific notes for Pangolin Cloud and Enterprise Edition.

Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
This commit is contained in:
Stefan Mogeritsch
2026-03-11 11:24:24 +01:00
parent a70f132fd9
commit aa157e82f8
87 changed files with 13163 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Configure_Sites.md
+522
View File
@@ -0,0 +1,522 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure Sites
> Configure Newt for connecting to Pangolin sites
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
## Flags
<ResponseField name="id" type="string" required>
Newt ID generated by Pangolin to identify the client.
**Example**: `31frd0uzbjvp721`
</ResponseField>
<ResponseField name="secret" type="string" required>
A unique secret used to authenticate the client ID with the websocket.
**Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`
<Warning>
Keep this secret private and secure. It's used for authentication.
</Warning>
</ResponseField>
<ResponseField name="endpoint" type="string" required>
The endpoint where both Gerbil and Pangolin reside for websocket connections.
**Example**: `https://pangolin.example.com`
</ResponseField>
<ResponseField name="port" type="integer">
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.
**Example**: `34534`
</ResponseField>
<ResponseField name="mtu" type="integer">
MTU for the internal WireGuard interface.
**Default**: `1280`
</ResponseField>
<ResponseField name="dns" type="string">
DNS server to use for resolving the endpoint.
**Default**: `9.9.9.9`
</ResponseField>
<ResponseField name="log-level" type="string">
The log level to use for Newt output.
**Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
**Default**: `INFO`
</ResponseField>
<ResponseField name="ping-interval" type="string">
Interval for pinging the server.
**Default**: `3s`
</ResponseField>
<ResponseField name="ping-timeout" type="string">
Timeout for each ping.
**Default**: `5s`
</ResponseField>
<ResponseField name="docker-socket" type="string">
Set the Docker socket path for container discovery integration.
**Example**: `/var/run/docker.sock`
</ResponseField>
<ResponseField name="docker-enforce-network-validation" type="boolean">
Validate the container target is on the same network as the Newt process.
**Default**: `false`
</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.
**Example**: `/tmp/healthy`
</ResponseField>
<ResponseField name="updown" type="string">
Script to be called when targets are added or removed.
**Example**: `/path/to/updown.sh`
</ResponseField>
<ResponseField name="blueprint-file" type="string">
Path to blueprint file to define Pangolin resources and configurations.
**Example**: `/path/to/blueprint.yaml`
</ResponseField>
<ResponseField name="no-cloud" type="boolean">
Don't fail over to the cloud when using managed nodes in Pangolin Cloud.
**Default**: `false`
</ResponseField>
<ResponseField name="disable-clients" type="boolean">
Disable clients on the WireGuard interface.
**Default**: `false` (clients enabled)
</ResponseField>
<ResponseField name="interface" type="string">
Name of the WireGuard interface.
**Default**: `newt`
</ResponseField>
<ResponseField name="metrics" type="boolean">
Enable Prometheus /metrics exporter.
**Default**: `true`
</ResponseField>
<ResponseField name="otlp" type="boolean">
Enable OTLP exporters (metrics/traces) to OTEL\_EXPORTER\_OTLP\_ENDPOINT.
**Default**: `false`
</ResponseField>
<ResponseField name="metrics-admin-addr" type="string">
Admin/metrics bind address.
**Default**: `127.0.0.1:2112`
</ResponseField>
<ResponseField name="metrics-async-bytes" type="boolean">
Enable async bytes counting (background flush; lower hot path overhead).
**Default**: `false`
</ResponseField>
<ResponseField name="region" type="string">
Optional region resource attribute for telemetry and metrics.
**Example**: `us-west-2`
</ResponseField>
<ResponseField name="enforce-hc-cert" type="boolean">
Enforce certificate validation for health checks.
**Default**: `false` (accepts any cert)
</ResponseField>
<ResponseField name="tls-client-cert-file" type="string">
Path to client certificate file (PEM/DER format) for mTLS.
**Example**: `/path/to/client.crt`
</ResponseField>
<ResponseField name="tls-client-key" type="string">
Path to client private key file (PEM/DER format) for mTLS.
**Example**: `/path/to/client.key`
</ResponseField>
<ResponseField name="tls-client-ca" type="string">
Path to CA certificate file for validating remote certificates (can be specified multiple times).
**Example**: `/path/to/ca.crt`
</ResponseField>
<ResponseField name="tls-client-cert" type="string">
Path to client certificate (PKCS12 format) - DEPRECATED: use `--tls-client-cert-file` and `--tls-client-key` instead.
**Example**: `/path/to/client.p12`
</ResponseField>
<ResponseField name="prefer-endpoint" type="string">
Prefer this endpoint for the connection (if set, will override the endpoint from the server).
**Example**: `https://preferred.endpoint.com`
</ResponseField>
## Environment Variables
All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables
are particularly useful when running Newt in containerized environments.
<Note>
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
</Note>
<ResponseField name="PANGOLIN_ENDPOINT" type="string">
Endpoint of your Pangolin server (equivalent to `--endpoint`)
</ResponseField>
<ResponseField name="NEWT_ID" type="string">
Newt ID generated by Pangolin (equivalent to `--id`)
</ResponseField>
<ResponseField name="NEWT_SECRET" type="string">
Newt secret for authentication (equivalent to `--secret`)
</ResponseField>
<ResponseField name="PORT" type="integer">
Port for the peers to connect to Newt on (equivalent to `--port`)
</ResponseField>
<ResponseField name="MTU" type="integer">
MTU for the internal WireGuard interface (equivalent to `--mtu`)
**Default**: `1280`
</ResponseField>
<ResponseField name="DNS" type="string">
DNS server to use for resolving the endpoint (equivalent to `--dns`)
**Default**: `9.9.9.9`
</ResponseField>
<ResponseField name="CONFIG_FILE" type="string">
Load the config JSON from this file instead of in the home folder.
</ResponseField>
<ResponseField name="BLUEPRINT_FILE" type="string">
Path to blueprint file to define Pangolin resources and configurations (equivalent to `--blueprint-file`).
</ResponseField>
<ResponseField name="NO_CLOUD" type="boolean">
Don't fail over to the cloud when using managed nodes in Pangolin Cloud (equivalent to `--no-cloud`).
**Default**: `false`
</ResponseField>
<ResponseField name="LOG_LEVEL" type="string">
Log level (equivalent to `--log-level`)
**Default**: `INFO`
</ResponseField>
<ResponseField name="DOCKER_SOCKET" type="string">
Path to Docker socket for container discovery (equivalent to `--docker-socket`)
</ResponseField>
<ResponseField name="PING_INTERVAL" type="string">
Interval for pinging the server (equivalent to `--ping-interval`)
**Default**: `3s`
</ResponseField>
<ResponseField name="PING_TIMEOUT" type="string">
Timeout for each ping (equivalent to `--ping-timeout`)
**Default**: `5s`
</ResponseField>
<ResponseField name="UPDOWN_SCRIPT" type="string">
Path to updown script for target add/remove events (equivalent to `--updown`)
</ResponseField>
<ResponseField name="DOCKER_ENFORCE_NETWORK_VALIDATION" type="boolean">
Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`)
**Default**: `false`
</ResponseField>
<ResponseField name="HEALTH_FILE" type="string">
Path to health file for connection monitoring (equivalent to `--health-file`)
</ResponseField>
<ResponseField name="DISABLE_CLIENTS" type="boolean">
Disable clients on the WireGuard interface (equivalent to `--disable-clients`).
**Default**: `false`
</ResponseField>
<ResponseField name="INTERFACE" type="string">
Name of the WireGuard interface (equivalent to `--interface`)
**Default**: `newt`
</ResponseField>
<ResponseField name="NEWT_METRICS_PROMETHEUS_ENABLED" type="boolean">
Enable Prometheus /metrics exporter (equivalent to `--metrics`).
**Default**: `true`
</ResponseField>
<ResponseField name="NEWT_METRICS_OTLP_ENABLED" type="boolean">
Enable OTLP exporters (metrics/traces) to OTEL\_EXPORTER\_OTLP\_ENDPOINT (equivalent to `--otlp`).
**Default**: `false`
</ResponseField>
<ResponseField name="NEWT_ADMIN_ADDR" type="string">
Admin/metrics bind address (equivalent to `--metrics-admin-addr`).
**Default**: `127.0.0.1:2112`
</ResponseField>
<ResponseField name="NEWT_METRICS_ASYNC_BYTES" type="boolean">
Enable async bytes counting (background flush; lower hot path overhead, equivalent to `--metrics-async-bytes`).
**Default**: `false`
</ResponseField>
<ResponseField name="NEWT_REGION" type="string">
Optional region resource attribute for telemetry and metrics (equivalent to `--region`).
</ResponseField>
<ResponseField name="ENFORCE_HC_CERT" type="boolean">
Enforce certificate validation for health checks (equivalent to `--enforce-hc-cert`).
**Default**: `false`
</ResponseField>
<ResponseField name="TLS_CLIENT_CERT" type="string">
Path to client certificate file (PEM/DER format) for mTLS (equivalent to `--tls-client-cert-file`)
</ResponseField>
<ResponseField name="TLS_CLIENT_KEY" type="string">
Path to client private key file (PEM/DER format) for mTLS (equivalent to `--tls-client-key`)
</ResponseField>
<ResponseField name="TLS_CLIENT_CAS" type="string">
Comma-separated list of CA certificate file paths for validating remote certificates (equivalent to multiple `--tls-client-ca` flags)
</ResponseField>
<ResponseField name="TLS_CLIENT_CERT_PKCS12" type="string">
Path to client certificate (PKCS12 format) - DEPRECATED: use `TLS_CLIENT_CERT` and `TLS_CLIENT_KEY` instead
</ResponseField>
## Loading secrets from files
You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
```
$ cat ~/.config/newt-client/config.json
{
"id": "spmzu8rbpzj1qq6",
"secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
"endpoint": "https://app.pangolin.net",
"tlsClientCert": ""
}
```
This file is also written to when newt first starts up. So you do not need to run every time with --id and secret if you
have run it once!
Default locations:
* **macOS**: `~/Library/Application Support/newt-client/config.json`
* **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json`
* **Linux/Others**: `~/.config/newt-client/config.json`
## 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.
**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.
Supported values include:
* Local UNIX socket (default):
> You must mount the socket file into the container using a volume, so Newt can access it.
`unix:///var/run/docker.sock`
* TCP socket (e.g., via Docker Socket Proxy):
`tcp://localhost:2375`
* HTTP/HTTPS endpoints (e.g., remote Docker APIs):
`http://your-host:2375`
* SSH connections (experimental, requires SSH setup):
`ssh://user@host`
```yaml theme={null}
services:
newt:
image: fosrl/newt
container_name: newt
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
- DOCKER_SOCKET=unix:///var/run/docker.sock
```
<Note>
If the Docker socket is not available or accessible, Newt 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:
* **Running in Network Mode 'host'**: IP addresses will be used
* **Running in Network Mode 'bridge'**: IP addresses will be used
* **Running in docker-compose without a network specification**: Docker compose creates a network for the compose by
default, hostnames will be used
* **Running on docker-compose with defined network**: Hostnames will be used
**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.
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.
</Warning>
## Updown Scripts
You can pass in an updown script for Newt to call when it is adding or removing a target:
```bash theme={null}
--updown "python3 test.py"
```
The script will be called with arguments when a target is added or removed:
```bash theme={null}
python3 test.py add tcp localhost:8556
python3 test.py remove tcp localhost:8556
```
<Info>
Returning a string from the script in the format of a target (`ip:dst` so `10.0.0.1:8080`) will override the target and use this value instead to proxy.
</Info>
<Note>
You can look at `updown.py` as a reference script to get started!
</Note>
## 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.
### Option 1: PKCS12 (Legacy)
<Note>
This is the original method and still supported.
</Note>
**Requirements:**
* File must contain:
* Client private key
* Public certificate
* CA certificate
* Encrypted `.p12` files are **not supported**
**Example:**
```bash theme={null}
newt \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--tls-client-cert ./client.p12
```
### Option 2: Split PEM Files (Preferred)
You can now provide separate files for:
* `--tls-client-cert-file`: client certificate (`.crt` or `.pem`)
* `--tls-client-key`: client private key (`.key` or `.pem`)
* `--tls-client-ca`: CA cert to verify the server (can be specified multiple times)
**Example:**
```bash theme={null}
newt \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--tls-client-cert-file ./client.crt \
--tls-client-key ./client.key \
--tls-client-ca ./ca.crt
```
## NAT Traversal Tweaks
Newt supports NAT traversal to allow clients to connect directly to Newt sites without relaying through the Pangolin
server, improving performance and reducing latency.
In some environment depending on the NAT type and firewall, you may need to tweak some settings to get optimal
connectivity in the firewall itself. Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some
firewall changes you might be able to make.
Another option is to keep newt listening for client connections on a static port. This allows you to open a specific
port in your firewall for Newt client connections instead of random high ports. You can do this by setting the `--port`
flag or `PORT` environment variable and then opening this port in the your firewall to DNAT to Newt.
docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Install_Sites.md
+239
View File
@@ -0,0 +1,239 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Install Sites
> Install Newt as a binary or Docker container
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
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.
## 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:
```bash theme={null}
curl -fsSL https://static.pangolin.net/get-newt.sh | bash
```
#### Windows
If you would like to use Newt on Windows as a service or with clients, wintun.dll is sometimes required. Please use
latest installer from [GitHub releases](https://github.com/fosrl/newt/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.
Download and install manually:
```bash theme={null}
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 theme={null}
newt \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://app.pangolin.net
```
### Systemd Service
Create a basic systemd service:
```ini title="/etc/systemd/system/newt.service" theme={null}
[Unit]
Description=Newt
After=network.target
[Service]
ExecStart=/usr/local/bin/newt --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://app.pangolin.net
Restart=always
User=root
[Install]
WantedBy=multi-user.target
```
<Warning>
Make sure to move the binary to `/usr/local/bin/newt` before creating the service!
</Warning>
## Docker Installation
### Pull the Image
Pull the latest Newt image from Docker Hub:
```bash theme={null}
docker pull fosrl/newt:latest
```
### Run with Docker
Run Newt with CLI arguments from Pangolin:
```bash theme={null}
docker run -it fosrl/newt --id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://app.pangolin.net
```
### Docker Compose
#### Environment Variables (Recommended)
```yaml title="docker-compose.yml" theme={null}
services:
newt:
image: fosrl/newt
container_name: newt
restart: unless-stopped
environment:
- PANGOLIN_ENDPOINT=https://app.pangolin.net
- NEWT_ID=2ix2t8xk22ubpfy
- NEWT_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" theme={null}
{
"id": "2ix2t8xk22ubpfy",
"secret": "nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2",
"endpoint": "https://app.pangolin.net",
"tlsClientCert": ""
}
```
Then register and reference the secret in your `docker-compose.yml`:
```yaml title="docker-compose.yml" theme={null}
services:
newt:
image: fosrl/newt
container_name: newt
restart: unless-stopped
environment:
- CONFIG_FILE=/run/secrets/newt-config
secrets:
- newt-config
secrets:
newt-config:
file: ./newt-config.secret
```
This allows you to separate sensitive secrets from plain configuration, improving security when storing or sharing your
`docker-compose.yml` anywhere else.
#### CLI Arguments
```yaml title="docker-compose.yml" theme={null}
services:
newt:
image: fosrl/newt
container_name: newt
restart: unless-stopped
command:
- --id 31frd0uzbjvp721
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
- --endpoint https://app.pangolin.net
```
Start the service:
```bash theme={null}
docker compose up -d
```
## Platform-Specific Installation
### Unraid
Newt is available in the Unraid Community Applications store. Search for "Newt" and follow the installation prompts.
Enter the ID, secret, and endpoint from Pangolin in the template fields.
<Frame caption="Newt available in Unraid Community Applications store">
<img src="https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/unraid_store.png?fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=c726d330c8c27969304ed49fcab0d0a2" alt="Newt on CA" data-og-width="1142" width="1142" data-og-height="746" height="746" data-path="images/unraid_store.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/unraid_store.png?w=280&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=011fb8e63da725aa4f054d4373eaa17f 280w, https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/unraid_store.png?w=560&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=27593e79ed245aeca68a55b4a63886b7 560w, https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/unraid_store.png?w=840&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=1f2e1e6c26434cc78d7aba1cc9a8c6a0 840w, https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/unraid_store.png?w=1100&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=184ed00cc2e9687f0c89e227331aaac1 1100w, https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/unraid_store.png?w=1650&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=f9a654ed532cbddaf48f5369a638e987 1650w, https://mintcdn.com/fossorial/u-2SUNWyK_LJL3sU/images/unraid_store.png?w=2500&fit=max&auto=format&n=u-2SUNWyK_LJL3sU&q=85&s=db5abf30d3b912ca0776e78388ae702e 2500w" />
</Frame>
### 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 to be installed and run as a Windows service to remain persistent.
#### 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 theme={null}
Get-EventLog -LogName Application -Source "newtWireguardService" -Newest 10
```
docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Kubernetes.md
+113
View File
@@ -0,0 +1,113 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Kubernetes
> How to deploy a Newt Site on Kubernetes
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
This guide walks you through setting up Newt on Kubernetes using Helm.
This guide assumes you already are familiar with Kubernetes concepts and you fulfill the following Global prerequisites:
## Global Prerequisites
* Kubernetes Cluster (v1.28.15+)
* Access to the Kubernetes Cluster
* Helm (v3.0+) installed, see <Link href="https://helm.sh/docs/intro/install/">Helm install docs</Link>
## Helm Installation
All Fossorial Helm charts are available on Artifact Hub.
See <Link href="https://artifacthub.io/packages/search?org=fosrl">Fossorial Charts</Link>.
<Steps>
<Step title="Add Fossorial Helm repo">
```bash theme={null}
helm repo add fossorial https://charts.fossorial.io
helm repo update fossorial
helm search repo fossorial
```
</Step>
<Step title="Prepare Installation files">
Prepare your Newt credentials:
```env title="newt-cred.env" theme={null}
PANGOLIN_ENDPOINT=<your-endpoint>
NEWT_ID=<your-id>
NEWT_SECRET=<your-secret>
```
Prepare a values file with your desired configuration.
<Tip>See <Link href="https://github.com/fosrl/helm-charts/tree/main/charts/newt">Newt chart values configuration options</Link>.</Tip>
```yaml title="values-newt.yaml" theme={null}
newtInstances:
- name: main
enabled: true
auth:
existingSecretName: newt-cred
keys:
endpointKey: PANGOLIN_ENDPOINT
idKey: NEWT_ID
secretKey: NEWT_SECRET
```
</Step>
<Step title="Newt Installation">
Create a Kubernetes Secret from the env file created earlier:
```bash theme={null}
kubectl create secret generic newt-cred -n newt --from-env-file=newt-cred.env
```
Install Newt with Helm:
```bash theme={null}
helm install my-newt fossorial/newt \
-n newt --create-namespace \
-f values-newt.yaml
```
Change the release name (`my-newt`), namespace (`newt`), and values filename as needed.
</Step>
<Step title="Upgrade or rollback">
```bash theme={null}
# Update repo to get latest charts
helm repo update fossorial
# Upgrade Newt (after editing values)
helm upgrade my-newt fossorial/newt -n newt -f values-newt.yaml
```
```bash theme={null}
# Roll back to a previous revision
helm rollback my-newt 1 -n newt
```
</Step>
</Steps>
## Customizing Your Values
All configuration options are documented in the respective repositories:
* <Link href="https://github.com/fosrl/helm-charts/tree/main/charts/newt">Newt Helm chart values</Link>
## References
* <Link href="https://github.com/fosrl/helm-charts">All Fossorial Helm Charts repo</Link>
* <Link href="https://github.com/fosrl/kubernetes">All Fossorial Kubernetes resources</Link>
* <Link href="https://github.com/fosrl/pangolin-kube-controller">Pangolin Kubernetes Controller</Link>
* <Link href="https://helm.sh/docs/">Helm documentation</Link>
docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Site_Credentials.md
+70
View File
@@ -0,0 +1,70 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Site Credentials
> Understanding how site credentials work and how they can be rotated & regenerated
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
## Understanding Credentials
Every site is provisioned with a unique identifier (ID), secret, and endpoint. The site uses the combination of these
three to establish a secure, encrypted connection to the server.
### ID
Example: `ln8yqs6w85la5zg`
The ID represents the site connection type in the system. Every Newt site has an ID.
This value is not a secret and it is okay if made publically available.
### Secret
Example: `tfpwoc580jf1l1glfagix0o97p8kirjogdflqg604n0tr3to`
The secret represents the "password" of the site. This secret must match the secret hashed in the system for the
relevant ID.
<Note>
This is a *secret*! Only share it with trusted people and be sure to store it safely and securely.
</Note>
When the site connects, it uses this secret as a first handshake with the server. The server then passes temporary
session credentials back to the site before it can initiate a websocket connection. Once the websocket connection is
established, ephemeral keys are used to establish tunnels using WireGuard.
### Endpoint
Example: `https://app.pangolin.net` or `https://pangolin.my-server.com`
The endpoint is how the site knows which server to connect to. This is the fully qualified hostname of the Pangolin
server (the URL you use to access the dashboard). For Pangolin cloud, the endpoint is `https://app.pangolin.net`. The
site uses this endpoint ot establish a websocket connection and receive control messages from the server.
## Rotating and Regenerating Credentials
<Note>
This is an [Enterprise Edition](/self-host/enterprise-edition)-only feature.
</Note>
Site credentials can be regenerated. Regenerating credentials will completely invalidate the previous ID and secret. Use
this feature if you have lost the secret and need to reset the credentials, or if you wish to rotate credentials on a
regular basis for extra security.
To regenerate credentials, visit Sites > Your Site > Credentials in the Pangolin admin dashboard.
### Regenerate vs. Regenerate and Disconnect
Regenerate simply recreates the credentials and invalidates the old ones. The site will remain connected until you
restart it with the new credentials.
Regenerate and Disconnect recreates the credentials and invalides the old ones. The site will instantly disconnect and
will require you to restart it with the new credentials.
docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Understanding_Sites.md
+76
View File
@@ -0,0 +1,76 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Understanding Sites
> Create a site to connect to a remote network and expose resources
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
A site is a connection to a network where your resources live. Pangolin uses sites to make public and private resources
available to users. Every resource belongs to one or more sites. Newt is Pangolin's connector that establishes this
connection and routes traffic to targets on remote networks.
## The Basics
* **Tunneled sites should always run behind a firewall.** Do not expose a site directly to the public internet.
* **Users do not connect to a site directly.** Admins define public (browser-based) or private resources on the site's
network, and users connect to those resources.
* **You can run one or multiple sites per network.** You need at least one site to provide access, but you can run
multiple sites in the same network for redundancy.
* **Sites are software-defined proxies and deny traffic by default.** Deploying a site does not automatically expose
hosts. Admins must define resources and assign access.
## Site Types
Pangolin supports three different types of sites, each designed for different use cases and deployment scenarios.
### Newt Site (Recommended)
This site type exposes resources on a remote network through a managed tunnel and websocket connection. It requires the
Newt connector on the remote network. This is the easiest setup and does not require NAT configuration.
Use Newt sites in most deployments. Newt is the primary connector type and supports the broadest feature set.
Newt sites support:
* Public HTTPS proxied resources
* Private resources
* Load balancing
* Health checking
* Docker socket scanning
* And more
### Local Site
Use this to expose resources on the same host as your Pangolin server (self-hosted only). No tunnels are created.
Required ports must be open on the Pangolin host.
Use local sites when the resource runs on the same machine as your self-hosted Pangolin instance.
Local sites do not support:
* Private resources
* Health checking
* Docker socket scanning
### Basic WireGuard Site
This option is self-hosted only. It uses a raw WireGuard connection without Newt, so there is no websocket control
channel and setup is more manual. NAT is required to reach targets on other hosts in the remote network. Without NAT,
you can expose only resources on the WireGuard peer host itself.
In general, use Basic WireGuard sites only for specific advanced use cases.
Basic WireGuard sites do not support:
* Using LAN-style addresses as targets
* Private resources
* Health checking
* Docker socket scanning
docs/01_Architecture/Pangolin/Mange_Pangolin/Sites/Update_Sites.md
+59
View File
@@ -0,0 +1,59 @@
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Sites
> Update Newt to the latest version
<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
<Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
</Card>
</div>
The update process depends on how you originally installed Newt.
Find the latest version in the [GitHub releases](https://github.com/fosrl/newt/releases).
## Docker Installation
Update the image version in your `docker-compose.yml`:
```yaml title="docker-compose.yml" theme={null}
services:
newt:
image: fosrl/newt:{version} # Replace {version} with the latest version tag
# ... rest of config
```
Then pull and restart:
```bash theme={null}
docker compose pull newt
docker compose up -d newt
```
## Binary Installation
### Auto Installer (Recommended)
If you used the auto installer, simply run it again.
```bash theme={null}
curl -fsSL https://static.pangolin.net/get-newt.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 theme={null}
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>