Documentation fixes and improvements

README.md

@@ -11,6 +11,103 @@ for by this configuration mechanism.
 `rc.router` requires FreeBSD-15 or greater.  (It might work for some configurations
 on FreeBSD-14, but I no longer run any routers with it on FreeBSD-14.)
 
+## Prerequisites
+
+None, in particular.  The `rc.router/scripts/install-dependencies.sh` script will
+install all necessary dependency packages for FreeBSD.  Several of the
+`${rc_router_dir}/rc.d` startup scripts depend upon these.
+
+## Directory Layout
+
+#### `${rc_router_dir}/rc.d`
+
+This directory contains various startup scripts, including configuration
+file generation scripts.
+
+#### `${rc_router_dir}/defaults`
+
+This directory contains `rc.conf` defaults which are similar to
+`/etc/defaults/rc.conf`.  This file should not be edited, as user
+configurations can instead override these default options.
+
+#### `${rc_router_dir}/hints`
+
+This directory contains configuration hints for various common ISPs.
+
+#### `${rc_router_dir}/docs`
+
+This directory contains markdown formatted documentation for various `rc.conf`
+embeddable configuration commands.
+
+#### `${rc_router_dir}/templates`
+
+This directory contains the base templates for some generated file types.
+
+#### `${rc_router_dir}/harness`
+
+This directory contains a testing harness to allow running many of these
+configuration scripts outside of FreeBSD's init system, for testing and
+validation.  (Use `env RC_ROUTER_HARNESS=${path_to_harness_dir}` to
+execute one of the `rc.d` scripts or `rc.test`.)
+
+## Installation and Usage
+
+The `rc.router` configuration package is designed to be integrated with FreeBSD
+system startup for use in SOHO and Home-Lab edge routers.  It supports easy
+configuration for automatic generation of a lot of useful components.  Eventually
+the most basic use cases should be as simple as writing just two or three lines of
+configuration settings.
+
+The package is meant to integrate with `/etc/rc.conf` by setting two key
+variables to help the init system find the package and then by sourcing the
+package's entry point (`${rc_router_dir}/rc.entry`).  One can disable the entire
+package merely by commenting out that single line which sources `rc.entry`,
+which provides an easy way to diagnose if this package is causing problems.
+
+The `${rc_router_dir}` variable is meant to be set to the root directory of
+this package, and it must be mounted early enough in the boot process.  The
+`${rc_router_conf_dir}` can be set to any path which will be mounted and
+present early enough in the boot process as well.  The `${rc_router_conf_dir}`
+can be a git repository where `${rc_router_dir}` is a git submodule therein.
+This is the recommended deployment strategy, as it permits configuration
+versioning and easy-to-use rollback semantics for local configuration changes.
+
+## What it does and how it works
+
+`rc.router` will setup a number of shell script utility functions for use
+in processing `rc.conf` style configuration files.  After it does this, it
+will source `${rc_router_conf_dir}/rc.conf`.  When it does, the user's
+preferences for router settings will be processed there.
+
+These utility functions simplify the administration of a FreeBSD edge router
+and firewall by providing easy to use mechanisms to change groups of related
+`rc.conf` variables for those use cases.  For example, instead of having to
+write:
+
+```
+vlans_xy0="2"
+dhcpd_ifaces="xy0.2"
+dhcp6c_interfaces="xy0.2"
+rtadvd_interfaces="xy0.2"
+ifconfig_xy0_2="192.168.2.1/24"
+ifconfig_xy0_2_ipv6="fd12:3456:7890:2::1/64"
+# And manually configure several other related variables and configuration files
+```
+
+one could instead just write:
+```
+add_net xy0 2
+```
+
+and all the necessary `rc.conf` variables will be set by the
+[`add_net`](docs/add_net.md) command and the related DHCP configuration
+files and router advertisement configuration files will be generated.  Scripts
+such as `${rc_router_dir}/rc.d/generate_internal_dhcpv4` will generate the
+necessary configuration files from various `rc.conf` variables and hints.
+`rc.router` uses several internal variables (set by its commands) to help
+drive this process, such that more customized configurations can be
+co-mingled with its patterns.
+
 ## How to setup (Easy dual-stack example With Git)
 
 Executing this sequence of sample commands will setup a basic Dual-stack router

docs/add_canned_isp.md

@@ -31,6 +31,12 @@ 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.
 
+## Example
+```
+# Connect to Verizon FIOS over `abc0`, and name the connection `main_isp`.
+add_canned_isp abc0 main_isp verizon_fios
+```
+
 ## See Also
 
  - [`add_net`](add_net.md)

docs/add_net.md

@@ -49,11 +49,11 @@ 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|
+|   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|
+| 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|
+| 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|
+| 900|90              | 90              |192.168.90.0/24|2001:db8:abcd:ef25::/64|
 
 ## Options
 

docs/add_v6_net.md

@@ -45,11 +45,11 @@ 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|
+|   7|  7              |2001:db8:abcd:ef07::/64|
-| 101| 11              |2001:db8:abcd:ef11:::/64|
+| 101| 11              |2001:db8:abcd:ef11::/64|
-| 205| 25              |2001:db8:abcd:ef25:::/64|
+| 205| 25              |2001:db8:abcd:ef25::/64|
-| 900| 90              |2001:db8:abcd:ef25:::/64|
+| 900| 90              |2001:db8:abcd:ef25::/64|
 
 ## Options
 

docs/variables.md

@@ -99,7 +99,7 @@ rc_router_gen_dir="/tmp/rc-router-gen/"
 This variable defines the lower bound of DHCPv4 pools for auto-generated `/24`
 networks constructed by [`add_v4_net`](add_v4_net.md) or [`add_net`](add_net.md).
 These pools can also be specified per-physical-interface (but not vlan) by using
-`dhcpdv4_pool_lo_${iface}`.
+`dhcpv4_pool_lo_${iface}`.
 
 ### Example
 
@@ -117,7 +117,7 @@ dhcpv4_pool_lo_xy0="200" # For networks on `xy0`, start the dynamic pool at 200.
 This variable defines the upper bound of DHCPv4 pools for auto-generated `/24`
 networks constructed by [`add_v4_net`](add_v4_net.md) or [`add_net`](add_net.md).
 These pools can also be specified per-physical-interface (but not vlan) by using
-`dhcpdv4_pool_hi_${iface}`.
+`dhcpv4_pool_hi_${iface}`.
 
 ### Example