Merge pull request #4323 from garlick/shutdown_doc

flux-shutdown(1): document new options

Author: mergify[bot]

doc/man1/flux-shutdown.rst

@@ -35,6 +35,11 @@ the shutdown command on stderr, until the broker completes executing its
 ``rc3`` script.  By default, log messages with severity level <= LOG_INFO
 are printed.
 
+A Flux system instance requires offline KVS garbage collection to remove
+deleted KVS content and purged job directories, which accrue over time and
+increase storage overhead and restart time.  It is recommended that the
+*--gc* option be used on a routine basis to optimize Flux.
+
 
 OPTIONS
 =======
@@ -55,6 +60,22 @@ OPTIONS
    Increase output verbosity.  Level 1 shows all log messages.  Higher
    verbosity levels are reserved for future use.
 
+**--dump=PATH**
+   Dump a checkpoint of KVS content to *PATH* using :man1:`flux-dump` after the
+   KVS has been unloaded.  The dump may be restored into a new Flux instance
+   using :man1:`flux-restore`.  Dump creation adds time to the shutdown
+   sequence, proportional to the amount of data in the KVS.  ``--dump=auto``
+   is a special case equivalent to ``--gc``.
+
+**--gc**
+   Prepare for offline KVS garbage collection by dumping a checkpoint of KVS
+   content to ``dump/<date>.tgz`` in *statedir*, if defined, otherwise in
+   the broker's current working directory.  Create a symbolic link named
+   ``dump/RESTORE`` pointing to the dump file.  When this link is discovered
+   on instance startup, the content database is truncated and recreated from
+   the dump, and the link is removed.  :linux:man8:`systemd-tmpfiles`
+   automatically cleans up dump files in ``/var/lib/flux/dump`` after 30 days.
+
 
 RESOURCES
 =========
@@ -65,4 +86,5 @@ Flux: http://flux-framework.org
 SEE ALSO
 ========
 
-:man1:`flux-start`, :man1:`flux-uptime`, :man1:`flux-uri`
+:man1:`flux-start`, :man1:`flux-uptime`, :man1:`flux-uri`, :man1:`flux-dump`,
+:linux:man8:`systemd-tmpfiles`

doc/test/spell.en.pws

@@ -623,3 +623,6 @@ xz
 validator
 statedir
 num
+gc
+tgz
+tmpfiles