ionscale

https://jsiebens.github.io/ionscale
Admin
ionscale is an open-source self-hosted alternative to Tailscale's control server that provides...
Tokens:24,440
Snippets:373
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Download and Prepare ionscale Installation Script

Source: https://jsiebens.github.io/ionscale/installation/linux

Download the official installation script using curl, then make it executable. This script automates the ionscale setup process.

```bash
# Download the script
curl -fsSL https://raw.githubusercontent.com/jsiebens/ionscale/main/scripts/install.sh -o install.sh
chmod +x install.sh
```

--------------------------------

### Complete Configuration Example

Source: https://jsiebens.github.io/ionscale/configuration?q=

A comprehensive example covering network, TLS, database, DERP, security, polling, and OIDC authentication settings.

```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"]
```

--------------------------------

### Enable Ionscale Service to Start on Boot

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

Use this command to ensure the ionscale service automatically starts when the system boots up. This is typically a one-time setup.

```bash
sudo systemctl enable ionscale
```

--------------------------------

### Run ionscale Installation Script (Interactive)

Source: https://jsiebens.github.io/ionscale/installation/linux

Execute the downloaded installation script in interactive mode. It will prompt you for necessary information like your domain and email.

```bash
./install.sh
```

--------------------------------

### Complete OIDC Configuration with System Admins

Source: https://jsiebens.github.io/ionscale/configuration/auth-oidc?q=

Example showing OIDC provider setup alongside system administrator email and filter definitions.

```yaml
auth:
  provider:
    issuer: "https://accounts.google.com"
    client_id: "your-client-id.apps.googleusercontent.com"
    client_secret: "your-client-secret"
    additional_scopes: "groups"

  system_admins:
    emails:
      - "admin@example.com"
    filters:
      - "domain == \"example.com\" && token.groups contains \"admin\""
```

--------------------------------

### Download and Execute ionscale Installation Script

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

Quickly deploy ionscale using the provided installation script. Download it, make it executable, and run it in interactive mode.

```bash
# Download the script
curl -fsSL https://raw.githubusercontent.com/jsiebens/ionscale/main/scripts/install.sh -o install.sh
chmod +x install.sh

# Run the script (interactive mode)
./install.sh
```

--------------------------------

### Logging Configuration Example

Source: https://jsiebens.github.io/ionscale/configuration?q=

Set up logging parameters such as level, format, and an optional log file path.

```yaml
logging:
  level: "info"                     # debug, info, warn, error
  format: "text"                    # text or json
  file: "/var/log/ionscale.log"     # Optional log file path
```

--------------------------------

### Run ionscale with a Configuration File

Source: https://jsiebens.github.io/ionscale/configuration

Demonstrates how to start the ionscale server using a specified configuration file via the --config flag.

```bash
ionscale server --config /etc/ionscale/config.yaml

```

--------------------------------

### Loading Configuration via CLI

Source: https://jsiebens.github.io/ionscale/configuration?q=

Specify a configuration file path when starting the server.

```bash
ionscale server --config /etc/ionscale/config.yaml
```

--------------------------------

### Install the ionscale CLI

Source: https://jsiebens.github.io/ionscale/getting-started?q=

Download and install the ionscale binary for Linux AMD64 systems.

```bash
# Download the CLI (adjust the URL for your system architecture)
curl -L -o ionscale https://github.com/jsiebens/ionscale/releases/download/v0.17.0/ionscale_linux_amd64

# Make it executable
chmod +x ionscale

# Move to system path
sudo mv ionscale /usr/local/bin/
```

--------------------------------

### Complete Configuration Example

Source: https://jsiebens.github.io/ionscale/configuration

A comprehensive example of an ionscale configuration file, including network, TLS, database, DERP, keys, polling, and OIDC settings. Use environment variables for sensitive values like API secrets.

```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"]

```

--------------------------------

### Verify ionscale Binary Installation

Source: https://jsiebens.github.io/ionscale/installation/linux

After installing the binary, run 'ionscale version' to confirm the installation was successful and check the installed version.

```bash
ionscale version
```

--------------------------------

### Common IAM policy patterns

Source: https://jsiebens.github.io/ionscale/getting-started/iam-policies

Example configurations for domain-based access and personal tailnet setups.

