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

Documentation issues #430

New Issue
Closed
opened 2025-12-29 01:29:06 +01:00 by adam · 5 comments
adam commented 2025-12-29 01:29:06 +01:00
Owner
Copy Link

Originally created by @Norodix on GitHub (Feb 15, 2023).

Issue description

I really like this software! I just set up it on my VPS and I would like to give some feedback on the installation instructions. Issues I ran into that were not very obvious from the documentation.

To Reproduce

Install headscale on linux following the docs.

Context info

I love the software, and I hope I can help with this feedback.

File permissions not explained

I think it is not unreasonable to think someone with little to no linux experience would try to set up their own VPN. The docs dont go into detail with what the file permissions need to look like. There is mention of running it with a headscale user but not that this user needs to be able to write to some dirs and read others. Should the config files under /etc be read-only, belong to root or headscale, etc. I think it might be worth mentioning what it should look like.

Running from the same directory

This might be a bug, but when I started headscale for the first time from the command line, in the new terminal I could not list the users. I could wget the metrics as shown in the docs but I had to cd to /etc/headscale to be able to headscale users list. If it is not a bug, it should be mentioned explicitly.

Systemd not printing all errors.

This might be a bug, but when I ran headscale as a systemd service it could not start but in the status it did not show the errors. I had to run it with headscale user to see that I had some permission errors. I dont know why it was not printed to systemd's status.

Some files need to be created manually

Some files like /var/run/headscale/headscale.sock need to be created manually. It is not created by headscale if it does not exist. It might be better to explicitly mention it in the docs.

How to keep up-to-date

I dont see any mention in the docs how to upgrade between version of headscale. Given how fast it is developed it might be a good idea to add a short guide. I assume back up stuff, replace bin, run again, but I am just guessing.

Originally created by @Norodix on GitHub (Feb 15, 2023). <!-- Headscale is a multinational community across the globe. Our common language is English. Please consider raising the issue in this language. --> <!-- If you have a question, please consider using our Discord for asking questions --> **Issue description** I really like this software! I just set up it on my VPS and I would like to give some feedback on the installation instructions. Issues I ran into that were not very obvious from the documentation. **To Reproduce** Install headscale on linux following the docs. **Context info** I love the software, and I hope I can help with this feedback. ### File permissions not explained I think it is not unreasonable to think someone with little to no linux experience would try to set up their own VPN. The docs dont go into detail with what the file permissions need to look like. There is mention of running it with a headscale user but not that this user needs to be able to write to some dirs and read others. Should the config files under /etc be read-only, belong to root or headscale, etc. I think it might be worth mentioning what it should look like. ### Running from the same directory This might be a bug, but when I started headscale for the first time from the command line, in the new terminal I could not list the users. I could wget the metrics as shown in the docs but I had to cd to `/etc/headscale` to be able to `headscale users list`. If it is not a bug, it should be mentioned explicitly. ### Systemd not printing all errors. This might be a bug, but when I ran headscale as a systemd service it could not start but in the status it did not show the errors. I had to run it with headscale user to see that I had some permission errors. I dont know why it was not printed to systemd's status. ### Some files need to be created manually Some files like `/var/run/headscale/headscale.sock` need to be created manually. It is not created by headscale if it does not exist. It might be better to explicitly mention it in the docs. ### How to keep up-to-date I dont see any mention in the docs how to upgrade between version of headscale. Given how fast it is developed it might be a good idea to add a short guide. I assume back up stuff, replace bin, run again, but I am just guessing.
adam added the bug label 2025-12-29 01:29:06 +01:00
adam closed this issue 2025-12-29 01:29:06 +01:00
adam commented 2025-12-29 01:29:07 +01:00
Author
Owner
Copy Link

@kradalby commented on GitHub (Feb 18, 2023):

Hi, it would be great if you could help improve the docs with your feedback :), we are very happy for pull requests to update the docs!

Thanks

@kradalby commented on GitHub (Feb 18, 2023): Hi, it would be great if you could help improve the docs with your feedback :), we are very happy for pull requests to update the docs! Thanks
adam commented 2025-12-29 01:29:07 +01:00
Author
Owner
Copy Link

@Norodix commented on GitHub (Feb 18, 2023):

I'm happy to do so but to be perfectly honest I'm not sure about some of the points. Should I just create PR for the ones I'm confident about and leave this issue up for the rest?

@Norodix commented on GitHub (Feb 18, 2023): I'm happy to do so but to be perfectly honest I'm not sure about some of the points. Should I just create PR for the ones I'm confident about and leave this issue up for the rest?
adam commented 2025-12-29 01:29:07 +01:00
Author
Owner
Copy Link

@kradalby commented on GitHub (Feb 18, 2023):

Yes that’s better than the current state :) Sent from Proton Mail for iOS On Sat, Feb 18, 2023 at 14:13, Norodix @.***> wrote:
I'm happy to do so but to be perfectly honest I'm not sure about some of the points. Should I just create PR for the ones I'm confident about and leave this issue up for the rest?

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: @.***>

@kradalby commented on GitHub (Feb 18, 2023): Yes that’s better than the current state :) Sent from Proton Mail for iOS On Sat, Feb 18, 2023 at 14:13, Norodix ***@***.***> wrote: I'm happy to do so but to be perfectly honest I'm not sure about some of the points. Should I just create PR for the ones I'm confident about and leave this issue up for the rest? —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: ***@***.***>
adam commented 2025-12-29 01:29:08 +01:00
Author
Owner
Copy Link

@Norodix commented on GitHub (Feb 19, 2023):

I opened a PR.

The only missing thing that I found is the general description on how to update headscale when a new version comes out. I'm curious about that myself.

@Norodix commented on GitHub (Feb 19, 2023): I opened a PR. The only missing thing that I found is the general description on how to update headscale when a new version comes out. I'm curious about that myself.
adam commented 2025-12-29 01:29:08 +01:00
Author
Owner
Copy Link

@Pr0pHesyer commented on GitHub (Dec 23, 2023):

It doesn't create /var/run/headscale/headscale.sock in 0.22.3 deb still,doc has no more information.
Is it need to fix?

@Pr0pHesyer commented on GitHub (Dec 23, 2023): It doesn't create `/var/run/headscale/headscale.sock` in 0.22.3 deb still,doc has no more information. Is it need to fix?
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 bug
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#430
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?