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

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