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

update docs

Browse Source
This commit is contained in:
Johan Siebens
2025-04-28 13:27:08 +02:00
parent 776e3de7d8
commit 5b9da83c30
6 changed files with 290 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mkdocs/docs/configuration/reference.md
-117
View File
@@ -1,117 +0,0 @@
# Configuration Reference
__ionscale__ uses the YAML file format for configuration.
A full configuration reference file is shown below, this provides comments and all available options.
```yaml
# The HTTP(S) listen address to serve the control plane.
listen_addr: ":8080"
# The STUN listen address when using the embedded DERP.
stun_listen_addr: ":3478"
# The address to bind to for the metrics.
metrics_listen_addr: ":9091"
# The DNS name of the server HTTP(S) endpoint as accessible by clients and the CLI.
public_addr: "ionscale.example.com:443"
# The DNS name of the STUN endpoint as accessible by clients.
stun_public_addr: "ionscale.example.com:3478"
tls:
# Disable TLS (not recommended)
# Use this flag to disable TLS e.g. when running behind a reverse proxy
disable: false
# Redirect HTTP requests to HTTPS requests
force_https: true
# The path to the certificate for TLS.
# Required when TLS is enabled and ACME disabled
cert_file: ""
# The path to the private key for the certificate.
# Required when TLS is enabled and ACME disabled
key_file: ""
# Enable automatic TLS certificates provisioning with Let's Encrypt
acme: false
# An email address, used when creating an ACME account and keeping you up-to-date regarding your certificates
acme_email: ""
# The URL to the ACME CA's directory.
acme_ca: "https://acme-v02.api.letsencrypt.org/directory"
# Path to store certificates and metadata needed by ACME
acme_path: "./data"
database:
# Type of databas to use, supported values are sqlite or postgres
type: "sqlite"
# The URL for connecting to the database
# e.g
# url: "/data/ionscale.db?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)"
# url: "postgres://ionscale:ionscale@localhost/ionscale?sslmode=disable"
url: "./ionscale.db"
derp:
server:
disabled: false
region_id: 1000
region_code: "ionscale"
region_name: "ionscale Embedded DERP"
sources:
- https://controlplane.tailscale.com/derpmap/default
keys:
# A private, 32 bytes in hex, system admin key
# Use this key with the CLI when configuring system-wide resources like tailnets
# A key can be generated by:
# - ionscale genkey
# - openssl rand -hex 32
system_admin_key: ""
poll_net:
# Period to send keep alive messages to the connected devices
keep_alive_interval: "60s"
# Optional authentication configuration
auth:
# OIDC provider configuration
provider:
# OIDC issuer URL where ionscale can find the OpenID Provider Configuration Document
issuer: ""
# OIDC client id and secrets
client_id: ""
client_secret: ""
# additional OIDC scopes used in the OIDC flow
additional_scopes: ""
# IAM policy to mark some authenticated users as System Admin
system_admins:
# A list of emails of users that are System Admin
emails: []
# A list of ID (sub OIDC claim) of users that are System Admin
subs: []
# A list of BEXPR filters to mark authenticated users as System Admin
filters: []
dns:
# The base domain of the MagicDNS FQDN hostnames
magic_dns_suffix: "ionscale.net"
# A DNS provider for setting public TXT records
# This is a requirement to enable Tailscale HTTPS certs.
provider:
# name of your provider, currently supported implementations:
# - azure (https://github.com/libdns/azure)
# - cloudflare (https://github.com/libdns/cloudflare)
# - digitialocean (https://github.com/libdns/digitalocean)
# - googleclouddns (https://github.com/libdns/googleclouddns)
# - route53 (https://github.com/libdns/route53)
name: ""
# DNS zone
zone: ""
# Provider specific configuration
config: {}
logging:
# Output formatting for logs: text or json
format: "text"
level: "info"
# Path of a target log file, if omitted logs are written to stdout
file: ""
```
mkdocs/docs/getting-started/acl-policies.md
+123
View File
@@ -0,0 +1,123 @@
# 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 between devices.
## Understanding ACL policies
ACL policies in ionscale follow the same format and rules as Tailscale's ACL system. They allow you to control:
- Which devices can communicate with each other
- What ports and protocols are allowed
- Who can use exit nodes and other special features
- SSH access between machines
- Tag ownership and management
## Basic ACL structure
A basic ACL policy contains rules that specify which sources can access which destinations:
```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"]
}
}
```
In this example:
- Web servers (tagged `tag:web`) can only access database servers on port 5432
- Admins have full access to all resources
- Only admin@example.com can assign the web and database tags to machines
## Managing ACL policies
You can view and update the ACL policy for a tailnet using the ionscale CLI:
```bash
# View current ACL policy
ionscale acl get --tailnet "my-tailnet"
# Update ACL policy from a file
ionscale acl update --tailnet "my-tailnet" --file acl.json
```
!!! tip
ACL changes take effect immediately for all devices in the tailnet.
## Common ACL patterns
### Allow specific tags to communicate
```json
{
"acls": [
{"action": "accept", "src": ["tag:web"], "dst": ["tag:api:8080"]},
{"action": "accept", "src": ["tag:api"], "dst": ["tag:db:5432"]}
]
}
```
### Group-based access
```json
{
"acls": [
{"action": "accept", "src": ["group:developers"], "dst": ["tag:dev-env:*"]},
{"action": "accept", "src": ["group:ops"], "dst": ["*:*"]}
],
"groups": {
"developers": ["alice@example.com", "bob@example.com"],
"ops": ["charlie@example.com", "diana@example.com"]
}
}
```
### SSH access control
```json
{
"ssh": [
{
"action": "accept",
"src": ["group:admins"],
"dst": ["tag:server"],
"users": ["root"]
},
{
"action": "accept",
"src": ["group:developers"],
"dst": ["tag:dev"],
"users": ["autogroup:nonroot"]
}
]
}
```
### Auto-approving advertised routes
```json
{
"autoApprovers": {
"routes": {
"10.0.0.0/24": ["group:network-admins"],
"192.168.1.0/24": ["user@example.com"]
},
"exitNode": ["group:network-admins"]
}
}
```
## Additional resources
For more detailed information on ACL syntax and capabilities, see the [Tailscale ACL documentation](https://tailscale.com/kb/1018/acls/).
!!! note "Feature support"
Not all ACL features from the official Tailscale control plane are supported in ionscale. Some advanced features or newer functionality may not be available.
mkdocs/docs/getting-started/iam-policies.md
+159
View File
@@ -0,0 +1,159 @@
# IAM Policies
Identity and Access Management (IAM) policies in ionscale control who can access a tailnet and what administrative permissions they have.
!!! 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.
## Understanding IAM policies
IAM policies determine:
- Which users can join a tailnet
- What roles and permissions users have within the tailnet
- How access decisions are made based on user attributes
An IAM policy consists of:
```json
{
"subs": ["auth0|123456789"],
"filters": ["domain == example.com"],
"emails": ["specific-user@otherdomain.com"],
"roles": {
"admin@example.com": "admin"
}
}
```
## IAM policy components
### Subs
The `subs` list provides direct access based on user IDs (subjects):
```json
"subs": ["auth0|123456789", "google-oauth2|12345"]
```
Any user whose ID matches an entry in this list will be granted access to the tailnet. User IDs are typically provided by the OIDC provider and are unique identifiers for each user.
### Emails
The `emails` list provides direct access to specific email addresses:
```json
"emails": ["alice@example.com", "bob@otherdomain.com"]
```
Any user with an email in this list will be granted access to the tailnet, regardless of filters.
### Filters
Filters are expressions that evaluate user attributes:
```json
"filters": ["domain == example.com", "email.endsWith('@engineering.example.com')"]
```
These expressions determine if a user can access the tailnet based on their identity attributes. Users matching any filter expression will be granted access.
### Roles
The `roles` map assigns specific roles to users:
```json
"roles": {
"admin@example.com": "admin",
"devops@example.com": "admin",
"developer@example.com": "member"
}
```
Available roles:
- `admin`: Can manage tailnet settings, ACLs, and auth keys
- `member`: Standard access to use the tailnet (default)
## Managing IAM policies
View and update IAM policies using the ionscale CLI:
```bash
# View current IAM policy
ionscale iam get-policy --tailnet "my-tailnet"
# Update IAM policy using a JSON file
ionscale iam update-policy --tailnet "my-tailnet" --file policy.json
```
## Common IAM patterns
### Domain-based tailnet
Grant access to everyone with the same email domain:
```json
{
"filters": ["domain == example.com"],
"roles": {
"admin1@example.com": "admin",
"admin2@example.com": "admin"
}
}
```
### Personal tailnet
Create a tailnet for individual use:
```json
{
"emails": ["personal@example.com"],
"roles": {
"personal@example.com": "admin"
}
}
```
## Setting IAM during tailnet creation
You can set basic IAM policies during tailnet creation with CLI flags:
```bash
# Allow all users with an @example.com email address
ionscale tailnet create --name "shared-tailnet" --domain "example.com"
# Allow only a specific user
ionscale tailnet create --name "personal-tailnet" --email "user@example.com"
```
These shortcuts create appropriate filter rules or email entries in the IAM policy.
## IAM policy evaluation
When a user attempts to access a tailnet, the following checks occur:
1. Is the user's ID in the `subs` list? If yes, grant access.
2. Is the user's email in the `emails` list? If yes, grant access.
3. Does the user match any expression in the `filters` list? If yes, grant access.
4. If none of these conditions are met, access is denied.
For role determination:
1. Check if the user has an entry in the `roles` map
2. If yes, assign that role
3. If no, assign the default `member` role
## Security considerations
- **Principle of least privilege**: Start with minimal access and add users or filters as needed
- **Regular audits**: Periodically review IAM policies to ensure only appropriate users have access
- **Admin roles**: Limit admin roles to trusted users who need to manage tailnet settings
## Troubleshooting access issues
If a user is having trouble accessing a tailnet:
1. Verify the user's email is correct and matches their OIDC identity
2. Check filter expressions to ensure they match the user's attributes
3. Verify the user is authenticating against the correct ionscale instance
4. Check OIDC provider configuration and token issuance
mkdocs/docs/getting-started/index.md
+1 -7
View File
@@ -75,10 +75,4 @@ 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/tailnet.md
+5 -29
View File
@@ -126,39 +126,15 @@ 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
## Network access and security 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.
By default, tailnets are created with an open policy that allows all connections between devices. For production environments, you'll want to configure:
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"]
}
}
```
- **[IAM Policies](iam-policies.md)**: Manage who can access your tailnet
- **[ACL Policies](acl-policies.md)**: Control which devices can communicate within your tailnet
!!! 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/).
For detailed information on configuring security policies, see the dedicated documentation sections on [IAM Policies](iam-policies.md) and [ACL Policies](acl-policies.md).
## Managing multiple tailnets
mkdocs/mkdocs.yml
+2
View File
@@ -21,6 +21,8 @@ nav:
- Getting started:
- Getting started: ./getting-started/index.md
- Creating a tailnet: ./getting-started/tailnet.md
- IAM Policies: ./getting-started/iam-policies.md
- ACL Policies: ./getting-started/acl-policies.md
theme:
name: material