feat: Create headscale user and group as system user/groups

[jyundt]

When creating the headscale user and group, create both as system groups rather than creating them as 'user' groups.

FIXES #2278

• 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

[jyundt]

Tested the new postinst, UID/GID looks good:

root@aa9aa3bd9af8:~# id headscale
uid=999(headscale) gid=999(headscale) groups=999(headscale)
root@aa9aa3bd9af8:~#

[kradalby]

How will this impact already created users?

[jyundt]

How will this impact already created users?

@kradalby existing users/groups will not be modified by this change, they will remain with their non-System UIDs/GIDs.

Example:

root@e55169df78a2:/tmp# apt install ./headscale_0.24.0-beta.1_linux_amd64.deb 
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Note, selecting 'headscale' instead of './headscale_0.24.0-beta.1_linux_amd64.deb'
The following NEW packages will be installed:
  headscale
0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded.
Need to get 0 B/18.5 MB of archives.
After this operation, 52.0 MB of additional disk space will be used.
Get:1 /tmp/headscale_0.24.0-beta.1_linux_amd64.deb headscale amd64 0.24.0~beta.1 [18.5 MB]
debconf: delaying package configuration, since apt-utils is not installed
Selecting previously unselected package headscale.
(Reading database ... 4393 files and directories currently installed.)
Preparing to unpack .../headscale_0.24.0-beta.1_linux_amd64.deb ...
Unpacking headscale (0.24.0~beta.1) ...
Setting up headscale (0.24.0~beta.1) ...
Sudo permissions detected
Found headscale /usr/bin/headscale
PostInstall: Adding headscale user headscale
PostInstall: Creating headscale run directory 
PostInstall: Modifying group ownership of headscale run directory 
----------------------------------------------------------------------
 headscale package has been successfully installed.

 Please follow the next steps to start the software:

    sudo systemctl enable headscale
    sudo systemctl start headscale

 Configuration settings can be adjusted here:
    /etc/headscale/config.yaml

----------------------------------------------------------------------
root@e55169df78a2:/tmp# id headscale
uid=1000(headscale) gid=1000(headscale) groups=1000(headscale)
root@e55169df78a2:/tmp# apt upgrade ./headscale_0.24.0-beta.2_jy_linux_amd64.deb 
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Note, selecting 'headscale' instead of './headscale_0.24.0-beta.2_jy_linux_amd64.deb'
Calculating upgrade... Done
The following packages will be upgraded:
  headscale
1 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
Need to get 0 B/14.8 MB of archives.
After this operation, 1208 kB of additional disk space will be used.
Do you want to continue? [Y/n] y
Get:1 /tmp/headscale_0.24.0-beta.2_jy_linux_amd64.deb headscale amd64 0.24.0~beta.2 [14.8 MB]
debconf: delaying package configuration, since apt-utils is not installed
(Reading database ... 4401 files and directories currently installed.)
Preparing to unpack .../headscale_0.24.0-beta.2_jy_linux_amd64.deb ...
Unpacking headscale (0.24.0~beta.2) over (0.24.0~beta.1) ...
Removing run directory
Setting up headscale (0.24.0~beta.2) ...
Installing new version of config file /etc/headscale/config.yaml ...
Sudo permissions detected
Found headscale /usr/bin/headscale
PostInstall: Adding headscale user headscale
useradd: user 'headscale' already exists
PostInstall: Creating headscale run directory 
PostInstall: Modifying group ownership of headscale run directory 
----------------------------------------------------------------------
 headscale package has been successfully installed.

 Please follow the next steps to start the software:

    sudo systemctl enable headscale
    sudo systemctl start headscale

 Configuration settings can be adjusted here:
    /etc/headscale/config.yaml

----------------------------------------------------------------------
root@e55169df78a2:/tmp# id headscale
uid=1000(headscale) gid=1000(headscale) groups=1000(headscale)
root@e55169df78a2:/tmp# 

[chriswiggins]

If the install target is using systemd, would it not be beneficial to use DynamicUser?

The cockpit project does this now and it works really well: https://github.com/cockpit-project/cockpit/blob/main/src/systemd/cockpit-wsinstance-socket-user.service

You set a dependency on the user unit, and then the service uses that dynamically, using cgroups which means it is adequately sandboxed

[ghost]

Pull Request Revisions

Revision	Description
r1	Added system user and group flags Modified user and group creation commands to use system-level flags (-r for useradd, -r for groupadd, -S for alpine addgroup)

---

✅ AI review completed for r1

Help

React with emojis to give feedback on AI-generated reviews:

• 👍 means the feedback was helpful and actionable
• 👎 means the feedback was incorrect or unhelpful

💬 Replying to feedback with a comment helps us improve the system. Your input also contributes to shaping future interactions with the AI reviewer.

We'd love to hear from you—reach out anytime at [email protected].