bionic (5) bilibop.conf.5.gz

Provided by: bilibop-common_0.5.4_amd64 bug

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_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.

       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).

       • 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
       One time 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 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 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_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

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>.