min-copy-closure use rsync instead of rogue as demo package

this is to fix the CI job - because rsync builds and rogue presently doesn't

CODE-OF-CONDUCT.md

@@ -1,57 +0,0 @@
-# Liminix community spaces Code of Conduct
-
-As of Feb 2023, "RESPONSE TEAM" and "LEADERSHIP TEAM" in the text that follows
-both refer to me, Daniel Barlow, as there are not yet any other project members.
-
-Liminix is dedicated to providing a harassment-free experience for everyone. We do not tolerate harassment of participants in any form.
-
-This code of conduct applies to all Liminix spaces, including the IRC channel, mailing lists, and Github forums, both online and off. Anyone who violates this code of conduct may be sanctioned or expelled from these spaces at the discretion of the RESPONSE TEAM.
-
-Some Liminix spaces may have additional rules in place, which will be made clearly available to participants. Participants are responsible for knowing and abiding by these rules.
-
-Harassment includes:
-
-*Offensive comments related to gender, gender identity and expression, sexual orientation, disability, mental illness, neuro(a)typicality, physical appearance, body size, age, race, or religion.
-*Unwelcome comments regarding a person’s lifestyle choices and practices, including those related to food, health, parenting, drugs, and employment.
-*Deliberate misgendering or use of ‘dead’ or rejected names.
-*Gratuitous or off-topic sexual images or behaviour in spaces where they’re not appropriate.
-*Physical contact and simulated physical contact (eg, textual descriptions like “*hug*” or “*backrub*”) without consent or after a request to stop.
-*Threats of violence.
-*Incitement of violence towards any individual, including encouraging a person to commit suicide or to engage in self-harm.
-*Deliberate intimidation.
-*Stalking or following.
-*Harassing photography or recording, including logging online activity for harassment purposes.
-*Sustained disruption of discussion.
-*Unwelcome sexual attention.
-*Pattern of inappropriate social contact, such as requesting/assuming inappropriate levels of intimacy with others
-*Continued one-on-one communication after requests to cease.
-*Deliberate “outing” of any aspect of a person’s identity without their consent except as necessary to protect vulnerable people from intentional abuse.
-*Publication of non-harassing private communication.
-Liminix prioritizes marginalized people’s safety over privileged people’s comfort. RESPONSE TEAM reserves the right not to act on complaints regarding:
-*‘Reverse’ -isms, including ‘reverse racism,’ ‘reverse sexism,’ and ‘cisphobia’
-*Reasonable communication of boundaries, such as “leave me alone,” “go away,” or “I’m not discussing this with you.”
-*Communicating in a ‘tone’ you don’t find congenial
-*Criticizing racist, sexist, cissexist, or otherwise oppressive behavior or assumptions
-
-## Reporting
-
-If you are being harassed by a member of Liminix, notice that someone else is being harassed, or have any other concerns, please contact the RESPONSE TEAM at [email address or other contact point]. If the person who is harassing you is on the team, they will recuse themselves from handling your incident. We will respond as promptly as we can.
-
-This code of conduct applies to Liminix spaces, but if you are being harassed by a member of Liminix outside our spaces, we still want to know about it. We will take all good-faith reports of harassment by Liminix members, especially LEADERSHIP TEAM, seriously. This includes harassment outside our spaces and harassment that took place at any point in time. The abuse team reserves the right to exclude people from Liminix based on their past behavior, including behavior outside Liminix spaces and behavior towards people who are not in Liminix.
-
-In order to protect volunteers from abuse and burnout, we reserve the right to reject any report we believe to have been made in bad faith. Reports intended to silence legitimate criticism may be deleted without response.
-
-We will respect confidentiality requests for the purpose of protecting victims of abuse. At our discretion, we may publicly name a person about whom we’ve received harassment complaints, or privately warn third parties about them, if we believe that doing so will increase the safety of Liminix members or the general public. We will not name harassment victims without their affirmative consent.
-
-### Consequences
-
-Participants asked to stop any harassing behavior are expected to comply immediately.
-
-If a participant engages in harassing behavior, RESPONSE TEAM may take any action they deem appropriate, up to and including expulsion from all Liminix spaces and identification of the participant as a harasser to other Liminix members or the general public.
-
-## License and attribution
-
-The policy is based on the Geek Feminism
-[Community anti-harassment/Policy](https://geekfeminism.fandom.com/wiki/Community_anti-harassment/Policy)
-and is the work of Annalee Flower Horne with assistance from Valerie
-Aurora, Alex Skud Bayley, Tim Chevalier, and Mary Gardiner.

NEWS

@@ -156,4 +156,16 @@ https://www.liminix.org/doc/admin.html#updating-an-installed-system
 2024-12-22
 
 outputs.zimage is now outputs.kernel.zImage. This is unlikely to
-affect many people at all but I mention it anyway.
+affect many people at all but I mention it anyway.
+
+2024-03-11
+
+The fennel function (svc.open ...) now expects to be given the store
+directory of a service derivation, not a direct path to the .outputs
+directory. Thus
+
+(svc.open "/nix/store/eeeeeeeeeeeeee-hellod")
+not
+(svc.open "/nix/store/eeeeeeeeeeeeee-hellod/.outputs")
+
+This simplifies most extant uses of it

THOUGHTS.txt

@@ -7196,3 +7196,444 @@ we may still need to template the rest of the firewall if we want to have
 other variables (rate limits) in it, because the rules for that need to be
 inserted ahead of the rules for accepting icmp, and there's no way to
 do that without
+
+Sun Mar  9 21:46:30 GMT 2025
+
+OK, we have updating firewall zones that are good neough to pass the test
+(and may even work ...).  We need
+
+* to write a rule with a rate limit for incoming icmp6 for each interface,
+capping it to 5% of the interface bandwidth
+
+* some place to say what the bandwidth is, which I am thinking we could do with
+a passthru attribute of some kind on services
+
+{
+  run = "mdcnvdfngkj";
+  name = "dtret";
+  properties.bandwidthKbps = 80000;
+}
+
+and insert logic in the up/run commands to copy the properties to
+outputs.  Or we could use `data` or `env` directories, which means
+that the properties would be there even while the service is down, if
+that's a concern, but would need a different way to look them up. And
+also, would we allow them to change? What if there's some kind of interface
+where we _can_ interrogate the bandwidth at runtime?
+
+Mon Mar 10 21:00:17 GMT 2025
+
+The idea that occured to me at lunchtime is "what if we made the
+(svc:output ) method fall back to properties if no output was present".
+To do this, we'd have to
+
+(1) arrange for /nix/store/eeee-service/.properties to exist
+
+ - add properties attribute to service functions
+ - write them to .properties in liminix-tools/services/builder.sh
+ - make sure they get passed through whne provided to all the service
+    builder functions
+
+[done] (2) pass the store directory to svc.open instead of  ..../.outputs
+
+(3) make service:output look in both places
+
+(4) write the damn firewall rule
+
+Mon Mar 17 21:13:36 GMT 2025
+
+Argh why is it never simple?
+
+We need to write a rate-limiting firewall rule for each interface to
+restrict icmp on that interface. This is not easy to reconcile with
+putting them in default-rules because how do we generate multiple
+array elements by config file templating?
+
+There are two things in my mind now:
+
+1) could we have some better way of manipulating the firewall rules
+such that the rules from different modules are composable
+
+this is complicated somewhat by ordering: if every rule in a chain is
+"drop" or "accept" then it's easy to add another, but if the same
+chain does first one then the other, doing the other and then the one
+will not work
+
+today we do e.g.
+
+input-ip6
+-> reject-bogons
+-> accept non-bogus-icmp
+-> process per-zone allowlist
+-> allow established,related on wan
+-> allow all on lan (so why did we need an allowlist?)
+
+could we express this in a less sequential form? the
+specification of what's allowed
+
+
+input-ip6 for wan: is input-ip6 with the wan allowlist
+input-ip6 for lan: is input-ip6 with the lan allowlist
+
+
+input-ip6 for ppp0: is input-ip6 with the wan allowlist with a rate
+limit for icmp
+
+ssh module wishes to modify the allowlist for lan/wan/both so that
+it includes port 22
+
+am wondering if we could do default deny and _all_ the rules
+(except for bogons) are allows
+
+maybe we have the concept of "subtraction": a rule can be an allow
+preceded by some number of drops which (at least by convention; this is
+probably hard to enforce) are "carve outs" of the packets that are
+being allowed.
+
+... it's hard to express the forward-ipv6 in these terms, though.
+we end up with "some drops and then multiple accepts"
+
+we have
+(and (not (or drop1 drop2 ...)) (or accept1 accept2 ...))
+
+and to add ssh we need to break into the second clause instead of
+composing at the top level
+
+(and (not (or drop1 drop2 ...))
+     (or accept1 accept2 accept-ssh...))
+
+
+then the icmp bogons composite rule is "drop weird icmp and then
+allow what's left"
+
+(side note: maybe we could use a map to do interface name -> bandwidth
+for rate limiting)
+
+
+
+
+a composite rule might be a bunch of denies and then an allow
+for anything the
+
+2) some kinda syntax for referencing outputs (or properties) that's not
+just string interpolation
+
+
+----
+
+I think we could address the immediate problem by writing a rule for
+rate-limiting that looks up the rate in a map, and some maps (with
+extraText) that get the rates from service properties? And that would
+suffice for addressing the RoS audit, at least
+
+Tue Mar 18 18:48:22 GMT 2025
+
+Unless the interface exists, we do not (at least, may not) know its
+name because that's an output. So the fact that it has a permanent
+property is not per se terribly useful
+
+limit rate 50000 bytes / minute accept
+
+
+nft add rule ip nat postrouting snat to ip saddr map { 192.168.1.0/24 : 10.0.0.1, 192.168.2.0/24 : 10.0.0.2 }
+
+nft add rule table-ip input-ip4 ip daddr 2.2.2.3/32 limit rate iifname map { "eth0": 10, "ppp0": 20 } kbytes/second   accept
+
+nft add map 'table-ip intf-limits  { typeof 5000000 ;  elements = { lan: 50000000, ppp0: 3500000 } ; }'
+
+OK, we can't do rate lookup in a map because the nftables grammar only
+supports a numeric literal for limit_rate_bytes. so we're back to writing
+a collection of rules, one for each interface with an ifname output,
+that sets the limit for that interface
+
+* we could do this all in one element of a rules list, with newlines
+between each actual rule
+
+* we could add extraText to the ruleset syntax - but does it go at the
+start of the rules or the end or somewhere in the middle? this is
+almost worse
+
+* we could pick up where we left off on march 17 and redesign the
+  firewall module
+
+gonna be option 1 isn't it?
+
+Tue Mar 25 00:13:31 GMT 2025
+
+the logic for watch-outputs is not correct
+
+(1) when we first read outputs, how do we know if the controlled
+service is up to date wrt those outputs? we should perform the action
+for the first time after reading initial state and before waiting
+
+(2) it isn't writing the new outputs back into trees, so will refresh
+continually after the fisrt change
+
+set tree to empty for each service
+loop:
+for each service
+  read new tree
+  if different
+    do action
+    set tree = new tree
+wait for changes
+next iteration
+
+Fri Mar 28 23:25:49 GMT 2025
+
+the ppp connection doesn't come back after a&a reset the lns, this has
+happened twice now. Possibly-relevant log entries:
+
+
+2025-03-27 01:10:20.189135502 rotuer dhcp6c.prefix.dhcp6c.wan.link.pppoe.int.link.a.192.168.8.1 Executed "ip address change 2001:8b0:de3a:40de::1/64 dev int valid_lft 5682 preferred_lft 5682", exit code true
+2025-03-27 01:10:20.189182063 rotuer dhcp6c.addr.dhcp6c.wan.link.pppoe.wan.link.pppoe Executed "ip address change 2001:8b0:1111:1111:0:ffff:d9a9:14de/128 dev ppp0 valid_lft 5682 preferred_lft 2082", exit code true
+
+# am assuming these are just normal updates from remote dhcp6
+
+2025-03-27 01:11:19.179528428 rotuer wan.link.pppoe rcvd [LCP TermReq id=0x0]
+2025-03-27 01:11:19.179542189 rotuer wan.link.pppoe LCP terminated by peer
+2025-03-27 01:11:19.179545869 rotuer wan.link.pppoe Connect time 54273.0 minutes.
+2025-03-27 01:11:19.179550109 rotuer wan.link.pppoe Sent 3022278191 bytes, received 2202783935 bytes.
+2025-03-27 01:11:19.183056872 rotuer wan.link.pppoe sent [LCP TermAck id=0x0]
+# ppp died
+2025-03-27 01:11:19.183071352 rotuer dhcp6c.wan.link.pppoe odhcp6c[615]: carrier => 0 event on
+2025-03-27 01:11:19.183076072 rotuer dhcp6c.wan.link.pppoe odhcp6c[615]: Failed to send RS (Network unreachable)
+2025-03-27 01:11:19.183081592 rotuer dhcp6c.wan.link.pppoe odhcp6c[615]: Starting RELEASE transaction (timeout 4294967295s, max rc 5)
+2025-03-27 01:11:19.183086312 rotuer dhcp6c.wan.link.pppoe odhcp6c[615]: Send RELEASE message (elapsed 0ms, rc 0)
+2025-03-27 01:11:19.183091992 rotuer dhcp6c.wan.link.pppoe odhcp6c[615]: Failed to send RELEASE message to ff02::1:2 (Network unreachable)
+2025-03-27 01:11:19.183096392 rotuer dhcp6c.wan.link.pppoe odhcp6c[615]: (re)starting transaction on ppp0
+
+# dhcp6c noticed no ppp so tried to release address. it can't because
+#  ppp is down. how did it know it was time to say byebye?
+
+2025-03-27 01:11:19.198178337 rotuer int.link.a.192.168.8.1.dnsmasq dnsmasq-dhcp[631]: router advertisement on 2001:8b0:de3a:40de::, old prefix for int
+2025-03-27 01:11:19.199068668 rotuer dhcp6c.prefix.dhcp6c.wan.link.pppoe.int.link.a.192.168.8.1 Executed "ip address del 2001:8b0:de3a:40de::1/64 dev int", exit code true
+# our prefix delegation is no longer ours
+
+2025-03-27 01:11:19.199381632 rotuer dhcp6c.addr.dhcp6c.wan.link.pppoe.wan.link.pppoe ip: RTNETLINK answers: Address not available
+2025-03-27 01:11:19.199401552 rotuer dhcp6c.addr.dhcp6c.wan.link.pppoe.wan.link.pppoe /nix/store/anz85qjb2qw084f5xhpx4qndp260xr9i-lua-tty-aarch64-unknown-linux-musl/bin/lua: ...ch64-unknown-linux-musl-0.1/share/lua/5.3/anoia/init.lua:93: Error executing "ip address del 2001:8b0:1111:1111:0:ffff:d9a9:14de/128 dev ppp0" (exit)
+
+this is the ip6 address that ppp negotiated.  is this command failing because
+it was removed already?
+
+[....]
+2025-03-27 01:11:25.545493523 rotuer wan.link.pppoe Script /nix/store/9n2314z07z1g9dd3sqr0kndinjv0vma3-ip6-up started (pid 10346)
+2025-03-27 01:11:25.551376155 rotuer wan.link.pppoe Script /nix/store/9n2314z07z1g9dd3sqr0kndinjv0vma3-ip6-up finished (pid 10346), status = 0x0
+2025-03-27 01:11:25.552949055 rotuer wan.link.pppoe sh: write error: Broken pipe
+2025-03-27 01:11:25.553494501 rotuer wan.link.pppoe Script /nix/store/jkvnjhiqjahydmns33z5lni1hf9sl3x8-ip-up finished (pid 10345), status = 0x1
+2025-03-27 01:11:26.596566491 rotuer wlan0.link.hostapd wlan0: STA-OPMODE-SMPS-MODE-CHANGED 96:75:33:6c:6b:86 static
+2025-03-27 01:11:26.656620107 rotuer wlan0.link.hostapd wlan0: STA-OPMODE-SMPS-MODE-CHANGED 96:75:33:6c:6b:86 off
+2025-03-27 01:11:27.189590642 rotuer dhcp6c.wan.link.pppoe odhcp6c[615]: Failed to send RS (Network unreachable)
+
+it's supposed to send only one notification (each up-script only sends
+if an output the other has created is there).
+
+~~maybe we're not wiping the outputs when it terminates?~~ checked, we are.
+
+
+2025-03-27 01:11:27.279458704 rotuer int.link.a.192.168.8.1.dnsmasq dnsmasq-dhcp[631]: no address range available for DHCPv6 request via int
+2025-03-27 01:11:27.557594914 rotuer dhcp6c.wan.link.pppoe odhcp6c[615]: Failed to send SOLICIT message to ff02::1:2 (Network unreachable)
+2025-03-27 01:11:31.193583256 rotuer dhcp6c.wan.link.pppoe odhcp6c[615]: Failed to send RS (Network unreachable)
+
+Hypothesis
+
+1) when the remote end bounces ppp, s6 restarts the ppp process
+but this doesn't cause dependent services to notice, so odhcpc,
+which is bound to the interface, doesn't see that we now have a
+new interface but with the same name as the old one
+
+and/or
+
+2) there is a race between acquire-*.fnl starting and the
+prefix/address outputs being updated so that we miss the first
+value change.
+
+Tue Apr  1 21:29:03 BST 2025
+
+what to do with the web site?
+
+* we could add the "community" and "development" pages to the manual,
+but we probably don't want the blog entries to be in the liminix git
+repo because workflow
+
+* if we do that, the ->html conversion in the manual needs to have
+  better nav
+
+links we want on the homepage
+
+"I am new to Liminix and want to find if it's for me"
+ - introduction/tutorial (how do i use it)
+ - hardware list (is my device supported)
+   - which includes how to install the system
+
+"I am ready to run, and need a reference for stuff"
+[this is a merge of the existing config and admin sections]
+ - what is a module, what is a service
+ - how to do secrets
+ - list of service and module options
+ - using a running system: services and logs
+   (move controlled services stuff up a level, its not runtime)
+ - updating/changing the configuration
+   writable fs: use outputs.updater
+   readonly fs: use levitate
+
+"I want to stay in touch/find out what's new"
+ - blog
+ - mailing lists
+ - irc
+ - CoC
+
+"I want to contribute"
+Developer manual, plus
+ - mailing lists
+ - git repo
+   - how to send patches
+ - also transplant "module implementation" here
+ - porting
+   - how to bring up
+   - what we look for in a new device patch (kconfig style
+
+
+perhaps we can get rid of generic "installation" in the manual
+and have each method transcluded into the hardware device descriptions
+
+
+
+see also:
+1) "Continuous updates" is misleading as it gives the impression
+downstreams would be restarted if an upstream restarts. Not true.
+We should describe secrets subscriber here
+
+
+-----
+
+leaving us with these titles remaining
+
+* tutorial
+* hardware
+* reference (could just call it "manual")
+* development
+* blog
+
+and these which get moved
+
+* configuration/admin -> tutorial
+* Module options -> sublevel in Reference
+* outputs -> transcluded in hardware
+  (might also add as an appendix, so that porters can see all in one place)
+
+maybe also footer link for
+- CoC
+- privacy policy
+- ?
+
+source for all of these except blog and landing page is the doc/ folder
+
+landing page will have some big rectangles that essentially duplicate
+the menu items
+
+----
+
+to get there from here:
+
+1) we need to know the heading titles for a ToC to use as drop-down
+menus in the template, so will have to pass twice over the documents.
+Note that the same template is used for each doc so we can't expect the
+titles of the other docs to be provided by pandoc as variables
+
+(but maybe we could pass them in on the command line so as not to
+rewrite template.json?)
+
+note that we also need to use the template with the blog files,
+although for those we also need title and date frontmatter
+
+if the blog sources the template at build time to make pages, it's
+always going to be out of sync with the manual.
+
+would javascript be acceptable?
+
+should we just monorepo the two things together? we could run jekyll as
+part of the doc target, or even pandoc the markdown directly
+
+apparently myhtic.telent.net is running an rsync server?
+
+1) it needs doc/ removing from its path
+   path = "/var/www/blogs/www.liminix.org/_site/doc";
+   in hosts/myhtic.nix
+   (and moving to rmeote)
+
+2) make install should add doc to the path, for the manual,
+  and not for the blog entries which should be in yyyy/mm/dd folders
+
+Sun Apr  6 17:48:33 BST 2025
+
+This is all getting quite involved and I'm not convinced it's the
+simplest way forward
+
+- convert the manual to asciidoctor and make it have a sidebar
+  - use --embedded flag to splice in header/footer
+
+- the landing page can have big display-sized links to different
+manual sections and to the blog
+
+- get rid of the blog content that's not actually posts, merge it into
+  the manual
+
+- the blog also needs the header/footer spliced in
+
+site nav has three options: "home", "news", "manual"
+- unless we want to put the manual deeplinks from the homepage in
+ there as well
+- if we do that, need to indicate somehow that they're part of the
+ manual, not distinct from it
+
+do we need to move urls around? maybe not so much
+
+what to do about the "hardware" page?
+
+ - do we really expect the reader to scroll through every device
+ that's not theirs?
+ - there's going to be a lot of repeated text for similar devices
+ - "generic" instructions might go in the body of the manual with
+   devices as an appendix. However, you have to read the relevant
+   appendix section to make sense of the generic instructions anyway.
+   If only we had hypertext
+
+
+Mon Apr  7 23:49:40 BST 2025
+
+DOC TODO
+
+[done] * need to explain the mailing lists and IRC somewhere
+
+[done] * markup the devices section as an appendix.
+
+[done] * docs for outputs? maybe appendix ii
+
+[done] * move "module implementation" from admin to dev (maybe?)
+
+[done] * CI: move from website to Development
+
+[done] * move info on the Community page to Introduction
+
+[halfarsed done] * write doc for porting to new hw
+ - how to bring up
+ - what we look for in a new device patch (kconfig style etc)
+
+[done] * add rsyncy thing to rmeote
+
+* we still have serial connection guff in both installation and
+  development sections
+
+* convert all the embedded rst to adoc
+
+* remove pages that are not posts from jekyll blog
+
+* landing page
+
+* "Continuous updates" is misleading as it gives the impression
+downstreams would be restarted if an upstream restarts. Not true.
+We should describe secrets subscriber here
+
+* some basic css to make it not the same as (I assume) every single
+  other asciidoc site

ci.nix

@@ -35,44 +35,7 @@ let
           device = import (liminix + "/devices/qemu");
           liminix-config = vanilla;
         }).buildEnv;
-      doc =
-        let
-          json =
-            (import liminix {
-              inherit borderVmConf;
-              device = import (liminix + "/devices/qemu");
-              liminix-config =
-                { ... }:
-                {
-                  imports = [ ./modules/all-modules.nix ];
-                };
-            }).outputs.optionsJson;
-        in
-        pkgs.stdenv.mkDerivation {
-          name = "liminix-doc";
-          nativeBuildInputs = with pkgs; [
-            gnumake
-            sphinx
-            fennel
-            luaPackages.lyaml
-          ];
-          src = ./.;
-          buildPhase = ''
-            cat ${json} | fennel --correlate doc/parse-options.fnl > doc/modules-generated.inc.rst
-            cat ${json} | fennel --correlate doc/parse-options-outputs.fnl     > doc/outputs-generated.inc.rst
-            cp ${(import ./doc/hardware.nix)} doc/hardware.rst
-            make -C doc html
-          '';
-          installPhase = ''
-            mkdir -p $out/nix-support $out/share/doc/
-            cd doc
-            cp *-generated.inc.rst hardware.rst $out
-            ln -s ${json} $out/options.json
-            cp -a _build/html $out/share/doc/liminix
-            echo "file source-dist \"$out/share/doc/liminix\"" \
-                > $out/nix-support/hydra-build-products
-          '';
-        };
+      doc = pkgs.callPackage ./doc.nix { inherit liminix borderVmConf; } ;
     };
 in
 jobs

devices/families/qemu.nix

