Nebula VPN split configuration

 October 31, 2024

We have had Nebula VPN within the Fedora repositories for a couple of years. A couple of months ago, I changed the default systemd service unit. More specifically, this is the change:

-ExecStart=/usr/bin/nebula -config /etc/nebula/config.yml
+ExecStart=/usr/bin/nebula -config /etc/nebula

Although the change is only a few characters, this change allows for a much more flexible use of Nebula. Before this change, the configuration could only be placed in the config.yaml file. After this change, all YAML files in the folders will be read, merged, and used as configuration.

I see three significant advantages to this:

Ability to quickly share some parts of the configuration across multiple hosts.
Ability to easily automate the management of Nebula configuration with configuration management systems.
Ability to override some fields in specific hosts or situations.

Nebula configuration uses the YAML format, which is already fairly convenient by itself, but with this change, managing nebula nodes should become even more convenient.

Nebula reads the configuration folder by reading all YAML files in alphabetical order. Nebula will use the keys and values found to populate the configuration in every read file.

As an example, if there are the following two files:

punchy:
  punch: true

punchy:
  respond: true

The result will be the following:

punchy:
  punch: true
  respond: true

If the same array is present in multiple files, the values of the array are added together like in the following example:

lighthouse:
  hosts:
  - 192.168.1.1

lighthouse:
  hosts:
  - 192.168.1.2

The result will be the following:

lighthouse:
  hosts:
  - 192.168.1.1
  - 192.168.1.2

In case the same key of a non-array is configured twice, the latest occurrence of it will be considered, so - assuming that the files are alphabetically sorted in the appearing order - the following configuration files:

tun:
  dev: nebula

tun:
  dev: nebula1

This will result in the following:

tun:
  dev: nebula1

It is also possible to check the exact configuration that Nebula created by merging the configuration files by running:

nebula -test -config /etc/nebula

I understand this change will potentially be detrimental for people with multiple configurations for different VPNs in the /etc/nebula folder. For those cases, I suggest creating sub-folders for the various VPN configurations and then tweaking the systemd service unit to ensure that the correct folder is picked up.

 Fedora, Networking, Security, Self-hosting

 Nebula, VPN, WireGuard

Say something

Comments

Michael on 2025-02-01 19:26:20 UTC said:

Hello Fale,

it is a very good idea to split the configuration file. Many thanks for the article.

I would be very pleased if you could describe how you manage your clients with configuration management. I would be particularly interested in how you carry out the distribution via the nebula network in order to always be able to access all clients. I would also be very interested in your DNS solution for this network.

Many thanks in advance.

Kind regards Michael

Fabio Alessandro Locati on 2025-02-03 08:59:26 UTC said:

Hi Michael,

Generally speaking, I use Ansible to manage the clients configurations by using simple Jinja templates. These configurations are done the first time via an out-of-band channel, and then from that point forward, I use the Nebula channel itself, ensuring that I have or I can potentially re-enable the out-of-band channel if I break Nebula. I’m going to clean up a little bit my process first, but my longer term goal is to fully publish the code I use and do (at least) one blog post on it.

As for the DNS part, I use NSD, which is not tied in any way to Nebula, I simply configured and manage it independently, also with Ansible.

I hope this helps, Fale

Michael on 2025-02-07 10:49:06 UTC said:

Hello Fale,

I’m really looking forward to your code and the blog article. (But I don’t want to put any pressure on you! ;-) ) I have another question about the DNS, how do you configure it so that the central DNS is used via nebula for a nebula connection and another one if there is no connection?

Thank you very much and have a nice weekend.

Kind regards Michael

Fabio Alessandro Locati on 2025-02-11 07:26:47 UTC said:

Hi Michael,

I’ll try to be reasonably quick at publishing the code and write the article… but I can not promise a specific date ;-).

The way I manage the double DNS is with a split-DNS configuration in systemd-resolved, since that is the DNS resolution daemon I have. I tend to always have the network on, so the resolution always works. There are some edge cases (some very constrained wifis) where it does not work, but in those cases also the services are not available, so the DNS not functioning is not creating any additional issue.

I hope this helps, Fale