Ubuntu Manpage: bilibop.conf - configuration file of bilibop packages

NAME

       bilibop.conf - configuration file of bilibop packages

SYNOPSIS

       /etc/bilibop/bilibop.conf

DESCRIPTION

       bilibop.conf  is  the  configuration file of bilibop-* packages, which are intended to be used on systems
       running from an external and writable media (USB, FireWire, MMC, eSATA). It is composed of VARIABLE=VALUE
       pairs, where VARIABLE is a string beginning by 'BILIBOP_', and VALUE must be inserted between  quotes  if
       it  contains  blank characters (spaces or tabulations). Spaces around the equal sign (=) are not allowed.
       Empty lines or lines beginning by a hash sign (#) are ignored.

       Valid configuration options can be divided in 'common' and 'specific' sections, as follows:

COMMON VARIABLES

   BILIBOP_COMMON_BASENAME
       This variable defines the basename of bilibop subdirectories (or symlink) that will be  created  in  /dev
       and  /run  at  boot  time,  from into the initramfs environment or from into the running system. If it is
       empty or unset, the value will fallback to 'bilibop'.  If you modify it to anything  else,  you  have  to
       take  care  that  some  symlinks or custom settings of your system reflect the new location. At least, if
       bilibop-rules is installed, you should execute the helper scripts provided by  this  package,  either  by
       hand or with 'dpkg-reconfigure bilibop-rules'.  So, maybe it is not a good idea to modify it.

       Default is unset.

BILIBOP-LOCKFS SPECIFIC VARIABLES

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

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

If empty, unset, or set to anything else, then a heuristic will be used to set it to true or false,
depending on the removable flag of the disk in the sysfs attributes, knowing that generally USB keys are
seen as removable devices (true), and USB HDDs are seen as non removable devices (false).

In all cases, the value of this variable can be overridden from the boot commandline by adding 'lockfs'
or 'nolockfs' to the line of kernel parameters. However, if the drive is physically locked by a switch,
this will be detected and all previous settings will be overridden to set BILIBOP_LOCKFS as true.

Default is unset.

BILIBOP_LOCKFS_POLICY
This variable defines an additional 'lock' level to be enabled or not. Its value can be overridden 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 allow root to save some changes on them.
This kind of action is highly discouraged here, but is 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); this is used by aufs to
optimize some internal operations. Additionally, 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, avoiding low-level write access to them (even by root) and
avoiding the filesystems to be remounted later as writable.

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

Default is unset.

BILIBOP_LOCKFS_UNION_METHOD
This variable defines which unionfs module is preferred and must be tried first. As this module may be
unsupported by the current kernel, the other module supported by 'bilibop-lockfs' is the fallback. Its
value can be overridden 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 will fallback to aufs. So as soon as aufs-dkms
package is installed, it is used.

Default is unset.

BILIBOP_LOCKFS_PATH_PREFIX
This variable defines the main directory under which all readonly and writable branches are set. It may
be any arbitrary string, as long as it is a valid name and the directory does not exist yet. Its value
can be overridden from the boot commandline with 'lockfs=:prefix' (note the leading colon that is a
marker).

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

Default is unset.

BILIBOP_LOCKFS_PATH_SCHEME
This variable defines the structure of each set of ro and rw branches, regarding the others. It exists
only because unlike aufs, overlay does not allow one to easily nest mount points (especially the
upperdirs). Its value can be overridden from the boot commandline with 'lockfs=isolated' or
'lockfs=hybrid' or 'lockfs=nested'.

• isolated
Each set of readonly and writable branches is created into 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 reaonly 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
avalaibable 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 will fallback to nested with aufs, and isolated with
overlay.

Default is 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 gives the ability to avoid the lockfs mechanism
for some mountpoints: this is 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 is whitelisted by the initramfs script, that 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 into the initramfs, locking it must be done into the
initramfs too. It means that 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 it is possible to 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, it is also possible to use
an option of the form 'lockfs=-/foobar', where /foobar is the mountpoint to not lock; not that it is
preceded by a minus sign (-).

Default is 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. Its value can be
overridden 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 will fallback to ro. However, if the drive is
physically locked, previous settings will be overridden and the ro policy will be automatically applied.

