How to Configure Split DNS / Horizon

[Flagelmann]

Hello,

I found out only other two entries about this topic, Split Horizon / DNS, but unfortunately I did not get completely the info that I need in a clear way.

As it would be very useful to use this app but there's lack of any detailed, scenario-based, documentation of this app, I would like to ask if any of you has finally configured it properly on his own self-hosted instance.

The scenario in which I am is the following:

• I have a primary DNS zone configured and working correctly, with several A records registered.
• This DNS server is serving both my LAN but also some personal devices from internet, mainly using DoT configuration (Private DNS).
• The DNS domain used is and MUST remain the same for both internal and external requests but providing a different IP based on where the device is located (and here it is the need of Split DNS).

Now, I have checked other few posts I have found about the Split Horizon app and it seems it is done by doing two main steps:

1. Opening the "Config" part from the app page and modifying/saving the main configuration file of the app (where specifying the networkGroupMap and the groups basically).
2. Then creating an "APP" record in which we have to define in the "Record Data" some other spec about the actual translation needed.

NOTE: need also to understand better the "externalToInternalTranslation" purpose defined under each group.

Personally, I get the idea of the configuration, but still do not get a full picture of the configuration in Technitium DNS server, as there is a complete lack of a full example, so the "main configuration" + "APP record" properly configured and explained.

Right now to configure it for me it seems basically a trial and error.

Anyone that could provide a full example on how to properly configure the Split Horizon app for this scenario (no need of a CNAME example, but A record example)?

Many thanks

[ShreyasZare]

Thanks for asking. Unfortunately there is no documentation available for the apps. However, there is plan to support GUI for all apps so it should be more user friendly and easy to understand once GUI is available.

The Split Horizon app supports 2 features. First is to use APP record which is useful only when you have the zones locally hosted. With this APP record, you can return custom A or CNAME response based on the request's IP address.

The second feature is Address Translation which works globally (for all domain names hosted or not) and is to be configured via the app's config. In there, you need to configure groups for the client networks and in that group you can specify the external to internal translation map. This feature will automatically check for all the responses and replace any external IP match with internal IP as defined in the config.

Let me know if you have any more queries regarding the config.

[Flagelmann]

Thanks for your availability ShreyasZare. :)

Ok, let's say that I want to use the APP record approach and not the global config approach.

I go to the actual zone, then I open the new APP record section, as shown below.

Then I want to specify, for the specific subdomain, let's say g.example.com that for internal LAN based on 192.168.1.0/25 the IP that should be returned to clients will be 192.168.1.40 and for all the others the public IP one, how should I configure the "Record Data" section?

[ShreyasZare]

You're welcome :)

The record data JSON for that scenario will be as follows:

{
  "192.168.1.0/25": [
    "192.168.1.40"
  ],
  "0.0.0.0/0": [
    "<public-ip-address>"
  ]
}

The 0.0.0.0/0 network address will match to all addresses.

Edit: fixed missing comma in example.

[Flagelmann]

Perfect. :D

Ok, this is a first common simple scenario that would be very helpful to introduce to Split DNS in Technitium.

Thanks a lot, by doing some first tests even using Private DNS on multiple Android devices it seems working as expected, getting the proper IP as expected.

There is a missing comma in the example above, but fixed as follows:

{
  "192.168.1.0/25": [
    "192.168.1.40"
  ],
  "0.0.0.0/0": [
    "<public-ip-address>"
  ]
}

[ShreyasZare]

Good to know you got it working. Will edit to fix missing comma.

[UncleVic]

I have the same question because I'd just faced out with Split a week ago.

What about A records? Do I have to remove them completely or not?

[ShreyasZare]

I have the same question because I'd just faced out with Split a week ago.

What about A records? Do I have to remove them completely or not?

If you have A records then those will get returned. So you will need to remove them so that the requests hits APP record.

[kranked]

Sorry to revive an old thread, but can you point it to a ANAME? e.g.
{
"192.168.1.11": [
""
],
"0.0.0.0/0": [
"webserverexample.lan"
]
}

[ShreyasZare]

@kevdogg Thanks for asking. The json template is available in the Apps section under the "More Details" link for the Split Horizon app. Just click that link to expand the details.

[UncleVic]

Sorry for asking again, but it doesn't work.

My Split's main config is

{
    "networks": {
        "public": [
          "0.0.0.0/0"
        ],
        "private": [
          "192.168.10.0/24",
          "192.168.20.0/24"
        ]
    }
}

The DNS record is

{
  "private": [
    "192.168.20.2"
  ],
  "0.0.0.0/0": [
    "10.17.40.1"
  ]
}

And the name is resolved with the external IP.

[ShreyasZare]

@UncleVic thanks for asking. You cannot define "public" and "private" networks since those are keywords so you need to use different names for your networks in the app's main config.

[UncleVic]

Are there any more keywords?

[ShreyasZare]

@UncleVic No. Just public and private are the ones used to automatically map to all public/private networks.

[smileBeda]

Sorry to revive the older thread, I would like to achieve something similar but more globally.

