100 Commits

This Branch

This Branch

All Branches

Author	SHA1	Message	Date
Florian Preinstorfer	32e1d77663	Install config-example.yaml as example for the debian package ... The directory /usr/share/doc/headscale/examples may be used to install arbitrary example files. This is useful to get a matching configuration for the release which gets also overwritten automatically.	2026-04-13 20:49:39 +02:00
Florian Preinstorfer	61c9ae81e4	Remove old migrations for the debian package ... Those were required to streamline new installs with updates before 0.27. Since 0.29 will not allow direct upgrades from <0.27 to 0.29 we might as well remove it.	2026-04-11 20:35:15 +02:00
Florian Preinstorfer	23a5f1b628	Use pymdownx.magiclink with its default configuration ... The docs contain bare links that are not rendered without it.	2026-04-02 21:24:27 +02:00
Florian Preinstorfer	44600550c6	Fix invisible selected menu item ... A light background with white primary font makes the selected menu entry unreadable.	2026-04-02 21:24:27 +02:00
Florian Preinstorfer	f3512d50df	Switch to mkdocs-materialx ... The project mkdocs-material is in maintenance-only mode and their successor is not ready yet. Use the modern, refreshed theme and drop the pymdownx.magiclink extension.	2026-03-25 22:30:03 +01:00
Florian Preinstorfer	efd83da14e	Explicitly mention that a headscale username should *not* end with @ ... See: #3149	2026-03-20 19:44:33 +01:00
Florian Preinstorfer	9baa795ddb	Update docs for auth-id changes ... - Replace "headscale nodes register" with "headscale auth register" - Update from registration key to Auth ID - Fix API example to register a node	2026-03-01 13:38:22 +01:00
Florian Preinstorfer	acddd73183	Reformat docs with mdformat	2026-03-01 09:24:52 +01:00
Florian Preinstorfer	47307d19cf	Switch to mdformat to format docs ... - Use mdformat and mdformat-mkdocs to format docs - Add mdformat to Makefile and pre-commit-config - Prettier ignores docs/	2026-03-01 09:24:52 +01:00
Florian Preinstorfer	cfb308b4a7	Add FAQ entry to migrate back to default IP prefixes	2026-02-19 17:16:40 +01:00
Florian Preinstorfer	4bb0241257	Require to update from one version to the next	2026-02-19 17:16:40 +01:00
Florian Preinstorfer	513544cc11	Simplify upgrade snippet with a link to the upgrade guide ... Remove some duplicated text.	2026-02-19 17:16:40 +01:00
Florian Preinstorfer	d556df1c36	Extend upgrade guide with backup instructions	2026-02-19 17:16:40 +01:00
Florian Preinstorfer	faf55f5e8f	Document how to use the provider identifier in the policy	2026-02-18 10:24:05 +01:00
Florian Preinstorfer	e3323b65e5	Describe how to set username instead of SPN for Kanidm	2026-02-18 10:24:05 +01:00
Florian Preinstorfer	8f60b819ec	Refresh update path	2026-02-16 15:22:46 +01:00
Florian Preinstorfer	c29bcd2eaf	Release planning happens in milestones	2026-02-16 15:22:46 +01:00
Florian Preinstorfer	890a044ef6	Add more UIs	2026-02-16 15:22:46 +01:00
Florian Preinstorfer	8028fa5483	No longer consider autogroup:self experimental	2026-02-16 15:22:46 +01:00
Florian Preinstorfer	9e50071df9	Link Fosdem 2026 talk	2026-02-05 08:01:02 +01:00
Florian Preinstorfer	c907b0d323	Fix version in mkdocs	2026-02-05 08:01:02 +01:00
Florian Preinstorfer	5d300273dc	Add a tags page and describe a few common operations	2026-01-28 15:52:57 +01:00
Florian Preinstorfer	7f003ecaff	Add a page to describe supported registration methods	2026-01-28 15:52:57 +01:00
Florian Preinstorfer	2695d1527e	Use registration key instead of machine key	2026-01-28 15:52:57 +01:00
Florian Preinstorfer	d32f6707f7	Add missing words	2026-01-28 15:52:57 +01:00
Florian Preinstorfer	89e436f0e6	Bump year/version for mkdocs	2026-01-28 15:52:57 +01:00
Florian Preinstorfer	49b70db7f2	Conversion from personal to tagged node is reversible	2026-01-24 17:18:59 +01:00
Florian Preinstorfer	04b4071888	Fix node expiration success message ... A node is expired when the requested expiration is either now or in the past.	2026-01-24 15:18:12 +01:00
Florian Preinstorfer	ee127edbf7	Remove trace log for preauthkeys create ... This always prints a TRC message on `preauthkeys create`. Since we don't print anything for `apikeys create` either we might as well remove it.	2026-01-23 08:40:09 +01:00
Florian Preinstorfer	18e13f6ffa	Link to headscale.net for docs	2026-01-16 14:54:04 +01:00
Florian Preinstorfer	a445278f76	Mention tags on the features page	2026-01-16 14:54:04 +01:00
Florian Preinstorfer	8387c9cd82	Fix ownership description for auto approved routers/exits ... Just the tags tag:router and tag:exit are owned by alice. Upon join, those nodes will have their ownership transferred from alice to the system user "tagged-devices".	2026-01-16 14:54:04 +01:00
Florian Preinstorfer	25a7434830	Bump version in mkdocs	2026-01-16 14:54:04 +01:00
Florian Preinstorfer	183a38715c	Fix list-routes examples	2026-01-16 14:54:04 +01:00
Florian Preinstorfer	99d35fbbbc	Document oidc.email_verification_required	2026-01-16 14:54:04 +01:00
Florian Preinstorfer	d50108c722	Changelog: mark oidc.email_verified_required as breaking ... Headscale is now stricter and this is a breaking change if authorization filters are used and at least one user has an unverified email address.	2026-01-16 14:54:04 +01:00
Florian Preinstorfer	6d21a4a3fe	Document /version in the API docs	2026-01-16 14:54:04 +01:00
Florian Preinstorfer	7d81dca9aa	Document how to disable the metrics interfaces	2026-01-16 14:54:04 +01:00
Florian Preinstorfer	c3e2e57f8e	Clarify autogroup:member ... Fixes: #3007	2026-01-14 12:44:18 +01:00
Florian Preinstorfer	9146140217	Add headscale-operator ... Ref: #1523	2025-12-23 20:22:57 +01:00
Florian Preinstorfer	5c6cd62df1	Legacy preauthkeys must be used as-is	2025-12-17 13:05:08 +01:00
Florian Preinstorfer	bba91a89be	Use lists for integration docs ... Refactor the tables in "Tools" and "WebUI" integration pages to lists. Lists are easier to extend and contributions are easier to review.	2025-12-08 12:50:19 +01:00
Florian Preinstorfer	6359511a62	Use debian13 distroless images	2025-12-07 20:58:29 +01:00
Florian Preinstorfer	f00c412cde	Move static doc assets into docs/assets	2025-11-28 21:27:54 +01:00
Florian Preinstorfer	2010805712	Provide Headscale's favicon at its expected place ... Assets need to reside within the docs/ directory for mkdocs to pick them up.	2025-11-28 21:27:54 +01:00
Florian Preinstorfer	c5133ee5d3	Fix trailing whitespace	2025-11-28 21:27:54 +01:00
Florian Preinstorfer	9c33cbfdc8	Exclude docs/ only for prettier pre-commit hook ... Applying the the built-in hooks to docs/ seems to be fine.	2025-11-28 21:27:54 +01:00
Florian Preinstorfer	9b327f6b56	Update pre-commit-hooks	2025-11-28 21:27:54 +01:00
Florian Preinstorfer	72d5fd04a7	Remove duplicated documentation and link to getting started instead	2025-11-18 11:07:49 +01:00
Florian Preinstorfer	e86d063056	Mention /health instead of /windows	2025-11-18 11:07:49 +01:00
Florian Preinstorfer	21af106f68	Containers should be read-only ... This improves security and explicitly fails on startup when a user picks the wrong directory to store its data. - Run in read-only mode - Make /var/run/headscale a read-write tmpfs - Mount the config volume read-only - Use the /health endpoint to check if Headscale is up	2025-11-14 14:51:27 +01:00
Florian Preinstorfer	249630bed8	Add API documentation ... Document the API endpoint and the built-in swagger docs at /swagger. The remote control docs are just a use case for gRPC - move it in the API docs and update links to it.	2025-11-13 15:22:55 +01:00
Florian Preinstorfer	abed534628	Document how to restrict access to exit nodes per user/group ... Updates: #2855 Ref: #2784	2025-11-11 11:51:35 +01:00
Florian Preinstorfer	0a43aab8f5	Use Debian 12 as minimum version for the deb package	2025-10-28 05:55:26 +01:00
Florian Preinstorfer	4bd614a559	Use current stable base images for Debian and Alpine	2025-10-28 05:55:26 +01:00
Florian Preinstorfer	8becb7e54a	Mention explicitly that @ is only required in policy	2025-10-21 14:28:03 +02:00
Florian Preinstorfer	ed38d00aaa	Fix autogroup:self alternative example ... Also indent and split the comment into two lines to avoid horizontal scrolling.	2025-10-21 14:28:03 +02:00
Florian Preinstorfer	8010cc574e	Remove outdated hint about an empty config file	2025-10-19 17:14:15 +02:00
Florian Preinstorfer	047dbda136	Add FAQ on how to disable log submission ... Fixes: #2793	2025-10-19 08:24:23 +02:00
Florian Preinstorfer	2a1392fb5b	Add healthcheck to container docs	2025-10-19 08:22:30 +02:00
Florian Preinstorfer	46477b8021	Downgrade completed broadcast message to debug	2025-10-18 07:56:59 +02:00
Florian Preinstorfer	881a6b9227	The sequential prefix allocation uses a best-effort approach ... Fixes: #2682	2025-10-15 17:07:13 +02:00
Florian Preinstorfer	bd35fcf338	Add FAQ entry about policy migration in the database	2025-09-17 16:32:29 +02:00
Florian Preinstorfer	2d680b5ebb	Misc typos and spelling	2025-09-17 16:32:29 +02:00
Florian Preinstorfer	30d12dafed	Add FAQ entry about the recommended upgrade path	2025-09-13 08:15:01 +02:00
Florian Preinstorfer	c6427aa296	Use group id instead of group name for Entra ID	2025-09-09 12:23:34 +02:00
Florian Preinstorfer	4e6d42d5bd	Keycloak's group format is configurable	2025-09-09 12:23:34 +02:00
Florian Preinstorfer	8ff5baadbe	Refresh OIDC docs ... The UserInfo endpoint is always queried since 5d8a2c2. This allows to use all OIDC related features without any extra configuration on Authelia. For Keycloak, its sufficient to add the groups mapper to the userinfo endpoint.	2025-09-09 12:23:34 +02:00
Florian Preinstorfer	2f3c365b68	Describe how to remove a DERP region ... Add documentation for d29feaef. Fixes: #2450	2025-09-09 11:05:30 +02:00
Florian Preinstorfer	e949859d33	Add DERP docs	2025-08-22 12:09:31 +02:00
Florian Preinstorfer	4d61da30d0	Use an IPv4 address range suitable for documentation	2025-08-22 12:09:31 +02:00
Florian Preinstorfer	be337c6a33	Enable derp.server.verify_clients by default ... This setting is already enabled in example-config.yaml but would default to false if no key is set.	2025-08-19 11:30:44 +02:00
Florian Preinstorfer	7b8b796a71	docs: connect Android using a preauthkey ... Fixes: #2616	2025-08-18 16:06:17 +02:00
Florian Preinstorfer	30a1f7e68e	Log registrationID to simplify interactive node registration ... Some clients such as Android make it hard to transfer the registrationID to the server, its easier to get it from the server logs.	2025-08-15 17:11:38 +02:00
Florian Preinstorfer	30cec3aa2b	Document ports in use ... Ref: #1767	2025-08-14 09:24:09 +02:00
Florian Preinstorfer	bcd80ee773	Add debugging and troubleshooting guide	2025-07-22 14:56:45 +02:00
Florian Preinstorfer	c04e17d82e	Document valid log levels ... Also change the order as the level seems more important than the format.	2025-07-22 14:56:45 +02:00
Florian Preinstorfer	98fc0563ac	Bump version in docs	2025-07-22 14:56:45 +02:00
Florian Preinstorfer	a98d9bd05f	The preauthkeys commands expect a user id instead of a username	2025-07-16 09:53:05 +02:00
Florian Preinstorfer	46c59a3fff	Fix command in bug report template	2025-07-15 21:12:32 +02:00
Florian Preinstorfer	d461db3abd	Refactor OpenID Connect documentation ... Restructure and rewrite the OpenID Connect documentation. Start from the most minimal configuration and describe what needs to be done both in Headscale and the identity provider. Describe additional features such as PKCE and authorization filters in a generic manner with examples. Document how Headscale populates its user profile and how it relates to OIDC claims. This is a revised version from the table in the changelog. Document the validation rules for fields and extend known limitations. Sort the provider specific section alphabetically and add a section for Authelia, Authentik, Kanidm and Keycloak. Also simplify and rename Azure to Entra ID. Update the description for the oidc section in the example configuration. Give a short explanation of each configuration setting. All documentend features were tested with Headscale 0.26 (using a fresh database each time) using the following identity providers: * Authelia * Authentik * Kanidm * Keycloak Fixes: #2295	2025-07-04 10:51:37 +02:00
Florian Preinstorfer	cd704570be	Drop support for Ubuntu 20.04 ... Its old and our service file logs warning about unsupported options.	2025-05-21 15:40:32 +02:00
Florian Preinstorfer	43c9c50af4	Drop syslog.target and systemd-managed /var/run ... The systemd target "syslog.target" and not required because syslog is socket activated. The directory /var/run is usually a symlink to /run and its created by systemd via the RuntimeDirectory=headscale option. System creates and handles permissions, no need to manually mark it as a read-write path.	2025-05-21 15:40:32 +02:00
Florian Preinstorfer	4a941a2cb4	Refactor Debian/Ubuntu package ... Move files for packaging outside the docs directory into its own packaging directory. Replace the existing postinstall and postremove scripts with Debian maintainerscripts to behave more like a typical Debian package: * Start and enable the headscale systemd service by default * Does not print informational messages * No longer stop and disable the service on updates This package also performs migrations for all changes done in previous package versions on upgrade: * Set login shell to /usr/sbin/nologin * Set home directory to /var/lib/headscale * Migrate to system UID/GID The package is lintian-clean with a few exceptions that are documented as excludes and it passes puipars (both tested on Debian 12). The following scenarious were tested on Ubuntu 22.04, Ubuntu 24.04, Debian 11, Debian 12: * Install * Install same version again * Install -> Remove -> Install * Install -> Purge -> Install * Purge * Update from 0.22.0 * Update from 0.26.0 See: #2278 See: #2133 Fixes: #2311	2025-05-21 15:40:32 +02:00
Florian Preinstorfer	b50e10a1be	Document breaking change for dns.override_local_dns ... See: #2438	2025-05-16 19:33:00 +02:00
Florian Preinstorfer	c15aa541bb	Document HEADSCALE_CONFIG	2025-05-16 19:33:00 +02:00
Florian Preinstorfer	49b3468845	Do not ignore config-example.yml ... Various tools (e.g ripgrep) skip files ignored by Git. Do not ignore config-example.yml to include it in searches.	2025-05-16 19:33:00 +02:00
Florian Preinstorfer	707438f25e	Mention that private keys generated if needed	2025-03-19 06:12:14 +01:00
Florian Preinstorfer	24ad235917	Explicitly handle /headscale/{config,lib,run} in container docs ... Fixes: #2304	2025-03-19 06:12:14 +01:00
Florian Preinstorfer	cbce8f6011	Remove coderabbit ... It is no longer available for free and didn't do anything in the past months.	2025-03-16 14:02:33 +01:00
Florian Preinstorfer	05202099f7	Set content-type to JSON for some debug endpoints ... Some endpoints in /debug send JSON data as string. Set the Content-Type header to "application/json" which renders nicely in Firefox. Mention the /debug route in the example configuration.	2025-03-16 14:02:12 +01:00
Florian Preinstorfer	586a20fbff	Add a FAQ entry about two nodes seeing each other ... See: #2431 See: #2174	2025-03-14 18:48:44 +01:00
Florian Preinstorfer	0a243b4162	Remove leftover printf	2025-03-10 16:52:29 +01:00
Florian Preinstorfer	29ba29478b	Add usage example to routes flag	2025-03-10 16:52:29 +01:00
Florian Preinstorfer	e52f1e87ce	Drop routes table	2025-03-10 16:52:29 +01:00
Florian Preinstorfer	f12cb2e048	Headscale now updates the user profile	2025-02-05 11:05:03 +01:00
Florian Preinstorfer	8c09afe20c	Headscale implements a single tailnet ... Separate the term "tailnet" from user and be more explicit about providing a single tailnet. Also be more explicit about users. Refer to "headscale users" when mentioning commandline invocations and use the term "local users" when discussing unix accounts. Fixes: #2335	2025-02-05 11:05:03 +01:00
Florian Preinstorfer	bbc93a90a2	Set title for code listings	2024-12-17 14:08:34 +01:00
Florian Preinstorfer	0acb2b5647	Misc doc updates	2024-12-17 14:08:34 +01:00
Florian Preinstorfer	3269cfdca0	Mention reload and SIGHUP when editing the ACL policy file ... Fixes: #2284	2024-12-17 14:08:34 +01:00