@@ -42,11 +42,11 @@
           in
           {
             wan = link.build {
-              devpath = "/devices/pci0000:00/0000:00:13.0/virtio0";
+              devpath = "/devices/pci0000:00/0000:00:12.0/virtio0";
               ifname = "wan";
             };
             lan = link.build {
-              devpath = "/devices/pci0000:00/0000:00:14.0/virtio1";
+              devpath = "/devices/pci0000:00/0000:00:13.0/virtio1";
               ifname = "lan";
             };
 

doc.nix

@@ -0,0 +1,55 @@
+{ stdenv,
+  lib,
+  liminix,
+  gnumake,
+  fennel,
+  pandoc,
+  luaPackages,
+  asciidoctor,
+  borderVmConf
+}:
+let
+  json =
+    (import liminix {
+      inherit borderVmConf;
+      device = import (liminix + "/devices/qemu");
+      liminix-config =
+        { ... }:
+        {
+          imports = [ ./modules/all-modules.nix ];
+        };
+    }).outputs.optionsJson;
+in
+stdenv.mkDerivation {
+  name = "liminix-doc";
+  nativeBuildInputs = [
+    gnumake
+    fennel
+    pandoc
+    asciidoctor
+    luaPackages.lyaml
+  ];
+
+  src = lib.sources.sourceFilesBySuffices
+    (lib.cleanSource ./. ) [
+      ".adoc"
+      ".nix" ".rst" "Makefile" ".svg"
+      ".fnl" ".py" ".css" ".html"
+      ".md" ".html.in"
+    ];
+
+  buildPhase = ''
+    cat ${json} | fennel --correlate doc/parse-options.fnl > doc/module-options-generated.inc.rst
+    cat ${json} | fennel --correlate doc/parse-options-outputs.fnl     > doc/outputs-generated.inc.rst
+    cp ${(import ./doc/hardware.nix)} doc/hardware.rst
+    make -C doc html
+  '';
+  installPhase = ''
+    mkdir -p $out/nix-support
+    cd doc
+    make install prefix=$out
+    ln -s ${json} $out/options.json
+    echo "file source-dist \"$out/share/doc/liminix\"" \
+        > $out/nix-support/hydra-build-products
+  '';
+}

doc/Makefile

@@ -1,24 +1,23 @@
-# Minimal makefile for Sphinx documentation
-#
+DOCS=\
+	admin \
+	configuration \
+	development \
+	index \
+	installation \
+	intro \
+	hardware \
+	module-options-generated.inc \
+	outputs-generated.inc \
+	tutorial
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
+%.adoc: %.rst
+	pandoc -f rst -t asciidoc $< | sed -E  -e 's/^(=*) /=\1 /g' > $@
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+hardware.adoc: hardware.nix
 
-hardware.rst: hardware.nix
-	@rm -f hardware.rst || true
-	@cp $$(nix-build hardware.nix) hardware.rst
+html: Makefile  $(patsubst %,%.adoc,$(DOCS))
+	asciidoctor  -D _build -d book index.adoc
 
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-html: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+install:
+	mkdir -p $(prefix)/share/doc/liminix
+	cp -a _build/* $(prefix)/share/doc/liminix

doc/admin.adoc

@@ -0,0 +1,352 @@
+== System Administration
+
+=== Services on a running system
+
+Liminix services are built on s6-rc, which is itself layered on s6.
+Services are defined at build time in your configuration (see
+<<_services>> for information) and can't be added
+to/changed at runtime, but to monitor events or diagnose problems you
+may need to inspect them on the running system. Here are some of the
+most commonly used s6,-rc commands:
+
+.Service management quick reference
+[width="100%",cols="55%,45%",options="header",]
+|===
+|What |How
+|List all running services |`+s6-rc -a list+`
+
+|List all services that are *not* running |`+s6-rc -da list+`
+
+|List services that `+wombat+` depends on
+|`+s6-rc-db dependencies wombat+`
+
+|... transitively |`+s6-rc-db all-dependencies wombat+`
+
+|List services that depend on service `+wombat+`
+|`+s6-rc-db -d dependencies wombat+`
+
+|... transitively |`+s6-rc-db -d all-dependencies wombat+`
+
+|Stop service `+wombat+` and everything depending on it
+|`+s6-rc -d change wombat+`
+
+|Start service `+wombat+` (but not any services depending on it)
+|`+s6-rc -u change wombat+`
+
+|Start service `+wombat+` and all* services depending on it
+|`+s6-rc-up-tree wombat+`
+|===
+
+`+s6-rc-up-tree+` brings up a service and all services that depend on
+it, except for any services that depend on a "controlled" service that
+is not currently running. Controlled services are not started at boot
+time but in response to external events (e.g. plugging in a particular
+piece of hardware) so you probably don't want to be starting them by
+hand if the conditions aren't there.
+
+A service may be *up* or *down* (there are no intermediate states like
+"started" or "stopping" or "dying" or "cogitating"). Some (but not all)
+services have "readiness" notifications: the dependents of a service
+with a readiness notification won't be started until the service signals
+(by writing to a nominated file descriptor) that it's prepared to start
+work. Most services defined by Liminix also have a `+timeout-up+`
+parameter, which means that if a service has readiness notifications and
+doesn't become ready in the allotted time (defaults 20 seconds) it will
+be terminated and its state set to *down*.
+
+If the process providing a service dies, it will be restarted
+automatically. Liminix does not automatically set it to *down*.
+
+(If the process providing a service dies without ever notifying
+readiness, Liminix will restart it as many times as it has to until the
+timeout period elapses, and then stop it and mark it down.)
+
+==== Controlled services
+
+*Controlled* services are those which are started/stopped on demand by a
+*controller* (another service) instead of being started at boot time.
+For example:
+
+* `+svc.uevent-rule.build+` creates a controlled service which is active
+when a particular hardware device (identified by uevent/sysfs directory)
+is present.
+* `+svc.round-robin.build+` creates a service controller that invokes
+two or more services in turn, running the next one when the process
+providing the previous one exits. We use this for failover from one
+network connection to a backup connection, for example.
+* `+svc.health-check.build+` creates a service controller that runs a
+controlled service and periodically tests whether it is healthy by
+running an external health check command or script. If the check command
+repeatedly fails, the controlled service is restarted.
++
+The Configuration section of the manual describes controlled services in
+more detail. Some operational considerations
+* `+round-robin+` detects a service status by looking at its `+outputs+`
+directory, so it won't work unless the service creates some outputs.
+This is considered a bug and will be fixed in a future release
+* `+health-check+` works for longruns but not for oneshots, as it
+internally relies on `+s6-svc+` to restart the process
+
+==== Logs
+
+Logs for all services are collated into `+/run/log/current+`. The log
+file is rotated when it reaches a threshold size, into another file in
+the same directory whose name contains a TAI64 timestamp.
+
+Each log line is prefixed with a TAI64 timestamp and the name of the
+service, if it is a longrun. If it is a oneshot, a timestamp and the
+name of some other service. To convert the timestamp into a
+human-readable format, use `+s6-tai64nlocal+`.
+
+[source,console]
+----
+# ls -l /run/log/
+-rw-r--r--    1         0 lock
+-rw-r--r--    1         0 state
+-rwxr--r--    1     98059 @4000000000025cb629c311ac.s
+-rwxr--r--    1     98061 @40000000000260f7309c7fb4.s
+-rwxr--r--    1     98041 @40000000000265233a6cc0b6.s
+-rwxr--r--    1     98019 @400000000002695d10c06929.s
+-rwxr--r--    1     98064 @4000000000026d84189559e0.s
+-rwxr--r--    1     98055 @40000000000271ce1e031d91.s
+-rwxr--r--    1     98054 @400000000002760229733626.s
+-rwxr--r--    1     98104 @4000000000027a2e3b6f4e12.s
+-rwxr--r--    1     98023 @4000000000027e6f0ed24a6c.s
+-rw-r--r--    1     42374 current
+
+# tail -2 /run/log/current
+@40000000000284f130747343 wan.link.pppoe Connect: ppp0 <--> /dev/pts/0
+@40000000000284f230acc669 wan.link.pppoe sent [LCP ConfReq id=0x1 <asyncmap 0x0> <magic 0x667a9594> <pcomp> <accomp>]
+# tail -2 /run/log/current  | s6-tai64nlocal
+1970-01-02 21:51:45.828598156 wan.link.pppoe sent [LCP ConfReq id=0x1 <asyncmap 0x0> <magic 0x667a9594> <pcomp> <accom
+p>]
+1970-01-02 21:51:48.832588765 wan.link.pppoe sent [LCP ConfReq id=0x1 <asyncmap 0x0> <magic 0x667a9594> <pcomp> <accom
+p>]
+----
+
+===== Log persistence
+
+Logs written to `+/run/log/+` will not survive a reboot or crash, as it
+is an ephemeral filesystem.
+
+On supported hardware you can enable logging to
+https://www.kernel.org/doc/Documentation/ABI/testing/pstore[pstore]
+which means the most recent log messages will be preserved on reboot.
+Set the config option `+logging.persistent.enable = true+` to log
+messages to `+/dev/pmsg0+` as well as to the regular log. This is a
+circular buffer, so when it fills up newer messages will overwrite the
+oldest messages.
+
+Logs found in pstore after a reboot will be moved at startup to
+`+/run/log/previous-boot+`
+
+=== Updating an installed system
+
+If your system has a writable root filesystem (JFFS2, btrfs etc
+-anything but squashfs), we have mechanisms for in-places updates
+analogous to `+nixos-rebuild+`, but the operation is a bit different
+because it expects to run on a build machine and then copy to the host
+device using `+ssh+`.
+
+To use this, build the `+outputs.updater+` target and then run the
+`+update.sh+` script it generates.
+
+[source,console]
+----
+nix-build -I liminix-config=./my-configuration.nix \
+   --arg device "import ./devices/mydevice" \
+   -A outputs.updater
+./result/bin/update.sh root@the-device 
+----
+
+The update script uses min-copy-closure to copy new or changed packages
+to the device, then (perhaps) reboots it. The reboot behaviour can be
+affected by flags:
+
+* [.title-ref]#--no-reboot# will cause it not to reboot at all, if you
+would rather do that yourself. Note that none of the newly-installed or
+updated services will be running until you do.
+* [.title-ref]#--fast# causes it tn not do a full reboot, but instead to
+restart only the services that have been changed. This will restart all
+of the services that have updated store paths (and anything that depends
+on them), but will not affect services that haven't changed.
+
+It doesn't delete old packages automatically: to do that run
+`+min-collect-garbage+`, which will delete any packages not in the
+current system closure. Note that Liminix does not have the NixOS
+concept of environments or generations, and there is no way back from
+this except for building the previous configuration again.
+
+==== Caveats
+
+* it needs there to be enough free space on the device for all the new
+packages in addition to all the packages already on it - which may be a
+problem if there is little flash storage or if a lot of things have
+changed (e.g. a new version of nixpkgs).
+* it may not be able to upgrade the kernel: this is device-dependent. If
+your device boots from a kernel image on a raw MTD partition or or UBI
+volume, update.sh is unable to alter the kernel partition. If your
+device boots from a kernel inside the filesystem (e.g. using
+bootloader.extlinux or bootloder.fit) then the kernel will be upgraded
+along with the userland
+
+==== Recovery/downgrades
+
+The `+update.sh+` script also creates a timestamped symlink on the
+device which points to the system configuration it installs. If you
+install a configuration that doesn't work, you can revert to any other
+installed configuration by
+
+[arabic]
+. booting to some kind of rescue or recovery system (which may be some
+vendor-provided rescue option, or your own recovery system perhaps based
+on `+examples/recovery.nix+`) and mounting your Liminix filesystem on
+/mnt
+. picking another previously-installed configuration that _link:[did]
+work, and switching back to it:
+
+[source,console]
+----
+# ls  -ld /mnt/*configuration
+lrwxrwxrwx    1        90 /mnt/20252102T182104.configuration -> nix/store/v1w0h4zw65ah4c2r0k7nyy125qrxhq78-system-configuration-aarch64-unknown-linux-musl
+lrwxrwxrwx    1        90 /mnt/20251802T181822.configuration -> nix/store/wqjl9s9xljl2wg8257292zghws9ssidk-system-configuration-aarch64-unknown-linux-musl
+# : 20251802T181822 is the working system, so reinstall it
+# /mnt/20251802T181822.configuration/bin/install /mnt
+# umount /mnt
+# reboot
+----
+
+This will install the previous configuration's activation binary into
+/bin, and copy its kernel and initramfs into /boot. Note that it depends
+on the previous system not having been garbage-collected.
+
+==== Adding packages
+
+If you simply wish to add a package without any change to services, you
+can call `+min-copy-closure+` directly to install any package in Nixpkgs
+or in the Liminix overlay
+
+[source,console]
+----
+nix-build -I liminix-config=./my-configuration.nix \
+ --arg device "import ./devices/mydevice" -A pkgs.tcpdump
+
+nix-shell -p min-copy-closure root@the-device result/
+----
+
+Note that this only copies the package and its dependencies to the
+device: it doesn't update any profile to add it to `+$PATH+`
+
+[reftext="Levitate"]
+[[levitate]]
+=== Levitate: Reinstalling on a running system
+
+Liminix is initially installed from a monolithic `+firmware.bin+` - and
+unless you're running a writable filesystem, the only way to update it
+is to build and install a whole new `+firmware.bin+`. However, you
+probably would prefer not to have to remove it from its installation
+site, unplug it from the network and stick serial cables in it all over
+again.
+
+It is not (generally) safe to install a new firmware onto the flash
+partitions that the active system is running on. To address this we have
+`+levitate+`, which a way for a running Liminix system to "soft restart"
+into a ramdisk running only a limited set of services, so that the main
+partitions can then be safely flashed.
+
+==== Configuration
+
+Levitate _needs to be configured when you create the initial system_ to
+specify which services/packages/etc to run in maintenance mode. Most
+likely you want to configure a network interface and an ssh for example
+so that you can login to reflash it.
+
+[source,nix]
+----
+defaultProfile.packages = with pkgs; [
+  ...
+  (levitate.override {
+    config  = {
+      services = {
+        inherit (config.services) dhcpc sshd watchdog;
+      };
+      defaultProfile.packages = [ mtdutils ];
+      users.root = config.users.root;
+    };
+  })
+];
+----
+
+==== Use
+
+Connect (with ssh, probably) to the running Liminix system that you wish
+to upgrade.
+
+[source,console]
+----
+bash$ ssh root@the-device
+----
+
+Run `+levitate+`. This takes a little while (perhaps a few tens of
+seconds) to execute, and copies all config required for maintenance mode
+to `+/run/maintenance+`.
+
+[source,console]
+----
+# levitate 
+----
+
+Reboot into maintenance mode. You will be logged out
+
+[source,console]
+----
+# reboot
+----
+
+Connect to the device again - note that the ssh host key will have
+changed.
+
+[source,console]
+----
+# ssh -o UserKnownHostsFile=/dev/null root@the-device
+----
+
+Check we're in maintenance mode
+
+[source,console]
+----
+# cat /etc/banner 
+
+LADIES AND GENTLEMEN WE ARE FLOATING IN SPACE
+
+Most services are disabled. The system is operating
+with a ram-based root filesystem, making it safe to
+overwrite the flash devices in order to perform
+upgrades and maintenance.
+
+Don't forget to reboot when you have finished.
+----
+
+Perform the upgrade, using flashcp. This is an example, your device will
+differ
+
+[source,console]
+----
+# cat /proc/mtd 
+dev:    size   erasesize  name
+mtd0: 00030000 00010000 "u-boot"
+mtd1: 00010000 00010000 "u-boot-env"
+mtd2: 00010000 00010000 "factory"
+mtd3: 00f80000 00010000 "firmware"
+mtd4: 00220000 00010000 "kernel"
+mtd5: 00d60000 00010000 "rootfs"
+mtd6: 00010000 00010000 "art"
+# flashcp -v firmware.bin mtd:firmware
+----
+
+All done
+
+[source,console]
+----
+# reboot
+----

doc/admin.rst

@@ -1,371 +0,0 @@
-System Administration
-#####################
-
-Services on a running system
-****************************
-
-Liminix services are built on s6-rc, which is itself layered on s6.
-Services are defined at build time in your configuration (see
-:ref:`configuration-services` for information) and can't be added
-to/changed at runtime, but to monitor
-events or diagnose problems you may need to inspect them on the
-running system. Here are some of the most commonly used s6,-rc
-commands:
-
-.. list-table:: Service management quick reference
-   :widths: 55 45
-   :header-rows: 1
-   
-   * - What
-     - How
-   * - List all running services
-     - ``s6-rc -a list``
-   * - List all services that are **not** running
-     - ``s6-rc -da list``
-   * - List services that ``wombat`` depends on
-     - ``s6-rc-db dependencies wombat``
-   * - ... transitively
-     - ``s6-rc-db all-dependencies wombat``
-   * - List services that depend on service ``wombat``
-     - ``s6-rc-db -d dependencies wombat``
-   * - ... transitively
-     - ``s6-rc-db -d all-dependencies wombat``
-   * - Stop service ``wombat`` and everything depending on it
-     - ``s6-rc -d change wombat``
-   * - Start service ``wombat`` (but not any services depending on it)
-     - ``s6-rc -u change wombat``
-   * - Start service ``wombat`` and all* services depending on it
-     - ``s6-rc-up-tree wombat``
-
-:command:`s6-rc-up-tree` brings up a service and all services that
-depend on it, except for any services that depend on a "controlled"
-service that is not currently running. Controlled services are not
-started at boot time but in response to external events (e.g. plugging
-in a particular piece of hardware) so you probably don't want to be
-starting them by hand if the conditions aren't there.
-
-A service may be **up** or **down** (there are no intermediate states
-like "started" or "stopping" or "dying" or "cogitating"). Some (but
-not all) services have "readiness" notifications: the dependents of a
-service with a readiness notification won't be started until the
-service signals (by writing to a nominated file descriptor) that it's
-prepared to start work. Most services defined by Liminix also have a
-``timeout-up`` parameter, which means that if a service has readiness
-notifications and doesn't become ready in the allotted time (defaults
-20 seconds) it will be terminated and its state set to **down**.
-
-If the process providing a service dies, it will be restarted
-automatically. Liminix does not automatically set it to **down**.
-
-(If the process providing a service dies without ever notifying
-readiness, Liminix will restart it as many times as it has to until the
-timeout period elapses, and then stop it and mark it down.)
-
-Controlled services
-===================
-
-**Controlled** services are those which are started/stopped on demand
-by a **controller** (another service) instead of being started at boot
-time.  For example:
-
-* ``svc.uevent-rule.build`` creates a controlled service which is
-  active when a particular hardware device (identified by uevent/sysfs
-  directory) is present.
-
-* ``svc.round-robin.build`` creates a service controller that
-  invokes two or more services in turn, running the next one when the
-  process providing the previous one exits. We use this for failover
-  from one network connection to a backup connection, for example.
-
-* ``svc.health-check.build`` creates a service controller that
-  runs a controlled service and periodically tests whether it is
-  healthy by running an external health check command or script. If the
-  check command repeatedly fails, the controlled service is
-  restarted.
-
-  The Configuration section of the manual describes controlled
-  services in more detail. Some operational considerations
-
-* ``round-robin`` detects a service status by looking at its
-  :file:`outputs` directory, so it won't work unless the service
-  creates some outputs. This is considered a bug and will be
-  fixed in a future release
-
-* ``health-check`` works for longruns but not for oneshots, as it
-  internally relies on ``s6-svc`` to restart the process
-
-Logs
-====
-
-Logs for all services are collated into :file:`/run/log/current`.
-The log file is rotated when it reaches a threshold size, into another
-file in the same directory whose name contains a TAI64 timestamp.
-
-Each log line is prefixed with a TAI64 timestamp and the name of the
-service, if it is a longrun. If it is a oneshot, a timestamp and the
-name of some other service. To convert the timestamp into a
-human-readable format, use :command:`s6-tai64nlocal`.
-
-.. code-block:: console
-
-  # ls -l /run/log/
-  -rw-r--r--    1         0 lock
-  -rw-r--r--    1         0 state
-  -rwxr--r--    1     98059 @4000000000025cb629c311ac.s
-  -rwxr--r--    1     98061 @40000000000260f7309c7fb4.s
-  -rwxr--r--    1     98041 @40000000000265233a6cc0b6.s
-  -rwxr--r--    1     98019 @400000000002695d10c06929.s
-  -rwxr--r--    1     98064 @4000000000026d84189559e0.s
-  -rwxr--r--    1     98055 @40000000000271ce1e031d91.s
-  -rwxr--r--    1     98054 @400000000002760229733626.s
-  -rwxr--r--    1     98104 @4000000000027a2e3b6f4e12.s
-  -rwxr--r--    1     98023 @4000000000027e6f0ed24a6c.s
-  -rw-r--r--    1     42374 current
-  
-  # tail -2 /run/log/current
-  @40000000000284f130747343 wan.link.pppoe Connect: ppp0 <--> /dev/pts/0
-  @40000000000284f230acc669 wan.link.pppoe sent [LCP ConfReq id=0x1 <asyncmap 0x0> <magic 0x667a9594> <pcomp> <accomp>]
-  # tail -2 /run/log/current  | s6-tai64nlocal
-  1970-01-02 21:51:45.828598156 wan.link.pppoe sent [LCP ConfReq id=0x1 <asyncmap 0x0> <magic 0x667a9594> <pcomp> <accom
-  p>]
-  1970-01-02 21:51:48.832588765 wan.link.pppoe sent [LCP ConfReq id=0x1 <asyncmap 0x0> <magic 0x667a9594> <pcomp> <accom
-  p>]
-
-Log persistence
----------------
-
-Logs written to :file:`/run/log/` will not survive a reboot or crash,
-as it is an ephemeral filesystem.
-
-On supported hardware you can enable logging to `pstore
-<https://www.kernel.org/doc/Documentation/ABI/testing/pstore>`_ which
-means the most recent log messages will be preserved on reboot.  Set
-the config option ``logging.persistent.enable = true`` to log messages
-to :file:`/dev/pmsg0` as well as to the regular log. This is a
-circular buffer, so when it fills up newer messages will overwrite the
-oldest messages.
-
-Logs found in pstore after a reboot will be moved at startup to
-:file:`/run/log/previous-boot`
-
-
-
-Updating an installed system
-****************************
-
-If your system has a writable root filesystem (JFFS2, btrfs etc -
-anything but squashfs), we have mechanisms for in-places updates
-analogous to :command:`nixos-rebuild`, but the operation is a bit
-different because it expects to run on a build machine and then copy
-to the host device using :command:`ssh`.
-
-To use this, build the ``outputs.updater``
-target and then run the :command:`update.sh` script it generates.
-
-.. code-block:: console
-
-    nix-build -I liminix-config=./my-configuration.nix \
-       --arg device "import ./devices/mydevice" \
-       -A outputs.updater
-    ./result/bin/update.sh root@the-device 
-
-The update script uses min-copy-closure to copy new or changed
-packages to the device, then (perhaps) reboots it. The reboot
-behaviour can be affected by flags:
-
-* `--no-reboot` will cause it not to reboot at all, if you would
-  rather do that yourself. Note that none of the newly-installed or
-  updated services will be running until you do.
-
-* `--fast` causes it tn not do a full reboot, but instead to restart
-  only the services that have been changed. This will restart all of
-  the services that have updated store paths (and anything that
-  depends on them), but will not affect services that haven't changed.
-
-It doesn't delete old packages automatically: to do that run
-:command:`min-collect-garbage`, which will delete any packages not in
-the current system closure. Note that Liminix does not have the NixOS
-concept of environments or generations, and there is no way back from
-this except for building the previous configuration again.
-
-Caveats
--------
-
-* it needs there to be enough free space on the device for all the new
-  packages in addition to all the packages already on it - which may
-  be a problem if there is little flash storage or if a lot of things
-  have changed (e.g. a new version of nixpkgs).
-
-* it may not be able to upgrade the kernel: this is device-dependent.
-  If your device boots from a kernel image on a raw MTD partition or
-  or UBI volume, update.sh is unable to alter the kernel partition.
-  If your device boots from a kernel inside the filesystem (e.g. using
-  bootloader.extlinux or bootloder.fit) then the kernel will be
-  upgraded along with the userland
-
-
-Recovery/downgrades
--------------------
-
-The :command:`update.sh` script also creates a timestamped symlink on
-the device which points to the system configuration it installs. If
-you install a configuration that doesn't work, you can revert to any
-other installed configuration by
-
-1) booting to some kind of rescue or recovery system (which may be
-   some vendor-provided rescue option, or your own recovery system
-   perhaps based on :file:`examples/recovery.nix`) and mounting
-   your Liminix filesystem on /mnt
-
-2) picking another previously-installed configuration that _did_ work,
-   and switching back to it:
-
-.. code-block:: console
-   
-    # ls  -ld /mnt/*configuration
-    lrwxrwxrwx    1        90 /mnt/20252102T182104.configuration -> nix/store/v1w0h4zw65ah4c2r0k7nyy125qrxhq78-system-configuration-aarch64-unknown-linux-musl
-    lrwxrwxrwx    1        90 /mnt/20251802T181822.configuration -> nix/store/wqjl9s9xljl2wg8257292zghws9ssidk-system-configuration-aarch64-unknown-linux-musl
-    # : 20251802T181822 is the working system, so reinstall it
-    # /mnt/20251802T181822.configuration/bin/install /mnt
-    # umount /mnt
-    # reboot
-    
-This will install the previous configuration's activation binary into
-/bin, and copy its kernel and initramfs into /boot. Note that it
-depends on the previous system not having been garbage-collected.
-
-
-
-
-.. _levitate:  
-
-Adding packages
-===============
-
-If you simply wish to add a package without any change to services,
-you can call :command:`min-copy-closure` directly to install
-any package in Nixpkgs or in the Liminix overlay
-
-.. code-block:: console
-
-    nix-build -I liminix-config=./my-configuration.nix \
-     --arg device "import ./devices/mydevice" -A pkgs.tcpdump
-
-    nix-shell -p min-copy-closure root@the-device result/
-
-Note that this only copies the package and its dependencies to the
-device: it doesn't update any profile to add it to ``$PATH``
-
-
-.. _rebuilding the system:
-
-Reinstalling on a running system
-********************************
-
-Liminix is initially installed from a monolithic
-:file:`firmware.bin` - and unless you're running a writable
-filesystem, the only way to update it is to build and install a whole
-new :file:`firmware.bin`.  However, you probably would prefer not to
-have to remove it from its installation site, unplug it from the
-network and stick serial cables in it all over again.
-
-It is not (generally) safe to install a new firmware onto the flash
-partitions that the active system is running on. To address this we
-have :command:`levitate`, which a way for a running Liminix system to
-"soft restart" into a ramdisk running only a limited set of services,
-so that the main partitions can then be safely flashed.
-
-
-
-Configuration
-=============
-
-Levitate *needs to be configured when you create the initial system*
-to specify which services/packages/etc to run in maintenance
-mode. Most likely you want to configure a network interface and an ssh
-for example so that you can login to reflash it.
-
-.. code-block:: nix
-
-  defaultProfile.packages = with pkgs; [
-    ...
-    (levitate.override {
-      config  = {
-        services = {
-          inherit (config.services) dhcpc sshd watchdog;
-        };
-        defaultProfile.packages = [ mtdutils ];
-        users.root = config.users.root;
-      };
-    })
-  ];
-  		
-
-
-Use
-===
-
-Connect (with ssh, probably) to the running Liminix system that you
-wish to upgrade.
-
-.. code-block:: console
-
-  bash$ ssh root@the-device
-  
-Run :command:`levitate`. This takes a little while (perhaps a few
-tens of seconds) to execute, and copies all config required for
-maintenance mode to :file:`/run/maintenance`.
-  
-.. code-block:: console
-  
-  # levitate 
-  
-Reboot into maintenance mode. You will be logged out
-  
-.. code-block:: console
-
-  # reboot
-  
-Connect to the device again - note that the ssh host key will have changed.
-  
-.. code-block:: console
-
-  # ssh -o UserKnownHostsFile=/dev/null root@the-device
-  
-Check we're in maintenance mode
-  
-.. code-block:: console
-
-  # cat /etc/banner 
-  
-  LADIES AND GENTLEMEN WE ARE FLOATING IN SPACE
-  
-  Most services are disabled. The system is operating
-  with a ram-based root filesystem, making it safe to
-  overwrite the flash devices in order to perform
-  upgrades and maintenance.
-  
-  Don't forget to reboot when you have finished.
-  
-Perform the upgrade, using flashcp. This is an example,
-your device will differ
-   
-.. code-block:: console
-
-  # cat /proc/mtd 
-  dev:    size   erasesize  name
-  mtd0: 00030000 00010000 "u-boot"
-  mtd1: 00010000 00010000 "u-boot-env"
-  mtd2: 00010000 00010000 "factory"
-  mtd3: 00f80000 00010000 "firmware"
-  mtd4: 00220000 00010000 "kernel"
-  mtd5: 00d60000 00010000 "rootfs"
-  mtd6: 00010000 00010000 "art"
-  # flashcp -v firmware.bin mtd:firmware
-
-All done
-  
-.. code-block:: console
-
-  # reboot
-

doc/code-of-conduct.adoc

@@ -0,0 +1,106 @@
+= Code of Conduct
+
+NOTE: As of Feb 2023, "`RESPONSE TEAM`" and "`LEADERSHIP TEAM`" in the text
+that follows both refer to me, Daniel Barlow, as the project leader.
+
+Liminix is dedicated to providing a harassment-free experience for
+everyone. We do not tolerate harassment of participants in any form.
+
+This code of conduct applies to all Liminix spaces, including the IRC
+channel, mailing lists, and other forums, both online and off. Anyone
+who violates this code of conduct may be sanctioned or expelled from
+these spaces at the discretion of the RESPONSE TEAM.
+
+Some Liminix spaces may have additional rules in place, which will be
+made clearly available to participants. Participants are responsible for
+knowing and abiding by these rules.
+
+Harassment includes:
+
+* Offensive comments related to gender, gender identity and expression,
+sexual orientation, disability, mental illness, neuro(a)typicality,
+physical appearance, body size, age, race, or religion.
+* Unwelcome comments regarding a person’s lifestyle choices and
+practices, including those related to food, health, parenting, drugs,
+and employment.
+* Deliberate misgendering or use of '`dead`' or rejected names.
+* Gratuitous or off-topic sexual images or behaviour in spaces where
+they’re not appropriate.
+* Physical contact and simulated physical contact (eg, textual
+descriptions like "`__hug__`" or "`__backrub__`") without consent or
+after a request to stop.
+* Threats of violence.
+* Incitement of violence towards any individual, including encouraging a
+person to commit suicide or to engage in self-harm.
+* Deliberate intimidation.
+* Stalking or following.
+* Harassing photography or recording, including logging online activity
+for harassment purposes.
+* Sustained disruption of discussion.
+* Unwelcome sexual attention.
+* Pattern of inappropriate social contact, such as requesting/assuming
+inappropriate levels of intimacy with others
+* Continued one-on-one communication after requests to cease.
+* Deliberate "`outing`" of any aspect of a person’s identity without
+their consent except as necessary to protect vulnerable people from
+intentional abuse.
+* Publication of non-harassing private communication.
+
+Liminix prioritizes marginalized people’s safety over privileged
+people’s comfort. RESPONSE TEAM reserves the right not to act on
+complaints regarding:
+
+* '`Reverse`' -isms, including '`reverse racism,`' '`reverse sexism,`'
+and '`cisphobia`'
+* Reasonable communication of boundaries, such as "`leave me alone,`"
+"`go away,`" or "`I’m not discussing this with you.`"
+* Communicating in a '`tone`' you don’t find congenial
+* Criticizing racist, sexist, cissexist, or otherwise oppressive
+behavior or assumptions
+
+== Reporting
+
+If you are being harassed by a member of Liminix, notice that someone
+else is being harassed, or have any other concerns, please contact the
+RESPONSE TEAM at [email address or other contact point]. If the person
+who is harassing you is on the team, they will recuse themselves from
+handling your incident. We will respond as promptly as we can.
+
+This code of conduct applies to Liminix spaces, but if you are being
+harassed by a member of Liminix outside our spaces, we still want to
+know about it. We will take all good-faith reports of harassment by
+Liminix members, especially LEADERSHIP TEAM, seriously. This includes
+harassment outside our spaces and harassment that took place at any
+point in time. The abuse team reserves the right to exclude people from
+Liminix based on their past behavior, including behavior outside Liminix
+spaces and behavior towards people who are not in Liminix.
+
+In order to protect volunteers from abuse and burnout, we reserve the
+right to reject any report we believe to have been made in bad faith.
+Reports intended to silence legitimate criticism may be deleted without
+response.
+
+We will respect confidentiality requests for the purpose of protecting
+victims of abuse. At our discretion, we may publicly name a person about
+whom we’ve received harassment complaints, or privately warn third
+parties about them, if we believe that doing so will increase the safety
+of Liminix members or the general public. We will not name harassment
+victims without their affirmative consent.
+
+== Consequences
+
+Participants asked to stop any harassing behavior are expected to comply
+immediately.
+
+If a participant engages in harassing behavior, RESPONSE TEAM may take
+any action they deem appropriate, up to and including expulsion from all
+Liminix spaces and identification of the participant as a harasser to
+other Liminix members or the general public.
+
+== License and attribution
+
+The policy is based on the Geek Feminism
+https://geekfeminism.fandom.com/wiki/Community_anti-harassment/Policy[Community
+anti-harassment/Policy] and is the work of Annalee Flower Horne with
+assistance from Valerie Aurora, Alex Skud Bayley, Tim Chevalier, and
+Mary Gardiner.

doc/configuration.adoc

@@ -0,0 +1,223 @@
+== Configuration
+
+There are many things you can specify in a configuration, but most
+commonly you 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 `+modules/ntp+` to your `+imports+` list, then you
+create a service by calling `+config.system.service.ntp.build { .... }+`
+with the appropriate service-dependent configuration parameters.
+
+[source,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. (For the background to this, please
+refer to the `+architecture decision record <adr/module-system>+`)
+
+[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.
+====
+
+[[configuration-services]]
+=== Services
+
+In Liminix a service is any kind of long-running task or process on the
+system, that is managed (started, stopped, and monitored) by a service
+supervisor. A typical SOHO router might have services to
+
+* answer DHCP and DNS requests from the LAN
+* provide a wireless access point
+* connect using PPPoE or L2TP to an upstream network
+* start/stop the firewall
+* enable/disable IP packet forwarding
+* mount filesystems
+
+(Some of these might not be considered services using other definitions
+of the term: for example, this L2TP process would be a "client" in the
+client/server classification; and enabling packet forwarding doesn't
+require any long-lived process - just a setting to be toggled. However,
+there is value in being able to use the same abstractions for all the
+things to manage them and specify their dependency relationships - so in
+Liminix "everything is a service")
+
+The service supervision system enables service health monitoring,
+restart of unhealthy services, and failover to "backup" services when a
+primary service fails or its dependencies are unavailable. The intention
+is that you have a framework in which you can specify policy
+requirements like "ethernet wan dhcp-client should be restarted if it
+crashes, but if it can't start because the hardware link is down, then
+4G ppp service should be started instead".
+
+Any attribute in [.title-ref]#config.services# will become part of the
+default set of services that s6-rc will try to bring up. Services are
+usually started at boot time, but *controlled services* are those that
+are required only in particular contexts. For example, a service to
+mount a USB backup drive should run only when the drive is attached to
+the system. Liminix currently implements three kinds of controlled
+service:
+
+* "uevent-rule" service controllers use sysfs/uevent to identify when
+particular hardware devices are present, and start/stop a controlled
+service appropriately.
+* the "round-robin" service controller is used for service failover: it
+allows you to specify a list of services and runs each of them in turn
+until it exits, then runs the next.
+* the "health-check" service wraps another service, and runs a "health
+check" command at regular intervals. When the health check fails,
+indicating that the wrapped service is not working, it is terminated and
+allowed to restart.
+
+=== Runtime secrets (external vault)
+
+Secrets (such as wifi passphrases, PPP username/password, SSH keys, etc)
+that you provide as literal values in `+configuration.nix+` are
+processed into into config files and scripts at build time, and
+eventually end up in various files in the (world-readable)
+`+/nix/store+` before being baked into a flashable image. To change a
+secret - whether due to a compromise, or just as part of to a routine
+key rotation - you need to rebuild the configuration and potentially
+reflash the affected devices.
+
+To avoid this, you may instead use a "secrets service", which is a
+mechanism for your device to fetch secrets from a source external to the
+Nix store, and create at runtime the configuration files and scripts
+that start the services which require them.
+
+Not every possible parameter to every possible service is configurable
+using a secrets service. Parameters which can be configured this way are
+those with the type `+liminix.lib.types.replacable+`. At the time this
+document was written, these include:
+
+* ppp (pppoe and l2tp): `+username+`, `+password+`
+* ssh: `+authorizedKeys+`
+* hostapd: all parameters (most likely to be useful for
+`+wpa_passphrase+`)
+
+To use a runtime secret for any of these parameters:
+
+* create a secrets service to specify the source of truth for secrets
+* use the `+outputRef+` function in the service parameter to specify the
+secrets service and path
+
+For example, given you had an HTTPS server hosting a JSON file with the
+structure
+
+[source,json]
+----
+"ssh": {
+  "authorizedKeys": {
+"root": [ "ssh-rsa ....",  "ssh-rsa ....", ... ]
+"guest": [ "ssh-rsa ....",  "ssh-rsa ....", ... ]
+  }
+}
+----
+
+you could use a `+configuration.nix+` fragment something like this to
+make those keys visible to ssh:
+
+[source,nix]
+----
+services.secrets = svc.secrets.outboard.build {
+  name = "secret-service";
+  url = "http://10.0.0.1/secrets.json";
+  username = "secrets";
+  password = "liminix";
+  interval = 30; # minutes
+  dependencies = [ config.services.lan ];
+};
+services.sshd = svc.ssh.build {
+  authorizedKeys = outputRef config.services.secrets "ssh/authorizedKeys";
+};
+----
+
+There are presently two implementations of a secrets service:
+
+===== Outboard secrets (HTTPS)
+
+This service expects a URL to a JSON file containing all the secrets.
+
+You may specify a username and password along with the URL, which are
+used if the file is password-protected (HTTP Basic authentication). Note
+that this is not a protection against a malicious local user: the
+username and password are normal build-time parameters so will be
+readable in the Nix store. This is a mitigation against the URL being
+accidentally discovered due to e.g. a log file or error message on the
+server leaking.
+
+===== Tang secrets (encrypted local file)
+
+Aternatively, secrets may be stored locally on the device, in a file
+that has been encrypted using https://github.com/latchset/tang[Tang].
+
+____
+Tang is a server for binding data to network presence.
+
+This sounds fancy, but the concept is simple. You have some data, but
+you only want it to be available when the system containing the data is
+on a certain, usually secure, network.
+____
+
+[source,nix]
+----
+services.secrets = svc.secrets.tang.build {
+  name = "secret-service";
+  path = "/run/mnt/usbstick/secrets.json.jwe";
+  interval = 30; # minutes
+  dependencies = [ config.services.mount-usbstick ];
+};
+----
+
+The encryption uses the same scheme/algorithm as
+https://github.com/latchset/clevis[Clevis] : you may use the
+https://github.com/latchset/clevis?tab=readme-ov-file#pin-tang[Clevis
+instructions] to encrypt the file on another host and then copy it to
+your Liminix device, or you can use `+tangc encrypt+` to encrypt
+directly on the device. (That latter approach may pose a chicken/egg
+problem if the device needs secrets to boot up and run the services you
+are relying on in order to login).
+

doc/configuration.rst

@@ -1,482 +0,0 @@
-.. _configuration:
-
-Configuration
-#############
-
-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.
-(For the background to this, please refer to the :doc:`architecture decision record <adr/module-system>`)
-
-.. 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.
-
-.. _configuration-services:
-
-Services
-********
-
-In Liminix a service is any kind of long-running task or process on
-the system, that is managed (started, stopped, and monitored) by a
-service supervisor.  A typical SOHO router might have services to
-
-* answer DHCP and DNS requests from the LAN
-* provide a wireless access point
-* connect using PPPoE or L2TP to an upstream network
-* start/stop the firewall
-* enable/disable IP packet forwarding
-* mount filesystems
-
-(Some of these might not be considered services using other
-definitions of the term: for example, this L2TP process would be a
-"client" in the client/server classification; and enabling packet
-forwarding doesn't require any long-lived process - just a setting to
-be toggled.  However, there is value in being able to use the same
-abstractions for all the things to manage them and specify their
-dependency relationships - so in Liminix "everything is a service")
-
-The service supervision system enables service health monitoring,
-restart of unhealthy services, and failover to "backup" services when
-a primary service fails or its dependencies are unavailable. The
-intention is that you have a framework in which you can specify policy
-requirements like "ethernet wan dhcp-client should be restarted if it
-crashes, but if it can't start because the hardware link is down, then
-4G ppp service should be started instead".
-
-Any attribute in `config.services` will become part of the default set
-of services that s6-rc will try to bring up.  Services are usually
-started at boot time, but **controlled services** are those that are
-required only in particular contexts.  For example, a service to mount
-a USB backup drive should run only when the drive is attached to the
-system. Liminix currently implements three kinds of controlled service:
-
-* "uevent-rule" service controllers use sysfs/uevent to identify when
-  particular hardware devices are present, and start/stop a controlled
-  service appropriately.
-
-* the "round-robin" service controller is used for service failover:
-  it allows you to specify a list of services and runs each of them
-  in turn until it exits, then runs the next.
-
-* the "health-check" service wraps another service, and runs a "health
-  check" command at regular intervals. When the health check fails,
-  indicating that the wrapped service is not working, it is terminated
-  and allowed to restart.
-
-Runtime secrets (external vault)
-================================
-
-Secrets (such as wifi passphrases, PPP username/password, SSH keys,
-etc) that you provide as literal values in :file:`configuration.nix`
-are processed into into config files and scripts at build time, and
-eventually end up in various files in the (world-readable)
-:file:`/nix/store` before being baked into a flashable image. To
-change a secret - whether due to a compromise, or just as part of to a
-routine key rotation - you need to rebuild the configuration and
-potentially reflash the affected devices.
-
-To avoid this, you may instead use a "secrets service", which is a
-mechanism for your device to fetch secrets from a source external to
-the Nix store, and create at runtime the configuration files and
-scripts that start the services which require them.
-
-Not every possible parameter to every possible service is configurable
-using a secrets service. Parameters which can be configured this way
-are those with the type ``liminix.lib.types.replacable``. At the time
-this document was written, these include:
-
-* ppp (pppoe and l2tp): ``username``, ``password``
-* ssh: ``authorizedKeys``
-* hostapd: all parameters (most likely to be useful for ``wpa_passphrase``)
-
-To use a runtime secret for any of these parameters:
-
-* create a secrets service to specify the source of truth for secrets
-* use the :code:`outputRef` function in the service parameter to specify the secrets service and path
-
-For example, given you had an HTTPS server hosting a JSON file with the structure
-
-.. code-block:: json
-
-    "ssh": {
-      "authorizedKeys": {
-	"root": [ "ssh-rsa ....",  "ssh-rsa ....", ... ]
-	"guest": [ "ssh-rsa ....",  "ssh-rsa ....", ... ]
-      }
-    }
- 
-you could use a :file:`configuration.nix` fragment something like this
-to make those keys visible to ssh:
-  
-.. code-block:: nix  
-
-    services.secrets = svc.secrets.outboard.build {
-      name = "secret-service";
-      url = "http://10.0.0.1/secrets.json";
-      username = "secrets";
-      password = "liminix";
-      interval = 30; # minutes
-      dependencies = [ config.services.lan ];
-    };
-    services.sshd = svc.ssh.build {
-      authorizedKeys = outputRef config.services.secrets "ssh/authorizedKeys";
-    };
-
-
-    
-There are presently two implementations of a secrets service:
-
-Outboard secrets (HTTPS)
-------------------------
-
-This service expects a URL to a JSON file containing all the secrets.
-
-You may specify a username and password along with the URL, which are
-used if the file is password-protected (HTTP Basic
-authentication). Note that this is not a protection against a
-malicious local user: the username and password are normal build-time
-parameters so will be readable in the Nix store.  This is a mitigation
-against the URL being accidentally discovered due to e.g. a log file
-or error message on the server leaking.
-
-
-Tang secrets (encrypted local file)
------------------------------------
-
-Aternatively, secrets may be stored locally on the device, in a file
-that has been encrypted using `Tang <https://github.com/latchset/tang>`_.
-
-    Tang is a server for binding data to network presence.
-
-    This sounds fancy, but the concept is simple. You have some data, but you only want it to be available when the system containing the data is on a certain, usually secure, network. 
-
-
-.. code-block:: nix
-
-    services.secrets = svc.secrets.tang.build {
-      name = "secret-service";
-      path = "/run/mnt/usbstick/secrets.json.jwe";
-      interval = 30; # minutes
-      dependencies = [ config.services.mount-usbstick ];
-    };
-
-The encryption uses the
-same scheme/algorithm as `Clevis <https://github.com/latchset/clevis>`_ : you may use the `Clevis instructions <https://github.com/latchset/clevis?tab=readme-ov-file#pin-tang>`_ to
-encrypt the file on another host and then copy it to your Liminix
-device, or you can use :command:`tangc encrypt` to encrypt directly on
-the device.  (That latter approach may pose a chicken/egg problem if
-the device needs secrets to boot up and run the services you are
-relying on in order to login).
- 
-
-Writing services
-================
-
-For the most part, for common use cases, hopefully the services you
-need will be defined by modules and you will only have to pass the
-right parameters to ``build``.
-
-Should you need to create a custom service of your own devising, use
-the `oneshot` or `longrun` functions:
-
-* a "longrun" service is the "normal" service concept: it has a
-  ``run`` action which describes the process to start, and it watches
-  that process to restart it if it exits. The process should not
-  attempt to daemonize or "background" itself, otherwise s6-rc will think
-  it died. Whatever it prints to standard output/standard error
-  will be logged.
-
-.. code-block:: nix
-
-    config.services.cowsayd = pkgs.liminix.services.longrun {
-      name = "cowsayd";
-      run = "${pkgs.cowsayd}/bin/cowsayd --port 3001 --breed hereford";
-      # don't start this until the lan interface is ready
-      dependencies = [ config.services.lan ];
-    }
-
-
-* a "oneshot" service doesn't have a process attached. It consists of
-  ``up`` and ``down`` actions which are bits of shell script that
-  are run at the appropriate points in the service lifecycle
-
-.. code-block:: nix
-
-    config.services.greenled = pkgs.liminix.services.oneshot {
-      name = "greenled";
-      up = ''
-	echo 17 > /sys/class/gpio/export
-	echo out > /sys/class/gpio/gpio17/direction
-	echo 0   > /sys/class/gpio/gpio17/value
-      '';
-      down = ''
-	echo 0   > /sys/class/gpio/gpio17/value
-      '';
-    }
-
-Services may have dependencies: as you see above in the ``cowsayd``
-example, it depends on some service called ``config.services.lan``,
-meaning that it won't be started until that other service is up.
-
-Service outputs
-===============
-
-Outputs are a mechanism by which a service can provide data which may
-be required by other services. For example:
-
-* the DHCP client service can expect to receive nameserver address
-  information as one of the fields in the response from the DHCP
-  server: we provide that as an output which a dependent service for a
-  stub name resolver can use to configure its upstream servers.
-
-* a service that creates a new network interface (e.g. ppp) will
-  provide the name of the interface (:code:`ppp0`, or :code:`ppp1` or
-  :code:`ppp7`) as an output so that a dependent service can reference
-  it to set up a route, or to configure firewall rules.
-
-A service :code:`myservice` should write its outputs as files in
-:file:`/run/services/outputs/myservice`: you can look around this
-directory on a running Liminix system to see how it's used currently.
-Usually we use the :code:`in_outputs` shell function in the
-:command:`up` or :command:`run` attributes of the service:
-
-.. code-block:: shell
-		
-    (in_outputs ${name}
-     for i in lease mask ip router siaddr dns serverid subnet opt53 interface ; do
-       (printenv $i || true) > $i
-     done)
- 
-The outputs are just files, so technically you can read them using
-anything that can read a file. Liminix has two "preferred"
-mechanisms, though:
-
-One-off lookups
----------------
-
-In any context that ends up being evaluated by the shell, use 
-:code:`output` to print the value of an output
-
-.. code-block:: nix
-		
-    services.defaultroute4 = svc.network.route.build {
-      via = "$(output ${services.wan} address)";
-      target = "default";
-      dependencies = [ services.wan ];
-    };	  
-
-    
-Continuous updates
-------------------
-
-The downside of using shell functions in downstream service startup
-scripts is that they only run when the service starts up: if a service
-output *changes*, the downstream service would have to be restarted to
-notice the change. Sometimes this is OK but other times the downstream
-has no other need to restart, if it can only get its new data.
-
-For this case, there is the :code:`anoia.svc` Fennel library, which
-allows you to write a simple loop which is iterated over whenever a
-service's outputs change. This code is from
-:file:`modules/dhcp6c/acquire-wan-address.fnl`
-
-.. code-block:: fennel
-
-    (fn update-addresses [wan-device addresses new-addresses exec]
-      ;; run some appropriate "ip address [add|remove]" commands
-      )
-
-    (fn run []
-      (let [[state-directory wan-device] arg
-	    dir (svc.open state-directory)]
-	(accumulate [addresses []
-		     v (dir:events)]
-	  (update-addresses wan-device addresses
-	                    (or (v:output "address") []) system))))		
-
-The :code:`output` method seen here accepts a filename (relative
-to the service's output directory), or a directory name. It 
-returns the first line of that file, or for directories it
-returns a table (Lua's key/value datastructure, similar to
-a hash/dictionary) of the outputs in that directory.
-	  
-    
-Output design considerations
-----------------------------
-
-For preference, outputs should be short and simple, and not require
-downstream services to do complicated parsing in order to use them.
-Shell commands in Liminix are run using the Busybox shell which
-doesn't have the niceties of an advanced shell like Bash let alone
-those of a real programming language.
-
-Note also that the Lua :code:`svc` library only reads the first line
-of each output.
-
-
-Module implementation
-*********************
-
-Modules in Liminix conventionally live in
-:file:`modules/somename/default.nix`. If you want or need to
-write your own, you may wish to refer to the
-examples there in conjunction with reading this section.
-
-A module is a function that accepts ``{lib, pkgs, config, ... }`` and
-returns an attrset with keys ``imports, options config``.
-
-* ``imports`` is a list of paths to the other modules required by this one
-
-* ``options`` is a nested set of option declarations
-
-* ``config`` is a nested set of option definitions
-
-The NixOS manual section `Writing NixOS Modules
-<https://nixos.org/manual/nixos/stable/#sec-writing-modules>`_ is a
-quite comprehensive reference to writing NixOS modules, which is also
-mostly applicable to Liminix except that it doesn't cover
-service templates.
-
-Service templates
-=================
-
-To expose a service template in a module, it needs the following:
-
-* an option declaration for ``system.service.myservicename`` with the
-  type of ``liminix.lib.types.serviceDefn``
-
-.. code-block:: nix
-
-    options = {
-      system.service.cowsay = mkOption {
-	type = liminix.lib.types.serviceDefn;
-      };
-    };
-
-* an option definition for the same key, which specifies where to
-  import the service template from (often :file:`./service.nix`)
-  and the types of its parameters.
-
-.. code-block:: nix
-
-    config.system.service.cowsay = config.system.callService ./service.nix {
-      address = mkOption {
-	type = types.str;
-	default = "0.0.0.0";
-	description = "Listen on specified address";
-	example = "127.0.0.1";
-      };
-      port = mkOption {
-	type = types.port;
-	default = 22;
-	description = "Listen on specified TCP port";
-      };
-      breed = mkOption {
-	type = types.str;
-	default = "British Friesian"
-	description = "Breed of the cow";
-      };
-    };
-
-Then you need to provide the service template itself, probably in
-:file:`./service.nix`:
-
-.. code-block:: nix
-
-    {
-      # any nixpkgs package can be named here
-      liminix
-    , cowsayd
-    , serviceFns
-    , lib
-    }:
-    # these are the parameters declared in the callService invocation
-    { address, port, breed} :
-    let
-      inherit (liminix.services) longrun;
-      inherit (lib.strings) escapeShellArg;
-    in longrun {
-      name = "cowsayd";
-      run = "${cowsayd}/bin/cowsayd --address ${address} --port ${builtins.toString port} --breed ${escapeShellArg breed}";
-    }
-
-.. tip::
-
-   Not relevant to module-based services specifically, but a common
-   gotcha when specifiying services is forgetting to transform "rich"
-   parameter values into text when composing a command for the shell
-   to execute. Note here that the port number, an integer, is
-   stringified with ``toString``, and the name of the breed,
-   which may contain spaces, is
-   escaped with ``escapeShellArg``
-
-Types
-=====
-
-All of the NixOS module types are available in Liminix. These
-Liminix-specific types also exist in ``pkgs.liminix.lib.types``:
-
-* ``service``: an s6-rc service
-* ``interface``: an s6-rc service which specifies a network
-  interface
-* ``serviceDefn``: a service "template" definition
-
-In the future it is likely that we will extend this to include other
-useful types in the networking domain: for example; IP address,
-network prefix or netmask, protocol family and others as we find them.

doc/development.adoc

@@ -0,0 +1,637 @@
+= For Developers
+
+In any Nix-based system the line between "configuration"
+and "development" is less of a line and more of a continuum.
+This section covers some topics further towards the latter end.
+
+== Writing modules and services
+
+It helps here to know NixOS! Liminix uses the NixOS module
+infrastructure code, meaning that everything that has been written for
+NixOS about the syntax, the type system, and the rules for combining
+configuration values from different sources is just as applicable
+here.
+
+=== Services
+
+For the most part, for common use cases, we hope that Liminix modules
+provide service templates for all the services you will need, and you
+will only have to pass the right parameters to `+build+`.
+
+But if you're reading this then our hopes are in vain.  To create a
+custom service of your own devising, use the [.title-ref]#oneshot# or
+[.title-ref]#longrun# functions:
+
+* a "longrun" service is the "normal" service concept: it has a `+run+`
+action which describes the process to start, and it watches that process
+to restart it if it exits. The process should not attempt to daemonize
+or "background" itself, otherwise s6-rc will think it died. Whatever it
+prints to standard output/standard error will be logged.
+
+[source,nix]
+----
+config.services.cowsayd = pkgs.liminix.services.longrun {
+  name = "cowsayd";
+  run = "${pkgs.cowsayd}/bin/cowsayd --port 3001 --breed hereford";
+  # don't start this until the lan interface is ready
+  dependencies = [ config.services.lan ];
+}
+----
+
+* a "oneshot" service doesn't have a process attached. It consists of
+`+up+` and `+down+` actions which are bits of shell script that are run
+at the appropriate points in the service lifecycle
+
+[source,nix]
+----
+config.services.greenled = pkgs.liminix.services.oneshot {
+  name = "greenled";
+  up = ''
+    echo 17 > /sys/class/gpio/export
+    echo out > /sys/class/gpio/gpio17/direction
+    echo 0   > /sys/class/gpio/gpio17/value
+  '';
+  down = ''
+    echo 0   > /sys/class/gpio/gpio17/value
+  '';
+}
+----
+
+Services may have dependencies: as you see above in the `+cowsayd+`
+example, it depends on some service called `+config.services.lan+`,
+meaning that it won't be started until that other service is up.
+
+===== Service outputs
+
+Outputs are a mechanism by which a service can provide data which may be
+required by other services. For example:
+
+* the DHCP client service can expect to receive nameserver address
+information as one of the fields in the response from the DHCP server:
+we provide that as an output which a dependent service for a stub name
+resolver can use to configure its upstream servers.
+* a service that creates a new network interface (e.g. ppp) will provide
+the name of the interface (`+ppp0+`, or `+ppp1+` or `+ppp7+`) as an
+output so that a dependent service can reference it to set up a route,
+or to configure firewall rules.
+
+A service `+myservice+` should write its outputs as files in
+`+/run/services/outputs/myservice+`: you can look around this directory
+on a running Liminix system to see how it's used currently. Usually we
+use the `+in_outputs+` shell function in the `+up+` or `+run+`
+attributes of the service:
+
+[source,shell]
+----
+(in_outputs ${name}
+ for i in lease mask ip router siaddr dns serverid subnet opt53 interface ; do
+   (printenv $i || true) > $i
+ done)
+----
+
+The outputs are just files, so technically you can read them using
+anything that can read a file. Liminix has two "preferred" mechanisms,
+though:
+
+===== One-off lookups
+
+In any context that ends up being evaluated by the shell, use `+output+`
+to print the value of an output
+
+[source,nix]
+----
+services.defaultroute4 = svc.network.route.build {
+  via = "$(output ${services.wan} address)";
+  target = "default";
+  dependencies = [ services.wan ];
+};
+----
+
+===== Continuous updates
+
+The downside of using shell functions in downstream service startup
+scripts is that they only run when the service starts up: if a service
+output _changes_, the downstream service would have to be restarted to
+notice the change. Sometimes this is OK but other times the downstream
+has no other need to restart, if it can only get its new data.
+
+For this case, there is the `+anoia.svc+` Fennel library, which allows
+you to write a simple loop which is iterated over whenever a service's
+outputs change. This code is from
+`+modules/dhcp6c/acquire-wan-address.fnl+`
+
+[source,fennel]
+----
+(fn update-addresses [wan-device addresses new-addresses exec]
+  ;; run some appropriate "ip address [add|remove]" commands
+  )
+
+(fn run []
+  (let [[state-directory wan-device] arg
+        dir (svc.open state-directory)]
+    (accumulate [addresses []
+                 v (dir:events)]
+      (update-addresses wan-device addresses
+			(or (v:output "address") []) system))))
+----
+
+The `+output+` method seen here accepts a filename (relative to the
+service's output directory), or a directory name. It returns the first
+line of that file, or for directories it returns a table (Lua's
+key/value datastructure, similar to a hash/dictionary) of the outputs in
+that directory.
+
+===== Design considerations for outputs
+
+For preference, outputs should be short and simple, and not require
+downstream services to do complicated parsing in order to use them.
+Shell commands in Liminix are run using the Busybox shell which doesn't
+have the niceties evel of an advanced shell like Bash, let alone those of a
+real programming language.
+
+Note also that the Lua `+svc+` library only reads the first line of each
+output.
+
+
+=== Modules
+
+Modules in Liminix conventionally live in
+`+modules/somename/default.nix+`. If you want or need to write your own,
+you may wish to refer to the examples there in conjunction with reading
+this section.
+
+A module is a function that accepts `+{lib, pkgs, config, ... }+` and
+returns an attrset with keys `+imports, options, config+`.
+
+* `+imports+` is a list of paths to the other modules required by this
+one
+* `+options+` is a nested set of option declarations
+* `+config+` is a nested set of option definitions
+
+The NixOS manual section
+https://nixos.org/manual/nixos/stable/#sec-writing-modules[Writing NixOS
+Modules] is a quite comprehensive reference to writing NixOS modules,
+which is also mostly applicable to Liminix except that it doesn't cover
+service templates.
+
+
+==== Service templates
+
+Although you can define services "ad hoc" using `longrun` or `oneshot`
+<<_writing_services,as above>>, this approach has limitations if
+you're writing code intended for wider use. Services in the
+modules bundled with Liminix are implemented following a pattern we
+call "service templates": functions that accept a _type-checked_
+attrset and return an appropriately configured service that can be
+assigned by the caller to a key in ``config.services``.
+
+To expose a service template in a module, it needs the following:
+
+* an option declaration for `+system.service.myservicename+` with the
+type of `+liminix.lib.types.serviceDefn+`
+
+[source,nix]
+----
+options = {
+  system.service.cowsay = mkOption {
+    type = liminix.lib.types.serviceDefn;
+  };
+};
+----
+
+* an option definition for the same key, which specifies where to import
+the service template from (often `+./service.nix+`) and the types of its
+parameters.
+
+[source,nix]
+----
+config.system.service.cowsay = config.system.callService ./service.nix {
+  address = mkOption {
+    type = types.str;
+    default = "0.0.0.0";
+    description = "Listen on specified address";
+    example = "127.0.0.1";
+  };
+  port = mkOption {
+    type = types.port;
+    default = 22;
+    description = "Listen on specified TCP port";
+  };
+  breed = mkOption {
+    type = types.str;
+    default = "British Friesian"
+    description = "Breed of the cow";
+  };
+};
+----
+
+Then you need to provide the service template itself, probably in
+`+./service.nix+`:
+
+[source,nix]
+----
+{
+  # any nixpkgs package can be named here
+  liminix
+, cowsayd
+, serviceFns
+, lib
+}:
+# these are the parameters declared in the callService invocation
+{ address, port, breed} :
+let
+  inherit (liminix.services) longrun;
+  inherit (lib.strings) escapeShellArg;
+in longrun {
+  name = "cowsayd";
+  run = "${cowsayd}/bin/cowsayd --address ${address} --port ${builtins.toString port} --breed ${escapeShellArg breed}";
+}
+----
+
+TIP: Not relevant to module-based services specifically, but a common gotcha
+when specifiying services is forgetting to transform "rich" parameter
+values into text when composing a command for the shell to execute. Note
+here that the port number, an integer, is stringified with `+toString+`,
+and the name of the breed, which may contain spaces, is escaped with
+`+escapeShellArg+`
+
+=== Types
+
+All of the NixOS module types are available in Liminix. These
+Liminix-specific types also exist in `+pkgs.liminix.lib.types+`:
+
+* `+service+`: an s6-rc service
+* `+interface+`: an s6-rc service which specifies a network interface
+* `+serviceDefn+`: a service "template" definition
+
+In the future it is likely that we will extend this to include other
+useful types in the networking domain: for example; IP address, network
+prefix or netmask, protocol family and others as we find them.
+
+
+=== Emulated devices
+
+Unless your changes depend on particular hardware devices, you may
+want to test your new/changed module with one of the emulated
+"devices" which runn on your build machine using the free
+http://www.qemu.org[QEMU machine emulator]. They are
+
+* `qemu`(MIPS)
+* `qemu-armv7l`(32 bit ARM)
+* `qemu-aarch64` (64 bit ARM)
+
+This means you don't need to keep flashing or messing with U-Boot: it
+also enables testing against emulated network peers using
+https://wiki.qemu.org/Documentation/Networking#Socket[QEMU socket
+networking], which may be preferable to letting Liminix loose on your
+actual LAN. To build,
+
+[source,console]
+----
+nix-build -I liminix-config=path/to/your/configuration.nix --arg device "import ./devices/qemu" -A outputs.default
+----
+
+This creates a `+result/+` directory containing a `+vmlinux+` and a
+`+rootfs+`, and a shell script `+run.sh+` which invokes QEMU to run
+that kernel with that filesystem. It connects the Liminix serial console
+and the https://www.qemu.org/docs/master/system/monitor.html[QEMU
+monitor] to stdin/stdout. Use `^P` (not `^A`) to switch to the monitor.
+
+// FIXME should add a `connect.sh` script instead of requiring nix-shell here
+
+If you run with `+--background /path/to/some/directory+` as the first
+parameter, it will fork into the background and open Unix sockets in
+that directory for console and monitor. Use `+nix-shell --run
+connect-vm+` to connect to either of these sockets, and ^O to
+disconnect.
+
+[[qemu-networking]]
+===== Networking
+
+VMs can network with each other using QEMU socket networking. We observe
+these conventions, so that we can run multiple emulated instances and
+have them wired up to each other in the right way:
+
+* multicast 230.0.0.1:1234 : access (interconnect between router and
+"isp")
+* multicast 230.0.0.1:1235 : lan
+* multicast 230.0.0.1:1236 : world (the internet)
+
+Any VM started by a `+run.sh+` script is connected to "lan" and
+"access". The emulated upstream (see below) runs PPPoE and is
+connected to "access" and "world".
+
+===== Upstream connection
+
+In pkgs/routeros there is a derivation to install and configure
+https://mikrotik.com/software[Mikrotik RouterOS] as a PPPoE access
+concentrator connected to the `+access+` and `+world+` networks, so that
+Liminix PPPoE client support can be tested without actual hardware.
+
+This is made available as the `+routeros+` command in `+buildEnv+`, so
+you can do something like:
+
+....
+mkdir ros-sockets
+nix-shell
+nix-shell$ routeros ros-sockets
+nix-shell$ connect-vm ./ros-sockets/console
+....
+
+to start it and connect to it. Note that by default it runs in the
+background. It is connected to "access" and "world" virtual networks and
+runs a PPPoE service on "access" - so a Liminix VM with a PPPOE client
+can connect to it and thus reach the virtual internet. [ check, but
+pretty sure this is not the actual internet ]
+
+[.title-ref]#Liminix does not provide RouterOS licences and it is your
+own responsibility if you use this to ensure you're compliant with the
+terms of Mikrotik's licencing. It may be supplemented or replaced in
+time with configurations for RP-PPPoE and/or Accel PPP.#
+
+== Hardware hacking/porting to new device
+
+The steps to port to a new hardware device are largely undocumented at
+present (although this hasn't stopped people from figuring it out
+already). As an outline I would recommend
+
+* choose hardware that OpenWrt already supports, otherwise you will
+probably spend a lot of time writing kernel code.  The OpenWrt kernel
+supports many network interfaces and other hardware for a lot of
+hardware boards that might only just about be able to boot Linux on a
+serial port if you stick to mainline Linux
+
+* work out how to get a serial console on it. You are unlikely to get
+  working networking on your first go at boulding a kernel
+
+* find the most similar device in Liminiux and copy
+  `devices/existing-similar-device` to `devices/cool-new-device` as a
+  starting point
+
+* use the kernel configuration (`/proc/config.gz`) from OpenWrt as a
+ reference for the kernel config you'll need to specify
+ in `devices/cool-new-device/default.nix`
+
+* break it down into achieveable goals. Your first goal should be
+  something that can TFTP boot the kernel as far as a running
+  userland. Networking is harder, Wifi often much harder - it
+  sometimes also depends on having working flash _even if_ you're TFTP
+  booting because the driver expects to load wifi firmware or
+  calibration data from the flash
+
+* ask on IRC!
+
+=== TFTP
+
+[[tftpserver]]
+How you get your image onto hardware will vary according to the device,
+but is likely to involve taking it apart to add wires to serial console
+pads/headers, then using U-Boot to fetch images over TFTP. The OpenWrt
+documentation has a
+https://openwrt.org/docs/techref/hardware/port.serial[good explanation]
+of what you may expect to find on the device.
+
+[[tufted]]
+`tufted` is a rudimentary TFTP server which runs from the command
+line, has an allowlist for client connections, and follows symlinks,
+so you can have your device download images direct from the
+`+./result+` directory without exposing `+/nix/store/+` to the
+internet or mucking about copying files to `+/tftproot+`. If the
+permitted device is to be given the IP address 192.168.8.251 you might
+do something like this:
+
+[source,console]
+----
+nix-shell --run "tufted -a 192.168.8.251 result"
+----
+
+Now add the device and server IP addresses to your configuration:
+
+[source,nix]
+----
+boot.tftp = {
+  serverip = "192.168.8.111";
+  ipaddr = "192.168.8.251";
+};
+----
+
+and then build the derivation for `+outputs.default+` or
+`+outputs.mtdimage+` (for which it will be an alias on any device where
+this is applicable). You should find it has created
+
+* `+result/firmware.bin+` which is the file you are going to flash
+* `+result/flash.scr+` which is a set of instructions to U-Boot to
+download the image and write it to flash after erasing the appropriate
+flash partition.
+
+NOTE: TTL serial connections typically have no form of flow control and so
+don't always like having massive chunks of text pasted into them - and
+U-Boot may drop characters while it's busy. So don't necessarily expect
+to copy-paste the whole of `+boot.scr+` into a terminal emulator and
+have it work just like that. You may need to paste each line one at a
+time, or even retype it.
+
+=== Running from RAM
+
+For a faster edit-compile-test cycle, you can build a TFTP-bootable
+image which boots directly from RAM (using phram) instead of needing
+to be flashed first. In your device configuration add
+
+[source,nix]
+----
+imports = [
+  ./modules/tftpboot.nix
+];
+----
+
+and then build `+outputs.tftpboot+`. This creates a file `+result/boot.scr+`, which you can copy and paste into U-Boot to
+transfer the kernel and filesystem over TFTP and boot the kernel from
+RAM.
+
+[[bng]]
+=== Networking
+
+You probably don't want to be testing a device that might serve DHCP,
+DNS and routing protocols on the same LAN as you (or your colleagues,
+employees, or family) are using for anything else, because it will
+interfere. You also might want to test the device against an "upstream"
+connection without having to unplug your regular home router from the
+internet so you can borrow the cable/fibre/DSL.
+
+`+bordervm+` is included for this purpose. You will need
+
+* a Linux machine with a spare (PCI or USB) ethernet device which you
+can dedicate to Liminix
+* an L2TP service such as https://www.aa.net.uk/broadband/l2tp-service/
+
+You need to "hide" the Ethernet device from the host so that QEMU has
+exclusive use of it. For PCI this means configuring it for VFIO
+passthru; for USB you need to unload the module(s) it uses. I have
+this segment in my build machine's `configuration.nix` which you may
+be able to adapt:
+
+[source,nix]
+----
+boot = {
+  kernelParams = [ "intel_iommu=on" ];
+  kernelModules = [
+    "kvm-intel" "vfio_virqfd" "vfio_pci" "vfio_iommu_type1" "vfio"
+  ];
+
+  postBootCommands = ''
+    # modprobe -i vfio-pci
+    # echo vfio-pci > /sys/bus/pci/devices/0000:01:00.0/driver_override
+  '';
+  blacklistedKernelModules = [
+    "r8153_ecm" "cdc_ether"
+  ];
+};
+services.udev.extraRules = ''
+  SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="8153", OWNER="dan"
+'';
+----
+
+Then you can execute `+run-border-vm+` in a `+buildEnv+` shell, which
+starts up QEMU using the NixOS configuration in
+`+bordervm-configuration.nix+`.
+
+Inside the VM
+
+* your Liminix checkout is mounted under `+/home/liminix/liminix+`
+* TFTP is listening on the ethernet device and serving
+`+/home/liminix/liminix+`. The server IP address is 10.0.0.1
+* a PPPOE-L2TP relay is running on the same ethernet card. When the
+connected Liminix device makes PPPoE requests, the relay spawns L2TPv2
+Access Concentrator sessions to your specified L2TP LNS. Note that
+authentication is expected at the PPP layer not the L2TP layer, so the
+PAP/CHAP credentials provided by your L2TP service can be configured
+into your test device - bordervm doesn't need to know about them.
+
+To configure bordervm, you need a file called `+bordervm.conf.nix+`
+which you can create by copying and appropriately editing
+`+bordervm.conf-example.nix+`
+
+NOTE: If you make changes to the bordervm configuration after executing
+`+run-border-vm+`, you need to remove the `+border.qcow2+` disk image
+file otherwise the changes won't get picked up.
+
+== Contributing
+
+Patches welcome! Also bug reports, documentation improvements,
+experience reports/case studies etc etc all equally as welcome.
+
+* if you have an obvious bug fix, new package, documentation
+  improvement or other uncontroversial small patch, send it straight
+  in.
+
+* if you have a large new feature or design change in mind, please
+  please _get in touch_ to talk about it before you commit time to
+  implementing it. Perhaps it isn't what we were expecting, almost
+  certainly we will have ideas or advice on what it should do or how
+  it should be done.
+
+Liminix development is not tied to Github or any other particular
+forge. How to send changes:
+
+1. Push your Liminix repo with your changes to a git repository
+somewhere on the Internet that I can clone from. It can be on Codeberg
+or Gitlab or Sourcehut or Forgejo or Gitea or Github or a bare repo in
+your own personal web space or any kind of hosting you like.
+
+2. Email devel@liminix.org with the URL of the repo and the branch
+name, and we will take a look.
+
+If that's not an option, I’m also happy for you to send your changes
+direct to the list itself, as an incremental git bundle or using git
+format-patch. We'll work it out somehow.
+
+The main development repo for Liminix is hosted at
+<https://gti.telent.net/dan/liminix>, with a read-only mirror at
+<https://github.com/telent/liminix>. If you're happy to use Github
+then you can fork from the latter to make your changes, but please use
+the mailing list one of the approved routes to tell me about your changes because I don't regularly go there to check PRs.
+
+Remember that the <<_code_of_conduct>> applies to all Liminix spaces,
+and anyone who violates it may be sanctioned or expelled from these
+spaces at the discretion of the project leadership.
+
+=== Nix language style
+
+This section describes some Nix language style points that we attempt to
+adhere to in this repo. Some are more aspirational than actual.
+
+* indentation and style is according to `nixfmt-rfc-style`
+* favour `+callPackage+` over raw `+import+` for calling derivations or
+any function that may generate one - any code that might need `+pkgs+`
+or parts of it.
+* prefer `+let inherit (quark) up down strange charm+` over
+`+with quark+`, in any context where the scope is more than a single
+expression or there is more than one reference to `+up+`, `+down+` etc.
+`+with pkgs; [ foo bar baz]+` is OK,
+`+with lib; stdenv.mkDerivation { ... }+` is usually not.
+* `+<liminix>+` is defined only when running tests, so don't refer to it
+in "application" code
+* the parameters to a derivation are sorted alphabetically, except for
+`+lib+`, `+stdenv+` and maybe other non-package "special cases"
+* where a `+let+` form defines multiple names, put a newline after the
+token `+let+`, and indent each name two characters
+* to decide whether some code should be a package or a module? Packages
+are self-contained - they live in `+/nix/store/eeeeeee-name+` and don't
+directly change system behaviour by their presence or absense. modules
+can add to `+/etc+` or `+/bin+` or other global state, create services,
+all that side-effecty stuff. Generally it should be a package unless it
+can't be.
+
+=== Copyright
+
+The Nix code in Liminix is MIT-licenced (same as Nixpkgs), but the code
+it combines from other places (e.g. Linux, OpenWrt) may have a variety
+of licences. Copyright assignment is not expected:
+just like when submitting to the Linux kernel you retain the copyright
+on the code you contribute.
+
+=== Automated builds
+
+Automated builds are run on each push to the main branch. This tests
+that (among other things)
+
+* every device image builds
+* the build for the “qemu” target is executed with a fake network upstream to test
+  * PPPoE and DHCP service
+  * hostap (wireless gateway)
+
+You can view the build output at https://build.liminix.org . The tests
+are defined in ci.nix.
+
+Unfortunately there's no (easy) way I can make _my_ CI infrastructure
+run _your_ code, other than merging it. But see <<_running_tests>>
+for how to exercise the same code locally on your machine.
+
+
+== Running tests
+
+You can run all of the tests by evaluating `+ci.nix+`, which is the
+input I use in Hydra.
+
+[source,console]
+----
+nix-build -I liminix=`pwd`  ci.nix -A pppoe # run one job
+nix-build -I liminix=`pwd`  ci.nix -A all # run all jobs
+----
+
+== Troubleshooting
+
+=== Diagnosing unexpectedly large images
+
+Sometimes you can add a package and it causes the image size to balloon
+because it has dependencies on other things you didn't know about. Build
+the `+outputs.manifest+` attribute, which is a JSON representation of
+the filesystem, and you can run `+nix-store --query+` on it.
+
+[source,console]
+----
+nix-build -I liminix-config=path/to/your/configuration.nix \
+  --arg device "import ./devices/qemu" -A outputs.manifest \
+  -o manifest
+nix-store -q --tree manifest
+----

doc/development.rst

@@ -1,340 +0,0 @@
-Development
-###########
-
-As a developer working on Liminix, or implementing a service or
-module, you probably want to test your changes more conveniently
-than by building and flashing a new image every time. This section
-documents various affordances for iteration and experiments.
-
-In general, packages and tools that run on the "build" machine are
-available in the ``buildEnv`` derivation and can most easily
-be added to your environment by running :command:`nix-shell`.
-
-
-
-Emulated devices
-****************
-
-Liminix has a ``qemu`` device, which generates images suitable for
-running on your build machine using the free `QEMU machine emulator <http://www.qemu.org>`_.
-This is useful for developing userland without needing to keep
-flashing or messing with U-Boot: it also enables testing against
-emulated network peers using `QEMU socket networking <https://wiki.qemu.org/Documentation/Networking#Socket>`_,
-which may be preferable to letting Liminix loose on your actual LAN.
-To build it,
-
-.. code-block:: console
-
-    nix-build -I liminix-config=path/to/your/configuration.nix --arg device "import ./devices/qemu" -A outputs.default
-
-This creates a :file:`result/` directory containing a :file:`vmlinux`
-and a :file:`rootfs`, and also a shell script :file:`run.sh` which
-invokes QEMU to run that kernel with that filesystem. It connects the Liminix
-serial console and the `QEMU monitor  <https://www.qemu.org/docs/master/system/monitor.html>`_ to stdin/stdout. Use ^P (not ^A) to switch to the monitor.
-
-If you run with ``--background /path/to/some/directory`` as the first
-parameter, it will fork into the background and open Unix sockets in
-that directory for console and monitor.  Use :command:`nix-shell --run
-connect-vm` to connect to either of these sockets, and ^O to
-disconnect.
-
-.. _qemu-networking:
-
-Networking
-==========
-
-VMs can network with each other using QEMU
-socket networking.  We observe these conventions, so that we can run
-multiple emulated instances and have them wired up to each other in
-the right way:
-
-* multicast 230.0.0.1:1234  : access (interconnect between router and "isp")
-* multicast 230.0.0.1:1235  : lan
-* multicast 230.0.0.1:1236  : world (the internet)
-
-Any VM started by a :command:`run.sh` script is connected to "lan" and
-"access", and the emulated border network gateway (see below) runs
-PPPoE and is connected to "access" and "world".
-
-.. _border-network-gateway:
-
-Border Network Gateway
-----------------------
-
-In pkgs/routeros there is a derivation to install and configure
-`Mikrotik RouterOS <https://mikrotik.com/software>`_ as a PPPoE access
-concentrator connected to the ``access`` and ``world`` networks, so that
-Liminix PPPoE client support can be tested without actual hardware.
-
-This is made available as the :command:`routeros` command in
-``buildEnv``, so you can do something like::
-
-    mkdir ros-sockets
-    nix-shell
-    nix-shell$ routeros ros-sockets
-    nix-shell$ connect-vm ./ros-sockets/console
-
-to start it and connect to it. Note that by default it runs in the
-background. It is connected to "access" and "world" virtual networks
-and runs a PPPoE service on "access" - so a Liminix VM with a
-PPPOE client can connect to it and thus reach the virtual internet.
-[ check, but pretty sure this is not the actual internet ]
-
-`Liminix does not provide RouterOS licences and it is your own
-responsibility if you use this to ensure you're compliant with the
-terms of Mikrotik's licencing. It may be supplemented or replaced in
-time with configurations for RP-PPPoE and/or Accel PPP.`
-
-Hardware devices
-****************
-
-
-TFTP
-====
-
-.. _tftp server:
-
-How you get your image onto hardware will vary according to the
-device, but is likely to involve taking it apart to add wires to
-serial console pads/headers, then using U-Boot to fetch images over
-TFTP.  The OpenWrt documentation has a `good explanation <https://openwrt.org/docs/techref/hardware/port.serial>`_ of what you may expect to find on
-the device.
-
-There is a rudimentary TFTP server bundled with the system which runs
-from the command line, has an allowlist for client connections, and
-follows symlinks, so you can have your device download images direct
-from the :file:`./result` directory without exposing :file:`/nix/store/` to the
-internet or mucking about copying files to :file:`/tftproot`. If the
-permitted device is to be given the IP address 192.168.8.251 you might
-do something like this:
-
-.. code-block:: console
-
-    nix-shell --run "tufted -a 192.168.8.251 result"
-
-Now add the device and server IP addresses to your configuration:
-
-.. code-block:: nix
-
-  boot.tftp = {
-    serverip = "192.168.8.111";
-    ipaddr = "192.168.8.251";
-  };
-
-and then build the derivation for ``outputs.default`` or
-``outputs.mtdimage`` (for which it will be an alias on any device
-where this is applicable). You should find it has created
-
-* :file:`result/firmware.bin` which is the file you are going to flash
-* :file:`result/flash.scr` which is a set of instructions to U-Boot to
-  download the image and write it to flash after erasing the appropriate
-  flash partition.
-
-.. NOTE::
-
-   TTL serial connections typically have no form of flow control and
-   so don't always like having massive chunks of text pasted into
-   them - and U-Boot may drop characters while it's busy. So don't
-   necessarily expect to copy-paste the whole of :file:`boot.scr` into
-   a terminal emulator and have it work just like that. You may need
-   to paste each line one at a time, or even retype it.
-
-
-For a faster edit-compile-test cycle, you can build a TFTP-bootable
-image instead of flashing. In your device configuration add
-
-.. code-block:: nix
-
-  imports = [
-    ./modules/tftpboot.nix
-  ];
-
-and then build ``outputs.tftpboot``. This creates a file in
-``result/`` called ``boot.scr``, which you can copy and paste into
-U-Boot to transfer the kernel and filesystem over TFTP and boot the
-kernel from RAM.
-
-
-.. _bng:
-
-Networking
-==========
-
-You probably don't want to be testing a device that might serve DHCP,
-DNS and routing protocols on the same LAN as you (or your colleagues,
-employees, or family) are using for anything else, because it will
-interfere. You also might want to test the device against an
-"upstream" connection without having to unplug your regular home
-router from the internet so you can borrow the cable/fibre/DSL.
-
-``bordervm`` is included for this purpose. You will need
-
-* a Linux machine with a spare (PCI or USB) ethernet device which you can dedicate to Liminix
-
-* an L2TP service such as https://www.aa.net.uk/broadband/l2tp-service/
-
-You need to "hide" the Ethernet device from the host - for PCI this
-means configuring it for VFIO passthru; for USB you need to unload the
-module(s) it uses. I have this segment in configuration.nix which you
-may be able to adapt:
-
-.. code-block:: nix
-
-  boot = {
-    kernelParams = [ "intel_iommu=on" ];
-    kernelModules = [
-      "kvm-intel" "vfio_virqfd" "vfio_pci" "vfio_iommu_type1" "vfio"
-    ];
-
-    postBootCommands = ''
-      # modprobe -i vfio-pci
-      # echo vfio-pci > /sys/bus/pci/devices/0000:01:00.0/driver_override
-    '';
-    blacklistedKernelModules = [
-      "r8153_ecm" "cdc_ether"
-    ];
-  };
-  services.udev.extraRules = ''
-    SUBSYSTEM=="usb", ATTRS{idVendor}=="0bda", ATTRS{idProduct}=="8153", OWNER="dan"
-  '';
-
-Then
-you can execute :command:`run-border-vm` in a ``buildEnv`` shell,
-which starts up QEMU using the NixOS configuration in
-:file:`bordervm-configuration.nix`.
-
-In this VM
-
-* your Liminix checkout is mounted under :file:`/home/liminix/liminix`
-
-* TFTP is listening on the ethernet device and serving
-  :file:`/home/liminix/liminix`.  The server IP address is 10.0.0.1
-
-* a PPPOE-L2TP relay is running on the same ethernet card.  When the
-  connected Liminix device makes PPPoE requests, the relay spawns
-  L2TPv2 Access Concentrator sessions to your specified L2TP LNS.
-  Note that authentication is expected at the PPP layer not the L2TP
-  layer, so the PAP/CHAP credentials provided by your L2TP service can
-  be configured into your test device - bordervm doesn't need to know
-  about them.
-
-To configure bordervm, you need a file called :file:`bordervm.conf.nix`
-which you can create by copying and appropriately editing  :file:`bordervm.conf-example.nix`
-
-.. note::
-
-    If you make changes to the bordervm configuration after executing
-    :command:`run-border-vm`, you need to remove the :file:`border.qcow2` disk
-    image file otherwise the changes won't get picked up.
-
-
-Running tests
-*************
-
-You can run all of the tests by evaluating :file:`ci.nix`, which is the
-input I use in Hydra. 
-
-.. code-block:: console
-
-    nix-build -I liminix=`pwd`  ci.nix -A pppoe # run one job
-    nix-build -I liminix=`pwd`  ci.nix -A all # run all jobs
-    
-
-Troubleshooting
-***************
-
-Diagnosing unexpectedly large images
-====================================
-
-Sometimes you can add a package and it causes the image size to balloon
-because it has dependencies on other things you didn't know about. Build the
-``outputs.manifest`` attribute, which is a JSON representation of the
-filesystem, and you can run :command:`nix-store --query` on it.
-
-.. code-block:: console
-
-    nix-build -I liminix-config=path/to/your/configuration.nix \
-      --arg device "import ./devices/qemu" -A outputs.manifest \
-      -o manifest
-    nix-store -q --tree manifest
-
-
-Contributing
-************
-
-Contributions are welcome, though in these early days there may be a
-bit of back and forth involved before patches are merged:
-Please get in touch somehow `before` you invest a lot of time into a
-code contribution I haven't asked for.  Just so I know it's expected
-and you're not wasting time doing something I won't accept or have
-already started on.
-
-
-Nix language style
-==================
-
-This section describes some Nix language style points that we
-attempt to adhere to in this repo.
-
-* favour ``callPackage`` over raw ``import`` for calling derivations
-  or any function that may generate one - any code that might need
-  ``pkgs`` or parts of it.
-
-* prefer ``let inherit (quark) up down strange charm`` over
-  ``with quark``, in any context where the scope is more than a single
-  expression or there is more than one reference to ``up``, ``down``
-  etc.  ``with pkgs; [ foo bar baz]`` is OK,
-  ``with lib; stdenv.mkDerivation { ... }`` is usually not.
-
-* ``<liminix>`` is defined only when running tests, so don't refer to it
-  in "application" code
-
-* the parameters to a derivation are sorted alphabetically, except for
-  ``lib``, ``stdenv`` and maybe other non-package "special cases"
-
-* indentation is whatever emacs nix-mode says it is.
-
-* where a ``let`` form defines multiple names, put a newline after the
-  token ``let``, and indent each name two characters
-
-* to decide whether some code should be a package or a module?
-  Packages are self-contained - they live in ``/nix/store/eeeeeee-name``
-  and don't directly change system behaviour by their presence or
-  absense. modules can add to
-  ``/etc`` or ``/bin`` or other global state, create services, all that
-  side-effecty stuff.  Generally it should be a package unless it
-  can't be.
-
-
-
-Copyright
-=========
-
-The Nix code in Liminix is MIT-licenced (same as Nixpkgs), but the
-code it combines from other places (e.g. Linux, OpenWrt) may have a
-variety of licences.  I have no intention of asking for copyright
-assignment: just like when submitting to the Linux kernel you retain
-the copyright on the code you contribute.
-
-
-Code of Conduct
-===============
-
-Please govern yourself in Liminix project venues according to the
-`Code of Conduct <https://gti.telent.net/dan/liminix/src/commit/7bcf6b15c3fdddafeda13f65b3cd4a422dc52cd3/CODE-OF-CONDUCT.md>`_
-
-
-Where to send patches
-=====================
-
-
-Liminix' primary repo is https://gti.telent.net/dan/liminix but you
-can't send code there directly  because it doesn't have open registrations.
-
-* There's a `mirror on Github <https://github.com/telent/liminix>`_ for
-  convenience and visibility: you can open PRs against that
-
-* or, you can send me your patch by email using `git send-email <https://git-send-email.io/>`_
-
-* or in the future, some day, we will have federated Gitea using
-  ActivityPub.

doc/hardware.nix

@@ -11,7 +11,7 @@ let
       d' = {
         description = ''
           ${n}
-          ${substring 0 (stringLength n) "********************************"}
+          ${substring 0 (stringLength n) "============================"}
         '';
       } // d;
     in
@@ -19,18 +19,6 @@ let
   ) devices;
 in
 writeText "hwdoc" ''
-  Supported hardware
-  ##################
-
-  For development, the `GL.iNet GL-MT300A <https://www.gl-inet.com/products/gl-mt300a/>`_
-  is an attractive choice as it has a builtin "debrick" procedure in the
-  boot monitor and is also comparatively simple to
-  attach serial cables to (soldering not required), so it
-  is lower-risk than some devices.
-
-  For a more powerful device, something with an ath10k would be the safe bet,
-  or the Linksys E8450 which seems popular in the openwrt community.
-
   ${lib.concatStringsSep "\n\n" texts}
 
 ''

doc/index.adoc

@@ -0,0 +1,57 @@
+= Liminix
+Daniel Barlow
+:doctype: book
+:toc: left
+
+include::intro.adoc[]
+
+include::tutorial.adoc[]
+
+include::installation.adoc[]
+
+= For Administrators
+
+include::configuration.adoc[]
+
+include::admin.adoc[]
+
+include::development.adoc[]
+
+include::modules.adoc[]
+
+include::code-of-conduct.adoc[]
+
+[appendix]
+= Supported hardware
+
+=== Recommended devices
+
+For development, the supported GL.iNet devices are all good choices if
+you can find them, as they have a builtin "debrick" procedure in the
+boot monitor and are also comparatively simple to attach serial cables
+to (soldering not required), so are lower-risk than some other devices.
+
+For a more powerful device, something with an ath10k wireless would be
+the safe bet, or the Linksys E8450 which seems popular in the OpenWrt
+community.
+
+include::hardware.adoc[]
+
+[appendix]
+= Module and service options
+
+include::module-options-generated.inc.adoc[]
+
+[appendix]
+= Outputs
+
+*Outputs* are artefacts that can be installed somehow on a
+target device, or "installers" which run on the target device to perform
+the installation.
+
+There are different outputs because different target devices need
+different artefacts, or have different ways to get that artefact
+installed. The options available for a particular device are described
+in the section for that device.
+
+include::outputs-generated.inc.adoc[]

doc/index.rst

@@ -1,24 +0,0 @@
-Liminix
-#######
-
-.. toctree::
-   :maxdepth: 3
-   :caption: Contents:
-
-   intro
-   tutorial
-   installation
-   configuration
-   admin
-   development
-   modules
-   hardware
-   outputs
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

doc/installation.adoc

@@ -0,0 +1,182 @@
+= Installation
+
+Hardware devices vary wildly in their affordances for installing new
+operating systems, so it should be no surprise that the Liminix
+installation procedure is hardware-dependent. This section contains
+generic instructions, but please refer to the documentation for your
+device to find whether and how well they apply.
+
+Most of the supported devices fall into one of two broad categories:
+
+* devices we install by preparing a raw flash image and copying it
+  directly onto (some part of) the flash. This is analogous to (though
+  not quite the same as) using
+  https://www.man7.org/linux/man-pages/man1/dd.1.html:dd(1) on a
+  "grown up" computer to copy a raw disk image. Devices in this
+  category are usually smaller, older, and/or less powerful.
+
+* devices where the vendor provides a "higher level" storage
+  abstraction, such as http://linux-mtd.infradead.org/doc/ubi.html:UBI
+  over raw flash, or a consumer flash such as MMC, or another storage
+  technology entirely. Installation on these devices is less uniform
+  because it depends on exactly what kind of storage abstraction.
+  
+
+== Building a firmware image
+
+Liminix uses the Nix language to provide congruent configuration
+management. This means that to change anything about the way in which a
+Liminix system works, you make that change in your `+configuration.nix+`
+(or one of the other files it references), and rerun `+nix-build+` 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: `+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.
+
+For a more full description of how to configure Liminix, see
+<<_configuration>>. Assuming for the moment that you want a typical home
+wireless gateway/router, the best way to get started is to copy
+`+examples/rotuer.nix+` and edit it for your requirements.
+
+[source,console]
+----
+$ cp examples/rotuer.nix configuration.nix
+$ vi configuration.nix # other editors are available 
+$ # adjust this next command for your hardware device
+$ nix-build -I liminix-config=./configuration.nix \
+ --arg device "import ./devices/gl-mt300a" -A outputs.default
+----
+
+For raw flash devices, this will leave you with a file
+`+result/firmware.bin+` which you now need to write to the flash.
+For other devices, _please check the device documentation_
+
+== Flashing from the boot monitor (TFTP install)
+
+You will need
+
+* to open the device and attach a TTL serial adaptor of some kind 
+* a TFTP server on the network that the device is plugged into
+(or can be plugged into for installation)
+
+Installing via serial connection is quite hardware-specific and
+depending on the device may even involve soldering. However, it is in
+some ways the most "reliable" option: if you can see what's happening
+(or not happening) in early boot, the risk of "bricking" is
+substantially reduced and you have options for recovering if you
+misstep or flash a bad image.
+
+[[serial]]
+=== Serial connections
+
+To speak to U-Boot on your device you'll usually need a serial
+connection to it. This typically involves opening the box, locating the
+serial header pins (TX, RX and GND) and connecting a USB TTL converter
+to them.
+
+The Rolls Royce of USB/UART cables is the
+https://cpc.farnell.com/ftdi/ttl-232r-rpi/cable-debug-ttl-232-usb-rpi/dp/SC12825?st=usb%20to%20uart%20cable[FTDI
+cable], but there are cheaper alternatives based on the PL2303 and
+CP2102 chipsets - or you could even get creative and use the
+https://pinout.xyz/[UART GPIO pins] on a Raspberry Pi. Whatever you do,
+make sure that the voltages are compatible: if your device is 3.3V (this
+is typical but not universal), you don't want to be sending it 5v or
+(even worse) 12v.
+
+Run a terminal emulator such as Minicom on the computer at other end of
+the link. 115200 8N1 is the typical speed.
+
+[NOTE]
+====
+TTL serial connections often have no flow control and so don't always
+like having massive chunks of text pasted into them - and U-Boot may
+drop characters while it's busy. So don't do that.
+
+If using Minicom, you may find it helps to bring up the "Termimal
+settings" dialog (C^A T), then configure "Newline tx delay" to some
+small but non-zero value.
+====
+
+When you turn the router on you should be greeted with some messages
+from U-Boot, followed by the instruction to hit some key to stop
+autoboot. Do this and you will get to the prompt. If you didn't see
+anything, the strong likelihood is that TX and RX are the wrong way
+around, or your computer is expecting flow control which the 3 wire
+connection does not provide. If you see garbage, try a different
+speed.
+
+Interesting commands to try first in U-Boot are `+help+` and
+`+printenv+`.
+
+=== TFTP
+
+You will also need to configure a TFTP server on a network that's
+accessible to the device: how you do that will vary according to which
+TFTP server you're using and so is out of scope for this document.
+
+HINT: <<tufted>>, a rudimentary TFTP server, is supplied with Liminix
+for development purposes. It may or may not fit your needs here.
+
+==== Building and installing the image
+
+Follow the device-specific instructions for "TFTP install": usually, the
+steps are
+
+* build the [.title-ref]#outputs.mtdimage# output
+* copy `+result/firmware.bin+` to wherever your TFTP server serves files
+from
+* execute the commands listed in `+result/flash.scr+` at the
+U-Boot command line
+* reset the device
+
+You should now see messages from U-Boot, then from the Linux kernel and
+eventually a shell prompt.
+
+NOTE: Before you reboot, check which networks the device is plugged into, and
+disconnect as necessary. If you've just installed a DHCP server or
+anything else that responds to broadcasts, you may not want it to do
+that on the network that you temporarily connected it to for installing
+it.
+
+== Flashing from OpenWrt
+
+CAUTION: Untested! A previous version of these instructions (without
+the -e flag) led to soft-bricking the device when flashing a JFFS2
+image. The current version _should_ work better but if you are reading this
+message then nobody has yet confirmed it
+
+If your device is running OpenWrt then it probably has the `+mtd+`
+command installed. Transfer `+result/firmware.bin+` onto the running
+device using e.g. `+scp+`. Now flash as follows:
+
+[source,console]
+----
+mtd -e -r write /tmp/firmware.bin firmware
+----
+
+The options to this command are for "erase before writing" and "reboot
+after writing".
+
+For more information, please see the
+https://openwrt.org/docs/guide-user/installation/sysupgrade.cli[OpenWrt
+manual] which may also contain (hardware-dependent) instructions on how
+to flash an image using the vendor firmware - perhaps even from a web
+interface.
+
+== Flashing from Liminix
+
+If the device is already running Liminix then in general you cannot safely
+copy a new image over the top of the running system while it is running.
+
+If the running system was configured with <<levitate>> you can use
+that to safely flash your new image.  Otherwise you may attempt to use
+`+flashcp+` directly, but bust out the serial leads in preparation for
+it going horribly wrong.
+

doc/installation.rst

@@ -1,211 +0,0 @@
-Installation
-############
-
-Hardware devices vary wildly in their affordances for installing new
-operating systems, so it should be no surprise that the Liminix
-installation procedure is hardware-dependent. This section contains
-generic instructions, but please refer to the documentation for your
-device to find whether and how well they apply.
-
-
-Building a firmware image
-*************************
-
-Liminix uses the Nix language to provide congruent configuration
-management.  This means that to change anything about the way in
-which a Liminix system works, you make that change in
-your :file:`configuration.nix` (or one of the other files it references),
-and rerun :command:`nix-build` 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.
-
-For a more full description of how to configure Liminix, see
-:ref:`configuration`. Assuming for the moment that you want a typical
-home wireless gateway/router, the best way to get started is to copy
-:file:`examples/rotuer.nix` and edit it for your requirements.
-
-
-.. code-block:: console
-
-    $ cp examples/rotuer.nix configuration.nix
-    $ vi configuration.nix # other editors are available 
-    $ # adjust this next command for your hardware device
-    $ nix-build -I liminix-config=./configuration.nix \
-     --arg device "import ./devices/gl-mt300a" -A outputs.default
-
-Usually  (not always, *please check the documentation for your device*)
-this will leave you with a file :file:`result/firmware.bin`
-which you now need to flash to the device.
-
-
-Flashing from the boot monitor (TFTP install)
-*********************************************
-
-If you are prepared to open the device and have a TTL serial adaptor
-of some kind to connect it to, you can probably use U-Boot and a TFTP
-server to download and flash the image.
-
-This is quite hardware-specific and may even involve soldering - see
-the documention for your device. However, it is in some ways the most
-"reliable" option: if you can see what's happening (or not happening)
-in early boot, the risk of "bricking" is substantially reduced and you
-have options for recovering if you misstep or flash a bad image.
-
-
-.. _serial:
-
-U-Boot and serial shenanigans
-=============================
-
-Every device that we have so far encountered in Liminix uses `U-Boot,
-the "Universal Boot Loader" <https://docs.u-boot.org/en/latest/>`_ so
-it's worth knowing a bit about it. "Universal" is in this context a
-bit of a misnomer, though: encountering *mainline* U-Boot is very rare
-and often you'll find it is a fork from some version last updated
-in 2008. Upgrading U-Boot is more or less complicated depending on the
-device and is outside scope for Liminix.
-
-To speak to U-Boot on your device you'll usually need a serial
-connection to it.  This typically involves opening the box, locating
-the serial header pins (TX, RX and GND) and connecting a USB TTL
-converter to them.
-
-The Rolls Royce of USB/UART cables is the `FTDI cable
-<https://cpc.farnell.com/ftdi/ttl-232r-rpi/cable-debug-ttl-232-usb-rpi/dp/SC12825?st=usb%20to%20uart%20cable>`_,
-but there are cheaper alternatives based on the PL2303 and CP2102 chipsets -   or you could even 
-get creative and use the `UART GPIO pins <https://pinout.xyz/>`_ on a Raspberry Pi. Whatever you do, make sure
-that the voltages are compatible: if your device is 3.3V (this is
-typical but not universal), you don't want to be sending it 5v or
-(even worse) 12v.
-
-Run a terminal emulator such as Minicom on the computer at other end
-of the link. 115200 8N1 is the typical speed.
-
-.. NOTE::
-
-   TTL serial connections often have no flow control and
-   so don't always like having massive chunks of text pasted into
-   them - and U-Boot may drop characters while it's busy. So don't
-   do that.
-
-   If using Minicom, you may find it helps to bring up the "Termimal
-   settings" dialog (C^A T), then configure "Newline tx delay" to
-   some small but non-zero value.
-
-When you turn the router on you should be greeted with some messages
-from U-Boot, followed by the instruction to hit some key to stop
-autoboot. Do this and you will get to the prompt. If you didn't see
-anything, the strong likelihood is that TX and RX are the wrong way
-around. If you see garbage, try a different speed.
-
-Interesting commands to try first in U-Boot are :command:`help` and
-:command:`printenv`.
-
-You will also need to configure a TFTP server on a network that's
-accessible to the device: how you do that will vary according to which
-TFTP server you're using and so is out of scope for this document.
-
-
-
-Building and installing the image
-=================================
-
-Follow the device-specific instructions for "TFTP install": usually,
-the steps are 
-
-* build the `outputs.mtdimage` output
-* copy :file:`result/firmware.bin` to your TFTP server
-* copy/paste the commands in :file:`result/flash.scr` one at a time into the U-Boot command line
-* reset the device
-
-You should now see messages from U-Boot, then from the Linux kernel
-and eventually a shell prompt.
-
-.. NOTE:: Before you reboot, check which networks the device is
-          plugged into, and disconnect as necessary. If you've just
-          installed a DHCP server or anything similar that responds to
-          broadcasts, you may not want it to do that on the network
-          that you temporarily connected it to for installing it.
-
-
-
-Flashing from OpenWrt
-*********************
-
-.. CAUTION:: Untested! A previous version of these instructions
-	     (without the -e flag) led to bricking the device
-	     when flashing a jffs2 image. If you are reading
-	     this message, nobody has yet reported on whether the
-	     new instructions are any better.
-
-If your device is running OpenWrt then it probably has the
-:command:`mtd` command installed. Build the `outputs.mtdimage` output
-(as you would for a TFTP install) and then transfer
-:file:`result/firmware.bin` onto the device using e.g.
-:command:`scp`. Now flash as follows:
-
-.. code-block:: console
-
-   mtd -e -r write /tmp/firmware.bin firmware
-
-The options to this command are for "erase before writing" and "reboot
-after writing".
-
-For more information, please see the `OpenWrt manual <https://openwrt.org/docs/guide-user/installation/sysupgrade.cli>`_ which may also contain (hardware-dependent) instructions on how to flash an image using the vendor firmware - perhaps even from a web interface.
-
-
-Flashing from Liminix
-*********************
-
-If the device is already running Liminix and has been configured with
-:command:`levitate`, you can use that to safely flash your new image.
-Refer to :ref:`levitate` for an explanation.
-
-If the device is running Liminix but doesn't have :command:`levitate`
-your options are more limited. You may attempt to use
-:command:`flashcp` but it doesn't always work: as it copies the new
-image over the top of the active root filesystem, surprise may ensue.
-Consider instead using a serial connection: you may need one anyway
-after trying flashcp if it corrupts the image.
-
-flashcp (not generally recommended)
-===================================
-
-Connect to the device and locate the "firmware" partition, which you
-can do with a combination of :command:`dmesg` output and the contents
-of :file:`/proc/mtd`
-
-.. code-block:: console
-
-   <5>[    0.469841] Creating 4 MTD partitions on "spi0.0":
-   <5>[    0.474837] 0x000000000000-0x000000040000 : "u-boot"
-   <5>[    0.480796] 0x000000040000-0x000000050000 : "u-boot-env"
-   <5>[    0.487056] 0x000000050000-0x000000060000 : "art"
-   <5>[    0.492753] 0x000000060000-0x000001000000 : "firmware"
-
-   # cat /proc/mtd
-   dev:    size   erasesize  name
-   mtd0: 00040000 00001000 "u-boot"
-   mtd1: 00010000 00001000 "u-boot-env"
-   mtd2: 00010000 00001000 "art"
-   mtd3: 00fa0000 00001000 "firmware"
-   mtd4: 002a0000 00001000 "kernel"
-   mtd5: 00d00000 00001000 "rootfs"
-
-Copy :file:`result/firmware.bin` to the device and now run (in this
-example)
-
-.. code-block:: console
-
-   flashcp -v firmware.bin /dev/mtd3
-
-

doc/intro.adoc

@@ -0,0 +1,62 @@
+= Introduction
+
+== What is Liminix?
+
+Liminix is a Nix-based collection of software tailored for domestic
+wifi router or IoT devices, of the kind that OpenWrt or DD-WRT
+or Gargoyle or Tomato run on. It's not NixOS on your router: we target
+devices that are underpowered for the full NixOS experience. It uses
+busybox tools, musl instead of GNU libc, and s6-rc instead of systemd.
+
+The Liminix name comes from Liminis, in Latin the genitive declension of
+"limen", or "of the threshold". Your router stands at the threshold of
+your (online) home and everything you send to/receive from the outside
+word goes across it.
+
+== Where to find out more
+
+=== The Manual
+
+You are reading it now, and it is available from wherever you
+are reading it :-) but its canonical location is
+https://www.liminix.org/doc/
+
+=== Source code
+
+Liminix source code is held in git, and hosted at
+https://gti.telent.net/dan/liminix, with a mirror at
+https://github.com/telent/liminix. You can clone from either of those
+repos.  For more on this, see <<_contributing>>.
+
+=== IRC
+
+There is an IRC channel https://webchat.oftc.net/?nick=&channels=#liminix[#liminix] registered on the https://www.oftc.net/[OFTC] network, which
+is a good place to ask if you want a quick answer about how to use
+Liminix or are looking at a new port. Be mindful that other
+participants may be in different timezones than your own, so do not
+expect an immediate answer.
+
+=== Mailing lists
+
+Three Liminix mailing lists are available: all are quite low volume.
+To subscribe to any of these lists, send an email to
+listname+subscribe@liminix.org. You can write anything you want in the
+subject and message body: only the destination address is important.
+
+
+* https://lists.liminix.org/announce/maillist.html[`announce@liminix.org`] for infrequent announcements from Liminix maintainers
+* https://lists.liminix.org/devel/maillist.html[`devel@liminix.org`] for development-related discussion, patches, suggestions etc
+* https://lists.liminix.org/users/maillist.html[`users@liminix.org`] for help requests and general discussion
+
+The mailing lists are managed with Mlmmj and archived with MHonArc.
+
+=== Standards of behaviour
+
+Liminix is dedicated to providing a harassment-free experience for
+everyone. We do not tolerate harassment of participants in any form.
+
+The Liminix <<_code_of_conduct>> applies to all Liminix spaces, including
+the IRC channel, mailing lists, and any other forums, both online and
+off. Anyone who violates the code of conduct may be sanctioned or
+expelled from these spaces at the discretion of the project
+leadership.

doc/intro.rst

@@ -1,15 +0,0 @@
-Introduction
-############
-
-Liminix is a Nix-based collection of software tailored for domestic
-wifi router or IoT device devices, of the kind that OpenWrt or DD-WRT
-or Gargoyle or Tomato run on.
-
-This is not NixOS-on-your-router: it's aimed at devices that are
-underpowered for the full NixOS experience. It uses busybox tools,
-musl instead of GNU libc, and s6-rc instead of systemd.
-
-The Liminix name comes from Liminis, in Latin the genitive declension
-of "limen", or "of the threshold". Your router stands at the threshold
-of your (online) home and everything you send to/receive from the
-outside word goes across it.

doc/modules.adoc

@@ -0,0 +1 @@
+== Module options

doc/modules.rst

@@ -1,4 +0,0 @@
-Module options
-##############
-
-.. include:: modules-generated.inc.rst

doc/outputs.adoc

@@ -1,13 +1,12 @@
-Outputs
-#######
+== Outputs
 
-Liminix *outputs* are artefacts that can be installed somehow on a
-target device, or "installers" which run on the target device to
-perform the installation.
+Liminix _outputs_ are artefacts that can be installed somehow on a
+target device, or "installers" which run on the target device to perform
+the installation.
 
 There are different outputs because different target devices need
 different artefacts, or have different ways to get that artefact
-installed. The options available for a particular device are described in
-the section for that device.
+installed. The options available for a particular device are described
+in the section for that device.
 
-.. include:: outputs-generated.inc.rst
+include::outputs-generated.inc.adoc[]

doc/tutorial.adoc

@@ -0,0 +1,322 @@
+== Tutorial
+
+Liminix is very configurable, which can make it initially quite daunting
+- especially if you're learning Nix or Linux or networking concepts at
+the same time. In this section we build some "worked example" Liminix
+images to introduce the concepts. If you follow the examples exactly,
+they should work. If you change things as you go along, they may work
+differently or not at all, but the experience should be educational
+either way.
+
+=== Requirements
+
+You will need a reasonably powerful computer running Nix. Target devices
+for Liminix are unlikely to have the CPU power and disk space to be able
+to build it in situ, so the build process is based around
+"cross-compilation" from another computer. The build machine can be any
+reasonably powerful desktop/laptop/server PC running NixOS. Standalone
+Nixpkgs installations on other Linux distributions - or on MacOS, or
+even in a Docker container - also ought to work but are untested.
+
+=== Running in Qemu
+
+You can try out Liminix without even having a router to play with. Clone
+the Liminix git repository and change into its directory
+
+[source,console]
+----
+git clone https://gti.telent.net/dan/liminix
+cd liminix
+----
+
+Now build Liminix
+
+[source,console]
+----
+nix-build -I liminix-config=./examples/hello-from-qemu.nix \
+ --arg device "import ./devices/qemu" -A outputs.default
+----
+
+In this command `+liminix-config+` points to the desired software
+configuration (e.g. services, users, filesystem, secrets) and `+device+`
+describes the hardware (or emulated hardware) to run it on.
+`+outputs.default+` tells Liminix that we want the default image output
+for flashing to the device: for the Qemu "hardware" it's an alias for
+`+outputs.vmbuild+`, which creates a directory containing a root
+filesystem image and a kernel.
+
+[TIP]
+====
+The first time you run this it may take several hours, because it builds
+all of the dependencies including a full MIPS gcc and library toolchain.
+Once those intermediate build products are in the nix store, subsequent
+builds will be much faster - practically instant, if nothing has
+changed.
+====
+
+Now you can try it:
+
+[source,console]
+----
+./result/run.sh
+----
+
+This starts the Qemu emulator with a bunch of useful options, to run the
+Liminix configuration you just built. It connects the emulated device's
+serial console and the
+https://www.qemu.org/docs/master/system/monitor.html[QEMU monitor] to
+stdin/stdout.
+
+You should now see Linux boot messages and after a few seconds be
+presented with a root shell prompt. You can run commands to look at the
+filesystem, see what processes are running, view log messages (in
+:file:/run/log/current), etc. To kill the emulator, press ^P (Control P)
+then c to enter the "QEMU Monitor", then type `+quit+` at the `+(qemu)+`
+prompt.
+
+To see that it's running network services we need to connect to its
+emulated network. Start the machine again, if you had stopped it, and
+open up a second terminal on your build machine. We're going to run
+another virtual machine attached to the virtual network, which will
+request an IP address from our Liminix system and give you a shell you
+can run ssh from.
+
+We use https://www.system-rescue.org/[System Rescue] in tty mode (no
+graphical output) for this example, but if you have some other favourite
+Linux Live CD ISO - or, for that matter, any other OS image that QEMU
+can boot - adjust the command to suit.
+
+Download the System Rescue ISO:
+
+[source,console]
+----
+curl https://fastly-cdn.system-rescue.org/releases/10.01/systemrescue-10.01-amd64.iso -O
+----
+
+and run it
+
+[source,console]
+----
+nix-shell -p qemu --run " \
+qemu-system-x86_64 \
+-echr 16 \
+-m 1024 \
+-cdrom systemrescue-10.01-amd64.iso \
+-netdev socket,mcast=230.0.0.1:1235,localaddr=127.0.0.1,id=lan \
+-device virtio-net,disable-legacy=on,disable-modern=off,netdev=lan,mac=ba:ad:3d:ea:21:01 \
+-display none -serial mon:stdio"
+----
+
+System Rescue displays a boot menu at which you should select the
+"serial console" option, then after a few moments it boots to a root
+prompt. You can now try things out:
+
+* run `+ip a+` and see that it's been allocated an IP address in the
+range 10.3.0.0/16.
+* run `+ping 10.3.0.1+` to see that the Liminix VM responds
+* run `+ssh root@10.3.0.1+` to try logging into it.
+
+Congratulations! You have installed your first Liminix system - albeit
+it has no practical use and it's not even real. The next step is to try
+running it on hardware.
+
+=== Installing on hardware
+
+For the next example, we're going to install onto an actual hardware
+device. These steps have been tested using a GL.iNet GL-MT300A, which
+has been chosen for the purpose because it's cheap and easy to unbrick
+if necessary.
+
+[WARNING]
+====
+There is always a risk of rendering your device unbootable by flashing
+it with an image that doesn't work. The GL-MT300A has a builtin
+"debrick" procedure in the boot monitor and is also comparatively simple
+to attach serial cables to (soldering not required), so it is lower-risk
+than some devices. Using some other Liminix-supported MIPS hardware
+device also _ought_ to work here, but you accept the slightly greater
+bricking risk if it doesn't.
+
+See <<_supported_hardware>> for device support status.
+====
+
+You may want to read and inwardly digest the section on <<serial>>
+when you start working with Liminix on real hardware. You
+won't _need_ serial access for this example, assuming it works, but it
+allows you to see the boot monitor and kernel messages, and to login
+directly to the device if for some reason it doesn't bring its network
+up.
+
+Now we can build Liminix. Although we could use the same example
+configuration as we did for Qemu, you might not want to plug a DHCP
+server into your working LAN because it will compete with the real DHCP
+service. So we're going to use a different configuration with a DHCP
+client: this is `+examples/hello-from-mt300.nix+`
+
+It's instructive to compare the two configurations:
+
+[source,console]
+----
+diff -u examples/hello-from-qemu.nix examples/hello-from-mt300.nix
+----
+
+You'll see a new `+boot.tftp+` stanza which you can ignore,
+`+services.dns+` has been removed, and the static IP address allocation
+has been replaced by a `+dhcp.client+` service.
+
+[source,console]
+----
+nix-build -I liminix-config=./examples/hello-from-mt300.nix \
+ --arg device "import ./devices/gl-mt300a" -A outputs.default
+----
+
+[TIP]
+====
+The first time you run this it may take several hours. Again? Yes, even
+if you ran the previous example. Qemu is set up as a big-endian system
+whereas the MediaTek SoC on this device is little-endian - so it
+requires building all of the dependencies including an entirely
+different MIPS gcc and library toolchain to the other one.
+====
+
+This time in `+result/+` you will see a bunch of files. Most of them you
+can ignore for the moment, but `+result/firmware.bin+` is the firmware
+image you can flash.
+
+==== Flashing
+
+Again, there are a number of different ways you could do this: using
+TFTP with a serial cable, through the stock firmware's web UI, or using
+the https://docs.gl-inet.com/router/en/3/tutorials/debrick/[vendor's
+"debrick" process]. The last of these options has a lot to recommend it
+for a first attempt:
+
+* it works no matter what firmware is currently installed
+* it doesn't require plugging a router into the same network as your
+build system and potentially messing up your actual upstream
+* no need to open the device and add cables
+
+You can read detailed instructions on the vendor site, but the short
+version is:
+
+[arabic]
+. turn the device off
+. connect it by ethernet cable to a computer
+. configure the computer to have static ip address 192.168.1.10
+. while holding down the Reset button, turn the device on
+. after about five seconds you can release the Reset button
+. visit http://192.168.1.1/ using a web browser on the connected
+computer
+. click on "Browse" and choose `+result/firmware.bin+`
+. click on "Update firmware"
+. wait a minute or so while it updates.
+
+There's no feedback from the web interface when the flashing is
+finished, but what should happen is that the router reboots and starts
+running Liminix. Now you need to figure out what address it got from
+DHCP - e.g. by checking the DHCP server logs, or maybe by pinging
+`+hello.lan+` or something. Once you've found it on the network you can
+ping it and ssh to it just like you did the Qemu example, but this time
+for real.
+
+[WARNING]
+====
+Do not leave the default root password in place on any device exposed to
+the internet! Although it has no writable storage and no default route,
+a motivated attacker with some imagination could probably still do
+something awful using it.
+====
+
+Congratulations Part II! You have installed your first Liminix system on
+actual hardware - albeit that it _still_ has no practical use.
+
+Exercise for the reader: change the default password by editing
+`+examples/hello-from-mt300.nix+`, and then create and upload a new
+image that has it set to something less hopeless.
+
+=== Routing
+
+The third example `+examples/demo.nix+` is a fully-functional home "WiFi
+router" - although you will have to edit it a bit before it will
+actually work for you. Copy `+examples/demo.nix+` to `+my-router.nix+`
+(or other name of your choice) and open it in your favourite text
+editor. Everywhere that the text `+EDIT+` appears is either a place you
+probably want to change or a place you almost certainly need to change.
+
+There's a lot going on in this configuration:
+
+* it provides a wireless access point using the `+hostapd+` service: in
+this stanza you can change the ssid, the channel, the passphrase etc.
+* the wireless lan and wired lan are bridged together with the
+`+bridge+` service, so that your wired and wireless clients appear to be
+on the same network.
+
+[TIP]
+====
+If you were using a hardware device that provides both 2.4GHz and 5GHz
+wifi, you'd probably find that it has two wireless devices (often called
+wlan0 and wlan1). In Liminix we handle this by running two `+hostapd+`
+services, and adding both of them to the network bridge along with the
+wired lan. (You can see an example in `+examples/rotuer.nix+`)
+====
+
+* we use the combination DNS and DHCP daemon provided by the `+dnsmasq+`
+service, which you can configure
+* the upstream network is "PPP over Ethernet", provided by the `+pppoe+`
+service. Assuming that your ISP uses this standard, they will have
+provided you with a PPP username and password (sometimes this will be
+listed as "PAP" or "CHAP") which you can edit into the configuration
+* this example supports the
+newfootnote:[https://datatracker.ietf.org/doc/html/rfc1883[RFC1883
+Internet Protocol&#44; Version 6] was published in 1995, so only "new"
+when Bill Clinton was US President] Internet Protocol v6 as well as
+traditional IPv4. Configuring IPv6 seems to vary from one ISP to the
+next: this example expects them to be providing IP address allocation
+and "prefix delegation" using DHCP6.
+
+Build it using the same method as the previous example
+
+[source,console]
+----
+nix-build -I liminix-config=./my-router.nix \
+ --arg device "import ./devices/gl-mt300a" -A outputs.default
+----
+
+and then you can flash it to the device.
+
+==== Bonus: in-place updates
+
+This configuration uses a writable filesystem (see the line
+`+rootfsType = "jffs2"+`), which means that once you've flashed it for
+the first time, you can make further updates over SSH onto the running
+router. To try this, make a small change (I'd suggest changing the
+hostname) and then run
+
+[source,console]
+----
+nix-build  -I liminix-config=./my-router.nix \
+  --arg device "import ./devices/gl-ar750" \
+  -A outputs.systemConfiguration && \
+result/install.sh root@address-of-the-device 
+----
+
+(This requires the device to be network-accessible from your build
+machine, which for a test/demo system might involve a second network
+device in your build system - USB ethernet adapters are cheap - or a bit
+of messing around unplugging cables.)
+
+For more information about in-place-updates, see the manual section
+`+Rebuilding the system+`.
+
+=== Final thoughts
+
+* These are demonstration configs for pedagogical purposes. If you'd
+like to see some more realistic uses of Liminix,
+`+examples/rotuer,arhcive,extneder.nix+` are based on some actual real
+hosts in my home network.
+* The technique used here for flashing was chosen mostly because it
+doesn't need much infrastructure/tooling, but it is a bit of a faff
+(requires physical access, vendor specific). There are slicker ways to
+do it that need a bit more setup - we'll talk about that later as well.
+
+*Footnotes*

doc/tutorial.rst

@@ -1,327 +0,0 @@
-Tutorial
-########
-
-Liminix is very configurable, which can make it initially quite
-daunting - especially if you're learning Nix or Linux or networking
-concepts at the same time. In this section we build some "worked
-example" Liminix images to introduce the concepts. If you follow the
-examples exactly, they should work. If you change things as you go
-along, they may work differently or not at all, but the experience
-should be educational either way.
-
-
-Requirements
-************
-
-You will need a reasonably powerful computer running Nix.  Target
-devices for Liminix are unlikely to have the CPU power and disk space
-to be able to build it in situ, so the build process is based around
-"cross-compilation" from another computer. The build machine can be
-any reasonably powerful desktop/laptop/server PC running NixOS.
-Standalone Nixpkgs installations on other Linux distributions - or on
-MacOS, or even in a Docker container - also ought to work but are
-untested.
-
-
-Running in Qemu
-***************
-
-You can try out Liminix without even having a router to play with.
-Clone the Liminix git repository and change into its directory
-
-
-.. code-block:: console
-
-    git clone https://gti.telent.net/dan/liminix
-    cd liminix
-
-Now build Liminix
-
-.. code-block:: console
-
-    nix-build -I liminix-config=./examples/hello-from-qemu.nix \
-     --arg device "import ./devices/qemu" -A outputs.default
-
-In this command ``liminix-config`` points to the desired software
-configuration (e.g. services, users, filesystem, secrets) and
-``device`` describes the hardware (or emulated hardware) to run it on.
-``outputs.default`` tells Liminix that we want the default image
-output for flashing to the device: for the Qemu "hardware" it's an
-alias for ``outputs.vmbuild``, which creates a directory containing a
-root filesystem image and a kernel.
-
-.. tip:: The first time you run this it may take several hours,
-         because it builds all of the dependencies including a full
-         MIPS gcc and library toolchain. Once those intermediate build
-         products are in the nix store, subsequent builds will be much
-         faster - practically instant, if nothing has changed.
-
-Now you can try it:
-
-.. code-block:: console
-
-    ./result/run.sh
-
-This starts the Qemu emulator with a bunch of useful options, to run
-the Liminix configuration you just built.  It connects the emulated
-device's serial console and the `QEMU monitor
-<https://www.qemu.org/docs/master/system/monitor.html>`_ to
-stdin/stdout.
-
-You should now see Linux boot messages and after a few seconds be
-presented with a root shell prompt.  You can run commands to look at
-the filesystem, see what processes are running, view log messages (in
-:file:/run/log/current), etc. To kill the emulator, press ^P
-(Control P) then c to enter the "QEMU Monitor", then type ``quit`` at
-the ``(qemu)`` prompt.
-
-To see that it's running network services we need to connect to its
-emulated network. Start the machine again, if you had stopped it, and
-open up a second terminal on your build machine. We're going to run
-another virtual machine attached to the virtual network, which will
-request an IP address from our Liminix system and give you a shell you
-can run ssh from.
-
-We use `System Rescue <https://www.system-rescue.org/>`_ in tty
-mode (no graphical output) for this example, but if you have some
-other favourite Linux Live CD ISO - or, for that matter, any other OS
-image that QEMU can boot - adjust the command to suit.
-
-Download the System Rescue ISO:
-
-.. code-block:: console
-
-    curl https://fastly-cdn.system-rescue.org/releases/10.01/systemrescue-10.01-amd64.iso -O
-
-and run it
-
-.. code-block:: console
-
-    nix-shell -p qemu --run " \
-    qemu-system-x86_64 \
-	-echr 16 \
-	-m 1024 \
-	-cdrom systemrescue-10.01-amd64.iso \
-	-netdev socket,mcast=230.0.0.1:1235,localaddr=127.0.0.1,id=lan \
-	-device virtio-net,disable-legacy=on,disable-modern=off,netdev=lan,mac=ba:ad:3d:ea:21:01 \
-	-display none -serial mon:stdio"
-
-System Rescue displays a boot menu at which you should select the
-"serial console" option, then after a few moments it boots to a root
-prompt. You can now try things out:
-
-* run :command:`ip a` and see that it's been allocated an IP address in the range 10.3.0.0/16.
-
-* run :command:`ping 10.3.0.1` to see that the Liminix VM responds
-
-* run :command:`ssh root@10.3.0.1` to try logging into it.
-
-Congratulations! You have installed your first Liminix system - albeit
-it has no practical use and it's not even real. The next step is to try
-running it on hardware.
-
-Installing on hardware
-**********************
-
-For the next example, we're going to install onto an actual hardware
-device.  These steps have been tested using a GL.iNet GL-MT300A, which
-has been chosen for the purpose because it's cheap and easy to
-unbrick if necessary.
-
-.. warning:: There is always a risk of rendering your device
-	     unbootable by flashing it with an image that doesn't
-	     work. The GL-MT300A has a builtin "debrick" procedure in
-	     the boot monitor and is also comparatively simple to
-	     attach serial cables to (soldering not required), so it
-	     is lower-risk than some devices.  Using some other
-	     Liminix-supported MIPS hardware device also *ought* to
-	     work here, but you accept the slightly greater bricking
-	     risk if it doesn't.
-
-See :doc:`hardware` for device support status.
-
-You may want to read and inwardly digest the Develoment Manual section
-:ref:`serial` when you start working with Liminix on real hardware. You
-won't *need* serial access for this example, assuming it works, but it
-allows you
-to see the boot monitor and kernel messages, and to login directly to
-the device if for some reason it doesn't bring its network up.
-
-Now we can build Liminix. Although we could use the same example
-configuration as we did for Qemu, you might not want to plug a DHCP
-server into your working LAN because it will compete with the real
-DHCP service. So we're going to use a different configuration with a
-DHCP client: this is :file:`examples/hello-from-mt300.nix`
-
-It's instructive to compare the two configurations:
-
-.. code-block:: console
-
-    diff -u examples/hello-from-qemu.nix examples/hello-from-mt300.nix
-
-You'll see a new ``boot.tftp`` stanza which you can ignore,
-``services.dns`` has been removed, and the static IP address allocation
-has been replaced by a ``dhcp.client`` service.
-
-.. code-block:: console
-
-    nix-build -I liminix-config=./examples/hello-from-mt300.nix \
-     --arg device "import ./devices/gl-mt300a" -A outputs.default
-
-.. tip:: The first time you run this it may take several hours.
-         Again? Yes, even if you ran the previous example. Qemu is
-         set up as a big-endian system whereas the MediaTek SoC
-         on this device is little-endian - so it requires building
-         all of the dependencies including an entirely different
-         MIPS gcc and library toolchain to the other one.
-
-This time in :file:`result/` you will see a bunch of files. Most of
-them you can ignore for the moment, but :file:`result/firmware.bin` is
-the firmware image you can flash.
-
-
-Flashing
-========
-
-Again, there are a number of different ways you could do this: using
-TFTP with a serial cable, through the stock firmware's web UI, or
-using the `vendor's "debrick" process
-<https://docs.gl-inet.com/router/en/3/tutorials/debrick/>`_. The last
-of these options has a lot to recommend it for a first attempt:
-
-* it works no matter what firmware is currently installed
-
-* it doesn't require plugging a router into the same network as your
-  build system and potentially messing up your actual upstream
-
-* no need to open the device and add cables
-
-You can read detailed instructions on the vendor site, but the short version is:
-
-1. turn the device off
-2. connect it by ethernet cable to a computer
-3. configure the computer to have static ip address 192.168.1.10
-4. while holding down the Reset button, turn the device on
-5. after about five seconds you can release the Reset button
-6. visit http://192.168.1.1/ using a web browser on the connected computer
-7. click on "Browse" and choose :file:`result/firmware.bin`
-8. click on "Update firmware"
-9. wait a minute or so while it updates.
-
-There's no feedback from the web interface when the flashing is
-finished, but what should happen is that the router reboots and
-starts running Liminix. Now you need to figure out what address it got
-from DHCP - e.g. by checking the DHCP server logs, or maybe by pinging
-``hello.lan`` or something. Once you've found it on the
-network you can ping it and ssh to it just like you did the Qemu
-example, but this time for real.
-
-.. warning:: Do not leave the default root password in place on any
-             device exposed to the internet!  Although it has no
-             writable storage and no default route, a motivated attacker
-	     with some imagination could probably still do something
-	     awful using it.
-
-Congratulations Part II! You have installed your first Liminix system on actual hardware - albeit that it *still* has no practical use.
-
-Exercise for the reader: change the default password by editing
-:file:`examples/hello-from-mt300.nix`, and then create and upload a
-new image that has it set to something less hopeless.
-
-Routing
-*******
-
-The third example :file:`examples/demo.nix` is a fully-functional home
-"WiFi router" - although you will have to edit it a bit before it will
-actually work for you. Copy :file:`examples/demo.nix` to
-:file:`my-router.nix` (or other name of your choice) and open it in
-your favourite text editor. Everywhere that the text :code:`EDIT`
-appears is either a place you probably want to change or a place you
-almost certainly need to change.
-
-There's a lot going on in this configuration:
-
-* it provides a wireless access point using the :code:`hostapd`
-  service: in this stanza you can change the ssid, the channel,
-  the passphrase etc.
-
-* the wireless lan and wired lan are bridged together with the
-  :code:`bridge` service, so that your wired and wireless clients appear
-  to be on the same network.
-
-.. tip:: If you were using a hardware device that provides both 2.4GHz
-	  and 5GHz wifi, you'd probably find that it has two wireless
-	  devices (often called wlan0 and wlan1). In Liminix we handle
-	  this by running two :code:`hostapd` services, and adding
-	  both of them to the network bridge along with the wired lan.
-	  (You can see an example in :file:`examples/rotuer.nix`)
-
-* we use the combination DNS and DHCP daemon provided by the
-  :code:`dnsmasq` service, which you can configure
-
-* the upstream network is "PPP over Ethernet", provided by the
-  :code:`pppoe` service. Assuming that your ISP uses this standard,
-  they will have provided you with a PPP username and password
-  (sometimes this will be listed as "PAP" or "CHAP") which you can edit
-  into the configuration
-
-* this example supports the new [#ipv6]_ Internet Protocol v6
-  as well as traditional IPv4. Configuring IPv6 seems to
-  vary from one ISP to the next: this example expects them
-  to be providing IP address allocation and "prefix delegation"
-  using DHCP6.
-
-Build it using the same method as the previous example
-
-
-.. code-block:: console
-
-    nix-build -I liminix-config=./my-router.nix \
-     --arg device "import ./devices/gl-mt300a" -A outputs.default
-
-and then you can flash it to the device.
-
-
-Bonus: in-place updates
-=======================
-
-This configuration uses a writable filesystem (see the line
-:code:`rootfsType = "jffs2"`), which means that once you've flashed it
-for the first time, you can make further updates over SSH onto the
-running router. To try this, make a small change (I'd suggest changing
-the hostname) and then run
-
-.. code-block:: console
-
-    nix-build  -I liminix-config=./my-router.nix \
-      --arg device "import ./devices/gl-ar750" \
-      -A outputs.systemConfiguration && \
-    result/install.sh root@address-of-the-device 
-
-(This requires the device to be network-accessible from your build
-machine, which for a test/demo system might involve a second network
-device in your build system - USB ethernet adapters are cheap - or
-a bit of messing around unplugging cables.)
-
-For more information about in-place-updates, see the manual section :ref:`Rebuilding the system`.
-
-
-Final thoughts
-**************
-
-* These are demonstration configs for pedagogical purposes. If you'd
-  like to see some more realistic uses of Liminix,
-  :file:`examples/rotuer,arhcive,extneder.nix` are based on some
-  actual real hosts in my home network.
-
-* The technique used here for flashing was chosen mostly because it
-  doesn't need much infrastructure/tooling, but it is a bit of a faff
-  (requires physical access, vendor specific). There are slicker ways
-  to do it that need a bit more setup - we'll talk about that later as
-  well.
-
-
-
-.. rubric:: Footnotes
-
-.. [#ipv6] `RFC1883 Internet Protocol, Version 6 <https://datatracker.ietf.org/doc/html/rfc1883>`_ was published in 1995, so only "new" when Bill Clinton was US President

examples/rotuer.nix

@@ -71,6 +71,7 @@ rec {
         interface = config.hardware.networkInterfaces.wan;
         username = secrets.l2tp.name;
         password = secrets.l2tp.password;
+        bandwidth = 70 * 1000 * 1000;
       };
       # once the wan has ipv4 connnectivity, should we run dhcp6
       # client to potentially get an address range ("prefix

modules/dhcp6c/acquire-delegated-prefix.fnl

@@ -25,6 +25,7 @@
 (fn run []
   (let [[state-directory lan-device] arg
         dir (svc.open state-directory)]
+    (update-prefixes lan-device [] (or (dir:output "prefix") []) system)
     (accumulate [addresses []
                  v (dir:events)]
       (update-prefixes lan-device addresses (or (v:output "prefix") []) system))))

modules/dhcp6c/acquire-wan-address.fnl

@@ -25,6 +25,7 @@
 (fn run []
   (let [[state-directory wan-device] arg
         dir (svc.open state-directory)]
+    (update-addresses wan-device [] (or (dir:output "address") []) system)
     (accumulate [addresses []
                  v (dir:events)]
       (update-addresses wan-device addresses (or (v:output "address") []) system))))

modules/dhcp6c/address.nix

@@ -10,7 +10,7 @@ let
 in
 longrun {
   inherit name;
-  run = "${script} $SERVICE_OUTPUTS/${client.name} $(output ${interface} ifname)";
+  run = "${script} ${client} $(output ${interface} ifname)";
   dependencies = [
     client
     interface

modules/dhcp6c/client.nix

@@ -2,19 +2,29 @@
   liminix,
   odhcp6c,
   odhcp-script,
+  svc
 }:
 { interface }:
 let
   inherit (liminix.services) longrun;
+  inherit (liminix) outputRef;
   name = "dhcp6c.${interface.name}";
-in
-longrun {
-  inherit name;
-  notification-fd = 10;
-  run = ''
-    export SERVICE_STATE=$SERVICE_OUTPUTS/${name}
-    ${odhcp6c}/bin/odhcp6c -s ${odhcp-script} -e -v -p /run/${name}.pid -P0 $(output ${interface} ifname)
-    )
-  '';
-  dependencies = [ interface ];
+  service =
+    longrun {
+      inherit name;
+      notification-fd = 10;
+      run = ''
+        export SERVICE_STATE=$SERVICE_OUTPUTS/${name}
+        ifname=$(output ${interface} ifname)
+        test -n "$ifname" && ${odhcp6c}/bin/odhcp6c -s ${odhcp-script} -e -v -p /run/${name}.pid -P0 $ifname
+        )
+      '';
+      dependencies = [ interface ];
+    };
+in svc.secrets.subscriber.build {
+  # if the ppp service gets restarted, the interface may be different and
+  # we will have to restart dhcp on the new one
+  watch = [ (outputRef interface "ifindex") ];
+  action = "restart";
+  inherit service;
 }

modules/dhcp6c/prefix.nix

@@ -10,7 +10,7 @@ let
 in
 longrun {
   inherit name;
-  run = "${script} $SERVICE_OUTPUTS/${client.name} $(output ${interface} ifname)";
+  run = "${script} ${client} $(output ${interface} ifname)";
   dependencies = [
     client
     interface

modules/firewall/default.nix

@@ -37,6 +37,7 @@ let
       "nft_fib"
       "nft_fib_ipv4"
       "nft_fib_ipv6"
+      "nft_limit"
       "nft_log"
       "nft_masq"
       "nft_nat"
@@ -114,6 +115,7 @@ in
       NFT_CT = "m";
       NFT_FIB_IPV4 = "m";
       NFT_FIB_IPV6 = "m";
+      NFT_LIMIT = "m";
       NFT_LOG = "m";
       NFT_MASQ = "m";
       NFT_NAT = "m";

modules/firewall/service.nix

@@ -3,13 +3,9 @@
   lib,
   firewallgen,
   nftables,
-  writeFennel,
-  anoia,
   svc,
   lua,
   output-template,
-  lualinux,
-  linotify,
 }:
 {
   rules,
@@ -20,7 +16,6 @@ let
   inherit (liminix.services) longrun;
   inherit (lib.attrsets) mapAttrs' nameValuePair mapAttrsToList;
   inherit (lib.strings) concatStringsSep;
-  inherit (lib.lists) flatten;
   inherit (builtins) concatLists toJSON attrValues;
   inherit (liminix) outputRef;
   mkSet =
@@ -44,12 +39,63 @@ let
          end
       }}
       '';
-  };
+    };
+
+  rateHook6 =
+    let rules =
+          map
+            (x: ''
+               {{;
+                local s = "${x}";
+                local n = output(s, "ifname");
+                local bw = output(s, "bandwidth");
+                if n and bw then
+                  return "meta l4proto icmpv6 iifname ".. n .. " limit rate over " .. (math.floor (tonumber(bw) / 8 / 20)) .. " bytes/second drop"
+                else
+                  return "# " .. (n or "not n") .. " " .. (bw or "not bw")
+                end
+               }}
+             '')
+            (concatLists (builtins.attrValues zones));
+    in {
+      type = "filter"; family = "ip6";
+      hook = "input"; priority = "-1"; policy = "accept";
+      inherit rules;
+    };
+
+  rateHook4 =
+    let rules =
+          map
+            (x: ''
+               {{;
+                local s = "${x}";
+                local n = output(s, "ifname");
+                local bw = output(s, "bandwidth");
+                if n and bw then
+                  return "meta l4proto icmp iifname ".. n .. " limit rate over " .. (math.floor (tonumber(bw) / 8 / 20)) .. " bytes/second drop"
+                else
+                  return "# " .. (n or "not n") .. " " .. (bw or "not bw")
+                end
+               }}
+             '')
+            (concatLists (builtins.attrValues zones));
+    in {
+      type = "filter"; family = "ip";
+      hook = "input"; priority = "-1"; policy = "accept";
+      inherit rules;
+    };
+
   sets = (mapAttrs' (n: _: mkSet "ip" n) zones) //
          (mapAttrs' (n: _: mkSet "ip6" n) zones);
-  allRules = lib.recursiveUpdate extraRules (lib.recursiveUpdate sets rules);
+  allRules =
+    {
+      icmp6-ratehook = rateHook6;
+      icmp4-ratehook = rateHook4;
+    } //
+    (lib.recursiveUpdate
+      extraRules
+      (lib.recursiveUpdate sets rules));
   script = firewallgen "firewall1.nft" allRules;
-  watchArg = z: intfs: map (i: "${z}:${i}/.outputs") intfs;
   name = "firewall";
   service = longrun {
     inherit name;

modules/ppp/common.nix

@@ -13,6 +13,7 @@
   username,
   password,
   lcpEcho,
+  bandwidth,
   ppp-options,
   dependencies ? [ ],
 }:
@@ -35,18 +36,21 @@ let
     echo $3 > speed
     echo $4 > address
     echo $5 > peer-address
+    cat /sys/class/net/$1/ifindex > ifindex
     set +o nounset
     if test -n "''${DNS1}" ;then echo ''${DNS1} > ns1 ; fi
     if test -n "''${DNS2}" ;then echo ''${DNS2} > ns2 ; fi
-    test -e ipv6-address && echo >/proc/self/fd/10
+    touch ip-up
+    test -e ipv6-up && echo >/proc/self/fd/10
   '';
   ip6-up = writeAshScript "ip6-up" { } ''
     exec >&5 2>&5
     . ${serviceFns} 
     in_outputs ${name}
-    echo $4 > ipv6-address
     echo $5 > ipv6-peer-address
-    test -e ifname && echo >/proc/self/fd/10
+    echo $4 > ipv6-address
+    touch ipv6-up
+    test -e ip-up && echo >/proc/self/fd/10
   '';
   literal_or_output =
     let
@@ -115,6 +119,7 @@ let
       ${command}
     '';
     notification-fd = 10;
+    properties.bandwidth = bandwidth;
     timeout-up =
       if lcpEcho.failure != null then (10 + lcpEcho.failure * lcpEcho.interval) * 1000 else 60 * 1000;
     inherit dependencies;

modules/ppp/default.nix

@@ -56,6 +56,11 @@ in
         default = null;
         description = "password";
       };
+      bandwidth = mkOption {
+        type = types.nullOr (types.int);
+        default = null;
+        description = "approximate bandwidth in bytes/second. Used to calculate rate limits for ICMP";
+      };
       lcpEcho = {
         adaptive = mkOption {
           description = "send LCP echo-request frames only if no traffic was received from the peer since the last echo-request was sent";
@@ -127,6 +132,16 @@ in
         description = "options supplied on ppp command line";
       };
     };
+
+    # rp-pppoe attempts to drop privs by switching to user "nobody"
+    users.nobody = {
+      uid = 65534;
+      gid = 65534;
+      gecos = "Captain Nemo";
+      dir = "/run/";
+      shell = "/bin/false";
+    };
+
     kernel = {
       config = {
         PPP = "y";

modules/ppp/l2tp.nix

@@ -13,6 +13,7 @@
   lns,
   ppp-options,
   lcpEcho,
+  bandwidth,
   username,
   password,
   debug,
@@ -40,6 +41,7 @@ common {
     username
     password
     lcpEcho
+    bandwidth
     ppp-options
     ;
   command = ''

modules/ppp/pppoe.nix

@@ -13,6 +13,7 @@
   interface,
   ppp-options,
   lcpEcho,
+  bandwidth,
   username,
   password,
   debug,
@@ -31,6 +32,7 @@ common {
     username
     password
     lcpEcho
+    bandwidth
     ppp-options
     ;
   command = ''

modules/secrets/subscriber.nix

@@ -5,6 +5,7 @@
   s6,
   s6-rc,
   watch-outputs,
+  s6-rc-up-tree
 }:
 {
   watch,
@@ -47,7 +48,7 @@ let
         echo waiting for $dir
         if test -e $dir/notification-fd; then flag="-U"; else flag="-u"; fi
         ${s6}/bin/s6-svwait $flag /run/service/${name} || exit
-        PATH=${s6-rc}/bin:${s6}/bin:$PATH
+        PATH=${s6-rc}/bin:${s6}/bin:${s6-rc-up-tree}/bin:$PATH
         ${watch-outputs}/bin/watch-outputs ${restart-flag} ${name} ${refs}
       '';
     };

overlay.nix

@@ -72,6 +72,8 @@ extraPkgs
       chrony' = prev.chrony.overrideAttrs (o: {
         configureFlags = [
           "--chronyvardir=$(out)/var/lib/chrony"
+          "--sbindir=$(out)/bin"
+          "--chronyrundir=/run/chrony"
           "--disable-readline"
           "--disable-editline"
         ];
@@ -81,6 +83,7 @@ extraPkgs
       gnutls = null;
       libedit = null;
       libseccomp = null;
+      libcap = null;
       # should texinfo be in nativeBuildInputs instead of
       # buildInputs?
       texinfo = null;
@@ -141,20 +144,22 @@ extraPkgs
   dropbear = crossOnly prev.dropbear (
     d:
     d.overrideAttrs (o: rec {
+      # nixpkgs 25.05 contains newer dropbear (2025.87) than this,
+      # we can drop this override when that's ready
       version = "2024.85";
       src = final.fetchurl {
         url = "https://matt.ucc.asn.au/dropbear/releases/dropbear-${version}.tar.bz2";
         sha256 = "sha256-hrA2xDOmnYnOUeuuM11lxHc4zPkNE+XrD+qDLlVtpQI=";
       };
       patches =
-        # need to update nixpkgs patch for new version of dropbear
+        # in 24.11 we need to update nixpkgs patch for new version of dropbear
         let
           passPath = final.runCommand "pass-path" { } ''
             sed < ${builtins.head o.patches} -e 's,svr-chansession.c,src/svr-chansession.c,g' > $out
           '';
         in
         [
-          passPath
+          (if (lib.versionOlder o.version "2024") then passPath else (builtins.head o.patches))
           ./pkgs/dropbear/add-authkeyfile-option.patch
         ];
       postPatch = ''
@@ -299,10 +304,10 @@ extraPkgs
             hash = "sha256-jOsGka7xLkJznb9M90v5TsJraXXTAj84lcphcSxjYLU=";
           })
         ];
+        buildInputs = o.buildInputs ++ [ final.libslirp ];
       });
       overrides =
         {
-          nixosTestRunner = true;
           hostCpuTargets = map (f: "${f}-softmmu") [
             "arm"
             "aarch64"
@@ -320,6 +325,10 @@ extraPkgs
         }
         // lib.optionalAttrs (lib.versionOlder lib.version "24.10") {
           texinfo = null;
+          nixosTestRunner = true;
+        }
+        // lib.optionalAttrs (lib.versionAtLeast lib.version "25.04") {
+          minimal = true;
         };
     in
     q.override overrides;

pkgs/anoia/Makefile

@@ -1,4 +1,5 @@
 servicedir:=$(shell mktemp -d)
+outputdir:=$(servicedir)/.outputs
 
 default: fs.lua init.lua nl.lua svc.lua process.lua net/constants.lua
 
@@ -8,13 +9,15 @@ check:
 	ln -s . anoia
 	fennel ./run-tests.fnl $(CHECK)
 	fennel test.fnl
+	mkdir -p $(outputdir)
 	fennel test-svc.fnl $(servicedir)
-	test -f $(servicedir)/fish
-	test "`cat $(servicedir)/fish`" = "food"
-	test -d $(servicedir)/nested/path
-	test "`cat $(servicedir)/nested/path/name`" = "value"
-	test "`cat $(servicedir)/nested/path/complex/attribute`" = "val"
-	test "`cat $(servicedir)/nested/path/complex/other`" = "42"
+	find $(outputdir) -ls
+	test -f $(outputdir)/fish
+	test "`cat $(outputdir)/fish`" = "food"
+	test -d $(outputdir)/nested/path
+	test "`cat $(outputdir)/nested/path/name`" = "value"
+	test "`cat $(outputdir)/nested/path/complex/attribute`" = "val"
+	test "`cat $(outputdir)/nested/path/complex/other`" = "42"
 
 
 net/constants.lua: net/constants.c

pkgs/anoia/example-output/.outputs/array/1

@@ -0,0 +1 @@
+cat

pkgs/anoia/example-output/.outputs/array/2

@@ -0,0 +1 @@
+dog

pkgs/anoia/example-output/.outputs/array/3

@@ -0,0 +1 @@
+cow

pkgs/anoia/example-output/.outputs/array/4

@@ -0,0 +1 @@
+sheep

pkgs/anoia/init.fnl

@@ -25,8 +25,27 @@
 (fn basename [path]
   (string.match path ".*/([^/]-)$"))
 
+
 (fn dirname [path]
-  (string.match path "(.*)/[^/]-$"))
+  (let [stripped (string.match path "(.-)/*$")]
+    (pick-values
+     1
+     (if (not path) "."
+         (= path "") "."
+         (not stripped) "."
+         (= stripped "") "/"
+         (string.match stripped ".+/.-") (stripped:gsub "(.*)(/.*)" "%1")
+         (string.match stripped "/") "/"
+         "."))))
+
+(define-tests
+  ;; these are examples from dirname(3)
+  (expect= (dirname "/usr/lib") "/usr")
+  (expect= (dirname "/usr/") "/")
+  (expect= (dirname "usr") ".")
+  (expect= (dirname "/") "/")
+  (expect= (dirname ".") ".")
+  (expect= (dirname "..") "."))
 
 (fn append-path [dirname filename]
   (let [base (or (string.match dirname "(.*)/$") dirname)

pkgs/anoia/svc.fnl

@@ -1,22 +1,56 @@
 (local inotify (require :inotify))
-(local { : file-exists? : dirname } (require :anoia))
+(local { : file-exists? : dirname : append-path } (require :anoia))
 (local { : file-type : dir : mktree &as fs } (require :anoia.fs))
+(local { : readlink } (require :lualinux))
 
 (fn read-line [name]
   (with-open [f (assert (io.open name :r) (.. "can't open file " name))]
     (f:read "*l")))
 
+
+;; If the directory is missing, we cannot add a inotify watch
+;; for it.  We need a watch that opens the parent if the pathname is missing,
+;; and it needs to be the resolved path not the syntactic parent.
+
+;; If the directory is not missing, then having a watch on the
+;; parent may result in extra wakeups but should only affect
+;; efficiency not correctness
+
+;; Each time the directory may have been added we need to update
+;; watches. If it's been removed, the watch will be removed
+;; automatically. inotify_add_watch when it already exists will modify
+;; instead of making a new one, so we can treat it as idempotent
+
+
+(fn resolve-link [pathname]
+  (if (= (file-type pathname) :link)
+      (readlink pathname)
+      pathname))
+
 (fn watch-fsevents [directory-name]
-  (let [handle (inotify.init)]
-    (handle:addwatch directory-name
-                     inotify.IN_CREATE
-                     inotify.IN_MOVE
-                     inotify.IN_DELETE
-                     inotify.IN_DELETE_SELF
-                     inotify.IN_MOVED_FROM
-                     inotify.IN_MOVED_TO
-                     inotify.IN_CLOSE_WRITE)
-    handle))
+  (let [handle (inotify.init)
+        parent-name (dirname (resolve-link directory-name))
+        refresh (fn []
+                  (handle:addwatch directory-name
+                                   inotify.IN_CREATE
+                                   inotify.IN_MOVE
+                                   inotify.IN_DELETE
+                                   inotify.IN_DELETE_SELF
+                                   inotify.IN_MOVED_FROM
+                                   inotify.IN_MOVED_TO
+                                   inotify.IN_CLOSE_WRITE)
+                  (handle:addwatch parent-name
+                                   inotify.IN_CREATE
+                                   inotify.IN_DELETE))]
+    ;; if you are using poll() to check for events on this
+    ;; watcher and on other events at the same time, be sure
+    ;; to call fileno each time around the loop instead
+    ;; of only once
+    {
+     :fileno #(do (refresh) (handle:fileno))
+     :wait #(do (refresh) (handle:read))
+     :close #(handle:close)
+     }))
 
 (fn write-value [pathname value]
   (mktree (dirname pathname))
@@ -25,7 +59,7 @@
     (with-open [f (assert (io.open pathname :w) (.. "can't open " pathname))]
       (f:write value))
     "table" (each [k v (pairs value)]
-              (write-value (.. pathname "/" k) v))))
+              (write-value (append-path pathname k) v))))
 
 (fn read-value [pathname]
   (case (file-type pathname)
@@ -33,7 +67,7 @@
     :directory
     (collect [f (fs.dir pathname)]
       (when (not (or (= f ".") (= f "..")))
-        (values f (read-value ( .. pathname "/" f)))))
+        (values f (read-value (append-path pathname f)))))
     :file
     (read-line pathname)
     :link