I’d like to achieve a global Split Horizon behavior for my DNS zones:

• If a request comes from the 10.7.0.0/24 subnet (e.g., from 10.7.0.4), I want all my internal services registered in Technitium (e.g., heimdall.lan, jellyfin.lan, etc.) to resolve to their WireGuard IP (10.7.0.3).
• If a request comes from the 192.168.1.0/24 subnet (e.g., from 192.168.1.4), I want the same services to resolve to their LAN IP (192.168.1.3).
• For all other domains (e.g., external sites like google.com), I want Technitium to behave like a normal resolver with no translation - just forward the query to the upstream DNS.

I understand that to achieve this I have to:

• install the Split Horizon Plugin
• directly edit the config - not the single records
• however, I got confused on the dnsApp.config syntax. Do I have to remove the entries already present such as custom-networks and the already present groups? Perhaps an example based on above would help me greatly!
• and, of course, finally, I would have to go and remove all the existing A records, as I understand it from this thread... I guess I will have some work ahead of me haha

Thanks for any hints and feedbacks, I appreciate both answer and that tool!

[smileBeda]

The global Forwarder simply does not work for me even when removing the single entries A/AAAA

However what I got working is setting an APP record for each entry (and remove A/AAAA)

JSOn in both cases is:

{
  "10.7.0.0/24": ["10.7.0.4"],
  "192.168.1.0/24": ["192.168.1.3"],
  "default": []
}

This works on the single record level. In the Zone for . on Forwarder this does not work and presents the issues aforementioned (I am aware on the SSL issue, but that is not the problem because I already installed the cert, otherwise it would not work either when not using the horizons feature)

Perhaps this simply is not how global forwarder is working, and I misuderstand it?

This is how I set it up:

And then in the zone I add @ record with the aforeshared JSON

[ShreyasZare]

Thanks for the details. Make the APP record's json config as below:

{
  "10.7.0.0/24": ["10.7.0.4"],
  "192.168.1.0/24": ["192.168.1.3"]
}

The empty default entry days that there is no A/AAAA records so a NO DATA response is sent. When that entry is missing, the APP record bails and let the forwarding work.

Also, make the APP record a wildcard by using * as the subdomain name if you need that all domain names resolve to that IP. Otherwise, have a single APP records with a specific different subdomain name and then using a CNAME that points to the APP record for all the other domain names you wish to resolve. This way would be easier than having APP record for all of them.

[smileBeda]

Thanks, I will try this in short.

Also, make the APP record a wildcard by using * as the subdomain name if you need that all domain names resolve to that IP.

Do you mean where I added . in the Zone, I add * instead?
Note, I have no subdomains - only top level domains, such as heimdall.lan or jellyfin.lan
All non-lan is of course to be routed over standard DNS like 1.1.1.1 or else (bypass technitum basically)

UPDATE:
no, that cannot be it, because if I add * I get Error! Domain name for a zone cannot contain wildcard character. when setting up the Forwarder zone.

[ShreyasZare]

Do you mean where I added . in the Zone, I add * instead?

I meant to use * when adding the APP record. You enter the * in the Name field of the APP record.

Note, I have no subdomains - only top level domains, such as heimdall.lan or jellyfin.lan
All non-lan is of course to be routed over standard DNS like 1.1.1.1 or else (bypass technitum basically)

If you wish to manage only lan and a few other domain names, then I would recommend that you create forwarder zone for lan and the other ones separately instead of having a single root forwarder zone. This will make it easier to manage and debug issues.

[smileBeda]

It works flawlessly as long I create an entry in each zone. If I create a root zone, and add an App record, it does not work.
Then the error happens I mentioned before (first, says cert is invalid, and if accepted, says server not found).
Yet it works perfectly if I add it to each single zone.

[raylu]

is there a way to get split horizon to handle IPv6 addresses? I tried

{
  "127.0.0.0/8": ["127.0.0.1"],
  "::1": ["127.0.0.1"],
  "::1/128": ["127.0.0.1"],
  "0.0.0.0/0": ["127.2.3.4"]
}

and when I query technitium from the machine it's running on, I get

$ dig xis
[...]
;; ANSWER SECTION:
xis.                    3600    IN      A       127.2.3.4

;; Query time: 0 msec
;; SERVER: ::1#53(::1) (UDP)

[ShreyasZare]

Check the query logs and find out what was the source IP address for the dig request that you made and verify if it matches the APP record config. The app will respond based on the source IP address that was used.

Another thing, ::1 and ::1/128 are one and the same thing so just remove one of them from the config.

You can enable query logging from the Settings > Logs section which will log all queries to the text log file. Or, you can install Query Logs (Sqlite) app and then use the Logs > Query Logs section.

[raylu]

ah, thanks a lot! I was able to pull the logs from the regular Logs → View Logs section. technitium is running in docker so the client IP when run on the host is 172.17.0.0/16

(I know ::1 and ::1/128 are the same but neither was working so I kept trying stuff)

[ShreyasZare]

You're welcome! Docker networking is quirky.