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

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