@@ -49,18 +83,26 @@
       (self:wait))))
 
 (fn open [directory]
-  (let [watcher (watch-fsevents directory)
-        has-file? (fn [filename] (file-exists? (.. directory "/" filename)))]
+  (let [outputs-dir (append-path directory ".outputs")
+        has-file? #(file-exists? (append-path directory $1))
+        watcher (watch-fsevents outputs-dir)
+        properties-dir (append-path directory ".properties")]
     {
-     :wait #(watcher:read)
      :ready? (fn [self]
-               (and (has-file? "state") (not (has-file? ".lock"))))
+               (and (has-file? ".outputs/state")
+                    (not (has-file? ".outputs/.lock"))))
+     :property (fn [_ filename]
+                 (read-value (append-path properties-dir filename)))
      :output (fn [_ filename new-value]
                (if new-value
-                   (write-value (.. directory "/" filename) new-value)
-                   (read-value (.. directory "/" filename))))
+                   (write-value (append-path outputs-dir filename) new-value)
+                   (or
+                    (read-value (append-path outputs-dir filename))
+                    (read-value (append-path properties-dir filename)))))
+     :wait #(watcher:wait)
      :close #(watcher:close)
      :fileno #(watcher:fileno)
+     : directory
      : events
      }))
 

pkgs/firewallgen/default.nix

