From 04b7ba3a33bded61429bf18f0513983c5ab08eb3 Mon Sep 17 00:00:00 2001 From: pennae Date: Sun, 1 Oct 2023 18:41:26 +0200 Subject: add *some* documentation --- doc/book.toml | 2 ++ doc/default.nix | 47 ++++++++++++++++++++++++++++++++++ doc/src/SUMMARY.md | 6 +++++ doc/src/how-to.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 129 insertions(+) create mode 100644 doc/book.toml create mode 100644 doc/default.nix create mode 100644 doc/src/SUMMARY.md create mode 100644 doc/src/how-to.md (limited to 'doc') diff --git a/doc/book.toml b/doc/book.toml new file mode 100644 index 0000000..bb3ccc2 --- /dev/null +++ b/doc/book.toml @@ -0,0 +1,2 @@ +[book] +title = "dewclaw documentation" diff --git a/doc/default.nix b/doc/default.nix new file mode 100644 index 0000000..95b9dea --- /dev/null +++ b/doc/default.nix @@ -0,0 +1,47 @@ +{ pkgs ? import { config = {}; overlays = []; } +}: + +let + evaluated = pkgs.lib.evalModules { + modules = [ + ../openwrt + ]; + specialArgs = { + inherit pkgs; + }; + }; + + optionsDoc = pkgs.nixosOptionsDoc { + inherit (evaluated) options; + transformOptions = opt: + let + cwd = toString ../.; + shorten = decl: + let + removed = pkgs.lib.removePrefix cwd decl; + in + if removed != decl + then { + url = + "https://git.eno.space/dewclaw.git/tree${removed}" + + (if pkgs.lib.hasSuffix ".nix" removed + then "" + else "/default.nix"); + name = ""; + } + else removed; + in + opt // { declarations = map shorten opt.declarations; }; + }; +in + +pkgs.runCommand "dewclaw-book" { + src = ./src; + buildInputs = [ pkgs.mdbook ]; +} '' + cp -r --no-preserve=all $src ./src + ln -s ${optionsDoc.optionsCommonMark} ./src/options.md + ln -s ${../README.md} ./src/README.md + mdbook build + mv book $out +'' diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md new file mode 100644 index 0000000..2040fd3 --- /dev/null +++ b/doc/src/SUMMARY.md @@ -0,0 +1,6 @@ +# Summary + +[But why?](./README.md) + +- [How to use this](./how-to.md) +- [Options documentation](./options.md) diff --git a/doc/src/how-to.md b/doc/src/how-to.md new file mode 100644 index 0000000..a78f3c5 --- /dev/null +++ b/doc/src/how-to.md @@ -0,0 +1,74 @@ +# How to use + +dewclaw can declaratively manage some (but by far not all) aspects of OpenWRT devices. +Packages can be installed (and subsequently removed) declaratively by listing them in the `packages` option. +UCI configs can be set declaratively using the `uci.settings` hierarchy, or be marked for imperative configuration by adding the appropriate package names to `uci.retain`. +Files in `/etc` can be create with the `etc` hierarchy. + +## Mapping UCI options + +Mapping existing UCI configurations to `uci.settings` values is straight-forward starting with the output of `uci show`. UCI outputs its configuration in a specific format: +``` +package.namedSection=type1 +package.namedSection.option='value' +package.namedSection.list='value1' 'value2' ... +package.@anonSection=type2 +package.@anonSection.option='value' +``` + +In dewclaw `package` is the top level of keys in `uci.settings`, `type` is the second level, and below the `type` level we either have a third `namedSection` level or a list of `anonSection`s. +Each named or anonymous section is itself a set of `option = value` assignments. +dewclaw cannot mix named and anonymous sections, any given type must be configured entirely with named sections or entirely with unnamed sections. + +The example `uci show` output above would thus map to the following dewclaw device configuration: +```nix +openwrt.router.uci.settings = { + package.type1 = { + namedSection = { + option = "value"; + list = [ "value1" "value2" ]; + }; + }; + + package.type2 = [ + { + option = "value"; + } + ]; +} +``` + +Option values may be any UCI-compatible type: strings, paths and integers are passed through, booleans are converted to `0/1`. +Additionally there is support for secret values, with a [sops] secrets backend built into dewclaw directly. +Secrets are loaded from a backend during deployment time and will be interpolated into the generated UCI config. +To load an option value from a secret, set `option._secret = "secretName"` in `uci.settings`. + +## Building a configuration + +Once a configuration for any number of devices is written it can be passed to dewclaw and built into a set of deployment scripts: +```nix +{ pkgs ? import {} }: + +import { + inherit pkgs; + configuration = ./config.nix; +} +``` + +All `openwrt` device configurations listed in `config.nix` will be built, each producing a stand-alone deployment script, and provided in a single nix output. + +## Deploying a configuration + +Building the provided example produces an output with a single deployment script, `deploy-example`, that can be run without arguments to deploy to the assigned target and reboot the device. +The deployment process on the device will take a snapshot of the current device configuration, apply changes as needed to satisfy the new configuration, and wait for confirmation that the new configuration is acceptable. +The deployment script provides this confirmation by reconnecting to the device after it has rebooted, if this reconnection succeeds the configuration is accepted. + +After a reboot the device will wait for a set amount of time before automatically rolling back to the previous configuration. + +### Reload-only deployment + +Deploy scripts also accept a `--reload` argument to instruct the device to only reload UCI configuration instead of rebooting. +This is faster and less disruptive but may have unintended side-effects on services that are not properly configured by OpenWRT's `reload_config` and should thus be used with care. +Despite not rebooting to apply the configuration this mode also takes a snapshot and performs a rollback if no confirmation is provided. + +[sops]: https://github.com/getsops/sops -- cgit v1.2.3