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

Provided by: bilibop-common_0.4.20_amd64

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) mountpoint 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 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) 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_WHITELIST
One time the root filesystem is locked as the readonly branch of an aufs, the /etc/fstab file is modified
on the writable branch to lock all other local filesystems as readonly branches of aufs 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 whitelist 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.

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_SIZE
By default, bilibop-lockfs allocates half of RAM size (or TMPFS_SIZE if set in /etc/default/tpmfs) for
each aufs 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 mountpoints will be lost at shutdown. If some
mountpoints have been whitelisted, a second notification will be send 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 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_FAKE_DEVICE_MAP
By default, bilibop(7) rules build a /boot/grub/device.map style-file named grub-device.map in the
bilibop subdirectory in /run (defined by the BILIBOP_COMMON_BASENAME variable). The goal is to map the
removable device hosting the running system as (hd0), i.e. as the first disk in the BIOS boot sequence.
To make this faked map usable by update-grub(8), the file /boot/grub/device.map must be replaced by a
symlink to it. If it is the case, but you don't want to build this map, and then use a real map built on
the fly by grub-mkdevicemap(8), 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
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                                            2013-11-24                                    BILIBOP.CONF(5)

NAME

SYNOPSIS

DESCRIPTION

COMMON VARIABLES

BILIBOP-LOCKFS SPECIFIC VARIABLES

BILIBOP-RULES SPECIFIC VARIABLES

FILES

SEE ALSO

AUTHOR