@@ -13,8 +13,8 @@ let
     optionalString
     ;
   inherit (lib.lists) groupBy;
-  inherit (lib.attrsets) mapAttrsToList;
-  inherit (builtins) map head tail;
+  inherit (lib.attrsets) attrsToList mapAttrsToList;
+  inherit (builtins) elemAt map head tail toString;
 
   indentLines =
     offset: lines:
@@ -68,6 +68,25 @@ let
       }
     '';
 
+  domap =
+    {
+      name,
+      type,
+      elements ? [ ],
+      extraText ? null,
+      ...
+    }:
+      let
+        colonize = v:
+          let  ty = elemAt (attrsToList v) 0; in "${ty.name}: ${ty.value}";
+      in ''
+        map ${name}  {
+          type ${colonize type}
+          ${if elements != [ ] then "elements = { ${concatStringsSep ", " (mapAttrsToList (k: v : "${k}: ${toString v}") elements)} }" else ""}
+          ${optionalString (extraText != null) extraText}
+        }
+      '';
+
   dochainorset =
     {
       kind ? "chain",
@@ -76,6 +95,7 @@ let
     {
       chain = dochain;
       set = doset;
+      map = domap;
     }
     .${kind}
       params;

pkgs/firewallgen/test-rules-min.nix

@@ -151,6 +151,18 @@ in
       "eth0"
       "eth1"
     ];
