mirror of
https://github.com/jsiebens/ionscale.git
synced 2026-03-31 15:07:49 +01:00
add configuration page
This commit is contained in:
Johan Siebens
@@ -0,0 +1,393 @@
|
||||
# Configuration Guide
|
||||
|
||||
ionscale uses a flexible YAML-based configuration system that supports environment variable substitution and sensible defaults. This guide explains how to configure your ionscale instance.
|
||||
|
||||
## Configuration File Format
|
||||
|
||||
ionscale uses YAML for its configuration files. Here's a basic example:
|
||||
|
||||
```yaml
|
||||
# Server network configuration
|
||||
listen_addr: ":8080"
|
||||
public_addr: "ionscale.example.com:443"
|
||||
stun_listen_addr: ":3478"
|
||||
stun_public_addr: "ionscale.example.com:3478"
|
||||
|
||||
# TLS configuration
|
||||
tls:
|
||||
disable: false
|
||||
force_https: true
|
||||
cert_file: /etc/ionscale/cert.pem
|
||||
key_file: /etc/ionscale/key.pem
|
||||
|
||||
# Database configuration
|
||||
database:
|
||||
type: postgres
|
||||
url: postgres://user:password@localhost:5432/ionscale
|
||||
```
|
||||
|
||||
## Loading Configuration
|
||||
|
||||
When starting ionscale, you can specify a configuration file using the `--config` or `-c` flag:
|
||||
|
||||
```bash
|
||||
ionscale server --config /etc/ionscale/config.yaml
|
||||
```
|
||||
|
||||
If no configuration file is provided, ionscale will use its default values.
|
||||
|
||||
## Environment Variable Support
|
||||
|
||||
ionscale supports two ways to use environment variables in configuration:
|
||||
|
||||
### 1. Direct Configuration via Environment Variables
|
||||
|
||||
You can provide the entire configuration as a base64-encoded string using the `IONSCALE_CONFIG_BASE64` environment variable. This is useful for containerized deployments where you want to inject configuration without mounting files.
|
||||
|
||||
```bash
|
||||
# Create base64-encoded config
|
||||
CONFIG_B64=$(cat config.yaml | base64 -w0)
|
||||
|
||||
# Run ionscale with environment config
|
||||
IONSCALE_CONFIG_BASE64=$CONFIG_B64 ionscale server
|
||||
```
|
||||
|
||||
### 2. Variable Substitution in YAML Files
|
||||
|
||||
You can reference environment variables directly in your YAML configuration files using:
|
||||
|
||||
- `${VAR}` syntax for required variables
|
||||
- `${VAR:default}` syntax for variables with default values
|
||||
|
||||
For example:
|
||||
|
||||
```yaml
|
||||
database:
|
||||
type: ${DB_TYPE:sqlite}
|
||||
url: ${DB_URL}
|
||||
max_open_conns: ${DB_MAX_OPEN_CONNS:10}
|
||||
```
|
||||
|
||||
In this example:
|
||||
- `DB_TYPE` has a default value of "sqlite" if the environment variable is not set
|
||||
- `DB_URL` is required and must be set in the environment
|
||||
- `DB_MAX_OPEN_CONNS` defaults to 10 if not set
|
||||
|
||||
If a required variable is missing, the configuration loading will fail with an error.
|
||||
|
||||
## Default Configuration
|
||||
|
||||
If no configuration file is provided, ionscale uses these default values:
|
||||
|
||||
```yaml
|
||||
listen_addr: ":8080"
|
||||
metrics_listen_addr: ":9091"
|
||||
stun_listen_addr: ":3478"
|
||||
|
||||
database:
|
||||
type: sqlite
|
||||
url: ./ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)&_pragma=foreign_keys(ON)
|
||||
max_idle_conns: 2
|
||||
|
||||
poll_net:
|
||||
keep_alive_interval: 1m
|
||||
|
||||
dns:
|
||||
magic_dns_suffix: ionscale.net
|
||||
|
||||
derp:
|
||||
server:
|
||||
disabled: false
|
||||
region_id: 1000
|
||||
region_code: ionscale
|
||||
region_name: ionscale Embedded DERP
|
||||
|
||||
logging:
|
||||
level: info
|
||||
```
|
||||
|
||||
## Configuration Sections
|
||||
|
||||
### Server Network Configuration
|
||||
|
||||
Controls the network interfaces and addresses:
|
||||
|
||||
```yaml
|
||||
# The HTTP(S) listen address for the control plane
|
||||
listen_addr: ":8080"
|
||||
|
||||
# The metrics listen address (for Prometheus)
|
||||
metrics_listen_addr: ":9091"
|
||||
|
||||
# The STUN listen address when using the embedded DERP
|
||||
stun_listen_addr: ":3478"
|
||||
|
||||
# The DNS name of the server HTTP(S) endpoint as accessible by clients
|
||||
public_addr: "ionscale.example.com:443"
|
||||
|
||||
# The DNS name of the STUN endpoint as accessible by clients
|
||||
stun_public_addr: "ionscale.example.com:3478"
|
||||
```
|
||||
|
||||
### TLS Configuration
|
||||
|
||||
Controls HTTPS and certificate usage:
|
||||
|
||||
```yaml
|
||||
tls:
|
||||
# Disable TLS (not recommended for production)
|
||||
disable: false
|
||||
|
||||
# Force HTTPS redirect
|
||||
force_https: true
|
||||
|
||||
# Path to certificate files (when not using ACME)
|
||||
cert_file: /etc/ionscale/cert.pem
|
||||
key_file: /etc/ionscale/key.pem
|
||||
|
||||
# Let's Encrypt ACME configuration
|
||||
acme: true
|
||||
acme_email: admin@example.com
|
||||
acme_ca: https://acme-v02.api.letsencrypt.org/directory
|
||||
```
|
||||
|
||||
### Database Configuration
|
||||
|
||||
Controls the database storage:
|
||||
|
||||
```yaml
|
||||
database:
|
||||
# Database type: sqlite or postgres
|
||||
type: postgres
|
||||
|
||||
# Database connection URL
|
||||
url: postgres://user:password@localhost:5432/ionscale
|
||||
|
||||
# Connection pool settings
|
||||
max_open_conns: 10
|
||||
max_idle_conns: 5
|
||||
conn_max_life_time: 5m
|
||||
conn_max_idle_time: 5m
|
||||
```
|
||||
|
||||
### OIDC Configuration
|
||||
|
||||
Controls OpenID Connect authentication providers and admin access:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
# OIDC provider configuration
|
||||
provider:
|
||||
issuer: https://auth.example.com
|
||||
client_id: client_id
|
||||
client_secret: client_secret
|
||||
additional_scopes: ["profile", "email"]
|
||||
|
||||
# System administrators configuration
|
||||
system_admins:
|
||||
emails: ["admin@example.com"]
|
||||
subs: ["subject123"]
|
||||
filters: ["domain == example.com"]
|
||||
```
|
||||
|
||||
For more details about configuring OIDC authentication, see [OIDC Configuration](./auth-oidc.md).
|
||||
|
||||
### DNS Configuration
|
||||
|
||||
Controls DNS settings:
|
||||
|
||||
```yaml
|
||||
dns:
|
||||
# Suffix for MagicDNS
|
||||
magic_dns_suffix: ionscale.net
|
||||
|
||||
# DNS provider for dynamic updates
|
||||
provider:
|
||||
name: cloudflare
|
||||
zone: example.com
|
||||
config:
|
||||
auth_token: ${CLOUDFLARE_TOKEN}
|
||||
```
|
||||
|
||||
For more details about configuring DNS providers, see [DNS Providers](./dns-providers.md).
|
||||
|
||||
### DERP Configuration
|
||||
|
||||
Controls relay server configuration:
|
||||
|
||||
```yaml
|
||||
derp:
|
||||
# Embedded DERP server configuration
|
||||
server:
|
||||
disabled: false
|
||||
region_id: 1000
|
||||
region_code: ionscale
|
||||
region_name: ionscale Embedded DERP
|
||||
|
||||
# External DERP maps to load
|
||||
sources:
|
||||
- https://controlplane.tailscale.com/derpmap/default
|
||||
- file:///etc/ionscale/custom-derp.json
|
||||
```
|
||||
|
||||
For more details about configuring DERP servers, see [DERP Configuration](./derp.md).
|
||||
|
||||
### Logging Configuration
|
||||
|
||||
Controls log output:
|
||||
|
||||
```yaml
|
||||
logging:
|
||||
# Log level: debug, info, warn, error
|
||||
level: info
|
||||
|
||||
# Log format: text, json
|
||||
format: text
|
||||
|
||||
# Optional file output (in addition to stdout)
|
||||
file: /var/log/ionscale.log
|
||||
```
|
||||
|
||||
### Keys and Security
|
||||
|
||||
You can configure private keys for the system:
|
||||
|
||||
```yaml
|
||||
keys:
|
||||
# System administrator key for CLI authentication
|
||||
system_admin_key: your-private-key
|
||||
|
||||
# Control plane keys (optional, auto-generated when not provided)
|
||||
control_key: your-control-key
|
||||
legacy_control_key: your-legacy-control-key
|
||||
```
|
||||
|
||||
The `control_key` and `legacy_control_key` are optional and will be automatically generated if not provided. Once generated, they are stored in the database and reused across restarts.
|
||||
|
||||
!!! warning
|
||||
Never commit sensitive keys in your configuration files to version control. Use environment variables for sensitive values.
|
||||
|
||||
## Configuration File Locations
|
||||
|
||||
Common locations for ionscale configuration files:
|
||||
|
||||
- `/etc/ionscale/config.yaml` - System-wide configuration
|
||||
- `$HOME/.config/ionscale/config.yaml` - User-specific configuration
|
||||
- `./config.yaml` - Local directory configuration
|
||||
|
||||
## Complete Configuration Example
|
||||
|
||||
Below is a complete configuration file example with comments:
|
||||
|
||||
```yaml
|
||||
# Network configuration
|
||||
listen_addr: ":8080" # HTTP/HTTPS control plane address
|
||||
stun_listen_addr: ":3478" # STUN server listen address
|
||||
metrics_listen_addr: ":9091" # Prometheus metrics address
|
||||
public_addr: "ionscale.example.com:443" # Public HTTPS endpoint for clients
|
||||
stun_public_addr: "ionscale.example.com:3478" # Public STUN endpoint for clients
|
||||
|
||||
# TLS configuration
|
||||
tls:
|
||||
disable: false # Set to true if behind a TLS-terminating proxy
|
||||
force_https: true # Redirect HTTP to HTTPS
|
||||
# Provide your own certificates
|
||||
cert_file: "/etc/ionscale/cert.pem"
|
||||
key_file: "/etc/ionscale/key.pem"
|
||||
# Or use Let's Encrypt
|
||||
acme: false # Enable ACME/Let's Encrypt
|
||||
acme_email: "admin@example.com" # Contact email for Let's Encrypt
|
||||
acme_ca: "https://acme-v02.api.letsencrypt.org/directory"
|
||||
acme_path: "./data" # Storage path for ACME certificates
|
||||
|
||||
# Database configuration
|
||||
database:
|
||||
# SQLite configuration
|
||||
type: "sqlite"
|
||||
url: "/var/lib/ionscale/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)&_pragma=foreign_keys(ON)"
|
||||
|
||||
# Or PostgreSQL configuration
|
||||
# type: "postgres"
|
||||
# url: "postgres://user:password@localhost:5432/ionscale?sslmode=disable"
|
||||
|
||||
# Connection pool settings
|
||||
max_open_conns: 10
|
||||
max_idle_conns: 5
|
||||
conn_max_life_time: "5m"
|
||||
conn_max_idle_time: "5m"
|
||||
|
||||
# DERP (relay) configuration
|
||||
derp:
|
||||
# Embedded DERP server
|
||||
server:
|
||||
disabled: false # Set to true to disable embedded DERP
|
||||
region_id: 1000 # Region ID (1000+ reserved for ionscale)
|
||||
region_code: "ionscale" # Short code for the region
|
||||
region_name: "ionscale Embedded DERP" # Human-readable name
|
||||
|
||||
# External DERP sources (optional)
|
||||
sources:
|
||||
- https://controlplane.tailscale.com/derpmap/default # Tailscale's DERP map
|
||||
# - file:///etc/ionscale/custom-derp.json # Custom DERP map
|
||||
# - git::https://github.com/example/derp//map.json # DERP map from git
|
||||
|
||||
# Security keys
|
||||
keys:
|
||||
# System admin key for CLI authentication (required for admin CLI usage)
|
||||
system_admin_key: "${IONSCALE_SYSTEM_ADMIN_KEY}" # Use environment variable
|
||||
|
||||
# Control keys (optional, auto-generated if not provided)
|
||||
# control_key: "privkey:xxxxxx"
|
||||
# legacy_control_key: "privkey:xxxxxx"
|
||||
|
||||
# Network polling configuration
|
||||
poll_net:
|
||||
# How often to send keep-alive messages
|
||||
keep_alive_interval: "60s"
|
||||
|
||||
# OIDC authentication configuration
|
||||
auth:
|
||||
# OIDC provider settings
|
||||
provider:
|
||||
issuer: "https://auth.example.com" # OIDC issuer URL
|
||||
client_id: "your-client-id" # OAuth client ID
|
||||
client_secret: "${OIDC_CLIENT_SECRET}" # OAuth client secret from env var
|
||||
additional_scopes: ["profile", "email"] # Extra scopes to request
|
||||
|
||||
# System administrator policy
|
||||
system_admins:
|
||||
# Users identified by email
|
||||
emails: ["admin@example.com"]
|
||||
# Users identified by subject ID
|
||||
subs: ["subject-id-12345"]
|
||||
# Users matching expression filters
|
||||
filters: ["domain == example.com"]
|
||||
|
||||
# DNS configuration
|
||||
dns:
|
||||
# Suffix for MagicDNS hostnames
|
||||
magic_dns_suffix: "ionscale.net"
|
||||
|
||||
# DNS provider for automatic DNS management (optional)
|
||||
provider:
|
||||
name: "cloudflare" # Provider name (cloudflare, route53, etc.)
|
||||
zone: "example.com" # DNS zone to manage
|
||||
config: # Provider-specific configuration
|
||||
auth_token: "${DNS_API_TOKEN}"
|
||||
|
||||
# Logging configuration
|
||||
logging:
|
||||
level: "info" # debug, info, warn, error
|
||||
format: "text" # text or json
|
||||
file: "/var/log/ionscale.log" # Optional log file path
|
||||
```
|
||||
|
||||
!!! note "Environment variables"
|
||||
In this example, we use environment variables for sensitive values:
|
||||
```
|
||||
${IONSCALE_SYSTEM_ADMIN_KEY} - System admin key for CLI authentication
|
||||
${OIDC_CLIENT_SECRET} - OIDC client secret
|
||||
${DNS_API_TOKEN} - DNS provider API token
|
||||
```
|
||||
|
||||
These must be set in your environment before starting ionscale.
|
||||
+4
-4
@@ -13,14 +13,14 @@ nav:
|
||||
- Installation: ./installation/index.md
|
||||
- Linux installation: ./installation/linux.md
|
||||
- Docker installation: ./installation/docker.md
|
||||
- Getting started:
|
||||
- Getting started: ./getting-started/index.md
|
||||
- Creating a tailnet: ./getting-started/tailnet.md
|
||||
- Configuration:
|
||||
- Configuration: ./configuration/index.md
|
||||
- DERP: ./configuration/derp.md
|
||||
- OIDC: ./configuration/auth-oidc.md
|
||||
- DNS providers: ./configuration/dns-providers.md
|
||||
- Reference: ./configuration/reference.md
|
||||
- Getting started:
|
||||
- Getting started: ./getting-started/index.md
|
||||
- Creating a tailnet: ./getting-started/tailnet.md
|
||||
|
||||
theme:
|
||||
name: material
|
||||
|
||||
Reference in New Issue
Block a user