Provided by:
initramfs-tools-ubuntu-core_0.7.12_all 
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).