leviathonbeast/ionscale
1
0
Fork 0
mirror of https://github.com/jsiebens/ionscale.git synced 2026-03-31 15:07:49 +01:00
Code Issues Packages Projects Releases Wiki Activity

chore: updates docs

Browse Source
This commit is contained in:
Johan Siebens
2025-04-26 21:54:11 +02:00
parent a2fd56be89
commit e1f3ad61fb
13 changed files with 1245 additions and 223 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mkdocs/docs/configuration/auth-oidc.md
+191
View File
@@ -0,0 +1,191 @@
# Configuring authentication with OIDC
While ionscale can operate without an OIDC (OpenID Connect) provider using only static keys, configuring an OIDC provider is highly recommended for enhanced security, user management, and a smoother administrative experience.
## Why configure an OIDC provider?
Without an OIDC provider, ionscale operates in a key-only mode:
- System administrators can only use the system admin key for administrative tasks
- Tailscale devices can only connect using [tags](https://tailscale.com/kb/1068/tags) and [pre-authentication keys](https://tailscale.com/kb/1085/auth-keys)
- No user accounts or user-specific permissions are available
With an OIDC provider configured:
- Users can authenticate using their existing identity provider credentials
- Administrators can assign specific permissions to users
- System administration can be delegated to specific users
- Fine-grained access control based on user identity becomes possible
- More seamless user experience with browser-based authentication
## Supported OIDC providers
ionscale supports any standard OIDC provider, including:
- Google Workspace
- Auth0
- Okta
- Azure AD / Microsoft Entra ID
- Keycloak
- GitLab
- GitHub (OAuth 2.0 with OIDC extensions)
- And many others
## Basic OIDC configuration
To configure an OIDC provider, update your ionscale configuration file (`config.yaml`) with the following settings:
```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"
```
### Required configuration fields
- `issuer`: The URL to your OIDC provider's issuer. This URL is used to discover your provider's endpoints.
- `client_id`: The client ID from your OIDC provider application registration.
- `client_secret`: The client secret from your OIDC provider application registration.
### Optional configuration
- `additional_scopes`: A space-separated list of additional OAuth scopes to request during authentication.
By default, ionscale requests the `openid`, `email`, and `profile` scopes.
## Configuring your OIDC provider
When registering ionscale with your OIDC provider, you'll need to configure the following:
**Redirect URI**: Set to `https://your-ionscale-domain.com/auth/callback`
## System administrator access
With OIDC configured, you'll want to specify which users have system administrator privileges.
This is done in the `auth.system_admins` section of your configuration:
```yaml
auth:
# Configuration from previous section...
system_admins:
# By email address
emails:
- "admin@example.com"
- "secadmin@example.com"
# By subject identifier (sub claim from OIDC)
subs:
- "user|123456"
# By attribute expression (using BEXPR syntax)
filters:
- "token.groups contains \"admin\""
- "domain == \"admin.example.com\""
```
You can use one or more of these methods to designate system administrators:
1. **By Email**: List specific email addresses that should have admin privileges.
2. **By Subject ID**: List specific user IDs (the `sub` claim from your OIDC provider).
3. **By Expression**: Use BEXPR filters to determine admin status based on token claims.
## OIDC authentication flow
When a user attempts to authenticate with ionscale:
1. The user is redirected to the OIDC provider's login page.
2. After successful authentication, the user is redirected back to ionscale.
3. ionscale verifies the authentication and checks if:
- The user is a system administrator (based on the `system_admins` configuration).
- The user has access to any tailnets (based on IAM policies configured for individual tailnets).
## Provider-specific setup instructions
### Google
1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Create a new project or select an existing one.
3. Navigate to "APIs & Services" > "Credentials".
4. Click "Create Credentials" > "OAuth client ID".
5. Select "Web application" as the application type.
6. Add `https://your-ionscale-domain.com/auth/callback` as an authorized redirect URI.
7. Copy the client ID and client secret.
Configure ionscale:
```yaml
auth:
provider:
issuer: "https://accounts.google.com"
client_id: "your-client-id.apps.googleusercontent.com"
client_secret: "your-client-secret"
```
### Auth0
1. Go to the [Auth0 Dashboard](https://manage.auth0.com/).
2. Create a new application or select an existing one of type "Regular Web Application".
3. Under "Settings", configure:
- Allowed Callback URLs: `https://your-ionscale-domain.com/auth/callback`
4. Copy the Domain, Client ID, and Client Secret.
Configure ionscale:
```yaml
auth:
provider:
issuer: "https://your-tenant.auth0.com/"
client_id: "your-client-id"
client_secret: "your-client-secret"
```
### Microsoft Azure AD / Entra ID
1. Go to the [Azure Portal](https://portal.azure.com/).
2. Navigate to "Azure Active Directory" > "App registrations".
3. Create a new registration.
4. Add `https://your-ionscale-domain.com/auth/callback` as a redirect URI of type "Web".
5. Under "Certificates & secrets", create a new client secret.
6. Copy the Application (client) ID and the new secret.
Configure ionscale:
```yaml
auth:
provider:
issuer: "https://login.microsoftonline.com/your-tenant-id/v2.0"
client_id: "your-client-id"
client_secret: "your-client-secret"
additional_scopes: "offline_access"
```
## Complete configuration example
```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\""
```
## OIDC without system admin
If you've configured OIDC but no system administrators, you can still use the system admin key from your initial setup for administrative tasks:
```bash
export IONSCALE_URL="https://your-ionscale-domain.com"
export IONSCALE_KEY="your-system-admin-key"
ionscale tailnet list
```
mkdocs/docs/configuration/dns-providers.md
+176
View File
@@ -0,0 +1,176 @@
# Configuring DNS providers
ionscale supports integration with various DNS providers to enable Tailscale's HTTPS certificate functionality. When a DNS provider is properly configured, ionscale can automatically manage TXT records required for the DNS-01 challenge when requesting certificates.
## Why configure a DNS provider
While not strictly required for basic ionscale operation, configuring a DNS provider enables important Tailscale features:
1. **Tailscale HTTPS Certificates**: Allows nodes to receive valid HTTPS certificates for their Tailscale hostnames, enabling secure web services within your tailnet.
2. **Tailscale Serve**: Supports the `tailscale serve` feature, which allows users to easily share web services with proper HTTPS.
Without a configured DNS provider, these features will not be available to your users.
## Supported DNS providers
ionscale uses the [libdns](https://github.com/libdns) libraries to support the following DNS providers:
- [Azure DNS](https://github.com/libdns/azure)
- [Cloudflare](https://github.com/libdns/cloudflare)
- [DigitalOcean](https://github.com/libdns/digitalocean)
- [Google Cloud DNS](https://github.com/libdns/googleclouddns)
- [Amazon Route 53](https://github.com/libdns/route53)
!!! info "Provider availability"
These are the DNS providers supported at the time of this writing. Since ionscale uses the libdns ecosystem, additional providers may be added in future releases as the ecosystem expands.
If you need support for a different DNS provider, check the [libdns GitHub organization](https://github.com/libdns) for newly available providers or consider contributing an implementation for your provider.
!!! note "Future plugin system"
A plugin system for DNS providers is currently in the ideation phase. This would make it significantly easier to add and configure additional DNS providers without modifying the core ionscale code. Stay tuned for updates on this feature in future releases.
## DNS provider configuration
To configure a DNS provider, add the appropriate settings to your ionscale configuration file (`config.yaml`):
```yaml
dns:
# The base domain for MagicDNS FQDN hostnames
magic_dns_suffix: "ionscale.net"
# DNS provider configuration for HTTPS certificates
provider:
# Name of your DNS provider
name: "cloudflare"
# The DNS zone to use (typically your domain name)
zone: "example.com"
# Provider-specific configuration (varies by provider)
config:
# Provider-specific credentials and settings go here
# See provider-specific examples below
```
### Important requirements
1. The `magic_dns_suffix` must be a subdomain of the provider's zone (or the zone itself).
2. MagicDNS must be enabled for the tailnet to use HTTPS certificates.
3. You must have administrative access to the DNS zone to configure the provider.
## Provider-specific examples
### Cloudflare
```yaml
dns:
magic_dns_suffix: "ts.example.com"
provider:
name: "cloudflare"
zone: "example.com"
config:
auth_token: "your-cloudflare-api-token"
# OR use email/api_key authentication
# email: "your-email@example.com"
# api_key: "your-global-api-key"
```
For Cloudflare, create an API token with the "Edit" permission for "Zone:DNS".
### Azure DNS
```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"
```
For Azure, create a service principal with "DNS Zone Contributor" role for your DNS zone's resource group.
### Amazon Route 53
```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"
```
For AWS Route 53, create an IAM user with permissions to modify records in your hosted zone.
### Google Cloud DNS
```yaml
dns:
magic_dns_suffix: "ts.example.com"
provider:
name: "googleclouddns"
zone: "example-com" # Note: GCP uses zone names without dots
config:
project: "your-project-id"
# Either provide service account JSON directly
service_account_json: '{"type":"service_account","project_id":"your-project",...}'
# OR specify a path to a service account key file
# service_account_key_file: "/path/to/service-account-key.json"
```
For Google Cloud DNS, create a service account with the "DNS Administrator" role.
### DigitalOcean
```yaml
dns:
magic_dns_suffix: "ts.example.com"
provider:
name: "digitalocean"
zone: "example.com"
config:
token: "your-digitalocean-api-token"
```
For DigitalOcean, create an API token with read and write access.
## Enabling HTTPS certificates for a tailnet
After configuring a DNS provider in your ionscale server, you can enable HTTPS certificates for a tailnet:
```bash
# Enable MagicDNS and HTTPS certificates for a tailnet
ionscale dns update --tailnet "my-tailnet" --magic-dns --https-certs
```
## Verifying DNS provider configuration
To verify that your DNS provider is correctly configured:
1. Configure a tailnet with MagicDNS and HTTPS certificates enabled.
2. Connect a device to the tailnet.
3. On the device, run:
```bash
tailscale cert <hostname>
```
4. If successful, the command will obtain a certificate for the hostname.
5. You should see TXT records created in your DNS zone for the ACME challenge.
## Troubleshooting
If you encounter issues with DNS provider integration:
1. **Check DNS Provider Credentials**: Ensure the credentials in your configuration have sufficient permissions.
2. **Verify Zone Configuration**: Make sure the zone in your configuration matches your actual DNS zone.
3. **Check MagicDNS Settings**: Confirm that `magic_dns_suffix` is properly configured as a subdomain of your zone.
4. **Review Server Logs**: The ionscale server logs may contain error messages related to DNS provider integration.
5. **Test DNS Record Creation**: Some providers offer tools to test API access for creating and updating DNS records.
mkdocs/docs/getting-started/docker.md
-72
View File
@@ -1,72 +0,0 @@
# Getting started with Docker
You can install and run __ionscale__ using the Docker images published on [GitHub Container Registry](https://github.com/jsiebens/ionscale/pkgs/container/ionscale).
## Requirements
- A Linux machine with port 443 and 3478 open to ingress traffic.
- Docker installed. See the [official installation documentation](https://docs.docker.com/install/)
- A registered domain name.
## Step 1. Configure DNS
Set up a `A` DNS records: `ionscale.example.com` (We are assuming that your domain name is example.com.)
!!! tip
You can use `dig` to make sure that DNS records are propagated:
``` bash
$ dig ionscale.example.com
```
## Step 2. Run ionscale with Docker
### Configure ionscale
``` bash
mkdir -p ionscale/data
cd ./ionscale
```
Generate a configuration file for __ionscale__ with the following commands:
``` bash
export IONSCALE_ACME_EMAIL=<your email>
export IONSCALE_DOMAIN=ionscale.example.com
export IONSCALE_SYSTEM_ADMIN_KEY=$(docker run ghcr.io/jsiebens/ionscale:0.15.0 genkey -n)
```
``` bash
tee ./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}"
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
```
### Start ionscale
Run an __ionscale__ instance with the following command:
``` bash
docker run \
-v $(pwd)/config.yaml:/etc/ionscale/config.yaml \
-v $(pwd)/data:/data \
-p 443:443 \
-p 3478:3478/udp \
ghcr.io/jsiebens/ionscale:0.15.0 server --config /etc/ionscale/config.yaml
```
mkdocs/docs/getting-started/index.md
+84
View File
@@ -0,0 +1,84 @@
# Getting started with ionscale
After installing ionscale, you'll need to configure the CLI to interact with your server. This guide will walk you through the initial setup and explain the authentication options available.
## Installing the ionscale CLI
The ionscale CLI is the primary tool for managing your ionscale instance. It allows you to create and manage tailnets, users, and access controls.
```bash
# Download the CLI (adjust the URL for your system architecture)
curl -L -o ionscale https://github.com/jsiebens/ionscale/releases/download/v0.16.0/ionscale_linux_amd64
# Make it executable
chmod +x ionscale
# Move to system path
sudo mv ionscale /usr/local/bin/
```
## Authentication requirements
To use the ionscale CLI, you must authenticate with the server using one of two methods:
!!! important "Administrator access required"
All management operations require either:
1. **System admin key** authentication, or
2. **OIDC user** authentication with system administrator privileges
### Option 1: Using the system admin key
If you configured ionscale with a system admin key during installation, you can authenticate using that key:
```bash
# Configure environment variables
export IONSCALE_URL="https://ionscale.example.com"
export IONSCALE_KEY="your-system-admin-key"
# Verify connection
ionscale version
```
The system admin key provides full administrative access to your ionscale instance. This is the default authentication method when OIDC is not configured.
### Option 2: Using OIDC authentication
If you configured ionscale with an OIDC provider, users designated as system administrators in the OIDC configuration can authenticate:
```bash
# Configure URL only
export IONSCALE_URL="https://ionscale.example.com"
# Authenticate through OIDC
ionscale auth login
```
This will open a browser window where you can authenticate with your OIDC provider. After successful authentication, if your account has system administrator privileges, you'll be able to use the CLI.
!!! tip "OIDC system administrators"
System administrators are defined in the ionscale configuration under the `auth.system_admins` section. See the [Authentication with OIDC](../configuration/auth-oidc.md) documentation for details.
## Basic CLI commands
Once authenticated, you can use the ionscale CLI to manage your instance:
```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
```
## Next steps
After setting up the CLI, you can:
1. [Create your first tailnet](tailnet.md)
mkdocs/docs/getting-started/manual.md
-115
View File
@@ -1,115 +0,0 @@
# Getting started on a Linux Server
This tutorial will guide you through the steps needed to install and run __ionscale__ on a Linux machine.
## Prerequisites
- A Linux machine with port 443 and 3478 open to ingress traffic.
- A registered domain name.
## Step 1. Configure DNS
Set up a `A` DNS records: `ionscale.example.com` (We are assuming that your domain name is example.com.)
!!! tip
You can use `dig` to make sure that DNS records are propagated:
``` bash
$ dig ionscale.example.com
```
## Step 2. Set up ionscale on your Linux host
### Prepare installation
Run the following commands to prepare the installation:
``` bash
sudo mkdir -p /etc/ionscale
sudo mkdir -p /var/lib/ionscale
sudo useradd --system --no-create-home --shell /bin/false ionscale
sudo chown ionscale:ionscale /etc/ionscale
sudo chown ionscale:ionscale /var/lib/ionscale
```
### Install ionscale
Run the following commands to install the __ionscale__ binary on your Linux host:
``` bash
sudo curl \
-o "/usr/local/bin/ionscale" \
-sfL "https://github.com/jsiebens/ionscale/releases/download/v0.15.0/ionscale_linux_amd64"
sudo chmod +x "/usr/local/bin/ionscale"
```
### Configure ionscale
Generate a system admin key for __ionscale__ using the `ionscale genkey` command and write it the an environment file:
``` bash
sudo tee /etc/default/ionscale >/dev/null <<EOF
IONSCALE_KEYS_SYSTEM_ADMIN_KEY=$(ionscale genkey -n)
EOF
```
Generate a configuration file for __ionscale__ with the following commands:
``` bash
export IONSCALE_ACME_EMAIL=<your email>
export IONSCALE_DOMAIN=ionscale.example.com
```
``` 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)"
logging:
level: info
EOF
```
Create a systemd service file for __ionscale__ with the following commands:
``` bash
sudo tee /etc/systemd/system/ionscale.service >/dev/null <<EOF
[Unit]
Description=ionscale - a Tailscale Controller 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
```
### Start ionscale
On your Linux machine, run the following commands to enable and start the __ionscale__ daemon:
``` bash
sudo systemctl daemon-reload
sudo systemctl enable ionscale
sudo systemctl start ionscale
```
mkdocs/docs/getting-started/tailnet.md
+191
View File
@@ -0,0 +1,191 @@
# Creating your first tailnet
A tailnet is a private network that connects your devices securely using Tailscale. This guide will walk you through creating your first tailnet with ionscale.
## Prerequisites
Before creating a tailnet, make sure you have:
- ionscale server installed and running
- The ionscale CLI installed and configured
- Authentication with system administrator privileges
## Creating a tailnet
The simplest way to create a tailnet is with the `tailnet create` command:
```bash
ionscale tailnet create --name "my-first-tailnet"
```
This creates a basic tailnet named "my-first-tailnet" with:
- A default ACL policy that allows all connections
```
{"acls": [{"action": "accept", "src": ["*"], "dst": ["*:*"]}]}
```
- A default IAM policy that determines who can access the tailnet
!!! note
The tailnet name must be unique within your ionscale instance and should only contain alphanumeric characters, hyphens, and underscores.
## Setting IAM policies for access control
!!! important "OIDC required"
IAM policies are only relevant when an OIDC provider is configured. If your ionscale instance isn't using OIDC, access to tailnets is managed solely through auth keys, and the configuration in this section won't apply.
When using OIDC authentication, you'll need to configure who can access your tailnet through IAM policies.
### Configuring IAM during tailnet creation
You can set a basic IAM policy when creating a tailnet using flags:
```bash
# Allow all users with an @example.com email address
ionscale tailnet create --name "company-tailnet" --domain "example.com"
# Allow only a specific user
ionscale tailnet create --name "personal-tailnet" --email "user@example.com"
```
These flags provide quick ways to set up common IAM policies:
- `--domain example.com`: Creates a **shared tailnet** that allows all users with an email address from the specified domain. This is ideal for company or team networks where multiple users need access. The IAM policy will contain a filter rule like `domain == "example.com"`.
- `--email user@example.com`: Creates a **personal tailnet** that grants access only to the specific email address. This is suitable for individual use or when you want to tightly control access to a specific user. The IAM policy will contain an entry for the specified email.
!!! note
You can't use both flags together. Choose either domain-based access for a shared network or email-based access for a personal network.
### Configuring IAM after tailnet creation
You can view and update the IAM policy for an existing tailnet:
```bash
# View current IAM policy
ionscale iam get-policy --tailnet "my-first-tailnet"
# Update IAM policy using a JSON file
ionscale iam update-policy --tailnet "my-first-tailnet" --file policy.json
```
Example policy.json file:
```json
{
"filters": ["domain == example.com"],
"emails": ["specific-user@otherdomain.com"],
"roles": {
"admin@example.com": "admin"
}
}
```
## Connecting devices to your tailnet
How devices connect to your tailnet depends on your authentication configuration:
### Using OIDC authentication
If OIDC is configured, users with access (based on the IAM policy) connect via web authentication:
```bash
tailscale up --login-server=https://ionscale.example.com
```
This opens a browser window where users authenticate with the OIDC provider. After successful authentication, if the user has access based on the tailnet's IAM policy, the device will be connected.
### Using auth keys
Auth keys allow devices to join a tailnet without interactive authentication. This is useful for automated deployments, servers, or environments where browser-based authentication isn't practical.
There are two main scenarios for creating auth keys:
#### Without OIDC configured
When OIDC is not configured, a system administrator must create auth keys with appropriate tags:
```bash
# Create an auth key with a tag
ionscale auth-key create --tailnet "my-first-tailnet" --tags "tag:server"
```
The tags assigned to the key will determine what network access the device has once connected, based on your ACL rules.
#### With OIDC configured
When OIDC is configured, any user with access to a tailnet can create auth keys for that tailnet:
```bash
# As an authenticated user, create an auth key
ionscale auth-key create --tailnet "my-first-tailnet"
```
Additionally, system administrators can create auth keys with specific tags:
```bash
# As a system administrator, create a key with tags
ionscale auth-key create --tailnet "my-first-tailnet" --tags "tag:database"
```
#### Connecting with auth keys
To connect a device using an auth key:
```bash
# Connect using the auth key
tailscale up --login-server=https://ionscale.example.com --auth-key=...
```
!!! note
Auth keys in ionscale are single-use by default. Once a key has been used to authenticate a device, it cannot be used again.
## Configuring ACL policies
Access Control Lists (ACLs) define what network access is allowed within a tailnet. By default, tailnets are created with an open policy that allows all connections.
To update the ACL policy:
```bash
# View current ACL policy
ionscale acl get --tailnet "my-first-tailnet"
# Update ACL policy
ionscale acl update --tailnet "my-first-tailnet" --file acl.json
```
Example acl.json with more restrictive rules:
```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"]
}
}
```
!!! tip
ACLs give you fine-grained control over which devices can communicate within your tailnet. For more information, see the [Tailscale ACL documentation](https://tailscale.com/kb/1018/acls/).
## Managing multiple tailnets
You can create multiple tailnets to separate different network 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"
```
!!! note
Each tailnet is a separate network with its own devices, ACLs, and IAM policies. Devices in different tailnets cannot communicate with each other by default.
mkdocs/docs/index.md
+21 -26
View File
@@ -1,35 +1,30 @@
# ionscale
# Welcome to ionscale
> **Note**:
> ionscale is currently beta quality, actively being developed and so subject to changes
ionscale is an open-source alternative to Tailscale's control server, designed to provide a self-hosted coordination service for your Tailscale networks.
**What is Tailscale?**
!!! info "Beta status"
ionscale is currently in beta. While it's stable for production use for small tailnets, we're actively developing new features and improvements.
[Tailscale](https://tailscale.com) is a VPN service that makes the devices and applications you own accessible anywhere in the world, securely and effortlessly.
It enables encrypted point-to-point connections using the open source [WireGuard](https://www.wireguard.com/) protocol, which means only devices on your private network can communicate with each other.
## What is ionscale?
**What is ionscale?**
Tailscale allows your devices to communicate securely across networks using WireGuard®. While Tailscale's client software is open source, their centralized coordination server (which manages public keys and network configurations) is proprietary.
While the Tailscale software running on each node is open source, their centralized "coordination server" which act as a shared drop box for public keys is not.
**ionscale aims to implement a lightweight, open-source control server that:**
_ionscale_ aims to implement such lightweight, open source alternative Tailscale control server.
- Acts as a drop-in replacement for Tailscale's coordination server
- Can be self-hosted on your infrastructure
- Gives you full control over your network configuration
- Works with the standard Tailscale clients
- Supports a [wide range of Tailscale features](./overview/features.md)
## Features
## Getting started
- multi [tailnet](https://tailscale.com/kb/1136/tailnet/) support
- multi user support
- OIDC integration (not required, although recommended)
- [Auth keys](https://tailscale.com/kb/1085/auth-keys/)
- [Access control list](https://tailscale.com/kb/1018/acls/)
- [DNS](https://tailscale.com/kb/1054/dns/)
- nameservers
- Split DNS
- MagicDNS
- [HTTPS Certs](https://tailscale.com/kb/1153/enabling-https/)
- [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh/)
- [Service collection](https://tailscale.com/kb/1100/services/)
- [Taildrop](https://tailscale.com/kb/1106/taildrop/)
- [**Installation guide**](./installation/index.md) - Install ionscale using Docker or directly on Linux
- [**CLI configuration**](./getting-started/index.md) - Set up the ionscale CLI and authenticate
- [**Creating a tailnet**](./getting-started/tailnet.md) - Create and manage your first tailnet
- [**OIDC authentication**](./configuration/auth-oidc.md) - Configure user authentication via OIDC
- [**DNS providers**](./configuration/dns-providers.md) - Set up DNS integration for HTTPS certificates
## Disclaimer
This is not an official Tailscale or Tailscale Inc. project.
<small>
Disclaimer: This is not an official Tailscale or Tailscale Inc. project. Tailscale and WireGuard are trademarks of their respective owners.
</small>
mkdocs/docs/installation/docker.md
+101
View File
@@ -0,0 +1,101 @@
# Installing ionscale with Docker
This guide will walk you through installing and configuring ionscale using Docker containers. Docker provides a simple and consistent way to deploy ionscale across different environments.
## Prerequisites
Before you begin, make sure you have:
- A Linux server (virtual or physical)
- Docker installed ([official Docker installation guide](https://docs.docker.com/engine/install/))
- Root or sudo access
- A registered domain name pointing to your server
- Ports 443 (HTTPS) and 3478/UDP (STUN) open in your firewall
- Basic familiarity with the Linux command line
## Domain and DNS configuration
ionscale requires a domain name to function properly. This enables secure HTTPS connections and proper Tailscale device discovery.
1. Configure an A record in your domain's DNS settings:
```
ionscale.example.com → YOUR_SERVER_IP
```
(Replace "example.com" with your actual domain and "YOUR_SERVER_IP" with your server's public IP address)
2. Verify the DNS record has propagated:
```bash
dig ionscale.example.com
```
The command should return your server's public IP address.
## Container setup
### Creating a directory structure
Create a dedicated directory for ionscale files:
```bash
mkdir -p ionscale/data
cd ./ionscale
```
### Generating a configuration file
First, set up environment variables for the configuration:
```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.16.0 genkey -n)
```
!!! important "System admin key"
The system admin key is a critical security component that provides full administrative access to your ionscale instance. Make sure to save this key securely.
Alternatively, you can configure ionscale without a system admin key by using an OIDC provider and setting up system admin accounts through the OIDC configuration. See the [Authentication with OIDC](../configuration/auth-oidc.md) documentation for details.
Now create the configuration file:
```bash
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
```
### Running the container
Start the ionscale container with the following command:
```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.16.0 server --config /etc/ionscale/config.yaml
```
This command:
- Creates a persistent container named "ionscale"
- Mounts your configuration file and data directory
- Maps the required ports to the host
- Automatically restarts the container if it stops unexpectedly
mkdocs/docs/installation/index.md
+38
View File
@@ -0,0 +1,38 @@
# Installation guide
ionscale can be installed in several ways, depending on your preferences and requirements. This section covers the different installation methods available.
## Choose your installation method
ionscale offers two primary installation methods:
### Docker installation
The [Docker installation](docker.md) method is recommended for:
- Quick deployments
- Testing and evaluation
- Users familiar with container environments
- Simplified upgrades and maintenance
Docker provides an isolated environment with all dependencies included, making it the easiest way to get started with ionscale.
### Linux installation
The [Linux installation](linux.md) method is suitable for:
- Production environments
- Integration with existing infrastructure
- More control over the installation
- Systems without Docker
This approach installs ionscale directly on your Linux server and configures it as a system service.
## Post-installation steps
After completing the installation, consider these next steps:
1. Configure an [OIDC provider](../configuration/auth-oidc.md) for user authentication
2. Set up a [DNS provider](../configuration/dns-providers.md) to enable HTTPS certificates for Tailscale nodes
3. Create and configure tailnets
4. Set up access controls and permissions
mkdocs/docs/installation/linux.md
+155
View File
@@ -0,0 +1,155 @@
# Linux installation
This guide walks you through installing ionscale directly on a Linux server. This approach gives you more control over the installation and is suitable for production environments.
## Prerequisites
Before you begin, make sure you have:
- A Linux server (virtual or physical)
- Root or sudo access
- A registered domain name pointing to your server
- Ports 443 (HTTPS) and 3478/UDP (STUN) open in your firewall
- Basic familiarity with the Linux command line
## Domain and DNS configuration
ionscale requires a domain name to function properly. This enables secure HTTPS connections and proper Tailscale device discovery.
1. Configure an A record in your domain's DNS settings:
```
ionscale.example.com → YOUR_SERVER_IP
```
(Replace "example.com" with your actual domain and "YOUR_SERVER_IP" with your server's public IP address)
2. Verify the DNS record has propagated:
```bash
dig ionscale.example.com
```
The command should return your server's public IP address.
## System preparation
### Create a dedicated service user
For security reasons, ionscale should run under a dedicated, unprivileged system user:
```bash
# Create directories
sudo mkdir -p /etc/ionscale
sudo mkdir -p /var/lib/ionscale
# Create service user
sudo useradd --system --no-create-home --shell /bin/false ionscale
# Set appropriate permissions
sudo chown ionscale:ionscale /etc/ionscale
sudo chown ionscale:ionscale /var/lib/ionscale
```
## Installation
### Download and install the binary
Install the ionscale binary on your system:
```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.16.0/ionscale_linux_amd64"
# Make it executable
sudo chmod +x "/usr/local/bin/ionscale"
# Verify installation
ionscale version
```
### Configuration
1. Generate a system admin key and store it in an environment file:
```bash
sudo tee /etc/default/ionscale >/dev/null <<EOF
IONSCALE_KEYS_SYSTEM_ADMIN_KEY=$(ionscale genkey -n)
EOF
```
!!! important "System admin key"
The system admin key is a critical security component that provides full administrative access to your ionscale instance. Make sure to save this key securely.
Alternatively, you can configure ionscale without a system admin key by using an OIDC provider and setting up system admin accounts through the OIDC configuration. See the [Authentication with OIDC](../configuration/auth-oidc.md) documentation for details.
2. Set up environment variables for the configuration:
```bash
export IONSCALE_ACME_EMAIL="your-email@example.com" # For Let's Encrypt notifications
export IONSCALE_DOMAIN="ionscale.example.com" # Your ionscale domain
```
3. Create the configuration file:
```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)"
logging:
level: info
EOF
```
## Setting up systemd service
Create a systemd service file to manage the ionscale process:
```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
```
The `AmbientCapabilities=CAP_NET_BIND_SERVICE` line allows ionscale to bind to privileged ports (443) without running as root.
## Starting ionscale
Enable and start the ionscale service:
```bash
# Reload systemd to recognize the new service
sudo systemctl daemon-reload
# Enable service to start on boot
sudo systemctl enable ionscale
# Start the service
sudo systemctl start ionscale
# Check status
sudo systemctl status ionscale
```
If everything started successfully, you should see an "active (running)" status.
mkdocs/docs/overview/features.md
+59
View File
@@ -0,0 +1,59 @@
# Supported features
ionscale implements key Tailscale features to provide a complete control server experience. This page outlines the major features that ionscale supports.
## Multi-tailnet support
ionscale allows you to create and manage multiple tailnets (Tailscale private networks) from a single server:
- Create isolated networks for different teams or environments
- Manage separate tailnets for personal and organizational use
- Configure each tailnet with its own ACLs and settings
## User management
- **Multi-user support**: Multiple users can access and use the same tailnet based on permissions
- **OIDC integration**: Optional but recommended for user authentication and management
## Authentication
- **[Auth keys](https://tailscale.com/kb/1085/auth-keys/)**: Generate and manage pre-authentication keys for devices
- **[Device tagging](https://tailscale.com/kb/1068/tags/)**: Apply tags to devices for better management and ACL control
## Network control
- **[Access control lists (ACLs)](https://tailscale.com/kb/1018/acls/)**: Define fine-grained rules for who can access what
- **[Subnet routers](https://tailscale.com/kb/1019/subnets/)**: Connect existing networks to your tailnet
- **[Exit nodes](https://tailscale.com/kb/1103/exit-nodes/)**: Configure nodes to act as VPN exit points
## DNS management
- **[MagicDNS](https://tailscale.com/kb/1081/magicdns/)**: Automatic DNS for tailnet devices
- **[Split DNS](https://tailscale.com/kb/1054/dns/)**: Route specific DNS queries to specific resolvers
- **Custom nameservers**: Configure any DNS servers for your tailnet
## HTTPS and certificates
- **[HTTPS certificates](https://tailscale.com/kb/1153/enabling-https/)**: Automatic SSL/TLS certificates for devices
- **DNS provider integration**: Support for various DNS providers to facilitate ACME challenges
- **[Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve/)**: Share web services easily with HTTPS
## SSH
- **[Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh/)**: Built-in SSH server support
- **SSH policy management**: Control who can SSH into which devices
## DERP
- **Embedded DERP server**
- **Custom DERP maps**: Configure your own DERP servers
## File sharing
- **[Taildrop](https://tailscale.com/kb/1106/taildrop/)**: Send files directly between tailnet devices
## Feature status
Most features are fully implemented and compatible with the official Tailscale clients. As ionscale is continuously developed, new features from Tailscale are regularly added.
If you find any issues with specific features or have requests for additional functionality, please check the [project repository](https://github.com/jsiebens/ionscale) for the latest updates or to submit feedback.
mkdocs/docs/stylesheets/extra.css
+126
View File
@@ -0,0 +1,126 @@
/* Custom CSS for ionscale documentation */
/* Enhance code blocks */
.md-typeset pre {
border-radius: 6px;
box-shadow: 0 2px 6px rgba(0, 0, 0, 0.12);
}
/* Enhance code block headers */
.md-typeset code {
border-radius: 3px;
font-size: 0.9em;
padding: 0.2em 0.4em;
}
/* Make admonitions stand out more */
.md-typeset .admonition {
border-radius: 4px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05);
margin: 1.5em 0;
}
.md-typeset .admonition-title {
padding-left: 2.5rem;
}
/* Make tables more professional */
.md-typeset table:not([class]) {
border-radius: 6px;
box-shadow: 0 1px 4px rgba(0, 0, 0, 0.08);
overflow: hidden;
}
.md-typeset table:not([class]) th {
background-color: rgba(63, 81, 181, 0.08);
font-weight: 600;
}
/* Enhance UI element spacing */
.md-typeset ul li,
.md-typeset ol li {
margin-bottom: 0.35em;
}
.md-typeset h1,
.md-typeset h2,
.md-typeset h3,
.md-typeset h4 {
font-weight: 500;
margin-top: 1.5em;
}
.md-typeset h2 {
border-bottom: 1px solid rgba(63, 81, 181, 0.1);
padding-bottom: 0.3em;
}
/* Subtle border on the right for table of contents */
.md-sidebar--secondary {
border-left: 1px solid rgba(0, 0, 0, 0.07);
background-color: rgba(0, 0, 0, 0.01);
}
/* Navigation improvements */
.md-nav__item .md-nav__link--active {
font-weight: 600;
}
/* Responsive improvements */
@media screen and (min-width: 76.25em) {
.md-sidebar--primary {
border-right: 1px solid rgba(0, 0, 0, 0.07);
background-color: rgba(0, 0, 0, 0.01);
}
}
/* Better footer */
.md-footer-meta {
background-color: rgba(0, 0, 0, 0.87);
}
/* Remove the logo and style site name */
.md-header__button.md-logo {
display: none;
}
/* Move the site name to the left */
.md-header__title {
margin-left: 0;
font-weight: 500;
letter-spacing: 0.02em;
font-family: Lato, sans-serif;
}
.md-header__topic {
color: white;
font-size: 1.2rem;
line-height: 2.4rem;
margin-left: 0.6rem;
}
/* Badge styles for version/status indicators */
.md-typeset .md-badge {
border-radius: 4px;
display: inline-block;
font-size: 0.75em;
font-weight: 700;
padding: 4px 6px;
margin: 0 0.5em;
vertical-align: middle;
}
.md-typeset .md-badge--new {
background-color: #28a745;
color: white;
}
.md-typeset .md-badge--beta {
background-color: #f0ad4e;
color: white;
}
.md-typeset .md-badge--deprecated {
background-color: #dc3545;
color: white;
}
mkdocs/mkdocs.yml
+103 -10
View File
@@ -1,28 +1,51 @@
site_name: ionscale
repo_name: jsiebens/ionscale
repo_url: https://github.com/jsiebens/ionscale
edit_uri: ""
# Remove the GitHub repository link from the top-right corner
# repo_name: jsiebens/ionscale
# repo_url: https://github.com/jsiebens/ionscale
# edit_uri: ""
nav:
- Overview:
- Introduction: index.md
- Supported Features: overview/features.md
- Installation:
- Manual: ./getting-started/manual.md
- Docker: ./getting-started/docker.md
- 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:
- OIDC: ./configuration/auth-oidc.md
- DNS providers: ./configuration/dns-providers.md
- Reference: ./configuration/reference.md
theme:
name: material
custom_dir: overrides
# Custom stylesheets
extra_css:
- stylesheets/extra.css
# Explicitly disable the logo to show only the site name
#logo: ""
favicon: assets/favicon.png
# Enhanced color scheme
palette:
- scheme: default
- media: "(prefers-color-scheme: light)"
scheme: default
primary: indigo
accent: indigo
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
- scheme: slate
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: indigo
accent: indigo
toggle:
icon: material/toggle-switch
name: Switch to light mode
@@ -32,9 +55,28 @@ theme:
code: Roboto Mono
features:
# Navigation
- navigation.tracking
- navigation.sections
- toc.integrate
- navigation.indexes
- navigation.top # Back-to-top button
- navigation.footer # Footer with previous/next links
# Content
- content.code.copy # Add copy button to code blocks
- content.code.annotate # Allow code annotations
- content.tabs.link # Sync all tabs with the same label
# Search
- search.highlight
- search.share
- search.suggest
# Table of contents
- toc.follow
# Hide the table of contents on the navigation
toc_depth: 0
include_search_page: false
search_index_only: true
@@ -42,15 +84,66 @@ theme:
language: en
markdown_extensions:
# Admonitions and callouts
- admonition
- pymdownx.details
- pymdownx.superfences
# Code blocks with syntax highlighting
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
# Code annotations
- pymdownx.snippets
- pymdownx.superfences
# Tabbed content
- pymdownx.tabbed:
alternate_style: true
# Content tabs
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
# Better formatting options
- attr_list # Add HTML attributes and CSS classes
- def_list # Definition lists
- md_in_html # Markdown within HTML
- tables # Tables
- footnotes # Footnotes
# Typography improvements
- pymdownx.critic # Track changes
- pymdownx.caret # Superscript/subscript
- pymdownx.mark # Highlighting
- pymdownx.tilde # Strikethrough
- pymdownx.smartsymbols # Smart symbols (arrows, fractions)
extra:
# Page status annotations
status:
new: Recently added
deprecated: No longer supported
beta: Currently in beta
# Enhanced social cards
social:
- icon: fontawesome/brands/github
link: https://github.com/jsiebens/ionscale
- icon: fontawesome/brands/docker
link: https://github.com/jsiebens/ionscale/pkgs/container/ionscale
# Page customization
version:
provider: mike
# Footer customization
generator: false # Hide "Made with Material for MkDocs"
# Analytics (existing)
analytics:
provider: custom