From 54526c1e11a83a6905bd430f769fdff808d75cb9 Mon Sep 17 00:00:00 2001
From: Daniel Barlow <dan@telent.net>
Date: Sun, 17 Sep 2023 00:07:14 +0100
Subject: [PATCH] start writing configuration guide

---
 doc/configuration.rst | 86 +++++++++++++++++++++++++++++++++++++++++++
 doc/index.rst         |  1 +
 2 files changed, 87 insertions(+)
 create mode 100644 doc/configuration.rst

diff --git a/doc/configuration.rst b/doc/configuration.rst
new file mode 100644
index 0000000..90b3a24
--- /dev/null
+++ b/doc/configuration.rst
@@ -0,0 +1,86 @@
+Configuration and Module Guide
+##############################
+
+Liminix uses the Nix language to provide congruent configuration.
+This means that to change anything about the way in which a
+Liminix system works, you make that change in
+:file:`configuration.nix` (or one of the other files it references)
+and rerun :command:`nix-build` or :command:`liminix-rebuild` to action
+the change. It is not possible (at least, without shenanigans) to make
+changes by logging into the device and running imperative commands
+whose effects may later be overridden: :file:`configuration.nix`
+always describes the entire system and can be used to recreate that
+system at any time.  You can usefully keep it under version control.
+
+If you are familiar with NixOS, you will notice some similarities
+between NixOS and Liminix configuration, and also some
+differences. Sometimes the differences are due to the
+resource-constrained devices we deploy onto, sometimes due to
+differences in the uses these devices are put to.
+
+
+Configuration taxonomy
+**********************
+
+There are many things you can specify in a configuration, but these
+are the ones you most commonly need to change:
+
+* which services (processes) to run
+* what packages to install
+* permitted users and groups
+* Linux kernel configuration options
+* Busybox applets
+* filesystem layout
+
+
+Modules
+*******
+
+**Modules** are a means of abstraction which allow "bundling"
+of configuration options related to a common purpose or theme. For
+example, the ``dnsmasq`` module defines a template for a dnsmasq
+service, ensures that the dnsmasq package is installed, and provides a
+dnsmasq user and group for the service to run as. The ``ppp`` module
+defines a service template and also enables various PPP-related kernel
+configuration.
+
+Not all modules are included in the configuration by default, because
+that would mean that the kernel (and the Busybox binary providing
+common CLI tools) was compiled with many unnecessary bells and whistles
+and therefore be bigger than needed. (This is not purely an academic concern
+if your device has little flash storage).  Therefore, specifying a
+service is usually a two-step process.  For example, to add an NTP
+service you first add :file:`modules/ntp` to your ``imports`` list,
+then you create a service by calling
+:code:`config.system.service.ntp.build { .... }` with the appropriate
+service-dependent configuration parameters.
+
+.. code-block:: nix
+
+  let svc = config.system.service;
+  in {
+    # ...
+    imports = [
+      ./modules/ntp
+      # ....
+    ];
+    config.services.ntp = svc.ntp.build {
+      pools = { "pool.ntp.org" = ["iburst"]; };
+      makestep = { threshold = 1.0; limit = 3; };
+    };
+
+Merely including the module won't define the service on its own: it
+only creates the template in ``config.system.service.foo`` and you
+have to create an actual service using the template. This is an
+intentional choice to allow the creation of multiple
+differently-configured services based on the same template - perhaps
+e.g. when you have multiple networks (VPNs etc) in different trust
+domains, or you want to run two SSH daemons on different ports.
+
+.. tip:: Liminix modules should be quite familiar (but also different)
+	 if you already know how to use NixOS modules. We use the
+	 NixOS module infrastructure code, meaning that you should
+	 recognise the syntax, the type system, the rules for
+	 combining configuration values from different sources. We
+	 don't use the NixOS modules themselves, because the
+	 underlying system is not similar enough for them to work.
diff --git a/doc/index.rst b/doc/index.rst
index 19472ad..28ce81d 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -6,6 +6,7 @@ Liminix
    :caption: Contents:
 
    tutorial
+   configuration
 
 
 Indices and tables