9 files changed, 195 insertions, 15 deletions
diff --git a/hurd/bootstrap.mdwn b/hurd/bootstrap.mdwn
index fbce3bc1..c77682b9 100644
--- a/hurd/bootstrap.mdwn
+++ b/hurd/bootstrap.mdwn
@@ -15,8 +15,15 @@ this text.  -->
 
 [[!toc]]
 
+[[!inline pagenames=hurd/what_is_an_os_bootstrap raw=yes feeds=no]]
+
 # State at the beginning of the bootstrap
 
+Please note that as of May 2024 this document is out of date.  It does
+not explain how rumpdisk or the pci-arbitor is started.  Also consider
+reading about [[Serverboot V2|open_issues/serverbootv2]], which
+is a new bootstrap proposal.
+
 After initializing itself, GNU Mach sets up tasks for the various bootstrap
 translators (which were loader by the GRUB bootloader). It notably makes
 variables replacement on their command lines and boot script function calls (see
diff --git a/hurd/documentation.mdwn b/hurd/documentation.mdwn
index 154b08ba..b79ddb0a 100644
--- a/hurd/documentation.mdwn
+++ b/hurd/documentation.mdwn
@@ -24,6 +24,7 @@ is included in the section entitled
     * [[The design|/hurd-paper#design]]
     * [[Introduction to Translators|/hurd-paper#translator]] and
       [[Existing Translators|hurd/translator]]
+    * [[Subhurds|hurd/subhurd]]
     * [[The auth translator|/hurd-paper#auth]]
     * [[The proc translator|/hurd-paper#proc]]
     * [[The exec translator|/hurd-paper#exec]]
@@ -58,9 +59,42 @@ is included in the section entitled
     applied, comparisions to other systems.
 
 
-# Development
+# Developer References
 
+* [[Coding_Style]]
+* [[Rules]]
+* [[Trackers]]
+* [[Building]]
+* [[Toolchain]]
+    * [[glibc]]
+* RPC [[Interface]]s
+* Libraries
+  * [[libpager]]
+  * [[libports]]
+  * [[libstore]]
+  * [[libchannel]]
+  * [[libtrivfs]]
+  * [[libnetfs]] -- short introductory material
+  * [[libdiskfs]]
+  * [[libihash]]
+  * [[libpthread]]
+  * [[libfshelp]]
+  * [[libps]]
+* In-development Libraries
+  * [[libfuse]]
+* [[IO_Path]]
+* [[Porting]]
+* [[Debugging]]
+* [[Networking]]
+* [[Console]]
+* [[System bootstrap|hurd/bootstrap]]
+* Additional references
   * [[RPC]]: our usage of *Remote Procedure Call*s.
+  * The [[System Bootstrap|hurd/bootstrap]] explains how the early
+    boot of the Hurd works.  There is an alternative [[RFC bootstrap
+    proposal|open_issues/serverbootv2]].
+  * You should read the Hurd's [[IO path|hurd/io_path]] to learn how
+    glibc's `read ()` works on the Hurd.
   * *[[The_GNU_Hurd_Reference_Manual|reference_manual]]*.
   * [[*The Hurd Hacking Guide|Hurd_Hacking_Guide]]*, an introduction to GNU&nbsp;Hurd and Mach
     programming by Wolfgang Jährling.
diff --git a/hurd/documentation/translators.html b/hurd/documentation/translators.html
index 8ae2c180..348774d1 100644
--- a/hurd/documentation/translators.html
+++ b/hurd/documentation/translators.html
@@ -212,7 +212,7 @@ I recommend that you start by reading the <code>/bin/mount</code> command,
 it is only a small script. Because setting filesystem translators is
 similar to mounting partitions, you can easily grasp the concept this way.
 Make a file system image with <code>dd if=/dev/zero of=dummy.fs bs=1024k
-count=8; mke2fs dummy.fs</code> and "mount" it with <code>settrans -c dummy
+count=8; /sbin/mke2fs -E root_owner=$UID:0 dummy.fs</code> and "mount" it with <code>settrans -c dummy
 /hurd/ext2fs `pwd`/dummy.fs</code>. Note that the translator is not started
 yet, no new <code>ext2fs</code> process is running (verify with <code>ps
 Aux</code>). Check that everything is correct using <code>showtrans</code></p>
diff --git a/hurd/running/debian/after_install.mdwn b/hurd/running/debian/after_install.mdwn
index 927d05f1..4c7d924a 100644
--- a/hurd/running/debian/after_install.mdwn
+++ b/hurd/running/debian/after_install.mdwn
@@ -15,3 +15,8 @@ you.  See [[GRUB]]'s page for this.
 
 Installing packages without having a network connection is described
 [[DebianAptOffline]].
+
+# Setting up mDNS responder
+
+To get `ssh <hostname>.local` working, you can set up the
+[[hurd/terrible-mdns-responder]].
diff --git a/hurd/running/qemu/image_for_l4.mdwn b/hurd/running/qemu/image_for_l4.mdwn
index 515f51bc..3dfbc946 100644
--- a/hurd/running/qemu/image_for_l4.mdwn
+++ b/hurd/running/qemu/image_for_l4.mdwn
@@ -156,11 +156,11 @@ Let's create it : we use the magic command `dd` on the special device which cont
 
 We will mount it in loopback :
 
-    $ losetup /dev/loop0 hurd_l4.img
+    # losetup /dev/loop0 hurd_l4.img
 
 We need now to have it recognized as a hard disk :
 
-    $ fdisk -u -C58 -S63 -H16 /dev/loop0
+    # fdisk -u -C58 -S63 -H16 /dev/loop0
       Device contains neither a valid DOS partition table, nor Sun, SGI or OSF disklabel
       Building a new DOS disklabel. Changes will remain in memory only,
      until you decide to write them. After that, of course, the previous
@@ -195,12 +195,12 @@ If everything is fine (especially check the `Start` and `End` fields), you can p
 
 You will have noticed that the partition only starts at the 63rd sector. The beginning of the disk contains the MBR which is used for booting. We must then remount the disk making sure that this part is skipped before formating it. We know that a sector uses 512 bytes so we should begin at 63 \* 512 = 32256 :
 
-    $ losetup -d /dev/loop0
-    $ losetup -o32256 /dev/loop0 hurd_l4.img
+    # losetup -d /dev/loop0
+    # losetup -o32256 /dev/loop0 hurd_l4.img
 
 Now comes time to format it into a decent filesystem :
 
-    $ mke2fs /dev/loop0
+    # mke2fs /dev/loop0
       mke2fs 1.35 (28-Feb-2004)
       Filesystem label=
       OS type: Linux
@@ -223,19 +223,19 @@ Now comes time to format it into a decent filesystem :
 
 We should now be able to mount it the right way :
 
-    $ mkdir mnt
-    $ losetup -d /dev/loop0
-    $ mount -o loop,offset=32256 hurd_l4.img mnt/
+    # mkdir mnt
+    # losetup -d /dev/loop0
+    # mount -o loop,offset=32256 hurd_l4.img mnt/
 
 Here comes grub time (I assume you have the grub files in `/boot/grub` and the `menu.lst` we've obtained in the previous section is in `~/`) :
 
-    $ mkdir -p mnt/boot/grub
-    $ cp /boot/grub/stage1 /boot/grub/stage2 /boot/grub/e2fs_stage1_5 mnt/boot/grub/
-    $ cp ~/menu.lst mnt/boot/grub
+    # mkdir -p mnt/boot/grub
+    # cp /boot/grub/stage1 /boot/grub/stage2 /boot/grub/e2fs_stage1_5 mnt/boot/grub/
+    # cp ~/menu.lst mnt/boot/grub
 
 We will make a grub bootimage and boot it with bochs :
 
-    $ cat stage1 stage2 > grubboot.img
+    # cat stage1 stage2 > grubboot.img
 
 Copy the following into `.bochsrc` (replace the parts in caps by the right info) :
 
diff --git a/hurd/terrible-mdns-responder.mdwn b/hurd/terrible-mdns-responder.mdwn
new file mode 100644
index 00000000..08e6de75
--- /dev/null
+++ b/hurd/terrible-mdns-responder.mdwn
@@ -0,0 +1,52 @@
+[[!meta copyright="Copyright © 2024 Free Software Foundation,
+Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+[[!tag open_issue_hurd]]
+
+# What is the terrible mDNS responder?
+
+Suppose you have the Hurd running on a another machine in your local
+network.  `ssh <IP-ADDRESS>` is not guarenteed to work, because your
+router will occassionally change the IP address of your Hurd machine.
+That's kind of annoying!  Luckily, Sergey wrote the terrible-mDNS
+responder, so that `ssh <hostname>.local` just works! How cool is
+that!?
+
+To be very clear, this does *not* teach the system to do mDNS queries
+(.local hostname lookups). The terrible-mDNS-responder only responds
+to other host's queries. (Those other hosts may be running Avahi or
+sd-rd or Apple's mDNSResponder or LookupServer or ...)
+
+The sources are over on
+[[GitHub|https://github.com/bugaevc/terrible-mdns-responder]]. There
+are no dependencies other than a libc. It's built with Meson and
+licensed under AGPL v3+. It even comes with an awkward attempt at a
+sysv init script! What's not to like?
+
+# How to use it on Debian GNU/Hurd?
+
+	$ git clone git@github.com:bugaevc/terrible-mdns-responder.git
+	$ cd terrible-mdns-responder
+	$ meson setup build # you may need to apt install meson
+	$ ninja -C build
+	$ sudo ninja install -C build
+	$ sudo update-rc.d terrible-mdns-responder defaults
+	$ sudo update-rc.d avahi-daemon disable
+	$ sudo service terrible-mdns-responder start
+
+# FAQ  Why not use avahi?
+
+Debian GNU/Hurd comes with Avahi in the default install (I believe).
+Avahi has never worked for me (on the Hurd), and I doubt it has ever
+worked for anyone else either. I *have* looked into the why (as in
+spent hours debugging and patching it); I don't remember the
+specifics, but I do remember that I concluded it won't be easy to make
+it work. So, a dead end.
diff --git a/hurd/translator/ext2fs.mdwn b/hurd/translator/ext2fs.mdwn
index 957b9c13..9be6c885 100644
--- a/hurd/translator/ext2fs.mdwn
+++ b/hurd/translator/ext2fs.mdwn
@@ -32,6 +32,57 @@ Extend ext2fs to support 64bit time.
 
 [[!inline pagenames=faq/2_gib_partition_limit raw=yes feeds=no]]
 
+## Create your own custom ext2fs
+
+	$ dd if=/dev/zero of=silly.fs bs=1024k count=8
+	$ /sbin/mkfs.ext2 -E root_owner=$UID:0 silly.fs
+	$ settrans -c silly /hurd/ext2fs `pwd`/silly.fs
+	$ ps -e | grep silly  # ext2fs has not started
+	$ ls silly
+	$ ps -e | grep silly | awk '{ print $6 " " $7 }'
+	/hurd/ext2fs /home/joshua/silly.fs
+	$ cd silly
+	$ echo 'hello' > hello.txt
+	$ mkdir silly-dir
+	$ cd ..
+	$ fsysopts silly
+	/hurd/ext2fs --writable --relatime --no-inherit-dir-group /home/joshua/silly.fs
+	$ fsysopts silly --readonly  # stop writes to the filesystem
+	$ fsysopts silly --writable  # let writes again
+
+Try to make the filesystem read-only with fsysopts. Note how further
+write attempts fail now. Try to kill the active translator with
+settrans -g.
+
+You could go crazy even!  Why not make something like this:
+
+	~/silly <--> silly.fs
+	   |   \
+	   |    \
+	   |     \
+	   |	  \
+	   | 	   \
+	  \|/	    \/
+	 silly1 <-> silly1.fs
+	       ...
+
+	/hurd/joshua/silly/silly1/silly2/silly3/silly4
+
+Each sillyN is another ext2fs filesystem!  Make sure that as N gets
+bigger sillyN.fs gets smaller.  Let us know in the `#hurd` [irc
+channel](https://web.libera.chat/) how "silly" you are.  :)
+
+The current record is 2!
+
+	$ ps -e | grep silly | awk '{print $6 " " $7}'
+	/hurd/ext2fs /home/joshua/silly.fs
+	/hurd/ext2fs /home/joshua/silly/silly1.fs
+
+What is the limit?  How many nested ext2fs translators can you have?
+You could have 32 ["silly"
+directories](https://logs.guix.gnu.org/hurd/2024-05-31.log#005021).
+That's very silly!
+
 ### Ognyan's Work to allow ext2 to surpass the 2 GiB limit
 
   * Ognyan Kulev, [[*Supporting Large ext2 File Systems in the
diff --git a/hurd/what_is_an_os_bootstrap.mdwn b/hurd/what_is_an_os_bootstrap.mdwn
new file mode 100644
index 00000000..b2db2554
--- /dev/null
+++ b/hurd/what_is_an_os_bootstrap.mdwn
@@ -0,0 +1,24 @@
+[[!meta copyright="Copyright © 2020 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+[[!meta title="What is an OS bootstrap"]]
+
+# What is an OS bootstrap?
+
+An operating system's bootstrap is the process that happens shortly
+after you press the power on button, as shown below:
+
+Power-on -> Bios -> Bootloader ->  **OS Bootstrap** -> service manager
+
+Note that in this context the OS bootstrap is not [building a
+distribution and packages from source
+code](https://guix.gnu.org/manual/en/html_node/Bootstrapping.html).
+The OS bootstrap has nothing to do with [reproducible
+builds](https://reproducible-builds.org/).
diff --git a/hurd/what_is_the_gnu_hurd.mdwn b/hurd/what_is_the_gnu_hurd.mdwn
index 8315bfff..09c26ee7 100644
--- a/hurd/what_is_the_gnu_hurd.mdwn
+++ b/hurd/what_is_the_gnu_hurd.mdwn
@@ -33,7 +33,14 @@ provides the same standard interfaces known from other [[UNIX]]-like systems.
 Thus, for a typical user, the Hurd is intended to silently work in the
 background providing the services and infrastructure which the [[microkernel]]
 itself has no business implementing, but that are required for higher level
-programs and libraries to operate.
+programs and libraries to operate. Let's look at an example.
+
+[[!img open_issues/images/overview.svg]]
+
+Firefox invokes glibc's `send ()`, which in turn uses the pfinet (or
+lwip) TCP/IP stack, which talk to our device drivers (rump or netdde),
+which finally talk to GNU Mach.  Only GNU Mach runs in kernel space!
+Everything else is userspace!
 
 The Hurd supplies the last major software component needed for a complete
 [[GNU_operating_system|running/gnu]] as originally conceived by Richard