config.example.toml

# Railscale Configuration Example
# ================================
#
# Railscale looks for configuration in the following order:
#   1. /etc/railscale/config.toml
#   2. ~/.config/railscale/config.toml
#   3. ./config.toml (current directory)
#   4. Path specified with --config flag
#
# Priority order (highest to lowest):
#   CLI flags > Environment variables > Config file > Defaults
#
# -----------------------------------------------------------------------------
# Environment Variables
# -----------------------------------------------------------------------------
#
# All settings can be configured via environment variables with RAILSCALE_* prefix.
# For Headscale migration, HEADSCALE_* prefixed vars are also supported as fallback.
#
# Available environment variables:
#
#   RAILSCALE_CONFIG              Path to config file
#   RAILSCALE_DATABASE_URL        Database connection URL (sqlite:// or postgres://)
#   RAILSCALE_LISTEN_ADDR         Address to bind the server to
#   RAILSCALE_SERVER_URL          Public URL for client connections
#   RAILSCALE_POLICY_FILE         Path to policy JSON file
#   RAILSCALE_NOISE_KEY           Path to Noise protocol private key
#   RAILSCALE_BASE_DOMAIN         Base domain for MagicDNS
#   RAILSCALE_PREFIX_V4           IPv4 CIDR prefix for allocation
#   RAILSCALE_PREFIX_V6           IPv6 CIDR prefix for allocation
#   RAILSCALE_LOG_LEVEL           Log level (trace, debug, info, warn, error)
#
# DERP embedded server:
#   RAILSCALE_DERP_EMBEDDED_ENABLED   Enable embedded DERP (true/false)
#   RAILSCALE_DERP_REGION_ID          DERP region ID
#   RAILSCALE_DERP_REGION_NAME        DERP region name
#   RAILSCALE_DERP_LISTEN_ADDR        DERP listen address
#   RAILSCALE_DERP_ADVERTISE_HOST     Hostname advertised to clients
#   RAILSCALE_DERP_ADVERTISE_PORT     Port advertised to clients
#   RAILSCALE_DERP_CERT_PATH          Path to TLS certificate
#   RAILSCALE_DERP_TLS_KEY_PATH       Path to TLS private key
#   RAILSCALE_DERP_PRIVATE_KEY_PATH   Path to DERP protocol key
#
# Example:
#   export RAILSCALE_SERVER_URL="https://ts.example.com"
#   export RAILSCALE_DATABASE_URL="sqlite:///var/lib/railscale/db.sqlite"
#   railscale serve
#
# Headscale migration example (HEADSCALE_* vars work as fallback):
#   export HEADSCALE_SERVER_URL="https://ts.example.com"  # Works!
#   railscale serve

# -----------------------------------------------------------------------------
# Server Configuration
# -----------------------------------------------------------------------------

# The URL clients will use to connect to this server.
# Must be accessible from client machines.
# For production, use HTTPS with a valid domain.
server_url = "http://127.0.0.1:8080"

# Address to bind the HTTP server to.
# NOTE: code default is "0.0.0.0:8080" (all interfaces).
# For security, we recommend binding to localhost and using a reverse proxy.
listen_addr = "127.0.0.1:8080"

# Path to the Noise protocol private key file.
# This key encrypts traffic between railscale and Tailscale clients.
# A missing key will be automatically generated on first run.
noise_private_key_path = "/var/lib/railscale/noise_private.key"

# -----------------------------------------------------------------------------
# IP Address Allocation
# -----------------------------------------------------------------------------

# IPv4 prefix for node address allocation.
# Must be within 100.64.0.0/10 (CGNAT range reserved for Tailscale).
prefix_v4 = "100.64.0.0/10"

# IPv6 prefix for node address allocation.
# Must be within fd7a:115c:a1e0::/48 (Tailscale's ULA range).
prefix_v6 = "fd7a:115c:a1e0::/48"

# IP allocation strategy: "sequential" or "random"
# - sequential: allocate IPs in order (100.64.0.1, 100.64.0.2, ...)
# - random: allocate IPs randomly within the prefix
ip_allocation = "sequential"