```json
{
  "filters": ["domain == example.com"],
  "roles": {
    "admin1@example.com": "admin",
    "admin2@example.com": "admin"
  }
}
```

```json
{
  "emails": ["personal@example.com"],
  "roles": {
    "personal@example.com": "admin"
  }
}
```

--------------------------------

### Configure Cloudflare External DNS Plugin

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers?q=

Example configuration for using a hypothetical Cloudflare plugin. The plugin must be installed at the specified path.

```yaml
dns:
  magic_dns_suffix: "ts.example.com"
  provider:
    plugin_path: "/usr/local/bin/libdns-cloudflare-plugin"
    zone: "example.com"
    config:
      api_token: "your-cloudflare-api-token"

```

--------------------------------

### Start the Ionscale Service

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

Execute this command to manually start the ionscale service. This is useful for immediate activation or after configuration changes.

```bash
sudo systemctl start ionscale
```

--------------------------------

### Download and Install ionscale Binary

Source: https://jsiebens.github.io/ionscale/installation/linux

Download the latest ionscale binary for your system architecture, place it in /usr/local/bin, and make it executable.

```bash
# Download the latest version (adjust for your CPU architecture)
sudo curl -o "/usr/local/bin/ionscale" \
  -sfL "https://github.com/jsiebens/ionscale/releases/download/v0.17.0/ionscale_linux_amd64"

# Make it executable
sudo chmod +x "/usr/local/bin/ionscale"
```

--------------------------------

### Manage ionscale service with systemctl

Source: https://jsiebens.github.io/ionscale/installation/linux

Use these commands to configure the service to start on boot, initiate the service, and verify its current operational status.

```bash
sudo systemctl enable ionscale

# Start the service
sudo systemctl start ionscale

# Check status
sudo systemctl status ionscale
```

--------------------------------

### Reload systemd and Start ionscale Service

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

After creating the service file, reload the systemd daemon to recognize the new service and then enable and start the ionscale service.

```bash
# Reload systemd to recognize the new service
sudo systemctl daemon-reload
```

--------------------------------

### Run ionscale Container

Source: https://jsiebens.github.io/ionscale/installation/docker

Start the ionscale service with volume mounts for configuration and data, and port mappings for HTTPS and STUN.

```bash
docker run -d \
  --name ionscale \
  --restart unless-stopped \
  -v $(pwd)/config.yaml:/etc/ionscale/config.yaml \
  -v $(pwd)/data:/data \
  -p 443:443 \
  -p 3478:3478/udp \
  ghcr.io/jsiebens/ionscale:0.17.0 server --config /etc/ionscale/config.yaml
```

--------------------------------

### Download and Install ionscale Binary

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

Manually download the latest ionscale binary for your system architecture, place it in the system's PATH, and make it executable.

```bash
# Download the latest version (adjust for your CPU architecture)
sudo curl -o "/usr/local/bin/ionscale" \
  -sfL "https://github.com/jsiebens/ionscale/releases/download/v0.17.0/ionscale_linux_amd64"

# Make it executable
sudo chmod +x "/usr/local/bin/ionscale"

# Verify installation
ionscale version
```

--------------------------------

### Non-interactive ionscale Installation

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

For automated deployments, set the IONSCALE_DOMAIN and IONSCALE_ACME_EMAIL environment variables before running the installation script.

```bash
export IONSCALE_DOMAIN="ionscale.example.com"
export IONSCALE_ACME_EMAIL="your-email@example.com"
./install.sh
```

--------------------------------

### DNS Configuration Example

Source: https://jsiebens.github.io/ionscale/configuration?q=

Configure DNS settings, including the MagicDNS suffix and Cloudflare provider details. Ensure the DNS_API_TOKEN environment variable is set.

```yaml
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}"
```

--------------------------------

### Google OIDC Authentication with System Admins

Source: https://jsiebens.github.io/ionscale/configuration/auth-oidc

Example configuration for Google OpenID Connect authentication, including system administrator email and group filtering. This setup allows specific users or groups to have administrative privileges.

```yaml
auth:
  provider:
    issuer: "https://accounts.google.com"
    client_id: "your-client-id.apps.googleusercontent.com"
    client_secret: "your-client-secret"
    additional_scopes: "groups"

  system_admins:
    emails:
      - "admin@example.com"
    filters:
      - "domain == \"example.com\" && token.groups contains \"admin\""

```

