Setting Up Nebula Credentials - JS-Produksiyon/pulsar GitHub Wiki

The Nebula developers have created an efficient way for making a client connect to the mesh network. They achieve this by using a configuration file in .yaml format that is referenced when calling the executable as follows:

nebula -config config.yaml

They have created an excellent example configuration file that is well-commented, allowing the user to easily adapt the configuration to their specific network.

Nebula facilitates the connectivity between the client and the network via a certificate authority (CA), a client-specific private key and a client-specific certificate. The Quick Start Guide in Nebula’s documentation goes into detail on how to do this. Our brief documentation assumes that you have a fully functional Nebula infrastructure up and running and merely references a few details that we use specifically for our connectivity credential generation.

Generating Connectivity Certificates

The IP address and client name of a given node is defined by the client private key / certificate pair generated using the nebula-cert application. This binary is not distributed with Pulsar and needs to be downloaded from the Nebula Releases page (Pulsar is using Nebula v.1.8.2).

Since it is wise to protect the certificate authority private key, we keep ours in an encrypted location that we only decrypt when needing to generate new credentials. As such we use extended options with nebula-cert to generate the user credentials, here as it would be executed in PowerShell.

PS C:\Users\xyz> \Path\to\nebula-cert.exe sign -ca-crt "\path\to\ca.crt"  -ca-key "\path\to\ca.key" -ip "10.10.10.10/24" -name "client.mesh.example.com" -groups "clients"

The command works as follows:

  • sign executes function to sign the client certificate
  • The -ca-crt option defines the path to the CA certificate; if left out, nebula-cert will look for the CA certificate in the current directory.
  • The -ca-key option defines the path to the CA private key; if left out, nebula-cert will look for the CA private key in the current directory.
  • The -ip option is required and defines the IP address in CIDR format that the client will use in the mesh network.
  • The -name option defines the name of the client; we have used a FQDN in this example, however, this can also be a short string like client.
  • The -groups option defines which groups the client is a part of and is fully optional; multiple groups are separated by commas: -groups "web,ssh".

This command will output two files:

  • client.mesh.example.com.crt
  • client.mesh.example.com.key

This command, as written, needs to be executed in the directory (folder) where the keys are to be stored. To define an alternate location to save the credentials, you can use the -out-crt and -out-key options.

The Configuration File

Copy the example configuration file into the same directory (folder) that the keys are in and rename it as you choose. We usually use a format of client-config.yaml for the filename. The most important options for Pulsar to work are the items under the pki key.

pki:
    ca: ./ca.crt
    cert: ./client.mesh.example.com.crt
    key: ./client.mesh.example.com.key

Pulsar assumes that the credentials are in the same directory (folder) as the .yaml configuration file. The program will navigate to that directory and execute the Nebula executable from that directory. This path was chosen to make deployment of the software easier, as the credentials can be created in one location, but then easily executed from a location relative to the Pulsar executable, most likely on a completely separate machine.

It is possible to store the credentials elsewhere, however, in that case the pki entries must be configured with an absolute path to the credentials. In Windows this might look as follows:

pki:
    ca: C:\User\xyz\credentials\nebula\ca.crt
    cert: C:\User\xyz\credentials\nebula\client.mesh.example.com.crt
    key: C:\User\xyz\credentials\nebula\client.mesh.example.com.key

Pulsar will still navigate to the directory (folder) where the .yaml configuration file is located, but the absolute paths will supersede whatever is in the same directory (folder) as the configuration file.

Recommended Configuration Directory Structure for Pulsar

When deploying Pulsar to your environment, we recommend the following directory (folder) structure:

pulsar/
   |-- _internal/
   |
   |-- credentials/
   |        |-- ca.crt
   |        |-- config.yaml
   |        |-- hosts.txt
   |        |-- user.crt
   |        |-- user.key
   |
   |-- pulsar.exe

This is based on the Windows release.

We recommend the IT department set up a method whereby the Pulsar software and credentials are distributed as a single package to the end user for easy setup.

Troubleshooting Nebula

If on Windows Nebula exits with the error level=fatal msg="failed to set address: The object already exists."` remove the Windows TUN Adaptor V9 from the Device Manager.

Previous Page: Usage

Next Page: Configuring a valid HOSTS file

Last Updated: 2024-05-14