starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-11 20:00:28 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

[PR #2897] [MERGED] Add docs about how to communicate with the service as non headscale local user #2926

New Issue
Closed
opened 2025-12-29 04:19:41 +01:00 by adam · 0 comments
adam commented 2025-12-29 04:19:41 +01:00
Owner
Copy Link

📋 Pull Request Information

Original PR: https://github.com/juanfont/headscale/pull/2897
Author: @antaljanosbenjamin
Created: 11/15/2025
Status: ✅ Merged
Merged: 11/24/2025
Merged by: @nblock

Base: main ← Head: docs-about-access-unix-socket

📝 Commits (1)

  • 7258746 Add docs to manage headscale from another local user

📊 Changes

1 file changed (+17 additions, -0 deletions)

View changed files

📝 docs/usage/getting-started.md (+17 -0)

📄 Description

  • have read the CONTRIBUTING.md file
  • raised a GitHub issue or discussed it on the projects chat beforehand
  • added unit tests
  • added integration tests
  • updated documentation if needed
  • updated CHANGELOG.md

With a freshly installed headscale it is not possible to communicate with the headscale service unless the user is added into the headscale group. I added a small section about this in the documentation, because I have run into this issue:

user@host:~$ sudo dpkg -i headscale_0.27.1_linux_amd64.deb 
[sudo] password for user: 
Selecting previously unselected package headscale.
(Reading database ... 33581 files and directories currently installed.)
Preparing to unpack headscale_0.27.1_linux_amd64.deb ...
Unpacking headscale (0.27.1) ...
Setting up headscale (0.27.1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/headscale.service → /lib/systemd/system/headscale.service.
user@host:~$ sudo systemctl status headscale
● headscale.service - headscale coordination server for Tailscale
     Loaded: loaded (/lib/systemd/system/headscale.service; enabled; preset: enabled)
     Active: active (running) since Sat 2025-11-15 20:00:59 CET; 21s ago
   Main PID: 734 (headscale)
      Tasks: 9 (limit: 9482)
     Memory: 15.3M
        CPU: 108ms
     CGroup: /system.slice/headscale.service
             └─734 /usr/bin/headscale serve

Nov 15 20:00:59 user systemd[1]: Started headscale.service - headscale coordination server for Tailscale.
Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF No private key file at path, creating... path=/var/lib/headscale/noise_private.key
Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite
Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF Starting schema recreation with table renaming
Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF Schema recreation completed successfully
Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF Starting Headscale commit=f658a8eacd4d86edc65424b50635afed46ca4b2a version=v0.27.1+dirty
Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF Clients with a lower minimum version will be rejected minimum_version=v1.64.0
Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF listening and serving HTTP on: 127.0.0.1:8080
Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF listening and serving debug and metrics on: 127.0.0.1:9090
user@host:~$ headscale status
Error: unknown command "status" for "headscale"
Run 'headscale --help' for usage.
unknown command "status" for "headscale"
user@host:~$ headscale user list
2025-11-15T20:01:41+01:00 FTL Unable to read/write to headscale socket, do you have the correct permissions? error="open /var/run/headscale/headscale.sock: permission denied" socket=/var/run/headscale/headscale.sock

I haven't ticked all the boxes, because I think they don't apply.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/juanfont/headscale/pull/2897 **Author:** [@antaljanosbenjamin](https://github.com/antaljanosbenjamin) **Created:** 11/15/2025 **Status:** ✅ Merged **Merged:** 11/24/2025 **Merged by:** [@nblock](https://github.com/nblock) **Base:** `main` ← **Head:** `docs-about-access-unix-socket` --- ### 📝 Commits (1) - [`7258746`](https://github.com/juanfont/headscale/commit/7258746cb06bae6813b0ea491ad6f2e1b56d60a5) Add docs to manage headscale from another local user ### 📊 Changes **1 file changed** (+17 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/usage/getting-started.md` (+17 -0) </details> ### 📄 Description <!-- Headscale is "Open Source, acknowledged contribution", this means that any contribution will have to be discussed with the Maintainers before being submitted. This model has been chosen to reduce the risk of burnout by limiting the maintenance overhead of reviewing and validating third-party code. Headscale is open to code contributions for bug fixes without discussion. If you find mistakes in the documentation, please submit a fix to the documentation. --> <!-- Please tick if the following things apply. You… --> - [X] have read the [CONTRIBUTING.md](./CONTRIBUTING.md) file - [ ] raised a GitHub issue or discussed it on the projects chat beforehand - [ ] added unit tests - [ ] added integration tests - [ ] updated documentation if needed - [ ] updated CHANGELOG.md <!-- If applicable, please reference the issue using `Fixes #XXX` and add tests to cover your new code. --> With a freshly installed headscale it is not possible to communicate with the headscale service unless the user is added into the `headscale` group. I added a small section about this in the documentation, because I have run into this issue: ``` user@host:~$ sudo dpkg -i headscale_0.27.1_linux_amd64.deb [sudo] password for user: Selecting previously unselected package headscale. (Reading database ... 33581 files and directories currently installed.) Preparing to unpack headscale_0.27.1_linux_amd64.deb ... Unpacking headscale (0.27.1) ... Setting up headscale (0.27.1) ... Created symlink /etc/systemd/system/multi-user.target.wants/headscale.service → /lib/systemd/system/headscale.service. user@host:~$ sudo systemctl status headscale ● headscale.service - headscale coordination server for Tailscale Loaded: loaded (/lib/systemd/system/headscale.service; enabled; preset: enabled) Active: active (running) since Sat 2025-11-15 20:00:59 CET; 21s ago Main PID: 734 (headscale) Tasks: 9 (limit: 9482) Memory: 15.3M CPU: 108ms CGroup: /system.slice/headscale.service └─734 /usr/bin/headscale serve Nov 15 20:00:59 user systemd[1]: Started headscale.service - headscale coordination server for Tailscale. Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF No private key file at path, creating... path=/var/lib/headscale/noise_private.key Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF Starting schema recreation with table renaming Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF Schema recreation completed successfully Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF Starting Headscale commit=f658a8eacd4d86edc65424b50635afed46ca4b2a version=v0.27.1+dirty Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF Clients with a lower minimum version will be rejected minimum_version=v1.64.0 Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF listening and serving HTTP on: 127.0.0.1:8080 Nov 15 20:00:59 user headscale[734]: 2025-11-15T20:00:59+01:00 INF listening and serving debug and metrics on: 127.0.0.1:9090 user@host:~$ headscale status Error: unknown command "status" for "headscale" Run 'headscale --help' for usage. unknown command "status" for "headscale" user@host:~$ headscale user list 2025-11-15T20:01:41+01:00 FTL Unable to read/write to headscale socket, do you have the correct permissions? error="open /var/run/headscale/headscale.sock: permission denied" socket=/var/run/headscale/headscale.sock ``` I haven't ticked all the boxes, because I think they don't apply. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
adam added the pull-request label 2025-12-29 04:19:41 +01:00
adam closed this issue 2025-12-29 04:19:41 +01:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#2926
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?