diff options
Diffstat (limited to 'hurd')
78 files changed, 2172 insertions, 478 deletions
diff --git a/hurd/ada4hurd.mdwn b/hurd/ada4hurd.mdwn index c783e53b..e5ef1359 100644 --- a/hurd/ada4hurd.mdwn +++ b/hurd/ada4hurd.mdwn @@ -51,7 +51,7 @@ Ada4Hurd provides tools and examples to ease Ada development in Hurd. It is at a * Install the build dependencies as root - $ apt-get install gnat libopentoken4-dev libxmlada5-dev libasis2014-dev + $ apt install gnat libopentoken4-dev libxmlada5-dev libasis2014-dev * Build @@ -65,4 +65,4 @@ Ada4Hurd provides tools and examples to ease Ada development in Hurd. It is at a * Run netfs tests * In netfs\_base directory - $ make trans\_dbg\_on
\ No newline at end of file + $ make trans\_dbg\_on diff --git a/hurd/bootstrap.mdwn b/hurd/bootstrap.mdwn index 83ad3218..875541cf 100644 --- a/hurd/bootstrap.mdwn +++ b/hurd/bootstrap.mdwn @@ -15,48 +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)' - module /lib/ld.so.1 exec /hurd/exec '$(exec-task=task-create)' + '$(fs-task=task-create)' + module /lib/ld-x86-64.so.1 exec /hurd/exec '$(exec-task=task-create)' +Note: use `ld.so.1` instead of `ld-x86-64.so.1` on 32b systems. -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. + +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. + +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` 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 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. # ext2fs initialization @@ -68,27 +135,23 @@ opening the Mach console. Since the multiboot command line is available, `diskfs_init_main` sets the ext2fs bootstrap port to `MACH_PORT_NULL`: it is the bootstrap filesystem which -will be in charge of dancing with the exec translator. +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. -ext2fs then calls `diskfs_startup_diskfs` to really run the startup. +ext2fs then calls `diskfs_startup_diskfs` to really run the startup, implemented +by the libdiskfs library. -# diskfs bootstrap +# 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`. -TODO: we want `diskfs_startup_diskfs` to also call `task_get_bootstrap_port` to -call `fsys_startup` on its real bootstrap port once `diskfs_start_bootstrap` is -finished, for bootstrap translators before the root filesystem to know when the -root filesystem is ready, and register themselves as translators in the root -filesystem, register for shutdown notification, etc. - `diskfs_start_bootstrap` starts by creating a open port on itself for the current and root directory, all other processes will inherit it. @@ -108,14 +171,14 @@ its bootstrap port. `trivfs_startup` creates a control port for the exec translator, and calls `fsys_startup` on the bootstrap port to notify ext2fs that it is ready, give it -the control port, and get back a port on the underlying node for the exec +its exec control port, and get back a port on the underlying node for the exec translator (we want to make it show up on `/servers/exec`). -# diskfs taking back control +# libdiskfs taking back control `diskfs_execboot_fsys_startup` is thus called. It calls `dir_lookup` on `/servers/exec` to return the underlying node for the exec translator, and -stores the control port in `diskfs_exec_ctl`. It can then signal `execstarted`. +stores the `exec` control port in `diskfs_exec_ctl`. It can then signal `execstarted`. `diskfs_start_bootstrap` thus takes back control, It calls `fsys_getroot` on the control port of exec, and uses `dir_lookup` and `file_set_translator` to attach @@ -125,16 +188,27 @@ it to `/servers/exec`. be specified on the multiboot command line, but otherwise it will default to `/hurd/startup`. -Now that exec is up and running, the startup process can be created with +Now that exec is up and running, the `startup` process can be created with `exec_exec`. `diskfs_start_bootstrap` takes a lot of care in this: this is the first unix-looking process, it notably inherits the root directory and current working directory initialized above, it gets stdin/out/err on the mach console. It is passed as bootstrap port a port from the `diskfs_control_class`. +`diskfs_start_bootstrap` is complete, we are back to `diskfs_startup_diskfs`, +which checks whether ext2fs was given a bootstrap port, i.e. whether +the rumpdisk translator was started before ext2fs. If so, it +calls `diskfs_call_fsys_startup` which creates a new control port and passes +it do a call to `fsys_startup` on the bootstrap port, so rumpdisk gets access +to the ext2fs filesystem. Rumpdisk however does not return any `realnode` port, +since we are not exposing the ext2fs filesystem in rumpdisk, but rather the +converse. TODO: Rumpdisk forwards this `fsys_startup` call to pci-arbiter, so +the latter also gets access to the ext2fs filesystem. + # startup startup's `main` function starts and calls `task_get_bootstrap_port` to get its -bootstrap port, and `fsys_getpriv` to get a port on the ext2fs translator. It +bootstrap port, i.e. the control port of ext2fs, and `fsys_getpriv` on it to get +the host privileged port and device master port. It clears the bootstrap port so children do not inherit it. It sets itself up with output on the Mach console, and wires itself against swapping. It requests notification for ext2fs translator dying to detect it and print a warning in @@ -148,7 +222,7 @@ startup can then complete the unixish initialization, and run `/hurd/proc` and proc's `main` function starts. It initializes itself, and calls `task_get_bootstrap_port` to get a port on startup. It can then call -`startup_procinit` to pass it the proc port that will represent the startup +`startup_procinit` on it to pass it the proc port that will represent the startup task, and get ports on the auth server, the host privileged port, and device master port. @@ -159,7 +233,7 @@ ready. auth's `main` function starts. It creates the initial root auth handle (all permissions allowed). It calls `task_get_bootstrap_port` to get a port on -startup. It can then call `startup_authinit` to pass the initial root auth +startup. It can then call `startup_authinit` on it to pass the initial root auth handle, and get a port on the proc server. It can then register itself to proc. Eventually, auth calls `startup_essential_task` to tell startup that it is ready. @@ -181,29 +255,81 @@ filesystem on `/servers/startup`. `launch_core_servers` calls `startup_authinit_reply` to actually reply to the `startup_authinit` RPC with a port on proc. -`launch_core_servers` eventually calls `fsys_init` on its bootstrap port +`launch_core_servers` eventually calls `fsys_init` on its bootstrap port, to +give ext2fs the proc and auth ports. -# diskfs taking back control +diskfs' `diskfs_S_fsys_init` thus gets called. It first replies to startup, so +startup is not stuck in its `fsys_init` call and not able to reply to RPCs. From +then on, startup will be watching for `startup_essential_task` calls from the +various bootstrap processes. -diskfs' `diskfs_S_fsys_init` gets called, it thus knows that proc and auth are -ready, and can call `exec_init`. It initializes the default proc and auth ports -to be given to processes. +# libdiskfs taking back control -diskfs calls `startup_essential_task` to tell startup that it is -ready. +In diskfs' `diskfs_S_fsys_init`, diskfs now knows that proc and auth are ready, +and can call `exec_init` on the exec port. + +# exec getting initialized + +exec's `S_exec_init` gets called from the `exec_init` call from ext2fs. Exec can +register itself with proc, and eventually call `startup_essential_task` to tell +startup that it is ready. + +# back to libdiskfs initialization + +It also calls `fsys_init` +on its bootstrap port, i.e. rumpdisk. + +# rumpdisk getting initialized + +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 +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. + +# back to rumpdisk initialization + +It gets the root node of ext2fs, sets all common ports, and install +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. + +# back to libdiskfs initialization + +It initializes the default proc and auth ports to be given to processes. + +It calls `startup_essential_task` on the startup port to tell startup that +it is ready. Eventually, it calls `_diskfs_init_completed` to finish its initialization, and notably call `startup_request_notification` to get notified by startup when the system is shutting down. -# exec taking back control - -exec's `S_exec_init` gets called, it can register itself with proc, and -eventually call `startup_essential_task` to tell startup that it is ready. - # startup monitoring bootstrap progress -As mentioned above, the different essential tasks (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 @@ -211,6 +337,7 @@ system. Once all of proc, auth, exec have called `startup_essential_task`, startup replies to their respective RPCs, so they actually start working altogether. It -also calls `launch_system`, which calls `launch_something`, which "launches +also calls `init_stdarrays` which sets the initial values of the standard exec data, and `frob_kernel_process` to plug the kernel task into the picture. +It eventually calls `launch_something`, which "launches something", which by default is `/libexec/runsystem`, but if that can not be found, launches a shell instead, so the user can fix it. diff --git a/hurd/building.mdwn b/hurd/building.mdwn index 31d909e5..ef8c94d1 100644 --- a/hurd/building.mdwn +++ b/hurd/building.mdwn @@ -24,8 +24,8 @@ Building the Hurd requires the *build-essential* and *fakeroot* packages, their dependencies and additional packages that are specified by the source hurd package: - # apt-get install build-essential fakeroot - # apt-get build-dep hurd + # apt install build-essential fakeroot quilt + # apt build-dep -y hurd gnumach ## ... on non-Debian systems @@ -36,14 +36,18 @@ 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): - $ apt-get source hurd + $ git clone https://salsa.debian.org/hurd-team/hurd.git -Please see the Debian [[FAQ]] before using `apt-get source`. +Or you could use apt source + + $ apt source hurd + +Please see the Debian [[FAQ]] before using `apt source`. The unpacked source tree is around 20 MiB, and the build tree (configured with `--disable-profile`) is around 100 MiB. @@ -93,6 +97,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 dd36f1f5..10a7910b 100644 --- a/hurd/dde/guide.mdwn +++ b/hurd/dde/guide.mdwn @@ -58,11 +58,11 @@ Download the packages for offline installation: $ cd /mnt - $ apt-get -c etc/apt/apt.conf.offline update + $ apt -c etc/apt/apt.conf.offline update - $ apt-get -c etc/apt/apt.conf.offline build-dep hurd gnumach + $ apt -c etc/apt/apt.conf.offline build-dep hurd gnumach - $ apt-get -c etc/apt/apt.conf.offline install git-core build-essential libpciaccess-dev libpcap0.8-dev hurd-dev zlib1g-dev + $ apt -c etc/apt/apt.conf.offline install git-core build-essential libpciaccess-dev libpcap0.8-dev hurd-dev zlib1g-dev Get DDE code: @@ -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 @@ -117,9 +117,9 @@ so we can boot into Hurd to do the actual work. Once there, install the packages previously downloaded (again as root): - $ apt-get build-dep hurd gnumach + $ apt build-dep hurd gnumach - $ apt-get install git-core build-essential libpciaccess-dev libpcap0.8-dev hurd-dev zlib1g-dev + $ apt install git-core build-essential libpciaccess-dev libpcap0.8-dev hurd-dev zlib1g-dev Make sure we can build stuff as normal user: diff --git a/hurd/debugging/glibc.mdwn b/hurd/debugging/glibc.mdwn index a409f392..a5515e29 100644 --- a/hurd/debugging/glibc.mdwn +++ b/hurd/debugging/glibc.mdwn @@ -23,9 +23,11 @@ newly created libraries and loader actually work: they'll be used to run the `rpcgen` program. If that step doesn't succeed, it'll look similar to this: [...] - CPP='gcc -E -x c-header' [...]/build/elf/ld.so.1 --library-path [...] [...]/build/sunrpc/rpcgen [...] + CPP='gcc -E -x c-header' [...]/build/elf/ld-x86-64.so.1 --library-path [...] [...]/build/sunrpc/rpcgen [...] Segmentation fault +Note: use `ld.so.1` instead of `ld-x86-64.so.1` on 32b systems. + --- Unless cross-compiling, the next thing you'll probably want to do @@ -44,24 +46,26 @@ testsuite, use: To save even more build, stop the build after configure has run, and then you can restart the build of only libc.so and libc.a with: - cd build-tree/hurd-i386-libc - make lib + make -C build-tree/hurd-i386-libc lib or of only libc.so with: - make objdir=$PWD/build-tree/hurd-i386-libc $PWD/build-tree/hurd-i386-libc/libc.so + make -C build-tree/hurd-i386-libc objdir=$PWD/build-tree/hurd-i386-libc $PWD/build-tree/hurd-i386-libc/libc.so or of the whole tree with: - cd build-tree/hurd-i386-libc - make + make -C build-tree/hurd-i386-libc or of just one subdir with for instance: - make subdir=libpthread -C libpthread ..=../ objdir=$PWD/build-tree/hurd-i386-libc + make -C htl subdir=htl ..=../ objdir=$PWD/build-tree/hurd-i386-libc (note that most subdirs need libc.so built) +Similarly, you can run the testsuite of a single directory the same way: + + make check -C htl subdir=htl ..=../ objdir=$PWD/build-tree/hurd-i386-libc + --- In some cases, printing to stdout/stderr is problematic. One can use a kernel 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/subhurd.mdwn b/hurd/debugging/subhurd.mdwn index 7b5b07b1..34b3e097 100644 --- a/hurd/debugging/subhurd.mdwn +++ b/hurd/debugging/subhurd.mdwn @@ -42,11 +42,11 @@ with _ps_.) W3 - $ sudo gdb /var/tmp/one.full/lib/ld.so.1 + $ sudo gdb /var/tmp/one.full/lib/ld-x86-64.so.1 [...] (gdb) set solib-absolute-prefix /var/tmp/one.full (gdb) attach 854 - Attaching to program `/var/tmp/one.full/lib/ld.so.1', pid 854 + Attaching to program `/var/tmp/one.full/lib/ld-x86-64.so.1', pid 854 warning: Can't modify tracing state for pid 854: No signal thread Can't fetch registers from thread 1: No such thread @@ -54,7 +54,7 @@ W1 [<Enter>.] /hurd/ext2fs.static --bootflags=-dsf --host-priv-port=38 --device-master-port=43 --exec-server-task=47 -Tdevice pseudo-root - /lib/ld.so.1 /hurd/exec + /hurd/exec.static Now that this step has been accomplished, you can set break points in GDB, etc. 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..1a9ff3b3 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,50 @@ 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 + * [[hurd/rump/rumpdisk]] + * [[hurd/rump/rumpnet]] + * [[hurd/rump/rumpusbdisk]] + * [[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/translator_primer.mdwn b/hurd/documentation/translator_primer.mdwn index 92a1d5f9..073d5e07 100644 --- a/hurd/documentation/translator_primer.mdwn +++ b/hurd/documentation/translator_primer.mdwn @@ -84,7 +84,7 @@ What you do here is setting up the translator /hurd/hostmux on ftp: and passing Now that we can access ftp.gnu.org transparently, let's mount a remote ISO file: - $ settrans -c mnt /hurd/iso9660fs ftp://ftp.gnu.org/old-gnu/gnu-f2/hurd-F2-main.iso + $ settrans -c mnt /hurd/iso9660fs $PWD/ftp://ftp.gnu.org/old-gnu/gnu-f2/hurd-F2-main.iso $ ls mnt/ It is interesting to note that since the ISO9660 format is indexed, ftpfs does not have to download the whole ISO file, it merely fetches what iso9660fs requests. 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 4b5e8d38..736cc099 100644 --- a/hurd/glibc.mdwn +++ b/hurd/glibc.mdwn @@ -27,18 +27,18 @@ glibc. This should be working as per the following: $ mkdir -p /tmp/build/src $ cp -a /usr/src/glibc /tmp/build/src/ $ unset CFLAGS - $ /tmp/build/src/glibc/scripts/build-many-glibcs.py /tmp/build checkout - $ /tmp/build/src/glibc/scripts/build-many-glibcs.py /tmp/build host-libraries - $ /tmp/build/src/glibc/scripts/build-many-glibcs.py /tmp/build compilers i686-gnu + $ /tmp/build/src/glibc/scripts/build-many-glibcs.py --shallow /tmp/build checkout + $ /tmp/build/src/glibc/scripts/build-many-glibcs.py --strip /tmp/build host-libraries + $ /tmp/build/src/glibc/scripts/build-many-glibcs.py --strip /tmp/build compilers i686-gnu $ /tmp/build/src/glibc/scripts/build-many-glibcs.py /tmp/build glibcs i686-gnu Currently the master branch builds that way without any testsuite issue. -# Building +To save some disk space, after the compilers stage you can remove src/mpc, src/mpfr, src/binutils, src/linux. -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: @@ -49,6 +49,14 @@ 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 + +One can build by hand some target with e.g.: + + $ make $PWD/htl/libpthread.so -C ../htl subdir=htl objdir=$PWD ..=../ 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/interface/fs/19.mdwn b/hurd/interface/fs/19.mdwn index 86625d44..2a50d3e0 100644 --- a/hurd/interface/fs/19.mdwn +++ b/hurd/interface/fs/19.mdwn @@ -23,7 +23,10 @@ License|/fdl]]."]]"""]] Read entries from the directory. Each entry is identified by an index number starting at 0 and running through the file. This call fetches `nentries` (or any convenient number if `nentries` is -1) entries starting at `entry`, -returning an array of struct directs in `data`. The number of entries +returning a series of struct dirent in `data`. +Note that due to the variable-size `d_name` field, `d_reclen` has to be used to +jump from one struct dirent to the other. +The number of entries successfully read is returned in `amount`. If `entry` is bigger than the index of the last entry, then 0 is returned in `amount`. If `bufsize` is nonzero, never return more than `bufsize` bytes of data regardless. 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/libports.mdwn b/hurd/libports.mdwn index b0a0f6d5..c2c39226 100644 --- a/hurd/libports.mdwn +++ b/hurd/libports.mdwn @@ -16,8 +16,8 @@ ports|microkernel/mach/port]]. It is documented in the [[Reference_Manual]]. Mach ports to the functionality the Hurd needs, that is, it is not meant to provide an interface independently of the underlying [[microkernel]]. -*libports* does not itself depend on *[[libthreads]]*, but the appropriate -threading hooks are used if present, that is if *[[libthreads]]* is used by +*libports* does not itself depend on *[[/libpthread]]*, but the appropriate +threading hooks are used if present, that is if *[[/libpthread]]* is used by another component. diff --git a/hurd/libthreads.mdwn b/hurd/libthreads.mdwn deleted file mode 100644 index aa429d81..00000000 --- a/hurd/libthreads.mdwn +++ /dev/null @@ -1,39 +0,0 @@ -[[!meta copyright="Copyright © 2011, 2012, 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]]."]]"""]] - -`libthreads` a.k.a. C threads. - -**Note**: since Hurd migrated to [[libpthread]] as threading library, -the development and usage of libthreads has been discontinued. - - - -# Internals - -## Threading Model - -libthreads has a 1:1 threading model. - - -## Threads' Death - -A thread's death doesn't actually free the thread's stack (and maybe not the -associated Mach ports either). That's because there's no way to free the stack -after the thread dies (because the thread of control is gone); the stack needs -to be freed by something else, and there's nothing convenient to do it. There -are many ways to make it work. - -However, it isn't really a leak, because the unfreed resources do get used for -the next thread. So the issue is that the shrinkage of resource consumption -never happens, but it doesn't grow without bounds; it just stays at the maximum -even if the current number of threads is lower. - -The same issue exists in [[libpthread]]. diff --git a/hurd/porting/guidelines.mdwn b/hurd/porting/guidelines.mdwn index 5986269e..624f7fd5 100644 --- a/hurd/porting/guidelines.mdwn +++ b/hurd/porting/guidelines.mdwn @@ -132,6 +132,8 @@ 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> 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. Note: constants such as `_POSIX_PATH_MAX` are only the minimum required value @@ -140,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..ec67d6b5 --- /dev/null +++ b/hurd/rump/rumpnet.mdwn @@ -0,0 +1,41 @@ +[[!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 + +The Hurd is currently using an old Linux's TCP/IP stack (`pfinet`) and +device drivers. Hurd developers are replacing Linux's old ethernet +drivers with rumpnet's modern ethernet and wifi device drivers. While +porting Linux's device drivers would provide better hardware support, +we do not have the developer man-power to maintain it. Hurd +Developers prefer rumpnet's stable API over Linux's code churn. We +plan to replace `pfinet` with [[lwip|hurd/translator/lwip]] (or use +rump's TCP/IP stack). + +In 2025, Damien Zammit make significant progress with rumpnet. He +coded rumpnet to work with `/dev/wmX` cards, which are Intel i8254x +Gigabit Ethernet devices. (Documentation is available at +man.netbsd.org's [wm(4)](https://man.netbsd.org/wm.4) web +page). Please note that these are ethernet cards not wifi cards. This +should be easily extended to support other NICs by contributing to +netbsd/rump's makefiles. + +Example usage: + + $ settrans -fgap /dev/rumpnet /hurd/rumpnet + $ settrans -fgap /dev/wm0 /hurd/devnode -M /dev/rumpnet wm0 + $ settrans -fgap /servers/socket/2 /hurd/pfinet -i /dev/wm0 + $ ifup /dev/wm0 + + + 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 new file mode 100644 index 00000000..30b7b62a --- /dev/null +++ b/hurd/running/Guix.mdwn @@ -0,0 +1,67 @@ +[[!meta title="Guix"]] + +GNU/Hurd support has been integrated in Guix. + +--- +# QEMU Image +[[!inline pages=hurd/running/Guix/qemu_image raw=yes feeds=no]] + +--- +# Documentation + +As Hurd support is integrated in Guix, the [official +documentation](https://guix.gnu.org/manual/en/html_node/) also works +for Hurd. + +# Status + +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/Guix/qemu_image.mdwn b/hurd/running/Guix/qemu_image.mdwn new file mode 100644 index 00000000..52985c6f --- /dev/null +++ b/hurd/running/Guix/qemu_image.mdwn @@ -0,0 +1,14 @@ +[//]: # ([[meta copyright="Copyright © 2011, 2012, 2014, 2016 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="Guix's QEMU Image"]] + +There is a QEMU image with [[Guix GNU/Hurd|guix]] pre-installed available +at <https://ci.guix.gnu.org/search/latest/image?query=spec:images+status:success+system:x86_64-linux+hurd-barebones.qcow2>. diff --git a/hurd/running/chroot.mdwn b/hurd/running/chroot.mdwn index eac67282..0f5ec88f 100644 --- a/hurd/running/chroot.mdwn +++ b/hurd/running/chroot.mdwn @@ -24,7 +24,7 @@ It can be a good idea to put the chroot on a separate translator, for instance: Debootstrap should be able to build the content: - # debootstrap sid chroot + # debootstrap --keyring=/usr/share/keyrings/debian-ports-archive-keyring.gpg --extra-suites=unreleased sid chroot http://deb.debian.org/debian-ports/ # Tricks diff --git a/hurd/running/cloud.mdwn b/hurd/running/cloud.mdwn index 736a7113..3d0d37ef 100644 --- a/hurd/running/cloud.mdwn +++ b/hurd/running/cloud.mdwn @@ -15,4 +15,4 @@ It is possible to run the Hurd as a KVM-based OpenStack cloud instance. [[For the time being|open_issues/virtio]], you'll have to avoid using virtio drivers, and use emulated hardware instead: - $ glance image-create --property hw_disk_bus=ide --property hw_cdrom_bus=ide --property hw_vif_model=rtl8139 --disk-format raw --container-format bare --name gnu-hurd --copy-from https://cdimage.debian.org/cdimage/ports/latest/hurd-i386/debian-hurd.img + $ glance image-create --property hw_disk_bus=ide --property hw_cdrom_bus=ide --property hw_vif_model=e1000 --disk-format raw --container-format bare --name gnu-hurd --copy-from https://cdimage.debian.org/cdimage/ports/latest/hurd-i386/debian-hurd.img diff --git a/hurd/running/debian/CrossInstall.mdwn b/hurd/running/debian/CrossInstall.mdwn index c7a099c6..0cf9e6f2 100644 --- a/hurd/running/debian/CrossInstall.mdwn +++ b/hurd/running/debian/CrossInstall.mdwn @@ -1,31 +1,41 @@ -## <a name="Easy_install_with_CrossHurd"> Easy install with CrossHurd </a> +Curious about the Hurd? Have a 1-5 GiB partition free? Let's install GNU/Hurd on it! -Qurious about the Hurd? Have a 1-5 GiB partition free? Let's install GNU/Hurd on it! +This page covers two ways to install a Debian GNU/Hurd system from a running +Debian GNU/Linux in a dual boot type of setup, using either +[crosshurd](#CrossHurd) or [mmdebstrap](#mmdebstrap). + +For the sake of the examples in this page we will consider `/dev/hda3` as +the partition where you want to install your Hurd system as displayed from linux. + +The examples here assume the installation of a `hurd-i386` system, but it is +simple to modify for a `hurd-amd64` installation. -### <a name="Preparing_the_partition"> Preparing the partition </a> -We'll assume you have a partition ready, for the sake of argument we use an example here: /dev/hda3 is the Hurd partition (type: Linux) and /dev/hda4 is the Linux swap that we'll reuse. +## <a name="CrossHurd"> CrossHurd method </a> -First we create the Ext2 filesystem, notice the `hurd` option. +First install the [crosshurd package](http://packages.debian.org/crosshurd). - # mke2fs -o hurd /dev/DEVICE + # apt install crosshurd + +If you have problems it might be because the crosshurd version in the Stable +distribution is out of date, try the version in Unstable before reporting the issue. + +### <a name="Preparing_the_partition"> Preparing the partition </a> + +We create the Ext2 filesystem for the Hurd system, notice the `hurd` option. + + # mke2fs -o hurd /dev/hda3 Next we create a useful mountpoint and mount the partition. # mkdir /gnu # mount /dev/hda3 /gnu -### <a name="Retrieving_CrossHurd"> Retrieving CrossHurd </a> - -Unless you don't run Debian GNU/Linux download it from <http://packages.debian.org/crosshurd>, or simply apt-get the package from Testing or Unstable. Avoid using the version from Stable since it probably is outdated. In case of problems, make sure to try the Unstable version before reporting the issue. - - # apt-get install crosshurd ### <a name="Cross_installing"> Cross installing </a> The crosshurd package only operates in the given target directory, which is the first question asked when running the program. - # cd /gnu # crosshurd Answer the questions you get: $ What is the target directory?: `/gnu` $ Target Debian system?: gnu $ Target CPU?: i386 @@ -34,41 +44,87 @@ Now the program starts retrieving all the necessary base packages. ### <a name="Preparing_to_reboot"> Preparing to reboot </a> -When all packages have been extracted we must prepare [[GRUB]] for the Hurd when we reboot. Add the below entry to your `/boot/grub/menu.lst` file to boot the Hurd in single user mode (-s). Single user mode is needed only for the two reboots when running the Native Install. +When all packages have been extracted we must prepare [[GRUB]] for the Hurd when we reboot. +Add the below entry to `/etc/grub.d/40_custom` file in your linux installation. + + menuentry "Debian GNU/Hurd" { + set root='hd0,msdos3' + echo 'Loading GNU Mach ...' + multiboot /boot/gnumach-1.8-486-up.gz root=part:3:device:wd0 noide + echo 'Loading the Hurd ...' + 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 \ + --multiboot-command-line='${kernel-command-line}' \ + --exec-server-task='${exec-task}' -T typed '${root}' \ + '$(fs-task=task-create)' + module /hurd/exec.static exec '$(exec-task=task-create)' + } - title GNU (kernel GNUmach 1.5) - root (hd0,2) - kernel /boot/gnumach-1.5-486.gz root=device:hd0s3 -s - module /hurd/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) - module /lib/ld.so.1 /hurd/exec $(exec-task=task-create) +*Nota Bene:* In your menu file there should be no extra white space after the back slashes. -**_Nota Bene:_** In your menu file there should be no extra white space after the back slashes. +Following this, re-create the grub configuration file: + + # update-grub ### <a name="Native_install"> Native install </a> -Ah, reboot and select "GNU (kernel GNUmach 1.3)" from the Grub menu. At the prompt, setup TERM and run the native-install script. +Then, reboot and select "Debian GNU/Hurd" from the Grub menu. At the prompt, setup TERM and run the native-install script. # export TERM=mach # ./native-install -When done the native install requests that you reboot once again and rerun native-install. +You should add a swap partition to `/etc/fstab`. You can share the swap +partition between your Hurd and linux installations. If the swap partition +was `/dev/hda4` on linux, it will be `/dev/wd0s4` on the Hurd. - # reboot - ... - # export TERM=mach - # ./native-install +Before you reboot the system be sure to set a root password. + + # passwd + +We can now reboot into the newly configured system. + + # reboot-hurd + +## <a name="mmdebstrap"> mmdebstrap method </a> + +First we need to install the [mmdebstrap](http://packages.debian.org/mmdebstrap) and libarchive13t64 packages. + + # apt install mmdebstrap libarchive13t64 + +The way this installation method works is to run mmdebstrap in the +[chrootless mode](https://gitlab.mister-muffin.de/josch/mmdebstrap/wiki#modes) +from a linux host. But because misconfigured package Maintainer scripts may +damage the host installation while running in chrootless mode, we wrap two +mmdebstrap calls: the first creates a throw-away linux chainroot from within +which we call mmdebstrap in chrootless mode to install our GNU/Hurd image. -Done, continue setting up your system. +We run the following command (we use line breaks for readability, but it is a +single command): ----- + # mmdebstrap --variant=apt + --include=passwd,debian-ports-archive-keyring,mmdebstrap,sysvinit-core,sysv-rc,e2fsprogs,libarchive13t64 + --customize-hook='chroot "$1" + mmdebstrap --mode=chrootless --arch=hurd-i386 + --include=sysvinit-core,sysv-rc,debian-ports-archive-keyring,netdde,gnumach-image-1-486 + --customize-hook="passwd --root=\"\$1\" --delete root" + --variant=apt unstable - + "deb http://ftp.ports.debian.org/debian-ports/ unstable main" + "deb http://ftp.ports.debian.org/debian-ports/ unreleased main" + | mkfs.ext2 -o hurd -d - /dev/hda3' + stable /dev/null -Jeff Bailey has set up a system where you can install a Hurd system without having to use CDs. It's another type of cross-installation method which uses Debian package management tools to get the packages required as opposed to the one single big tarball. +We then need to [configure the bootloader grub](#Preparing_to_reboot) in the +same way as described in the crosshurd method above. -As of 2005-03-22, the latest version of crosshurd is 1.7.11. It can be found at <http://packages.debian.org/crosshurd>. +You can then reboot into the Debian GNU/Hurd system and install any further +packages using `apt`. --- [[Main/PeterMelville]] - 12 Jun 2004 diff --git a/hurd/running/debian/DebianAptOffline.mdwn b/hurd/running/debian/DebianAptOffline.mdwn index 9596040d..f97e5148 100644 --- a/hurd/running/debian/DebianAptOffline.mdwn +++ b/hurd/running/debian/DebianAptOffline.mdwn @@ -24,11 +24,11 @@ As root on the internet connected OS: # mount /dev/DEBIAN_GNU_HURD_PARTITON /mnt # cd /mnt - # apt-get -c etc/apt/apt.conf.offline {update, upgrade, install foo, etc.} + # apt -c etc/apt/apt.conf.offline {update, upgrade, install foo, etc.} Then, reboot into your Debian GNU/Hurd installation and as root, run: - # apt-get {update, upgrade, install foo, etc.} + # apt {update, upgrade, install foo, etc.} ## If you _cannot_ mount your Debian GNU/Hurd partition under another OS. @@ -47,7 +47,7 @@ From the remote sytem, as any user, run: $ cd myhurd $ tar -xf myhurdsconf.tar $ mkdir -p var/lib/apt/lists/partial var/cache/apt/archives/partial tmp - $ apt-get -c etc/apt/apt.conf.offline {update, upgrade, install foo, etc.} + $ apt -c etc/apt/apt.conf.offline {update, upgrade, install foo, etc.} $ tar cf myhurdsconf.tar etc/apt/{apt.conf.offline,sources.list} var/ Copy _myhurdsconf.tar_ back to your Debian GNU/Hurd system. @@ -59,4 +59,4 @@ Finally, from your Debian GNU/Hurd installation as the root user: # tar -xf myhurdsconf.tar # mv var/cache/apt/archives/*.deb /var/cache/apt/archives/ # mv var/lib/apt/lists/*_* /var/lib/apt/lists/ - # apt-get {update, upgrade, install foo, etc.} + # apt {update, upgrade, install foo, etc.} diff --git a/hurd/running/debian/MediaPressKitDiscuss.mdwn b/hurd/running/debian/MediaPressKitDiscuss.mdwn index 2bd97290..05e1761a 100644 --- a/hurd/running/debian/MediaPressKitDiscuss.mdwn +++ b/hurd/running/debian/MediaPressKitDiscuss.mdwn @@ -71,6 +71,6 @@ I think another active process for tracking recent news (if it doesn't already e Here are some interesting urls from [this issue](http://www.debian.org/News/weekly/2003/03/) of the Debian Weekly news: -**Debian Presentations.** Wolfgang Borgert was [looking](http://lists.debian.org/debian-devel-0301/msg00991.html) for a set of slides on dpkg, apt-get and debconf. Javier Fern�ndez-Sanguino Pe�a [intends](http://lists.debian.org/debian-devel-0301/msg01022.html) to provide a 'presentations' section in the [Debian Documentation Project](http://cvs.debian.org/ddp/?cvsroot=debian-doc) (DDP) and has already created an [archive](http://dat.etsit.upm.es/~jfs/debian/www/ddp/slides/) of slides. Whilst the Debian web site does link to [talks](http://www.debian.org/events/talks) given by developers and some [sample slides](http://www.debian.org/events/materials/slides/), it is difficult to gather this information and publish it in a homogeneous way. Talks should be reported to <events@debianNOSPAM.org> and forwarded to him. +**Debian Presentations.** Wolfgang Borgert was [looking](http://lists.debian.org/debian-devel-0301/msg00991.html) for a set of slides on dpkg, apt and debconf. Javier Fern�ndez-Sanguino Pe�a [intends](http://lists.debian.org/debian-devel-0301/msg01022.html) to provide a 'presentations' section in the [Debian Documentation Project](http://cvs.debian.org/ddp/?cvsroot=debian-doc) (DDP) and has already created an [archive](http://dat.etsit.upm.es/~jfs/debian/www/ddp/slides/) of slides. Whilst the Debian web site does link to [talks](http://www.debian.org/events/talks) given by developers and some [sample slides](http://www.debian.org/events/materials/slides/), it is difficult to gather this information and publish it in a homogeneous way. Talks should be reported to <events@debianNOSPAM.org> and forwarded to him. -- [[Main/GrantBow]] - 22 Jan 2003 diff --git a/hurd/running/debian/after_install.mdwn b/hurd/running/debian/after_install.mdwn index d3d32a6f..4c7d924a 100644 --- a/hurd/running/debian/after_install.mdwn +++ b/hurd/running/debian/after_install.mdwn @@ -11,7 +11,12 @@ typing a boring arcane. There are Debian-specific scripts that may help you. See [[GRUB]]'s page for this. -# Setup `apt-get` +# Setup `apt 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 6357d782..c6da1555 100644 --- a/hurd/running/debian/qemu_image.mdwn +++ b/hurd/running/debian/qemu_image.mdwn @@ -22,16 +22,27 @@ Usage: $ wget https://cdimage.debian.org/cdimage/ports/latest/hurd-i386/debian-hurd.img.tar.gz $ tar -xz < debian-hurd.img.tar.gz - $ kvm -m 1G -drive cache=writeback,file=$(echo debian-hurd-*.img) -no-reboot -net user,hostfwd=tcp:127.0.0.1:2222-:22 -net nic + $ kvm -m 1G -drive cache=writeback,file=$(echo debian-hurd-*.img) -no-reboot -net user,hostfwd=tcp:127.0.0.1:2222-:22 -net nic,model=e1000 -* Login as root (the root password is empty) +* Log in as root (the root password is empty) * Set up a root password with `passwd` +* update the system with `apt update && apt upgrade` + +* Log in as demo (the demo password is empty) +* Set up a demo password with `passwd` + +* You can also create another non-root user with `adduser <username>` +* and set the non-root user password with `passwd <username>` +* and add the non-root user to the sudo group via `gpasswd -a <user> sudo` + +* logout via `logout` + Optionally you may use `--curses` to keep your keyboard layout. If need be modprobe kvm_amd, kvm intel and kvm to get kvm support (which is much, much faster). 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 + $ qemu-system-i386 --enable-kvm -m 2G -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/debian/status.mdwn b/hurd/running/debian/status.mdwn index 95e48edc..cf3592e7 100644 --- a/hurd/running/debian/status.mdwn +++ b/hurd/running/debian/status.mdwn @@ -1,4 +1,4 @@ Debian GNU/Hurd is currently an official, non-releasing Debian port. I.e., there is no testing or stable distribution. - - [Build daemon/archive status](http://unstable.buildd.net/buildd/hurd-i386_stats) - - [Number of registered users](http://buildd.net/cgi/archvote.phtml) + - [Build daemon/archive status](https://buildd.debian.org/status/architecture.php?a=hurd-i386&suite=sid) + - [Number of registered users](https://popcon.debian.org/stat/sub-hurd-i386.png) diff --git a/hurd/running/distrib.mdwn b/hurd/running/distrib.mdwn index 357d840a..5d12f8ec 100644 --- a/hurd/running/distrib.mdwn +++ b/hurd/running/distrib.mdwn @@ -14,6 +14,7 @@ There are several GNU distributions that are built on the Hurd. If you develop a ###Working distributions of GNU/Hurd: * [[Debian]] +* [[Guix]] ###GNU/Hurd distributions in early stages of development: 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 6df06ace..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]] @@ -50,7 +100,7 @@ volunteers and may not have been tested extensively. ## Debian Installer -Instructions for creating a qemu image from the install CDs from debian installer can be found in the README alongside the d-i Hurd images: <http://people.debian.org/~sthibault/hurd-i386/installer/cdimage/> +Instructions for creating a qemu image from the install CDs from debian installer can be found in the README alongside the d-i Hurd images: <https://cdimage.debian.org/cdimage/ports/latest/hurd-i386/> --- # KVM acceleration @@ -60,7 +110,7 @@ Check if your CPU supports kvm: $ egrep '^flags.*(vmx|svm)' /proc/cpuinfo #### If you don't have hardware support (slow): - $ apt-get install qemu + $ apt install qemu Do not enable kernel-kqemu, as that assumes some particular behavior from the guest kernel, which we are reluctant to artificially add to gnumach. @@ -68,7 +118,7 @@ If QEMU with KVM is not available, [[Virtualbox]] reportedly has better performance. #### If you have hardware support (recommended): - $ apt-get install qemu-kvm + $ apt install qemu-kvm $ modprobe kvm Intel VTx/VTd: Enable Intel kvm in the BIOS @@ -119,7 +169,7 @@ First off you will need to create a disk image using `qemu-img`. I have set mine Next you will want to start up QEMU and begin the installation process. - $ qemu -m 1G -drive cache=writeback,file=hd0.img -cdrom debian-7.0-hurd-i386-NETINST-1.iso -net nic,model=rtl8139 -net user + $ qemu -m 1G -drive cache=writeback,file=hd0.img -cdrom debian-7.0-hurd-i386-NETINST-1.iso -net nic,model=e1000 -net user Now at his point do the regular install using `hd0` as your harddrive. Partition it and install the base system. @@ -167,7 +217,7 @@ Once you have finished installing the base system (might take some time) the sys Starting qemu/qemu-kvm: - $ kvm -m 1G -net nic -net user,hostfwd=tcp::5555-:22 -drive cache=writeback,file=hd0.img -vga vmware + $ kvm -m 1G -net nic,model=e1000 -net user,hostfwd=tcp::5555-:22 -drive cache=writeback,file=hd0.img -vga vmware vmsvga_value_write: guest runs Linux. Note: See below on port forwarding in the networking section. @@ -252,13 +302,13 @@ If you are on [[Debian GNU/Hurd|debian]], you can even use [[debian/DHCP]]. To get ssh working: - # apt-get 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>.) Outgoing internet connections should just work then. Testing it can be difficult with a minimal installation, -but `apt-get update` should work after you have filled out +but `apt update` should work after you have filled out `/etc/apt/sources.list`. After that you should be able to install other network packages, but note that `ping` doesn't work with QEMU's user-networking stack. @@ -288,7 +338,7 @@ This is the recommended way to work with a Command Line Interface (CLI) since al a) with ssh (assuming you have installed openssh-server) - $ kvm -m 1G -net nic -net user,hostfwd=tcp::5555-:22 -drive cache=writeback,file=hd0.img & + $ kvm -m 1G -net nic,model=e1000 -net user,hostfwd=tcp::5555-:22 -drive cache=writeback,file=hd0.img & Logging in to the running Hurd: @@ -305,7 +355,7 @@ Copying files: b) with telnet (assuming you have installed a telnet server, like telnetd) - $ kvm -m 1G -net nic -net user,hostfwd=tcp::5556-:23 -drive cache=writeback,file=hurd-install.qemu & + $ kvm -m 1G -net nic,model=e1000 -net user,hostfwd=tcp::5556-:23 -drive cache=writeback,file=hurd-install.qemu & Logging in to the running Hurd: @@ -346,7 +396,7 @@ Now it is time to start-up your QEMU Hurd system and get networking going in the **Important:** Remember you may need to use the `-M isapc` or `-isa` flag if using an older version of the gnumach package. - $ qemu -m 1G -drive cache=writeback,file=hd0.img -cdrom debian-K9-hurd-i386-CD1.iso -fda floppy.img -boot a -net nic -net tap + $ qemu -m 1G -drive cache=writeback,file=hd0.img -cdrom debian-K9-hurd-i386-CD1.iso -fda floppy.img -boot a -net nic,model=e1000 -net tap Once you have logged in as `root` run the `pfinet` translator with values that apply to your network. Think of your QEMU client as another computer in your network. @@ -355,14 +405,16 @@ 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. Get the multiboot modules. Either extract them from the disk image, or, download: - $ wget http://people.debian.org/~sthibault/hurd-i386/installer/cdimage/current/{gnumach.gz,ext2fs.static,ld.so.1} + $ wget https://cdimage.debian.org/cdimage/ports/latest/hurd-i386/gnumach.gz + $ wget https://cdimage.debian.org/cdimage/ports/latest/hurd-i386/ext2fs.static + $ wget https://cdimage.debian.org/cdimage/ports/latest/hurd-i386/exec.static Generally, these files need to correspond to the ones in the disk image, so don't forget to keep them up to date. @@ -372,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)',\ - > 'ld.so.1 /hurd/exec $(exec-task=task-create)' + > '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 a92a8d3f..5bd81425 100644 --- a/hurd/subhurd.mdwn +++ b/hurd/subhurd.mdwn @@ -37,11 +37,15 @@ 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: - root@debian:~# settrans -c /dev/pseudo-root /hurd/storeio pseudo-root root@debian:~# echo /dev/pseudo-root / ext2 defaults 0 1 >/etc/fstab root@debian:~# halt @@ -77,9 +81,17 @@ debootstrap as root: mke2fs /dev/hd0s6 settrans -ca mnt /hurd/ext2fs /dev/hd0s6 - debootstrap sid mnt/ http://httpredir.debian.org/debian + debootstrap --keyring=/usr/share/keyrings/debian-ports-archive-keyring.gpg --extra-suites=unreleased sid chroot http://deb.debian.org/debian-ports/ + chroot mnt passwd settrans -fga mnt +## Using mmdebstrap + +One can also use mmdebstrap: + + mmdebstrap --mode=chrootless --variant=required --keyring=/usr/share/keyrings/debian-ports-archive-keyring.gpg '' rootfs.tar.gz 'deb http://deb.debian.org/debian-ports unreleased main' 'deb http://deb.debian.org/debian-ports/ unstable main' + mke2fs /dev/hd0s6 -d rootfs.tar.gz + ## Booting If you are using a recent version of the Hurd (>= 0.9), then you can @@ -134,7 +146,7 @@ In the subhurd, you can do basically all the same things as in the main Hurd. You can even set up networking: Just invoke `settrans` on the `/servers/socket/2` as usual inside the subhurd, using `/dev/eth0`, only using a different local IP than in the main Hurd. This way, the subhurd will be able to communicate to -the outside world with its own IP -- allowing for example to do `apt-get` +the outside world with its own IP -- allowing for example to do `apt inside the subhurd, or to `ssh` directly into the subhurd. If you want to access the subhurd processes from the outside, e.g. for @@ -147,6 +159,17 @@ numbers are different, the order should usually match. Often it also helps to look at the number of threads (e.g. using `ps -l`), as many servers have very characteristic thread counts. +## Faster boot + +If you do not need daemons etc. you can just run a shell, similary to a chroot: + + boot /dev/hd0s6 -c init=/bin/bash + +Unless you change the boot script to pass `--writable` to ext2fs, you will want to remount / read-write: + + fsysopts / --writable + +And `poweroff-hurd` should be used to stop the subhurd. ### IRC, freenode, #hurd, 2013-08-09 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 32562a8b..fe669a12 100644 --- a/hurd/translator.mdwn +++ b/hurd/translator.mdwn @@ -89,24 +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/checkperms.mdwn b/hurd/translator/checkperms.mdwn new file mode 100644 index 00000000..a8a52cb1 --- /dev/null +++ b/hurd/translator/checkperms.mdwn @@ -0,0 +1,233 @@ +[[!meta copyright="Copyright © 2021 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 *checkperms* translator implements deferred authorization. + +It is part of a project to enable asking for a grant of authorization +when processes access a file. It is built as a translator and a simple +permission granting program. + +The translator can delegate permission-granting to the program via two +FIFO files. The goal is to create a simple replacement for the +use-case of polkit of granting privilege to a process to access some +resource after user-interaction with a permission-granting daemon. + + +# Code + +The translator is available in the checkperm-deferred-authorization branch in [the hurd repository](https://git.savannah.gnu.org/cgit/hurd/hurd.git). + +The code for the program is provided in this article + +# Usage Example + +We restrict a the node /hello to require explicit permission for every +PID that does not have the group `user`. This notably does include +processes started by root. + + +## How it looks + +**First shell** as root: + + settrans -cga /hello $(realpath ~/Dev/hurd/trans/checkperms) --groupname=user + su - user --shell /bin/bash -c 'cat /hello' + # ⇒ HELLOWORLD # user has the group user + cat /hello # root does not have the group user, so + # this blocks until positive reply in the other shell + +**Second shell** (run the program): + + Process 732 tries to access file /hello but is not in the required group user. + USER PID %CPU %MEM SZ RSS TT STAT START TIME COMMAND + root 732 0.0 0.1 148M 3.55M p2 Sso Mon 1AM 0:01.10 -bash + Grant permission and add group "user" for 5 minutes? [y/N]> y + +**First shell** as root: + + # ⇒ HELLOWORLD + # only blocks once despite getting two reads from cat, + # because for the second read cat already has the group `user`. + + + +## Trying it yourself + +Setup the development environment with the code at ~/Dev similar to +https://www.draketo.de/software/hurd-development-environment + + +Compile and setup the translator: + + cd ~/Dev/hurd && \ + patch -p1 < checkperms.patch && \ + autoreconf -i && \ + ./configure --without-parted && \ + make && \ + touch trans/checkperms.c && \ + CFLAGS="$CFLAGS -g" make && \ + echo HELLOWORLD > /hello && \ + settrans -cga /hello $(realpath ~/Dev/hurd/trans/checkperms) --groupname=user + +Create the FIFOs: + + USER=root + GROUP=user + mkdir -p /run/$USER/request-permission + mkdir -p /run/$USER/grant-permission + mkfifo /run/$USER/request-permission/$GROUP + mkfifo /run/$USER/grant-permission/$GROUP + +Setup the permission-granting program in a separate shell: + + USER=root + GROUP=user + while true; do + PID="$(cat /run/$USER/request-permission/$GROUP)" + echo Process $PID tries to access file /hello but is not in the required group $GROUP. + ps-hurd -p $PID -aeux + if [[ "$(read -e -p 'Grant permission and add group "'$GROUP'" for 5 minutes? [y/N]> '; echo $REPLY)" == [Yy]* ]]; then + addauth -p $PID -g $GROUP + echo 0 > /run/$USER/grant-permission/$GROUP + (sleep 300 && rmauth -p $PID -g $GROUP 2>/dev/null) & + else + echo 1 > /run/$USER/grant-permission/$GROUP + fi + done + + +Access the translator as user without the required group and with the group: + + su - user --shell /bin/bash -c cat /hello' + cat /hello & + + +# Concept + +## The translator + +The translator is started with a GROUP as argument. When the file is +accessed, the translator checks whether the process has the given +group. If it does, it returns data read from the underlying file. + +If the process lacks the required group, the translator retrieves its +USER and PID and writes the PID into a FIFO located at + + /run/USER/request-permission/GROUP + +Then it reads from + + /run/USER/grant-permission/GROUP + +It blocks until it gets a reply. If it reads a 0 (=success), it reads +from the file and returns the data. + +## The permission granting program + +The permission granting program reads the PID from + + /run/USER/request-permission/GROUP + +retrieves information about the PID and asks the user whether to allow +the program. + +If the USER answers no, the RET value is non-zero. + +If the USER answers yes, the RET value is zero (0) +and the program adds the GROUP to the process at PID (using addauth). + +It also starts a daemon that will remove the group again after 5 +minutes (modelled after the temporary permissions to run privileged +without password granted by sudo). + +The program then writes the RET value into + + /run/USER/grant-permission/GROUP + +## What if the translator crashes? + +If the translator crashes, the permissions return to those of the +underlying node. For every user except root this usually means that +the process does not have access to the file. + +The failure-mode should therefore be safe. + +# Possibilities + +The most important use-case for this translator is to make it easier +to start programs with reduced permissions and only add these when +required. + +To setup deferred permissions for a single file, you can create a +group just for that file. Then each file can have its own permission +granting program. Having dedicated groups decouples authentication and +authorization while staying in the conventional *nix permissions +scheme. + +You can also set this translator on a file that gets accessed first +when a process accesses a set of related files that all have the same +group. Since the authorization-program here adds the group for 5 +minutes, the other files can afterwards be accessed, too. + +Since the translator simply defers to a program, that program could do +any action to get authorization, including `curl`. Administrators for +a local network could therefore set up terminals for unprivileged +users that request permissions from a local server when accessing a +file. That way permissions can easily be coordinated over multiple +machines. (naturally this does not restrict root who can always use +settrans -g to get raw access to the file) + + + + +# Open Issues + +## read-only + +[[!tag open_issue_hurd]] + +The current implementation only provides read-access, writing is +prevented. This is not an intrinsic limitation, only an implementation +artefact. + +## delegate + +The underlying file is currently read by the translator and the data +returned to the reading process. To reduce delays, it could directly +delegate to the underlying file. With the long term goal to provide +multiplexing of access, for example for audio, reading via the +translator could be preferable, though. + +## writing via system shell + +Writing to and reading from the FIFOs is currently done with +`system()`. It would be nicer to move to an implementation that does +not rely on the system-shell. + +## potential race-condition + +Accesses from two different translators can currently race for the +reply. To fix this, the translator should write the PID and a random +LABEL into the request. The program should repeat that label for +replies to ensure that the reply and request can be matched. If +receiving a non-matching reply, it MUST be written into the grant +again after a random delay to enable a matching translator to +retrieve the grant. +REQUEST: PID LABEL +GRANT: RET LABEL (RET=0 is success) +LABEL=$RANDOM + + +## multiple permission-granting programs + +The system assumes having a single permission granting program per +user. For a setup with multiple unconnected sessions per user (like +several TTYs) the permission granting program needs to coordinate +between these. 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 + +### Use 64 bit time by default + +Extend ext2fs to support 64bit time. ## Large Stores -The `ext2fs` translator from the upstream Hurd code base can only handle file -systems with sizes of less than roughly 2 GiB. +[[!inline pagenames=faq/2_gib_partition_limit raw=yes feeds=no]] -[[!tag open_issue_hurd]] +## 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. :) -### Ognyan's Work +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/lwip.mdwn b/hurd/translator/lwip.mdwn index efa59285..fab7d6f2 100644 --- a/hurd/translator/lwip.mdwn +++ b/hurd/translator/lwip.mdwn @@ -16,7 +16,10 @@ To configure lwip for internet connectivity, use the The argument /server/socket/2 is the node that the translator is to be attached to. This is followed by the translator program to run and any 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. +There, -i, -a, -g and -m are, quite obviously, the (Mach) device to use, the IP +address, the gateway and netmask. You can discover these values via the +`ifconfig` command (You need to run this command on the host system and NOT in +the qemu environment). More information can be found on Joan Lledo's blog: 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]]? |