diff options
Diffstat (limited to 'hurd/translator')
30 files changed, 1012 insertions, 80 deletions
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 -## Large Stores - -The `ext2fs` translator from the upstream Hurd code base can only handle file -systems with sizes of less than roughly 2 GiB. +### Use 64 bit time by default -[[!tag open_issue_hurd]] +Extend ext2fs to support 64bit time. +## Large Stores -### Ognyan's Work +[[!inline pagenames=faq/2_gib_partition_limit raw=yes feeds=no]] + +## Create your own custom ext2fs + + $ dd if=/dev/zero of=silly.fs bs=1024k count=8 + $ /sbin/mkfs.ext2 -E root_owner=$UID:0 silly.fs + $ settrans -c silly /hurd/ext2fs `pwd`/silly.fs + $ ps -e | grep silly # ext2fs has not started + $ ls silly + $ ps -e | grep silly | awk '{ print $6 " " $7 }' + /hurd/ext2fs /home/joshua/silly.fs + $ cd silly + $ echo 'hello' > hello.txt + $ mkdir silly-dir + $ cd .. + $ fsysopts silly + /hurd/ext2fs --writable --relatime --no-inherit-dir-group /home/joshua/silly.fs + $ fsysopts silly --readonly # stop writes to the filesystem + $ fsysopts silly --writable # let writes again + +Try to make the filesystem read-only with fsysopts. Note how further +write attempts fail now. Try to kill the active translator with +settrans -g. + +You could go crazy even! Why not make something like this: + + ~/silly <--> silly.fs + | \ + | \ + | \ + | \ + | \ + \|/ \/ + silly1 <-> silly1.fs + ... + + /hurd/joshua/silly/silly1/silly2/silly3/silly4 + +Each sillyN is another ext2fs filesystem! Make sure that as N gets +bigger sillyN.fs gets smaller. Let us know in the `#hurd` [irc +channel](https://web.libera.chat/) how "silly" you are. :) + +The current record is 2! + + $ ps -e | grep silly | awk '{print $6 " " $7}' + /hurd/ext2fs /home/joshua/silly.fs + /hurd/ext2fs /home/joshua/silly/silly1.fs + +What is the limit? How many nested ext2fs translators can you have? +You could have 32 ["silly" +directories](https://logs.guix.gnu.org/hurd/2024-05-31.log#005021). +That's very silly! + +### Ognyan's Work to allow ext2 to surpass the 2 GiB limit * Ognyan Kulev, [[*Supporting Large ext2 File Systems in the Hurd*|ogi-fosdem2005.mgp]], 2005, at FOSDEM @@ -40,8 +92,8 @@ systems with sizes of less than roughly 2 GiB. * <http://kerneltrap.org/node/4429> -Ognyan's patch lifts this limitation (and is being used in the -[[Debian_GNU/Hurd_distribution|running/debian]]), but it introduces another +Ognyan's patch lifted this limitation (and is being used in the +[[Debian_GNU/Hurd_distribution|running/debian]]), but it introduced another incompatibility: `ext2fs` then only supports block sizes of 4096 bytes. Smaller block sizes are commonly automatically selected by `mke2fs` when using small backend stores, like floppy devices. @@ -565,18 +617,6 @@ That would be a nice improvement, but only after writeback throttling is impleme separate partitions is a way to alleviate them -## `ext2fs: ../../libdiskfs/rdwr-internal.c:42: _diskfs_rdwr_internal: Assertion `!diskfs_readonly' failed.` - -### IRC, freenode, #hurd, 2014-02-22 - - <gg0> login: init: notifying pfinet of shutdown...init: notifying tmpfs - none of shutdown...init: notifying tmpfs none of shutdown...init: - notifyi. - <gg0> ext2fs: ../../libdiskfs/rdwr-internal.c:42: _diskfs_rdwr_internal: - Assertion `!diskfs_readonly' failed. - <gg0> In tight loop: hit ctl-alt-del to reboot - - # Documentation * <http://e2fsprogs.sourceforge.net/ext2.html> diff --git a/hurd/translator/fakeroot.mdwn b/hurd/translator/fakeroot.mdwn new file mode 100644 index 00000000..59dd7ead --- /dev/null +++ b/hurd/translator/fakeroot.mdwn @@ -0,0 +1,86 @@ +[[!meta copyright="Copyright © 2024 Free Software Foundation, +Inc."]] + +[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable +id="license" text="Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no Invariant +Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license +is included in the section entitled [[GNU Free Documentation +License|/fdl]]."]]"""]] + +[[!tag stable_URL]] + +A translator for faking privileged access to an underlying filesystem. + +This translator appears to give transparent access to the underlying +directory node. However, all accesses are made using the credentials +of the translator regardless of the client and the translator fakes +success for chown and chmod operations that only root could actually +do, reporting the faked IDs and modes in later stat calls, and allows +any user to open nodes regardless of permissions as is done for root. + +## A trivial example + +Let's demonstrate that chown and chgrp requires root permission. + + $ mkdir ~/etc + $ touch ~/etc/this + $ settrans ~/etc/this /hurd/hello + $ ls -lha ~/etc/ + total 12K + drwxr-xr-x 2 joshua joshua 4.0K Oct 15 20:12 . + drwxr-xr-x 33 joshua joshua 4.0K Oct 15 20:11 .. + -r--r--r-- 1 joshua joshua 14 Oct 15 20:12 this + $ + $ chown root ~/etc/this + chown: changing ownership of '/home/joshua/etc/this': Operation not permitted + +Now, let's run through `fakeroot-hurd`: + + $ fakeroot + # ls -lha ~/etc/ + total 12K + drwxr-xr-x 2 root root 4.0K Oct 15 20:12 . + drwxr-xr-x 33 root root 4.0K Oct 15 20:11 .. + -r--r--r-- 1 root root 14 Oct 15 20:12 this + +The shell now believes we are root, and all the owner and group are turned into +root. Now we can chmod, chown, chgrp, ... + + # chown daemon ~/etc/this + # ls -lha ~/etc/ + total 12K + drwxr-xr-x 2 root root 4.0K Oct 15 20:12 . + drwxr-xr-x 33 root root 4.0K Oct 15 20:11 .. + -r--r--r-- 1 daemon root 14 Oct 15 20:12 this + +## A manual example + +We can also attach `/hurd/fakeroot` manually to `~/etc`, and we'll be able to +use `chown`, `chgrp`, `chmod`, etc. as a normal user. + + $ settrans ~/etc /hurd/fakeroot + $ cd ~/etc + $ cd + $ showtrans ~/etc + /hurd/fakeroot + $ ls -lha ~/etc/ + + total 16K + drwxr-xr-x 2 joshua joshua 4.0K Oct 15 20:12 . + drwxr-xr-x 33 root root 4.0K Oct 15 20:11 .. + -r--r--r-- 1 root root 14 Oct 15 20:12 this + +`fakeroot` turns all the owner and group to root when it starts. Now +we can chmod, chown, and chgrp as a normal user. + + $ chown joshua ~/etc/this + $ chgrp joshua ~/etc/this + $ chmod +xr ~/etc/this + $ ls -lha ~/etc/ + total 16K + drwxr-xr-x 2 joshua joshua 4.0K Oct 15 20:12 . + drwxr-xr-x 33 root root 4.0K Oct 15 20:11 .. + -rwxr-xr-x 1 joshua joshua 14 Oct 15 20:12 this + diff --git a/hurd/translator/ftpfs.mdwn b/hurd/translator/ftpfs.mdwn new file mode 100644 index 00000000..ac04890c --- /dev/null +++ b/hurd/translator/ftpfs.mdwn @@ -0,0 +1,40 @@ +[[!meta copyright="Copyright © 2024 Free Software Foundation, Inc."]] + +[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable +id="license" text="Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no Invariant +Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license +is included in the section entitled [[GNU Free Documentation +License|/fdl]]."]]"""]] + +[[!tag stable_URL]] + +[[!toc]] + +The File Transfer Protocol is a old, simple, and insecure method of +sharing files between computers. The Hurd supports it via `ftpfs`. + + $ settrans gnu.org /hurd/ftpfs ftp://ftp.gnu.org + $ cat ftp\:/ftp.gnu.org/README | grep GNU | head -n 2 + This is ftp.gnu.org, the FTP server of the the GNU project. + gnu/ Contains GNU programs and documents that we develop for the GNU + +So it's actually pretty cool to use standard command line utilities to +search through a remote file. But it is slightly a hassle to set up +`ftpfs` by hand for each server like this. +With the Hurd's [[hostmux]] you can actually skip that first +settrans command, and type in any FTP server and automatically connect +to it. On my box, this just works: + + $ ls ~/ftp://ftp.gnu.org/ + +`~/ftp:` is already set up to re-route any path lookup to the correct +FTP server. You can set up `~/ftp:` on your Hurd OS via the +[[hostmux]] translator: + + $ settrans -c $HOME/ftp: /hurd/hostmux /hurd/ftpfs / + +The [[translator primer|hurd/documentation/translator_primer]] shows +you how you can use ftpfs to mount a remote iso file and examine its +contents. diff --git a/hurd/translator/httpfs.mdwn b/hurd/translator/httpfs.mdwn index 8b02aa06..0ce0f30b 100644 --- a/hurd/translator/httpfs.mdwn +++ b/hurd/translator/httpfs.mdwn @@ -12,6 +12,84 @@ License|/fdl]]."]]"""]] While the httpfs translator works, it is only suitable for very simple use cases: it just provides the actual file contents downloaded from the URL, but no additional status information that are necessary for interactive use. (Progress indication, error codes, HTTP redirects etc.) +# Introduction + +Here we describe the structure of the /http filesystem for the Hurd. +Under the Hurd, we provide a translator called 'httpfs' which is intended +to provide the filesystem structure. + +The httpfs translator accepts an "http:// URL" as an argument. The underlying +node of the translator can be a file or directory. This is guided by the --mode +command lineoption. Default is a directory. + +If its a file, only file system read requests are supported on that node. If +its a directory, we can cd into that directory and ls would list the files in +the web server. A web server may provide a directory listing or it may not +provide, whatever it be the case the web server always returns an HTML stream +for an user request (GET command). So to get the files residing in the web +server, we have to parse the incoming HTML stream to find out the anchor +tags. These anchor tags point to different pages or files in the web +server. These file name are extracted and filled into the node of the +translator. An anchor tag can also be a pointer to an external URL, in such a +case we just show that URL as a regular file so that the user can make file +system read requests on that URL. In case the file is a URL, we change the name +of URL by converting all the /'s with .'s so that it can be displayed in the +file system. + +Only the root node is filled when the translator is set, subdirectories inside +that are filled as on demand, i.e. when a cd or ls occurs on that particular sub +directory. + +The File size is now displayed as 0. One way of getting individual file sizes is +sending a GET request for each file and cull the file size from Content-Length +field of an HTTP response. But this may put a very heavy burden on the network, +So as of now we have not incorporated this method with this http translator. + +The translator uses the libxml2 library for doing the parsing of HTML +stream. The libxml2 provides SAX interfaces for the parser which are used for +finding the begining of anchor tags `<A href="i.html">`. So the translator has +dependency on the libxml2 library. + +If the connection to the Internet through a proxy, then the user must explicitly +give the IP address and port of the proxy server by using the command line +options --proxy and --port. + + +# How to Use httpfs + + # settrans -a tmp/ /hurd/httpfs http://www.gnu.org/software/hurd/index.html + +<Remember to give the / at the end of the URL, unless you are specifying a specific file like www.hurd-project.com/httpfs.html > + + # cd tmp/ + + # ls -l + + # settrans -a tmp/ /hurd/httpfs http://www.gnu.org/software/hurd/index.html --proxy=192.168.1.103 + --port=3126 + +The above command should be used in case if the access to the Internet is +through a proxy server, substitute your proxies IP and port no.s + +# TODO + +- https:// support +- scheme-relative URL support (eg. "//example.com/") +- query-string and fragment support +- HTTP/1.1 support +- HTTP/2 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. [[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 <http://www.nongnu.org/hurdextras/#httpfs> 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/translator/xmlfs.mdwn b/hurd/translator/xmlfs.mdwn index a4de1668..6028d43f 100644 --- a/hurd/translator/xmlfs.mdwn +++ b/hurd/translator/xmlfs.mdwn @@ -11,6 +11,80 @@ License|/fdl]]."]]"""]] `xmlfs` is a translator that provides access to XML documents through the filesystem. +# How to Use xmlfs + + xmlfs - a translator for accessing XML documents + +This is only an alpha version. It works in read only. It supports +text nodes and attributes. It doesn't do anything fancy like size +computing, though. Here is an example of how to use it: + + $ wget http://cvs.savannah.nongnu.org/viewvc/*checkout*/hurdextras/xmlfs/example.xml?content-type=text%2Fplain; + $ settrans -ca xml /hurd/xmlfs example.xml #the website says to use ./xmlfs + $ cd xml; ls + library0 library1 + $ cd library0; ls -A + .text1 .text2 @name book0 book1 book2 sub-library0 sub-library1 + $ cat .text2 + +CDATA, again ! + + $ cat book0 + <book> + <author>Mark Twain</author> + <title>La case de l'oncle Tom</title> + <isbn>4242</isbn> + </book> + $ cat book0/author/.text + Mark Twain + +As you can see, text nodes are named .textN, with N an integer +starting from 0. Sorting is supposed to be stable, so you get the same +N every time you access the same file. If there is only one text node +at this level, N is ommitted. Attributes are prefixed with @. + +An example file, example.xml, is provided. Of course, it does not +contain anything useful. xmlfs has been tested on several-megabytes +XML documents, though. + +Comments are welcome. + + -- Manuel Menal <mmenal@hurdfr.org> + +# TODO +- Handle memory usage in a clever way: + - do not dump the nodes at each read, try to guess if read() + is called in a sequence of read() operations (e.g. cat reads + 8192 bytes by 8192 bytes) and if it is, cache the node + contents. That'd need a very small ftpfs-like GC. + - perhaps we shouldn't store the node informations from + first access to end and have a pool of them. That might come + with next entries though. +- Handle changes of the backing store (XML document) while running. + (Idea: we should probably attach to the XML node and handle + read()/write() operations ourselves, with libxml primitives.) +- Write support. Making things like echo >, sed and so on work is + quite obvious. Editing is not -that- simple, 'cause we could + want to save a not XML well-formed, and libxml will just return + an error. Perhaps we should use something like 'sync'. +- Handle error cases in a more clever way ; there are many error + conditions that will just cause xmlfs to crash or do strange + things. We should review them. +- Make sorting *really* stable. + +# TODO WISHLIST +-------- + +- Kilobug suggested a --xslt option that would make xmlfs provide + a tree matching the XSLT-modified document. + (Problem: In this case we cannot attach easily to the .xml 'cause + the user would loose access to theirs original document. Perhaps + we should allow an optional "file.xml" argument and check if it + is not the same as the file we are attaching to when --xslt is + specified.) +- DTD support ; perhaps XML schema/RelaxNG when I'm sure I understand + them ;-) + # Source |