diff options
Diffstat (limited to 'hurd')
62 files changed, 1601 insertions, 371 deletions
diff --git a/hurd/bootstrap.mdwn b/hurd/bootstrap.mdwn index fbce3bc1..76ad0dc5 100644 --- a/hurd/bootstrap.mdwn +++ b/hurd/bootstrap.mdwn @@ -15,98 +15,115 @@ this text. --> [[!toc]] +[[!inline pagenames=hurd/what_is_an_os_bootstrap raw=yes feeds=no]] + # State at the beginning of the bootstrap +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 -the details in `gnumach/kern/boot_script.c`). For instance, if the GRUB -bootloader has the following configuration: +the details in `gnumach/kern/boot_script.c`). For instance, the GRUB +bootloader can have the following typical configuration: multiboot /boot/gnumach-1.8-486-dbg.gz root=device:hd1 console=com0 - module /hurd/ext2fs.static ext2fs --readonly \ - --multiboot-command-line='${kernel-command-line}' \ + module /hurd/pci-arbiter.static pci-arbiter --host-priv-port='${host-port}' \ --device-master-port='${device-port}' \ + --next-task='${acpi-task}' \ + '$(pci-task=task-create)' '$(task-resume)' + module /hurd/acpi.static acpi \ + --next-task='${disk-task}' \ + '$(acpi-task=task-create)' + module /hurd/rumpdisk.static rumpdisk \ + --next-task='${fs-task}' \ + '$(disk-task=task-create)' + module /hurd/ext2fs.static ext2fs --readonly \ + --multiboot-command-line='${kernel-command-line}' \ --exec-server-task='${exec-task}' -T typed '${root}' \ - '$(task-create)' '$(task-resume)' + '$(fs-task=task-create)' module /lib/ld.so.1 exec /hurd/exec '$(exec-task=task-create)' -GNU Mach will first make the `$(task-create)` function calls, and thus create a -task for the ext2fs module and a task for the exec module (and store a port on -that task in the `exec-task` variable). +GNU Mach will first make the `$(task-create)` function calls, and thus create +a series of tasks for the various modules, and assign to the `pci-task`, +`acpi-task`, `disk-task`, and `fs-task` variables the task ports for each of +them. None of these tasks is started yet. It will then replace the variables (`${foo}`), i.e. * `${kernel-command-line}` with its own command line (`root=device:hd1 console=com0`), * `${host-port}` with a reference to the GNU Mach host port, * `${device-port}` with a reference to the GNU Mach device port, -* `${exec-task}` with a reference to the exec task port. +* `${acpi-task}` with a reference to the acpi task port, and similarly for all other tasks. * `${root}` with `device:hd1` This typically results in: - task loaded: ext2fs --readonly --multiboot-command-line=root="device:hd1 console=com0" --host-priv-port=1 --device-master-port=2 --exec-server-task=3 -T typed device:hd1 + task loaded: pci-arbiter --host-priv-port=1 --device-master-port=2 --next-task=3 + task loaded: acpi --next-task=1 + task loaded: rumpdisk --next-task=1 + task loaded: ext2fs --readonly --multiboot-command-line=root="device:sd1 console=com0" --exec-server-task=1 -T typed device:sd1 task loaded: exec /hurd/exec + (You will have noticed that `/hurd/exec` is not run directly, but through `ld.so.1`: Mach only knows to run statically-linked ELF binaries, so we could -either load `/hurd/exec.static`, or load the dynamic loader `ld.so.1` and tell -it to load `/hurd/exec`) +either load `/hurd/exec.static` directly, or load the dynamic loader `ld.so.1` +and tell it to load `/hurd/exec`, which will be readable once `ext2fs.static` is +started) GNU Mach will eventually make the `$(task-resume)` function calls, and thus -resume the ext2fs task only. +resume the `pci-arbiter` task only. -This starts a dance between the bootstrap processes: `ext2fs`, `exec`, `startup`, -`proc`, and `auth`. Indeed, there are a few dependencies between them: `exec` needs -`ext2fs` working to be able to start `startup`, `proc` and `auth`, and `ext2fs` needs to -register itself to `startup`, `proc` and `auth` so as to appear as a normal process, -running under uid 0. - -The base principle is that `ext2fs` has a nul bootstrap port set to while other -translators will have a non-nul bootstrap port, with which they will discuss. We -thus have a hierarchy between the bootstrap processes. `ext2fs` is at the root, -`exec` and `startup` are its direct children, and `auth` and `port` are direct -children of `startup`. - -Usually the bootstrap port is used when starting a translator, see +Usually the bootstrap ports of translators is used when starting them, see `fshelp_start_translator_long`: the parent translator starts the child and sets its bootstrap port. The parent then waits for the child to call `fsys_startup` on the bootstrap port, for the child to provide its control port, and for the parent to provide the FS node that the child is translator for. -For the bootstrap translators, the story is extended: +But here when `pci-arbiter` initializes itself, it notices that its bootstrap +port is nul (it is started by the kernel, not a filesystem) so it knows that it +is alone and can only rely on the kernel. It initializes itself and parses the +arguments, and since it is given a `next-task`, it uses `task_set_special_port` +to pass a send right to its own control port to that next task (here `acpi`) as +bootstrap port, and uses `task_resume` to start it. + +Similarly, `acpi` initializes itself, gives a send right to `rumpdisk` and +starts it. + +`rumpdisk` does the same, so that eventually `ext2fs` starts, with all of +`pci-arbiter`, `acpi` and `rumpdisk` ready to reply to `device_open` requests on +the `pci`, `acpi`, and disks device names. + +Now that `ext2fs` starts, a dance begin between the remaining bootstrap +processes: `ext2fs`, `exec`, `startup`, `proc`, and `auth`. Indeed, there are +a few dependencies between them: `exec` needs `ext2fs` working to be able to +start `startup`, `proc` and `auth`, and `ext2fs` needs to register itself to +`startup`, `proc` and `auth` so as to appear as a normal process, running under +uid 0. + +They will register to each other the following way: -* Between `ext2fs` and `startup`: `startup` additionally calls `fsys_init`, to +* Between `ext2fs` and `startup`: `startup` calls `fsys_init`, to provide `ext2fs` with `proc` and `auth` ports. * Between `startup` and `proc`: `proc` just calls `startup_procinit` to hand over a `proc` port and get `auth` and `priv` ports. * Between `startup` and `auth`: `auth` calls `startup_authinit` to hand over an `auth` port and get a `proc` port, then calls `startup_essential_task` to notify `startup` that the boot can proceed. -* For translators before `ext2fs`, the child calls `fsys_startup` to pass over -the control port of `ext2fs` (instead of its own control port, which is useless -for its parent). This is typically done in the `S_fsys_startup` stub, simply -forwarding it. The child also calls `fsys_init` to pass over the `proc` and -`auth` ports. Again, this is typically done in the `S_fsys_init` stub, simply -forwarding them. +* For the series of translators before `ext2fs`, each task calls `fsys_startup` +to pass over the control port of `ext2fs` to the previous task (instead of +its own control port, which is useless for it). This is typically done in the +`S_fsys_startup` stub, simply forwarding it. It also calls `fsys_init` to +pass over the `proc` and `auth` ports. Again, this is typically done in the +`S_fsys_init` stub, simply forwarding them. With that in mind, the dance between the bootstrap translators is happening as described in the next sections. -# Initialization of translators before ext2fs - -We plan to start pci-arbiter and rumpdisk translators before ext2fs. - -pci-arbiter's `main` function parses the arguments, and since it is given a disk -task port, it knows it is a bootstrap translator and thus initializes the -machdev library. `machdev_trivfs_init` resumes the disk task. - -rumpdisk's `main` function parses the arguments, and since it is given a FS task -port, it knows it is a bootstrap translator, and thus `machdev_trivfs_init` -resumes the FS task. - # ext2fs initialization ext2fs's `main` function starts by calling `diskfs_init_main`. @@ -120,7 +137,8 @@ ext2fs bootstrap port to `MACH_PORT_NULL`: it is the bootstrap filesystem which will be in charge of dancing with the exec and startup translator. `diskfs_init_main` then initializes the libdiskfs library and spawns a thread to -manage libdiskfs RPCs. +manage libdiskfs RPCs. It also notices that the filesystem is given a kernel +command line, i.e. this is the bootstrap filesystem. ext2fs continues its initialization: creating a pager, opening the hypermetadata, opening the root inode to be set as root by libdiskfs. @@ -130,7 +148,7 @@ by the libdiskfs library. # libdiskfs bootstrap -Since the bootstrap port is `MACH_PORT_NULL`, `diskfs_startup_diskfs` calls +Since this is the bootstrap filesystem, `diskfs_startup_diskfs` calls `diskfs_start_bootstrap`. `diskfs_start_bootstrap` starts by creating a open port on itself for the @@ -265,13 +283,26 @@ on its bootstrap port, i.e. rumpdisk. rumpdisk's `trivfs_S_fsys_init` gets called from the `fsys_init` call from ext2fs. It calls `fsys_init` on its bootstrap port. +# acpi getting initialized + +acpi's `trivfs_S_fsys_init` gets called from the `fsys_init` call from +rumpdisk. It calls `fsys_init` on its bootstrap port. + # pci-arbiter getting initialized pci-arbiter's `trivfs_S_fsys_init` gets called from the `fsys_init` call from rumpdisk. It gets the root node of ext2fs, sets all common ports, and install -pci-arbiter in the ext2fs FS as translator for `/servers/bus/pci`. +itself in the ext2fs FS as translator for `/servers/bus/pci`. + +It eventually calls `startup_essential_task` to tell startup that it is ready, +and requests shutdown notifications. + +# back to acpi initialization + +It gets the root node of ext2fs, sets all common ports, and install +itself in the ext2fs FS as translator for `/servers/acpi`. It eventually calls `startup_essential_task` to tell startup that it is ready, and requests shutdown notifications. @@ -279,7 +310,7 @@ and requests shutdown notifications. # back to rumpdisk initialization It gets the root node of ext2fs, sets all common ports, and install -rumpdisk in the ext2fs FS as translator for `/dev/disk`. +itself in the ext2fs FS as translator for `/dev/disk`. It eventually calls `startup_essential_task` to tell startup that it is ready, and requests shutdown notifications. @@ -297,7 +328,7 @@ system is shutting down. # startup monitoring bootstrap progress -As mentioned above, the different essential tasks (pci-arbiter, rumpdisk, ext2fs, proc, auth, exec) +As mentioned above, the different essential tasks (pci-arbiter, acpi, rumpdisk, ext2fs, proc, auth, exec) call `startup_essential_task` when they are ready. startup's `S_startup_essential_task` function thus gets called each time, and startup records each of them as essential, monitoring their death to crash the whole diff --git a/hurd/building.mdwn b/hurd/building.mdwn index 7cfc7c7e..ea3213e5 100644 --- a/hurd/building.mdwn +++ b/hurd/building.mdwn @@ -36,7 +36,7 @@ package: You can chose between getting the [sources from the developers's git](http://savannah.gnu.org/git/?group=hurd): - $ git clone git://git.sv.gnu.org/hurd/hurd.git + $ git clone git://git.savannah.gnu.org/hurd/hurd.git ... or (if you are working on a Debian system) the ones that are used for the [current Debian hurd package](http://packages.debian.net/source/unstable/hurd): @@ -93,6 +93,12 @@ or `/local/`, so your current Hurd servers will be replaced. To install to a different location, specify `--prefix=PREFIX` as `configure` parameter, e.g. `--prefix=/usr` (as done when having a real `/usr`). +To build acpi: + + $ make acpi + +You may need to install necessary acpi headers (`libacpica-dev` package in Debian based distro). + By default profiling versions of all the libraries and code are generated but this is useless in most of the cases, so we disable them by specifying `--disable-profile` on `configure`'s command line. diff --git a/hurd/dde/guide.mdwn b/hurd/dde/guide.mdwn index b6cf7753..10a7910b 100644 --- a/hurd/dde/guide.mdwn +++ b/hurd/dde/guide.mdwn @@ -74,9 +74,9 @@ Note: here, use dde-debian instead of dde if you have gnumach >= 2:1.3.99.dfsg.git20120219-1 already installed and running. Otherwise you will get "vm_allocate_contiguous: (ipc/mig) bad request message ID" error messages. - $ git clone git://git.sv.gnu.org/hurd/incubator.git -b dde hurd + $ git clone git://git.savannah.gnu.org/hurd/incubator.git -b dde hurd - $ git clone git://git.sv.gnu.org/hurd/gnumach.git -b master-user_level_drivers + $ git clone git://git.savannah.gnu.org/hurd/gnumach.git -b master-user_level_drivers Now comes the tricky part: you need to find out diff --git a/hurd/debugging/rpctrace.mdwn b/hurd/debugging/rpctrace.mdwn index 0c19da02..be937939 100644 --- a/hurd/debugging/rpctrace.mdwn +++ b/hurd/debugging/rpctrace.mdwn @@ -15,6 +15,7 @@ doing. See `rpctrace --help` about how to use it. + $ rpctrace cat /dev/null # IRC, freenode, #hurd, 2013-07-29 diff --git a/hurd/debugging/translator/gdb.mdwn b/hurd/debugging/translator/gdb.mdwn index 82a50736..fdf6adff 100644 --- a/hurd/debugging/translator/gdb.mdwn +++ b/hurd/debugging/translator/gdb.mdwn @@ -12,6 +12,8 @@ Say you want to try running file system server ([[`ext2fs`|translator/ext2fs]], [[`jfs`|translator/jfs]], ...) against a modified version of [[`libpager`|libpager]] and debug the latter one using [[debugging/GDB]]. +On Debian you need the `hurd-dbgsym` and `libc0.3-dbg` packages installed. + Set the [[hurd/translator]] like this: $ settrans -fgap ↩ @@ -51,3 +53,11 @@ course): [...] Voilà. + +If you need to debug the initialization of the translator, start the translator +like + + $ settrans -Pa /foo /hurd/foofs + +The `-P` option will make it +pause and you will be able to attach [[debugging/GDB]] to the process. diff --git a/hurd/documentation.mdwn b/hurd/documentation.mdwn index f095cf26..f9a2428f 100644 --- a/hurd/documentation.mdwn +++ b/hurd/documentation.mdwn @@ -22,7 +22,9 @@ is included in the section entitled * [[*Towards_a_New_Strategy_of_OS_Design*|/hurd-paper]], an architectural overview by Thomas Bushnell, BSG, notably: * [[The design|/hurd-paper#design]] - * [[Translators|/hurd-paper#translator]] + * [[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]] @@ -57,9 +59,47 @@ is included in the section entitled applied, comparisions to other systems. -# Development +# Developer References +* [[Coding_Style]] +* [[Rules]] +* [[Trackers]] +* [[Building]] +* [[Toolchain]] + * [[glibc]] +* Device Drivers + * [[rump|hurd/rump]] NetBSD drivers + * [[DDE|hurd/dde]] Outdated Linux Drivers (unmaintained) +* RPC [[Interface]]s +* Libraries + * [[libpager]] + * [[libports]] + * [[libstore]] + * [[libchannel]] + * [[libtrivfs]] + * [[libmachdev]] + * [[libnetfs]] -- short introductory material + * [[libdiskfs]] + * [[libihash]] + * [[libirqhelp]] + * [[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 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/glibc.mdwn b/hurd/glibc.mdwn index 6c7080c2..736cc099 100644 --- a/hurd/glibc.mdwn +++ b/hurd/glibc.mdwn @@ -36,11 +36,9 @@ Currently the master branch builds that way without any testsuite issue. To save some disk space, after the compilers stage you can remove src/mpc, src/mpfr, src/binutils, src/linux. -# Building - -One of the tests really put boxes on its knees: +Build logs are available in `/tmp/build/logs` - $ echo "tests-unsupported += test-lfs" >> sysdeps/mach/hurd/i386/Makefile +# Building One can build libc this way: @@ -51,6 +49,10 @@ One can build libc this way: $ make $ make check -k +One can run tests individually with: + + $ make test t=wcsmbs/test-wcsnlen + One can run tests with the new libc by hand: $ ./testrun.sh ~/test diff --git a/hurd/glibc/hurd-specific_api.mdwn b/hurd/glibc/hurd-specific_api.mdwn index 7ead63cd..ed25a821 100644 --- a/hurd/glibc/hurd-specific_api.mdwn +++ b/hurd/glibc/hurd-specific_api.mdwn @@ -1,5 +1,5 @@ -[[!meta copyright="Copyright © 2002, 2007, 2008, 2010 Free Software Foundation, -Inc."]] +[[!meta copyright="Copyright © 2002, 2007, 2008, 2010, 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 @@ -19,166 +19,193 @@ programs -- they are used to produce `.h` files. <!-- TODO. Need to convert this to a proper table. --tschwinge --> -<dl> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>getcwdir</b> (void);</tt></dt> - <p> - </p> - <dd>Get <tt>file_t</tt> port name of current working directory. See <tt>&lt;hurd/fs.defs&gt;</tt> and <tt>&lt;hurd/fs.h&gt;</tt>.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>setcwdir</b> (file_t);</tt></dt> - <dd>Set current working directory.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>getcrdir</b> (void);</tt></dt> - <dd>Get <tt>file_t</tt> port name of current root directory.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>setcrdir</b> (file_t);</tt></dt> - <p> - </p> - <dd>Set current root directory.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>file_name_lookup</b> (const char *file, int flags, mode_t mode);</tt></dt> - <dd>Open a port to FILE with the given FLAGS and MODE (see <tt>&lt;fcntl.h&gt;</tt>). The file lookup uses the current root and working directory. Returns a port to the file if successful; otherwise sets <tt>errno</tt> and returns <tt>MACH_PORT_NULL</tt>.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>file_name_lookup_under</b> (file_t startdir, const char *file, int flags, mode_t mode);</tt></dt> - <dd>Open a port to FILE with the given FLAGS and MODE (see <tt>&lt;fcntl.h&gt;</tt>). The file lookup uses the current root directory, but uses STARTDIR as the "working directory" for file relative names. Returns a port to the file if successful; otherwise sets <tt>errno</tt> and returns <tt>MACH_PORT_NULL</tt>.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>file_name_path_lookup</b> (const char *file_name, const char *path, int flags, mode_t mode, char **prefixed_name);</tt></dt> - <dd>Lookup FILE_NAME and return the node opened with FLAGS &amp; MODE (see <tt>hurd_file_name_lookup</tt> for details), but a simple file name (without any directory prefixes) will be consecutively prefixed with the pathnames in the <tt>:</tt> separated list PATH until one succeeds in a successful lookup. If none succeed, then the first error that wasn't ENOENT is returned, or ENOENT if no other errors were returned. If PREFIXED_NAME is non-NULL, then if the result is looked up directly, *PREFIXED_NAME is set to NULL, and if it is looked up using a prefix from PATH, *PREFIXED_NAME is set to malloc'd storage containing the prefixed name.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>file_name_split</b> (const char file, char **name);</tt></dt> - <dd>Split FILE into a directory and a name within the directory. The directory lookup uses the current root and working directory. If successful, stores in *NAME a pointer into FILE where the name within directory begins and returns a port to the directory; otherwise sets <tt>errno</tt> and returns <tt>MACH_PORT_NULL</tt>.</dd> - <p> - </p> - <dt><tt>file_t</tt></dt> - <dt><tt><b>directory_name_split</b> (const char *file, char **name);</tt></dt> - <p> - </p> - <dd>Split DIRECTORY into a parent directory and a name within the directory. This is the same as <tt>file_name_split</tt>, but ignores trailing slashes.</dd> - <p> - </p> - <dt><tt>FILE *</tt></dt> - <dt><tt><b>fopenport</b> (io_t port, const char *mode);</tt></dt> - <dd>Open a stream on a port. MODE is as for <tt>fopen</tt>. If successful, this consumes a user reference for PORT (which will be deallocated on fclose).</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>openport</b> (io_t port, int flags);</tt></dt> - <p> - </p> - <dd>Open a [[unix/file_descriptor]] on a [[microkernel/mach/port]]. FLAGS - are as for <tt>open</tt>; flags affected by <tt>io_set_openmodes</tt> are - not changed by this. If successful, this consumes a user reference for - PORT (which will be deallocated on close.) See - <tt>&lt;hurd/io.defs&gt;</tt> and - <tt>&lt;hurd/io.h&gt;</tt>. - </dd> - <p> - </p> - <dt><tt>task_t</tt></dt> - <dt><tt><b>pid2task</b> (pid_t pid);</tt></dt> - <p> - </p> - <dd>Return the task control port of process PID. On error, sets <tt>errno</tt> and returns <tt>MACH_PORT_NULL</tt>.</dd> - <p> - </p> - <dt><tt>pid_t</tt></dt> - <dt><tt><b>task2pid</b> (task_t task);</tt></dt> - <dd>Return the PID of the task whose control port is TASK. On error, sets <tt>errno</tt> and returns -1. </dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>geteuids</b> (int n, uid_t *uidset);</tt></dt> - <dd>Get the effective UID set.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>seteuids</b> (int n, const uid_t *uidset);</tt></dt> - <dd>Set the effective UID set.</dd> - <p> - </p> - <dt><tt>auth_t</tt></dt> - <dt><tt><b>getauth</b> (void);</tt></dt> - <dd>Get port name of current authentication server. See <tt>&lt;hurd/auth.defs&gt;</tt> and <tt>&lt;hurd/auth.h&gt;</tt>.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>setauth</b> (auth_t);</tt></dt> - <p> - </p> - <dd>Set current authentication server.</dd> - <p> - </p> - <dt><tt>process_t</tt></dt> - <dt><tt><b>getproc</b> (void);</tt></dt> - <dd>Get port name of current process server. See <tt>&lt;hurd/process.defs&gt;</tt> and <tt>&lt;hurd/process.h&gt;</tt>.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>setproc</b> (process_t);</tt></dt> - <p> - </p> - <dd>Set current process server.</dd> - <p> - </p> - <dt><tt>mach_port_t</tt></dt> - <dt><tt><b>getcttyid</b> (void);</tt></dt> - <dd>Get the CTTY port.</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>setcttyid</b> (mach_port_t);</tt></dt> - <dd>Set the CTTY port.</dd> - <p> - </p> - <dt><tt>kern_return_t</tt></dt> - <dt><tt><b>get_privileged_ports</b> (host_priv_t *host_priv_ptr, device_t *device_master_ptr);</tt></dt> - <dd>Fetch the host privileged port and device master port from the process server.</dd> - <p> - </p> - <dt><tt>mode_t</tt></dt> - <dt><tt><b>getumask</b> (void);</tt></dt> - <dd>Get the current `umask' value without changing it (this glibc functions is available only under GNU Hurd.)</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>vpprintf</b> (io_t port, const char *format, va_list arg);</tt></dt> - <dd>Write formatted output to PORT, a Mach port supporting the i/o protocol, according to the format string FORMAT, using the argument list in ARG.</dd> - <p> - </p> - <dt><tt>thread_t</tt></dt> - <dt><tt><b>hurd_thread_self</b> (void);</tt></dt> - <dd>Return the current thread's thread port. This is a cheap operation (no [[system call]]), but it relies on Hurd signal state being set up.</dd> - <p> - </p> - <dt><tt>error_t</tt></dt> - <dt><tt><b>hurd_thread_cancel</b> (thread_t thread);</tt></dt> - <p> - </p> - <dd>Cancel pending operations on THREAD. If it is doing an interruptible RPC, that RPC will now return EINTR; otherwise, the "cancelled" flag will be set, causing the next <tt>hurd_check_cancel</tt> call to return nonzero or the next interruptible RPC to return <tt>EINTR</tt> (whichever is called first).</dd> - <p> - </p> - <dt><tt>int</tt></dt> - <dt><tt><b>hurd_check_cancel</b> (void);</tt></dt> - <p> - </p> - <dd>Test and clear the calling thread's "cancelled" flag.</dd> - <p> - </p> -</dl> + + file_t + getcwdir (void); + +Get `file_t` port name of the current working directory. See +`hurd.defs` and `hurd.h`. + + int + setcwdir (file_t); + +Set the current working directory. + + file_t + getcrdir (void); + +Get file_t port name of current root directory. + + int + setcrdir (file_t); + +Set current root directory. + + file_t + file_name_lookup (const char *file, int flags, mode_t mode); + +Open a port to `FILE` with the given `FLAGS` and `MODE` (see +`fcntl.h`). The file lookup uses the current root and working +directory. Returns a port to the file if successful; otherwise sets +`errno` and returns `MACH_PORT_NULL`. + + file_t + file_name_lookup_under (file_t startdir, const char *file, + int flags, mode_t mode); + +Open a port to `FILE` with the given `FLAGS` and `MODE` (see +`fcntl.h`). The file lookup uses the current root directory, but uses +`STARTDIR` as the "working directory" for file relative names. Returns +a port to the file if successful; otherwise sets errno and returns +`MACH_PORT_NULL`. + + file_t + file_name_path_lookup (const char *file_name, const char *path, + int flags, mode_t mode, + char **prefixed_name); + +Lookup `FILE_NAME` and return the node opened with `FLAGS` & `MODE` +(see `hurd_file_name_lookup` for details), but a simple file name +(without any directory prefixes) will be consecutively prefixed with +the pathnames in the : separated list `PATH` until one succeeds in a +successful lookup. If none succeed, then the first error that wasn't +`ENOENT` is returned, or `ENOENT` if no other errors were returned. If +`PREFIXED_NAME` is non-NULL, then if the result is looked up directly, +`*PREFIXED_NAME` is set to NULL, and if it is looked up using a prefix +from `PATH`, `*PREFIXED_NAME` is set to malloc'd storage containing +the prefixed name. + + file_t + file_name_split (const char file, char **name); + +Split `FILE` into a directory and a name within the directory. The +directory lookup uses the current root and working directory. If +successful, stores in `*NAME` a pointer into `FILE` where the name +within directory begins and returns a port to the directory; otherwise +sets errno and returns `MACH_PORT_NULL`. + + file_t + directory_name_split (const char *file, char **name); + +Split `DIRECTORY` into a parent directory and a name within the +directory. This is the same as `file_name_split`, but ignores trailing +slashes. + + FILE * + fopenport (io_t port, const char *mode); + +Open a stream on a port. `MODE` is as for `fopen`. If successful, this +consumes a user reference for `PORT` (which will be deallocated on +`fclose`). + + int + openport (io_t port, int flags); + +Open a [[file descriptor|unix/file_descriptor]] on a +[[port|microkernel/mach/port]]. `FLAGS` are as for open; flags +affected by `io_set_openmodes` are not changed by this. If successful, +this consumes a user reference for `PORT` (which will be deallocated +on close.) See `hurd/io.defs` and `hurd/io.h`. + + task_t + pid2task (pid_t pid); + +Return the task control port of process `PID`. On error, sets errno and +returns `MACH_PORT_NULL`. + + pid_t + task2pid (task_t task); + +Return the `PID` of the task whose control port is `TASK`. On error, sets +errno and returns -1. + + int + geteuids (int n, uid_t *uidset); + +Get the effective UID set. + + int + seteuids (int n, const uid_t *uidset); + +Set the effective UID set. + + auth_t + getauth (void); + +Get port name of current authentication server. See +`hurd/auth.defs` and `hurd/auth.h`. + + int + setauth (auth_t); + +Set current authentication server. + + process_t + getproc (void); + +Get port name of current process server. See `hurd/process.defs` +and `hurd/process.h`. `process_t` is a port to the proc server, by +which RPCs are made to the proc server. It is also a way to represent +a task when communicating with the proc server. Each task has its own +port by which it communicates with the process server under the +identity of the task. You can pass a `process_t` to another process, +and then that process can call RPCs with the process server with the +identity of the original task that pasted the port. +<!-- I got the information about process_t from this irc chat log +https://logs.guix.gnu.org/hurd/2021-03-18.log#105247 --> + + int + setproc (process_t); + +Set current process server. + + mach_port_t + getcttyid (void); + +Get the CTTY port. + + int + setcttyid (mach_port_t); + +Set the CTTY port. + + kern_return_t + get_privileged_ports (host_priv_t *host_priv_ptr, + device_t *device_master_ptr); + +Fetch the host privileged port and device master port from the process +server. + + mode_t + getumask (void); + +Get the current `umask` value without changing it (this glibc +functions is available only under GNU Hurd.) + + int + vpprintf (io_t port, const char *format, va_list arg); + +Write formatted output to `PORT`, a Mach port supporting the i/o +protocol, according to the format string `FORMAT`, using the argument +list in `ARG`. + + thread_t + hurd_thread_self (void); + +Return the current thread's thread port. This is a cheap operation (no +[[system call|system_call]]), but it relies on Hurd signal state being +set up. + + error_t + hurd_thread_cancel (thread_t thread); + +Cancel pending operations on `THREAD`. If it is doing an interruptible +RPC, that RPC will now return `EINTR`; otherwise, the "cancelled" flag +will be set, causing the next `hurd_check_cancel` call to return +nonzero or the next interruptible RPC to return `EINTR` (whichever is +called first). + + int + hurd_check_cancel (void); + +Test and clear the calling thread's "cancelled" flag. diff --git a/hurd/libirqhelp.mdwn b/hurd/libirqhelp.mdwn new file mode 100644 index 00000000..c2111036 --- /dev/null +++ b/hurd/libirqhelp.mdwn @@ -0,0 +1,53 @@ +[[!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 stable_URL]] + +Damien Zammit authored libirqhelp, which lets userspace attach and +handle interupts. Suppose, a user presses a key on his keyboard, then +the keyboard can send an interrupt request (an IRQ), to the +processor. The CPU will try to interrupt the program, so that a +callback handler can run instead. A brief overview of `x86` interrupt +information can be found on +[[wikipedia|https://en.wikipedia.org/wiki/Interrupt_request]]. The +[[osdev wiki|https://wiki.osdev.org/IOAPIC]] has more technical +information. In `libirqhelp` the delivery of the interrupt is through an RPC +message that triggers a handler. +The source for `libirqhelp` can be found in `$hurd-src/libirqhelp/`. + +First you must call `irqhelp_init ();` Then you can install an +interrupt handler with this function: + + struct irq * + irqhelp_install_interrupt_handler (int gsi, int bus, int dev, + int fun, void (*handler)(void*), + void *context); + +If `gsi` is `-1`, then ACPI will look up the global system interrupt from the PCI `bus`, `dev`, and `fun`. +If `bus`, `dev`, and `fun` are `-1`, then you must define `gsi` +(global system interrupt). You then use the returned `struct irq *` +to call the other functions. + +You can enable an irq via: + + void irqhelp_enable_irq (struct irq *irq); + +You can disable an irq via: + + void irqhelp_disable_irq (struct irq *irq); + +You can deregister a handler via: + + error_t irqhelp_remove_interrupt_handler (struct irq *irq); + +To receive irq notifications, you have to call this next function in a separate thread, giving the `struct irq *` as `arg`. + + void * irqhelp_server_loop (void *arg); diff --git a/hurd/libmachdev.mdwn b/hurd/libmachdev.mdwn new file mode 100644 index 00000000..3f8634e4 --- /dev/null +++ b/hurd/libmachdev.mdwn @@ -0,0 +1,28 @@ +[[!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]]."]]"""]] + +GNU/Linux is a monolithic kernel, meaning that a lot of functionality +is baked into the kernel, including filesystems like `ext4` or `xfs`. +Alternatively, the Hurd's filesystems are in userspace, but our disk +device drivers are baked into the GNU Mach kernel image (via +[[DDE|hurd/dde]]). With [[rumpdisk|hurd/rump/rumpdisk]], the Hurd can +use SSDs with userspace device drivers! RumpDisk uses `libmachdev` as +a helper library. + +`libmachdev` exposes devices to userspace via some Mach `device-*` RPC +calls. `libmachdev` provides a trivfs that intercepts the +`device_open` RPC, which the `/dev` node uses. It also fakes a +filesystem node, so you can mount a `netfs` onto it. You still have +to implement `device_read` and `device_write` yourself, but that code +runs in userspace. An example of this can be found in +`rumpdisk/block-rump.c`. + +If [[serverboot V2|open_issues/serverbootv2]] is written, then +`libmachdev` could be simplified or maybe removed. diff --git a/hurd/porting/guidelines.mdwn b/hurd/porting/guidelines.mdwn index d132f516..624f7fd5 100644 --- a/hurd/porting/guidelines.mdwn +++ b/hurd/porting/guidelines.mdwn @@ -132,7 +132,7 @@ If you get Bad File Descriptor error when trying to read from a file (or accessi <http://pubs.opengroup.org/onlinepubs/009695399/basedefs/limits.h.html> -Also see <https://eklitzke.org/path-max-is-tricky> +Also see <https://eklitzke.org/path-max-is-tricky> and <https://insanecoding.blogspot.com/2007/11/pathmax-simply-isnt.html> Every unconditionalized use of `PATH_MAX`, `MAX_PATH` or `MAXPATHLEN` is a POSIX incompatibility. If there is no upper limit on the length of a path (as its the case for GNU), this symbol is not defined in any header file. Instead, you need to either use a different implementation that does not rely on the length of a string or use `sysconf()` to query the length at runtime. If `sysconf()` returns -1, you have to use `realloc()` to allocate the needed memory dynamically. Usually it is thus simpler to just use dynamic allocation. Sometimes the amount is actually known. Else, a geometrically growing loop can be used: for instance, see [Pulseaudio patch](http://bugs.debian.org/cgi-bin/bugreport.cgi?msg=5;filename=patch-pulse;att=1;bug=522100). Note that in some cases there are GNU extensions that just work fine: when the `__GLIBC__` macro is defined, `getcwd()` calls can be just replaced by `get_current_dir_name()` calls. @@ -142,10 +142,10 @@ for a potential corresponding `PATH_MAX` macro. They are not a replacement for Note 2: Yes, some POSIX functions such as `realpath()` actually assume that `PATH_MAX` is defined. This is a bug of the POSIX standard, which got fixed in -POSIX 2001, in which one can simply pass `NULL` to get a dynamically +POSIX 2008, in which one can simply pass `NULL` to get a dynamically allocated buffer. One can thus use: - #if _POSIX_VERSION >= 200112 || defined(__GLIBC__) + #if _POSIX_VERSION >= 200809 || defined(__GLIBC__) char *path = realpath(orig, NULL); #else char path[PATH_MATH]; diff --git a/hurd/porting/system_api_limitations.mdwn b/hurd/porting/system_api_limitations.mdwn index 1615ccc0..5fe13fdb 100644 --- a/hurd/porting/system_api_limitations.mdwn +++ b/hurd/porting/system_api_limitations.mdwn @@ -22,8 +22,5 @@ These are the known system API limits that have porting implications. **_[\#47998](http://bugs.debian.org/47998): `msgget` IPC not implemented_** -**_[[nice() doesn't work|open_issues/nice_vs_mach_thread_priorities]]_**. - **_[\#187391](http://bugs.debian.org/187391): libc0.3-dev: `sockaddr_un.sun_path` can't be assigned a `const char *` when compiling with g++_**<br />**breaks:** fam, gail<br />**status:** maybe this should be in [[PortingIssues]] (see _long_ bug log) -**_[\#190367](http://bugs.debian.org/190367): libc0.3-dev: `fcntl` `F_GETLK` not implemented (`ENOSYS`)_**<br />**breaks:** gnome-session (and others) from running<br />**error:** misc lock-related errors diff --git a/hurd/rump.mdwn b/hurd/rump.mdwn new file mode 100644 index 00000000..401634bd --- /dev/null +++ b/hurd/rump.mdwn @@ -0,0 +1,82 @@ +[[!meta copyright="Copyright © 2009, 2010, 2011, 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 stable_URL]] + + * [[community/gsoc/project ideas/driver glue code]] + + * [[open issues/user-space device drivers]] + + * [[open issues/device drivers and io systems]] + +--- + +The rump kernels provide existing real world drivers from netbsd. +Since [[DDE]] no longer seems like a promising approach to get drivers +for the Hurd, it appears that rump kernels are the best alternative. +It already does the hard work of providing an environment where the +foreign drivers can run, and offers the additional benefit of being +externally maintained. Rump also offers the necessary facilities for +running all drivers in separate userspace processes, which is more +desirable than drivers running in the microkernel. + +A rump kernel is a minimal and portable NetBSD kernel running in +userspace. Rump kernels provide drivers for modern hard drives, sound +cards, usb support, and a TCP/IP stack. Instead of re-inventing and +maintaining drivers ourselves, we can re-use the existing NetBSD +drivers. + +Hurd developers have enabled experimental support for modern hard +drives with a rump kernel. We call it +[[rumpdisk|hurd/rump/rumpdisk]], and you can try it in the [[Debian +GNU/Hurd image|hurd/running/qemu]]. + +As of May 2023, Hurd users are having good success with it in qemu +environments and some are using it on real hardware! + +We do hope to use rump kernels for usb support, sound support (this +was working at some point), and possibly a new TCP/IP stack, but work +has not completed on those projects. + +# Rump kernels + + * [[rumpdisk|rump/rumpdisk]] HHD/SSD/NVMe device drivers + + * [[rumpfs|rump/rumpfs]] using NetBSDs filesystems (FFS) + + * [[rumpnet|rump/rumpnet]] wifi/ethernet device drivers + + * [[rumpsound|rump/rumpsound]] audio device drivers + + * [[rumpusbdisk|rump/rumpusbdisk]] accessing external SATA devices + +# Documentation + + * <http://www.fixup.fi/misc/usenix-login-2015/login_oct15_02_kantee.pdf> + + This is an an opinion paper that explains why operating systems need compartmentalized kernel drivers. + + * <https://github.com/rumpkernel/wiki/wiki/Tutorial:-Getting-started> + + A tutorial introduction for those interested in using and deploying rump kernels. + + * <https://netbsd.org/docs/rump/sptut.html> + + Another tutorial on rump kernel servers and clients. + + * <https://core.ac.uk/display/41816390> + + "User space approach to audio device driving on UNIX-like systems" by Robert Millan Hernandez. + + +# Source Code + + * <https://github.com/rumpkernel> diff --git a/hurd/rump/rumpdisk.mdwn b/hurd/rump/rumpdisk.mdwn new file mode 100644 index 00000000..33e37ff7 --- /dev/null +++ b/hurd/rump/rumpdisk.mdwn @@ -0,0 +1,62 @@ +[[!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 stable_URL]] + +# RumpDisk + +The Hurd supports modern SATA devices like SSDs with RumpDisk. If you +successfully installed the Hurd in real hardware, via toggling the +"compatibility" mode in your BIOS, then the Hurd is probably using old +Linux drivers to access your hard drive/SSD. Even more problematic, +those drivers are baked into the GNU Mach kernel! With rumpdisk, you +can use SSDs on the Hurd and enjoy a max partition size of [[2 +TiB|faq/2_gib_partition_limit]]! + +If you want to test if the Hurd can boot with your SSD, change any +occurence of `hdN` in `/boot/grub/grub.cfg` to `wdN`, where `N` is a +number, and add the `noide` option on the `multiboot` line, +(which disables the old Linux disk drivers). Also change any occurence +of `hdN` in your `/etc/fstab` to `wdN`. + + /boot/grub/grub.cfg + + # multiboot /boot/gnumach-1.8-486.gz root=part:2:device:hd0 console=com0 + multiboot /boot/gnumach-1.8-486.gz root=part:2:device:wd0 console=com0 noide + + /etc/fstab + + #/dev/hd0s2 / ext2 defaults 0 1 + /dev/wd0s2 / ext2 defaults 0 1 + #/dev/hd0s1 none swap sw 0 0 + /dev/wd0s1 none swap sw 0 0 + #/dev/hd2 /media/cdrom0 iso9660 noauto 0 0 + /dev/wd2 /media/cdrom0 iso9660 noauto 0 0 + +Then reboot your machine. Before Grub appears change "compatibility" +in your BIOS to "AHCI" (not "RAID"). If you successfully boot, +congrats! You are now using rumpdisk! You can permanently add in the +"noide" option to grub: + + /etc/default/grub + + # make sure you add this next line somewhere in the file + GRUB_CMDLINE_GNUMACH="noide" + +Now you can run `update-grub`. That way when you update the kernel, +you can be sure to use rumpdisk. + +rumpdisk is normally already set up on `/dev/rumpdisk`. + + $ showtrans /dev/rumpdisk + /hurd/rumpdisk + +[[!inline pages=open_issues/running_rump_for_slash raw=yes feeds=no]] diff --git a/hurd/rump/rumpfs.mdwn b/hurd/rump/rumpfs.mdwn new file mode 100644 index 00000000..8236defa --- /dev/null +++ b/hurd/rump/rumpfs.mdwn @@ -0,0 +1,31 @@ +[[!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 stable_URL]] + +# What is rumpfs? + +`Rumpfs` would let us use the [[NetBSD +filesystems|https://man.netbsd.org/fstab.5]], namely FFS, which is a +journaled filesystem that supports snapshots. This is a significant +improvement over the Hurd's current filesystem: +[[ext2|hurd/translator/ext2fs]], which forces users to deal with +occassional filesystem corruption. With FFS, this would no longer be +an issue, and NetBSD developers would maintain the FFS codebase. + +As of October 2024, rumpfs still needs to be implemented. + +Another option is to create an ext3fs. We have a +[[task|https://savannah.gnu.org/task/?5498]] for this, which mentions +some existing experimental code. + +Another option is to create translators out of +[[libguestfs|hurd/translator/libguestfs]]. diff --git a/hurd/rump/rumpnet.mdwn b/hurd/rump/rumpnet.mdwn new file mode 100644 index 00000000..5ea3ba61 --- /dev/null +++ b/hurd/rump/rumpnet.mdwn @@ -0,0 +1,22 @@ +[[!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 stable_URL]] + +# RumpNet + +Hurd developers want to use rumpnet, so that we can use modern +ethernet and wifi device drivers. The Hurd is currently using Linux's +old TCP/IP stack (`pfinet`) and device drivers. We plan to replace +`pfinet` with [[lwip|hurd/translator/lwip]] and use rumpnet's modern +device drivers for ethernet and wifi hardware. Alternatively, we +could use rump's TCP/IP stack. + diff --git a/hurd/rump/rumpsound.mdwn b/hurd/rump/rumpsound.mdwn new file mode 100644 index 00000000..f8f113e6 --- /dev/null +++ b/hurd/rump/rumpsound.mdwn @@ -0,0 +1,25 @@ +[[!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 stable_URL]] + +rumpsound lets us use audio devices on the Hurd. There is an +experimental/basic [[hurd rump audio +translator|https://github.com/dm0-/hurd-rump-audio]] that exists. The +translator runs at `/dev/audio`, which is somehow similiar to a +Solaris audio device. Any application that supports pulseaudio, can +play through this device. + +Some Hurd developers, believe that pulseaudio may not be the best +choice for supporting sound on the Hurd. Damien Zammit has several +[[ideas|https://lists.gnu.org/archive/html/bug-hurd/2019-11/msg00086.html]] +how to get proper sound support on the Hurd. The [[audio +page|open_issues/audio]] has more information. diff --git a/hurd/rump/rumpusbdisk.mdwn b/hurd/rump/rumpusbdisk.mdwn new file mode 100644 index 00000000..8463e670 --- /dev/null +++ b/hurd/rump/rumpusbdisk.mdwn @@ -0,0 +1,26 @@ +[[!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 stable_URL]] + +# RumpUSBDisk + +With RumpUSBDisk, the Hurd can use a usb to SATA dongle to access a +SATA device. StarTech offers a good quality dongle that works +well. The Hurd could then read/write data from a SATA device with an +fatfs or ext2 filesystem. Damien Zammit implemented [[rumpusbdisk +already|https://lists.gnu.org/archive/html/bug-hurd/2023-07/msg00025.html]]. +However, as of October 2024, netdde seems to exhibit a bug when +running `ifdown /dev/eth0` simultaneously to running the rumpusbdisk +translator, due to the two devices sharing the same IRQ. + + + diff --git a/hurd/running/Guix.mdwn b/hurd/running/Guix.mdwn index 64f9d0e7..30b7b62a 100644 --- a/hurd/running/Guix.mdwn +++ b/hurd/running/Guix.mdwn @@ -9,11 +9,59 @@ GNU/Hurd support has been integrated in Guix. --- # Documentation -As Hurd support is integrated in Guix, the official documentation (<https://guix.gnu.org/en/manual/devel/>) also works for Hurd. +As Hurd support is integrated in Guix, the [official +documentation](https://guix.gnu.org/manual/en/html_node/) also works +for Hurd. -Guix has even support in its configuration language for creating Hurd VMs from a running Guix system (<https://guix.gnu.org/en/manual/devel/en/guix.html#The-Hurd-in-a-Virtual-Machine>). - ---- # Status -At the time of writing, the official Guix manual says that "This configuration is experimental and under development. The easiest way for you to give it a try is by setting up an instance of hurd-vm-service-type on your GNU/Linux machine (see hurd-vm-service-type). See Contributing, on how to help!" (<https://guix.gnu.org/en/manual/devel/en/guix.html#GNU-Distribution>). +At the time of writing the Guix manual says "This configuration is +experimental and under development. … See +[Contributing](https://guix.gnu.org/manual/en/html_node/Contributing.html), +on how to help!" + +The easiest way to try Guix/Hurd is by setting up a Guix Childhurd +instance on your GNU/Linux machine. + +Cross-building to x86_64-gnu [has just landed on Guix +master](https://lists.gnu.org/archive/html/guix-patches/2024-12/msg00199.html). + +# Childhurds + +Guix' operating-system description supports a [`hurd-vm` +or *childhurd* service](https://guix.gnu.org/manual/devel/en/html_node/Virtualization-Services.html#The-Hurd-in-a-Virtual-Machine). +Specifying the `hurd-vm-service-type` in the `services` of an `operating system` description + + (operating-system + ;; … + (services + (list + ;; Add the 'hurd-vm' service + (service hurd-vm-service-type) + … + %base-services))) + +automagically builds and starts a `Childhurd` that can be also used +for +[offloading](https://guix.gnu.org/manual/en/html_node/Daemon-Offload-Setup.html) +Hurd builds. + +# Rumpdisk and NetDDE support + +Guix supports NetDDE and Rumpdisk, also [running in a +Childhurd](https://toot.aquilenet.fr/@civodul/110848429561223704). + +# Guix/Hurd on Real Iron + +Guix/Hurd has been [ installed on a Thinkpad +X60](https://todon.nl/@janneke/110451493405777898). + +The Guix installer supports cross-installation support for Guix/Hurd. + +Of course Guix/Hurd can also be installed from a running GNU/Linux +system by doing something like: + + guix system init hurd.scm /hurd + +An blog post was published about running [Guix/Hurd on a Thinkpad +X60](https://guix.gnu.org/blog/2024/hurd-on-thinkpad/). diff --git a/hurd/running/debian/CrossInstall.mdwn b/hurd/running/debian/CrossInstall.mdwn index 26cd77af..0f56a3e7 100644 --- a/hurd/running/debian/CrossInstall.mdwn +++ b/hurd/running/debian/CrossInstall.mdwn @@ -56,13 +56,6 @@ Ah, reboot and select "GNU (kernel GNUmach 1.3)" from the Grub menu. At the prom # export TERM=mach # ./native-install -When done the native install requests that you reboot once again and rerun native-install. - - # reboot - ... - # export TERM=mach - # ./native-install - Done, continue setting up your system. ---- 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/debian/patch_submission.mdwn b/hurd/running/debian/patch_submission.mdwn index d1a3ba33..e8c8aab0 100644 --- a/hurd/running/debian/patch_submission.mdwn +++ b/hurd/running/debian/patch_submission.mdwn @@ -18,9 +18,9 @@ package, or otherwise frequently used package, or you know upstream anyway. If you had to change the code considerably and are not 100% sure you did not introduce a regression, or are not very experienced with these kinds of code -changes, you should first submit your patch for review to the [Debian alioth -patch -tracker](http://alioth.debian.org/tracker/?atid=410472&group_id=30628&func=browse). +changes, you should first submit your patch for review to +[[https://salsa.debian.org/hurd-team/hurd/|https://salsa.debian.org/hurd-team/hurd/]]. Its +documentation is available [[here|https://wiki.debian.org/Salsa]]. If the patch is trivial, or one of the Debian porters approved your patch for submission, submit the patch to the Debian BTS (bug tracking system). You can diff --git a/hurd/running/debian/porting.mdwn b/hurd/running/debian/porting.mdwn index 77519c8f..28fcb9b4 100644 --- a/hurd/running/debian/porting.mdwn +++ b/hurd/running/debian/porting.mdwn @@ -17,9 +17,9 @@ More than half of the Debian archive has been compiled successfully on the Hurd, however, many programs fail to build for various reasons. A [list of build failures including error -messages](https://people.debian.org/~sthibault/failed_packages.txt) can be +messages](https://people.debian.org/~sthibault/hurd-i386/failed_packages.txt) can be found, as well as a [preliminary -analysis](http://lists.debian.org/debian-hurd/2007/07/msg00000.html) of them and [solutions](http://lists.debian.org/debian-hurd/2007/07/msg00001.html), and some more details in [[hurd/porting/guidelines]]. [Graphs and statistics](http://people.debian.org/~sthibault/) about the consequence in terms of build dependencies are available. +analysis](http://lists.debian.org/debian-hurd/2007/07/msg00000.html) of them and [solutions](http://lists.debian.org/debian-hurd/2007/07/msg00001.html), and some more details in [[hurd/porting/guidelines]]. [Graphs and statistics](http://people.debian.org/~sthibault/hurd-i386/) about the consequence in terms of build dependencies are available. There is a mailing list, [debian-hurd-build-logs](http://lists.alioth.debian.org/mailman/listinfo/debian-hurd-build-logs), diff --git a/hurd/running/debian/qemu_image.mdwn b/hurd/running/debian/qemu_image.mdwn index 9984ac33..8409bc8c 100644 --- a/hurd/running/debian/qemu_image.mdwn +++ b/hurd/running/debian/qemu_image.mdwn @@ -42,7 +42,7 @@ Optionally you may use `--curses` to keep your keyboard layout. If need be modpr Note that if you do not have a command named `kvm`, you can try something across the lines of: - $ qemu-system-i386 --enable-kvm -drive cche=writeback,file=$(echo debian-hurd-*.img) -net user,hostfwd=tcp:127.0.0.1:2222-:22 -net nic,model=e1000 + $ qemu-system-i386 --enable-kvm -drive cache=writeback,file=$(echo debian-hurd-*.img) -net user,hostfwd=tcp:127.0.0.1:2222-:22 -net nic,model=e1000 Or, if your machine does not allow for KVM acceleration, omit `--enable-kvm` from the command. diff --git a/hurd/running/gnu.mdwn b/hurd/running/gnu.mdwn index 964e7e8e..b45841df 100644 --- a/hurd/running/gnu.mdwn +++ b/hurd/running/gnu.mdwn @@ -2,31 +2,32 @@ # <a name="The_GNU_Operating_System"> </a> The GNU Operating System -The GNU Operating System, Commonly referred to as simply "The GNU System", is a +The GNU Operating System, commonly referred to as simply "The GNU System", is a complete [[Unix]]-like operating system composed entirely of [free software](http://www.gnu.org/philosophy/free-sw.html). The creation of the GNU System is one of the goals of the [GNU Project](http://www.gnu.org/), which was [launched in 1983](http://www.gnu.org/gnu/initial-announcement.html) by -[Richard Stallman](http://www.stallman.org/). It has many ambitious goals that -the GNU/Hurd intends to address. - -These goals include increased security through the [[principle of least -privilege|https://en.wikipedia.org/wiki/Principle%5Fof%5Fleast%5Fprivilege]], an -[[extensible system|extensibility]], conformation to open operating standards -including [[POSIX|https://en.wikipedia.org/wiki/POSIX]], modularity, and -respecting user freedom. Many of these goals are things that the GNU/Hurd can -resolve, however the GNU/Hurd is not the most stable operating system yet. +[Richard Stallman](http://www.stallman.org/). The GNU/Hurd intends to +increase security through the [[principle of least +privilege|https://en.wikipedia.org/wiki/Principle%5Fof%5Fleast%5Fprivilege]], provide an +[[extensible system|extensibility]], conform to open operating standards +including [[POSIX|https://en.wikipedia.org/wiki/POSIX]], contain a modular code-base, and +[[respect user freedom|https://www.gnu.org/philosophy/free-sw.html]]. +Many of these goals are things that the GNU/Hurd can +resolve, however the GNU/Hurd is not yet the most stable operating system. If you are looking for a production ready GNU system, then [[hurd/running/Debian]] GNU/Hurd may -not be the best choice for you. Debian GNU/Hurd currently lacks 64-bit support, -many device drivers, sound support, SMP, and a few other essential bits that -provide a flexible operating system. +not be the best choice for you. Debian GNU/Hurd currently lacks many device drivers, sound +support, and a few other essential bits that provide a flexible operating system. +It also has some tricky [[problems|challenges]] to solve. However, [[gnu.org|https://www.gnu.org/distros/free-distros.html]] maintains a list of freedom respecting and production ready GNU/Linux systems. One of the -most promising of these is [[GuixSD|https://www.gnu.org/software/guix/]], which +most promising of these is [[Guix System|https://www.gnu.org/software/guix/]], which is the GNU Guix System Distribution, which eventually plans to support the GNU -Hurd as the kernel! +Hurd as the kernel! You can even use a +[[childhurd|https://guix.gnu.org/manual/devel/en/html_node/Virtualization-Services.html#The-Hurd-in-a-Virtual-Machine]] +on Guix System! ## Resources diff --git a/hurd/running/qemu.mdwn b/hurd/running/qemu.mdwn index 3514ac98..c56292c8 100644 --- a/hurd/running/qemu.mdwn +++ b/hurd/running/qemu.mdwn @@ -24,6 +24,56 @@ You can use the following images to give the Hurd a try. [[!inline pages=hurd/running/debian/qemu_image raw=yes feeds=no]] +#### Trying out rumpdisk + +[[Rump kernels|hurd/rump]] provide new modern drivers for the Hurd. +We refer to rumpdisk as a rump kernel that provides drivers for modern +hard drives, SSDs, etc. The Rump kernels' integration into the Hurd +are still somewhat experimental, but they seem to work fairly well on +bleeding edge Debian. + +Once you have your latest qemu Debian GNU/Hurd image running, then you +can try the rumpdisk (be sure to pass "-m 2GB" or more). First, +add these sources to your /etc/apt/sources.list + + deb http://deb.debian.org/debian-ports unstable main + deb-src http://deb.debian.org/debian unstable main + deb http://deb.debian.org/debian-ports unreleased main + +Then, upgrade to the bleeding edge Debian GNU/Hurd: + + # apt update + # apt upgrade --without-new-pkgs + # apt dist-upgrade + +Now test to see if the rump kernel works before you make the change +permanent. Manually tweak your /boot/grub/grub.cfg like so: + + # multiboot /boot/gnumach-1.8-486.gz root=part:2:device:hd0 console=com0 + multiboot /boot/gnumach-1.8-486.gz root=part:2:device:wd0 console=com0 noide + +and your /etc/fstab + + #/dev/hd0s2 / ext2 defaults 0 1 + /dev/wd0s2 / ext2 defaults 0 1 + #/dev/hd0s1 none swap sw 0 0 + /dev/wd0s1 none swap sw 0 0 + #/dev/hd2 /media/cdrom0 iso9660 noauto 0 0 + /dev/wd2 /media/cdrom0 iso9660 noauto 0 0 + +Now you can poweroff your machine, reboot, and start using the +rumpdisk! You can make these changes permanent by tweaking +/etc/default/grub and telling it to use rumpdisk: + + GRUB_CMDLINE_GNUMACH="noide" + +Then update your grub: + + # update-grub + +Check that "noide" does appear in your /boot/grub/grub.cfg. + + ## Arch Hurd Live CD [[!inline pages=hurd/running/live_cd raw=yes feeds=no]] @@ -252,7 +302,7 @@ If you are on [[Debian GNU/Hurd|debian]], you can even use [[debian/DHCP]]. To get ssh working: - # apt install random-egd openssh-server (Similarly for telnet if preferred) + # apt install openssh-server (Similarly for telnet if preferred) (See also <http://www.nongnu.org/qemu/qemu-doc.html#SEC32>.) @@ -355,7 +405,7 @@ Once you have logged in as `root` run the `pfinet` translator with values that a That should do it! Do not forget to edit/update `/etc/resolv.conf` to get DNS working. --- -# Multiboot +# Booting Hurd without grub, using qemu's multiboot support See "Linux/Multiboot boot specific" section on QEMU manpage. @@ -374,18 +424,15 @@ you'll get told: *qemu: linux kernel too old to load a ram disk*. $ qemu [...] \ > --kernel gnumach \ + > --append 'root=device:hd0s1' \ > --initrd \ - > 'ext2fs.static --multiboot-command-line=${kernel-command-line} --host-priv-port=${host-port} --device-master-port=${device-port} --exec-server-task=${exec-task} -T typed device:hd0s1 $(task-create) $(task-resume)',\ + > 'ext2fs.static --multiboot-command-line=${kernel-command-line} --host-priv-port=${host-port} --device-master-port=${device-port} --exec-server-task=${exec-task} -T typed ${root} $(task-create) $(task-resume)',\ > 'exec.static $(exec-task=task-create)' Note that, contrary to [[GRUB]]'s configuration file, you don't specify "`argv[0]`" here, and it's fortunate that neither ext2fs nor exec need a comma on their command line... -You can also use `--append [...]`, which will show up in `/proc/cmdline`. - -Command line above crashes with old qemu versions, for instance qemu 1.1.2 on Debian Wheezy, fixed by upgrading to wheezy-backports currently qemu 1.7.0, see [[!debbug 741873]] - --- # Related Links 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/running/virtualbox.mdwn b/hurd/running/virtualbox.mdwn index b48f7ebd..cf9a5870 100644 --- a/hurd/running/virtualbox.mdwn +++ b/hurd/running/virtualbox.mdwn @@ -11,8 +11,23 @@ License|/fdl]]."]]"""]] [[!meta title="VirtualBox"]] -<http://www.virtualbox.org/> - +Some people are very familiar with using VirtualBox to run virtual machines of OS +like GNU/Linux, Windows, etc. Hurd CAN also be run with VirtualBox normally, and +the way is very similar to running other OS with it. The main problem may be that +Hurd may not support as many emulated hardware as others, which is also a good +point to help us. + +This also provides a good opportunity for people who want to play with Hurd on +every other OS which can run VirtualBox. You can absolutely run and develop Hurd +without switching your current OS or running a nest Hurd in another virtual machine. + +If you happen to have experience on developing GNU/Linux on other OS like +Windows, you can develop Hurd smoothly just like before. We might recommend that +you use a FSF approved operating system to get better experience of developing +Hurd, but if for some reason you are stuck using Windows, this won't be an +unsolvable obstacle. + +You can download VirtualBox at <http://www.virtualbox.org/>. # Installation diff --git a/hurd/status.mdwn b/hurd/status.mdwn index bc04d78d..28919995 100644 --- a/hurd/status.mdwn +++ b/hurd/status.mdwn @@ -34,6 +34,8 @@ drivers, and experimental support for SATA devices was added in May 2013. Robert Millan worked on a port of the Rump kernel, which allowed to run a sound driver in userland. This work now needs to be extended. Support for character devices and other hardware (USB, multicore) is mostly missing. +Damien Zammit added [[RumpDisk|hurd/rump/rumpdisk]], which lets the Hurd +boot and use SSDs with a minimal NetBSD kernel running in userspace. Although the [[POSIX interface|faq/posix_compatibility]] is provided, some additional interfaces @@ -56,14 +58,28 @@ official Debian release), in April 2015 the [[Debian GNU/Hurd|hurd/running/debian]] team released [[Debian GNU/Hurd 2015|news/2015-04-29-debian_gnu_hurd_2015]]. Similarly, along Debian "stretch", in June 2017 [[Debian GNU/Hurd 2017|news/2017-06-18-debian_gnu_hurd_2017]] was released. +The latest release is from +[[2023|https://darnassus.sceen.net/~hurd-web/news/2023-06-11-debian_gnu_hurd_2023/]]. + +With [[Guix System|hurd/running/guix]] one can trivially run a childhurd or a +hurd vm running atop GNU/Linux. The adventurous can run it on +[[real iron|https://guix.gnu.org/blog/2024/hurd-on-thinkpad/]]. [[hurd/running/Arch_Hurd]] offers *LiveCDs* for testing and installation. [[hurd/running/Nix]] provides QEMU images. - ## Usability Reports +### Joshua Branson, 2025-04-30 + +I've had my T43 Thinkpad with 1.5 GB of RAM running Debian GNU/Hurd +for about a year now. I use a combination of the i3 window +manager, emacs, git, the netsurf web browser, and a terminal to edit +this wiki. The Hurd is fairly stable, but it tends to lock up on me +about once a month. While I am fairly certain that I have had some +filesystem corruption, I have not noticed any lost files yet. + ### Svante Signell, 2013-05-21 I have been running GNU/Hurd for some years now, with VMs, mainly in the diff --git a/hurd/subhurd.mdwn b/hurd/subhurd.mdwn index 9b196f2d..d24369bc 100644 --- a/hurd/subhurd.mdwn +++ b/hurd/subhurd.mdwn @@ -37,6 +37,11 @@ boot it: $ gunzip debian-hurd.img.gz $ boot --kernel-command-line="fastboot root=pseudo-root" -T typed part:1:file:debian-hurd.img +/!\ If you face an error from the mach-defpager (most probably +because there is already a default pager), you can comment +the part that says `/hurd/mach-defpager` from the `/etc/hurd/runsystem.sysv` file +included within the `debian-hurd.img` file you are trying to use. + The 'fastboot' is necessary to skip the filesystem check which fails because the image assumes the root filesystem to be /etc/hd0s1. Once booted, you can correct this: 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.mdwn b/hurd/translator.mdwn index dad26881..fe669a12 100644 --- a/hurd/translator.mdwn +++ b/hurd/translator.mdwn @@ -89,26 +89,39 @@ The [[concept|concepts]] of translators creates its own problems, too: * [[hello]] * [[auth]] +* [[devnode]] * [[exec]] +* [[ifsock]] +* [[password]] * [[proc]] +* [[procfs]] * [[pfinet]] +* [[proxy-defpager]] * [[lwip]] * [[eth-filter]] +* [[eth-multiplexer]] * [[pflocal]] * [[hostmux]] +* [[startup]] * [[storeio]] +* [[streamio]] * [[ext2fs]] * [[fatfs]] -* [[ufs]] +* [[ftpfs]] * [[magic]] * [[mtab]] +* [[pci-arbiter]] +* [[remap]] * [[unionfs]] * [[nfs]] * [[symlink]] +* [[fakeroot]] * [[firmlink]] * [[fifo]] * [[term]] * [[checkperms]] +* [[usermux]] +* [[rtc]] * ... diff --git a/hurd/translator/cvsfs.mdwn b/hurd/translator/cvsfs.mdwn index 11c9c01f..9cbe7840 100644 --- a/hurd/translator/cvsfs.mdwn +++ b/hurd/translator/cvsfs.mdwn @@ -49,7 +49,7 @@ Happy Hacking. ## References * <http://www.nongnu.org/hurdextras/> - * <http://cvs.sv.nongnu.org/viewcvs/*checkout*/cvsfs/README?root=hurdextras> + * <http://cvs.savannah.gnu.org/viewcvs/*checkout*/cvsfs/README?root=hurdextras> ### Old version at Berlios diff --git a/hurd/translator/devnode.mdwn b/hurd/translator/devnode.mdwn new file mode 100644 index 00000000..24c84a7e --- /dev/null +++ b/hurd/translator/devnode.mdwn @@ -0,0 +1,19 @@ +[[!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 stable_URL]] + +`devnode` is the Hurd devnode translator. It exposes a Mach device as +a filesystem node (hence "devnode"), so you can do `open("/dev/foobar")` +then `device_open("foobar")`. In particular this means that the +Unix permission model can be used to manage access to the fs node, +rather than you having to have the device master port (= be root). + diff --git a/hurd/translator/eth-multiplexer.mdwn b/hurd/translator/eth-multiplexer.mdwn new file mode 100644 index 00000000..0f7a6189 --- /dev/null +++ b/hurd/translator/eth-multiplexer.mdwn @@ -0,0 +1,35 @@ +[[!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 stable_URL]] + +The `eth-multiplexer` translator lets one share an ethernet device. +It is commonly used to set up subhurds' networking to share an +ethernet device with the subhurd and the main hurd. The [[subhurds' +page|hurd/subhurd]] has a guide to show you how to do this. + +Here's a basic example to get you started using the eth-multiplexer. +To do so, install the multiplexer at `/dev/eth0m`. + + # settrans -c /dev/eth0m /hurd/eth-multiplexer --interface=/dev/eth0 + +Then configure your main Hurd system to use the virtual network +interface `/dev/eth0m/0` instead of `/dev/eth0`. On Debian/Hurd, this +can be accomplished via: + + # ifdown /dev/eth0 + # sed -i -e s_/dev/eth0_/dev/eth0m/0_ /etc/network/interfaces + # ifup /dev/eth0m/0 + +Now you are all set to follow the [[subhurd's guide|hurd/subhurd]] to +set up a subhurd's networking! If you want to do more cool stuff with +the `eth-multiplexer`, then you could take a look at the +[[hurd/translator/lwip]] page or [[hurd/translator/remap]] page. diff --git a/hurd/translator/ext2fs.mdwn b/hurd/translator/ext2fs.mdwn index 81e54dff..3baf6b03 100644 --- a/hurd/translator/ext2fs.mdwn +++ b/hurd/translator/ext2fs.mdwn @@ -22,16 +22,68 @@ License|/fdl]]."]]"""]] * [[internal_allocator]] +## Current Limitations -## Large Stores - -The `ext2fs` translator from the upstream Hurd code base can only handle file -systems with sizes of less than roughly 2 GiB. +### Use 64 bit time by default -[[!tag open_issue_hurd]] +Extend ext2fs to support 64bit time. +## Large Stores -### Ognyan's Work +[[!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 Hurd*|ogi-fosdem2005.mgp]], 2005, at FOSDEM @@ -40,8 +92,8 @@ systems with sizes of less than roughly 2 GiB. * <http://kerneltrap.org/node/4429> -Ognyan's patch lifts this limitation (and is being used in the -[[Debian_GNU/Hurd_distribution|running/debian]]), but it introduces another +Ognyan's patch lifted this limitation (and is being used in the +[[Debian_GNU/Hurd_distribution|running/debian]]), but it introduced another incompatibility: `ext2fs` then only supports block sizes of 4096 bytes. Smaller block sizes are commonly automatically selected by `mke2fs` when using small backend stores, like floppy devices. @@ -565,18 +617,6 @@ That would be a nice improvement, but only after writeback throttling is impleme separate partitions is a way to alleviate them -## `ext2fs: ../../libdiskfs/rdwr-internal.c:42: _diskfs_rdwr_internal: Assertion `!diskfs_readonly' failed.` - -### IRC, freenode, #hurd, 2014-02-22 - - <gg0> login: init: notifying pfinet of shutdown...init: notifying tmpfs - none of shutdown...init: notifying tmpfs none of shutdown...init: - notifyi. - <gg0> ext2fs: ../../libdiskfs/rdwr-internal.c:42: _diskfs_rdwr_internal: - Assertion `!diskfs_readonly' failed. - <gg0> In tight loop: hit ctl-alt-del to reboot - - # Documentation * <http://e2fsprogs.sourceforge.net/ext2.html> diff --git a/hurd/translator/fakeroot.mdwn b/hurd/translator/fakeroot.mdwn new file mode 100644 index 00000000..59dd7ead --- /dev/null +++ b/hurd/translator/fakeroot.mdwn @@ -0,0 +1,86 @@ +[[!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 stable_URL]] + +A translator for faking privileged access to an underlying filesystem. + +This translator appears to give transparent access to the underlying +directory node. However, all accesses are made using the credentials +of the translator regardless of the client and the translator fakes +success for chown and chmod operations that only root could actually +do, reporting the faked IDs and modes in later stat calls, and allows +any user to open nodes regardless of permissions as is done for root. + +## A trivial example + +Let's demonstrate that chown and chgrp requires root permission. + + $ mkdir ~/etc + $ touch ~/etc/this + $ settrans ~/etc/this /hurd/hello + $ ls -lha ~/etc/ + total 12K + drwxr-xr-x 2 joshua joshua 4.0K Oct 15 20:12 . + drwxr-xr-x 33 joshua joshua 4.0K Oct 15 20:11 .. + -r--r--r-- 1 joshua joshua 14 Oct 15 20:12 this + $ + $ chown root ~/etc/this + chown: changing ownership of '/home/joshua/etc/this': Operation not permitted + +Now, let's run through `fakeroot-hurd`: + + $ fakeroot + # ls -lha ~/etc/ + total 12K + drwxr-xr-x 2 root root 4.0K Oct 15 20:12 . + drwxr-xr-x 33 root root 4.0K Oct 15 20:11 .. + -r--r--r-- 1 root root 14 Oct 15 20:12 this + +The shell now believes we are root, and all the owner and group are turned into +root. Now we can chmod, chown, chgrp, ... + + # chown daemon ~/etc/this + # ls -lha ~/etc/ + total 12K + drwxr-xr-x 2 root root 4.0K Oct 15 20:12 . + drwxr-xr-x 33 root root 4.0K Oct 15 20:11 .. + -r--r--r-- 1 daemon root 14 Oct 15 20:12 this + +## A manual example + +We can also attach `/hurd/fakeroot` manually to `~/etc`, and we'll be able to +use `chown`, `chgrp`, `chmod`, etc. as a normal user. + + $ settrans ~/etc /hurd/fakeroot + $ cd ~/etc + $ cd + $ showtrans ~/etc + /hurd/fakeroot + $ ls -lha ~/etc/ + + total 16K + drwxr-xr-x 2 joshua joshua 4.0K Oct 15 20:12 . + drwxr-xr-x 33 root root 4.0K Oct 15 20:11 .. + -r--r--r-- 1 root root 14 Oct 15 20:12 this + +`fakeroot` turns all the owner and group to root when it starts. Now +we can chmod, chown, and chgrp as a normal user. + + $ chown joshua ~/etc/this + $ chgrp joshua ~/etc/this + $ chmod +xr ~/etc/this + $ ls -lha ~/etc/ + total 16K + drwxr-xr-x 2 joshua joshua 4.0K Oct 15 20:12 . + drwxr-xr-x 33 root root 4.0K Oct 15 20:11 .. + -rwxr-xr-x 1 joshua joshua 14 Oct 15 20:12 this + diff --git a/hurd/translator/ftpfs.mdwn b/hurd/translator/ftpfs.mdwn new file mode 100644 index 00000000..ac04890c --- /dev/null +++ b/hurd/translator/ftpfs.mdwn @@ -0,0 +1,40 @@ +[[!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 stable_URL]] + +[[!toc]] + +The File Transfer Protocol is a old, simple, and insecure method of +sharing files between computers. The Hurd supports it via `ftpfs`. + + $ settrans gnu.org /hurd/ftpfs ftp://ftp.gnu.org + $ cat ftp\:/ftp.gnu.org/README | grep GNU | head -n 2 + This is ftp.gnu.org, the FTP server of the the GNU project. + gnu/ Contains GNU programs and documents that we develop for the GNU + +So it's actually pretty cool to use standard command line utilities to +search through a remote file. But it is slightly a hassle to set up +`ftpfs` by hand for each server like this. +With the Hurd's [[hostmux]] you can actually skip that first +settrans command, and type in any FTP server and automatically connect +to it. On my box, this just works: + + $ ls ~/ftp://ftp.gnu.org/ + +`~/ftp:` is already set up to re-route any path lookup to the correct +FTP server. You can set up `~/ftp:` on your Hurd OS via the +[[hostmux]] translator: + + $ settrans -c $HOME/ftp: /hurd/hostmux /hurd/ftpfs / + +The [[translator primer|hurd/documentation/translator_primer]] shows +you how you can use ftpfs to mount a remote iso file and examine its +contents. diff --git a/hurd/translator/httpfs.mdwn b/hurd/translator/httpfs.mdwn index 3ac9f8ab..0ce0f30b 100644 --- a/hurd/translator/httpfs.mdwn +++ b/hurd/translator/httpfs.mdwn @@ -78,11 +78,17 @@ through a proxy server, substitute your proxies IP and port no.s - query-string and fragment support - HTTP/1.1 support - HTTP/2 support -- HTTP/3 support +- HTTP/3 support (there may exist a C library that provides HTTP/[123] + support). - Teach httpfs to understand HTTP status codes like re-directs, 404 not found, etc. - Teach httpfs to look for "sitemaps". Many sites offer a sitemap, and this - would be a nifty way for httpfs to allow grep-ing the entire site's contents. + would be a nifty way for httpfs to allow grep-ing the entire site's + contents. [[sitemaps.org|https://www.sitemaps.org]] is a great resource for + this. +- Teach httpfs to check if the computer has an internet connection at + startup and during operation. The translator causes 30 second + pauses on commands like "ls", when the internet is down. # Source diff --git a/hurd/translator/ifsock.mdwn b/hurd/translator/ifsock.mdwn new file mode 100644 index 00000000..57b9a0b2 --- /dev/null +++ b/hurd/translator/ifsock.mdwn @@ -0,0 +1,16 @@ +[[!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 stable_URL]] + +Ifsock is a translator to provide Unix domain sockets. + +It acts as a hook for Unix domain sockets. The [[pflocal]] +translator, which sits on `/servers/socket/1` implements the sockets. diff --git a/hurd/translator/nsmux.mdwn b/hurd/translator/nsmux.mdwn index 6b3be79c..bef0ec0b 100644 --- a/hurd/translator/nsmux.mdwn +++ b/hurd/translator/nsmux.mdwn @@ -29,14 +29,14 @@ list. `nsmux` translator can be obtained with the following series of commands: - $ git clone git://git.sv.gnu.org/hurd/incubator.git nsmux + $ git clone git://git.savannah.gnu.org/hurd/incubator.git nsmux $ cd nsmux/ $ git checkout -b nsmux origin/nsmux `filter` translator can be obtained with the following series of commands: - $ git clone git://git.sv.gnu.org/hurd/incubator.git filter + $ git clone git://git.savannah.gnu.org/hurd/incubator.git filter $ cd filter/ $ git checkout -b filter origin/filter diff --git a/hurd/translator/password.mdwn b/hurd/translator/password.mdwn new file mode 100644 index 00000000..9a60b94c --- /dev/null +++ b/hurd/translator/password.mdwn @@ -0,0 +1,20 @@ +[[!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 stable_URL]] + +The password server (`/servers/password`) runs as root and hands out +authorization tags after receiving the correct password. The ids +corresponding to the authentication port match the unix user and group +ids. + +Support for shadow passwords is implemented here. Several utilities +make use of this server, so they don't need to be setuid root. diff --git a/hurd/translator/pci-arbiter.mdwn b/hurd/translator/pci-arbiter.mdwn new file mode 100644 index 00000000..359531b7 --- /dev/null +++ b/hurd/translator/pci-arbiter.mdwn @@ -0,0 +1,14 @@ +[[!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 stable_URL]] + +[[!inline pages=open_issues/pci_arbiter raw=yes feeds=no]] diff --git a/hurd/translator/pfinet.mdwn b/hurd/translator/pfinet.mdwn index f6ceec4f..1dd5c8b5 100644 --- a/hurd/translator/pfinet.mdwn +++ b/hurd/translator/pfinet.mdwn @@ -27,6 +27,14 @@ arguments to give it. There, `-i`, `-a`, `-g` and `-m` are, quite obviously, the (Mach) device to use, the IP address, the gateway and netmask. +You can see your currently running `pfinet`'s options via + + $ fsysopts /servers/socket/2 # provides IPv4 + /hurd/pfinet --interface=/dev/eth0 --address=ADDRESS --netmask=NETMASK --gateway=GATEWAY --address6=ADDRESS --address6=ADDRESS --gateway6=:: + + $ fsysopts /servers/socket/26 # provides IPv6 + /hurd/pfinet --interface=/dev/eth0 --address=ADDRESS --netmask=ADDRESS --gateway=GATEWAY --address6=ADDRESS --address6=ADDRESS --gateway6=:: + --- To make DNS lookups work, you'll also have to properly configure the diff --git a/hurd/translator/pfinet/ipv6.mdwn b/hurd/translator/pfinet/ipv6.mdwn index ccb359cb..d864e256 100644 --- a/hurd/translator/pfinet/ipv6.mdwn +++ b/hurd/translator/pfinet/ipv6.mdwn @@ -139,7 +139,7 @@ Indeed, IPv6 now works properly, and the very machine hosting this wiki <youpi> which repo? <youpi> I don't have such commit here <gnu_srs> - http://git.savannah.gnu.org/cgit/hurd/hurd.git/commit/?id=2b2d7fdc42475019e5ce3eabc9c9673e3c13d89f + https://git.savannah.gnu.org/cgit/hurd/hurd.git/commit/?id=2b2d7fdc42475019e5ce3eabc9c9673e3c13d89f <gnu_srs> From which release, 2.4.x, 2.6.x? <youpi> it's very old <youpi> 2002 diff --git a/hurd/translator/procfs.mdwn b/hurd/translator/procfs.mdwn index 0228d4d4..8735e88c 100644 --- a/hurd/translator/procfs.mdwn +++ b/hurd/translator/procfs.mdwn @@ -15,15 +15,15 @@ systems, and many tools concerned with process management use it. (`ps`, `top`, `htop`, `gtop`, `killall`, `pkill`, ...) Instead of porting all these tools to use [[libps]] (Hurd's official method for -accessing process information), they could be made to run out of the box, by -implementing a Linux-compatible `/proc` filesystem for the Hurd. +accessing process information), they run out of the box, via the +Hurd's Linux-compatible `procfs` at `/proc`. (On Linux, the +`/proc` filesystem is used also for debugging purposes; but this is +highly system-specific anyways, so there is probably no point in +trying to duplicate this functionality as well...) -The goal is to implement all `/proc` functionality needed for the various process -management tools to work. (On Linux, the `/proc` filesystem is used also for -debugging purposes; but this is highly system-specific anyways, so there is -probably no point in trying to duplicate this functionality as well...) +# History of procfs -Ther was an implementation in [[open_issues/HurdExtras]], +There was an implementation in [[open_issues/HurdExtras]], <http://www.nongnu.org/hurdextras/#procfs>. Madhusudan.C.S has implemented a new, fully functional [[procfs|madhusudancs]] for @@ -31,7 +31,7 @@ Madhusudan.C.S has implemented a new, fully functional [[procfs|madhusudancs]] f In August 2010, Jérémie Koenig [published another, new version](http://lists.gnu.org/archive/html/bug-hurd/2010-08/msg00165.html). -This can be found in <http://git.savannah.gnu.org/cgit/hurd/procfs.git/>. +This can be found in <https://git.savannah.gnu.org/cgit/hurd/procfs.git/>. Testing it is as simple as this: diff --git a/hurd/translator/proxy-defpager.mdwn b/hurd/translator/proxy-defpager.mdwn new file mode 100644 index 00000000..133b0e04 --- /dev/null +++ b/hurd/translator/proxy-defpager.mdwn @@ -0,0 +1,17 @@ +[[!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 stable_URL]] + +[[!toc]] + +`proxy-defpager` lets one access the control interfaces of Mach's +default pager. This translator should normally be set on +`/servers/default-pager`. diff --git a/hurd/translator/remap.mdwn b/hurd/translator/remap.mdwn new file mode 100644 index 00000000..06e3c8c5 --- /dev/null +++ b/hurd/translator/remap.mdwn @@ -0,0 +1,120 @@ +[[!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 stable_URL]] + +The remap translator lets you remap directories. This translator is to +be used as a chroot, within which paths point to the same files as the +original root, except a given set of paths, which are remapped to given +paths. + +This translator completes the [[server +overriding|community/gsoc/project_ideas/server_overriding]] google +summer of code project. + +It is often desirable to execute a command in a transitory environment +with remapped files. The `remap` script lets you do this. + +# Example Uses + +## remapping /bin/sh + +On Debian, `/bin/sh` points to `dash`. Maybe you would rather it +point to `bash`. + + $ ls -lha /bin/sh + lrwxr-xr-x 1 root root 4 Jun 5 04:08 /bin/sh -> dash + $ remap /bin/sh /bin/bash -- ls -lha /bin/sh + -rwxr-xr-x 1 root root 1,2M 20 oct. 12:53 /bin/sh + /bin/settrans: fsys_goaway: (ipc/mig) server died + +(the warning is expected, it just tells that the exected command has finished) + +## remapping python3 + +Perhaps you've want to use a python package that requires a python +feature that your distro does not yet support. Compiling this custom +python3 can be a little annoying, because `./configure` makes you +specify where all the various libraries are. It's much easier to just +remap. + + $ remap /usr/bin/python3 $HOME/bin/python3-custom -- ./configure + $ remap /usr/bin/python3 $HOME/bin/python3-custom -- cool-package + +## Run a command through a custom pflocal +<!-- https://lists.debian.org/debian-hurd/2016/08/msg00016.html --> + + $ cd /tmp + $ settrans -ac 1 ~/HURD-SRC/pflocal/pflocal + $ remap /servers/socket/1 /tmp/1 -- /bin/bash -c 'echo huhu world | wc' + 1 2 11 + +## Remapping `/servers/socket/2` and `26` for vpn/firewall + +TODO add an example here. + +## Use remap to debug lwip + +Suppose, you want to debug [[lwip|hurd/lwip]]. You could set `lwip` +on `/servers/socket/2`, but it's hard to use an OS, if your network is +buggy. It would be nice to use the stable `pfinet` and test `lwip` as +needed. You can use the `eth-multiplexer` combined with `remap` to +have such a configuration. First, use the `eth-multiplexer` to change +`pfinet`'s interface from `/dev/eth0` to `/dev/eth0m/0` + + # settrans -c /dev/eth0m /hurd/eth-multiplexer --interface=/dev/eth0 + +Now we configure own main Hurd system to use a virtual network +interface (e.g. `/dev/eth0m/0`) instead. On Debian/Hurd, this can be +accomplished using + + # ifdown /dev/eth0 + # sed -i -e s_/dev/eth0_/dev/eth0m/0_ /etc/network/interfaces + # ifup /dev/eth0m/0 + +Then you can do set up `lwip` on `~/lwip/servers/socket{2,26}` +<!-- $ settrans -ac my2 path/to/my-ipstack -what -ever; --> + + $ settrans -c ~/lwip/servers/socket/2 /hurd/lwip -i \ + /dev/eth0m/1 -4 ~/lwip/servers/socket/2 \ + -6 ~/lwip/servers/socket/26 + $ settrans -c ~/lwip/servers/socket/26 /hurd/lwip -i \ + /dev/eth0m/1 -4 ~/lwip/servers/socket/2 \ + -6 ~/lwip/servers/socket/26 + $ remap /servers/socket/2 ~/lwip/servers/socket/2 -- \ + ping -c 3 gnu.org + +If you are running the Hurd in qemu, then you can skip setting up the +`eth-multiplexer` and just configure another virtual ethernet +interface: `eth1`. Then using `lwip` is as simple as: + + $ settrans -c ~/lwip/servers/socket/2 -i /dev/eth1 \ + -4 ~/lwip/servers/socket/2 -6 ~/lwip/servers/socket/26 + $ settrans -c ~/lwip/servers/socket/26 -i /dev/eth1 \ + -4 ~/lwip/servers/socket/2 -6 ~/lwip/servers/socket/26 + $ remap /servers/socket/2 $HOME/lwip/servers/socket/2 \ + -- ping -c 3 gnu.org + +Alternatively, you could also launch a subhurd whose's networking uses +lwip. The [[subhurd]] page should give you an idea of how to do this. + +## remap example bugs + +Remap is written in a rather simplistic way. It should layer over the +filesystem in a better. These examples demonstrate some problems. + + $ remap /etc/motd /dev/null -- sh -c 'wc /etc/motd; cd /etc; wc motd;' + 0 0 0 /etc/motd + 7 40 284 motd + + $ settrans $HOME/foo /hurd/remap /bin/sh /bin/bash + $ ls $HOME/foo/ + ls: cannot open directory 'foo/': Permission denied diff --git a/hurd/translator/rtc.mdwn b/hurd/translator/rtc.mdwn new file mode 100644 index 00000000..7a917b46 --- /dev/null +++ b/hurd/translator/rtc.mdwn @@ -0,0 +1,31 @@ +[[!meta copyright="Copyright © 2025 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]]."]]"""]] + +The *rtc* translator implements a real-time clock driver. It can be used to add +the `rtc` device files, with those files, we can access the underlying +real-time clock using `ioctl()`. The description of `ioctl()` can be found +[here](https://www.gnu.org/software/libc/manual/html_node/IOCTLs.html). + +The operation macros are required to access the real-time clock. They are +defined as `RTC_*` in `hurd/rtc.h`. + +The `hwclock` command from `util-linux` can use the `rtc` device files to +access the real-time clock devices. + +# Usage Example +Setup a `rtc` device file in `/tmp`: + + settrans -c /tmp/rtc /hurd/rtc + +Read the time value through the `rtc` device file: + + int fd = open("/tmp/rtc", O_RDONLY); + struct rtc_time time; + ioctl(fd, RTC_RD_TIME, &time); diff --git a/hurd/translator/startup.mdwn b/hurd/translator/startup.mdwn new file mode 100644 index 00000000..d364c7bf --- /dev/null +++ b/hurd/translator/startup.mdwn @@ -0,0 +1,20 @@ +[[!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 stable_URL]] + +[[!toc]] + +The `startup` translator starts and maintains the hurd core servers +and system run state. It is not the service manager (like systemd). +Rather it is used in the Hurd's current [[system +bootstrap|hurd/bootstrap]], which is the process that sets up a +traditional Unix-like environment after Mach starts. + diff --git a/hurd/translator/storeio.mdwn b/hurd/translator/storeio.mdwn index 8e26a959..fc39932f 100644 --- a/hurd/translator/storeio.mdwn +++ b/hurd/translator/storeio.mdwn @@ -1,4 +1,5 @@ -[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]] +[[!meta copyright="Copyright © 2007, 2008, 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 @@ -8,7 +9,17 @@ 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]]."]]"""]] -`storeio` is a *translator for devices and other stores*. +<!-- http://richtlijn.be/~larstiq/hurd/hurd-2010-08-25 --> + +`storeio` is a translator for devices and other stores. You can use +it for user-level access to disks via `/dev/hd0s1` instead of kernel-based +device access. + + $ settrans -ca foo /hurd/storeio myfile + +Now, foo will look like a device, which gives you transparent +decompression, partition handling, etc. It is a little like Linux's +`losetup`, and you don't have to be root to use it! It relies heavily on [[libstore]]. diff --git a/hurd/translator/streamio.mdwn b/hurd/translator/streamio.mdwn new file mode 100644 index 00000000..ad40d6d0 --- /dev/null +++ b/hurd/translator/streamio.mdwn @@ -0,0 +1,23 @@ +[[!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 stable_URL]] + +<!-- http://richtlijn.be/~larstiq/hurd/hurd-2010-08-25 --> +<!-- http://richtlijn.be/~larstiq/hurd/hurd-2009-01-16 --> + +`streamio` is a translator for kernel stream devices, +e.g. the kernel log messages or the parallel port. +It is mainly used for kernel devices, so you will need root +privileges to use it. It provides a basic interface for character +devices. It is low-level and cannot provide device-specific `ioctl`s. +It cannot provide buffering, data format conversions, etc. + diff --git a/hurd/translator/symlink.mdwn b/hurd/translator/symlink.mdwn new file mode 100644 index 00000000..f5f4b03f --- /dev/null +++ b/hurd/translator/symlink.mdwn @@ -0,0 +1,23 @@ +[[!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 stable_URL]] + +The hurd `symlink` translator lets you create a filesystem node that +refers to another node. It is similar to the `ln` command. Suppose +you begin writing a new filesystem for the hurd from scratch. To +develop it quickly, you could skip implementing symlinks. The user +would instead use the `/hurd/symlink` translator. The Hurd could +provide all sorts of filesystem like functionality that would work +regardless of the user's choice of filesystem. + +Please note that [[ext2fs]] does not use `/hurd/symlink`. Instead it +supports linking directly in the filesystem, since that is faster than +using `/hurd/symlink`. diff --git a/hurd/translator/tmpfs.mdwn b/hurd/translator/tmpfs.mdwn index 3d5cb74e..4db6542b 100644 --- a/hurd/translator/tmpfs.mdwn +++ b/hurd/translator/tmpfs.mdwn @@ -20,6 +20,18 @@ system|ext2fs]] on it, having a real `tmpfs` is better, as it need not deal with the additional block-level indirection layer that `ext2` (or any other disk-based file system) imposes. -`tmpfs` generally works, although it requires root permissions for file content; -see the [[discussion]] sub-pages for the past and current issues. -There is a [[!FF_project 271]][[!tag bounty]] on this task. +`tmpfs` generally works. See the [[discussion]] sub-pages for the +past and current issues. There is a [[!FF_project 271]][[!tag +bounty]] on this task. + +## How to use tmpfs + + $ settrans -ac tmp /hurd/tmpfs 1MB + $ cd tmp + $ touch file + $ cat file + + $ echo "tmpfs rocks!" > ./file + $ cat file + tmpfs rocks! + $
\ No newline at end of file diff --git a/hurd/translator/tmpfs/discussion.mdwn b/hurd/translator/tmpfs/discussion.mdwn index 72400121..d61fd796 100644 --- a/hurd/translator/tmpfs/discussion.mdwn +++ b/hurd/translator/tmpfs/discussion.mdwn @@ -107,7 +107,7 @@ License|/fdl]]."]]"""]] <antrik> mcsim: did you publish your in-progress work? <mcsim> there is a branch with working tmpfs in git repository: - http://git.savannah.gnu.org/cgit/hurd/hurd.git/log/?h=mplaneta/tmpfs/defpager + https://git.savannah.gnu.org/cgit/hurd/hurd.git/log/?h=mplaneta/tmpfs/defpager <jd823592> sorry for interrupting the meeting but i wonder what is a lazyfs? <mcsim> jd823592: lazyfs is tmpfs which uses own pager diff --git a/hurd/translator/ufs.mdwn b/hurd/translator/ufs.mdwn deleted file mode 100644 index 4d611e95..00000000 --- a/hurd/translator/ufs.mdwn +++ /dev/null @@ -1,38 +0,0 @@ -[[!meta copyright="Copyright © 2013 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]]."]]"""]] - -The `ufs` translator supports some kind of the Unix File System. Beware, we're -not aware of anybody having used/tested it in ages, so maybe it is very broken -and will eat your data. - - -# IRC, freenode, #hurd, 2013-08-30 - -[[!tag open_issue_hurd]] - - <Arne`> There might be a copyright problem: <nalaginrut> well, there seems - BSD-4clauses in the code: - http://git.savannah.gnu.org/cgit/hurd/hurd.git/tree/ufs/alloc.c - <Arne`> braunr, tschwinge: Do you have any info on that? 4-clause BSD and - GPL on the same code are a license incompatibility… - <tschwinge> Arne`: I've put it onto my (long) TODO list. - <tschwinge> Easiest solution might be: rm -rf ufs. - <nalaginrut> will these affected code rewritten? or just modify license? - <mark_weaver> only the regents of the University of California could choose - to modify the license. - <youpi> nalaginrut: one can't modify a licence if one is not the author - <youpi> we can simply dump the code - <mark_weaver> s/author/owner/ - <tschwinge> As I suppose ufs is unused/untested for a decade or so, I'd - have no issues with simply removing it from the tree, together with - ufs-fsck and ufs-utils. - <pinotree> tschwinge: or maybe extract the ufs stuff in an own repo, to be - imported as branch in incubator or own hurd/ufs.git? - <tschwinge> Sure, why not. diff --git a/hurd/translator/unionfs.mdwn b/hurd/translator/unionfs.mdwn index 06524f3e..ce0a0f0d 100644 --- a/hurd/translator/unionfs.mdwn +++ b/hurd/translator/unionfs.mdwn @@ -15,7 +15,7 @@ License|/fdl]]."]]"""]] *Unionfs allows you to simply union one directory or translator into another one, so you see the files of both of them side by side.* -Source repository: <http://git.savannah.gnu.org/cgit/hurd/unionfs.git/> +Source repository: <https://git.savannah.gnu.org/cgit/hurd/unionfs.git/> Right now there are some problems with syncing, so please be aware that it might not work as expected. @@ -88,7 +88,7 @@ options of the `unionfs` translator. This implementation resides in the master-unionmount branch of the unionfs git repository. To checkout the code, do the following: - $ git clone git://git.sv.gnu.org/hurd/unionfs.git + $ git clone git://git.savannah.gnu.org/hurd/unionfs.git $ cd unionfs $ git checkout -b master-unionmount $ git pull origin master-unionmount diff --git a/hurd/translator/usermux.mdwn b/hurd/translator/usermux.mdwn new file mode 100644 index 00000000..84af45ed --- /dev/null +++ b/hurd/translator/usermux.mdwn @@ -0,0 +1,47 @@ +[[!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 stable_URL]] + +The word "mux" is reserved in the Hurd terminology to mean invoking +user specific translators based on the filename, which is what usermux +and [[hostmux]] do. While, `hostmux` invokes a +translator based on the host name, `usermux` invokes a +translator based on the user name. You should be able to use +`usermux` with [[nfs]]. + +## irc log 2010-08-25 + + <ArneBab> does that mean you could very easily use nfs to + automatically mount the home folders of users by just + accessing them? + <youpi> that's usermux, yes + <giselher> I am confused where is the difference ? + <youpi> usermux is specialized in user names + <youpi> i.e. it can translate it into a uid before giving it as + parameter to the underlying translator, for instance + <ArneBab> what I meant is a little different, I think: + <ArneBab> each user has his/her own computer with the disk + <ArneBab> and all can access each others folders as if they were local + <youpi> that could be done too + <youpi> it's a bit like autofs on linux + <giselher> settrans -ca nfs: /hurd/usermux /hurd/nfs server && cd nfs:/puplic + <giselher> ^-- is that right? + <ArneBab> youpi: but it can be done by anyone, not just root. + <youpi> ArneBab: sure + <youpi> giselher: I guess so + <ArneBab> and that is a huge difference. It lowers a barrier, + hopefully to such an extend that many more users can utilize it. + <anatoly> but it'll distinguish different computers? + <ArneBab> once the hurd has many more users, that is :) + <anatoly> s/but/but how + <youpi> anatoly: by a level of directories + <anatoly> cd nfs:/foo.bar:/blabla - it's how it should be? + diff --git a/hurd/translator/writing/example.mdwn b/hurd/translator/writing/example.mdwn index 0a3be4df..26a6353c 100644 --- a/hurd/translator/writing/example.mdwn +++ b/hurd/translator/writing/example.mdwn @@ -241,7 +241,7 @@ Makefile: CC = gcc MIG = mig CFLAGS = -Wall -g -D_GNU_SOURCE - LDFLAGS = -lthreads -lports -ltrivfs -lfshelp -lshouldbeinlibc + LDFLAGS = -lports -ltrivfs -lfshelp -lshouldbeinlibc -lpthread INCLUDES = -I. LCHDRS = MIGCOMSFLAGS = -prefix S_ 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..0ccead52 100644 --- a/hurd/what_is_the_gnu_hurd.mdwn +++ b/hurd/what_is_the_gnu_hurd.mdwn @@ -12,6 +12,13 @@ License|/fdl]]."]]"""]] [[!meta title="What Is the GNU Hurd?"]] The Hurd is the GNU project's replacement for the [[UNIX]] system's [[kernel]]. +There are several +[[free software operating systems|https://www.gnu.org/distros/free-distros.en.html]] +using the [[Linux kernel|https://en.wikipedia.org/wiki/Linux_kernel]]. The +Hurd is an alternate operating system that uses a different kernel. You can +read more about the status of the Hurd [[here|hurd/status]]. If you decide +to use the Hurd, then we would recommend +[[the Debian GNU/Hurd distribution|https://www.debian.org/ports/hurd/]]. The Hurd is firstly a collection of protocols formalizing how different components may interact. The protocols are designed to reduce the mutual @@ -23,7 +30,8 @@ access to its backing store and that the [[principal]] that started it own the file system node to which it connects. The Hurd is also a set of [[servers|translator]] that implement these -protocols. They include file systems, network protocols and authentication. +protocols. They include [[file systems|hurd/translator/ext2fs]], network +protocols and [[authentication|hurd/translator/auth]]. The servers run on top of the [[microkernel/Mach]] [[microkernel]] and use Mach's [[microkernel/mach/IPC]] mechanism to transfer information. @@ -33,7 +41,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 can actually access the hardware without entering kernel space +(GNU Mach). That's a lot of power for userspace! The Hurd supplies the last major software component needed for a complete [[GNU_operating_system|running/gnu]] as originally conceived by Richard @@ -44,7 +59,10 @@ organization that is the home of the [GNU project](http://gnu.org/gnu/). The Hurd development effort is a somewhat separate project from the [[Debian_GNU/Hurd|hurd/running/debian]] port. +Want to know what the Hurd can do? Read the [[status|hurd/status]] page. Read about what the GNU Hurd is [[gramatically_speaking]]. Read about the [[origin_of_the_name]]. + +Want to read more [[Hurd documentation|hurd/documentation]]? |