Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document reloadable configs #125

Merged
merged 2 commits into from
May 29, 2024
Merged

Document reloadable configs #125

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0e45aa7
Document reloadable configs
IanVS May 22, 2024
c577e59
Add note about cert reloading
IanVS May 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions docs/config/firewall.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,8 @@ firewall:

## firewall.outbound

<Pill className="mb-24">Reloadable</Pill>

It is quite common to allow any outbound traffic to flow from a host. This simply means that the host can use any port
or protocol to attempt to connect to any other host in the overlay network. (Whether or not those other hosts allow that
inbound traffic is up to them.)
Expand All @@ -129,12 +131,14 @@ outbound:

## firewall.inbound

<Pill className="mb-24">Reloadable</Pill>

At a minimum, it is recommended to enable ICMP so that `ping` can be used to verify connectivity. Additionally, if
enabling the built-in Nebula SSH server, you may wish to grant access over the Nebula network via firewall rules.

## firewall.default_local_cidr_any

<Pill className="mb-24">Default: True</Pill>
<Pill className="mb-24">Default: True</Pill> <Pill className="mb-24">Reloadable</Pill>

This setting was introduced in Nebula v1.9.0 for backwards compatibility purposes. The default will be changed to
`false` in Nebula v1.10.0 and the config option will be deprecated.
Expand All @@ -149,6 +153,8 @@ in the `local_cidr` field.

## firewall.conntrack

<Pill className="mb-24">Reloadable</Pill>

Settings for the Connection Tracker.

