diff --git a/README.md b/README.md index 413d353..5edac89 100644 --- a/README.md +++ b/README.md @@ -33,61 +33,108 @@ When Newt receives WireGuard control messages, it will use the information encod ## CLI Args +### Core Configuration + - `id`: Newt ID generated by Pangolin to identify the client. - `secret`: A unique secret (not shared and kept private) used to authenticate the client ID with the websocket in order to receive commands. - `endpoint`: The endpoint where both Gerbil and Pangolin reside in order to connect to the websocket. - -- `mtu` (optional): MTU for the internal WG interface. Default: 1280 -- `dns` (optional): DNS server to use to resolve the endpoint. Default: 9.9.9.9 +- `blueprint-file` (optional): Path to blueprint file to define Pangolin resources and configurations. +- `no-cloud` (optional): Don't fail over to the cloud when using managed nodes in Pangolin Cloud. Default: false - `log-level` (optional): The log level to use (DEBUG, INFO, WARN, ERROR, FATAL). Default: INFO -- `enforce-hc-cert` (optional): Enforce certificate validation for health checks. Default: false (accepts any cert) + +### Docker Integration + - `docker-socket` (optional): Set the Docker socket to use the container discovery integration -- `ping-interval` (optional): Interval for pinging the server. Default: 3s -- `ping-timeout` (optional): Timeout for each ping. Default: 5s -- `updown` (optional): A script to be called when targets are added or removed. -- `tls-client-cert` (optional): Client certificate (p12 or pfx) for mTLS. See [mTLS](#mtls) -- `tls-client-cert` (optional): Path to client certificate (PEM format, optional if using PKCS12). See [mTLS](#mtls) -- `tls-client-key` (optional): Path to private key for mTLS (PEM format, optional if using PKCS12) -- `tls-ca-cert` (optional): Path to CA certificate to verify server (PEM format, optional if using PKCS12) - `docker-enforce-network-validation` (optional): Validate the container target is on the same network as the newt process. Default: false -- `health-file` (optional): Check if connection to WG server (pangolin) is ok. creates a file if ok, removes it if not ok. Can be used with docker healtcheck to restart newt + +### Accpet Client Connection + - `accept-clients` (optional): Enable WireGuard server mode to accept incoming newt client connections. Default: false - `generateAndSaveKeyTo` (optional): Path to save generated private key - `native` (optional): Use native WireGuard interface when accepting clients (requires WireGuard kernel module and Linux, must run as root). Default: false (uses userspace netstack) - `interface` (optional): Name of the WireGuard interface. Default: newt - `keep-interface` (optional): Keep the WireGuard interface. Default: false -- `blueprint-file` (optional): Path to blueprint file to define Pangolin resources and configurations. -- `no-cloud` (optional): Don't fail over to the cloud when using managed nodes in Pangolin Cloud. Default: false + +### Metrics & Observability + +- `metrics` (optional): Enable Prometheus /metrics exporter. Default: true +- `otlp` (optional): Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT. Default: false +- `metrics-admin-addr` (optional): Admin/metrics bind address. Default: 127.0.0.1:2112 +- `metrics-async-bytes` (optional): Enable async bytes counting (background flush; lower hot path overhead). Default: false +- `region` (optional): Optional region resource attribute for telemetry and metrics. + +### Network Configuration + +- `mtu` (optional): MTU for the internal WG interface. Default: 1280 +- `dns` (optional): DNS server to use to resolve the endpoint. Default: 9.9.9.9 +- `ping-interval` (optional): Interval for pinging the server. Default: 3s +- `ping-timeout` (optional): Timeout for each ping. Default: 5s + +### Security & TLS + +- `enforce-hc-cert` (optional): Enforce certificate validation for health checks. Default: false (accepts any cert) +- `tls-client-cert` (optional): Client certificate (p12 or pfx) for mTLS or path to client certificate (PEM format). See [mTLS](#mtls) +- `tls-client-key` (optional): Path to private key for mTLS (PEM format, optional if using PKCS12) +- `tls-ca-cert` (optional): Path to CA certificate to verify server (PEM format, optional if using PKCS12) + +### Monitoring & Health + +- `health-file` (optional): Check if connection to WG server (pangolin) is ok. creates a file if ok, removes it if not ok. Can be used with docker healtcheck to restart newt +- `updown` (optional): A script to be called when targets are added or removed. ## 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. +### Core Configuration + - `PANGOLIN_ENDPOINT`: Endpoint of your pangolin server (equivalent to `--endpoint`) - `NEWT_ID`: Newt ID generated by Pangolin (equivalent to `--id`) - `NEWT_SECRET`: Newt secret for authentication (equivalent to `--secret`) -- `MTU`: MTU for the internal WG interface. Default: 1280 (equivalent to `--mtu`) -- `DNS`: DNS server to use to resolve the endpoint. Default: 9.9.9.9 (equivalent to `--dns`) +- `CONFIG_FILE`: Load the config json from this file instead of in the home folder. +- `BLUEPRINT_FILE`: Path to blueprint file to define Pangolin resources and configurations. (equivalent to `--blueprint-file`) +- `NO_CLOUD`: Don't fail over to the cloud when using managed nodes in Pangolin Cloud. Default: false (equivalent to `--no-cloud`) - `LOG_LEVEL`: Log level (DEBUG, INFO, WARN, ERROR, FATAL). Default: INFO (equivalent to `--log-level`) + +### Docker Integration + - `DOCKER_SOCKET`: Path to Docker socket for container discovery (equivalent to `--docker-socket`) -- `PING_INTERVAL`: Interval for pinging the server. Default: 3s (equivalent to `--ping-interval`) -- `PING_TIMEOUT`: Timeout for each ping. Default: 5s (equivalent to `--ping-timeout`) -- `UPDOWN_SCRIPT`: Path to updown script for target add/remove events (equivalent to `--updown`) -- `TLS_CLIENT_CERT`: Path to client certificate for mTLS (equivalent to `--tls-client-cert`) -- `TLS_CLIENT_CERT`: Path to client certificate for mTLS (equivalent to `--tls-client-cert`) -- `TLS_CLIENT_KEY`: Path to private key for mTLS (equivalent to `--tls-client-key`) -- `TLS_CA_CERT`: Path to CA certificate to verify server (equivalent to `--tls-ca-cert`) - `DOCKER_ENFORCE_NETWORK_VALIDATION`: Validate container targets are on same network. Default: false (equivalent to `--docker-enforce-network-validation`) -- `ENFORCE_HC_CERT`: Enforce certificate validation for health checks. Default: false (equivalent to `--enforce-hc-cert`) -- `HEALTH_FILE`: Path to health file for connection monitoring (equivalent to `--health-file`) + +### Accept Client Connections + - `ACCEPT_CLIENTS`: Enable WireGuard server mode. Default: false (equivalent to `--accept-clients`) - `GENERATE_AND_SAVE_KEY_TO`: Path to save generated private key (equivalent to `--generateAndSaveKeyTo`) - `USE_NATIVE_INTERFACE`: Use native WireGuard interface (Linux only). Default: false (equivalent to `--native`) - `INTERFACE`: Name of the WireGuard interface. Default: newt (equivalent to `--interface`) - `KEEP_INTERFACE`: Keep the WireGuard interface after shutdown. Default: false (equivalent to `--keep-interface`) -- `CONFIG_FILE`: Load the config json from this file instead of in the home folder. -- `BLUEPRINT_FILE`: Path to blueprint file to define Pangolin resources and configurations. (equivalent to `--blueprint-file`) -- `NO_CLOUD`: Don't fail over to the cloud when using managed nodes in Pangolin Cloud. Default: false (equivalent to `--no-cloud`) + +### Monitoring & Health + +- `HEALTH_FILE`: Path to health file for connection monitoring (equivalent to `--health-file`) +- `UPDOWN_SCRIPT`: Path to updown script for target add/remove events (equivalent to `--updown`) + +### Metrics & Observability + +- `NEWT_METRICS_PROMETHEUS_ENABLED`: Enable Prometheus /metrics exporter. Default: true (equivalent to `--metrics`) +- `NEWT_METRICS_OTLP_ENABLED`: Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT. Default: false (equivalent to `--otlp`) +- `NEWT_ADMIN_ADDR`: Admin/metrics bind address. Default: 127.0.0.1:2112 (equivalent to `--metrics-admin-addr`) +- `NEWT_METRICS_ASYNC_BYTES`: Enable async bytes counting (background flush; lower hot path overhead). Default: false (equivalent to `--metrics-async-bytes`) +- `NEWT_REGION`: Optional region resource attribute for telemetry and metrics (equivalent to `--region`) + +### Network Configuration + +- `MTU`: MTU for the internal WG interface. Default: 1280 (equivalent to `--mtu`) +- `DNS`: DNS server to use to resolve the endpoint. Default: 9.9.9.9 (equivalent to `--dns`) +- `PING_INTERVAL`: Interval for pinging the server. Default: 3s (equivalent to `--ping-interval`) +- `PING_TIMEOUT`: Timeout for each ping. Default: 5s (equivalent to `--ping-timeout`) + +### Security & TLS + +- `ENFORCE_HC_CERT`: Enforce certificate validation for health checks. Default: false (equivalent to `--enforce-hc-cert`) +- `TLS_CLIENT_CERT`: Path to client certificate for mTLS (equivalent to `--tls-client-cert`) +- `TLS_CLIENT_KEY`: Path to private key for mTLS (equivalent to `--tls-client-key`) +- `TLS_CA_CERT`: Path to CA certificate to verify server (equivalent to `--tls-ca-cert`) ## Loading secrets from files