BILIBOP.CONF(5)

💖 BILIBOP.CONF(5) 💖

Hey bestie! This is bilibop.conf(5) from the Bilibop Project, and it's giving "config file that runs the whole external-media situation." Let's get into it. ✨

✨ NAME ✨

bilibop.conf — configuration file of bilibop packages. 💅

🌸 SYNOPSIS 🌸

/etc/bilibop/bilibop.conf

🦋 DESCRIPTION 🦋

bilibop.conf is the configuration file for the bilibop-* packages. These are meant to be used on systems that run from an external and writable media — think USB, FireWire, MMC, eSATA. 🔥

It's made of VARIABLE=VALUE pairs. VARIABLE is a string that starts with BILIBOP_, and VALUE has to be wrapped in quotes if it contains blank characters (spaces or tabulations). No spaces around the equal sign (=) — not even one, bestie. Empty lines, or lines starting with a hash sign (#), are ignored.

Valid configuration options split into 'common' and 'specific' sections, like this:

🫶 COMMON VARIABLES 🫶

💜 BILIBOP_COMMON_BASENAME 💜

This one sets the basename of the bilibop subdirectories (or symlink) that get created in /dev and /run at boot time, either from inside the initramfs environment or from inside the running system. If it's empty or unset, it falls back to bilibop. If you change it to literally anything else, you have to make sure some symlinks or custom settings on your system reflect that new location. At minimum, if bilibop-rules is installed, you should run the helper scripts from that package — either by hand or with dpkg-reconfigure bilibop-rules. So yeah, maybe not the move to modify it. 🙈

Default: unset.

💅 BILIBOP-LOCKFS SPECIFIC VARIABLES 💅

💅 BILIBOP_LOCKFS 💅

This variable defines the main behaviour of the bilibop-lockfs initramfs script. It's a boolean:

If set to false, the system boots normally, and the other BILIBOP_LOCKFS_* variables are ignored — except BILIBOP_LOCKFS_NOTIFY_POLICY. If set to true, the initramfs script moves the normal root filesystem to another mountpoint used as the lower/readonly branch of an aufs(5) or overlay mountpoint (depends on your kernel version), and that mountpoint is used as the actual root filesystem. After that, the temporary and writable /etc/fstab file is modified to prepare other filesystems — if not whitelisted — to be mounted as readonly branches of aufs or overlay too.

If it's empty, unset, or set to anything else, a heuristic kicks in to set it to true or false, based on the removable flag of the disk in the sysfs attributes. Generally USB keys are seen as removable devices (true), and USB HDDs are seen as non-removable devices (false).

In all cases, you can override this variable from the boot commandline by adding lockfs or nolockfs to the kernel parameters line. BUT — if the drive is physically locked by a switch, that gets detected and all previous settings are overridden to set BILIBOP_LOCKFS as true. 😭

Default: unset.

🌈 BILIBOP_LOCKFS_POLICY 🌈

This defines an additional 'lock' level to enable or not. You can override it from the boot commandline with lockfs=hard or lockfs=soft.

• soft — The readonly branches of aufs(5) or overlay mountpoints will be set to ro (readonly). Later, these readonly filesystems can be remounted manually as writable to let root save some changes on them. This kind of action is highly discouraged here, but it's possible if you REALLY know what you do; otherwise it can lead to unexpected results, including of course data loss. 💀
• hard — The readonly branches of aufs mountpoints will be set to rr (real readonly); aufs uses this to optimize some internal operations. On top of that, the corresponding block devices will be set as readonly too, by using the read_only_volume_list variable in lvm.conf(5) for Logical Volumes, or blockdev(8) for other block devices. That avoids low-level write access to them (even by root) and avoids the filesystems being remounted later as writable.

If empty, unset, or set to anything else, the value falls back to hard. However, if the drive is physically locked, previous settings are overridden and the hard policy is automatically applied.

Default: unset.

🧚 BILIBOP_LOCKFS_UNION_METHOD 🧚

This defines which unionfs module is preferred and must be tried first. Since this module might not be supported by the current kernel, the other module supported by bilibop-lockfs is the fallback. You can override it from the boot commandline with lockfs=aufs or lockfs=overlay.

• aufs — Try to load aufs first, otherwise overlay.
• overlay — Try to load overlay first, otherwise aufs.