-
   };
+
+  map-intf-limits-ip6 = {
+    name = "intf-limits";
+    kind = "map";
+    family = "ip6";
+    type = { ifname = "bytes"; };
+    elements = {
+      # XXX keys need to be generated from interface outputs
+      ppp0 = builtins.floor (70*1000*1000 * 0.05); # 5% of 70MB fttp connection
+      lan = builtins.floor (1000*1000*1000 * 0.05); # GB ethernet
+    };
+  };
+
 }

pkgs/liminix-tools/services/builder.sh

@@ -1,5 +1,15 @@
 source $stdenv/setup
 mkdir -p $out/${name}
+
+writepath(){
+    mkdir -p $(dirname $1)
+    if test -n "$2" ; then ( echo $2 > $1 ) ;fi
+}
+if test -n "$propertiesText"; then
+    mkdir $out/.properties
+    ( cd $out/.properties; eval "$propertiesText" )
+fi
+
 echo $serviceType > $out/${name}/type
 mkdir -p $out/${name}/dependencies.d
 echo $buildInputs > $out/buildInputs

pkgs/liminix-tools/services/default.nix

@@ -8,6 +8,8 @@
 let
   prefix = "/run/services/outputs";
   output = service: name: "${prefix}/${service.name}/${name}";
+  inherit (lib.attrsets) mapAttrsRecursive collect;
+  inherit (lib.strings) concatStringsSep;
   serviceScript = commands: ''
     #!/bin/sh
     exec 2>&1
