writable-paths(5)

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

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

    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.

    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.

    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.

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