commit d0c2b3b274e90d37cfc6d12a4d9360262a5ad4aa
parent dfe7228b995837dd939c0a9b4c6124f910f12c37
Author: Daniel Barlow <dan@telent.net>
Date: Tue, 26 Sep 2023 18:24:40 +0100
explain the "demo" example
Diffstat:
| M | doc/tutorial.rst | | | 78 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 78 insertions(+), 0 deletions(-)
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
@@ -234,6 +234,78 @@ 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-shell --run "liminix-rebuild root@address-of-the-device -I liminix-config=./my-router.nix --arg device "import ./devices/gl-ar750""
+
+(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.)
+
Final thoughts
**************
@@ -253,3 +325,9 @@ Final thoughts
(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