--------------------------------

### Required Environment Variables

Source: https://jsiebens.github.io/ionscale/configuration

Lists the sensitive environment variables that must be configured before starting the Ionscale service.

```text
${IONSCALE_SYSTEM_ADMIN_KEY} - System admin key for CLI authentication
${OIDC_CLIENT_SECRET} - OIDC client secret
${DNS_API_TOKEN} - DNS provider API token
```

--------------------------------

### Basic ionscale Configuration YAML

Source: https://jsiebens.github.io/ionscale/configuration

A fundamental example of an ionscale configuration file in YAML format, illustrating server network, TLS, and database settings.

```yaml
# Server network configuration
listen_addr: ":8080"
public_addr: "ionscale.example.com:443"

```

```yaml
# TLS configuration
tls:
  disable: false
  force_https: true
  cert_file: /etc/ionscale/cert.pem
  key_file: /etc/ionscale/key.pem

```

```yaml
# Database configuration
database:
  type: postgres
  url: postgres://user:password@localhost:5432/ionscale

```

--------------------------------

### Example IAM Policy JSON

Source: https://jsiebens.github.io/ionscale/getting-started/tailnet?q=

An example JSON file structure for defining IAM policies, including filters, specific emails, and role assignments.

```json
{
  "filters": ["domain == example.com"],
  "emails": ["specific-user@otherdomain.com"],
  "roles": {
    "admin@example.com": "admin"
  }
}
```

--------------------------------

### Azure DNS provider configuration

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers

Example configuration for Azure requiring a service principal with DNS Zone Contributor role.

```yaml
dns:
  magic_dns_suffix: "ts.example.com"
  provider:
    name: "azure"
    zone: "example.com"
    config:
      tenant_id: "your-tenant-id"
      client_id: "your-client-id"
      client_secret: "your-client-secret"
      subscription_id: "your-subscription-id"
      resource_group_name: "your-resource-group"
```

--------------------------------

### Example IAM Policy Structure

Source: https://jsiebens.github.io/ionscale/getting-started/iam-policies?q=

This is a general structure of an IAM policy, showing the different components like subs, filters, emails, and roles.

```json
{
  "subs": ["auth0|123456789"],
  "filters": ["domain == example.com"],
  "emails": ["specific-user@otherdomain.com"],
  "roles": {
    "admin@example.com": "admin"
  }
}
```

--------------------------------

### Get Instance DERP Map

Source: https://jsiebens.github.io/ionscale/configuration/derp?q=

Retrieve the current DERP map configuration for the ionscale instance. Use the `--json` flag for machine-readable output.

```bash
ionscale system get-derp-map [--json]
```

--------------------------------

### Create ionscale Service User and Directories

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

Set up a dedicated system user and necessary directories for ionscale to run securely and with appropriate permissions.

```bash
# Create service user
sudo useradd --system --no-create-home --shell /bin/false ionscale

# Create directories
sudo mkdir -p /etc/ionscale
sudo mkdir -p /var/lib/ionscale

# Set appropriate permissions
sudo chown ionscale:ionscale /etc/ionscale
sudo chown ionscale:ionscale /var/lib/ionscale
```

--------------------------------

### Create Directory Structure

Source: https://jsiebens.github.io/ionscale/installation/docker

Initialize the local directory for ionscale data storage.

```bash
mkdir -p ionscale/data
cd ./ionscale
```

--------------------------------

### Load ionscale Configuration via Base64 Environment Variable

Source: https://jsiebens.github.io/ionscale/configuration

Shows how to provide the entire configuration as a base64-encoded string using the IONSCALE_CONFIG_BASE64 environment variable, suitable for containerized environments.

```bash
# Create base64-encoded config
CONFIG_B64=$(cat config.yaml | base64 -w0)

# Run ionscale with environment config
IONSCALE_CONFIG_BASE64=$CONFIG_B64 ionscale server

```

--------------------------------

### Execute basic CLI commands

Source: https://jsiebens.github.io/ionscale/getting-started?q=

Common commands for checking version, managing tailnets, and handling auth keys.