If empty, unset, or set to anything else, the value falls back to aufs. So as soon as the aufs-dkms package is installed, it gets used.

Default: unset.

🍓 BILIBOP_LOCKFS_PATH_PREFIX 🍓

This defines the main directory under which all readonly and writable branches are set. It can be any arbitrary string, as long as it's a valid name and the directory doesn't exist yet. You can override it from the boot commandline with lockfs=:prefix — note the leading colon, it's a marker.

If empty or unset, it defaults to the name of the module currently in use (i.e. aufs or overlay).

Default: unset.

👑 BILIBOP_LOCKFS_PATH_SCHEME 👑

This defines the structure of each set of ro and rw branches, regarding the others. It exists only because unlike aufs, overlay does not let you easily nest mount points (especially the upperdirs). You can override it from the boot commandline with lockfs=isolated or lockfs=hybrid or lockfs=nested.

• isolated — Each set of readonly and writable branches is created inside a dedicated directory. For example, to set up an aufs or overlay for /usr/local, /$union/usr/local/ro and /$union/usr/local/rw are used. So with this scheme, branches related to a specific mount point are clearly identified, but symlinks crossing filesystem boundaries are broken (on the branches, not on their union mount).
• nested — All readonly branches are set under the same readonly sub-tree, and all writable branches are set under the same writable sub-tree. So branches are easily browsable, and symlinks are preserved. For example, to set an aufs for /usr/local, /aufs/ro/usr/local and /aufs/rw/usr/local are used. This scheme is not available with overlay, and is the default with aufs, for backward compatibility with versions of bilibop until 0.4.23.
• hybrid — Readonly branches are nested, and writable branches are isolated.

If empty, unset, or set to anything else, the value falls back to nested with aufs, and isolated with overlay.

Default: unset.

🌸 BILIBOP_LOCKFS_WHITELIST 🌸

Once the root filesystem is locked as the readonly branch of an aufs or overlay filesystem, the /etc/fstab file is modified on the writable branch to lock all other local filesystems as readonly branches of aufs or overlay mountpoints. This variable lets you avoid the lockfs mechanism for some mountpoints: it's a whitespace separated list of mountpoints or device names (as known in fstab(5)) or tokens of the form UUID=fsuuid, LABEL=fslabel or TYPE=fstype. If the LABEL of a device contains spaces, replace them by underscores (_), as given by the output of udevadm info --query property --name DEVICE or blkid -o udev -p DEVICE for ID_FS_UUID, ID_FS_LABEL and ID_FS_TYPE variables. Note that whitelisting a mountpoint, a device name or any token matching the corresponding fstab entry makes the device whitelisted by the initramfs script, which is faster. Otherwise, mount.lockfs(8) will query metadata about the device to check if it must skip it or not.

Note that since mounting of /usr is now done inside the initramfs, locking it must be done inside the initramfs too. That means only the simple and early parser is available at this time, and the simplest way to whitelist /usr is to call it /usr, and nothing else, to avoid boot failures or unexpected results.

Also note that you can override (and blank) the value of this variable by adding lockfs=all on the boot commandline. This is also automatically done when the drive is physically locked. On the contrary, to append mountpoints to this whitelist from the boot commandline, you can also use an option of the form lockfs=-/foobar, where /foobar is the mountpoint to not lock; note that it is preceded by a minus sign (-).

Default: unset.

💖 BILIBOP_LOCKFS_FALLBACK_POLICY 💖

If a mount option or a filesystem type is not supported by aufs(5) or overlay, mount.lockfs will fail to lock it as expected. This variable defines the policy to apply in case of mount error. You can override it from the boot commandline with lockfs=ro or lockfs=asis.

• ro — The mount helper script will retry to mount the filesystem as if it was whitelisted, but readonly to avoid mistaken changes.
• asis — The mount helper script will retry to mount the filesystem as if it was whitelisted.

If empty, unset, or set to anything else, the value falls back to ro. However, if the drive is physically locked, previous settings are overridden and the ro policy is automatically applied.

Default: unset.

⭐ BILIBOP_LOCKFS_SIZE ⭐

By default, bilibop-lockfs allocates half of RAM size (or TMPFS_SIZE if set in /etc/default/tpmfs) for each aufs or overlay writable branch of a locked filesystem. You can override this value for some mountpoints in a whitespace separated list of mountpoint=size pairs. Sizes can be absolute (suffixed with k, K, m, M, g or G), or relative to the total amount of RAM (and suffixed with %). The size allocated to the root filesystem can be fixed here too, but can be overridden from the boot commandline with a lockfs=size kernel parameter.

