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

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