# Inactivity timeout for ephemeral nodes (in seconds).
# Ephemeral nodes are created with auth keys that have the "ephemeral" flag set.
# When an ephemeral node disconnects and remains inactive for this duration,
# it is automatically deleted from the database.
# Set to 0 to disable automatic deletion (ephemeral nodes persist until manually removed).
# Default: 120 seconds (2 minutes)
ephemeral_node_inactivity_timeout_secs = 120

# Base domain for MagicDNS hostnames.
# Nodes will be accessible as <hostname>.<base_domain>
# This MUST be different from your server_url domain.
base_domain = "railscale.net"

# -----------------------------------------------------------------------------
# Database Configuration
# -----------------------------------------------------------------------------

[database]
# Database type: "sqlite" or "postgres"
# SQLite is recommended for most deployments.
db_type = "sqlite"

# For SQLite: path to the database file
# For Postgres: connection string (e.g., "postgres://user:pass@host/db")
connection_string = "/var/lib/railscale/db.sqlite"

[database.sqlite]
# Enable WAL mode for better write concurrency (default: true).
write_ahead_log = true

# -----------------------------------------------------------------------------
# DERP (Relay) Configuration
# -----------------------------------------------------------------------------
#
# DERP is a relay system that Tailscale uses when direct connections
# cannot be established (NAT traversal, firewalls, etc.).
# https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp

[derp]
# URL to fetch the public DERP map from.
# Set to null/empty to disable fetching from URL.
derp_map_url = "https://controlplane.tailscale.com/derpmap/default"

# Path to a local DERP map file (JSON format).
# Use this to define custom DERP servers.
# derp_map_path = "/etc/railscale/derp-map.json"

# How often to refresh the DERP map (in seconds).
update_frequency_secs = 3600

# Embedded DERP server configuration.
# Running your own DERP server improves latency and privacy.
[derp.embedded_derp]
# Enable the embedded DERP server.
# When enabled, your railscale server also acts as a relay.
enabled = false

# Region ID for the embedded DERP server.
# Must be unique if using multiple DERP regions.
region_id = 999

# Human-readable name shown in Tailscale UI.
region_name = "railscale"

# Address to bind the DERP HTTPS listener to.
listen_addr = "0.0.0.0:3340"

# Hostname or IP advertised to clients.
# Defaults to the host from server_url if not set.
# advertise_host = "derp.example.com"

# Port advertised to clients.
# Defaults to the port from listen_addr if not set.
# advertise_port = 443

# TLS certificate and key paths (PEM format).
# Required when embedded DERP is enabled.
cert_path = "/var/lib/railscale/derp_cert.pem"
tls_key_path = "/var/lib/railscale/derp_tls_key.pem"

# DERP protocol private key path.
# A missing key will be automatically generated.
private_key_path = "/var/lib/railscale/derp_private.key"

# STUN server address for NAT traversal assistance.
# STUN helps clients discover their public IP.
stun_listen_addr = "0.0.0.0:3478"

# -----------------------------------------------------------------------------
# DNS Configuration
# -----------------------------------------------------------------------------
#
# Railscale supports Tailscale's DNS features including MagicDNS.
# See: https://tailscale.com/kb/1054/dns/
#      https://tailscale.com/kb/1081/magicdns/
#
# For DNS to work, clients must have --accept-dns=true (the default).

[dns]
# Enable MagicDNS.
# When enabled, nodes are accessible by hostname via the tailnet.
magic_dns = true

# Override local DNS settings on clients.
# - true (default): Clients use railscale's DNS config exclusively
# - false: Clients keep their local DNS, railscale only handles tailnet domains
#
# Set to false if you don't want to break clients' existing DNS setup.
override_local_dns = true

# Search domains added to client DNS config.
# The base_domain is always included first when MagicDNS is enabled.
search_domains = []

