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

API for adding Extra Domain Records #479

New Issue
Closed
opened 2025-12-29 02:18:41 +01:00 by adam · 15 comments
adam commented 2025-12-29 02:18:41 +01:00
Owner
Copy Link

Originally created by @athul on GitHub (Apr 20, 2023).

Feature request

Thank you for Headscale. I was trying it out to host a few servers under a single network so that inter server communication don't go unsecure. Some of the servers have their own domain name and magic dns routing always ends up with a SSL error when trying to use curl. I tried adding the same server as an A record in the config and it works perfectly.

The thing is we automate all these stuff and we could use Ansible to write to the config file once a server is added to the tailnet with the domain name and IP but would be great if this was doable via API. We already use the API to fetch details about the machines and the IPs and all those stuff.

Maybe it could be something like
POST: /api/v1/domains/extra
Payload

{
        "domain":"abc.xyz.example.com",
        "ip":"100.0.0.4"
}
Originally created by @athul on GitHub (Apr 20, 2023). <!-- Headscale is a multinational community across the globe. Our common language is English. Please consider raising the feature request in this language. --> **Feature request** <!-- A clear and precise description of what new or changed feature you want. --> <!-- Please include the reason, why you would need the feature. E.g. what problem does it solve? Or which workflow is currently frustrating and will be improved by this? --> Thank you for Headscale. I was trying it out to host a few servers under a single network so that inter server communication don't go unsecure. Some of the servers have their own domain name and magic dns routing always ends up with a SSL error when trying to use `curl`. I tried adding the same server as an A record in the config and it works perfectly. The thing is we automate all these stuff and we could use Ansible to write to the config file once a server is added to the tailnet with the domain name and IP but would be great if this was doable via API. We already use the API to fetch details about the machines and the IPs and all those stuff. Maybe it could be something like POST: `/api/v1/domains/extra` Payload ```json { "domain":"abc.xyz.example.com", "ip":"100.0.0.4" } ```
adam added the enhancementstalemight-come labels 2025-12-29 02:18:41 +01:00
adam closed this issue 2025-12-29 02:18:41 +01:00
adam commented 2025-12-29 02:18:42 +01:00
Author
Owner
Copy Link

@loprima-l commented on GitHub (Apr 28, 2023):

Hi, thanks for your FR, won't it be better to try to fix your ssl issue ? And also, if you're using Headscale only between the server, it's not mandatory to use ssl as the communication is already encrypted between your servers.

Can you open an issue to describe your ssl problem a bit more ?

@loprima-l commented on GitHub (Apr 28, 2023): Hi, thanks for your FR, won't it be better to try to fix your ssl issue ? And also, if you're using Headscale only between the server, it's not mandatory to use ssl as the communication is already encrypted between your servers. Can you open an issue to describe your ssl problem a bit more ?
adam commented 2025-12-29 02:18:42 +01:00
Author
Owner
Copy Link

@athul commented on GitHub (May 1, 2023):

Hi,

The SSL issue happens due to the SSL cert present in the end server. It's a name invalid SSL error and this pops up because the ssl cert and the name of the domain(magicdns) I was trying to curl was different.

Elaborating to get a better idea.

SSL cert on server: abc.example.com

MagicDNS domain name: abc

If I just curl -L abc it will ping the right place but won't return the data from the abc.example.com since the SSL cert is pointed to abc.exaple.com

@athul commented on GitHub (May 1, 2023): Hi, The SSL issue happens due to the SSL cert present in the end server. It's a name invalid SSL error and this pops up because the ssl cert and the name of the domain(magicdns) I was trying to curl was different. Elaborating to get a better idea. SSL cert on server: abc.example.com MagicDNS domain name: abc If I just `curl -L abc` it will ping the right place but won't return the data from the `abc.example.com` since the SSL cert is pointed to abc.exaple.com
adam commented 2025-12-29 02:18:43 +01:00
Author
Owner
Copy Link

@loprima-l commented on GitHub (May 1, 2023):

Oh i got it

@loprima-l commented on GitHub (May 1, 2023): Oh i got it
adam commented 2025-12-29 02:18:43 +01:00
Author
Owner
Copy Link

@loprima-l commented on GitHub (May 1, 2023):

And why don't you redirect all your traffic to abc.example.com ?

@loprima-l commented on GitHub (May 1, 2023): And why don't you redirect all your traffic to abc.example.com ?
adam commented 2025-12-29 02:18:44 +01:00
Author
Owner
Copy Link

@6ixfalls commented on GitHub (May 6, 2023):

Even with the SSL issue resolved, this would still be a great feature to add. It would allow, for example, https://github.com/iFargle/headscale-webui to have a DNS records page, which would make it easy to update the configuration (without having to ssh into the control plane, and changing the configuration file). Of course, it would need to also have listing APIs as well as delete, and since they're already defined in the configuration file they'd have to be migrated or something.

@6ixfalls commented on GitHub (May 6, 2023): Even with the SSL issue resolved, this would still be a great feature to add. It would allow, for example, https://github.com/iFargle/headscale-webui to have a DNS records page, which would make it easy to update the configuration (without having to ssh into the control plane, and changing the configuration file). Of course, it would need to also have listing APIs as well as delete, and since they're already defined in the configuration file they'd have to be migrated or something.
adam commented 2025-12-29 02:18:44 +01:00
Author
Owner
Copy Link

@6ixfalls commented on GitHub (May 6, 2023):

If not (maybe design decisions), it would also be great to separate the DNS configuration from the main configuration, and automatically reload any new DNS configurations, so a control plane restart isn't required to change DNS records.

@6ixfalls commented on GitHub (May 6, 2023): If not (maybe design decisions), it would also be great to separate the DNS configuration from the main configuration, and automatically reload any new DNS configurations, so a control plane restart isn't required to change DNS records.
adam commented 2025-12-29 02:18:44 +01:00
Author
Owner
Copy Link

