From 9d371f90a9c302115aa1c1bab08774c66ad6de1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Lesimple?= Date: Tue, 18 Jan 2022 16:43:06 +0000 Subject: [PATCH] doc: add documentation for osh-remove-empty-folders --- .../osh-remove-empty-folders.conf.header | 13 +++ doc/sphinx/Makefile | 13 +-- .../administration/configuration/index.rst | 7 +- .../osh-remove-empty-folders_conf.rst | 83 +++++++++++++++++++ .../osh-remove-empty-folders.conf.dist | 8 +- 5 files changed, 111 insertions(+), 13 deletions(-) create mode 100644 doc/sphinx-reference-headers/osh-remove-empty-folders.conf.header create mode 100644 doc/sphinx/administration/configuration/osh-remove-empty-folders_conf.rst diff --git a/doc/sphinx-reference-headers/osh-remove-empty-folders.conf.header b/doc/sphinx-reference-headers/osh-remove-empty-folders.conf.header new file mode 100644 index 0000000..76eb000 --- /dev/null +++ b/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 +=========== diff --git a/doc/sphinx/Makefile b/doc/sphinx/Makefile index 4a14e99..e03ba77 100644 --- a/doc/sphinx/Makefile +++ b/doc/sphinx/Makefile @@ -31,12 +31,13 @@ plugins: @bash build-plugins-help.sh config_doc_ref: - @env GLOBAL_REFS=1 perl build-config-doc-ref.pl bastion.conf < ../../etc/bastion/bastion.conf.dist > administration/configuration/bastion_conf.rst - @ perl build-config-doc-ref.pl osh-http-proxy.conf < ../../etc/bastion/osh-http-proxy.conf.dist > administration/configuration/osh-http-proxy_conf.rst - @ perl build-config-doc-ref.pl osh-encrypt-rsync.conf < ../../etc/bastion/osh-encrypt-rsync.conf.dist > administration/configuration/osh-encrypt-rsync_conf.rst - @ 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 + @env GLOBAL_REFS=1 perl build-config-doc-ref.pl bastion.conf < ../../etc/bastion/bastion.conf.dist > administration/configuration/bastion_conf.rst + @ perl build-config-doc-ref.pl osh-http-proxy.conf < ../../etc/bastion/osh-http-proxy.conf.dist > administration/configuration/osh-http-proxy_conf.rst + @ perl build-config-doc-ref.pl osh-encrypt-rsync.conf < ../../etc/bastion/osh-encrypt-rsync.conf.dist > administration/configuration/osh-encrypt-rsync_conf.rst + @ 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 diff --git a/doc/sphinx/administration/configuration/index.rst b/doc/sphinx/administration/configuration/index.rst index 56a0f64..453012e 100644 --- a/doc/sphinx/administration/configuration/index.rst +++ b/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 diff --git a/doc/sphinx/administration/configuration/osh-remove-empty-folders_conf.rst b/doc/sphinx/administration/configuration/osh-remove-empty-folders_conf.rst new file mode 100644 index 0000000..9cbd8b1 --- /dev/null +++ b/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). + diff --git a/etc/bastion/osh-remove-empty-folders.conf.dist b/etc/bastion/osh-remove-empty-folders.conf.dist index 7889b45..3b9a4b5 100644 --- a/etc/bastion/osh-remove-empty-folders.conf.dist +++ b/etc/bastion/osh-remove-empty-folders.conf.dist @@ -34,18 +34,18 @@ 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 # # MTIME_DAYS (int, >= 0) # DESC: 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). +# 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). # DEFAULT: 1 MTIME_DAYS=1