```yml
Expand All @@ -160,7 +166,7 @@ conntrack:

## outbound_action, inbound_action

<Pill className="mb-24">Default: drop</Pill>
<Pill className="mb-24">Default: drop</Pill> <Pill className="mb-24">Reloadable</Pill>

Action to take when a packet is not allowed by the firewall rules.

Expand Down
12 changes: 11 additions & 1 deletion docs/config/lighthouse.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,14 +118,16 @@ lighthouse:

## lighthouse.interval

<Pill className="mb-24">Default: 10</Pill>
<Pill className="mb-24">Default: 10</Pill> <Pill className="mb-24">Reloadable</Pill>

`interval` specifies how often a nebula host should report itself to a lighthouse. By default, hosts report themselves
to lighthouses once every 10 seconds. Use caution when changing this interval, as it may affect host discovery times in
a large nebula network.

## lighthouse.hosts

<Pill className="mb-24">Reloadable</Pill>

:::warning

This should be empty on lighthouse nodes
Expand All @@ -143,6 +145,8 @@ lighthouse:

## lighthouse.remote_allow_list

<Pill className="mb-24">Reloadable</Pill>

`remote_allow_list` allows you to control ip ranges that this node will consider when handshaking to another node. By
default, any remote IPs are allowed. You can provide CIDRs here with `true` to allow and `false` to deny. The most
specific CIDR rule applies to each remote. If all rules are "allow", the default will be "deny", and vice-versa. If both
Expand All @@ -162,6 +166,8 @@ lighthouse:

## lighthouse.local_allow_list

<Pill className="mb-24">Reloadable</Pill>

`local_allow_list` allows you to filter which local IP addresses we advertise to the lighthouses. This uses the same
logic as `remote_allow_list`, but additionally, you can specify an `interfaces` map of regular expressions to match
against interface names. The regexp must match the entire name. All interface rules must be either true or false (and
Expand All @@ -180,6 +186,8 @@ lighthouse:

## lighthouse.advertise_addrs

<Pill className="mb-24">Reloadable</Pill>

`advertise_addrs` are routable addresses that will be included along with discovered addresses to report to the
lighthouse. The format is "ip:port". `port` can be `0`, in which case the actual listening port will be used in its
place, useful if `listen.port` is set to `0`. This option is mainly useful when there are static IP addresses the host
Expand All @@ -188,6 +196,8 @@ multiple paths to the internet.)

## lighthouse.calculated_remotes

<Pill className="mb-24">Reloadable</Pill>

:::danger

EXPERIMENTAL: This option may change or disappear in the future. This setting allows nebula to "guess" what the remote
Expand Down
8 changes: 5 additions & 3 deletions docs/config/logging.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,24 +17,26 @@ logging:

## logging.level

<Pill className="mb-24">Default: info</Pill>
<Pill className="mb-24">Default: info</Pill> <Pill className="mb-24">Reloadable</Pill>

Controls the verbosity of logs. The options are `panic`, `fatal`, `error`, `warning`, `info`, or `debug`.

## logging.format

<Pill className="mb-24">Default: text</Pill>
<Pill className="mb-24">Default: text</Pill> <Pill className="mb-24">Reloadable</Pill>

Controls the logging format. The options are `json` or `text`

## logging.disable_timestamp

<Pill className="mb-24">Default: False</Pill>
<Pill className="mb-24">Default: False</Pill> <Pill className="mb-24">Reloadable</Pill>

Disables timestamp logging. Useful when output is redirected to logging system that already adds timestamps.

## logging.timestamp_format

<Pill className="mb-24">Reloadable</Pill>

`timestamp_format` is specified in Go time format, see: https://golang.org/pkg/time/#pkg-constants.

The default when `format: json` is set is an [RFC3339 timestamp](https://datatracker.ietf.org/doc/html/rfc3339), e.g.
Expand Down
17 changes: 13 additions & 4 deletions docs/config/pki.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ pki:

## pki.ca

<Pill className="mb-24">Required</Pill>
<Pill className="mb-24">Required</Pill> <Pill className="mb-24">Reloadable</Pill>

The `ca` is a collection of one or more certificate authorities this host should trust. In the above example,
`/etc/nebula/ca.crt` contains PEM-encoded data for each CA we should trust, concatenated into a single file. The
Expand All @@ -39,22 +39,31 @@ pki:

## pki.cert

<Pill className="mb-24">Required</Pill>
<Pill className="mb-24">Required</Pill> <Pill className="mb-24">Reloadable</Pill>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should note that while a certificate is reloadable, it will only be accepted if the ip address hasnt changed. All other properties of the cert can change though


:::note

A new certificate will only take effect after a reload if the IP address has not changed, but all other properties of
the certificate can be changed.

:::

The `cert` is a certificate unique to every host on a Nebula network. The certificate identifies a host’s IP address,
name, and group membership within a Nebula network. The certificate is signed by a certificate authority when created,
which informs other hosts on whether to trust a particular host certificate.

## pki.key

<Pill className="mb-24">Required</Pill>
<Pill className="mb-24">Required</Pill> <Pill className="mb-24">Reloadable</Pill>

The `key` is a private key unique to every host on a Nebula network. It is used in conjunction with the host certificate
to prove a host’s identity to other members of the Nebula network. The private key should never be shared with other
hosts.

## pki.blocklist

<Pill className="mb-24">Reloadable</Pill>

:::note

The blocklist is _not_ distributed via Lighthouses. To ensure access to your entire network is blocked you must
Expand All @@ -69,6 +78,6 @@ stolen or compromised.

## pki.disconnect_invalid

<Pill className="mb-24">Default: False</Pill>
<Pill className="mb-24">Default: False</Pill> <Pill className="mb-24">Reloadable</Pill>

`disconnect_invalid` is a toggle to force a client to be disconnected if the certificate is expired or invalid.
4 changes: 4 additions & 0 deletions docs/config/preferred-ranges.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,12 @@ sidebar_position: 8
description: Configure the priority order of underlay IP addresses to increase performance and reduce latency.
---

import { Pill } from '@components/Pill/Pill';

# preferred_ranges

<Pill className="mb-24">Reloadable</Pill>

`preferred_ranges` sets the priority order for underlay IP addresses. Two hosts on the same LAN would likely benefit
from having their tunnels use the LAN IP addresses rather than the public IP addresses the lighthouse may have learned
for them. `preferred_ranges` accepts a list of [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)
Expand Down
6 changes: 3 additions & 3 deletions docs/config/punchy.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,21 +26,21 @@ punchy:

## punchy.respond

<Pill className="mb-24">Default: False</Pill>
<Pill className="mb-24">Default: False</Pill> <Pill className="mb-24">Reloadable</Pill>

`respond` means that a node unable to receive handshakes will attempt to initiate a handshake to the host attempting to
establish a tunnel, which can be the case when hole punching fails in one direction. This can be extremely useful if one
node is behind a difficult nat, such as a symmetric NAT.

## punchy.respond_delay

<Pill className="mb-24">Default: 5s</Pill>
<Pill className="mb-24">Default: 5s</Pill> <Pill className="mb-24">Reloadable</Pill>

Delay before attempting punchy.respond. respond must be true to take effect.

## punchy.delay

<Pill className="mb-24">Default: 1s</Pill>
<Pill className="mb-24">Default: 1s</Pill> <Pill className="mb-24">Reloadable</Pill>

`delay` slows down punch responses which can be helpful for conditions where a NAT is unable to handle certain race
conditions. `respond` must be true to take effect. Changing this value while running will not affect any in progress
Expand Down
6 changes: 6 additions & 0 deletions docs/config/relay.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ sidebar_position: 9
description: Configure Nebula relays to forward packets between hosts with tricky connectivity issues.
---

import { Pill } from '@components/Pill/Pill';

# relay

:::note
Expand Down Expand Up @@ -36,6 +38,8 @@ their own config.

## relay.relays

<Pill className="mb-24">Reloadable</Pill>

`relays` is a list of Nebula IPs that peers can use to relay packets to this host. IPs in this list must have `am_relay`
set to `true` in their configs, otherwise they will reject relay requests.

Expand All @@ -50,6 +54,8 @@ will indicate its supported relays in addition to its known IP addresses.

## relay.am_relay

<Pill className="mb-24">Reloadable</Pill>

Set `am_relay` to true to enable forwarding packets for other hosts. This host will only forward traffic for hosts which
specify it as a relay in their own config file. The default is false.

Expand Down
8 changes: 7 additions & 1 deletion docs/config/sshd.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,17 +30,21 @@ See also the [Debugging with Nebula SSH commands](/docs/guides/debug-ssh-command

## sshd.enabled

<Pill className="mb-24">Default: False</Pill>
<Pill className="mb-24">Default: False</Pill> <Pill className="mb-24">Reloadable</Pill>

`enabled` toggles this feature globally.

## sshd.listen

<Pill className="mb-24">Reloadable</Pill>

`listen` is used to specify the host ip and port number for the nebula debug console to listen on, port 22 is not
allowed for your safety.

## sshd.host_key

<Pill className="mb-24">Reloadable</Pill>

`host_key` points to a file containing the ssh host private key to use for the ssh server side of the console. In the
above example, `/path/to/ssh_host_ed25519_key` contains a PEM-encoded SSH host key. The following example shows a host
key inlined as a YAML multiline string.
Expand Down Expand Up @@ -70,6 +74,8 @@ You can generate a host key using the `ssh-keygen` command line utility.

## sshd.authorized_users, user, keys

<Pill className="mb-24">Reloadable</Pill>

These options are how you create `users` for the debug ssh daemon. Password authentication for the ssh debug console is
NOT supported.

Expand Down
6 changes: 5 additions & 1 deletion docs/config/tun.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,12 +58,14 @@ Default is 500.

## tun.mtu

<Pill className="mb-24">Default: 1300</Pill>
<Pill className="mb-24">Default: 1300</Pill> <Pill className="mb-24">Reloadable: Linux</Pill>

Default MTU for every packet, safe setting is (and the default) 1300 for internet routed packets.

## tun.routes

<Pill className="mb-24">Reloadable</Pill>

Route based MTU overrides. If you have known VPN IP paths that can support larger MTUs you can increase/decrease them
here.

Expand All @@ -76,6 +78,8 @@ tun:

## tun.unsafe_routes

<Pill className="mb-24">Reloadable</Pill>

:::warning

The nebula certificate of the `via` node MUST have the `route` defined as a subnet in its certificate or it will refuse
Expand Down
Loading