applications/luci-app-statistics/README.md

   1 # Backups
   2
   3 The backup scheme implemented in `/etc/init.d/luci_statistics` aims to
   4 limit writes to stable storage, to preserve flash memory lifetime.
   5 (Flash-memory based routers may have limited lifetime of write cycles,
   6 we want to conserve those.)  While it would be simpler to run a periodic
   7 backup as a cron job, you'd risk wearing out the flash memory.  This
   8 scheme only writes backups to flash during shutdowns/reboots and
   9 upgrades.
  10
  11 The backup is only enabled if the administrator sets
  12 `luci_statistics.collectd_rrdtool.backup=1`.
  13
  14 We only want to restore a sysupgrade backup file if:
  15
  16 1. It was installed by `sysupgrade -r` (restore configuration files), and
  17    we have rebooted.  In this case, there is an orderly shutdown that calls
  18    the shutdown methods.  We do not want to overwrite the
  19    restored sysupgrade backup file during shutdown, but after reboot we
  20    do want to restore it.
  21
  22 1. It was generated during a true sysupgrade, and we are rebooting into
  23    the new image: `sysupgrade` with any or none of `-o`, `-c`, `-f`,
  24    `-u`, resulting in a new image being installed and a config file
  25    being preserved for processing after reboot.  In this case we do not
  26    want to overwrite the backup while rebooting during the upgrade.
  27    `sysupgrade` in this case stores a `.tgz` archive of all preserved
  28    files where it can be found after rebooting into the new image, and
  29    it does not run the shutdown scripts before rebooting.
  30
  31 When the administrator runs `sysupgrade -b` (command line or LuCI), we
  32 create a sysupgrade backup file and it is included in the combined
  33 backup.  Then the system continues running.  When we later stop or
  34 restart or reboot (orderly conditions, when
  35 `/etc/init.d/luci_statistics` is called to shut down), we do not want to
  36 use the saved sysupgrade backup.  If we had a control path after
  37 `sysupgrade -b` that would allow us to remove the sysupgrade backup, this
  38 would be simple.  But we don't!
  39
  40 What we *can* do is arrange that a sysupgrade backup contains enough
  41 information to indicate if it should be restored.
  42
  43 1. True sysupgrade is straightforward: we arrange that the backed-up
  44    file list only includes the sysupgrade backup file and one twin file
  45    (see below).  The next starting of `/etc/init.d/luci_statistics`
  46    after a sysupgrade will restore the sysupgrade backup.
  47
  48 1. Continued system operation after `sysupgrade -b`: next time we stop the
  49    service (during reboot or during other init script actions), we check
  50    for a stale sysupgrade backup, and if we detect it we remove it.
  51
  52 1. `sysupgrade -r` only unpacks the backup files, it does not erase
  53    other non-backed-up files still in the overlay.  Its intended use is
  54    to then immediately reboot, which will run an orderly shutdown/normal
  55    backup.  We must ensure the orderly shutdown in this case preserves
  56    the sysupgrade backup, unlike the previous case.
  57
  58 To implement these cases, we use a pair of twinned files, only one of
  59 which is included in the list of files preserved by sysupgrade.  If we
  60 detect mismatched files (or only one file present) during service
  61 shutdown or startup, we trust that the sysupgrade backup should be kept
  62 and restored.  If the files are matched, that indicates that we have not
  63 restored files since the sysupgrade backup, and the current normal
  64 backup should be used instead.
  65
  66 ## During sysupgrade backup
  67
  68 `/etc/init.d/luci_statistics sysupgrade_backup` is invoked by sysupgrade
  69 for true upgrade or for the `-l` or `-b` flags.  We detect the list flag
  70 (`-l`) by checking the process environment, and if found, we only
  71 generate a list: we don't actually do a backup.  For all cases, we edit
  72 the list of files listed already and remove any other mentions of
  73 `/etc/luci_statistics` to ensure that only the backup file and one of
  74 the twin files is in the backup list.
  75
  76 ## During sysupgrade
  77
  78 During a true sysupgrade, only the sysupgrade backup file and one of the
  79 twin files is restored after the image reboots, so the first running of
  80 startup scripting will restore the sysupgrade backup.  This could be at
  81 the time of first boot, if the image has been built to include this
  82 package, or it could be later when the package is downloaded, installed,
  83 and the service is started.
  84
  85 ## During backup (including orderly shutdown)
  86
  87 During backup (run during shutdown), if there is a matched set of twins,
  88 then we know that sometime since the last service start the
  89 administrator ran `sysupgrade -b` and had the chance to copy the
  90 resulting backup.  We can now erase the twins and the sysupgrade backup.
  91
  92 If there is a mismatched set of twins, then someone restored a backup
  93 such as with `sysupgrade -r` and we should now be rebooting, so we
  94 should leave the sysupgrade files alone to be processed on service
  95 restart (after reboot).
  96
  97 If someone takes a `sysupgrade -b` backup and then restores it before
  98 they reboot or restart statistics, the twins will still match, and we
  99 then don't keep the statistics from the restored backup, we instead take
 100 a new backup from current data and use that on reboot.
 101
 102 ## During startup
 103
 104 If there are matched twin files (the normal case for shutdown/reboot
 105 without sysupgrade), then the sysupgrade backup is ignored and the
 106 regular backup is restored.  If there are mismatched twin files, then
 107 the sysupgrade backup is restored.
 108
 109 ## During disorderly reboot
 110
 111 In a system crash or other disorderly reboot, the shutdown scripts do
 112 not run.  What remains on the system is the previous contents of
 113 `/etc/luci_statistics`.
 114
 115 * If the system never started luci_statistics, or it was cleanly shut
 116   down before the crash, then there is no difference in behavior from
 117   normal startup: we restore either the sysupgrade backup (if
 118   luci_statistics had never run) or the regular backup (if
 119   luci_statistics was cleanly stopped)
 120
 121 * If luci_statistics and collectd were running at the time of the crash,
 122   there could be a regular backup and a sysupgrade backup present, plus
 123   volatile data in /tmp (which are lost in the crash).  The regular
 124   backup would be from the most recent time the system cleanly stopped
 125   luci_statistics.  During the subsequent reboot/service start up:
 126
 127   * If there is a sysupgrade backup on disk from having run `sysupgrade
 128     -b`, with both twin files matching (meaning the administrator had
 129     taken a backup sometime during the life of the system, before the
 130     crash), they are ignored and a regular backup (if any) is restored.
 131
 132   * If the sysupgrade backup has mismatched twin files or only one twin,
 133         then it is used to restore state.  This would be the case if a
 134         sysupgrade restored configuration (`sysupgrade -r`), whether or not
 135         it did an orderly shutdown/reboot, or if the file system were
 136         damaged in a crash and only one of the twin files survived.