@@ -38,6 +40,7 @@ let
       buildInputs ? [ ],
       restart-on-upgrade ? false,
       controller ? null,
+      properties ? {}
     }:
     stdenvNoCC.mkDerivation {
       # we use stdenvNoCC to avoid generating derivations with names
@@ -56,7 +59,13 @@ let
         timeout-up
         timeout-down
         restart-on-upgrade
-        ;
+      ;
+      propertiesText =
+        let a = mapAttrsRecursive
+          (path: value: "writepath ${concatStringsSep "/" path} ${builtins.toString value}\n")
+          properties;
+        in collect builtins.isString a;
+
       buildInputs =
         buildInputs ++ dependencies ++ contents ++ lib.optional (controller != null) controller;
       inherit controller dependencies contents;

pkgs/lualinux/0001-realpath.patch

@@ -0,0 +1,36 @@
+diff --git a/lualinux.c b/lualinux.c
+index f3d1a4d..9c5dc9c 100644
+--- a/lualinux.c
++++ b/lualinux.c
+@@ -387,6 +387,18 @@ static int ll_readlink(lua_State *L) {
+ 	RET_STRN(buf, n);
+ }
+ 
++static int ll_realpath(lua_State *L) {
++	const char *pname = luaL_checkstring(L, 1);
++	char * resolved = realpath(pname, NULL); /* mallocs */
++	if (resolved == 0) {
++	    RET_ERRNO;
++	} else {
++	    lua_pushstring(L, resolved);
++	    free(resolved);
++	    return 1;
++	}
++}
++
+ static int ll_lstat3(lua_State *L) {
+ 	// lua api: lstat3(path [,statflag:int])
+ 	// if statflag=1: do stat(). default: do lstat
+@@ -924,6 +936,7 @@ static const struct luaL_Reg lualinuxlib[] = {
+ 	{"readdir", ll_readdir},
+ 	{"closedir", ll_closedir},
+ 	{"readlink", ll_readlink},
++	{"realpath", ll_realpath},
+ 	{"lstat3", ll_lstat3},
+ 	{"lstat", ll_lstat},
+ 	{"utime", ll_utime},
+@@ -969,4 +982,3 @@ int luaopen_lualinux (lua_State *L) {
+ 	lua_settable (L, -3);
+ 	return 1;
+ }
+-

pkgs/lualinux/default.nix

@@ -13,6 +13,11 @@ lua.pkgs.buildLuaPackage {
   version = "0.1"; # :shrug:
 
   inherit src;
+
+  patches = [
+    ./0001-realpath.patch
+  ];
+
   postPatch = ''
     sed -i -e '/strip/d' Makefile
   '';

pkgs/output-template/output-template.fnl

@@ -25,10 +25,14 @@
         myenv {
                : string
                : table
+               : math
                : ipairs
+               : tonumber
+               : type
+
                :output
                (fn [service-path path default]
-                 (let [s (assert (svc.open (.. service-path "/.outputs")))]
+                 (let [s (assert (svc.open service-path))]
                    (or (s:output path) default)))
                :lua_quote #(string.format "%q" $1)
                :json_quote (fn [x] (.. "\"" (json-escape x) "\""))

pkgs/pppoe/default.nix

@@ -6,13 +6,15 @@
 }:
 stdenv.mkDerivation rec {
   pname = "rp-pppoe";
-  version = "3.15";
+  version = "4.0-plus";
 
   src = fetchFromGitHub {
     owner = "dfskoll";
     repo = "rp-pppoe";
-    rev = "7cfd8c0405d14cf1c8d799d41d8207fd707979c1";
-    hash = "sha256-MFdCwNj8c52blxEuXH5ltT2yYDmKMH5MLUgtddZV25E=";
+    rev = "3c0f6c02279881d723743023634b19b77a7d9f82";
+    hash = "sha256-RUUbP5j2I2DERQ7RE8xj4Xt1FoQOanMRoMiB1H6Wrdw=";
+    # rev = "7cfd8c0405d14cf1c8d799d41d8207fd707979c1";
+    # hash = "sha256-MFdCwNj8c52blxEuXH5ltT2yYDmKMH5MLUgtddZV25E=";
   };
 
   buildInputs = [ ppp ];

pkgs/run-liminix-vm/run-liminix-vm.fnl

@@ -79,19 +79,25 @@
      "-serial" (.. "unix:" sock ",server,nowait")
      "-monitor" (.. "unix:" monitor ",server,nowait")]))
 
+(local netrom (pad-file "/dev/null" 16384))
+
 (fn access-net [override]
   [
    "-netdev"  (.. (or override
                       "socket,mcast=230.0.0.1:1234,localaddr=127.0.0.1")
                   ",id=access")
-   "-device" "virtio-net,disable-legacy=on,disable-modern=off,netdev=access,mac=ba:ad:1d:ea:21:02"
+   "-device"
+   (.. "virtio-net,disable-legacy=on,romfile=" netrom ",disable-modern=off,netdev=access,mac=ba:ad:1d:ea:21:02")
+   ;; (.. "virtio-net,disable-legacy=on,disable-modern=off,netdev=access,mac=ba:ad:1d:ea:21:02")
    ])
 
 (fn local-net [override]
   [
    "-netdev" (.. (or override "socket,mcast=230.0.0.1:1235,localaddr=127.0.0.1")
                  ",id=lan")
-   "-device" "virtio-net,disable-legacy=on,disable-modern=off,netdev=lan,mac=ba:ad:1d:ea:21:01"
+   "-device"
+   (.. "virtio-net,disable-legacy=on,romfile=" netrom ",disable-modern=off,netdev=lan,mac=ba:ad:1d:ea:21:01")
+   ;; (.. "virtio-net,disable-legacy=on,disable-modern=off,netdev=lan,mac=ba:ad:1d:ea:21:01")
    ])
 
 
@@ -132,7 +138,7 @@
                               options.u-boot options.disk-image))
            (appendm (access-net options.wan))
            (appendm (local-net options.lan))
-           (appendm ["-display" "none"])))
+           (appendm ["-display" "none" "-vga" "none"])))
 
 (each [n a (ipairs exec-args)]
   (print (.. (if (> n  1) "     " "") (string.format "%q" a))))