Default: unset.

🎀 BILIBOP_LOCKFS_SWAP_POLICY 🎀

This variable defines what to do with swap devices listed in /etc/fstab (and optionally in /etc/crypttab). Generally, there's no sense in setting up a swap device on a flash memory stick, but this can be done on USB, FireWire or eSATA HDDs. Five policies are available:

• soft — Nothing is changed: lines in fstab(5) and crypttab(5) are kept as is.
• hard — Swap entries in fstab and crypttab are disabled (commented).
• noauto — The noauto keyword is appended to the list of options of swap entries in fstab and crypttab. This means swap devices can be enabled manually with swapon(8).
• crypt — Entries about encrypted swap devices are kept as is, others are disabled. ATTENTION: this option makes no difference between swap devices encrypted with a random key (and whose the content is unrecoverable after system halt) and those whose the content is written in clear on a Logical Volume being itself included in an encrypted Volume Group.
• random — entries about swap devices encrypted with a random key? bestie, those get kept as is. everything else gets disabled. that's it. 💅

so if BILIBOP_LOCKFS_SWAP_POLICY is set to some value nobody recognizes, the fallbacks are crypt or hard, and which one you get depends on the removable flag of the disk in the sysfs attributes: for devices that read as removable (heyyy USB sticks 🫶), the policy is to not use swap devices at all — that's the hard policy. and ngl, in every single case you can still turn swap off from the boot commandline with the noswap kernel parameter. note that this is not a bilibop(7) specific boot option, but it leads to setting BILIBOP_LOCKFS_SWAP_POLICY to hard. same deal if the script notices the drive is physically locked. 🔒

Default is unset.

💖 BILIBOP_LOCKFS_NOTIFY_POLICY 💖

this one decides when to tell the user that filesystems are locked or not. these notifications can pop off at system boot (needs the plymouth package installed for it to actually work) and also at desktop session startup (needs the libnotify-bin package installed to work). heads up: what follows describes the desktop notifications — plymouth(8) messages are less chatty, less verbose. there are four available policies:

• always — this is the fallback when the variable is unset, or set to literally anything other than never, lockfs or nolockfs. if the bilibop-lockfs feature is disabled, a notification gets sent saying that all information of the session can be written on the disk. if the feature is enabled, a notification gets sent saying that all changes under the (listed) aufs or overlay mountpoints will be lost at shutdown 😭. and if some mountpoints have been whitelisted, a second notification goes out saying that all changes under them will be kept at shutdown. ✨
• never — never send notification about filesystems status. simple. iconic. silent. 🤫
• lockfs — if the bilibop-lockfs feature is enabled, then a notification gets sent saying that all changes under aufs or overlay mountpoints will be lost at shutdown.
• nolockfs — if the bilibop-lockfs feature is disabled, it does the same thing as always. if the feature is enabled and some mountpoints have been whitelisted, then a notification gets sent saying that all changes under them will be kept at shutdown.

in all cases, any user can — for their own desktop session — override the admin settings by copying lockfs-notify.desktop (normally in /etc/xdg/autostart) into their own .config/autostart directory and editing the lines beginning with Exec= or Hidden=. see lockfs-notify(1) for the deets. 👑

Default is unset.

---

🦋 BILIBOP-RULES SPECIFIC VARIABLES 🦋

okay so unlike all the previous variables, whose modifications only take effect after the system has been rebooted, most of the following BILIBOP_RULES_* variables — except the first one — can be modified and the changes applied during the same session by running lsbilibop -c. see lsbilibop(8). live changes, no reboot, we love to see it. 💅

🌸 BILIBOP_RULES_SYSTEM_INTERNAL 🌸

by default, bilibop rules use udisks facilities (both versions 1.x and 2.x) to override the usual bus type detection of whether a device counts as 'system internal'. what does that mean for you? it means root privileges will be needed to manage devices hosted by the same disk as the root filesystem. if you don't want this global behaviour, explicitly set this to false (all other values have no effect, i.e. they have the same effect as true). 🙈

Default is unset.

🌈 BILIBOP_RULES_SYSTEM_INTERNAL_WHITELIST 🌈

