diff --git a/manage/clients/add-client.mdx b/manage/clients/add-client.mdx index 3ff8ac4..91aa40e 100644 --- a/manage/clients/add-client.mdx +++ b/manage/clients/add-client.mdx @@ -63,7 +63,7 @@ Clients can relay traffic through a Pangolin server - through Gerbil specificall While functional, it does not always connect reliably and can fall back to relaying. We plan to work to improve the reliability over time by implementing more methods for those behind CGNAT or hard nats. -Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make to improve hole punch reliability and performance. +Take a look at Tailscale's recommendations [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make to improve hole punch reliability and performance. This should help to: - Increase performance (speed/bandwidth) diff --git a/manage/clients/configure-client.mdx b/manage/clients/configure-client.mdx index 6b1ee72..c908687 100644 --- a/manage/clients/configure-client.mdx +++ b/manage/clients/configure-client.mdx @@ -41,18 +41,32 @@ Refer to the [documentation in the official repository](https://github.com/fosrl **Example**: `https://pangolin.example.com` + + Organization ID to connect to. + + + + User authentication token. + + - MTU for the WireGuard interface. + MTU for the internal WireGuard interface. **Default**: `1280` - DNS server to use for resolving the endpoint. + DNS server to use to resolve the endpoint. **Default**: `8.8.8.8` + + Upstream DNS server(s), comma-separated. + + **Default**: `8.8.8.8:53` + + The log level to use for Olm output. @@ -73,16 +87,46 @@ Refer to the [documentation in the official repository](https://github.com/fosrl **Default**: `5s` - - Enable NAT hole punching mode instead of relaying through the VPS. + + Name of the WireGuard interface. + + **Default**: `olm` + + + + Enable API server for receiving connection requests. **Default**: `false` - - Path to a configuration file containing the same arguments as command line. + + HTTP server address (e.g., ':9452'). - **Example**: `/etc/olm/config.yaml` + **Default**: `:9452` + + + + Unix socket path (or named pipe on Windows). + + **Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows) + + + + Disable hole punching. + + **Default**: `false` + + + + Override system DNS settings. + + **Default**: `false` + + + + Disable relay connections. + + **Default**: `false` ### Environment Variables @@ -105,46 +149,141 @@ When both environment variables and CLI arguments are provided, CLI arguments ta Olm secret for authentication (equivalent to `--secret`) - - MTU for the WireGuard interface (equivalent to `--mtu`) + + Organization ID to connect to (equivalent to `--org`) + + + + User authentication token (equivalent to `--user-token`) + + + + MTU for the internal WireGuard interface (equivalent to `--mtu`) **Default**: `1280` - - DNS server to use for resolving the endpoint (equivalent to `--dns`) + + DNS server to use to resolve the endpoint (equivalent to `--dns`) **Default**: `8.8.8.8` - + + Upstream DNS server(s), comma-separated (equivalent to `--upstream-dns`) + + **Default**: `8.8.8.8:53` + + + Log level (equivalent to `--log-level`) **Default**: `INFO` - + Interval for pinging the server (equivalent to `--ping-interval`) **Default**: `3s` - + Timeout for each ping (equivalent to `--ping-timeout`) **Default**: `5s` - - Enable NAT hole punching mode (equivalent to `--holepunch`) + + Name of the WireGuard interface (equivalent to `--interface`) + + **Default**: `olm` + + + + Enable API server for receiving connection requests (equivalent to `--enable-api`) + + Set to "true" to enable **Default**: `false` - - Path to health file for connection monitoring (equivalent to `--health-file`) + + HTTP server address (equivalent to `--http-addr`) + + **Default**: `:9452` - - Load the config from this file instead of command line arguments (equivalent to `--config-file`) + + Unix socket path or Windows named pipe (equivalent to `--socket-path`) + + **Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows) + + + Disable hole punching (equivalent to `--disable-holepunch`) + + Set to "true" to disable + + **Default**: `false` + + + + Override system DNS settings (equivalent to `--override-dns`) + + Set to "true" to enable + + **Default**: `false` + + + + Disable relay connections (equivalent to `--disable-relay`) + + Set to "true" to disable + + **Default**: `false` + + + + Set to the location of a JSON file to load secret values + + +### 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/olm-client/config.json +{ + "id": "spmzu8rbpzj1qq6", + "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3", + "endpoint": "https://app.pangolin.net", + "org": "", + "userToken": "", + "mtu": 1280, + "dns": "8.8.8.8", + "upstreamDNS": ["8.8.8.8:53"], + "interface": "olm", + "logLevel": "INFO", + "enableApi": false, + "httpAddr": "", + "socketPath": "/var/run/olm.sock", + "pingInterval": "3s", + "pingTimeout": "5s", + "disableHolepunch": false, + "overrideDNS": false, + "disableRelay": false, + "tlsClientCert": "" +} +``` + +This file is also written to when olm 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/olm-client/config.json` +- **Windows**: `%PROGRAMDATA%\olm\olm-client\config.json` +- **Linux/Others**: `~/.config/olm-client/config.json` + +### API + +Olm can be started with a HTTP or socket API to configure and manage it. See the [API documentation](https://github.com/fosrl/olm/blob/main/API.md) for more details. \ No newline at end of file diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 2228f4d..5d50b30 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -49,7 +49,7 @@ If you're looking for a CLI interface for a client, we recommend using Pangolin Olm CLI is mainly only used for machine clients. Though the Pangolin CLI can also be used for machine clients, use Pangolin CLI if you expect to log in as a user. -### Binary Installation +### Binary Installation (Linux) #### Quick Install (Recommended) @@ -118,6 +118,47 @@ WantedBy=multi-user.target Make sure to move the binary to `/usr/local/bin/olm` before creating the service! +### Docker + +You can also run it with Docker compose. For example, a service in your `docker-compose.yml` might look like this using environment vars (recommended): + +```yaml +services: + olm: + image: fosrl/olm + container_name: olm + restart: unless-stopped + network_mode: host + devices: + - /dev/net/tun:/dev/net/tun + environment: + - PANGOLIN_ENDPOINT=https://example.com + - OLM_ID=31frd0uzbjvp721 + - OLM_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 +``` + +You can also pass the CLI args to the container: + +```yaml +services: + olm: + image: fosrl/olm + container_name: olm + restart: unless-stopped + network_mode: host + devices: + - /dev/net/tun:/dev/net/tun + command: + - --id 31frd0uzbjvp721 + - --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 + - --endpoint https://example.com +``` + +**Docker Configuration Notes:** + +- `network_mode: host` brings the olm network interface to the host system, allowing the WireGuard tunnel to function properly +- `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces + ### Windows Service On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to install and run the service to function like a cli tool. You can also run the following: @@ -175,6 +216,16 @@ Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10 Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes: - **Windows**: Olm will run as a service. You can use the commands described [Configure Client](/manage/clients/configure-client) to manage it. You can use this to run it in the background if needed! -- **LXC containers**: Need to be configured to allow tun access. See [Tailscale's guide](https://tailscale.com/kb/1130/lxc-unprivileged). +- **LXC containers**: Need to be configured to allow tun access. See below. - **Linux**: May require root privileges or specific capabilities to create tun interfaces. - **macOS**: May require additional permissions for network interface creation. + +#### LXC Container Configuration + +1. Create your LXC container. +2. Go to the Resources tab of the container. +3. Select Add. Then select Device Passthrough. +4. On the Add Device prompt, enter dev/net/tun in the Device Path field and select Add. +5. If the container is running, shut it down and start it up again. + +Once /dev/net/tun is available, the olm can run within the LXC. \ No newline at end of file diff --git a/manage/sites/configure-site.mdx b/manage/sites/configure-site.mdx index 17819d0..4c47a9a 100644 --- a/manage/sites/configure-site.mdx +++ b/manage/sites/configure-site.mdx @@ -36,7 +36,7 @@ description: "Configure Newt for connecting to Pangolin sites" DNS server to use for resolving the endpoint. - **Default**: `8.8.8.8` + **Default**: `9.9.9.9` @@ -83,42 +83,102 @@ description: "Configure Newt for connecting to Pangolin sites" **Example**: `/path/to/updown.sh` - - Client certificate (p12 or pfx) for mutual TLS (mTLS) authentication. + + Path to blueprint file to define Pangolin resources and configurations. - **Example**: `/path/to/client.p12` + **Example**: `/path/to/blueprint.yaml` - - Prevent Pangolin Clients from connecting to resources on this site. + + Don't fail over to the cloud when using managed nodes in Pangolin Cloud. **Default**: `false` - - Path to save generated private key (used with accept-clients). + + Disable clients on the WireGuard interface. - **Example**: `/var/key` + **Default**: `false` (clients enabled) - Use native WireGuard interface when accepting clients (requires WireGuard kernel module and Linux, must run as root). + Use native WireGuard interface (requires WireGuard kernel module and Linux, must run as root). **Default**: `false` (uses userspace netstack) - Name of the WireGuard interface (used with native mode). + Name of the WireGuard interface. **Default**: `newt` - - Keep the WireGuard interface after shutdown (used with native mode). + + Enable Prometheus /metrics exporter. + + **Default**: `true` + + + + Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT. **Default**: `false` + + Admin/metrics bind address. + + **Default**: `127.0.0.1:2112` + + + + Enable async bytes counting (background flush; lower hot path overhead). + + **Default**: `false` + + + + Optional region resource attribute for telemetry and metrics. + + **Example**: `us-west-2` + + + + Enforce certificate validation for health checks. + + **Default**: `false` (accepts any cert) + + + + Path to client certificate file (PEM/DER format) for mTLS. + + **Example**: `/path/to/client.crt` + + + + Path to client private key file (PEM/DER format) for mTLS. + + **Example**: `/path/to/client.key` + + + + Path to CA certificate file for validating remote certificates (can be specified multiple times). + + **Example**: `/path/to/ca.crt` + + + + Path to client certificate (PKCS12 format) - DEPRECATED: use `--tls-client-cert-file` and `--tls-client-key` instead. + + **Example**: `/path/to/client.p12` + + + + Prefer this endpoint for the connection (if set, will override the endpoint from the server). + + **Example**: `https://preferred.endpoint.com` + + ## 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. @@ -148,7 +208,21 @@ When both environment variables and CLI arguments are provided, CLI arguments ta DNS server to use for resolving the endpoint (equivalent to `--dns`) - **Default**: `8.8.8.8` + **Default**: `9.9.9.9` + + + + Load the config JSON from this file instead of in the home folder. + + + + Path to blueprint file to define Pangolin resources and configurations (equivalent to `--blueprint-file`). + + + + Don't fail over to the cloud when using managed nodes in Pangolin Cloud (equivalent to `--no-cloud`). + + **Default**: `false` @@ -177,10 +251,6 @@ When both environment variables and CLI arguments are provided, CLI arguments ta Path to updown script for target add/remove events (equivalent to `--updown`) - - Path to client certificate for mTLS (equivalent to `--tls-client-cert`) - - Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`) @@ -191,16 +261,12 @@ When both environment variables and CLI arguments are provided, CLI arguments ta Path to health file for connection monitoring (equivalent to `--health-file`) - - Enable WireGuard server mode (equivalent to `--accept-clients`) + + Disable clients on the WireGuard interface (equivalent to `--disable-clients`). **Default**: `false` - - Path to save generated private key (equivalent to `--generateAndSaveKeyTo`) - - Use native WireGuard interface (Linux only, equivalent to `--native`) @@ -213,37 +279,119 @@ When both environment variables and CLI arguments are provided, CLI arguments ta **Default**: `newt` - - Keep the WireGuard interface after shutdown (equivalent to `--keep-interface`) + + Enable Prometheus /metrics exporter (equivalent to `--metrics`). + + **Default**: `true` + + + + Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT (equivalent to `--otlp`). **Default**: `false` - - Load the config JSON from this file instead of in the home folder. + + Admin/metrics bind address (equivalent to `--metrics-admin-addr`). + + **Default**: `127.0.0.1:2112` + + Enable async bytes counting (background flush; lower hot path overhead, equivalent to `--metrics-async-bytes`). + + **Default**: `false` + + + + Optional region resource attribute for telemetry and metrics (equivalent to `--region`). + + + + Enforce certificate validation for health checks (equivalent to `--enforce-hc-cert`). + + **Default**: `false` + + + + Path to client certificate file (PEM/DER format) for mTLS (equivalent to `--tls-client-cert-file`) + + + + Path to client private key file (PEM/DER format) for mTLS (equivalent to `--tls-client-key`) + + + + Comma-separated list of CA certificate file paths for validating remote certificates (equivalent to multiple `--tls-client-ca` flags) + + + + Path to client certificate (PKCS12 format) - DEPRECATED: use `TLS_CLIENT_CERT` and `TLS_CLIENT_KEY` instead + + +## 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. On most Linux systems the socket is `/var/run/docker.sock`. When deploying Newt as a container, you need to mount the host socket as a volume for the Newt container to access it. +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. -```yaml title="docker-compose.yml" +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 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://app.pangolin.net - - NEWT_ID=2ix2t8xk22ubpfy - - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 - - DOCKER_SOCKET=/var/run/docker.sock + 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 ``` @@ -296,12 +444,47 @@ You can look at `updown.py` as a reference script to get started! ### mTLS Authentication -Newt supports mutual TLS (mTLS) authentication if the server has been configured to request a client certificate. +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) + + +This is the original method and still supported. + **Requirements:** -- Only PKCS12 (.p12 or .pfx) file format is accepted -- The PKCS12 file must contain: - - Private key +- File must contain: + - Client private key - Public certificate - CA certificate -- Encrypted PKCS12 files are currently not supported +- Encrypted `.p12` files are **not supported** + +**Example:** + +```bash +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 +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 +```