chore: v0.3.1

No longer required if the minimum is beta2

CHANGELOG.md

@@ -1,3 +1,30 @@
+### 0.3.1 (October 3, 2024)
+- Fixed the Docker integration to properly support custom socket paths. This regressed at some point previously.
+- Allow you to register a machine using machine keys (`nodekey:...`) on the machines page.
+- Added the option for debug logs with the `DEBUG=true` environment variable.
+
+### 0.3.0 (September 25, 2024)
+- Bumped the minimum supported version of Headscale to 0.23.
+- Updated the UI to respect `dns.use_username_in_magic_dns`.
+
+### 0.2.4 (August 24, 2024)
+- Removed ACL management from the integration since Headscale 0.23-beta2 now supports it natively.
+- Removed the `ACL_FILE` environment variable since it's no longer needed.
+- Introduce a `COOKIE_SECURE=false` environment variable to disable HTTPS requirements for cookies.
+- Fixed a bug where removing Split DNS configurations would crash the UI.
+
+### 0.2.3 (August 23, 2024)
+- Change the minimum required version of Headscale to 0.23-beta2
+- Support the new API policy mode for Headscale 0.23-beta1
+- Switch to the new DNS configuration in Headscale 0.23-beta2 (fixes [#29](https://github.com/tale/headplane/issues/29))
+- If OIDC environment variables are defined, don't use configuration file values (fixes [#24](https://github.com/tale/headplane/issues/24))
+
+### 0.2.2 (August 2, 2024)
+- Added a proper Kubernetes integration which utilizes `shareProcessNamespace` for PIDs.
+- Added a new logger utility that shows categories, levels, and timestamps.
+- Reimplemented the integration system to be more resilient and log more information.
+- Fixed an issue where the /proc integration found `undefined` PIDs.
+
 ### 0.2.1 (July 7, 2024)
 - Added the ability to manage custom DNS records on your Tailnet.
 - ACL tags for machines are now able to be changed via the machine menu.

app/components/Header.tsx

@@ -10,7 +10,6 @@ import TabLink from './TabLink'
 
 interface Properties {
 	readonly data?: {
-		acl: HeadplaneContext['acl']
 		config: HeadplaneContext['config']
 		user?: SessionData['user']
 	}
@@ -102,11 +101,7 @@ export default function Header({ data }: Properties) {
 			<nav className="container flex items-center gap-x-4 overflow-x-auto">
 				<TabLink to="/machines" name="Machines" icon={<ServerIcon className="w-4 h-4" />} />
 				<TabLink to="/users" name="Users" icon={<PeopleIcon className="w-4 h-4" />} />
-				{data?.acl.read
-					? (
-						<TabLink to="/acls" name="Access Control" icon={<LockIcon className="w-4 h-4" />} />
-						)
-					: undefined}
+				<TabLink to="/acls" name="Access Control" icon={<LockIcon className="w-4 h-4" />} />
 				{data?.config.read
 					? (
 						<>

app/components/Notice.tsx

@@ -1,15 +1,22 @@
 import { InfoIcon } from '@primer/octicons-react'
-import clsx from 'clsx'
-import { type ReactNode } from 'react'
+import type { ReactNode } from 'react'
 
-export default function Notice({ children }: { readonly children: ReactNode }) {
+import { cn } from '~/utils/cn'
+
+interface Props {
+	className?: string
+	children: ReactNode
+}
+
+export default function Notice({ children, className }: Props) {
 	return (
-		<div className={clsx(
-			'p-4 rounded-md w-fit flex items-center gap-3',
-			'bg-slate-400 dark:bg-slate-700'
+		<div className={cn(
+			'p-4 rounded-md w-full flex items-center gap-3',
+			'bg-ui-200 dark:bg-ui-800',
+			className,
 		)}
 		>
-			<InfoIcon className='h-6 w-6 text-white'/>
+			<InfoIcon className="h-6 w-6 text-ui-700 dark:text-ui-200" />
 			{children}
 		</div>
 	)

app/integration/docker.ts

@@ -4,124 +4,153 @@ import { setTimeout } from 'node:timers/promises'
 import { Client } from 'undici'
 
 import { HeadscaleError, pull } from '~/utils/headscale'
+import log from '~/utils/log'
 
-import type { Integration } from '.'
+import { createIntegration } from './integration'
 
-// Integration name
-const name = 'Docker'
-
-let url: URL | undefined
-let container: string | undefined
-
-async function preflight() {
-	const path = process.env.DOCKER_SOCK ?? 'unix:///var/run/docker.sock'
-
-	try {
-		url = new URL(path)
-	} catch {
-		return false
-	}
-
-	// The API is available as an HTTP endpoint
-	if (url.protocol === 'tcp:') {
-		url.protocol = 'http:'
-	}
-
-	// Check if the socket is accessible
-	if (url.protocol === 'unix:') {
-		try {
-			await access(path, constants.R_OK)
-		} catch {
-			return false
-		}
-	}
-
-	if (url.protocol === 'http:') {
-		try {
-			await fetch(new URL('/v1.30/version', url).href)
-		} catch {
-			return false
-		}
-	}
-
-	if (url.protocol !== 'http:' && url.protocol !== 'unix:') {
-		return false
-	}
-
-	container = process.env.HEADSCALE_CONTAINER
-		?.trim()
-		.toLowerCase()
-
-	if (!container || container.length === 0) {
-		return false
-	}
-
-	return true
+interface Context {
+	client: Client | undefined
+	container: string | undefined
+	maxAttempts: number
 }
 
-async function sighup() {
-	if (!url || !container) {
-		return
-	}
+export default createIntegration<Context>({
+	name: 'Docker',
+	context: {
+		client: undefined,
+		container: undefined,
+		maxAttempts: 10,
+	},
+	isAvailable: async (context) => {
+		// Check for the HEADSCALE_CONTAINER environment variable first
+		// to avoid unnecessary fetching of the Docker socket
+		log.debug('INTG', 'Checking Docker integration availability')
+		context.container = process.env.HEADSCALE_CONTAINER
+			?.trim()
+			.toLowerCase()
 
-	// Supports the DOCKER_SOCK environment variable
-	const client = url.protocol === 'unix:'
-		? new Client('http://localhost', {
-			socketPath: url.href,
-		})
-		: new Client(url.href)
+		if (!context.container || context.container.length === 0) {
+			log.error('INTG', 'Missing HEADSCALE_CONTAINER variable')
+			return false
+		}
 
-	const response = await client.request({
-		method: 'POST',
-		path: `/v1.30/containers/${container}/kill?signal=SIGHUP`,
-	})
+		log.info('INTG', 'Using container: %s', context.container)
+		const path = process.env.DOCKER_SOCK ?? 'unix:///var/run/docker.sock'
+		let url: URL | undefined
 
-	if (!response.statusCode || response.statusCode !== 204) {
-		throw new Error('Failed to send SIGHUP to Headscale')
-	}
-}
-
-async function restart() {
-	if (!url || !container) {
-		return
-	}
-
-	// Supports the DOCKER_SOCK environment variable
-	const client = url.protocol === 'unix:'
-		? new Client('http://localhost', {
-			socketPath: url.href,
-		})
-		: new Client(url.href)
-
-	const response = await client.request({
-		method: 'POST',
-		path: `/v1.30/containers/${container}/restart`,
-	})
-
-	if (!response.statusCode || response.statusCode !== 204) {
-		throw new Error('Failed to restart Headscale')
-	}
-
-	// Wait for Headscale to restart before continuing
-	let attempts = 0
-	// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition, no-constant-condition
-	while (true) {
 		try {
-			await pull('v1', '')
+			url = new URL(path)
+		} catch {
+			log.error('INTG', 'Invalid Docker socket path: %s', path)
+			return false
+		}
+
+		if (url.protocol !== 'tcp:' && url.protocol !== 'unix:') {
+			log.error('INTG', 'Invalid Docker socket protocol: %s',
+				url.protocol,
+			)
+			return false
+		}
+
+		// The API is available as an HTTP endpoint and this
+		// will simplify the fetching logic in undici
+		if (url.protocol === 'tcp:') {
+			// Apparently setting url.protocol doesn't work anymore?
+			const fetchU = url.href.replace(url.protocol, 'http:')
+
+			try {
+				log.info('INTG', 'Checking API: %s', fetchU)
+				await fetch(new URL('/v1.30/version', fetchU).href)
+			} catch (error) {
+				log.debug('INTG', 'Failed to connect to Docker API', error)
+				log.error('INTG', 'Failed to connect to Docker API')
+				return false
+			}
+
+			context.client = new Client(fetchU)
+		}
+
+		// Check if the socket is accessible
+		if (url.protocol === 'unix:') {
+			try {
+				log.info('INTG', 'Checking socket: %s',
+					url.pathname,
+				)
+				await access(url.pathname, constants.R_OK)
+			} catch (error) {
+				log.debug('INTG', 'Failed to access Docker socket: %s', error)
+				log.error('INTG', 'Failed to access Docker socket: %s',
+					path,
+				)
+				return false
+			}
+
+			context.client = new Client('http://localhost', {
+				socketPath: url.pathname,
+			})
+		}
+
+		return context.client !== undefined
+	},
+
+	onConfigChange: async (context) => {
+		if (!context.client || !context.container) {
 			return
-		} catch (error) {
-			if (error instanceof HeadscaleError && error.status === 401) {
-				break
-			}
-
-			if (attempts > 10) {
-				throw new Error('Headscale did not restart in time')
-			}
-
-			attempts++
-			await setTimeout(1000)
 		}
-	}
-}
 
-export default { name, preflight, sighup, restart } satisfies Integration
+		log.info('INTG', 'Restarting Headscale via Docker')
+
+		let attempts = 0
+		while (attempts <= context.maxAttempts) {
+			log.debug(
+				'INTG', 'Restarting container: %s (attempt %d)',
+				context.container,
+				attempts,
+			)
+
+			const response = await context.client.request({
+				method: 'POST',
+				path: `/v1.30/containers/${context.container}/restart`,
+			})
+
+			if (response.statusCode !== 204) {
+				if (attempts < context.maxAttempts) {
+					attempts++
+					await setTimeout(1000)
+					continue
+				}
+
+				const stringCode = response.statusCode.toString()
+				const body = await response.body.text()
+				throw new Error(`API request failed: ${stringCode} ${body}`)
+			}
+
+			break
+		}
+
+		attempts = 0
+		while (attempts <= context.maxAttempts) {
+			try {
+				log.debug('INTG', 'Checking Headscale status (attempt %d)', attempts)
+				await pull('v1', '')
+				return
+			} catch (error) {
+				if (error instanceof HeadscaleError && error.status === 401) {
+					break
+				}
+
+				if (error instanceof HeadscaleError && error.status === 404) {
+					break
+				}
+
+				if (attempts < context.maxAttempts) {
+					attempts++
+					await setTimeout(1000)
+					continue
+				}
+
+				throw new Error(`Missed restart deadline for ${context.container}`)
+			}
+		}
+	},
+})

app/integration/index.ts

@@ -1,58 +1,75 @@
-import docker from './docker'
-import proc from './proc'
+import log from '~/utils/log'
 
-export interface Integration {
-	name: string
-	preflight: () => Promise<boolean>
-	sighup?: () => Promise<void>
-	restart?: () => Promise<void>
-}
+import dockerIntegration from './docker'
+import { IntegrationFactory } from './integration'
+import kubernetesIntegration from './kubernetes'
+import procIntegration from './proc'
 
-// Because we previously supported the Docker integration by
-// checking for the HEADSCALE_CONTAINER variable, we need to
-// check for it here as well.
-//
-// This ensures that when people upgrade from older versions
-// of Headplane, they don't explicitly need to define the new
-// HEADSCALE_INTEGRATION variable that is needed to configure
-// an integration.
-export async function checkIntegration() {
+export * from './integration'
+
+export async function loadIntegration() {
 	let integration = process.env.HEADSCALE_INTEGRATION
 		?.trim()
 		.toLowerCase()
 
 	// Old HEADSCALE_CONTAINER variable upgrade path
+	// This ensures that when people upgrade from older versions of Headplane
+	// they don't explicitly need to define the new HEADSCALE_INTEGRATION
+	// variable that is needed to configure docker
 	if (!integration && process.env.HEADSCALE_CONTAINER) {
 		integration = 'docker'
 	}
 
 	if (!integration) {
-		console.log('Running Headplane without any integrations')
+		log.info('INTG', 'No integration set with HEADSCALE_INTEGRATION')
 		return
 	}
 
-	let module: Integration | undefined
-	try {
-		module = getIntegration(integration)
-		await module.preflight()
-	} catch (error) {
-		console.error('Failed to load integration', error)
-		return
-	}
-
-	return module
-}
-
-function getIntegration(name: string) {
-	switch (name) {
+	let integrationFactory: IntegrationFactory | undefined
+	switch (integration.toLowerCase().trim()) {
 		case 'docker': {
-			return docker
+			integrationFactory = dockerIntegration
+			break
 		}
-		case 'proc': {
-			return proc
+
+		case 'proc':
+		case 'native':
+		case 'linux': {
+			integrationFactory = procIntegration
+			break
 		}
+
+		case 'kubernetes':
+		case 'k8s': {
+			integrationFactory = kubernetesIntegration
+			break
+		}
+
 		default: {
-			throw new Error(`Unknown integration: ${name}`)
+			log.error('INTG', 'Unknown integration: %s', integration)
+			throw new Error(`Unknown integration: ${integration}`)
 		}
 	}
+
+	log.info('INTG', 'Loading integration: %s', integration)
+	try {
+		const res = await integrationFactory.isAvailable(
+			integrationFactory.context,
+		)
+		if (!res) {
+			log.error('INTG', 'Integration %s is not available',
+				integration,
+			)
+			return
+		}
+	} catch (error) {
+		log.error('INTG', 'Failed to load integration %s: %s',
+			integration,
+			error,
+		)
+		return
+	}
+
+	log.info('INTG', 'Loaded integration: %s', integration)
+	return integrationFactory
 }

app/integration/integration.ts

@@ -0,0 +1,13 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface IntegrationFactory<T = any> {
+	name: string
+	context: T
+	isAvailable: (context: T) => Promise<boolean> | boolean
+	onConfigChange?: (context: T) => Promise<void> | void
+}
+
+export function createIntegration<T>(
+	options: IntegrationFactory<T>,
+) {
+	return options
+}

app/integration/kubernetes.ts

@@ -0,0 +1,204 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { platform } from 'node:os'
+import { join, resolve } from 'node:path'
+import { kill } from 'node:process'
+
+import { Config, CoreV1Api, KubeConfig } from '@kubernetes/client-node'
+
+import log from '~/utils/log'
+
+import { createIntegration } from './integration'
+
+interface Context {
+	pid: number | undefined
+}
+
+export default createIntegration<Context>({
+	name: 'Kubernetes (k8s)',
+	context: {
+		pid: undefined,
+	},
+	isAvailable: async (context) => {
+		if (platform() !== 'linux') {
+			log.error('INTG', 'Kubernetes is only available on Linux')
+			return false
+		}
+
+		const svcRoot = Config.SERVICEACCOUNT_ROOT
+		try {
+			log.debug('INTG', 'Checking Kubernetes service account at %s', svcRoot)
+			const files = await readdir(svcRoot)
+			if (files.length === 0) {
+				log.error('INTG', 'Kubernetes service account not found')
+				return false
+			}
+
+			const mappedFiles = new Set(files.map(file => join(svcRoot, file)))
+			const expectedFiles = [
+				Config.SERVICEACCOUNT_CA_PATH,
+				Config.SERVICEACCOUNT_TOKEN_PATH,
+				Config.SERVICEACCOUNT_NAMESPACE_PATH,
+			]
+
+			log.debug('INTG', 'Looking for %s', expectedFiles.join(', '))
+			if (!expectedFiles.every(file => mappedFiles.has(file))) {
+				log.error('INTG', 'Malformed Kubernetes service account')
+				return false
+			}
+		} catch (error) {
+			log.error('INTG', 'Failed to access %s: %s', svcRoot, error)
+			return false
+		}
+
+		log.debug('INTG', 'Reading Kubernetes service account at %s', svcRoot)
+		const namespace = await readFile(
+			Config.SERVICEACCOUNT_NAMESPACE_PATH,
+			'utf8',
+		)
+
+		// Some very ugly nesting but it's necessary
+		if (process.env.HEADSCALE_INTEGRATION_UNSTRICT === 'true') {
+			log.warn('INTG', 'Skipping strict Pod status check')
+		} else {
+			const pod = process.env.POD_NAME
+			if (!pod) {
+				log.error('INTG', 'Missing POD_NAME variable')
+				return false
+			}
+
+			if (pod.trim().length === 0) {
+				log.error('INTG', 'Pod name is empty')
+				return false
+			}
+
+			log.debug('INTG', 'Checking Kubernetes pod %s in namespace %s',
+				pod,
+				namespace,
+			)
+
+			try {
+				log.debug('INTG', 'Attempgin to get cluster KubeConfig')
+				const kc = new KubeConfig()
+				kc.loadFromCluster()
+
+				const cluster = kc.getCurrentCluster()
+				if (!cluster) {
+					log.error('INTG', 'Malformed kubeconfig')
+					return false
+				}
+
+				log.info('INTG', 'Service account connected to %s (%s)',
+					cluster.name,
+					cluster.server,
+				)
+
+				const kCoreV1Api = kc.makeApiClient(CoreV1Api)
+
+				log.info('INTG', 'Checking pod %s in namespace %s (%s)',
+					pod,
+					namespace,
+					kCoreV1Api.basePath,
+				)
+
+				log.debug('INTG', 'Reading pod info for %s', pod)
+				const { response, body } = await kCoreV1Api.readNamespacedPod(
+					pod,
+					namespace,
+				)
+
+				if (response.statusCode !== 200) {
+					log.error('INTG', 'Failed to read pod info: http %d',
+						response.statusCode,
+					)
+					return false
+				}
+
+				log.debug('INTG', 'Got pod info: %o', body.spec)
+				const shared = body.spec?.shareProcessNamespace
+				if (shared === undefined) {
+					log.error(
+						'INTG',
+						'Pod does not have spec.shareProcessNamespace set',
+					)
+					return false
+				}
+
+				if (!shared) {
+					log.error(
+						'INTG',
+						'Pod has set but disabled spec.shareProcessNamespace',
+					)
+					return false
+				}
+
+				log.info('INTG', 'Pod %s enabled shared processes', pod)
+			} catch (error) {
+				log.error('INTG', 'Failed to read pod info: %s', error)
+				return false
+			}
+		}
+
+		log.debug('INTG', 'Looking for namespaced process in /proc')
+		const dir = resolve('/proc')
+		try {
+			const subdirs = await readdir(dir)
+			const promises = subdirs.map(async (dir) => {
+				const pid = Number.parseInt(dir, 10)
+
+				if (Number.isNaN(pid)) {
+					return
+				}
+
+				const path = join('/proc', dir, 'cmdline')
+				try {
+					log.debug('INTG', 'Reading %s', path)
+					const data = await readFile(path, 'utf8')
+					if (data.includes('headscale')) {
+						return pid
+					}
+				} catch (error) {
+					log.debug('INTG', 'Failed to read %s: %s', path, error)
+				}
+			})
+
+			const results = await Promise.allSettled(promises)
+			const pids = []
+
+			for (const result of results) {
+				if (result.status === 'fulfilled' && result.value) {
+					pids.push(result.value)
+				}
+			}
+
+			log.debug('INTG', 'Found Headscale processes: %o', pids)
+			if (pids.length > 1) {
+				log.error('INTG', 'Found %d Headscale processes: %s',
+					pids.length,
+					pids.join(', '),
+				)
+				return false
+			}
+
+			if (pids.length === 0) {
+				log.error('INTG', 'Could not find Headscale process')
+				return false
+			}
+
+			context.pid = pids[0]
+			log.info('INTG', 'Found Headscale process with PID: %d', context.pid)
+			return true
+		} catch {
+			log.error('INTG', 'Failed to read /proc')
+			return false
+		}
+	},
+
+	onConfigChange: (context) => {
+		if (!context.pid) {
+			return
+		}
+
+		log.info('INTG', 'Sending SIGTERM to Headscale')
+		kill(context.pid, 'SIGTERM')
+	},
+})

app/integration/proc.ts

@@ -1,83 +1,79 @@
-import { access, constants, readdir, readFile } from 'node:fs/promises'
+import { readdir, readFile } from 'node:fs/promises'
 import { platform } from 'node:os'
 import { join, resolve } from 'node:path'
 import { kill } from 'node:process'
 
-import type { Integration } from '.'
+import log from '~/utils/log'
 
-// Integration name
-const name = 'Native Linux (/proc)'
+import { createIntegration } from './integration'
 
-// Check if we have a /proc and if it's readable
-async function preflight() {
-	if (platform() !== 'linux') {
-		return false
-	}
-
-	const dir = resolve('/proc')
-	try {
-		await access(dir, constants.R_OK)
-		return true
-	} catch (error) {
-		console.error('Failed to access /proc', error)
-		return false
-	}
+interface Context {
+	pid: number | undefined
 }
 
-async function findPid() {
-	const dirs = await readdir('/proc')
-
-	const promises = dirs.map(async (dir) => {
-		const pid = Number.parseInt(dir, 10)
-
-		if (Number.isNaN(pid)) {
-			return
+export default createIntegration<Context>({
+	name: 'Native Linux (/proc)',
+	context: {
+		pid: undefined,
+	},
+	isAvailable: async (context) => {
+		if (platform() !== 'linux') {
+			log.error('INTG', '/proc is only available on Linux')
+			return false
 		}
 
-		const path = join('/proc', dir, 'cmdline')
+		log.debug('INTG', 'Checking /proc for Headscale process')
+		const dir = resolve('/proc')
 		try {
-			const data = await readFile(path, 'utf8')
-			if (data.includes('headscale')) {
-				return pid
+			const subdirs = await readdir(dir)
+			const promises = subdirs.map(async (dir) => {
+				const pid = Number.parseInt(dir, 10)
+
+				if (Number.isNaN(pid)) {
+					return
+				}
+
+				const path = join('/proc', dir, 'cmdline')
+				try {
+					log.debug('INTG', 'Reading %s', path)
+					const data = await readFile(path, 'utf8')
+					if (data.includes('headscale')) {
+						return pid
+					}
+				} catch (error) {
+					log.error('INTG', 'Failed to read %s: %s', path, error)
+				}
+			})
+
+			const results = await Promise.allSettled(promises)
+			const pids = []
+
+			for (const result of results) {
+				if (result.status === 'fulfilled' && result.value) {
+					pids.push(result.value)
+				}
 			}
-		} catch {}
-	})
 
-	const results = await Promise.allSettled(promises)
-	const pids = []
+			log.debug('INTG', 'Found Headscale processes: %o', pids)
+			if (pids.length > 1) {
+				log.error('INTG', 'Found %d Headscale processes: %s',
+					pids.length,
+					pids.join(', '),
+				)
+				return false
+			}
 
-	for (const result of results) {
-		if (result.status === 'fulfilled') {
-			pids.push(result.value)
+			if (pids.length === 0) {
+				log.error('INTG', 'Could not find Headscale process')
+				return false
+			}
+
+			context.pid = pids[0]
+			log.info('INTG', 'Found Headscale process with PID: %d', context.pid)
+			return true
+		} catch {
+			log.error('INTG', 'Failed to read /proc')
+			return false
 		}
 	}
-
-	if (pids.length > 1) {
-		console.warn('Found multiple Headscale processes', pids)
-		console.log('Disabling the /proc integration')
-		return
-	}
-
-	if (pids.length === 0) {
-		console.warn('Could not find Headscale process')
-		console.log('Disabling the /proc integration')
-		return
-	}
-
-	return pids[0]
-}
-
-async function sighup() {
-	const pid = await findPid()
-	if (!pid) {
-		return
-	}
-
-	try {
-		kill(pid, 'SIGHUP')
-	} catch (error) {
-		console.error('Failed to send SIGHUP to Headscale', error)
-	}
-}
-
-export default { name, preflight, sighup } satisfies Integration
+})

app/routes/_data.acls._index/editor.tsx

@@ -5,12 +5,12 @@ import { ClientOnly } from 'remix-utils/client-only'
 import Fallback from '~/routes/_data.acls._index/fallback'
 import { cn } from '~/utils/cn'
 
-interface MonacoProps {
-	variant: 'editor' | 'diff'
+interface Props {
+	variant: 'edit' | 'diff'
 	language: 'json' | 'yaml'
-	value: string
-	onChange: (value: string) => void
-	original?: string
+	state: [string, (value: string) => void]
+	policy?: string
+	isDisabled?: boolean
 }
 
 function monacoCallback(monaco: Monaco) {
@@ -26,7 +26,7 @@ function monacoCallback(monaco: Monaco) {
 	monaco.languages.register({ id: 'yaml' })
 }
 
-export default function MonacoEditor({ value, onChange, variant, original, language }: MonacoProps) {
+export default function MonacoEditor({ variant, language, state, policy, isDisabled }: Props) {
 	const [light, setLight] = useState(false)
 
 	useEffect(() => {
@@ -46,29 +46,30 @@ export default function MonacoEditor({ value, onChange, variant, original, langu
 			)}
 			>
 				<div className="overflow-y-scroll h-editor text-sm">
-					<ClientOnly fallback={<Fallback acl={value} />}>
-						{() => variant === 'editor'
+					<ClientOnly fallback={<Fallback acl={state[0]} />}>
+						{() => variant === 'edit'
 							? (
 								<Editor
 									height="100%"
 									language={language}
 									theme={light ? 'light' : 'vs-dark'}
-									value={value}
+									value={state[0]}
 									onChange={(updated) => {
 										if (!updated) {
 											return
 										}
 
-										if (updated !== value) {
-											onChange(updated)
+										if (updated !== state[0]) {
+											state[1](updated)
 										}
 									}}
-									loading={<Fallback acl={value} />}
+									loading={<Fallback acl={state[0]} />}
 									beforeMount={monacoCallback}
 									options={{
 										wordWrap: 'on',
 										minimap: { enabled: false },
 										fontSize: 14,
+										readOnly: isDisabled,
 									}}
 								/>
 								)
@@ -77,14 +78,15 @@ export default function MonacoEditor({ value, onChange, variant, original, langu
 									height="100%"
 									language={language}
 									theme={light ? 'light' : 'vs-dark'}
-									original={original}
-									modified={value}
-									loading={<Fallback acl={value} />}
+									original={policy}
+									modified={state[0]}
+									loading={<Fallback acl={state[0]} />}
 									beforeMount={monacoCallback}
 									options={{
 										wordWrap: 'on',
 										minimap: { enabled: false },
 										fontSize: 13,
+										readOnly: isDisabled,
 									}}
 								/>
 								)}

app/routes/_data.acls._index/route.tsx

@@ -1,32 +1,65 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
 import { BeakerIcon, EyeIcon, IssueDraftIcon, PencilIcon } from '@primer/octicons-react'
-import { type ActionFunctionArgs, json } from '@remix-run/node'
+import { ActionFunctionArgs, json, LoaderFunctionArgs } from '@remix-run/node'
 import { useFetcher, useLoaderData } from '@remix-run/react'
-import { useState } from 'react'
+import { useEffect, useState } from 'react'
 import { Tab, TabList, TabPanel, Tabs } from 'react-aria-components'
+import { setTimeout } from 'node:timers/promises'
 
 import Button from '~/components/Button'
+import Code from '~/components/Code'
 import Link from '~/components/Link'
 import Notice from '~/components/Notice'
 import Spinner from '~/components/Spinner'
 import { toast } from '~/components/Toaster'
 import { cn } from '~/utils/cn'
-import { loadAcl, loadContext, patchAcl } from '~/utils/config/headplane'
+import { loadContext } from '~/utils/config/headplane'
+import { HeadscaleError, pull, put } from '~/utils/headscale'
 import { getSession } from '~/utils/sessions'
 
 import Monaco from './editor'
 
-export async function loader() {
-	const context = await loadContext()
-	if (!context.acl.read) {
-		throw new Error('No ACL configuration is available')
-	}
+export async function loader({ request }: LoaderFunctionArgs) {
+	const session = await getSession(request.headers.get('Cookie'))
+
+	try {
+		const { policy } = await pull<{ policy: string }>(
+			'v1/policy',
+			session.get('hsApiKey')!,
+		)
+
+		try {
+			// We have read access, now do we have write access?
+			// Attempt to set the policy to what we just got
+			await put('v1/policy', session.get('hsApiKey')!, {
+				policy,
+			})
+
+			return {
+				hasAclWrite: true,
+				currentAcl: policy,
+				aclType: 'json',
+			} as const
+		} catch (error) {
+			if (!(error instanceof HeadscaleError)) {
+				throw error
+			}
+
+			if (error.status === 500) {
+				return {
+					hasAclWrite: false,
+					currentAcl: policy,
+					aclType: 'json',
+				} as const
+			}
+		}
+	} catch {}
 
-	const { data, type } = await loadAcl()
 	return {
-		hasAclWrite: context.acl.write,
-		currentAcl: data,
-		aclType: type,
-	}
+		hasAclWrite: true,
+		currentAcl: '',
+		aclType: 'json',
+	} as const
 }
 
 export async function action({ request }: ActionFunctionArgs) {
@@ -37,27 +70,102 @@ export async function action({ request }: ActionFunctionArgs) {
 		})
 	}
 
-	const context = await loadContext()
-	if (!context.acl.write) {
-		return json({ success: false }, {
-			status: 403,
+	const { acl } = await request.json() as { acl: string, api: boolean }
+	try {
+		await put('v1/policy', session.get('hsApiKey')!, {
+			policy: acl,
 		})
-	}
 
-	const data = await request.json() as { acl: string }
-	await patchAcl(data.acl)
-
-	if (context.integration?.sighup) {
-		await context.integration.sighup()
+		await setTimeout(250)
+		return json({ success: true })
+	} catch (error) {
+		return json({ success: false }, {
+			status: error instanceof HeadscaleError ? error.status : 500,
+		})
 	}
 
 	return json({ success: true })
 }
 
+export function ErrorBoundary() {
+	return (
+		<div>
+			<Notice className="mb-4">
+				An ACL policy is not available or an error occurred while trying to fetch it.
+			</Notice>
+			<h1 className="text-2xl font-medium mb-4">
+				Access Control List (ACL)
+			</h1>
+
+			<p className="mb-4 max-w-prose">
+				The ACL file is used to define the access control rules for your network.
+				You can find more information about the ACL file in the
+				{' '}
+				<Link
+					to="https://tailscale.com/kb/1018/acls"
+					name="Tailscale ACL documentation"
+				>
+					Tailscale ACL guide
+				</Link>
+				{' '}
+				and the
+				{' '}
+				<Link
+					to="https://headscale.net/acls"
+					name="Headscale ACL documentation"
+				>
+					Headscale docs
+				</Link>
+				.
+			</p>
+			<div>
+				<div className="max-w-prose">
+					<p className="mb-4 text-md">
+						If you are running Headscale 0.23-beta1 or later, the
+						ACL configuration is most likely set to
+						{' '}
+						<Code>file</Code>
+						{' '}
+						mode but the ACL file is not available. In order to
+						resolve this you will either need to correctly set
+						{' '}
+						<Code>policy.path</Code>
+						{' '}
+						in your Headscale configuration or set the
+						{' '}
+						<Code>policy.mode</Code>
+						{' '}
+						to
+						{' '}
+						<Code>database</Code>
+						.
+					</p>
+				</div>
+			</div>
+		</div>
+	)
+}
+
 export default function Page() {
 	const data = useLoaderData<typeof loader>()
+	const fetcher = useFetcher<typeof action>()
 	const [acl, setAcl] = useState(data.currentAcl)
-	const fetcher = useFetcher()
+	const [toasted, setToasted] = useState(false)
+
+	useEffect(() => {
+		if (!fetcher.data || toasted) {
+			return
+		}
+
+		if (fetcher.data.success) {
+			toast('Updated tailnet ACL policy')
+		} else {
+			toast('Failed to update tailnet ACL policy')
+		}
+
+		setToasted(true)
+		setAcl(data.currentAcl)
+	}, [fetcher.data, toasted, data.currentAcl])
 
 	return (
 		<div>
@@ -65,9 +173,12 @@ export default function Page() {
 				? undefined
 				: (
 					<div className="mb-4">
-						<Notice>
-							The ACL policy file is readonly to Headplane.
-							You will not be able to make changes here.
+						<Notice className="w-fit">
+							The ACL policy is read-only. You can view the current policy
+							but you cannot make changes to it.
+							<br />
+							To resolve this, you need to set the ACL policy mode to
+							database in your Headscale configuration.
 						</Notice>
 					</div>
 					)}
@@ -144,19 +255,18 @@ export default function Page() {
 				</TabList>
 				<TabPanel id="edit">
 					<Monaco
-						variant="editor"
+						isDisabled={!data.hasAclWrite}
+						variant="edit"
 						language={data.aclType}
-						value={acl}
-						onChange={setAcl}
+						state={[acl, setAcl]}
 					/>
 				</TabPanel>
 				<TabPanel id="diff">
 					<Monaco
 						variant="diff"
 						language={data.aclType}
-						value={acl}
-						onChange={setAcl}
-						original={data.currentAcl}
+						state={[acl, setAcl]}
+						policy={data.currentAcl}
 					/>
 				</TabPanel>
 				<TabPanel id="preview">
@@ -180,14 +290,13 @@ export default function Page() {
 				className="mr-2"
 				isDisabled={fetcher.state === 'loading' || !data.hasAclWrite || data.currentAcl === acl}
 				onPress={() => {
+					setToasted(false)
 					fetcher.submit({
 						acl,
 					}, {
 						method: 'PATCH',
 						encType: 'application/json',
 					})
-
-					toast('Updated tailnet ACL policy')
 				}}
 			>
 				{fetcher.state === 'idle'
@@ -197,7 +306,10 @@ export default function Page() {
 						)}
 				Save
 			</Button>
-			<Button onPress={() => { setAcl(data.currentAcl) }}>
+			<Button
+				isDisabled={fetcher.state === 'loading' || data.currentAcl === acl || !data.hasAclWrite}
+				onPress={() => { setAcl(data.currentAcl) }}
+			>
 				Discard Changes
 			</Button>
 		</div>

app/routes/_data.dns._index/dialogs/dns.tsx

@@ -47,7 +47,7 @@ export default function AddDNS({ records }: Props) {
 								setIp('')
 
 								submit({
-									'dns_config.extra_records': [
+									'dns.extra_records': [
 										...records,
 										{
 											name,

app/routes/_data.dns._index/dialogs/nameserver.tsx

@@ -55,7 +55,7 @@ export default function AddNameserver({ nameservers }: Props) {
 									}
 
 									submit({
-										'dns_config.restricted_nameservers': splitNs,
+										'dns.nameservers.split': splitNs,
 									}, {
 										method: 'PATCH',
 										encType: 'application/json',
@@ -65,7 +65,7 @@ export default function AddNameserver({ nameservers }: Props) {
 									globalNs.push(ns)
 
 									submit({
-										'dns_config.nameservers': globalNs,
+										'dns.nameservers.global': globalNs,
 									}, {
 										method: 'PATCH',
 										encType: 'application/json',

app/routes/_data.dns._index/dns.tsx

@@ -63,7 +63,7 @@ export default function DNS({ records, isDisabled }: Props) {
 									isDisabled={isDisabled}
 									onPress={() => {
 										submit({
-											'dns_config.extra_records': records
+											'dns.extra_records': records
 												.filter((_, i) => i !== index),
 										}, {
 											method: 'PATCH',

app/routes/_data.dns._index/domains.tsx

@@ -134,7 +134,7 @@ export default function Domains({ baseDomain, searchDomains, disabled }: Propert
 									onPress={() => {
 										fetcher.submit({
 										// eslint-disable-next-line @typescript-eslint/naming-convention
-											'dns_config.domains': [...localDomains, newDomain]
+											'dns.search_domains': [...localDomains, newDomain]
 										}, {
 											method: 'PATCH',
 											encType: 'application/json'
@@ -212,8 +212,7 @@ function Domain({ domain, id, localDomains, isDrag, disabled, fetcher }: DomainP
 					isDisabled={disabled}
 					onPress={() => {
 						fetcher.submit({
-							// eslint-disable-next-line @typescript-eslint/naming-convention
-							'dns_config.domains': localDomains.filter((_, index) => index !== id - 1)
+							'dns.search_domains': localDomains.filter((_, index) => index !== id - 1)
 						}, {
 							method: 'PATCH',
 							encType: 'application/json'

app/routes/_data.dns._index/magic.tsx

@@ -42,7 +42,7 @@ export default function Modal({ isEnabled, disabled }: Properties) {
 								onPress={() => {
 									fetcher.submit({
 										// eslint-disable-next-line @typescript-eslint/naming-convention
-										'dns_config.magic_dns': !isEnabled
+										'dns.magic_dns': !isEnabled
 									}, {
 										method: 'PATCH',
 										encType: 'application/json'

app/routes/_data.dns._index/nameservers.tsx

@@ -11,11 +11,10 @@ import AddNameserver from './dialogs/nameserver'
 
 interface Props {
 	nameservers: Record<string, string[]>
-	override: boolean
 	isDisabled: boolean
 }
 
-export default function Nameservers({ nameservers, override, isDisabled }: Props) {
+export default function Nameservers({ nameservers, isDisabled }: Props) {
 	return (
 		<div className="flex flex-col w-2/3">
 			<h1 className="text-2xl font-medium mb-4">Nameservers</h1>
@@ -37,7 +36,6 @@ export default function Nameservers({ nameservers, override, isDisabled }: Props
 						isGlobal={key === 'global'}
 						isDisabled={isDisabled}
 						nameservers={nameservers[key]}
-						override={override}
 						name={key}
 					/>
 				))}
@@ -57,11 +55,9 @@ interface ListProps {
 	isDisabled: boolean
 	nameservers: string[]
 	name: string
-	override: boolean
 }
 
-function NameserverList({ isGlobal, isDisabled, nameservers, name, override }: ListProps) {
-	const [localOverride, setLocalOverride] = useState(override)
+function NameserverList({ isGlobal, isDisabled, nameservers, name }: ListProps) {
 	const submit = useSubmit()
 
 	return (
@@ -70,30 +66,6 @@ function NameserverList({ isGlobal, isDisabled, nameservers, name, override }: L
 				<h2 className="text-md font-medium opacity-80">
 					{isGlobal ? 'Global Nameservers' : name}
 				</h2>
-				{isGlobal
-					? (
-						<div className="flex gap-2 items-center">
-							<span className="text-sm opacity-50">
-								Override local DNS
-							</span>
-							<Switch
-								label="Override local DNS"
-								defaultSelected={localOverride}
-								isDisabled={isDisabled}
-								onChange={() => {
-									submit({
-										'dns_config.override_local_dns': !localOverride,
-									}, {
-										method: 'PATCH',
-										encType: 'application/json',
-									})
-
-									setLocalOverride(!localOverride)
-								}}
-							/>
-						</div>
-						)
-					: undefined}
 			</div>
 			<TableList>
 				{nameservers.map((ns, index) => (
@@ -111,17 +83,17 @@ function NameserverList({ isGlobal, isDisabled, nameservers, name, override }: L
 							onPress={() => {
 								if (isGlobal) {
 									submit({
-										'dns_config.nameservers': nameservers
+										'dns.nameservers.global': nameservers
 											.filter((_, i) => i !== index),
 									}, {
 										method: 'PATCH',
 										encType: 'application/json',
 									})
 								} else {
-									const key = `dns_config.restricted_nameservers."${name}"`
+									const key = `dns.nameservers.split."${name}"`
+									const list = nameservers.filter((_, i) => i !== index)
 									submit({
-										[key]: nameservers
-											.filter((_, i) => i !== index),
+										[key]: list.length ? list : null,
 									}, {
 										method: 'PATCH',
 										encType: 'application/json',

app/routes/_data.dns._index/rename.tsx

@@ -28,7 +28,7 @@ export default function Modal({ name, disabled }: Properties) {
 				Devices are accessible at
 				{' '}
 				<Code>
-					[device].[user].{name}
+					[device].{name}
 				</Code>
 				{' '}
 				when Magic DNS is enabled.
@@ -80,7 +80,7 @@ export default function Modal({ name, disabled }: Properties) {
 									variant='confirm'
 									onPress={() => {
 										fetcher.submit({
-											'dns_config.base_domain': newName
+											'dns.base_domain': newName
 										}, {
 											method: 'PATCH',
 											encType: 'application/json'

app/routes/_data.dns._index/route.tsx

@@ -24,13 +24,14 @@ export async function loader() {
 	const config = await loadConfig()
 	const dns = {
 		prefixes: config.prefixes,
-		magicDns: config.dns_config.magic_dns,
-		baseDomain: config.dns_config.base_domain,
-		overrideLocal: config.dns_config.override_local_dns,
-		nameservers: config.dns_config.nameservers,
-		splitDns: config.dns_config.restricted_nameservers,
-		searchDomains: config.dns_config.domains,
-		extraRecords: config.dns_config.extra_records,
+		magicDns: config.dns.magic_dns,
+		baseDomain: config.dns.use_username_in_magic_dns
+			? `[user].${config.dns.base_domain}`
+			: config.dns.base_domain,
+		nameservers: config.dns.nameservers.global,
+		splitDns: config.dns.nameservers.split,
+		searchDomains: config.dns.search_domains,
+		extraRecords: config.dns.extra_records,
 	}
 
 	return {
@@ -57,8 +58,8 @@ export async function action({ request }: ActionFunctionArgs) {
 	const data = await request.json() as Record<string, unknown>
 	await patchConfig(data)
 
-	if (context.integration?.restart) {
-		await context.integration.restart()
+	if (context.integration?.onConfigChange) {
+		await context.integration.onConfigChange(context.integration.context)
 	}
 
 	return json({ success: true })
@@ -87,7 +88,6 @@ export default function Page() {
 			<RenameModal name={data.baseDomain} disabled={!data.config.write} />
 			<Nameservers
 				nameservers={allNs}
-				override={data.overrideLocal}
 				isDisabled={!data.config.write}
 			/>
 
@@ -109,7 +109,7 @@ export default function Page() {
 					on the tailnet. Devices will be accessible at
 					{' '}
 					<Code>
-						[device].[user].
+						[device].
 						{data.baseDomain}
 					</Code>
 					{' '}

app/routes/_data.machines.$id.tsx

@@ -27,8 +27,8 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
 
 	if (context.config.read) {
 		const config = await loadConfig()
-		if (config.dns_config.magic_dns) {
-			magic = config.dns_config.base_domain
+		if (config.dns.magic_dns) {
+			magic = config.dns.base_domain
 		}
 	}
 

app/routes/_data.machines._index/action.tsx

@@ -97,6 +97,35 @@ export async function menuAction(request: ActionFunctionArgs['request']) {
 			}
 		}
 
+		case 'register': {
+			const key = data.get('mkey')?.toString()
+			const user = data.get('user')?.toString()
+
+			if (!key) {
+				return json({ message: 'No machine key provided' }, {
+					status: 400,
+				})
+			}
+
+			if (!user) {
+				return json({ message: 'No user provided' }, {
+					status: 400,
+				})
+			}
+
+			try {
+				await post('v1/node/register', session.get('hsApiKey')!, {
+					user, key,
+				})
+
+				return json({ message: 'Machine registered' })
+			} catch {
+				return json({ message: 'Failed to register machine' }, {
+					status: 500,
+				})
+			}
+		}
+
 		default: {
 			return json({ message: 'Invalid method' }, {
 				status: 400,

app/routes/_data.machines._index/dialogs/new.tsx

@@ -0,0 +1,115 @@
+import { Form, useSubmit } from '@remix-run/react'
+import { Dispatch, SetStateAction, useState } from 'react'
+import { PlusIcon, ServerIcon, KeyIcon } from '@primer/octicons-react'
+import { cn } from '~/utils/cn'
+
+import Code from '~/components/Code'
+import Dialog from '~/components/Dialog'
+import TextField from '~/components/TextField'
+import Select from '~/components/Select'
+import Menu from '~/components/Menu'
+import { Machine, User } from '~/types'
+
+export interface NewProps {
+	server: string
+	users: User[]
+}
+
+export default function New(data: NewProps) {
+	const submit = useSubmit()
+	const mkeyState = useState(false)
+	const pkeyState = useState(false)
+	const [mkey, setMkey] = useState('')
+	const [user, setUser] = useState(data.users[0].id)
+
+	return (
+		<>
+			<Dialog>
+				<Dialog.Panel control={mkeyState}>
+					{close => (
+						<>
+							<Dialog.Title>
+								Register Machine Key
+							</Dialog.Title>
+							<Dialog.Text className='mb-4'>
+								The machine key is given when you run
+								{' '}
+								<Code>
+									tailscale up --login-server=
+								</Code>
+								<Code>
+									{data.server}
+								</Code>
+								{' '}
+								on your device.
+							</Dialog.Text>
+							<Form
+								method="POST"
+								onSubmit={(e) => {
+									submit(e.currentTarget)
+								}}
+							>
+								<input type="hidden" name="_method" value="register" />
+								<input type="hidden" name="id" value="_" />
+								<TextField
+									label='Machine Key'
+									placeholder='nodekey:ff.....'
+									name="mkey"
+									state={[mkey, setMkey]}
+									className='my-2 font-mono'
+								/>
+								<Select
+									label="Owner"
+									name="user"
+									placeholder="Select a user"
+									state={[user, setUser]}
+								>
+									{data.users.map(user => (
+										<Select.Item key={user.id} id={user.name}>
+											{user.name}
+										</Select.Item>
+									))}
+								</Select>
+								<div className='mt-6 flex justify-end gap-2 mt-6'>
+									<Dialog.Action
+										variant="cancel"
+										onPress={close}
+									>
+										Cancel
+									</Dialog.Action>
+									<Dialog.Action
+										variant="confirm"
+										onPress={close}
+									>
+										Register
+									</Dialog.Action>
+								</div>
+							</Form>
+						</>
+					)}
+				</Dialog.Panel>
+			</Dialog>
+			<Menu>
+				<Menu.Button
+					className={cn(
+						'w-fit text-sm rounded-lg px-4 py-2',
+						'bg-main-700 dark:bg-main-800 text-white',
+						'hover:bg-main-800 dark:hover:bg-main-700',
+					)}
+				>
+					Add Device
+				</Menu.Button>
+				<Menu.Items>
+					<Menu.ItemButton control={mkeyState}>
+						<ServerIcon className='w-4 h-4 mr-2'/>
+						Register Machine Key
+					</Menu.ItemButton>
+					<Menu.ItemButton control={pkeyState} isDisabled>
+						<KeyIcon className='w-4 h-4 mr-2'/>
+						Generate Pre-auth Key
+					</Menu.ItemButton>
+				</Menu.Items>
+			</Menu>
+		</>
+	)
+}

app/routes/_data.machines._index/machine.tsx

@@ -31,6 +31,10 @@ export default function MachineRow({ machine, routes, magic, users }: Props) {
 		tags.unshift('Expired')
 	}
 
+	let prefix = magic?.startsWith('[user]')
+		? magic.replace('[user]', machine.user.name)
+		: magic
+
 	return (
 		<tr
 			key={machine.id}
@@ -102,16 +106,14 @@ export default function MachineRow({ machine, routes, magic, users }: Props) {
 											'justify-between w-full break-keep',
 										)}
 										onPress={async () => {
-											const ip = `${machine.givenName}.${machine.user.name}.${magic}`
+											const ip = `${machine.givenName}.${prefix}`
 											await navigator.clipboard.writeText(ip)
 											toast('Copied hostname to clipboard')
 										}}
 									>
 										{machine.givenName}
 										.
-										{machine.user.name}
-										.
-										{magic}
+										{prefix}
 										<CopyIcon className="w-3 h-3" />
 									</Menu.ItemButton>
 									)

app/routes/_data.machines._index/route.tsx

@@ -15,6 +15,7 @@ import { useLiveData } from '~/utils/useLiveData'
 
 import { menuAction } from './action'
 import MachineRow from './machine'
+import NewMachine from './dialogs/new'
 
 export async function loader({ request }: LoaderFunctionArgs) {
 	const session = await getSession(request.headers.get('Cookie'))
@@ -29,8 +30,12 @@ export async function loader({ request }: LoaderFunctionArgs) {
 
 	if (context.config.read) {
 		const config = await loadConfig()
-		if (config.dns_config.magic_dns) {
-			magic = config.dns_config.base_domain
+		if (config.dns.magic_dns) {
+			magic = config.dns.base_domain
+		}
+
+		if (config.dns.use_username_in_magic_dns) {
+			magic = `[user].${magic}`
 		}
 	}
 
@@ -39,6 +44,7 @@ export async function loader({ request }: LoaderFunctionArgs) {
 		routes: routes.routes,
 		users: users.users,
 		magic,
+		server: context.headscaleUrl,
 	}
 }
 
@@ -52,7 +58,10 @@ export default function Page() {
 
 	return (
 		<>
-			<h1 className="text-2xl font-medium mb-4">Machines</h1>
+			<div className="flex justify-between items-center">
+				<h1 className="text-2xl font-medium mb-4">Machines</h1>
+				<NewMachine server={data.server} users={data.users} />
+			</div>
 			<table className="table-auto w-full rounded-lg">
 				<thead className="text-gray-500 dark:text-gray-400">
 					<tr className="text-left uppercase text-xs font-bold px-0.5">
@@ -76,7 +85,7 @@ export default function Page() {
 												based on their name and also at
 												{' '}
 												<Code>
-													[name].[user].
+													[name].
 													{data.magic}
 												</Code>
 											</Tooltip>

app/routes/_data.tsx

@@ -35,7 +35,6 @@ export async function loader({ request }: LoaderFunctionArgs) {
 
 	const context = await loadContext()
 	return {
-		acl: context.acl,
 		config: context.config,
 		user: session.get('user'),
 	}

app/routes/_data.users._index/add.tsx

@@ -36,7 +36,6 @@ export default function Add({ magic }: Props) {
 										{' '}
 										<Code>
 											[machine].
-											{username.length > 0 ? username : '[username]'}
 											.
 											{magic}
 										</Code>

app/routes/_data.users._index/rename.tsx

@@ -59,7 +59,6 @@ export default function Rename({ username, magic }: Props) {
 											{' '}
 											<Code>
 												[machine].
-												{newName.length > 0 ? newName : '[new-username]'}
 												.
 												{magic}
 											</Code>

app/routes/_data.users._index/route.tsx

@@ -41,8 +41,8 @@ export async function loader({ request }: LoaderFunctionArgs) {
 
 	if (context.config.read) {
 		const config = await loadConfig()
-		if (config.dns_config.magic_dns) {
-			magic = config.dns_config.base_domain
+		if (config.dns.magic_dns) {
+			magic = config.dns.base_domain
 		}
 	}
 

app/routes/login.tsx

@@ -80,8 +80,7 @@ export async function action({ request }: ActionFunctionArgs) {
 				}),
 			},
 		})
-	} catch (error) {
-		console.error(error)
+	} catch {
 		return json({
 			error: 'Invalid API key',
 		})

app/utils/config/headplane.ts

@@ -8,25 +8,21 @@ import { resolve } from 'node:path'
 
 import { parse } from 'yaml'
 
-import { checkIntegration, Integration } from '~/integration'
-
-import { HeadscaleConfig, loadConfig } from './headscale'
+import { IntegrationFactory, loadIntegration } from '~/integration'
+import { HeadscaleConfig, loadConfig } from '~/utils/config/headscale'
+import log from '~/utils/log'
 
 export interface HeadplaneContext {
+	debug: boolean
 	headscaleUrl: string
 	cookieSecret: string
-	integration: Integration | undefined
+	integration: IntegrationFactory | undefined
 
 	config: {
 		read: boolean
 		write: boolean
 	}
 
-	acl: {
-		read: boolean
-		write: boolean
-	}
-
 	oidc?: {
 		issuer: string
 		client: string
@@ -43,6 +39,12 @@ export async function loadContext(): Promise<HeadplaneContext> {
 		return context
 	}
 
+	const debug = process.env.DEBUG === 'true'
+	if (debug) {
+		log.info('CTXT', 'Debug mode is enabled! Logs will spam a lot.')
+		log.info('CTXT', 'Please disable debug mode in production.')
+	}
+
 	const path = resolve(process.env.CONFIG_FILE ?? '/etc/headscale/config.yaml')
 	const { config, contextData } = await checkConfig(path)
 
@@ -65,70 +67,34 @@ export async function loadContext(): Promise<HeadplaneContext> {
 	}
 
 	context = {
+		debug,
 		headscaleUrl,
 		cookieSecret,
-		integration: await checkIntegration(),
+		integration: await loadIntegration(),
 		config: contextData,
-		acl: await checkAcl(config),
 		oidc: await checkOidc(config),
 	}
 
-	console.log('Completed loading the Headplane Context')
-	console.log('Headscale URL:', headscaleUrl)
-	console.log('Integration:', context.integration?.name ?? 'None')
-	console.log('Config:', contextData.read ? `Found ${contextData.write ? '' : '(Read Only)'}` : 'Unavailable')
-	console.log('ACL:', context.acl.read ? `Found ${context.acl.write ? '' : '(Read Only)'}` : 'Unavailable')
-	console.log('OIDC:', context.oidc ? 'Configured' : 'Unavailable')
+	log.info('CTXT', 'Starting Headplane with Context')
+	log.info('CTXT', 'HEADSCALE_URL: %s', headscaleUrl)
+	log.info('CTXT', 'Integration: %s', context.integration?.name ?? 'None')
+	log.info('CTXT', 'Config: %s', contextData.read
+		? `Found ${contextData.write ? '' : '(Read Only)'}`
+		: 'Unavailable',
+	)
 
+	log.info('CTXT', 'OIDC: %s', context.oidc ? 'Configured' : 'Unavailable')
 	return context
 }
 
-export async function loadAcl(): Promise<{ data: string, type: 'json' | 'yaml' }> {
-	let path = process.env.ACL_FILE
-	if (!path) {
-		try {
-			const config = await loadConfig()
-			path = config.acl_policy_path
-		} catch {}
-	}
-
-	if (!path) {
-		return { data: '', type: 'json' }
-	}
-
-	const data = await readFile(path, 'utf8')
-
-	// Naive check for YAML over JSON
-	// This is because JSON.parse doesn't support comments
-	try {
-		parse(data)
-		return { data, type: 'yaml' }
-	} catch {
-		return { data, type: 'json' }
-	}
-}
-
-export async function patchAcl(data: string) {
-	let path = process.env.ACL_FILE
-	if (!path) {
-		try {
-			const config = await loadConfig()
-			path = config.acl_policy_path
-		} catch {}
-	}
-
-	if (!path) {
-		throw new Error('No ACL file defined')
-	}
-
-	await writeFile(path, data, 'utf8')
-}
-
 async function checkConfig(path: string) {
+	log.debug('CTXT', 'Checking config at %s', path)
+
 	let config: HeadscaleConfig | undefined
 	try {
 		config = await loadConfig(path)
 	} catch {
+		log.debug('CTXT', 'Config at %s failed to load', path)
 		return {
 			config: undefined,
 			contextData: {
@@ -140,9 +106,12 @@ async function checkConfig(path: string) {
 
 	let write = false
 	try {
+		log.debug('CTXT', 'Checking write access to %s', path)
 		await access(path, constants.W_OK)
 		write = true
-	} catch {}
+	} catch {
+		log.debug('CTXT', 'No write access to %s', path)
+	}
 
 	return {
 		config,
@@ -153,34 +122,13 @@ async function checkConfig(path: string) {
 	}
 }
 
-async function checkAcl(config?: HeadscaleConfig) {
-	let path = process.env.ACL_FILE
-	if (!path && config) {
-		path = config.acl_policy_path
-	}
-
-	let read = false
-	let write = false
-	if (path) {
-		try {
-			await access(path, constants.R_OK)
-			read = true
-		} catch {}
-
-		try {
-			await access(path, constants.W_OK)
-			write = true
-		} catch {}
-	}
-
-	return {
-		read,
-		write,
-	}
-}
-
 async function checkOidc(config?: HeadscaleConfig) {
+	log.debug('CTXT', 'Checking OIDC configuration')
+
 	const disableKeyLogin = process.env.DISABLE_API_KEY_LOGIN === 'true'
+	log.debug('CTXT', 'API Key Login Enabled: %s', !disableKeyLogin)
+
+	log.debug('CTXT', 'Checking ROOT_API_KEY and falling back to API_KEY')
 	const rootKey = process.env.ROOT_API_KEY ?? process.env.API_KEY
 	if (!rootKey) {
 		throw new Error('ROOT_API_KEY or API_KEY not set')
@@ -190,6 +138,10 @@ async function checkOidc(config?: HeadscaleConfig) {
 	let client = process.env.OIDC_CLIENT_ID
 	let secret = process.env.OIDC_CLIENT_SECRET
 
+	log.debug('CTXT', 'Checking OIDC environment variables')
+	log.debug('CTXT', 'Issuer: %s', issuer)
+	log.debug('CTXT', 'Client: %s', client)
+
 	if (
 		(issuer ?? client ?? secret)
 		&& !(issuer && client && secret)
@@ -198,12 +150,23 @@ async function checkOidc(config?: HeadscaleConfig) {
 		throw new Error('OIDC environment variables are incomplete')
 	}
 
+	if (issuer && client && secret) {
+		return {
+			issuer,
+			client,
+			secret,
+			rootKey,
+			disableKeyLogin,
+		}
+	}
+
 	if ((!issuer || !client || !secret) && config) {
 		issuer = config.oidc?.issuer
 		client = config.oidc?.client_id
 		secret = config.oidc?.client_secret
 
 		if (!secret && config.oidc?.client_secret_path) {
+			log.debug('CTXT', 'Trying to read OIDC client secret from %s', config.oidc.client_secret_path)
 			try {
 				const data = await readFile(
 					config.oidc.client_secret_path,
@@ -213,7 +176,9 @@ async function checkOidc(config?: HeadscaleConfig) {
 				if (data && data.length > 0) {
 					secret = data.trim()
 				}
-			} catch {}
+			} catch {
+				log.error('CTXT', 'Failed to read OIDC client secret from %s', config.oidc.client_secret_path)
+			}
 		}
 	}
 

app/utils/config/headscale.ts

@@ -12,6 +12,8 @@ import { resolve } from 'node:path'
 import { type Document, parseDocument } from 'yaml'
 import { z } from 'zod'
 
+import log from '~/utils/log'
+
 const goBool = z
 	.union([z.boolean(), z.literal('true'), z.literal('false')])
 	.transform((value) => {
@@ -43,7 +45,6 @@ const HeadscaleConfig = z.object({
 	disable_check_updates: goBool.default(false),
 	ephemeral_node_inactivity_timeout: goDuration.default('120s'),
 	randomize_client_port: goBool.default(false),
-	acl_policy_path: z.string().optional(),
 
 	acme_email: z.string().optional(),
 	acme_url: z.string().optional(),
@@ -51,6 +52,11 @@ const HeadscaleConfig = z.object({
 	unix_socket: z.string().default('/var/run/headscale/headscale.sock'),
 	unix_socket_permission: z.string().default('0o770'),
 
+	policy: z.object({
+		mode: z.enum(['file', 'database']).default('file'),
+		path: z.string().optional(),
+	}).optional(),
+
 	tuning: z.object({
 		batch_change_delay: goDuration.default('800ms'),
 		node_mapsession_buffered_chan_size: z.number().default(30),
@@ -82,18 +88,20 @@ const HeadscaleConfig = z.object({
 		v6: z.string(),
 	}),
 
-	dns_config: z.object({
-		override_local_dns: goBool.default(false),
-		nameservers: z.array(z.string()).default([]),
-		restricted_nameservers: z.record(z.array(z.string())).default({}),
-		domains: z.array(z.string()).default([]),
+	dns: z.object({
+		magic_dns: goBool.default(true),
+		base_domain: z.string().default('headscale.net'),
+		nameservers: z.object({
+			global: z.array(z.string()).default([]),
+			split: z.record(z.array(z.string())).default({}),
+		}).default({ global: [], split: {} }),
+		search_domains: z.array(z.string()).default([]),
 		extra_records: z.array(z.object({
 			name: z.string(),
 			type: z.literal('A'),
 			value: z.string(),
 		})).default([]),
-		magic_dns: goBool.default(false),
-		base_domain: z.string().default('headscale.net'),
+		use_username_in_magic_dns: goBool.default(false),
 	}),
 
 	oidc: z.object({
@@ -179,10 +187,12 @@ export async function loadConfig(path?: string) {
 		throw new Error('Path is required to lazy load config')
 	}
 
+	log.debug('CFGX', 'Loading Headscale configuration from %s', path)
 	const data = await readFile(path, 'utf8')
 	configYaml = parseDocument(data)
 
 	if (process.env.HEADSCALE_CONFIG_UNSTRICT === 'true') {
+		log.debug('CFGX', 'Loaded Headscale configuration in non-strict mode')
 		const loaded = configYaml.toJSON() as Record<string, unknown>
 		config = {
 			...loaded,
@@ -218,44 +228,47 @@ export async function loadConfig(path?: string) {
 				v6: '',
 			},
 
-			dns_config: loaded.dns_config ?? {
-				override_local_dns: false,
-				nameservers: [],
-				restricted_nameservers: {},
-				domains: [],
+			dns: loaded.dns ?? {
+				nameservers: {
+					global: [],
+					split: {},
+				},
+				search_domains: [],
 				extra_records: [],
 				magic_dns: false,
 				base_domain: 'headscale.net',
 			},
 		} as HeadscaleConfig
 
-		console.log('Loaded Headscale configuration in non-strict mode')
-		console.log('By using this mode you forfeit GitHub issue support')
-		console.log('This is very dangerous and comes with a few caveats:')
-		console.log('- Headplane could very easily crash')
-		console.log('- Headplane could break your Headscale installation')
-		console.log('- The UI could throw random errors/show incorrect data')
-		console.log('')
+		log.warn('CFGX', 'Loaded Headscale configuration in non-strict mode')
+		log.warn('CFGX', 'By using this mode you forfeit GitHub issue support')
+		log.warn('CFGX', 'This is very dangerous and comes with a few caveats:')
+		log.warn('CFGX', 'Headplane could very easily crash')
+		log.warn('CFGX', 'Headplane could break your Headscale installation')
+		log.warn('CFGX', 'The UI could throw random errors/show incorrect data')
+		log.warn('CFGX', '')
 		return config
 	}
 
 	try {
+		log.debug('CFGX', 'Attempting to parse Headscale configuration')
 		config = await HeadscaleConfig.parseAsync(configYaml.toJSON())
 	} catch (error) {
+		log.debug('CFGX', 'Failed to load Headscale configuration')
 		if (error instanceof z.ZodError) {
-			console.log('Failed to parse the Headscale configuration file!')
-			console.log('The following schema issues were found:')
+			log.error('CFGX', 'Recieved invalid configuration file')
+			log.error('CFGX', 'The following schema issues were found:')
 			for (const issue of error.issues) {
 				const path = issue.path.map(String).join('.')
 				const message = issue.message
 
-				console.log(`- '${path}': ${message}`)
+				log.error('CFGX', `  '${path}': ${message}`)
 			}
 
-			console.log('')
-			console.log('Please fix the configuration file and try again.')
-			console.log('Headplane will operate as if no config is present.')
-			console.log('')
+			log.error('CFGX', '')
+			log.error('CFGX', 'Resolve these issues and try again.')
+			log.error('CFGX', 'Headplane will operate without the config')
+			log.error('CFGX', '')
 		}
 
 		throw error
@@ -270,7 +283,9 @@ export async function patchConfig(partial: Record<string, unknown>) {
 		throw new Error('Config not loaded')
 	}
 
+	log.debug('CFGX', 'Patching Headscale configuration')
 	for (const [key, value] of Object.entries(partial)) {
+		log.debug('CFGX', 'Patching %s with %s', key, value)
 		// If the key is something like `test.bar."foo.bar"`, then we treat
 		// the foo.bar as a single key, and not as two keys, so that needs
 		// to be split correctly.
@@ -299,6 +314,11 @@ export async function patchConfig(partial: Record<string, unknown>) {
 
 		// Push the remaining element
 		path.push(temp.replaceAll('"', ''))
+		if (value === null) {
+			configYaml.deleteIn(path)
+			continue
+		}
+
 		configYaml.setIn(path, value)
 	}
 
@@ -307,5 +327,6 @@ export async function patchConfig(partial: Record<string, unknown>) {
 		: (await HeadscaleConfig.parseAsync(configYaml.toJSON()))
 
 	const path = resolve(process.env.CONFIG_FILE ?? '/etc/headscale/config.yaml')
+	log.debug('CFGX', 'Writing patched configuration to %s', path)
 	await writeFile(path, configYaml.toString(), 'utf8')
 }

app/utils/headscale.ts

@@ -1,4 +1,5 @@
 import { loadContext } from './config/headplane'
+import log from './log'
 
 export class HeadscaleError extends Error {
 	status: number
@@ -20,6 +21,8 @@ export class FatalError extends Error {
 export async function pull<T>(url: string, key: string) {
 	const context = await loadContext()
 	const prefix = context.headscaleUrl
+
+	log.debug('APIC', 'GET %s', `${prefix}/api/${url}`)
 	const response = await fetch(`${prefix}/api/${url}`, {
 		headers: {
 			Authorization: `Bearer ${key}`,
@@ -27,6 +30,7 @@ export async function pull<T>(url: string, key: string) {
 	})
 
 	if (!response.ok) {
+		log.debug('APIC', 'GET %s failed with status %d', `${prefix}/api/${url}`, response.status)
 		throw new HeadscaleError(await response.text(), response.status)
 	}
 
@@ -36,6 +40,8 @@ export async function pull<T>(url: string, key: string) {
 export async function post<T>(url: string, key: string, body?: unknown) {
 	const context = await loadContext()
 	const prefix = context.headscaleUrl
+
+	log.debug('APIC', 'POST %s', `${prefix}/api/${url}`)
 	const response = await fetch(`${prefix}/api/${url}`, {
 		method: 'POST',
 		body: body ? JSON.stringify(body) : undefined,
@@ -45,6 +51,28 @@ export async function post<T>(url: string, key: string, body?: unknown) {
 	})
 
 	if (!response.ok) {
+		log.debug('APIC', 'POST %s failed with status %d', `${prefix}/api/${url}`, response.status)
+		throw new HeadscaleError(await response.text(), response.status)
+	}
+
+	return (response.json() as Promise<T>)
+}
+
+export async function put<T>(url: string, key: string, body?: unknown) {
+	const context = await loadContext()
+	const prefix = context.headscaleUrl
+
+	log.debug('APIC', 'PUT %s', `${prefix}/api/${url}`)
+	const response = await fetch(`${prefix}/api/${url}`, {
+		method: 'PUT',
+		body: body ? JSON.stringify(body) : undefined,
+		headers: {
+			Authorization: `Bearer ${key}`,
+		},
+	})
+
+	if (!response.ok) {
+		log.debug('APIC', 'PUT %s failed with status %d', `${prefix}/api/${url}`, response.status)
 		throw new HeadscaleError(await response.text(), response.status)
 	}
 
@@ -54,6 +82,8 @@ export async function post<T>(url: string, key: string, body?: unknown) {
 export async function del<T>(url: string, key: string) {
 	const context = await loadContext()
 	const prefix = context.headscaleUrl
+
+	log.debug('APIC', 'DELETE %s', `${prefix}/api/${url}`)
 	const response = await fetch(`${prefix}/api/${url}`, {
 		method: 'DELETE',
 		headers: {
@@ -62,6 +92,7 @@ export async function del<T>(url: string, key: string) {
 	})
 
 	if (!response.ok) {
+		log.debug('APIC', 'DELETE %s failed with status %d', `${prefix}/api/${url}`, response.status)
 		throw new HeadscaleError(await response.text(), response.status)
 	}
 

app/utils/log.ts

@@ -0,0 +1,29 @@
+export default {
+	info: (category: string, message: string, ...args: unknown[]) => {
+		defaultLog('INFO', category, message, ...args)
+	},
+
+	warn: (category: string, message: string, ...args: unknown[]) => {
+		defaultLog('WARN', category, message, ...args)
+	},
+
+	error: (category: string, message: string, ...args: unknown[]) => {
+		defaultLog('ERRO', category, message, ...args)
+	},
+
+	debug: (category: string, message: string, ...args: unknown[]) => {
+		if (process.env.DEBUG === 'true') {
+			defaultLog('DEBG', category, message, ...args)
+		}
+	}
+}
+
+function defaultLog(
+	level: string,
+	category: string,
+	message: string,
+	...args: unknown[]
+) {
+	const date = new Date().toISOString()
+	console.log(`${date} (${level}) [${category}] ${message}`, ...args)
+}

app/utils/oidc.ts

@@ -2,7 +2,7 @@ import { redirect } from '@remix-run/node'
 import {
 	authorizationCodeGrantRequest,
 	calculatePKCECodeChallenge,
-	type Client,
+	Client,
 	discoveryRequest,
 	generateRandomCodeVerifier,
 	generateRandomNonce,

app/utils/sessions.ts

@@ -27,9 +27,8 @@ export const {
 			maxAge: 60 * 60 * 24, // 24 hours
 			path: '/',
 			sameSite: 'lax',
-			// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 			secrets: [process.env.COOKIE_SECRET!],
-			secure: true
+			secure: process.env.COOKIE_SECURE !== 'false',
 		}
 	}
 )

compose.yaml

@@ -2,14 +2,13 @@
 # IT IS NOT AN EXAMPLE OF SOMETHING YOU DEPLOY
 # I ONLY USE IT FOR DEVELOPING HEADPLANE
 
-version: '3.9'
 networks:
   headplane-dev:
     name: 'headplane-dev'
     driver: 'bridge'
 services:
   headscale:
-    image: 'headscale/headscale:0.23.0-alpha5'
+    image: 'headscale/headscale:0.23.0-beta2'
     container_name: 'headscale'
     restart: 'unless-stopped'
     command: 'serve'

docs/Advanced-Integration.md

@@ -1,5 +1,11 @@
 # Advanced Integration
 
+The advanced integration methods unlock the full capabilities of Headplane.
+This is the closest you can get to the SaaS experience if you were paying for
+Tailscale.
+
+### Configuration Management
+
 <picture>
     <source
         media="(prefers-color-scheme: dark)"
@@ -15,21 +21,18 @@
     >
 </picture>
 
-With the advanced integration it's possible to control Access Control Lists (ACLs) and the Headscale configuration via the Headplane UI.
-Every single aspect of this integration is optional, meaning you can only use what you want.
-Additionally, with an integration provider, you can automatically reload the configuration or ACLs when they are changed.
+The advanced integration allows you to manage the Headscale configuration via
+the Headplane UI. When the configuration is available for editing, the `DNS`
+and `Settings` tabs will become available. When using the Docker or Kubernetes
+integration, changes to the configuration file will be automatically applied
+to Headscale.
 
-## Configuration Editing
+> By default, the configuration file is read from `/etc/headscale/config.yaml`.
+This can be overridden by setting the `CONFIG_FILE` environment variable. Any
+variables including `HEADSCALE_URL`, `OIDC_CLIENT_ID`, `OIDC_ISSUER`, and
+`OIDC_CLIENT_SECRET` will take priority over the configuration file.
 
-When the configuration file is available to Headplane, the `DNS` and `Settings` tabs will become functional.
-Similar to the Tailscale UI, you'll be able to edit the configuration without needing to manually edit the file.
-Headscale will read the file from the path given in the `CONFIG_FILE` environment variable.
-By default this is set to `/etc/headscale/config.yaml`.
-
-> One important think to note is that environment variables always take priority over the configuration file.
-> The `HEADSCALE_URL`, `OIDC_CLIENT_ID`, `OIDFC_ISSUER`, and `OIDC_CLIENT_SECRET` will be preferred over the configuration file if available.
-
-## Access Control Lists (ACLs)
+### Access Control Lists (ACLs)
 
 <picture>
     <source
@@ -46,126 +49,23 @@ By default this is set to `/etc/headscale/config.yaml`.
     >
 </picture>
 
-Headplane will enable the `Access Controls` tab if it is able to read an ACL file from Headscale.<br>
-The ACL file path is read from the following sources in order of priority:
+The advanced integration allows you to manage the ACLs via the Headplane UI.
+When the ACL file is available for editing, the `Access Controls` tab will
+become available. All of the integrations support automatic reloading of the
+ACLs when the file is changed.
 
-- **Environment Variable**: If you set the `ACL_FILE` environment variable, Headplane will read the file from that path.
-- **Configuration Integration**: If you've set this up, then Headplane will read the `acl_policy_path` key from the configuration file.
+> By default, the ACL file is read from `/etc/headscale/acl_policy.json`.
+> If `policy.path` is set and `policy.mode` is set to `file`, the ACL file will
+> be read from the path specified in the configuration file instead.
 
-## Automatic Configuration Reload
-
-When the configuration file is changed, Headscale will need to be restarted to apply the changes.
-Similarly, when the ACL file is changed, Headscale will need to be sent a `SIGHUP` signal to reload the ACLs.
-Currently there are 2 integration providers that can do this for you:
-
-### Docker Integration
-
-To enable the Docker integration, set `HEADSCALE_INTEGRATION=docker` in the environment variables.
-Additionally, you'll need to pass in the `HEADSCALE_CONTAINER` environment variable.
-This should be either the name or ID of the Headscale container (you can retrieve this using `docker ps`).
-If the other integrations aren't setup, then Headplane will automatically disable the Docker integration.
-
-By default the integration will check for `/var/run/docker.sock`, however you can override this by
-setting the `DOCKER_SOCK` environment variable if you use a different configuration than the default.
-When setting `DOCKER_SOCK`, you'll need to include the protocol (e.g., `unix://` or `tcp://`).
-Headplane currently does not support the HTTPS protocol for the Docker socket.
-
-#### Example Docker Deployment
+## Deployment
 
 Requirements:
-- Headscale 0.23 alpha or later
+- Headscale 0.23 or newer
 - Headscale and Headplane need a Reverse Proxy (NGINX, Traefik, Caddy, etc)
-- Headscale needs to be running in a docker container
 
-Here's a good Docker Compose example:
-```yaml
-version: '3.8'
-services:
-  headscale:
-    image: 'headscale/headscale:0.23.0-alpha5'
-    container_name: 'headscale'
-    restart: 'unless-stopped'
-    command: 'serve'
-    volumes:
-      - './data:/var/lib/headscale'
-      - './configs:/etc/headscale'
-    ports:
-      - '8080:8080'
-    environment:
-      TZ: 'America/New_York'
-  headplane:
-    container_name: headplane
-    image: ghcr.io/tale/headplane:latest
-    restart: unless-stopped
-    volumes:
-      - './data:/var/lib/headscale'
-      - './configs:/etc/headscale'
-      - '/var/run/docker.sock:/var/run/docker.sock:ro'
-    ports:
-      - '3000:3000'
-    environment:
-      # This is always required for Headplane to work
-      COOKIE_SECRET: 'abcdefghijklmnopqrstuvwxyz'
+Currently there are 3 integration providers that can do this for you:
+- [Docker Integration](/docs/integration/Docker.md)
+- [Kubernetes Integration](/docs/integration/Kubernetes.md)
+- [Native Linux Integration](/docs/integration/Native.md)
 
-      HEADSCALE_INTEGRATION: 'docker'
-      HEADSCALE_CONTAINER: 'headscale'
-      DISABLE_API_KEY_LOGIN: 'true'
-      HOST: '0.0.0.0'
-      PORT: '3000'
-        
-      # Overrides the configuration file values if they are set in config.yaml
-      # If you want to share the same OIDC configuration you do not need this
-      OIDC_CLIENT_ID: 'headscale'
-      OIDC_ISSUER: 'https://sso.example.com'
-      OIDC_CLIENT_SECRET: 'super_secret_client_secret'
-
-      # This NEEDS to be set with OIDC, regardless of what's in the config
-      # This needs to be a very long-lived (999 day) API key used to create
-      # shorter ones for OIDC and allow the OIDC functionality to work
-      ROOT_API_KEY: 'abcdefghijklmnopqrstuvwxyz'
-```
-
-> For a breakdown of each configuration variable, please refer to the [Configuration](/docs/Configuration.md) guide. 
-> It explains what each variable does, how to configure them, and what the default values are.
-
-You may also choose to run it natively with the distributed binaries on the releases page.
-You'll need to manage running this yourself, and I would recommend making a `systemd` unit.
-
-### Native Linux Integration (Beta)
-
-The native integration for Linux relies on the `/proc` directory to locate the Headscale process.
-To enable it, set the `HEADSCALE_INTEGRATION=proc` value in the environment variables.
-Because of the way this integration works, it only supports automatically reloading ACLs.
-It's still very experimental and may not work in all environments.
-
-## Configuration Scenarios
-
-Since the configuration is fairly modular you can have a variety of different setups.
-This mostly applies to the Docker integration since the native integration isn't fully featured yet.
-Here are a few examples to inspire you and show you what can work and what can't:
-
-#### Full Integration
-Headscale runs in a container, Headplane can run in either a container or natively.
-Headplane is able to manage the configuration file and ACLs that Headscale uses.
-When changes happen, the Docker integration will automatically reload the configuration and ACLs.
-
-> Note that the full integration currently isn't possible if Headscale isn't running in a container.
-
-#### Configuration Only
-Headscale and Headplane can either run in containers or natively.
-Headplane is able to manage the configuration file and ACLs that Headscale uses.
-When changes are made, Headscale will need to be manually restarted to apply the changes.
-
-#### ACL Only
-Headscale and Headplane can either run in containers or natively.
-Headplane is able to manage the ACLs that Headscale uses.
-When changes are made, Headscale will need to be sent a `SIGHUP` to reload the ACLs.
-In this scenario, Headplane does not have access to the configuration file.
-
-#### Read-Only Configuration or ACLs
-If the configuration or ACLs are read-only, Headplane will not be able to manage them.
-Instead you'll only be able to view the configurations on the UI and need to edit them manually.
-
-#### No Integration
-If no integration is setup, Headplane will not be able to manage the configuration or ACLs.
-This is the simplest setup by far, however it also heavily reduces the capabilities of Headplane.

docs/Basic-Integration.md

@@ -1,28 +1,35 @@
 # Basic Integration
 
-The basic integration is not able to offer advanced features such as:
-- Automatic management of Access Control Lists (ACLs)
-- Management of DNS settings for your tailnet
-- Management of the Headscale configuration
+The basic integration is the simplest way to get started with Headplane.
+It's more of a preview and is heavily limited in the features it can offer
+when compared to the [Advanced Integration](/docs/Advanced-Integration.md).
 
-In order to support these features please refer to the [Advanced Integration](./docs/Advanced-Integration.md) guide.
-Note that in order to use this deployment strategy you need to run Headscale in a Docker container.
+> Note that the Advanced integration is the recommend way to run
+Headplane in a production environment.
+
+## Limitations
+- No automatic management of Access Control Lists (ACLs)
+- No management of DNS settings for your tailnet
+- No capability to edit the configuration
+- Limited support for OIDC authentication
 
 ## Deployment
 
 Requirements:
-- Headscale 0.23 alpha or later
+- Headscale 0.23 or newer
 - Headscale and Headplane need a Reverse Proxy (NGINX, Traefik, Caddy, etc)
 
-Headplane is currently best run in a Docker container due to the easy configuration.
-Here's a very basic `docker-compose.yaml` file that utilizes each configuration variable.
+Docker heavily simplifies the deployment process, but this process can be
+adopted to run natively. Follow the first section of the deployment guide
+in the [Native Integration](/docs/integration/Native.md#deployment) for a
+bare-metal or virtual machine deployment.
 
+Here is a simple Docker Compose deployment:
 ```yaml
-version: '3.8'
 services:
   headplane:
     container_name: headplane
-    image: ghcr.io/tale/headplane:latest
+    image: ghcr.io/tale/headplane:0.3.0
     restart: unless-stopped
     ports:
       - '3000:3000'
@@ -36,18 +43,14 @@ services:
       OIDC_ISSUER: 'https://sso.example.com'
       OIDC_CLIENT_SECRET: 'super_secret_client_secret'
       DISABLE_API_KEY_LOGIN: 'true'
+      COOKIE_SECURE: 'false'
 
       # These are the default values
       HOST: '0.0.0.0'
       PORT: '3000'
 ```
 
-> For a breakdown of each configuration variable, please refer to the [Configuration](/docs/Configuration.md) guide. 
-> It explains what each variable does, how to configure them, and what the default values are.
-
-You may also choose to run it natively with the distributed binaries on the releases page.
-You'll need to manage running this yourself, and I would recommend making a `systemd` unit.
-
-## ACL Configuration
-If you would like to get the web ACL configuration working, you'll need to pass the `ACL_FILE` environment variable.
-This should point to the path of the ACL file on the Headscale server (ie. `ACL_FILE=/etc/headscale/acl_policy.json`).
+> For a breakdown of each configuration variable, please refer to the
+[Configuration](/docs/Configuration.md) guide. 
+> It explains what each variable does, how to configure them, and what the
+default values are.

docs/Configuration.md

@@ -9,11 +9,12 @@ You can configure Headplane using environment variables.
 
 #### Optional Variables
 
+- **`DEBUG`**: Enable debug logging (default: `false`).
 - **`HOST`**: The host to bind the server to (default: `0.0.0.0`).
 - **`PORT`**: The port to bind the server to (default: `3000`).
 - **`CONFIG_FILE`**: The path to the Headscale `config.yaml` (default: `/etc/headscale/config.yaml`).
-- **`ACL_FILE`**: The path to the ACL file (default: `/etc/headscale/acl_policy.json`, not needed if you have `acl_policy_path` in your config).
 - **`HEADSCALE_CONFIG_UNSTRICT`**: This will disable the strict configuration loader (default: `false`).
+- **`COOKIE_SECURE`**: This option enables the `Secure` flag for cookies, ensuring they are sent only over HTTPS, which helps prevent interception and enhances data security. It should be disabled when using HTTP instead of HTTPS (default: `true`).
 
 #### Docker Integration
 The Docker integration allows Headplane to manage the Headscale docker container.

docs/integration/Docker.md

@@ -0,0 +1,89 @@
+## Docker Integration
+
+The Docker integration allows you to run Headplane and Headscale separately
+in a dockerized environment. It allows you to unlock full functionality such as
+automatic reloading of ACLs, DNS management, and Headscale configuration
+management.
+
+### Deployment
+
+> When running with the Docker integration, it's assumed that both Headscale and
+Headplane will run as containers. If you are running Headscale natively, then
+refer to the [Native Integration](/docs/integration/Native.md) guide.
+
+To enable the Docker integration, set the `HEADSCALE_INTEGRATION` environment
+variable to `docker`. You'll also need to supply `HEADSCALE_CONTAINER` with the
+name or ID of the Headscale container.
+
+By default Headplane uses `unix:///var/run/docker.sock` to connect to Docker.
+This can be overridden by setting the `DOCKER_SOCK` environment variable. For
+example, a remote socket would be `tcp://<my-remote-host>:2375`. When setting
+the variable, you'll need to specify the protocol (`unix://` or `tcp://`).
+
+> The `DOCKER_SOCK` variable does not support the HTTPS protocol.
+
+To enable the Docker integration, set `HEADSCALE_INTEGRATION=docker` in the environment variables.
+Additionally, you'll need to pass in the `HEADSCALE_CONTAINER` environment variable.
+This should be either the name or ID of the Headscale container (you can retrieve this using `docker ps`).
+If the other integrations aren't setup, then Headplane will automatically disable the Docker integration.
+
+By default the integration will check for `/var/run/docker.sock`, however you can override this by
+setting the `DOCKER_SOCK` environment variable if you use a different configuration than the default.
+When setting `DOCKER_SOCK`, you'll need to include the protocol (e.g., `unix://` or `tcp://`).
+Headplane currently does not support the HTTPS protocol for the Docker socket.
+
+Here's an example deployment using Docker Compose (recommended). Keep in mind
+that you'll NEED to setup a reverse proxy and this is incomplete:
+```yaml
+services:
+  headscale:
+    image: 'headscale/headscale:0.23.0'
+    container_name: 'headscale'
+    restart: 'unless-stopped'
+    command: 'serve'
+    volumes:
+      - './data:/var/lib/headscale'
+      - './configs:/etc/headscale'
+    ports:
+      - '8080:8080'
+    environment:
+      TZ: 'America/New_York'
+  headplane:
+    container_name: headplane
+    image: ghcr.io/tale/headplane:0.3.0
+    restart: unless-stopped
+    volumes:
+      - './data:/var/lib/headscale'
+      - './configs:/etc/headscale'
+      - '/var/run/docker.sock:/var/run/docker.sock:ro'
+    ports:
+      - '3000:3000'
+    environment:
+      # This is always required for Headplane to work
+      COOKIE_SECRET: 'abcdefghijklmnopqrstuvwxyz'
+
+      HEADSCALE_INTEGRATION: 'docker'
+      HEADSCALE_CONTAINER: 'headscale'
+      DISABLE_API_KEY_LOGIN: 'true'
+      HOST: '0.0.0.0'
+      PORT: '3000'
+        
+      # Only set this to false if you aren't behind a reverse proxy
+      COOKIE_SECURE: 'false'
+
+      # Overrides the configuration file values if they are set in config.yaml
+      # If you want to share the same OIDC configuration you do not need this
+      OIDC_CLIENT_ID: 'headscale'
+      OIDC_ISSUER: 'https://sso.example.com'
+      OIDC_CLIENT_SECRET: 'super_secret_client_secret'
+
+      # This NEEDS to be set with OIDC, regardless of what's in the config
+      # This needs to be a very long-lived (999 day) API key used to create
+      # shorter ones for OIDC and allow the OIDC functionality to work
+      ROOT_API_KEY: 'abcdefghijklmnopqrstuvwxyz'
+```
+
+> For a breakdown of each configuration variable, please refer to the
+[Configuration](/docs/Configuration.md) guide. 
+> It explains what each variable does, how to configure them, and what the
+default values are.

docs/integration/Kubernetes.md

@@ -0,0 +1,133 @@
+## Kubernetes Integration
+
+The Kubernetes integration allows you to run Headplane and Headscale together
+in a cluster. It allows you to unlock full functionality such as automatic
+reloading of ACLs, DNS management, and Headscale configuration management.
+
+Currently there are a few limitations to the Kubernetes integration:
+- Headplane and Headscale need to run in the same Pod and share the same
+  process space for the integration to work correctly due to a limitation in
+  the Kubernetes API.
+
+- The only supported methods of deploying the integration are through a
+  `Deployment` or `Pod` (more coming soon). You can still get around this with
+  the `HEADSCALE_INTEGRATION_UNSTRICT` variable, but it's not recommended.
+
+- The integration will assume that the Headscale container will always restart
+  because the integration relies on a system call that will exit the container.
+
+### Deployment
+
+In order to ensure Headplane can read Kubernetes resources, you'll need to
+grant additional RBAC permissions to the default `ServiceAccount` in the
+namespace. This can be done with the following:
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: headplane-agent
+  namespace: default # Adjust namespace as needed
+rules:
+- apiGroups: ['']
+  resources: ['pods']
+  verbs: ['get', 'list']
+- apiGroups: ['apps']
+  resources: ['deployments']
+  verbs: ['get', 'list']
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: headplane-agent
+  namespace: default # Adjust namespace as needed
+roleRef:
+    apiGroup: rbac.authorization.k8s.io
+    kind: Role
+    name: headplane-agent
+subjects:
+- kind: ServiceAccount
+  name: default # If you use a different service account, change this
+  namespace: default # Adjust namespace as needed
+```
+
+Keep in mind you'll need to make `PersistentVolumeClaim`s for the data and that
+they need to be either `ReadWriteOnce` or `ReadWriteMany` depending on your
+topology. Additionally, you can abstract environment variables and configuration
+away into a `ConfigMap` or `Secret` for easier management.
+
+The important parts of this deployment are the `HEADSCALE_INTEGRATION` and
+`DEPLOYMENT_NAME` environment variables. The `HEADSCALE_INTEGRATION` variable
+should be set to `kubernetes` and the `POST_NAME` variable should be set
+to the name of the pod (done using the Downward API below).
+
+> If you are having issues with validating `shareProcessNamespace`, you can
+set `HEADSCALE_INTEGRATION_UNSTRICT` to `true` to disable the strict checks.
+
+A basic deployment of the integration would look like this. Keep in mind that
+you are responsible for setting up a reverse-proxy via an `Ingress` or `Service`
+otherwise Headplane will not work:
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: headplane
+  namespace: default # Adjust namespace as needed
+  labels:
+    app: headplane
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: headplane
+  template:
+    metadata:
+      labels:
+        app: headplane
+    spec:
+      shareProcessNamespace: true
+      serviceAccountName: default
+      containers:
+      - name: headplane
+        image: ghcr.io/tale/headplane:0.3.0
+        env:
+        - name: COOKIE_SECRET
+          value: 'abcdefghijklmnopqrstuvwxyz'
+        - name: HEADSCALE_INTEGRATION
+          value: 'kubernetes'
+        - name: POD_NAME
+          valueFrom:
+            fieldRef:
+              fieldPath: metadata.name
+
+          # Only set this to false if you aren't behind a reverse proxy
+        - name: COOKIE_SECURE
+          value: 'false'
+        volumeMounts:
+        - name: headscale-config
+          mountPath: /etc/headscale
+
+      - name: headscale
+        image: headscale/headscale:0.23.0
+        command: ['serve']
+        env:
+        - name: TZ
+          value: 'America/New_York'
+        volumeMounts:
+        - name: headscale-data
+          mountPath: /var/lib/headscale
+        - name: headscale-config
+          mountPath: /etc/headscale
+
+      volumes:
+        - name: headscale-data
+          persistentVolumeClaim:
+            claimName: headscale-data
+        - name: headscale-config
+          persistentVolumeClaim:
+            claimName: headscale-config
+```
+
+> For a breakdown of each configuration variable, please refer to the
+[Configuration](/docs/Configuration.md) guide. 
+> It explains what each variable does, how to configure them, and what the
+default values are.

docs/integration/Native.md

@@ -0,0 +1,28 @@
+## Native Integration
+
+The Native integration allows you to run both Headplane and Headscale on
+bare-metal servers or virtual machines. This integration is best suited for
+environments where Docker or Kubernetes are not available or not desired.
+
+Currently the Native integration only supports automatic reloading of ACLs. It
+cannot handle configuration changes as killing the `headscale` process can lead
+to undefined behavior or the service not restarting.
+
+### Deployment
+
+Follow the instructions to install Headscale from the
+[Linux Installation Guide](https://headscale.net/running-headscale-linux/). As
+of now, Headplane requires Node.js 20 to be installed on the system. Once you
+are ready, clone the repository (`git clone https://github.com/tale/headplane`),
+install dependencies (`npm install`), build the project (`npm run build`), and
+start the server (`npm start`).
+
+> If you'd like, you can turn this into a `systemd` unit to manage the service.
+> I plan to provide packages and unit files to make this easier in the future.
+
+When running Headplane, you'll need to set environment variables to configure
+the application. The `HEADSCALE_INTEGRATION` variable should be set to `proc`.
+
+> For a breakdown of each configuration variable, please refer to the
+[Configuration](/docs/Configuration.md) guide. 
+> It explains what each variable does, how to configure them, and what the default values are.

package.json

@@ -15,6 +15,7 @@
 		"@dnd-kit/modifiers": "^7.0.0",
 		"@dnd-kit/sortable": "^8.0.0",
 		"@dnd-kit/utilities": "^3.2.2",
+		"@kubernetes/client-node": "^0.21.0",
 		"@monaco-editor/react": "^4.6.0",
 		"@primer/octicons-react": "^19.10.0",
 		"@react-aria/toast": "3.0.0-beta.12",
@@ -50,7 +51,7 @@
 		"typescript": "^5.5.3",
 		"vite": "^5.3.3",
 		"vite-plugin-babel": "^1.2.0",
-		"vite-tsconfig-paths": "^4.2.1"
+		"vite-tsconfig-paths": "^4.3.2"
 	},
 	"overrides": {
 		"@types/react": "npm:types-react@beta",

test/config.yaml

@@ -186,7 +186,8 @@ log:
 # Path to a file containg ACL policies.
 # ACLs can be defined as YAML or HUJSON.
 # https://tailscale.com/kb/1018/acls/
-acl_policy_path: /etc/headscale/acl.json
+policy:
+  mode: 'database'
 
 ## DNS
 #
@@ -197,7 +198,7 @@ acl_policy_path: /etc/headscale/acl.json
 # - https://tailscale.com/kb/1081/magicdns/
 # - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
 #
-dns_config:
+dns_config2:
   # Whether to prefer using Headscale provided DNS or use local.
   override_local_dns: true
 
@@ -253,6 +254,68 @@ dns_config:
   # The FQDN of the hosts will be
   # `hostname.user.base_domain` (e.g., _myhost.myuser.example.com_).
   base_domain: ts.net
+  extra_records:
+    - name: test.example.com
+      type: A
+      value: 1.1.1.1
+
+dns:
+  # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
+  # Only works if there is at least a nameserver defined.
+  magic_dns: true
+
+  # Defines the base domain to create the hostnames for MagicDNS.
+  # This domain _must_ be different from the server_url domain.
+  # `base_domain` must be a FQDN, without the trailing dot.
+  # The FQDN of the hosts will be
+  # `hostname.base_domain` (e.g., _myhost.example.com_).
+  base_domain: example.com
+
+  # List of DNS servers to expose to clients.
+  nameservers:
+    global:
+      - 1.1.1.1
+      - 1.0.0.1
+      - 2606:4700:4700::1111
+      - 2606:4700:4700::1001
+
+      # NextDNS (see https://tailscale.com/kb/1218/nextdns/).
+      # "abc123" is example NextDNS ID, replace with yours.
+      # - https://dns.nextdns.io/abc123
+
+    # Split DNS (see https://tailscale.com/kb/1054/dns/),
+    # a map of domains and which DNS server to use for each.
+    split:
+      {}
+      # foo.bar.com:
+      #   - 1.1.1.1
+      # darp.headscale.net:
+      #   - 1.1.1.1
+      #   - 8.8.8.8
+
+  # Set custom DNS search domains. With MagicDNS enabled,
+  # your tailnet base_domain is always the first search domain.
+  search_domains: []
+
+  # Extra DNS records
+  # so far only A-records are supported (on the tailscale side)
+  # See https://github.com/juanfont/headscale/blob/main/docs/dns-records.md#Limitations
+  extra_records: []
+  #   - name: "grafana.myvpn.example.com"
+  #     type: "A"
+  #     value: "100.64.0.3"
+  #
+  #   # you can also put it in one line
+  #   - { name: "prometheus.myvpn.example.com", type: "A", value: "100.64.0.3" }
+
+  # DEPRECATED
+  # Use the username as part of the DNS name for nodes, with this option enabled:
+  # node1.username.example.com
+  # while when this is disabled:
+  # node1.example.com
+  # This is a legacy option as Headscale has have this wrongly implemented
+  # while in upstream Tailscale, the username is not included.
+  use_username_in_magic_dns: false
 
 # Unix socket used for the CLI to connect without authentication
 # Note: for production you will want to set this to something like:
@@ -268,46 +331,46 @@ oidc:
   issuer: "https://sso.example.com"
   client_id: "headscale"
   client_secret: "super_secret_client_secret"
-#   # Alternatively, set `client_secret_path` to read the secret from the file.
-#   # It resolves environment variables, making integration to systemd's
-#   # `LoadCredential` straightforward:
-#   client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
-#   # client_secret and client_secret_path are mutually exclusive.
-#
-#   # The amount of time from a node is authenticated with OpenID until it
-#   # expires and needs to reauthenticate.
-#   # Setting the value to "0" will mean no expiry.
+  #   # Alternatively, set `client_secret_path` to read the secret from the file.
+  #   # It resolves environment variables, making integration to systemd's
+  #   # `LoadCredential` straightforward:
+  #   client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
+  #   # client_secret and client_secret_path are mutually exclusive.
+  #
+  #   # The amount of time from a node is authenticated with OpenID until it
+  #   # expires and needs to reauthenticate.
+  #   # Setting the value to "0" will mean no expiry.
   expiry: 180d
-#
-#   # Use the expiry from the token received from OpenID when the user logged
-#   # in, this will typically lead to frequent need to reauthenticate and should
-#   # only been enabled if you know what you are doing.
-#   # Note: enabling this will cause `oidc.expiry` to be ignored.
-#   use_expiry_from_token: false
-#
-#   # Customize the scopes used in the OIDC flow, defaults to "openid", "profile" and "email" and add custom query
-#   # parameters to the Authorize Endpoint request. Scopes default to "openid", "profile" and "email".
-#
-#   scope: ["openid", "profile", "email", "custom"]
-#   extra_params:
-#     domain_hint: example.com
-#
-#   # List allowed principal domains and/or users. If an authenticated user's domain is not in this list, the
-#   # authentication request will be rejected.
-#
+  #
+  #   # Use the expiry from the token received from OpenID when the user logged
+  #   # in, this will typically lead to frequent need to reauthenticate and should
+  #   # only been enabled if you know what you are doing.
+  #   # Note: enabling this will cause `oidc.expiry` to be ignored.
+  #   use_expiry_from_token: false
+  #
+  #   # Customize the scopes used in the OIDC flow, defaults to "openid", "profile" and "email" and add custom query
+  #   # parameters to the Authorize Endpoint request. Scopes default to "openid", "profile" and "email".
+  #
+  #   scope: ["openid", "profile", "email", "custom"]
+  #   extra_params:
+  #     domain_hint: example.com
+  #
+  #   # List allowed principal domains and/or users. If an authenticated user's domain is not in this list, the
+  #   # authentication request will be rejected.
+  #
   allowed_domains:
     - example.com
-#   # Note: Groups from keycloak have a leading '/'
-#   allowed_groups:
-#     - /headscale
-#   allowed_users:
-#     - alice@example.com
-#
-#   # If `strip_email_domain` is set to `true`, the domain part of the username email address will be removed.
-#   # This will transform `first-name.last-name@example.com` to the user `first-name.last-name`
-#   # If `strip_email_domain` is set to `false` the domain part will NOT be removed resulting to the following
-#   user: `first-name.last-name.example.com`
-#
+  #   # Note: Groups from keycloak have a leading '/'
+  #   allowed_groups:
+  #     - /headscale
+  #   allowed_users:
+  #     - alice@example.com
+  #
+  #   # If `strip_email_domain` is set to `true`, the domain part of the username email address will be removed.
+  #   # This will transform `first-name.last-name@example.com` to the user `first-name.last-name`
+  #   # If `strip_email_domain` is set to `false` the domain part will NOT be removed resulting to the following
+  #   user: `first-name.last-name.example.com`
+  #
   strip_email_domain: true
 
 # Logtail configuration