```bash
# View general information
ionscale version                # Show version information
ionscale help                   # Display help information

# Tailnet management
ionscale tailnet list           # List all tailnets
ionscale tailnet create -n NAME # Create a new tailnet

# Auth key management
ionscale auth-key list --tailnet NAME    # List auth keys for a tailnet
ionscale auth-key create --tailnet NAME  # Create a new auth key
```

--------------------------------

### Cloudflare DNS provider configuration

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers

Example configuration for Cloudflare requiring an API token with Zone:DNS Edit permissions.

```yaml
dns:
  magic_dns_suffix: "ts.example.com"
  provider:
    name: "cloudflare"
    zone: "example.com"
    config:
      api_token: "your-cloudflare-api-token"
```

--------------------------------

### Create ionscale Configuration File

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

Generate the main ionscale configuration file using a heredoc, specifying listen addresses, ACME settings, database path, system admin key, and logging level.

```bash
sudo tee /etc/ionscale/config.yaml >/dev/null <<EOF
listen_addr: ":443"
public_addr: "${IONSCALE_DOMAIN}:443"
stun_public_addr: "${IONSCALE_DOMAIN}:3478"

tls:
  acme: true
  acme_email: "${IONSCALE_ACME_EMAIL}"

database:
  url: "/var/lib/ionscale/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"

keys:
  system_admin_key: "${IONSCALE_KEYS_SYSTEM_ADMIN_KEY}"

logging:
  level: info
EOF
```

--------------------------------

### Authenticate with system admin key

Source: https://jsiebens.github.io/ionscale/getting-started?q=

Configure environment variables to authenticate using a system admin key.

```bash
# Configure environment variables
export IONSCALE_ADDR="https://ionscale.example.com"
export IONSCALE_SYSTEM_ADMIN_KEY="your-system-admin-key"

# Verify connection
ionscale version
```

--------------------------------

### Basic ACL Policy Structure

Source: https://jsiebens.github.io/ionscale/getting-started/acl-policies

Defines rules for source-destination access, groups, and tag ownership. Use this as a starting point for your ACL configuration.

```json
{
  "acls": [
    {"action": "accept", "src": ["tag:web"], "dst": ["tag:db:5432"]},
    {"action": "accept", "src": ["group:admins"], "dst": ["*:*"]}
  ],
  "groups": {
    "admins": ["admin@example.com"]
  },
  "tagOwners": {
    "tag:web": ["admin@example.com"],
    "tag:db": ["admin@example.com"]
  }
}

```

--------------------------------

### Generate Configuration File

Source: https://jsiebens.github.io/ionscale/installation/docker

Create the config.yaml file using the previously defined environment variables.

```yaml
cat > ./config.yaml <<EOF
listen_addr: ":443"
public_addr: "${IONSCALE_DOMAIN}:443"
stun_public_addr: "${IONSCALE_DOMAIN}:3478"

tls:
  acme: true
  acme_email: "${IONSCALE_ACME_EMAIL}"

keys:
  system_admin_key: "${IONSCALE_SYSTEM_ADMIN_KEY}"

database:
  url: "/data/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"

logging:
  level: info
EOF
```

--------------------------------

### Authenticate with OIDC

Source: https://jsiebens.github.io/ionscale/getting-started?q=

Configure the server address and initiate the OIDC login flow.

```bash
# Configure URL only
export IONSCALE_ADDR="https://ionscale.example.com"

# Authenticate through OIDC
ionscale auth login
```

--------------------------------

### Manage Tailnets via CLI

Source: https://jsiebens.github.io/ionscale/getting-started/tailnet?q=

Use these commands to list all available tailnets or create new ones for specific teams or environments.

```bash
# List all tailnets
ionscale tailnet list

# Create tailnets for different teams or businesses
ionscale tailnet create --name "tailnet-a"
ionscale tailnet create --name "tailnet-b"
ionscale tailnet create --name "tailnet-c"
```

--------------------------------

### Amazon Route 53 DNS provider configuration

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers

Example configuration for AWS Route 53 requiring an IAM user with record modification permissions.

```yaml
dns:
  magic_dns_suffix: "ts.example.com"
  provider:
    name: "route53"
    zone: "example.com"
    config:
      access_key_id: "your-access-key-id"
      secret_access_key: "your-secret-access-key"
      # Optional region, defaults to us-east-1
      region: "us-east-1"
      ...
```

