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

Add custom STUN responses #607

New Issue
Closed
opened 2025-12-29 02:21:08 +01:00 by adam · 3 comments
adam commented 2025-12-29 02:21:08 +01:00
Owner
Copy Link

Originally created by @neta540 on GitHub (Jan 7, 2024).

I would like to request a feature to allow the STUN server to return a custom IP address instead so that the other peers can connect to it. Basically, I would like to request a feature to return custom values for the responses using a ruleset that will be defined in the headscale config.

For example, I would like to have a config like this:

derp:
  server:
    ...

    stun:
      listen_addr: "0.0.0.0:3478"
      rules:
        - match: "10.1.40.0/24"
          return: "5.5.5.5"

Why

I am running a complex network with multiple subnets and complex NAT mapping, having headscale running inside a vlan separate from other vlans which can connect into it, but also connect to other peers from different network. I ran into a problem where the the STUN server is returning the IP internal address of the node in its vlan, where the other peers from other networks cannot connect to it.

Originally created by @neta540 on GitHub (Jan 7, 2024). I would like to request a feature to allow the STUN server to return a custom IP address instead so that the other peers can connect to it. Basically, I would like to request a feature to return custom values for the responses using a ruleset that will be defined in the headscale config. For example, I would like to have a config like this: ```yaml derp: server: ... stun: listen_addr: "0.0.0.0:3478" rules: - match: "10.1.40.0/24" return: "5.5.5.5" ``` ## Why I am running a complex network with multiple subnets and complex NAT mapping, having headscale running inside a vlan separate from other vlans which can connect into it, but also connect to other peers from different network. I ran into a problem where the the STUN server is returning the IP internal address of the node in its vlan, where the other peers from other networks cannot connect to it.
adam added the enhancementstale labels 2025-12-29 02:21:08 +01:00
adam closed this issue 2025-12-29 02:21:09 +01:00
adam commented 2025-12-29 02:21:09 +01:00
Author
Owner
Copy Link

@neta540 commented on GitHub (Jan 9, 2024):

I've tried to implement the functionality on a fork, commit is here:

https://github.com/neta540/headscale/commit/b1578a1ddead32cedf536f418ffdd669e83ebeed

This commit adds the functionality to set custom responses for the STUN server, allowing the server to use a rule-set to respond with addresses that are not from the server's prespective, this may be useful in complex NAT setups. First match wins, so the order of the rules is important.

When a port is not specified, the port from the client's request is used.

Example config:

...
    region_code: "headscale"
    region_name: "Headscale Embedded DERP"
    stun:
      listen_addr: "0.0.0.0:3478"
      rules:
        - match: "10.1.1.1/32"
          address: "4.4.4.4"
        - match: "10.0.0.0/8"
          address: "5.5.5.5"
        - match: "192.168.0.0/16"
          address: "6.6.6.6:1234"

derp.server.stun_listen_addr is changed to derp.server.stun.listen_addr, the old config location for the listen address will still work, but the new config location I suggest here takes precedence, to have all the STUN server config clean in one place.

I can make a PR if you want to use this.

Implements #1679

@neta540 commented on GitHub (Jan 9, 2024): I've tried to implement the functionality on a fork, commit is here: [https://github.com/neta540/headscale/commit/b1578a1ddead32cedf536f418ffdd669e83ebeed](https://github.com/neta540/headscale/commit/b1578a1ddead32cedf536f418ffdd669e83ebeed) This commit adds the functionality to set custom responses for the STUN server, allowing the server to use a rule-set to respond with addresses that are not from the server's prespective, this may be useful in complex NAT setups. First match wins, so the order of the rules is important. When a port is not specified, the port from the client's request is used. Example config: ```yaml ... region_code: "headscale" region_name: "Headscale Embedded DERP" stun: listen_addr: "0.0.0.0:3478" rules: - match: "10.1.1.1/32" address: "4.4.4.4" - match: "10.0.0.0/8" address: "5.5.5.5" - match: "192.168.0.0/16" address: "6.6.6.6:1234" ``` `derp.server.stun_listen_addr` is changed to `derp.server.stun.listen_addr`, the old config location for the listen address will still work, but the new config location I suggest here takes precedence, to have all the STUN server config clean in one place. I can make a PR if you want to use this. Implements #1679
adam commented 2025-12-29 02:21:09 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Apr 9, 2024):

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

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

@neta540 commented on GitHub (Apr 9, 2024):

I eventually used a custom STUN server instead of the one provided by Headscale.

@neta540 commented on GitHub (Apr 9, 2024): I eventually used a custom STUN server instead of the one provided by Headscale.
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 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#607
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?