norohind/nebula-ansible
1
0
Fork 0
mirror of https://github.com/norohind/nebula-ansible.git synced 2025-04-04 00:40:00 +03:00
Code Issues Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
norohind 2025-03-30 21:22:43 +00:00
commit 1b0e2f1dc9
Signed by: norohind
SSH Key Fingerprint: SHA256:SnI4bWnejM2/YEQ5hpH58TUohiQpnjoKN6tXUQlobE0
9 changed files with 367 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
LICENSE Normal file
View File

@ -0,0 +1,28 @@
BSD 3-Clause License
Copyright (c) 2025, norohind
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

110
README.md Normal file
View File

@ -0,0 +1,110 @@
Nebula role
=========
A role to install and manage [nebula vpn](https://nebula.defined.net/) nodes. It automatically detects and eliminates drift between
what groups, host name, ip address set in inventory and what actually is present in
host's cert. When it reissues a cert due to drift, the role will show you what exactly have drifted away.
The role generates nebula and embedded sshd private keys on remote hosts and never copies them off hosts.
It doesn't support password encrypted CAs.
It does not generate configs for you, you are expected to create hosts configs before running the role. It expects
to find config for every host in `configs/{{ inventory_hostname }}.yaml`.
It does use provided by a distro nebula package. Tested on Fedora 40, Debian 12 and Void Linux. On Void
nebula package was manually installed prior to running the role.
Requirements
------------
You have to manually generate CA before using this role. One of options is
```shell
nebula-cert ca -name "My CA for nebula"
```
It will place files ca.crt and ca.key in the current directory.
Role Variables
--------------
| Parameter name | Default value | Description |
|---------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ca_fingerprint | | You must provide a value. It is used to conditionally reissue certificate for a host during CA rotation. You can get fingerprint for your CA using `nebula-cert print -path ca.crt -json \| jq .fingerprint -r` |
| days_left_threshold | 30 | Amount of days before host cert expires the role will attempt to reissue cert for the host. It doesn't make much sense if you don't limit duration of host certs, because then nebula issues certificates with the same expiration time as CA. |
| config_prefix | /etc/nebula | Directory where on the host configuration for nebula should be located |
| ca_crt | ca.crt | Location of ca.crt on localhost |
| ca_key | ca.key | Location of ca.key on localhost |
| ct_log_file | ct.log | Location of file where the role will write information about all issued certificates. It can be helpful if you would need to blacklist a host certificate before it expires. Then you can just look into this look, find line of appropriate certificates, extract its fingerprint and put it into `pki.blocklist` |
| nebula_service_name | nebula | On some systems you might want to adjust service name. On fedora by default it's `nebula`. On debian it would be `nebula@config` |
| service_manager | systemd | Supports systemd and runit (Void Linux). Influences how nebula service will be enabled and reloaded |
| duration | | Value for argument `-duration`, directly passed to `nebula-cert`. If no value is supplied, it gets omitted from `nebula-cert` command, and `nebula-cert` defaults to CA expiration time. |
| pub_dir | pubkeys | Directory where role will copy nebula public keys from remote hosts to issue certificates, it doesn't remove these pub keys, so you could put some automation around it to track changes of keypairs on existing hosts |
| configs_dir | configs | Directory where role will get configs for hosts. I.e. for host "server-a" it will grab `"{{ configs_dir }}/server-a.yaml` file as config. |
| do_reissue | false | It's mostly internal variable, you can override it with value `true` if you need unconditionally reissue certificate. It is defined in vars/main.yaml, meaning it has higher position in precedence order, thus you can't overwrite it as easy as other variables. Please reference [variable precedence](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable) |
| nebula_addr | | You must provide a value. It's a host level var, you should set this in inventory. Example: `10.1.0.1/24` |
| nebula_groups | | It's a host level var, you should set this in inventory. Example: `servers,vps`. You might leave it empty |
Dependencies
------------
`community.general.runit` is used for service reload on runit systems.
Example Playbook
----------------
---
- name: Setup nodes
hosts: linux
strategy: free
gather_facts: false # The role don't need facts
roles:
- role: nebula
ca_fingerprint: abaecbeac8e8fa98bde42a2c4ccff1dcc9a07b7c3392396aaa4039fb6ed570ee # Acquired with `nebula-cert print -path ca.crt -json | jq`
# ct_log_file: /dev/null # If you don't need ct.log
# do_reissue: true # If you need to unconditionally reissue certificate
# nebula_service_name: nebula@config # For debian systems name of the service might actually be nebula@config
Inventory example, sorry, only JSON.
```json5
{
"linux": {
"hosts": {
"myserver-1.internal": { // inventory_hostname is used as name in nebula certificates and to locate configs
"ansible_host": "my-server-1-ssh", // You might have this host configured under another name in your ssh config
"nebula_addr": "10.1.0.1/24",
"nebula_groups": "server,vps,region:eu"
},
"laptop": {
"nebula_addr": "10.1.0.2/24",
"nebula_groups": "laptop",
"service_manager": "runit" // This laptop is running Void Linux
},
}
}
}
```
CA Rotation
-----------
There are [official guide](https://nebula.defined.net/docs/guides/rotating-certificate-authority/) about this. Please read it first.
1. Generate new CA.
2. Append new CA cert to trust bundle in configs, as described in official guide. Configs generation is out of scope for this project.
3. Apply role with new configs.
4. Update variable `ca_crt` and `ca_key` to reference new CA.
5. Apply role. It will detect mismatch in CA fingerprint and reissue certificates. You might want to start by applying role on one host first to check it works as expected.
6. Remove old CA cert from trust bundle in configs.
7. Apply role with new configs.
License
-------
BSD-3-Clause
Author Information
------------------
60548839+norohind@users.noreply.github.com

16
defaults/main.yml Normal file
View File

@ -0,0 +1,16 @@
---
# defaults file for nebula
ca_fingerprint:
days_left_threshold: 30
config_prefix: /etc/nebula
ca_crt: ca.crt
ca_key: ca.key
ct_log_file: ct.log
nebula_service_name: nebula
service_manager: systemd # Supports systemd and runit
duration:
nebula_groups:
pub_dir: pubkeys
configs_dir: configs

15
handlers/main.yml Normal file
View File

@ -0,0 +1,15 @@
---
# handlers file for nebula
- name: Reload nebula config (systemd)
when: service_manager == "systemd"
listen: nebula_reload
service:
name: "{{ nebula_service_name }}"
state: reloaded
- name: Reload nebula config (runit)
when: service_manager == "runit"
listen: nebula_reload
community.general.runit:
name: "{{ nebula_service_name }}"
state: reloaded

35
meta/main.yml Normal file
View File

@ -0,0 +1,35 @@
galaxy_info:
author: norohind
description: Manage nebula vpn
company:
license: BSD-3-Clause
min_ansible_version: 2.1
#
# Provide a list of supported platforms, and for each platform a list of versions.
# If you don't wish to enumerate all versions for a particular platform, use 'all'.
# To view available platforms and versions (or releases), visit:
# https://galaxy.ansible.com/api/v1/platforms/
#
platforms:
- name: Fedora
versions:
- 40
- name: Debian
versions:
- 12
galaxy_tags: []
# List tags for your role here, one per line. A tag is a keyword that describes
# and categorizes the role. Users find roles by searching for tags. Be sure to
# remove the '[]' above, if you add tags to this list.
#
# NOTE: A tag is limited to a single word comprised of alphanumeric characters.
# Maximum 20 tags per role.
dependencies: []
# List your role dependencies here, one per line. Be sure to remove the '[]' above,
# if you add dependencies to this list.

152
tasks/main.yml Normal file
View File

@ -0,0 +1,152 @@
---
- name: Ensure ca_fingerprint is present
assert:
that:
- ca_fingerprint is not none
fail_msg: "You must provide value for ca_fingerprint"
quiet: true
- name: Install nebula
ansible.builtin.package:
name: nebula
state: present
- name: Generate Nebula key pair
command: nebula-cert keygen -out-key {{ inventory_hostname }}.key -out-pub {{ inventory_hostname }}.pub
args:
chdir: "{{ config_prefix }}"
creates: "{{ inventory_hostname }}.pub"
- name: Copy public key of a remote host to sign locally
fetch:
flat: true
src: "{{ config_prefix }}/{{ inventory_hostname }}.pub"
dest: "{{ pub_dir }}/{{ inventory_hostname }}.pub"
- name: Check cert exists on remote host
stat:
path: "{{ config_prefix }}/{{ inventory_hostname }}.crt"
register: cert_present
- name: Fetch cert properties from remote host
when: cert_present.stat.exists
command:
cmd: 'nebula-cert print -path "{{ config_prefix }}/{{ inventory_hostname }}.crt" -json'
failed_when: cert_properties.stderr | length > 0 or cert_properties.rc != 0
check_mode: false
changed_when: false
register: cert_properties
- name: Compare groups, name, address; check cert expiration
when: cert_present.stat.exists
set_fact:
comparison:
- property: name
should_reissue: "{{ details.name != inventory_hostname }}"
name_cert: "{{ details.name }}"
name_conf: "{{ inventory_hostname }}"
- property: groups
should_reissue: "{{ groups_cert != nebula_groups }}"
groups_cert: "{{ groups_cert }}"
groups_conf: "{{ nebula_groups }}"
- property: ips
should_reissue: "{{ ips_cert != nebula_addr }}"
ips_cert: "{{ ips_cert }}"
ips_conf: "{{ nebula_addr }}"
- property: ca
should_reissue: "{{ ca_cert != ca_fingerprint }}"
ca_cert: "{{ ca_cert }}"
ca_conf: "{{ ca_fingerprint }}"
- property: expiration
should_reissue: "{{ days_left | int < days_left_threshold | int }}"
days_left: "{{ days_left }}"
vars:
details: "{{ (cert_properties.stdout | from_json).details }}"
groups_cert: "{{ details.groups | join(',') }}"
ips_cert: "{{ details.ips | join(',') }}"
ca_cert: "{{ cert_present.stat.exists and (cert_properties.stdout | from_json).details.issuer }}"
days_left: "{{ ((cert_properties.stdout | from_json).details.notAfter | to_datetime('%Y-%m-%dT%H:%M:%S%z') - now_ts | to_datetime('%Y-%m-%dT%H:%M:%S%z')).days }}"
- name: Set do_reissue
when: cert_present.stat.exists
set_fact:
do_reissue: "{{ comparison | map(attribute='should_reissue') | select('equalto', true) | list | length > 0 }}"
- name: Log reason for certificate reissuance
when: do_reissue
debug:
var: comparison | selectattr('should_reissue')
- name: Issue certificate
when: not cert_present.stat.exists or do_reissue
delegate_to: localhost
shell: >
nebula-cert sign \
-ca-crt {{ ca_crt | quote }} \
-ca-key {{ ca_key | quote }} \
{% if duration %}
-duration {{ duration | quote }} \
{% endif %}
-in-pub "{{ pub_dir }}/{{ inventory_hostname }}.pub" \
-name {{ inventory_hostname | quote }} \
-ip {{ nebula_addr | quote }} \
{% if nebula_groups %}
--groups {{ nebula_groups | quote }} \
{% endif %}
-out-crt {{ inventory_hostname | quote }}.crt
- name: Log new cert data
when: not cert_present.stat.exists or do_reissue
delegate_to: localhost
shell: >
nebula-cert print -path {{ inventory_hostname | quote }}.crt -json >> {{ ct_log_file | quote }}
- name: Copy issued certificate
notify: nebula_reload
when: not cert_present.stat.exists or do_reissue
copy:
src: "{{ inventory_hostname }}.crt"
dest: "{{ config_prefix }}/{{ inventory_hostname }}.crt"
- name: Delete issued certificate from management node
delegate_to: localhost
when: not cert_present.stat.exists or do_reissue
file:
path: "{{ inventory_hostname }}.crt"
state: absent
- name: Generate Nebula ssh host key
shell: >
ssh-keygen -t ed25519 -f ssh_host_ed25519_key -N "" < /dev/null
args:
chdir: "{{ config_prefix }}"
creates: ssh_host_ed25519_key
- name: Copy nebula config
notify: nebula_reload
copy:
src: "{{ configs_dir }}/{{ inventory_hostname }}.yaml"
dest: "{{ config_prefix }}/config.yml"
- name: Verify configuration
command: "nebula -test -config {{ config_prefix }}/config.yml"
changed_when: false
- name: Enable nebula service (systemd)
when: service_manager == "systemd"
systemd_service:
name: "{{ nebula_service_name }}"
enabled: true
state: started
- name: Enable nebula service (runit)
when: service_manager == "runit"
file:
src: /etc/sv/nebula
dest: /var/service/nebula
state: link

2
tests/inventory Normal file
View File

@ -0,0 +1,2 @@
localhost

5
tests/test.yml Normal file
View File

@ -0,0 +1,5 @@
---
- hosts: localhost
remote_user: root
roles:
- nebula

4
vars/main.yml Normal file
View File

@ -0,0 +1,4 @@
---
now_ts: "{{ ('%Y-%m-%dT%H:%M:%S%z' | strftime) }}"
do_reissue: false
ca_mismatch: false