Ubuntu Manpage: writable-paths - make select paths writable

Provided by: initramfs-tools-ubuntu-core_0.7.50_amd64

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.