--------------------------------

### Server Network Configuration Section

Source: https://jsiebens.github.io/ionscale/configuration?q=

Settings for HTTP, metrics, and STUN endpoints.

```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"
```

--------------------------------

### Get Current ACL Policy

Source: https://jsiebens.github.io/ionscale/getting-started/acl-policies

Retrieves the current ACL policy for a specified tailnet using the ionscale CLI. Ensure you have the correct tailnet name.

```bash
# View current ACL policy
ionscale acl get --tailnet "my-tailnet"

```

--------------------------------

### Generate ionscale System Admin Key

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

Create a system admin key for ionscale and store it in the environment file. This key grants full administrative access.

```bash
sudo tee /etc/default/ionscale >/dev/null <<EOF
IONSCALE_KEYS_SYSTEM_ADMIN_KEY=$(ionscale genkey -n)
EOF
```

--------------------------------

### Example DERP Map JSON Structure

Source: https://jsiebens.github.io/ionscale/configuration/derp?q=

A JSON structure defining regions and their associated DERP nodes. This serves as a template for custom DERP map configurations.

```json
{
  "Regions": {
    "1": {
      "RegionID": 1,
      "RegionCode": "nyc",
      "RegionName": "New York City",
      "Nodes": [
        {
          "Name": "1a",
          "RegionID": 1,
          "HostName": "derp1.example.com",
          "DERPPort": 443,
          "STUNPort": 3478
        }
      ]
    },
    "2": {
      "RegionID": 2,
      "RegionCode": "sfo",
      "RegionName": "San Francisco",
      "Nodes": [
        {
          "Name": "2a",
          "RegionID": 2,
          "HostName": "derp2.example.com",
          "DERPPort": 443,
          "STUNPort": 3478
        }
      ]
    }
  }
}
```

--------------------------------

### Database Configuration Section

Source: https://jsiebens.github.io/ionscale/configuration?q=

Settings for database type, connection URL, and connection pooling.

```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
```

--------------------------------

### Get Tailnet DERP Map

Source: https://jsiebens.github.io/ionscale/configuration/derp

View the DERP map currently configured for a specific tailnet. If no custom map is set, this will show the instance's default DERP map. Use the --json flag for machine-readable output.

```bash
# View a tailnet's current DERP map
ionscale tailnets get-derp-map --tailnet <tailnet-id> [--json]
```

--------------------------------

### Create an Auth Key with Specific Tags

Source: https://jsiebens.github.io/ionscale/getting-started/tailnet?q=

Creates a pre-authentication key with associated tags. These tags define the device's network access based on ACL rules once connected.

```bash
# Create an auth key with specific tags
ionscale auth-key create --tailnet "my-first-tailnet" --tags "tag:server"
```

--------------------------------

### Configure DNS A Record

Source: https://jsiebens.github.io/ionscale/installation/docker

Map the ionscale domain to the server's public IP address.

```text
ionscale.example.com  →  YOUR_SERVER_IP
```

--------------------------------

### Basic YAML Configuration

Source: https://jsiebens.github.io/ionscale/configuration?q=

A standard YAML configuration file defining network, TLS, and database settings.

```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
```

--------------------------------

### Keys and Security Configuration

Source: https://jsiebens.github.io/ionscale/configuration

Configure private keys for system administration and control plane authentication. Sensitive keys should be managed via environment variables.

```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

```

--------------------------------

### Set Configuration Environment Variables

Source: https://jsiebens.github.io/ionscale/installation/docker

Define environment variables for the domain, email, and system admin key generation.

```bash
export IONSCALE_ACME_EMAIL="your-email@example.com"  # Used for Let's Encrypt notifications
export IONSCALE_DOMAIN="ionscale.example.com"        # Your ionscale domain
export IONSCALE_SYSTEM_ADMIN_KEY=$(docker run --rm ghcr.io/jsiebens/ionscale:0.17.0 genkey -n)
```

--------------------------------

### TLS Configuration Section

Source: https://jsiebens.github.io/ionscale/configuration?q=

Settings for HTTPS, certificate paths, and ACME/Let's Encrypt integration.

```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
```

--------------------------------

### Base64 Environment Variable Configuration

Source: https://jsiebens.github.io/ionscale/configuration?q=

