HUMFSIFY(1)

📦 version 20070815.4, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute

✨ NAME ✨

humfsify — bestie, this little icon converts a directory into the format the UML humfs file system needs. It's giving "glow-up for your folders" 💅

🌸 SYNOPSIS 🌸

humfsify [user] [group] [size]

🦋 DESCRIPTION 🦋

Okay so, this manual page is a lil quick intro to the humfsify command, that's it, that's the vibe.

Real talk though: this page exists for the Debian GNU/Linux distribution specifically, because the original program lowkey does not have a manual page of its own 😭. Instead it ships documentation in HTML format — check the SEE ALSO section below, bestie.

humfsify is a Perl script, and it's literally necessary: it takes a directory and converts it to the format expected by the UML humfs file system. No script, no humfs, no cap. ✨

💜 HISTORY 💜

Not me giving you the whole origin story, but you need the lore 📖✨.

UMLFS was born with the idea to substitute the Hostfs implementation with a proper one for the UML purpose: when you manage files with Hostfs within UML you need to work with two different permission layers (the Host one and the UML one), which have different ideas of ownerships. It's giving two group chats that can't agree on who's admin 💀.

This becomes evident when you need to create a file as a non-root user on UML: you first need to interact with the UML file system implementation, and then with the host side.

The result of a file creation on a mounted hostfs file system is not what you expected: you can see that the file permissions refer to the Host side user rather than the UML creator. Yeah. Awkward.

So, to be clear on the cast of characters:

  • The Host side user is to be intended as the UML instance launcher.
  • The UML side user is the one you used to log in the UML instance.

And then it gets worse 😭. You can encounter a more-critical problem when creating a device node, operation that usually requires root privileges: you used a common user to launch the UML and, since the operation is done on the Host, it fails, even if you logged in as root. Root in the UML, rootless on the host, and everything just falls apart. Iconic behaviour from permissions, honestly.

Thus you need a set of tools which requires to bypass the Hostfs permission checks on the Host side: this is done by separating the file permissions and the ownership from the host's files. This is the concept behind the HumFs and its humfsify implementation. 🎀

🎀 ARGUMENTS 🎀

  • user — This is the user that needs to 'convert' a directory to the UML file system to use UML. This is the host user who will be using this filesystem from within UML. It may be specified as either a user name or a numeric user id.
  • group — This is the group which your UML user belongs to. This may be either a group name or a numeric group id.
  • size — This is the size of the file system as seen within the UML instance. It must be expressed in Gigabytes ("G"), Megabytes ("M"), or KiloBytes ("K"). ⚠️ Like, actually use one of those letters, bestie.

🌈 EXAMPLES 🌈

Create a directory on the host and mount it with humfsify — step by step, we're doing this together 🫶

host% mkdir your-humfs-dir

host% cd humfs-dir

Within this directory create a new one where you would like to have a UML-like hierarchy, i.e. you can loop-mount an UML rootfs:

host% mkdir dir-to-be-humsified

host# mount -o loop rootfs /mnt

host% cp -a /mnt dir-to-be-humsified/data

host# humfsify user group 512M

Then verify it on UML and mount the humfsified directory:

UML# mount none /your-uml-host -t humfs -o

where '/your-uml-mount-point' is the mount point on UML for the humfsified file system, and .../dir-to-be-humfsified is the humfsified directory in the example above. The '-t' mount option specifies that the file system is to be mounted as 'humfs'. 🦋

Heads up, bestie: I'm reading these examples to you exactly as they're written in the page, quirks and all — copy them verbatim and you're golden. ✨

💖 SEE ALSO 💖

The HostFs (link to URL http://user-mode-linux.sourceforge.net/new/hostfs.html) usage explanation within the User-Mode-Linux Web Site — go read it, it's the whole HTML documentation situation I mentioned earlier 📚

👑 AUTHOR 👑

humfsify was written by Jeff Dike. 💜

This manual page was written by Stefano Melchior stefano.melchior@openlabs.it for the Debian GNU/Linux system, based on material in the Official User Mode Linux Web Site. Slay, honestly.

And that's the whole page, bestie 🎀 — straight out of the General Commands Manual, section HUMFSIFY(1), footer and all: HUMFSIFY(1). Go humfsify something iconic. Periodt. 💅✨

📦 where this page comes from