@loprima-l commented on GitHub (May 6, 2023):

That's a good point I think the DNS API is as important than the ACL API, I will maybe do a PR for this when I got the time, I need to get a little bit more familiar with the code to start it and feel secure and confident.

@loprima-l commented on GitHub (May 6, 2023): That's a good point I think the DNS API is as important than the ACL API, I will maybe do a PR for this when I got the time, I need to get a little bit more familiar with the code to start it and feel secure and confident.
adam commented 2025-12-29 02:18:45 +01:00
Author
Owner
Copy Link

@juanfont commented on GitHub (May 10, 2023):

This is not a bad idea. We will probably look into it.

@juanfont commented on GitHub (May 10, 2023): This is not a bad idea. We will probably look into it.
adam commented 2025-12-29 02:18:45 +01:00
Author
Owner
Copy Link

@tbjers commented on GitHub (Jul 2, 2023):

SSL cert on server: abc.example.com

MagicDNS domain name: abc

If I just curl -L abc it will ping the right place but won't return the data from the abc.example.com since the SSL cert is pointed to abc.exaple.com

For reference, this does not work with Tailscale, either. Even if you use a wildcard cert on Headscale, Let's Encrypt will not generate SANs for abc, the host IP address, or the Tailnet IP address, for that matter.

You would be required to run your own CA server, which then leads to having to distribute the CAs to all clients. That's a pretty massive undertaking and probably out of scope for Headscale/Tailscale.

Maybe there are ways to accomplish this with Smallstep's step-ca. I am unsure if you can set up policies that will create certs that combine ip rules with dns rules.

@tbjers commented on GitHub (Jul 2, 2023): > SSL cert on server: abc.example.com > > MagicDNS domain name: abc > > If I just `curl -L abc` it will ping the right place but won't return the data from the `abc.example.com` since the SSL cert is pointed to abc.exaple.com For reference, this does not work with Tailscale, either. Even if you use a wildcard cert on Headscale, Let's Encrypt will not generate SANs for `abc`, the host IP address, or the Tailnet IP address, for that matter. You would be required to run your own CA server, which then leads to having to distribute the CAs to all clients. That's a pretty massive undertaking and probably out of scope for Headscale/Tailscale. Maybe there are ways to accomplish this with Smallstep's `step-ca`. I am unsure if you can set up policies that will create certs that combine `ip` rules with `dns` rules.
adam commented 2025-12-29 02:18:45 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Dec 17, 2023):

This issue is stale because it has been open for 90 days with no activity.

@github-actions[bot] commented on GitHub (Dec 17, 2023): This issue is stale because it has been open for 90 days with no activity.
adam commented 2025-12-29 02:18:46 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Dec 25, 2023):

This issue was closed because it has been inactive for 14 days since being marked as stale.

@github-actions[bot] commented on GitHub (Dec 25, 2023): This issue was closed because it has been inactive for 14 days since being marked as stale.
adam commented 2025-12-29 02:18:46 +01:00
Author
Owner
Copy Link

@stuartm commented on GitHub (Feb 3, 2025):

Is anyone still working on this? Allowing DNS records to be managed via API? This really is a must-have for me so if no-one has made any progress on it I might have to take a look.

Friction point for me, aside from lack of spare time, is zero experience with Go but needs must.

If I were to take this on, would it be better for extra records to be persisted in the database instead of the extra_records json file? I'd be wary of corruption if using the json file directly without any locking (concurrent manual edits).

@stuartm commented on GitHub (Feb 3, 2025): Is anyone still working on this? Allowing DNS records to be managed via API? This really is a must-have for me so if no-one has made any progress on it I might have to take a look. Friction point for me, aside from lack of spare time, is zero experience with Go but needs must. If I were to take this on, would it be better for extra records to be persisted in the database instead of the extra_records json file? I'd be wary of corruption if using the json file directly without any locking (concurrent manual edits).
adam commented 2025-12-29 02:18:47 +01:00
Author
Owner
Copy Link

@kradalby commented on GitHub (Feb 3, 2025):

You can write them to a file and it will automatically be picked up. It isn't in the database, and it will not be added there so it won't make it into an api.

See the latest config or change log for 0.23

See docs for dns.extra_records_path: https://headscale.net/0.24.2/ref/dns/#setting-extra-dns-records

@kradalby commented on GitHub (Feb 3, 2025): You can write them to a file and it will automatically be picked up. It isn't in the database, and it will not be added there so it won't make it into an api. See the latest config or change log for 0.23 --- See docs for `dns.extra_records_path`: https://headscale.net/0.24.2/ref/dns/#setting-extra-dns-records
adam commented 2025-12-29 02:18:47 +01:00
Author
Owner
Copy Link

@stuartm commented on GitHub (Feb 3, 2025):

So, Is that an official flat NO to allowing records to be managed through the API?

If it's not too bold a question, why? What's different about this than managing everything else through the API?

@stuartm commented on GitHub (Feb 3, 2025): So, Is that an official flat NO to allowing records to be managed through the API? If it's not too bold a question, why? What's different about this than managing everything else through the API?
adam commented 2025-12-29 02:18:47 +01:00
Author
Owner
Copy Link

@kradalby commented on GitHub (Mar 30, 2025):

@stuartm probably not going to add it to the API, it comes down to where the data is stored, extra records is not in the database, they are a file, and the API doesnt cover that.

@kradalby commented on GitHub (Mar 30, 2025): @stuartm probably not going to add it to the API, it comes down to where the data is stored, extra records is not in the database, they are a file, and the API doesnt cover that.
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 enhancement might-come stale
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#479
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?