# Extra DNS records served by MagicDNS.
# Useful for internal services that should resolve on the tailnet.
# extra_records = [
#     { name = "grafana.railscale.net", record_type = "A", value = "100.64.0.5" },
#     { name = "prometheus.railscale.net", record_type = "A", value = "100.64.0.6" },
# ]

[dns.nameservers]
# Global nameservers for general DNS queries.
# Can be IP addresses or DNS-over-HTTPS URLs.
# These are used for all queries except split DNS domains.
global = [
  "1.1.1.1", # Cloudflare primary
  "1.0.0.1", # Cloudflare secondary
  "8.8.8.8", # Google primary
  "8.8.4.4", # Google secondary
]

# For DNS-over-HTTPS (NextDNS example):
# global = [
#     "https://dns.nextdns.io/abc123",
# ]

# Split DNS: route specific domains to dedicated nameservers.
# Queries for these domains bypass global nameservers.
# Useful for resolving internal corporate domains.
[dns.nameservers.split]
# "corp.example.com" = ["10.0.0.53", "10.0.0.54"]
# "internal.lan" = ["192.168.1.1"]

# -----------------------------------------------------------------------------
# OIDC Authentication (Optional)
# -----------------------------------------------------------------------------
#
# Configure OpenID Connect for user authentication.
# When enabled, users authenticate via your identity provider.

# [oidc]
# # OIDC issuer URL from your identity provider.
# issuer = "https://sso.example.com"
#
# # Client credentials from your identity provider.
# client_id = "railscale"
# client_secret = "your-client-secret"
#
# # Alternatively, load secret from a file (supports env vars):
# # client_secret_path = "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
#
# # OAuth2 scopes to request.
# scope = ["openid", "profile", "email"]
#
# # Require email to be verified by the identity provider.
# email_verified_required = true
#
# # How long before a node needs to re-authenticate (seconds).
# # Default: 180 days. Set to 0 for no expiry.
# expiry_secs = 15552000
#
# # Use token expiry instead of expiry_secs.
# # Only enable if you understand the implications.
# use_expiry_from_token = false
#
# # Restrict access to specific email domains.
# allowed_domains = ["example.com"]
#
# # Restrict access to specific email addresses.
# allowed_users = ["alice@example.com", "bob@example.com"]
#
# # Restrict access to users in specific groups.
# allowed_groups = ["/railscale-users"]
#
# # Extra parameters sent to the authorization endpoint.
# [oidc.extra_params]
# domain_hint = "example.com"
#
# # PKCE (Proof Key for Code Exchange) adds security to the OAuth flow.
# # Enabled by default with S256 (recommended).
# [oidc.pkce]
# enabled = true
# method = "S256"

# -----------------------------------------------------------------------------
# REST API Configuration
# -----------------------------------------------------------------------------
#
# The REST API provides Headscale-compatible endpoints for remote administration.
# By default, API endpoints are served on the main HTTP server when enabled.
# Optionally, the API can run on a separate listener for network-level isolation.
#
# SECURITY: The API is disabled by default. Enable only if you need remote access.
# Always use HTTPS in production and rotate API keys regularly.

[api]
# Enable the REST API.
# When false, /api/v1/* endpoints return 404.
enabled = false

# Host/IP to bind the API listener to.
# If not set (default), API runs on the main server port (listen_addr).
# If set, API runs on a separate listener at listen_host:listen_port.
#
# Examples:
#   Not set       - API on same port as protocol (simple setup)
#   "127.0.0.1"   - API on localhost only (secure, recommended for production)
#   "0.0.0.0"     - API on all interfaces
#
# listen_host = "127.0.0.1"

# Port for the API listener. Only used when listen_host is set.
# listen_port = 9090

# Enable per-IP rate limiting for API requests.
# Protects against abuse and brute-force attacks.
rate_limit_enabled = true

# Maximum requests per minute per IP address.
# Only applies when rate_limit_enabled is true.
rate_limit_per_minute = 100

