pst

docs/pst.md

@@ -0,0 +1,41 @@
+# Persistent storage
+
+??? note
+    This feature is available on images older than 2022.06.20
+
+Sometimes advanced use of PiKVM requires storing some data on disk like API keys, config files, or something like that.
+For example, you want to have a script that will update SSL certificates once a week.
+However, the root file system is in a read-only state and does not involve remounting automatically by user scripts.
+
+To solve this problem, new versions of PiKVM have a small 256MiB storage partition that can be used to store that data.
+A special `kvmd-pst` daemon makes sure that this partition is mounted in read-only all the time, and remounts it to RW
+only when some user script requires it. This also solves the problems of simultaneous access, so the RW mode will be
+keeped as long as at least one client is working with the storage.
+
+
+## Usage
+
+Below is an example of a script `/root/test.sh` that wants to save a certain file in PST:
+
+```bash
+#!/bin/bash
+echo `date` + $@ > $KVMD_PST_DATA/foo
+cat $KVMD_PST_DATA/foo
+```
+
+To run it use:
+```
+# kvmd-pstrun -- /root/test.sh --some --script --args
+--    INFO -- Opening PST session ...
+--    INFO -- PST write is allowed: /var/lib/kvmd/pst/data
+--    INFO -- Running the process ...
+Mon Jun 20 04:23:14 MSK 2022 + --some --script --args
+--    INFO -- Process finished: returncode=0
+```
+
+So, what's going on here:
+1. `kvmd-pstrun` connects to the `kvmd-pst` daemon, which manages the mounting of the storage.
+2. If everything is fine, the daemon will remount the storage to RW mode and report the data root to `kvmd-pstrun`.
+3. `kvmd-pstrun` runs the script and pass the data root path using the environment variable `KVMD_PST_DATA` (`/var/lib/kvmd/pst/data`).
+4. If the `kvmd-pst` daemon stops or any other daemon error occurs, the script will be killed.
+5. After the script is finished, the daemon will remount the storage to RO mode.

mkdocs.yml

@@ -87,6 +87,7 @@ nav:
         - "Multiport KVM-over-IP": multiport.md
         - "Wake-on-LAN the server": wol.md
         - "IPMI & Redfish integration": ipmi.md
+        - "Persistent storage": pst.md
         - "Prometheus monitoring": prometheus.md
     - "Development":
         - "Cases for 3D printing": 3d_printing.md