pkgs/u-boot/0002-virtio-init-for-malta.patch

@@ -2,6 +2,18 @@ diff --git a/board/imgtec/malta/malta.c b/board/imgtec/malta/malta.c
 index 9853a0ba82..d95e332d6d 100644
 --- a/board/imgtec/malta/malta.c
 +++ b/board/imgtec/malta/malta.c
+@@ -23,6 +23,11 @@
+ 
+ #include "superio.h"
+ 
++#if IS_ENABLED(CONFIG_VIRTIO)
++#include <virtio_types.h>
++#include <virtio.h>
++#endif
++
+ DECLARE_GLOBAL_DATA_PTR;
+ 
+ #define MALTA_GT_PATH   "/pci0@1be00000"
 @@ -169,7 +169,9 @@ int board_early_init_f(void)
  int misc_init_r(void)
  {

pkgs/watch-outputs/watch-outputs.fnl

@@ -38,7 +38,6 @@
              "/nix/store/s2" [["out1"] ["out2" "ifname"]]}}
            ))
 
-
 (fn changed? [paths old-tree new-tree]
   (accumulate [changed? false
                _ path (ipairs paths)]
@@ -52,12 +51,10 @@
   (expect (not (changed? [["mtu"]] {:ifname "true"} {:ifname "false"})))
   )
 
-
-
 (fn do-action [action service]
   (case action
     :restart (system (%% "s6-svc -r /run/service/%s" service))
-    :restart-all (system (%% "s6-rc -b -d %q; s6-rc-up-tree %q" service service))
+    :restart-all (system (%% "s6-rc -b -d change %q; s6-rc-up-tree %q" service service))
     [:signal n] (system (%% "s6-svc -s %q /run/service/%s" n service))))
 
 (local POLLIN  0x0001)
@@ -71,7 +68,7 @@
 
 (fn open-services [output-references]
   (collect [s p (pairs output-references)]
-    (values (svc.open (.. s "/.outputs")) p)))
+    (values (svc.open s) p)))
 
 (fn run []
   (let [trees {}
@@ -80,16 +77,19 @@
          : controlled-service
          : action
          : watched-service
-         : paths } (parse-args arg)]
+         : paths } (parse-args arg)
+        services (open-services output-references)]
     (while true
-      (let [services (open-services output-references)
-            trees (collect [s _ (pairs services)]
-                    (values s (s:output ".")))]
-        (wait-for-change services)
-        (each [service paths (pairs services)]
-          (let [new-tree (service:output ".")]
-            (when (changed? paths (. trees service) new-tree)
-              (do-action action controlled-service))))))))
+      (when
+          (accumulate [changed false
+                       service paths (pairs services)]
+            (let [new-tree (service:output ".")]
+              (if (changed? paths (or (. trees service) {}) new-tree)
+                  (do (tset trees service new-tree) true)
+                  changed)))
+        (do-action action controlled-service))
+      (wait-for-change services))))
+
 
 
 