# Reverse proxy settings.
# When behind a reverse proxy (nginx, caddy), enable this to extract
# real client IPs from X-Forwarded-For headers for rate limiting.
# behind_proxy = true
# trusted_proxies = ["127.0.0.1", "10.0.0.0/8"]

# -----------------------------------------------------------------------------
# Verify Endpoint Configuration
# -----------------------------------------------------------------------------
#
# The /verify endpoint is used by DERP servers to check if a client is
# registered. It is intentionally unauthenticated for compatibility.
# Protect it with rate limiting and/or IP allowlists.

[verify]
# Rate limit for /verify requests (per minute per IP). 0 to disable.
rate_limit_per_minute = 60

# IP allowlist. When non-empty, only these IPs/CIDRs can reach /verify.
# allowed_ips = ["10.0.0.0/8", "192.168.1.100"]

# Trusted proxies for X-Forwarded-For extraction on /verify.
# Only used when allowed_ips is non-empty.
# trusted_proxies = ["127.0.0.1"]

# -----------------------------------------------------------------------------
# Feature Flags
# -----------------------------------------------------------------------------

# Enable Taildrop file sharing between nodes.
# Nodes can send files to each other using `tailscale file send`.
# https://tailscale.com/kb/1106/taildrop/
taildrop_enabled = true

# Randomize WireGuard port on clients.
# Helps with some buggy firewalls that block the default port 41641.
# https://tailscale.com/kb/1181/firewalls/
randomize_client_port = false

# Hide build metadata (commit, rustc, build time) from /version endpoint.
# Enable to prevent fingerprinting in production.
# hide_build_metadata = true

# DANGEROUS: Allow registration without Noise protocol (testing only).
# Never enable in production — bypasses cryptographic machine binding.
# allow_non_noise_registration = false

# -----------------------------------------------------------------------------
# DNS Provider for tailscale cert (Optional)
# -----------------------------------------------------------------------------
#
# Enables `tailscale cert` on nodes by providing a DNS provider for ACME
# dns-01 challenges. When configured, each node gets a cert domain in its
# map response and can request TXT records via /machine/set-dns.
#
# Cloudflare:
# [dns_provider]
# type = "cloudflare"
# api_token = "your-cloudflare-api-token"  # DNS:Edit permission
# zone_id = "your-zone-id"
#
# GoDaddy:
# [dns_provider]
# type = "godaddy"
# api_key = "your-api-key"
# api_secret = "your-api-secret"
#
# Generic webhook (for unsupported providers):
# [dns_provider]
# type = "webhook"
# url = "https://dns-api.example.com/txt-record"
# secret = "optional-hmac-sha256-secret"  # signs requests with X-Signature header

# -----------------------------------------------------------------------------
# App Connectors
# -----------------------------------------------------------------------------
#
# App connectors are configured in the policy file (not this config file).
# Add nodeAttrs to your policy JSON to designate app connector nodes:
#
# {
#   "nodeAttrs": [
#     {
#       "target": ["tag:connector"],
#       "app": {
#         "tailscale.com/app-connectors": [
#           {
#             "name": "my-app",
#             "domains": ["app.example.com"],
#             "connectors": ["tag:connector"]
#           }
#         ]
#       }
#     }
#   ]
# }
#
# Nodes matching the target selectors receive the app connector config in
# their CapMap. App connector nodes get non-exit routes auto-approved.

# -----------------------------------------------------------------------------
# Performance Tuning
# -----------------------------------------------------------------------------
#
# Advanced settings. The defaults work well for most deployments.
# Only modify if you've identified a specific performance issue.

[tuning]
# NodeStore batches write operations before rebuilding peer relationships.
# Larger batches reduce CPU usage but increase latency.
node_store_batch_size = 100
node_store_batch_timeout_ms = 500

# Registration cache settings.
# The cache stores pending registrations to handle retries.
register_cache_expiration_secs = 900 # 15 minutes
register_cache_cleanup_secs = 1200   # 20 minutes

# Interval between keep-alive messages for long-polling map sessions.
# Helps detect stale connections. Set to 0 to disable.
map_keepalive_interval_secs = 60