From 9707f951ac8247132ed4b0e2db2e160f8f7b322e Mon Sep 17 00:00:00 2001 From: Caleb Jasik Date: Fri, 7 Jun 2024 15:27:27 -0500 Subject: [PATCH 1/4] Start color coding overlay and underlay ips --- docs/config/firewall.mdx | 8 ++--- docs/config/lighthouse.mdx | 54 ++++++++++++++++++--------------- docs/config/static-host-map.mdx | 5 +-- src/components/Highlight.tsx | 21 +++++++++++++ src/components/OverlayIP.tsx | 16 ++++++++++ src/components/UnderlayIP.tsx | 16 ++++++++++ src/css/utility.css | 8 +++++ src/theme/MDXComponents.tsx | 16 ++++++++++ 8 files changed, 114 insertions(+), 30 deletions(-) create mode 100644 src/components/Highlight.tsx create mode 100644 src/components/OverlayIP.tsx create mode 100644 src/components/UnderlayIP.tsx create mode 100644 src/theme/MDXComponents.tsx diff --git a/docs/config/firewall.mdx b/docs/config/firewall.mdx index e3880c67..1dceb039 100644 --- a/docs/config/firewall.mdx +++ b/docs/config/firewall.mdx @@ -59,11 +59,11 @@ The possible fields of a firewall rule are: - `groups`: Same as `group` but accepts a list of values. Multiple values are AND'd together and a certificate must contain all groups to pass. -- `cidr`: a CIDR, `0.0.0.0/0` is any. This restricts which Nebula IP addresses the rule allows. +- `cidr`: a CIDR, `0.0.0.0/0` is any. This restricts which Nebula IP addresses the rule allows. -- `local_cidr`: a local CIDR, `0.0.0.0/0` is any. This restricts which destination IP addresses, when using - unsafe_routes, the rule allows. If unset, the rule will allow access to the specified ports on both the node itself as - well as any IP addresses it routes to. +- `local_cidr`: a local CIDR, `0.0.0.0/0` is any. This restricts which destination IP + addresses, when using unsafe_routes, the rule allows. If unset, the rule will allow access to the + specified ports on both the node itself as well as any IP addresses it routes to. :::note diff --git a/docs/config/lighthouse.mdx b/docs/config/lighthouse.mdx index 61bb4f52..025cf33f 100644 --- a/docs/config/lighthouse.mdx +++ b/docs/config/lighthouse.mdx @@ -58,14 +58,15 @@ name resolution by external DNS hosts. To enable listening on IPv6 in addition t The DNS listener can only respond to requests about hosts it's aware of. For this reason, it can only be enabled on Lighthouses. -`A` records contain the Nebula IP for a host name and can be queried by any host that can reach the DNS listener, -regardless of whether it is communicating over the Nebula network. +`A` records contain the Nebula IP for a host name and can be queried by any host that can reach +the DNS listener, regardless of whether it is communicating over the Nebula network. `TXT` records can only be queried over the Nebula network, and contain certificate information for the requested host IP address. -For example, if `192.168.100.1` was your Lighthouse node running a DNS server and you wanted to find the Nebula IP -address of a host named `web01`: +For example, if `192.168.100.1` was your Lighthouse node running a DNS server and you wanted to find the + +Nebula IP address of a host named `web01`: ```shell $ dig @192.168.100.1 +short web01 A @@ -101,8 +102,9 @@ firewall: ## lighthouse.dns `dns` is used to configure the address (`host`) and port (`port`) the DNS server should listen on. By listening on the -host's Nebula IP, you can make the DNS server accessible only on the Nebula network. Alternatively, listening on -`0.0.0.0` will allow anyone that can reach the host to make queries. +host's Nebula IP, you can make the DNS server accessible only on the Nebula network. +Alternatively, listening on `0.0.0.0` will allow anyone that can reach the host to make +queries. The default value for `dns.port` is `53` but you must set an IP address. @@ -135,7 +137,8 @@ This should be empty on lighthouse nodes ::: `hosts` is a list of lighthouse hosts this node should report to and query from. The lighthouses listed here should be -referenced by their **nebula IP**, not by the IPs of their physical network interfaces. +referenced by their **nebula IP**, not by the IPs of their physical +network interfaces. ```yml lighthouse: @@ -147,11 +150,12 @@ lighthouse: Reloadable -`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 -"allow" and "deny" rules are present, then you MUST set a rule for "0.0.0.0/0" as the default. Similarly if both "allow" -and "deny" IPv6 rules are present, then you MUST set a rule for "::/0" as the default. +`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 "allow" and "deny" rules are present, then you MUST set a rule for +"0.0.0.0/0" as the default. Similarly if both "allow" and "deny" IPv6 rules are present, then you MUST set a rule for +"::/0" as the default. ```yml lighthouse: @@ -168,10 +172,11 @@ lighthouse: Reloadable -`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 -the default will be the inverse). CIDR rules are matched after interface name rules. Default is all local IP addresses. +`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 the default will be the inverse). CIDR rules are matched after interface name rules. Default +is all local IP addresses. ```yml lighthouse: @@ -188,11 +193,11 @@ lighthouse: Reloadable -`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 -can be reached at that nebula can not typically discover on its own (e.g. when port forwarding or when the node has -multiple paths to the internet.) +`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 can be reached at that nebula can not typically discover on its own (e.g. when port +forwarding or when the node has multiple paths to the internet.) ## lighthouse.calculated_remotes @@ -205,9 +210,10 @@ might be for a host while it waits for the lighthouse response. ::: -For any Nebula IPs in the range, it will apply the mask and add the calculated IP as the initial remote (while it waits -for the response from the lighthouse). Both CIDRs must have the same mask size. For example, Nebula IP 10.0.10.123 will -have a calculated remote of 192.168.1.123. +For any Nebula IPs in the range, it will apply the mask and add the calculated +IP as the initial remote (while it waits for the response from the lighthouse). Both CIDRs must have the +same mask size. For example, Nebula IP 10.0.10.123 will have a calculated remote of +192.168.1.123. ```yml calculated_remotes: diff --git a/docs/config/static-host-map.mdx b/docs/config/static-host-map.mdx index 38877b87..adec0c5c 100644 --- a/docs/config/static-host-map.mdx +++ b/docs/config/static-host-map.mdx @@ -5,8 +5,9 @@ description: Define the static host map to enable peer discovery on the Nebula n # static_host_map -The static host map defines a set of hosts with fixed IP addresses on the internet (or any network). A host can have -multiple fixed IP addresses defined here, and nebula will try each when establishing a tunnel. The syntax is: +The static host map defines a set of hosts with fixed IP addresses on the internet (or any +network). A host can have multiple fixed IP addresses defined here, and nebula will try each +when establishing a tunnel. The syntax is: `"": [":"]` diff --git a/src/components/Highlight.tsx b/src/components/Highlight.tsx new file mode 100644 index 00000000..c2560ea5 --- /dev/null +++ b/src/components/Highlight.tsx @@ -0,0 +1,21 @@ +import React from 'react'; + +type Props = { + children: React.ReactNode; + color: string; +}; + +export default function Highlight({ children, color }: Props) { + return ( + + {children} + + ); +} diff --git a/src/components/OverlayIP.tsx b/src/components/OverlayIP.tsx new file mode 100644 index 00000000..4e8c989c --- /dev/null +++ b/src/components/OverlayIP.tsx @@ -0,0 +1,16 @@ +import Highlight from './Highlight'; + +export function OverlayIP({ children }) { + return ( + + {children} + + ); +} diff --git a/src/components/UnderlayIP.tsx b/src/components/UnderlayIP.tsx new file mode 100644 index 00000000..3433b358 --- /dev/null +++ b/src/components/UnderlayIP.tsx @@ -0,0 +1,16 @@ +import Highlight from './Highlight'; + +export function UnderlayIP({ children }) { + return ( + + {children} + + ); +} diff --git a/src/css/utility.css b/src/css/utility.css index f2d9d8d9..cad1be21 100644 --- a/src/css/utility.css +++ b/src/css/utility.css @@ -1,3 +1,11 @@ .mb-24 { margin-bottom: 24px; } + +.underlay-ip { + color: green; +} + +.overlay-ip { + color: purple; +} diff --git a/src/theme/MDXComponents.tsx b/src/theme/MDXComponents.tsx new file mode 100644 index 00000000..da417572 --- /dev/null +++ b/src/theme/MDXComponents.tsx @@ -0,0 +1,16 @@ +// Import the original mapper +import MDXComponents from '@theme-original/MDXComponents'; +import React from 'react'; +import Highlight from '@src/components/Highlight'; +import { OverlayIP } from '@src/components/OverlayIP'; +import { UnderlayIP } from '@src/components/UnderlayIP'; + +export default { + // Re-use the default mapping + ...MDXComponents, + // Map the "" tag to our Highlight component + // `Highlight` will receive all props that were passed to `` in MDX + Highlight, + OverlayIP, + UnderlayIP, +}; From cab6c7e44fecd037442a50866f85eb749550c3dc Mon Sep 17 00:00:00 2001 From: Caleb Jasik Date: Fri, 7 Jun 2024 15:31:10 -0500 Subject: [PATCH 2/4] More color coding --- docs/config/listen.mdx | 5 +++-- docs/config/preferred-ranges.mdx | 10 ++++++---- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/config/listen.mdx b/docs/config/listen.mdx index 42e14140..c3269f46 100644 --- a/docs/config/listen.mdx +++ b/docs/config/listen.mdx @@ -22,8 +22,9 @@ listen: Default: 0.0.0.0 -`host` is the ip of the interface to use when binding the listener. The default is `0.0.0.0` for all IPv4 interfaces. To -enable IPv6, use `'[::]'` instead. `host` may also contain a hostname. +`host` is the ip of the interface to use when binding the listener. The default is `0.0.0.0` +for all IPv4 interfaces. To enable IPv6, use `'[::]'` instead. `host` may also contain a +hostname. ## listen.port diff --git a/docs/config/preferred-ranges.mdx b/docs/config/preferred-ranges.mdx index b5c8fb3c..ca88dc68 100644 --- a/docs/config/preferred-ranges.mdx +++ b/docs/config/preferred-ranges.mdx @@ -9,10 +9,12 @@ import { Pill } from '@components/Pill/Pill'; Reloadable -`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) -ranges admitted as a set of preferred ranges of IP addresses. +`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) ranges admitted as a set of preferred ranges of +IP addresses. > An underlay network is the network that a nebula [overlay network](https://en.wikipedia.org/wiki/Overlay_network) maps > onto. It is the LAN network that a host is connected to in addition to the wider internet. From 1b1b9d3bc4ae94c3e19f761fe80cd288c77a66d2 Mon Sep 17 00:00:00 2001 From: Caleb Jasik Date: Fri, 7 Jun 2024 15:41:20 -0500 Subject: [PATCH 3/4] Even more color coded overlay/underlay ip addresses --- docs/config/relay.mdx | 12 +++++++----- docs/config/sshd.mdx | 4 ++-- docs/config/tun.mdx | 4 ++-- src/components/UnderlayIP.tsx | 2 +- 4 files changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/config/relay.mdx b/docs/config/relay.mdx index 68b7b803..d882904c 100644 --- a/docs/config/relay.mdx +++ b/docs/config/relay.mdx @@ -26,8 +26,8 @@ relay: In order to act as a relay for other hosts, `am_relay` must be set to true (default false.) In order to use relays, a host must have `use_relays` set to true (default true.) Any host can be a relay; it does not need to be a lighthouse. -However, like lighthouses, relay nodes should be deployed with a public internet IP and firewall rules that permit -Nebula's UDP traffic inbound. +However, like lighthouses, relay nodes should be deployed with a public internet IP and +firewall rules that permit Nebula's UDP traffic inbound. Hosts specify which other hosts may act as a relay when connecting to them via the `relays` option in the config. This allows hosts to specify relays that are "close" to them. For example, if you have some Nebula hosts in a private AWS @@ -40,8 +40,10 @@ their own config. Reloadable -`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. +`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. ```yml relays: @@ -50,7 +52,7 @@ relays: ``` This list of relays is reported to the Lighthouse. When other nodes attempt to handshake with this host, the Lighthouse -will indicate its supported relays in addition to its known IP addresses. +will indicate its supported relays in addition to its known IP addresses. ## relay.am_relay diff --git a/docs/config/sshd.mdx b/docs/config/sshd.mdx index 86a99a87..fae013b9 100644 --- a/docs/config/sshd.mdx +++ b/docs/config/sshd.mdx @@ -38,8 +38,8 @@ See also the [Debugging with Nebula SSH commands](/docs/guides/debug-ssh-command Reloadable -`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. +`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 diff --git a/docs/config/tun.mdx b/docs/config/tun.mdx index f99f0272..84e1746f 100644 --- a/docs/config/tun.mdx +++ b/docs/config/tun.mdx @@ -66,8 +66,8 @@ Default MTU for every packet, safe setting is (and the default) 1300 for interne Reloadable -Route based MTU overrides. If you have known VPN IP paths that can support larger MTUs you can increase/decrease them -here. +Route based MTU overrides. If you have known VPN IP paths that can support larger MTUs you can +increase/decrease them here. ```yml tun: diff --git a/src/components/UnderlayIP.tsx b/src/components/UnderlayIP.tsx index 3433b358..b1a7f66b 100644 --- a/src/components/UnderlayIP.tsx +++ b/src/components/UnderlayIP.tsx @@ -6,7 +6,7 @@ export function UnderlayIP({ children }) { style={{ textDecorationColor: 'green', textDecorationLine: 'underline', - textDecorationStyle: 'dotted', + textDecorationStyle: 'solid', textDecorationThickness: '2px', }} > From 22f6b530702d0ff44a024c95d8e0563ed6d4e64d Mon Sep 17 00:00:00 2001 From: Caleb Jasik Date: Tue, 11 Jun 2024 09:38:36 -0500 Subject: [PATCH 4/4] `pnpm format` --- docs/config/lighthouse.mdx | 1 + docs/config/relay.mdx | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/config/lighthouse.mdx b/docs/config/lighthouse.mdx index 025cf33f..9cb19f47 100644 --- a/docs/config/lighthouse.mdx +++ b/docs/config/lighthouse.mdx @@ -213,6 +213,7 @@ might be for a host while it waits for the lighthouse response. For any Nebula IPs in the range, it will apply the mask and add the calculated IP as the initial remote (while it waits for the response from the lighthouse). Both CIDRs must have the same mask size. For example, Nebula IP 10.0.10.123 will have a calculated remote of + 192.168.1.123. ```yml diff --git a/docs/config/relay.mdx b/docs/config/relay.mdx index d882904c..275a6765 100644 --- a/docs/config/relay.mdx +++ b/docs/config/relay.mdx @@ -42,8 +42,8 @@ their own config. `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. +IPs in this list must have `am_relay` set to `true` in their configs, otherwise they will reject +relay requests. ```yml relays: