From 54526c1e11a83a6905bd430f769fdff808d75cb9 Mon Sep 17 00:00:00 2001 From: Daniel Barlow 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