doc: Start writing some in-tree documentation
[petitboot] / doc / func / snapshots.rst
1 .. _snapshots:
2
3 Snapshots
4 =========
5
6 By default Petitboot does not directly mount any block devices. Instead it uses the device-mapper snapshot_ device to mount an in-memory representation of the device. Any writes Petitboot or another part of the system may make to the device are written to memory rather than the physical device, providing a "real" read-only guarantee beyond just that provided by the filesystem.
7
8 In normal operation this is completely transparent but there are two scenarios where actual writes are desired:
9
10 .. _snapshot: https://www.kernel.org/doc/Documentation/device-mapper/snapshot.txt
11
12 Saving bootloader data
13 ----------------------
14
15 Some configuration formats include directives to save some data before boot - like GRUB's ability to record the last option booted. Snapshots will prevent this but Petitboot can be configured to merge these writes back to the source device by enabling the ""Allow bootloader scripts to modify disks" option in the System Configuration screen.
16
17 Manual interaction
18 ------------------
19
20 Any writes to a block device first mounted by Petitboot will by default be thrown away. If a user makes changes to a disk or USB device for example that they want to preserve they can tell Petitboot to merge these writes to the source device with the "sync" event. For example if the user had written something to the sda2 partition, in the shell they can run:
21
22 .. code-block:: none
23
24    pb-event sync@sda2
25
26 Petitboot will handle the merging itself and remount the device read-only.
27
28 If desired snapshots can also be disabled via the "petitboot,snapshots?" parameter. For example:
29
30 .. code-block:: none
31
32    nvram --update-config petitboot,snapshots?=false
33
34 As of the next boot Petitboot will mount block devices directly.