Inject configuration as a base64-encoded string for containerized deployments.

```bash
# Create base64-encoded config
CONFIG_B64=$(cat config.yaml | base64 -w0)

# Run ionscale with environment config
IONSCALE_CONFIG_BASE64=$CONFIG_B64 ionscale server
```

--------------------------------

### Create ionscale systemd Service File

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

Define the systemd service unit file for ionscale, specifying its description, dependencies, execution user, command, restart policy, and capabilities.

```bash
sudo tee /etc/systemd/system/ionscale.service >/dev/null <<EOF
[Unit]
Description=ionscale - a Tailscale control server
Requires=network-online.target
After=network.target

[Service]
EnvironmentFile=/etc/default/ionscale
User=ionscale
Group=ionscale
ExecStart=/usr/local/bin/ionscale server --config /etc/ionscale/config.yaml
Restart=on-failure
RestartSec=10s
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target
EOF
```

--------------------------------

### Enable HTTPS Certificates

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers

Update the tailnet configuration to enable MagicDNS and HTTPS certificates.

```bash
# Enable MagicDNS and HTTPS certificates for a tailnet
ionscale dns update --tailnet "my-tailnet" --magic-dns --https-certs
```

--------------------------------

### Database Configuration Options

Source: https://jsiebens.github.io/ionscale/configuration

Parameters for configuring the database connection, including type, URL, and connection pool settings.

```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

```

--------------------------------

### Personal Tailnet Configuration

Source: https://jsiebens.github.io/ionscale/getting-started/iam-policies?q=

Set up a personal tailnet by allowing a specific email address and assigning it administrative privileges.

```json
{
  "emails": ["personal@example.com"],
  "roles": {
    "personal@example.com": "admin"
  }
}
```

--------------------------------

### Set ionscale Configuration Environment Variables

Source: https://jsiebens.github.io/ionscale/installation/linux?q=

Define environment variables for the ionscale domain and Let's Encrypt email address, which will be used in the configuration file.

```bash
export IONSCALE_ACME_EMAIL="your-email@example.com"  # For Let's Encrypt notifications
export IONSCALE_DOMAIN="ionscale.example.com"        # Your ionscale domain
```

--------------------------------

### Apply a custom DERP map to a tailnet

Source: https://jsiebens.github.io/ionscale/configuration/derp

Create a JSON file and use the ionscale CLI to apply the configuration to a specific tailnet.

```bash
# Create the DERP map file
cat > my-derpmap.json <<EOF
{
  "Regions": {
    "1": {
      "RegionID": 1,
      "RegionCode": "custom",
      "RegionName": "My Custom DERP",
      "Nodes": [
        {
          "Name": "derp1",
          "RegionID": 1,
          "HostName": "derp.example.com",
          "DERPPort": 443,
          "STUNPort": 3478
        }
      ]
    }
  }
}
EOF

# Apply it to a tailnet
ionscale tailnets set-derp-map --tailnet <tailnet-id> --file my-derpmap.json
```

--------------------------------

### Environment Variable Substitution in YAML

Source: https://jsiebens.github.io/ionscale/configuration

Illustrates using environment variables with default values or as required parameters within the YAML configuration file.

```yaml
database:
  type: ${DB_TYPE:sqlite}
  url: ${DB_URL}
  max_open_conns: ${DB_MAX_OPEN_CONNS:10}

```

--------------------------------

### Configure Custom DNS Plugin

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers?q=

Use this configuration for a custom DNS plugin. Ensure the plugin is executable and configured correctly.

```yaml
dns:
  magic_dns_suffix: "ts.example.com"
  provider:
    plugin_path: "/opt/dns-plugins/my-custom-provider"
    zone: "example.com"
    config:
      # Configuration specific to your custom plugin
      endpoint: "https://api.mydnsprovider.com"
      api_key: "your-api-key"
      custom_setting: "value"

```

--------------------------------

### Configure External DERP Server Sources

Source: https://jsiebens.github.io/ionscale/configuration/derp?q=

Specify URLs for external DERP map configurations to be loaded at startup. Supports HTTP/HTTPS, local files, Git, S3, and GCS. Changes require a server restart.

