xenial (5) writable-paths.5.gz

Provided by: initramfs-tools-ubuntu-core_0.7.43_all bug

NAME
       writable-paths - make select paths writable


SYNOPSIS
       /etc/system-image/writable-paths


DESCRIPTION
       An  Ubuntu  Core system normally contains three partitions: dual read-only root partitions and a writable
       data partition, used to record all persistent system changes.

       The file writable-paths allows specific paths in the root  partition  filesystem  to  be  made  writable,
       whilst  leaving  the  rest of the root filesystem read-only. It does this by creating overlaying writable
       mounts on top of the read-only root  filesystem.  These  writable  mounts  are  backed  to  the  writable
       partition.

       Any path not specified in this file, either directly or via a parent directory is by definition read-only
       meaning all writes are disallowed.

       Note further that this file effectively subsumes the fstab(5) file since the writable-paths file is  read
       at early system startup and used to generate dynamically the fstab(5) file for the host.

       The  format  of  the  file  is  similar  to the fstab(5) file in that it contains a number of whitespace-
       separated fields which specify how each path should be handled.

       Comment lines are those starting with '#'.

       Note that the order of entries in the file should not matter since it is up to the init system to  handle
       mount dependencies when parsing the fstab(5) file.


WARNINGS
       Like  the  fstab(5)  file that it generates, modifications to the writable-paths file should be done with
       extreme caution since invalid (or missing) entries may lead to a broken system.

       Do not modify this file unless you understand how to work in the initramfs should you introduce  problems
       inadvertently.

       It  is  also  important  to  understand that you should not attempt to modify the fstab(5) file since all
       changes will be discarded on next boot.


FIELDS
       1  Mount point

          A pre-existing directory on the read-only root partition where the writable mount  will  overlaid  (in
          other words the target or destination of the mount).

       2  Persistent storage path

          An  arbitrary  name  which  will form the mount source directory. Note that this name does not need to
          relate to a pre-existing directory - it will be created as required as a sub-directory of the writable
          partition.

          The following names are reserved as they have special meaning:

          none   Do not create a directory on the writable partition (used for temporary mounts).

          auto   Choose a name automatically, based on the value of the mount point.

       3  Type

          The type of mount to create. The following are recognised:

          persistent
                 Writes to the mount point will be persisted to the writable partition.

          synced Any file appearing in the root filesystem will also be copied over to writable storage. However
                 file removals are still not synced and files existing in both read-only and  writeable  storage
                 will not be updated.

          temporary
                 Writes  to  the  mount  point  will only be maintained in-memory (using tmpfs(5)) , meaning all
                 changes will be lost on reboot.

       4  Action

          Determines whether the mount requires  a  further  operation  before  it  becomes  usable.  Recognised
          options:

          transition
                 Allows  moving  a  read-only  rootfs  directory to a writeable directory stored on the writable
                 partition. This is achieved by performing a verbatim  move  (technically  a  copy  followed  by
                 removal  of  the  original data) of any data from the mount point on the root filesystem to the
                 writable filesystem before mounting.  This option requires the type field to be persistent.

                 WARNING: This is a one-off operation which requires that the source directory on  the  writable
                 partition  not  exist  initially:  if  this  condition is satisfied, the directory will then be
                 created and the data moved on first boot. Although the mountpoint will be writable,  note  that
                 subsequent  boots will ignore any new files appearing or disappearing in the original read-only
                 rootfs location unless you perform a factory reset.

          none   No action is performed.

       5  Mount Flags

          Normally this is either none or defaults but can be any flags recognised by mount(8).


EXAMPLES
              •   Allow  persistent  writes  to  /home  with  all  data  being  redirected  to   the   directory
                  home_directories below the writable partition mountpoint:

                  /home  home_directories  persistent  transition  none

              •   Make  /var/lib/logrotate  writable  and  persistent  by  storing  all  writes  in the writable
                  partition in an automatically-chosen directory name:

                  /var/lib/logrotate  auto  persistent  none  none

              •   Use non-persistent storage for /tmp:

                  /tmp  none  temporary  none  defaults


FILES
       /etc/system-image/writable-paths


       Copyright © 2014 Canonical Ltd.


LICENSE
       GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
       This is free software: you are free to change and redistribute it.  There is NO WARRANTY, to  the  extent
       permitted by law.


SEE ALSO
       fstab(5), initramfs-tools(8), mount(8), system-image-cli(1), tmpfs(5).