ionscale

ionscale is an open-source, lightweight alternative to the centralized Tailscale coordination server. While Tailscale nodes are open source, their coordination server (which manages public keys and device connectivity) is proprietary. ionscale implements a compatible control server to enable encrypted point-to-point connections using the WireGuard protocol for your private network.

Note: ionscale is currently in beta and is actively being developed, so its API and behavior are subject to change.

IAM policies in ionscale control tailnet access and user permissions. They are only active when an OIDC provider is configured. An IAM policy is composed of four main components:

• subs: A list of unique user IDs (subjects) provided by the OIDC provider (e.g., auth0|123456789). Matching a subject grants direct access.
• emails: A list of specific email addresses that grant direct access, bypassing filters.
• filters: Expressions that evaluate user attributes (e.g., domain == example.com). Users matching any filter expression are granted access.
• roles: A map assigning specific roles to users. If a user is not explicitly assigned a role in this map, they are assigned the default member role.

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

You can reference environment variables directly within your YAML configuration files using the following syntax:

• ${VAR}: Required variable. If the environment variable is missing, configuration loading will fail.
• ${VAR:default}: Variable with a default value. If the environment variable is missing, the provided default is used.

Example:

database:
  type: ${DB_TYPE:sqlite}
  url: ${DB_URL}
  max_open_conns: ${DB_MAX_OPEN_CONns:10}

An ACL policy is defined using a JSON structure containing acls, groups, and tagOwners.

• acls: An array of rules specifying an action (e.g., accept), a source (src), and a destination (dst). Destinations can include specific ports (e.g., tag:db:5432).
• groups: A mapping of group names to lists of users.
• tagOwners: A mapping of tags to the users authorized to assign those tags to machines.

{
  "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"]
  }
}

ionscale includes several DNS management capabilities:

• MagicDNS: Provides automatic DNS for all devices within a tailnet.
• Split DNS: Allows routing specific DNS queries to designated resolvers.
• Custom nameservers: Enables configuration of any DNS servers for your tailnet.

When a user attempts to access a tailnet, ionscale performs checks in a specific order to determine access and roles.

Access Decision Order:

1. Subject Check: Is the user's ID in the subs list? If yes, access is granted.
2. Email Check: Is the user's email in the emails list? If yes, access is granted.
3. Filter Check: Does the user match any expression in the filters list? If yes, access is granted.
4. Deny: If none of the above match, access is denied.

Role Determination Order:

1. Check if the user has an entry in the roles map.
2. If yes, assign that specific role.
3. If no, assign the default member role.

ionscale provides several features compatible with the Tailscale ecosystem, including:

• Multi-tailnet & Multi-user support: Manage multiple networks and users.
• OIDC Integration: Recommended for secure authentication.
• Auth keys: Support for Tailscale-style authentication keys.
• Access Control Lists (ACLs): Supports advanced features like autogroups, tagOwners, autoApprovers, nodeAttrs, and grants.
• DNS Capabilities: Includes nameservers, Split DNS, and MagicDNS.
• Network Routing: Support for Subnet routers and Exit Nodes.
• Tailscale Features: Support for HTTPS Certs, Tailscale SSH, Tailscale Serve, Service collection, and Taildrop.

Access Control Lists (ACLs) in ionscale define network access permissions within a tailnet. By default, tailnets are created with an open policy allowing all connections. ionscale ACLs follow the same format and rules as Tailscale's ACL system, allowing you to control:

• Device-to-device communication
• Allowed ports and protocols
• Usage of exit nodes and other special features
• SSH access between machines
• Tag ownership and management

You can manage how traffic flows through your tailnet using the following features:

• Access control lists (ACLs): Define fine-grained rules for network access permissions.
• Subnet routers: Connect existing physical or virtual networks to your tailnet.
• Exit nodes: Configure specific nodes to act as VPN exit points for tailnet traffic.

ionscale implements core connectivity and remote access features:

• Tailscale SSH: Built-in SSH server support with SSH policy management to control which users can access which devices.
• DERP: Includes an embedded DERP server and supports custom DERP maps for configuring your own DERP servers.

ionscale provides tools for managing users and device access:

• Multi-user support: Enables multiple users to access the same tailnet based on defined permissions.
• OIDC integration: Supports OpenID Connect (OIDC) for user authentication and management (recommended).
• Auth keys: Generate and manage pre-authentication keys for device onboarding.
• Device tagging: Apply tags to devices to facilitate management and ACL control.