```yaml
derp:
  sources:
    - https://controlplane.tailscale.com/derpmap/default  # Tailscale's default DERP map
    - https://example.com/my-custom-derpmap.json          # Custom DERP map
    - git::https://github.com/example/derpmap//config.json  # From a git repository
    - file:///etc/ionscale/derpmaps/custom.json           # From a local file
```

--------------------------------

### Create Tailnet Allowing Domain Access

Source: https://jsiebens.github.io/ionscale/getting-started/iam-policies?q=

Create a new tailnet and configure it to allow access for all users with a specified email domain.

```bash
# Allow all users with an @example.com email address
ionscale tailnet create --name "shared-tailnet" --domain "example.com"
```

--------------------------------

### Configure External DNS Plugin

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers

Use a plugin path to integrate with external DNS providers.

```yaml
dns:
  magic_dns_suffix: "ts.example.com"
  provider:
    plugin_path: "/usr/local/bin/libdns-cloudflare-plugin"
    zone: "example.com"
    config:
      api_token: "your-cloudflare-api-token"
```

--------------------------------

### Connect Device with Interactive Login

Source: https://jsiebens.github.io/ionscale/getting-started/tailnet?q=

Initiates an interactive login flow for connecting a device to the tailnet. This method requires an OIDC provider to be configured and opens a browser for authentication.

```bash
tailscale up --login-server=https://ionscale.example.com
```

--------------------------------

### DNS Configuration Section

Source: https://jsiebens.github.io/ionscale/configuration?q=

Settings for MagicDNS and external DNS providers.

```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}
```

--------------------------------

### Server Network Configuration Options

Source: https://jsiebens.github.io/ionscale/configuration

Configuration parameters for controlling the network interfaces and addresses for the ionscale control plane and STUN services.

```yaml
# The HTTP(S) listen address for the control plane
listen_addr: ":8080"

```

```yaml
# The metrics listen address (for Prometheus)
metrics_listen_addr: ":9091"

```

```yaml
# The STUN listen address when using the embedded DERP

```

```yaml
stun_listen_addr: ":3478"

```

```yaml
# The DNS name of the server HTTP(S) endpoint as accessible by clients
public_addr: "ionscale.example.com:443"

```

```yaml
# The DNS name of the STUN endpoint as accessible by clients
stun_public_addr: "ionscale.example.com:3478"

```

--------------------------------

### Create and Apply Custom DERP Map

Source: https://jsiebens.github.io/ionscale/configuration/derp?q=

Commands to create a custom DERP map JSON file and apply it to a tailnet using the `ionscale` CLI. Ensure the `my-derpmap.json` file is correctly formatted.

```bash
# Create the DERP map file
cat > my-derpmap.json <<EOF
{
  "Regions": {
    "1": {
      "RegionID": 1,
      "RegionCode": "custom",
      "RegionName": "My Custom DERP",
      "Nodes": [
        {
          "Name": "derp1",
          "RegionID": 1,
          "HostName": "derp.example.com",
          "DERPPort": 443,
          "STUNPort": 3478
        }
      ]
    }
  }
}
EOF

# Apply it to a tailnet
ionscale tailnets set-derp-map --tailnet <tailnet-id> --file my-derpmap.json

```

--------------------------------

### Connect Device using Auth Key

Source: https://jsiebens.github.io/ionscale/getting-started/tailnet?q=

Connects a device to the tailnet using a pre-generated authentication key. This bypasses interactive login and is suitable for non-interactive environments.

```bash
# Connect using the auth key
tailscale up --login-server=https://ionscale.example.com --auth-key=...
```

--------------------------------

### Using Environment Variables for Admin Access

Source: https://jsiebens.github.io/ionscale/configuration/auth-oidc

Set environment variables for the ionscale address and system admin key to perform administrative tasks like listing Tailnet devices. This is useful when OIDC is configured without explicit system admins.

```bash
export IONSCALE_ADDR="https://your-ionscale-domain.com"
export IONSCALE_SYSTEM_ADMIN_KEY="your-system-admin-key"
ionscale tailnet list

```

--------------------------------

### Configure DNS and Logging in YAML

Source: https://jsiebens.github.io/ionscale/configuration

Defines the MagicDNS suffix, DNS provider settings, and logging parameters for the Ionscale service.

```yaml
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
```

--------------------------------

### TLS Configuration Options

Source: https://jsiebens.github.io/ionscale/configuration