pkgs/watch-ssh-keys/watch-ssh-keys.fnl

@@ -50,8 +50,7 @@
 
 (fn run []
   (let [{: out-path : watched-service : path } (parse-args arg)
-        dir (.. watched-service "/.outputs")
-        service (assert (svc.open dir))]
+        service (assert (svc.open watched-service))]
     (accumulate [tree {}
                  v (service:events)]
       (write-changes out-path tree (or (service:output path) {})))))

tests/min-copy-closure/test.nix

@@ -6,6 +6,7 @@ let
     }
   );
   rogue = lmx.pkgs.rogue;
+  myPkg = lmx.pkgs.rsyncSmall;
   img = lmx.outputs.vmroot;
   pkgs = import <nixpkgs> { overlays = [ (import ../../overlay.nix) ]; };
 in
@@ -15,7 +16,7 @@ pkgs.runCommand "check"
       expect
       socat
       min-copy-closure
-      rogue
+      myPkg
     ];
   }
   ''
@@ -25,11 +26,12 @@ pkgs.runCommand "check"
     mkdir vm
     ${img}/run.sh --lan user,hostfwd=tcp::2022-:22  --background ./vm
     expect ${./wait-until-ready.expect}
+    echo ready to go
     export SSH_COMMAND="ssh -o StrictHostKeyChecking=no -p 2022 -i ${./id}"
     $SSH_COMMAND root@localhost echo ready
-    IN_NIX_BUILD=true min-copy-closure --quiet root@localhost ${rogue}
-    $SSH_COMMAND root@localhost ls -ld ${rogue}
-    IN_NIX_BUILD=true min-copy-closure --root /run root@localhost ${rogue}
-    $SSH_COMMAND root@localhost ls -ld /run/${rogue}
+    IN_NIX_BUILD=true min-copy-closure --quiet root@localhost ${myPkg}
+    $SSH_COMMAND root@localhost ls -ld ${myPkg}
+    IN_NIX_BUILD=true min-copy-closure --root /run root@localhost ${myPkg}
+    $SSH_COMMAND root@localhost ls -ld /run/${myPkg}
     ) 2>&1 | tee $out
   ''

tests/min-copy-closure/wait-until-ready.expect

@@ -1,13 +1,20 @@
 set timeout 60
 
 spawn socat unix-connect:vm/console -
-send "\r\n"
 expect {
-       "# " { send "hostname\r\n" };
+       "s6-linux-init"  { }
+       timeout { exit 1 }
 }
-
+set timeout 30
 expect {
-    "(none)" {}
-    "liminix" {}
-    timeout { exit(1) }
-}
+       "#" { send "PS1=\$(echo 'I1JFQURZIyA=' | base64 -d); stty -echo\n" }
+       timeout { exit 1 }
+}
+expect {
+       "#READY#" { send "s6-svwait -t 10000 -u /run/service/sshd; echo continue\n" }
+       timeout { exit 1 }
+}       
+expect {
+       "#READY#" { }
+       timeout { exit 1 }
+}

tests/pppoe/getaddress.expect

@@ -24,7 +24,7 @@ expect "#READY#"
 set timeout 30
 send "nft list set ip table-ip lan || touch /non/existent\n"
 expect {
-  "lan" { puts "lan found" }
+  "{ \"lan\" }" { puts "lan found" }
   "{ }" { puts "missing ifname"; exit 1 }
   "No such file or directory" { exit 1 }
 }  
@@ -36,7 +36,7 @@ expect "#READY#"
 # appears and you just have to make this sleep longer. Ew, yes
 send "sleep 10; nft list set ip table-ip wan || touch /non/existent\n"
 expect {
-  "ppp0" { puts "ppp0 found " }
+  "{ \"ppp0\" }" { puts "ppp0 found " }
   "{ }" { puts "missing ifname"; exit 1 }
   "No such file or directory" { exit 1 }
   timeout { exit 1 }