Default is 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. It is possible to 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 is 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 is no sense to setup 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 are kept as is, others are disabled.

If BILIBOP_LOCKFS_SWAP_POLICY is not set to a known value, crypt or hard are the fallbacks, depending on
the removable flag of the disk in the sysfs attributes: for devices seen as removable (USB sticks), the
policy is to not use swap devices at all (hard policy). Note that in all cases, swap usage can be
disabled from the boot commandline with the noswap kernel parameter, which is not a bilibop(7) specific
boot option, but leads to set BILIBOP_LOCKFS_SWAP_POLICY to hard. This is also the case if the script
detects that the drive is physically locked.

Default is unset.

BILIBOP_LOCKFS_NOTIFY_POLICY
This variable defines when to notify the user that filesystems are locked or not. Such notifications can
be sent at system boot (needs plymouth package installed to work) as well as desktop session startup
(needs libnotify-bin package installed to work). What follows describes desktop notifications;
plymouth(8) messages are less verbose. There are four available policies:

• always
This is the fallback when the variable is unset or set to something else than never, lockfs or
nolockfs. If the bilibop-lockfs feature is disabled, then a notification will be send to say that all
information of the session can be written on the disk. If the feature is enabled, a notification will
be send to say that all changes under the (listed) aufs or overlay mountpoints will be lost at
shutdown. If some mountpoints have been whitelisted, a second notification will be sent to say that all
changes under them will be kept at shutdown.

• never
Never send notification about filesystems status.

• lockfs
If the bilibop-lockfs feature is enabled, then a notification will be send to say that all changes
under aufs or overlay mountpoints will be lost at shutdown.

• nolockfs
If the bilibop-lockfs feature is disabled, does the same thing as for always. If the feature is
enabled and some mountpoints have been whitelisted, then a notification will be send to say that all
changes under them will be kept at shutdown.

In all cases, any user can (for its own desktop session) override the admin settings by copying
lockfs-notify.desktop (normally in /etc/xdg/autostart) in its own .config/autostart directory and by
modifying the lines beginning by Exec= or Hidden=. See lockfs-notify(1) for details.

Default is unset.

BILIBOP-RULES SPECIFIC VARIABLES

Unlike the previous variables whose modifications take effect only 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 a same session by running 'lsbilibop -c'. See lsbilibop(8).

BILIBOP_RULES_SYSTEM_INTERNAL
By default, bilibop rules use udisks (both versions 1.x and 2.x) facilities to override the usual bus
type detection of whether a device is considered 'system internal'. This means root privileges will be
needed to manage devices hosted by the same disk than the root filesystem. If you don't need this global
behaviour, explicitly set this to false (all other values have no effect, i.e. have the same effect than
true).

Default is unset.

BILIBOP_RULES_SYSTEM_INTERNAL_WHITELIST
If BILIBOP_RULES_SYSTEM_INTERNAL is not 'false', all partitions hosted on the same disk than the root
filesystem will be considered as 'system internal'. To disable this behaviour for only some devices —
for example if you want a partition mountable/unmountable without needs of 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. 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, ID_FS_TYPE and ID_FS_USAGE variables.

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 than 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. have the same effect than true).

Default is unset.

BILIBOP_RULES_PRESENTATION_HIDE_WHITELIST
If BILIBOP_RULES_PRESENTATION_HIDE is not 'false', all volumes hosted on the same disk than the root
filesystem will be hidden to the user. To disable this behaviour for only some devices, 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. 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, 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 another icon than the default one. For each
device or group of devices you want to change the default icon, 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 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 another name than the default one (generally
the label of the filesystem). For each device or group of devices you want to change the default name,
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
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

AUTHOR

       This manual page has been written by Bilibop Project <quidame@poivron.org>.

bilibop                                            2020-02-07                                    BILIBOP.CONF(5)

NAME

SYNOPSIS

DESCRIPTION

COMMON VARIABLES

BILIBOP-LOCKFS SPECIFIC VARIABLES

BILIBOP-RULES SPECIFIC VARIABLES

FILES

SEE ALSO

AUTHOR