Settings for controlling HTTPS, certificate management, and Let's Encrypt ACME integration.

```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

```

--------------------------------

### Verify Certificate Issuance

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers

Run this command on a device connected to the tailnet to verify certificate generation.

```bash
tailscale cert <hostname>
```

--------------------------------

### Enable MagicDNS and HTTPS Certificates

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers?q=

Command to enable MagicDNS and HTTPS certificates for a specific tailnet. This command configures the ionscale server.

```bash
# Enable MagicDNS and HTTPS certificates for a tailnet
ionscale dns update --tailnet "my-tailnet" --magic-dns --https-certs

```

--------------------------------

### Configure Custom DNS Plugin

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers

Define custom configuration settings for a proprietary DNS plugin.

```yaml
dns:
  magic_dns_suffix: "ts.example.com"
  provider:
    plugin_path: "/opt/dns-plugins/my-custom-provider"
    zone: "example.com"
    config:
      # Configuration specific to your custom plugin
      endpoint: "https://api.mydnsprovider.com"
      api_key: "your-api-key"
      custom_setting: "value"
```

--------------------------------

### Default Configuration Values

Source: https://jsiebens.github.io/ionscale/configuration?q=

The default settings applied when no configuration file is provided.

```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
```

--------------------------------

### Basic OIDC Configuration for ionscale

Source: https://jsiebens.github.io/ionscale/configuration/auth-oidc

Configure the OIDC provider details in your ionscale config.yaml. Ensure the issuer URL, client ID, and client secret are correctly set.

```yaml
auth:
  provider:
    # OIDC issuer URL where ionscale can find the OpenID Provider Configuration Document
    issuer: "https://your-oidc-provider.com"
    # OIDC client ID and secret
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    # Optional: additional OIDC scopes used in the OIDC flow
    additional_scopes: "groups"

```

--------------------------------

### Configure Logging Output

Source: https://jsiebens.github.io/ionscale/configuration?q=

Sets the log level, output format, and optional file path for log storage.

```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
```

--------------------------------

### Environment Variable Substitution in YAML

Source: https://jsiebens.github.io/ionscale/configuration?q=

Use ${VAR} or ${VAR:default} syntax to inject environment variables into the configuration file.

```yaml
database:
  type: ${DB_TYPE:sqlite}
  url: ${DB_URL}
  max_open_conns: ${DB_MAX_OPEN_CONNS:10}
```

--------------------------------

### OIDC Configuration Section

Source: https://jsiebens.github.io/ionscale/configuration?q=

Settings for OIDC authentication providers and system administrator access control.

```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"]
```

--------------------------------

### Manage Tailnet-Specific DERP Maps

Source: https://jsiebens.github.io/ionscale/configuration/derp?q=

Configure custom DERP maps for individual tailnets. Use `--file` to set a map, and `--tailnet` to specify the target tailnet. Revert to instance defaults with `reset-derp-map`.

```bash
# View a tailnet's current DERP map
ionscale tailnets get-derp-map --tailnet <tailnet-id> [--json]

# Set a custom DERP map for a specific tailnet
ionscale tailnets set-derp-map --tailnet <tailnet-id> --file <derpmap.json>

# Remove the custom configuration and revert to the instance default
ionscale tailnets reset-derp-map --tailnet <tailnet-id>
```

--------------------------------

### Configure Security Keys

Source: https://jsiebens.github.io/ionscale/configuration?q=

Defines system administrator and control plane keys. Use environment variables for sensitive values to avoid exposure in version control.

```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
```

--------------------------------

### Configure DigitalOcean DNS

Source: https://jsiebens.github.io/ionscale/configuration/dns-providers

Requires an API token with read and write access.

```yaml
dns:
  magic_dns_suffix: "ts.example.com"
  provider:
    name: "digitalocean"
    zone: "example.com"
    config:
      auth_token: "your-digitalocean-api-token"
```

--------------------------------

### Create a Basic Tailnet

Source: https://jsiebens.github.io/ionscale/getting-started/tailnet?q=

Use this command to create a new tailnet with default ACL and IAM policies. The tailnet name must be unique and contain only alphanumeric characters, hyphens, and underscores.

```bash
ionscale tailnet create --name "my-first-tailnet"
```
Tokens:
Raw