From 92d4a46ac5601f4a1a63f539687c79b6d2dea0de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Lesimple?=
 <stephane.lesimple+bastion@ovhcloud.com>
Date: Fri, 30 Jul 2021 11:53:33 +0000
Subject: [PATCH] doc: add osh-piv-grace-reaper.pl config reference

---
 bin/cron/osh-piv-grace-reaper.pl              |  6 +++-
 .../osh-piv-grace-reaper_conf.rst             | 35 +++++++++++++++++++
 etc/bastion/osh-piv-grace-reaper.conf.dist    | 13 ++++++-
 3 files changed, 52 insertions(+), 2 deletions(-)
 create mode 100644 doc/sphinx/administration/configuration/osh-piv-grace-reaper_conf.rst

diff --git a/bin/cron/osh-piv-grace-reaper.pl b/bin/cron/osh-piv-grace-reaper.pl
index c81a190..9281871 100755
--- a/bin/cron/osh-piv-grace-reaper.pl
+++ b/bin/cron/osh-piv-grace-reaper.pl
@@ -27,8 +27,12 @@ else {
     }
 }
 
+# set default values
+$config = {} if ref $config ne 'HASH';
+$config->{'SyslogFacility'} //= 'local6';
+
 # logging
-if ($config && $config->{'SyslogFacility'}) {
+if ($config->{'SyslogFacility'}) {
     OVH::SimpleLog::setSyslog($config->{'SyslogFacility'});
 }
 
diff --git a/doc/sphinx/administration/configuration/osh-piv-grace-reaper_conf.rst b/doc/sphinx/administration/configuration/osh-piv-grace-reaper_conf.rst
new file mode 100644
index 0000000..41baaf5
--- /dev/null
+++ b/doc/sphinx/administration/configuration/osh-piv-grace-reaper_conf.rst
@@ -0,0 +1,35 @@
+===================================
+osh-piv-grace-reaper.conf reference
+===================================
+
+.. note::
+
+   The osh-piv-grace-reaper script is called by cron and is responsible for removing
+   temporary grace periods on PIV policies, once they expire. If you don't use PIV keys,
+   this script won't do anything (see :doc:`/using/piv`).
+
+Option List
+===========
+
+Logging options
+---------------
+
+These options configure the way the script logs its actions
+
+- `SyslogFacility`_
+
+Option Reference
+================
+
+Logging
+-------
+
+SyslogFacility
+**************
+
+: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.
+
diff --git a/etc/bastion/osh-piv-grace-reaper.conf.dist b/etc/bastion/osh-piv-grace-reaper.conf.dist
index 890613d..c5f669e 100644
--- a/etc/bastion/osh-piv-grace-reaper.conf.dist
+++ b/etc/bastion/osh-piv-grace-reaper.conf.dist
@@ -1,3 +1,14 @@
+###################################################################
+## Config for /opt/bastion/bin/cron/osh-piv-grace-reaper.pl, the script
+## responsible for expiring the grace period of relaxed PIV policies.
+## This is a JSON file.
+###################################################################
 {
-    "SyslogFacility": "local6"
+# > Logging
+# >> These options configure the way the script logs its actions
+#
+# SyslogFacility (string)
+#    DESC: 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.
+# DEFAULT: local6
+"SyslogFacility": "local6"
 }