doc: add documentation for osh-remove-empty-folders

doc/sphinx-reference-headers/osh-remove-empty-folders.conf.header

@@ -0,0 +1,13 @@
+=======================================
+osh-remove-empty-folders.conf reference
+=======================================
+
+.. note::
+
+   The osh-remove-empty-folders script is called by cron and is responsible
+   for cleaning up the ``ttyrec/`` directory of users homes, which may contain
+   a high amount of empty folders for busy users connecting to a lot of
+   different servers, as we create one folder per destination IP.
+
+Option List
+===========

doc/sphinx/Makefile

@@ -37,6 +37,7 @@ config_doc_ref:
 	@                  perl build-config-doc-ref.pl osh-backup-acl-keys.conf      < ../../etc/bastion/osh-backup-acl-keys.conf.dist       > administration/configuration/osh-backup-acl-keys_conf.rst
 	@                  perl build-config-doc-ref.pl osh-piv-grace-reaper.conf     < ../../etc/bastion/osh-piv-grace-reaper.conf.dist      > administration/configuration/osh-piv-grace-reaper_conf.rst
 	@                  perl build-config-doc-ref.pl osh-sync-watcher.sh           < ../../etc/bastion/osh-sync-watcher.sh.dist            > administration/configuration/osh-sync-watcher_sh.rst
+	@                  perl build-config-doc-ref.pl osh-remove-empty-folders.conf < ../../etc/bastion/osh-remove-empty-folders.conf.dist  > administration/configuration/osh-remove-empty-folders_conf.rst
 
 reflist:
 	@python3 -m sphinx.ext.intersphinx _build/html/objects.inv

doc/sphinx/administration/configuration/index.rst

@@ -3,11 +3,12 @@ Configuration files
 ===================
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    bastion_conf
-   osh-http-proxy_conf
-   osh-encrypt-rsync_conf
    osh-backup-acl-keys_conf
+   osh-encrypt-rsync_conf
+   osh-http-proxy_conf
    osh-piv-grace-reaper_conf
+   osh-remove-empty-folders_conf
    osh-sync-watcher_sh

doc/sphinx/administration/configuration/osh-remove-empty-folders_conf.rst

@@ -0,0 +1,83 @@
+=======================================
+osh-remove-empty-folders.conf reference
+=======================================
+
+.. note::
+
+   The osh-remove-empty-folders script is called by cron and is responsible
+   for cleaning up the ``ttyrec/`` directory of users homes, which may contain
+   a high amount of empty folders for busy users connecting to a lot of
+   different servers, as we create one folder per destination IP.
+
+Option List
+===========
+
+Logging options
+---------------
+
+These options configure the way the script logs its actions
+
+- `LOGFILE`_
+- `LOG_FACILITY`_
+
+Behavior options
+----------------
+
+These options govern the behavior of the script
+
+- `ENABLED`_
+- `MTIME_DAYS`_
+
+Option Reference
+================
+
+Logging
+-------
+
+LOGFILE
+*******
+
+:Type: ``string, path to a file``
+
+:Default: ``""``
+
+File where the logs will be written to (don't forget to configure ``logrotate``!).
+Note that using this configuration option, the script will directly write to the file, without using syslog.
+If empty, won't log directly to any file.
+
+LOG_FACILITY
+************
+
+:Type: ``string``
+
+:Default: ``"local6"``
+
+The syslog facility to use for logging the script output.
+If set to the empty string, we'll not log through syslog at all.
+If this configuration option is missing from your config file altogether,
+the default value will be used (local6), which means that we'll log to syslog.
+
+Behavior
+--------
+
+ENABLED
+*******
+
+:Type: ``0 or 1``
+
+:Default: ``1``
+
+If set to 1, the script is enabled and will attempt to garbage-collect empty directories located
+in ``/home/*/ttyrec``. If set to anything else, the script is considered disabled and will not run.
+
+MTIME_DAYS
+**********
+
+:Type: ``int, >= 0``
+
+:Default: ``1``
+
+The amount of days the empty folder must have been empty before considering a removal. You probably
+don't need to change the default value, unless you want to ensure that a given folder has not been
+used since some time before removing it (this has no impact as folders are re-created as needed).
+

etc/bastion/osh-remove-empty-folders.conf.dist

@@ -34,12 +34,12 @@ LOGFILE=""
 # DEFAULT: "local6"
 LOG_FACILITY="local6"
 #
-# > Script options
+# > Behavior
 # >> These options govern the behavior of the script
 #
 # ENABLED (0 or 1)
 #    DESC: If set to 1, the script is enabled and will attempt to garbage-collect empty directories located
-#          in /home/*/ttyrec. If set to anything else, the script is considered disabled and will not run.
+#          in ``/home/*/ttyrec``. If set to anything else, the script is considered disabled and will not run.
 # DEFAULT: 1
 ENABLED=1
 #