From d2e4f916e3f269e7ad1f4c1e840e1475a5894895aa8186f8f583d07408df6439 Mon Sep 17 00:00:00 2001 From: ADAM David Alan Martin Date: Mon, 11 May 2026 17:07:21 -0400 Subject: [PATCH] A lot more documentation. --- README.md | 4 ++-- docs/add_canned_isp.md | 38 ++++++++++++++++++++++++++++++ docs/add_net.md | 36 +++++++++++++++++++++++++++++ docs/add_route_policy.md | 30 ++++++++++++++++++++++++ docs/add_v4_net.md | 36 ++++++++++++++++++++++++++++- docs/add_v6_net.md | 41 +++++++++++++++++++++++++++++++++ docs/add_vlan.md | 8 +++++++ docs/add_wireguard_interface.md | 34 +++++++++++++++++++++++++++ docs/add_wireguard_route.md | 29 +++++++++++++++++++++++ docs/clone_interface.md | 24 +++++++++++++++++++ 10 files changed, 277 insertions(+), 3 deletions(-) create mode 100644 docs/add_canned_isp.md create mode 100644 docs/add_route_policy.md create mode 100644 docs/add_wireguard_interface.md create mode 100644 docs/add_wireguard_route.md create mode 100644 docs/clone_interface.md diff --git a/README.md b/README.md index 2f3e9c1..b9c0919 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ $ git add rc.conf $ git submodule add rc.router https://gitea.nerdland.org/adam/rc.router $ git commit -m "FIRST POST!!!" $ echo 'rc_router_dir="/etc/router-conf/rc.router"' >> /etc/rc.conf -$ echo 'rc_router_conf_dif="/etc/router-conf"' >> /etc/rc.conf +$ echo 'rc_router_conf_dir="/etc/router-conf"' >> /etc/rc.conf $ echo ". ${rc_router_dir}/rc.entry" >> /etc/rc.conf ``` @@ -69,7 +69,7 @@ $ git add rc.conf $ git submodule add rc.router https://gitea.nerdland.org/adam/rc.router $ git commit -m "FIRST POST!!!" $ echo 'rc_router_dir="/etc/router-conf/rc.router"' >> /etc/rc.conf -$ echo 'rc_router_conf_dif="/etc/router-conf"' >> /etc/rc.conf +$ echo 'rc_router_conf_dir="/etc/router-conf"' >> /etc/rc.conf $ echo ". ${rc_router_dir}/rc.entry" >> /etc/rc.conf ``` diff --git a/docs/add_canned_isp.md b/docs/add_canned_isp.md new file mode 100644 index 0000000..d598270 --- /dev/null +++ b/docs/add_canned_isp.md @@ -0,0 +1,38 @@ +# `add_canned_isp` Command + +## Name + +`add_canned_isp` + +## Synopsis + +``` +add_canned_isp ${interface} ${custom_name} ${isp_name} +``` + +## Description + +Adds and configures an upstream ISP's connection interface. This attempts to +provision the connection as dual stack, both IPv4 and IPv6. Interfaces that +are external cannot also be internal. ISP interfaces will be added to the +`external` interface group, for ease of reference in `pf.conf` firewall rules. + +The specified `${interface}` will be provisioned for ISP uplink, according to +the specified `${isp_name}` configuration rules. + +The `${custom_name}` parameter provides a user-defined name for a specific ISP +link, which can be used with the `isp=...` options of [`add_net`](add_net.md) and +related scripts. It can be the same as `${isp_name}` but it does not have to be. + +The `${isp_name}` references ISP "hints" files in `${rc_router_dir}/hints` and +`${rc_router_conf_dir}/hints`. The latter of which can be populated with +user-defined ISP hints. + +ISPs are always configured as `dhcp` for IPv4. For custom static provisioning, +other methods of provisioning these interfaces can be used. + +## See Also + + - [`add_net`](add_net.md) + - [`add_vlan`](add_vlan.md) + - [`clone_interface`](clone_interface.md) diff --git a/docs/add_net.md b/docs/add_net.md index 0dec2a9..7dd9b4c 100644 --- a/docs/add_net.md +++ b/docs/add_net.md @@ -41,6 +41,42 @@ skip provisioning the specified network with any ISP's DHCPv6 `IA_PD` request. This calls [`add_v4_net`](add_v4_net.md) and [`add_v6_net`](add_v6_net.md) and passes all of its arguments. +## Subnet Calculation + +(It is strongly recommended that the 10s digit and 1000s digit of the VLAN ID be +kept as `0`, as those digits are reserved for future improvements. While this +limits the system to 100 vlans, it provides 1:1 visual alignment between IPv4, +IPv6, and VLAN ID. Each can be visually compared to the others.) + +|VLAN|IPv4 (3rd octet)|IPv6 suffix (hex)|Example IPv4 |Example IPv6 | +|---:|---------------:|----------------:|--------------:|-----------------------:| +| 7| 7 | 7 |192.168.7.0/24 |2001:db8:abcd:ef07:::/64| +| 101|11 | 11 |192.168.11.0/24|2001:db8:abcd:ef11:::/64| +| 205|25 | 25 |192.168.25.0/24|2001:db8:abcd:ef25:::/64| +| 900|90 | 90 |192.168.90.0/24|2001:db8:abcd:ef25:::/64| + +## Options + + - `no_ula` - Do not create a Unique Local Address for this network (on the IPv6 + side). + - `isp=${NAME}` - Attach this network to a specified ISP's configuration + - `no_isp` - This network should not be associated with any ISP (declines to + add network to DHCPv6 PD, among other things). + +## Examples + +#### Basic home LAN +`add_net abc2 100 main` + +#### Guest network with no ULA +`add_net xy2 102 guest no_ula` + +#### IoT network with no ULA and no ISP prefix delegation +`add_net xy2 103 iot no_ula no_isp` + +#### Management network on a different ISP PD +`add_net xy2 402 mgmt isp=fios_1` + ## See Also - [`add_v4_net`](add_v4_net.md) diff --git a/docs/add_route_policy.md b/docs/add_route_policy.md new file mode 100644 index 0000000..7034764 --- /dev/null +++ b/docs/add_route_policy.md @@ -0,0 +1,30 @@ +# `add_route_policy` Command + +## Name + +`add_route_policy` + +## Synopsis + +`add_route_policy ${ipv6_prefix} ${fib_number}` + +## Description + +Configures internal variables to cause `rc.d` scripts to generate pf rules that +route traffic originating from the specified `${ipv6_prefix}` to be routed +according to the rules in the specified `fib_number`. + +## Examples + +#### Send traffic from internal prefix `fd12:3456:789a:bcde::/64` through a friend's network on fib 42 + +``` +static_routes="${static_routes} my_friend" +route_my_friend="-6 :: 2001:db8:f000:b000::1 -fib 42" # This specifies a default route for fib 42. +add_route_policy fd12:3456:789a:bcde::/64 42 +``` + +## See Also + + - [`add_wireguard_route`](add_wireguard_route.md) + - [`add_wireguard_interface`](add_wireguard_interface.md) diff --git a/docs/add_v4_net.md b/docs/add_v4_net.md index 28a7c4b..e9e5139 100644 --- a/docs/add_v4_net.md +++ b/docs/add_v4_net.md @@ -7,7 +7,7 @@ ## Synopsis ``` -add_v4_net ${card} ${vlan} ${group} [{no_ula|isp=abc|no_isp}...] +add_v4_net ${card} ${vlan} ${group} [{isp=abc|no_isp}...] ``` ## Description @@ -27,6 +27,40 @@ the range `.100` to `.200` will be used as a dynamic allocation pool. Internally, this will call [`add_vlan`](add_vlan.md), passing it `${card}` and `${vlan}`. +## Subnet Calculation + +(It is strongly recommended that the 10s digit and 1000s digit of the VLAN ID be +kept as `0`, as those digits are reserved for future improvements. While this +limits the system to 100 vlans, it provides 1:1 visual alignment between IPv4, +IPv6, and VLAN ID. Each can be visually compared to the others.) + +|VLAN|IPv4 (3rd octet)|Example IPv4 | +|---:|---------------:|--------------:| +| 7| 7 |192.168.7.0/24 | +| 101|11 |192.168.11.0/24| +| 205|25 |192.168.25.0/24| +| 900|90 |192.168.90.0/24| + +## Options + + - `isp=${NAME}` - Attach this network to a specified ISP's configuration + - `no_isp` - This network should not be associated with any ISP (future expansion). + +## Examples + +#### Basic home LAN +`add_net abc2 100 main` + +#### Guest network with no ULA +`add_net xy2 102 guest no_ula` + +#### IoT network with no ULA and no ISP prefix delegation +`add_net xy2 103 iot no_ula no_isp` + +#### Management network on a different ISP PD +`add_net xy2 402 mgmt isp=fios_1` + + ## See Also - [`add_net`](add_net.md) diff --git a/docs/add_v6_net.md b/docs/add_v6_net.md index 00084c8..86a80df 100644 --- a/docs/add_v6_net.md +++ b/docs/add_v6_net.md @@ -37,6 +37,47 @@ on those prefixes. Internally, this will call [`add_vlan`](add_vlan.md), passing it `${card}` and `${vlan}`. +## Subnet Calculation + +(It is strongly recommended that the 10s digit and 1000s digit of the VLAN ID be +kept as `0`, as those digits are reserved for future improvements. While this +limits the system to 100 vlans, it provides 1:1 visual alignment between +IPv6 and VLAN ID. Each can be visually compared to the other.) + +|VLAN|IPv6 suffix (hex)|Example IPv6 | +|---:|----------------:|-----------------------:| +| 7| 7 |2001:db8:abcd:ef07:::/64| +| 101| 11 |2001:db8:abcd:ef11:::/64| +| 205| 25 |2001:db8:abcd:ef25:::/64| +| 900| 90 |2001:db8:abcd:ef25:::/64| + +## Options + + - `no_ula` - Do not create a Unique Local Address for this network. + - `isp=${NAME}` - Attach this network to a specified ISP's configuration + - `no_isp` - This network should not be associated with any ISP (declines to + add network to DHCPv6 PD, among other things). + +## Examples + +#### Basic home LAN +`add_v6_net abc2 100 main` + +#### Guest network with no ULA +`add_v6_net xy2 102 guest no_ula` + +#### IoT network with no ULA and no ISP prefix delegation +`add_v6_net xy2 103 iot no_ula no_isp` + +#### Management network on a different ISP PD +`add_v6_net xy2 402 mgmt isp=fios_1` + +#### Servers network with no ULA and no ISP prefix delegation and a dedicated static prefix +`add_v6_net xy2 402 hosting no_ula no_isp 2001:db8:1ab:42::` + +(This form is useful if you have your own `/48` or similar for your self-hosted +services, and that prefix gets routed to you over tunnels.) + ## See Also - [`add_net`](add_net.md) diff --git a/docs/add_vlan.md b/docs/add_vlan.md index 401dae4..14a66d4 100644 --- a/docs/add_vlan.md +++ b/docs/add_vlan.md @@ -20,7 +20,15 @@ The internal implementation prevents adding duplicate VLAN ID's to the same adaptor, by checking for their presence before adding. It can safely be used alongside manual changes to `rc.conf` changes to these variables. +## Examples + +``` +add_vlan xy0 123 # Creates xy0.123 +add_vlan abc3 765 # Creates abc3.765 +``` + ## See Also - [`add_net`](add_net.md) - [`add_v4_net`](add_v4_net.md) - [`add_v6_net`](add_v6_net.md) + - [`clone_interface`](clone_interface.md) diff --git a/docs/add_wireguard_interface.md b/docs/add_wireguard_interface.md new file mode 100644 index 0000000..d4f6b21 --- /dev/null +++ b/docs/add_wireguard_interface.md @@ -0,0 +1,34 @@ +# `add_wireguard_interface` Command + +## Name + +`add_wireguard_interface` or `add_wireguard_interfaces` + +## Synopsis + +`add_wireguard_interface ${wireguard_name} [${wireguard_name}]...` + +## Description + +Adds the specified wireguard interface name (`${wireguard_name}`) to the +`wireguard_interfaces` variable in `rc.conf`. Wireguard interfaces need +not be numbered sequentially. As usual, `/usr/local/etc/wireguard/wg0.conf` +and so forth are used to define the configuration for that tunnel. + +`add_wireguard_interfaces` exists as a convenience/readability alias to make +configuration lines which add multiple wireguard interfaces less ambiguous. + +## Examples + +#### Add a single wireguard interface + +`add_wireguard_interface wg0` + +#### Add wireguard interfaces for 0 and 1 and 2 + +`add_wireguard_interfaces 0 1 2` + +## See Also + + - [`add_vlan`](add_vlan.md) + - [`clone_interface`](clone_interface.md) diff --git a/docs/add_wireguard_route.md b/docs/add_wireguard_route.md new file mode 100644 index 0000000..138a90f --- /dev/null +++ b/docs/add_wireguard_route.md @@ -0,0 +1,29 @@ +# `add_wireguard_route` Command + +## Name + +`add_wireguard_route` + +## Synopsis + +`add_wireguard_route ${ipv6_prefix} ${wireguard_number}` + +## Description + +Creates a wireguard interface with the specified wireguard interface number +(`${wireguard_number}`), associates that intererface and the specified IPv6 +prefix (`${ipv6_prefix}`) with a fib of the same number (`${wireguard_number}`). + +Internally, this calls [`add_wireguard_interface`](add_wireguard_interface.md) and +[`add_route_policy`](add_route_policy.md), modifying and forwarding its parameters. + +## Examples + +#### Add a wireguard interface (number 3) for routing traffic from `2001:db8:3::/48` + +`add_wireguard_route 2001:db8:3::/48 3` + +## See Also + + - [`add_wireguard_interface`](add_wireguard_interface.md) + - [`add_route_policy`](add_route_policy.md) diff --git a/docs/clone_interface.md b/docs/clone_interface.md new file mode 100644 index 0000000..9b79f30 --- /dev/null +++ b/docs/clone_interface.md @@ -0,0 +1,24 @@ +# `clone_interface` Command + +## Name + +`clone_interface` + +## Synopsis + +``` +clone_interface []... +``` + +## Description + +Adds the specified NICs to the `cloned_interfaces` variable. This is a +friendly wrapper for `cloned_interfaces="${cloned_interfaces} $1"` in essence. +This command can be safely mixed with any raw variable setting of +`cloned_interfaces`, as long as care is taken in the raw variable setting +code not to overwrite the variable, but instead append to it. + +## See Also + + - [`add_vlan`](add_vlan.md) + - [`add_wireguard_interface`](add_wireguard_interface.md)