if BILIBOP_RULES_SYSTEM_INTERNAL is not false, then all partitions hosted on the same disk as the root filesystem get considered 'system internal'. to disable this behaviour for only some devices — say, if you want a partition you can mount/unmount without needing root privileges — you can list them here, separated by spaces. for each device or group of devices, you must specify at least one token of the form UUID=fsuuid, LABEL=fslabel, TYPE=fstype or USAGE=fsusage. and if the LABEL of a device contains spaces, replace them by underscores (_), exactly as given by the output of udevadm info --query property --name DEVICE or blkid -o udev -p DEVICE for the ID_FS_UUID, ID_FS_LABEL, ID_FS_TYPE and ID_FS_USAGE variables. periodt. ✨

Default is unset.

🎀 BILIBOP_RULES_PRESENTATION_HIDE 🎀

by default, bilibop rules hide (if possible) the filesystems contained on the same physical hard disk or memory stick as the root filesystem. this applies to desktop applications based on udisks (both versions 1.x and 2.x). if you don't want to hide the bilibop volumes, explicitly set this to false (all other values have no effect, i.e. they have the same effect as true). 🫣

Default is unset.

💜 BILIBOP_RULES_PRESENTATION_HIDE_WHITELIST 💜

if BILIBOP_RULES_PRESENTATION_HIDE is not false, all volumes hosted on the same disk as the root filesystem get hidden from the user. to disable this behaviour for only some devices, list them here, separated by spaces. for each device or group of devices, you must specify at least one token of the form UUID=fsuuid, LABEL=fslabel, TYPE=fstype or USAGE=fsusage. if the LABEL of a device contains spaces, replace them by underscores (_), as given by the output of udevadm info --query property --name DEVICE or blkid -o udev -p DEVICE for the ID_FS_UUID, ID_FS_LABEL, ID_FS_TYPE and ID_FS_USAGE variables. 💅

Default is unset.

⭐ BILIBOP_RULES_PRESENTATION_ICON ⭐

if a device is not hidden, it can be shown to the user with a different icon than the default one. cute, right? for each device or group of devices whose default icon you want to change, you must specify at least one token of the form UUID=fsuuid:icon, LABEL=fslabel:icon, TYPE=fstype:icon or USAGE=fsusage:icon. the icon name must follow the freedesktop.org icon theme specification. if the LABEL of a device contains spaces, replace them by underscores (_), as given by the output of udevadm info --query property --name DEVICE or blkid -o udev -p DEVICE for the ID_FS_UUID, ID_FS_LABEL, ID_FS_TYPE and ID_FS_USAGE variables. 🎨

Default is unset.

🦄 BILIBOP_RULES_PRESENTATION_NAME 🦄

if a device is not hidden, it can be shown to the user with a different name than the default one (which is generally the label of the filesystem). main character energy for your partitions, fr fr. for each device or group of devices whose default name you want to change, you must specify at least one token of the form UUID=fsuuid:name, LABEL=fslabel:name, TYPE=fstype:name or USAGE=fsusage:name. if the LABEL of a device contains spaces, replace them by underscores (_), as given by the output of udevadm info --query property --name DEVICE or blkid -o udev -p DEVICE for the ID_FS_UUID, ID_FS_LABEL, ID_FS_TYPE and ID_FS_USAGE variables. ✨

Default is unset.

---

📁 FILES 📁

• /etc/bilibop/bilibop.conf
• /usr/share/doc/bilibop-common/examples/bilibop.conf
• /usr/share/doc/bilibop-lockfs/examples/bilibop.conf
• /usr/share/doc/bilibop-rules/examples/bilibop.conf

---

👀 SEE ALSO 👀

aufs(5), bilibop(7), blkid(8), crypttab(5), fstab(5), lockfs-notify(1), lsbilibop(8), mount(8), mount.lockfs(8), notify-send(1), plymouth(8), proc(5), udev(7), udevadm(8), udisks(7), udisks(8)

---

💖 AUTHOR 💖

this manual page has been written by Bilibop Project <quidame@poivron.org>. shoutout to them, absolute legends. 🫶

---

and that's a wrap on BILIBOP.CONF(5) bestie!! 🎀 this page came from the bilibop project, version dated 2020-02-07, and it lives at section BILIBOP.CONF(5) — go forth and configure your filesystems like the icon you are. slay, no cap, bye!! 💅✨🦋