doc: generate scripts doc reference

doc/sphinx-reference-headers/bastion.conf.header

@@ -0,0 +1,13 @@
+======================
+bastion.conf reference
+======================
+
+.. note::
+
+   The Bastion has a lot of configuration options so that you can tailor it to your needs.
+   However, if you're just starting and would like to get started quickly, just configure
+   the ``Main Options``. All the other options have sane defaults that can still be customized
+   at a later time.
+
+Option List
+===========

doc/sphinx-reference-headers/osh-backup-acl-keys.conf.header

@@ -0,0 +1,17 @@
+==================================
+osh-backup-acl-keys.conf reference
+==================================
+
+.. note::
+
+   The osh-backup-acl-keys script is called by cron and is responsible for backing up
+   the bastion configuration, users & groups lists, credentials, and everything needed
+   to be able to restore a functioning bastion from scratch.
+
+.. warning::
+
+   If left unconfigured, this script won't do anything, and you won't have backups,
+   unless this task is handled by some other external system.
+
+Option List
+===========

doc/sphinx-reference-headers/osh-encrypt-rsync.conf.header

@@ -0,0 +1,17 @@
+================================
+osh-encrypt-rsync.conf reference
+================================
+
+.. note::
+
+   The osh-encrypt-rsync script is called by cron and is responsible for encrypting
+   and optionally pushing the recorded ``ttyrec`` files to a distant server.
+
+.. warning::
+
+   If left unconfigured, this script won't do anything, and recorded ``ttyrec`` files
+   won't be encrypted or moved out from the server. This might not be a problem for
+   low-traffic bastions or if you have plenty of storage available, though.
+
+Option List
+===========

doc/sphinx-reference-headers/osh-http-proxy.conf.header

@@ -0,0 +1,11 @@
+=============================
+osh-http-proxy.conf reference
+=============================
+
+.. note::
+
+   This module is optional, and disabled by default. To know more about the HTTP Proxy feature
+   of The Bastion, please check the :doc:`/using/http_proxy` section
+
+Option List
+===========

doc/sphinx-reference-headers/osh-piv-grace-reaper.conf.header

@@ -0,0 +1,12 @@
+===================================
+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
+===========

doc/sphinx-reference-headers/osh-sync-watcher.sh.header

@@ -0,0 +1,12 @@
+=============================
+osh-sync-watcher.sh reference
+=============================
+
+.. note::
+
+   The osh-sync-watcher daemon is responsible for ensuring secondary bastions are synced
+   up to their primary. If you don't have such HA setup, you can ignore this config file.
+   For more information, see :ref:`installation/advanced:clustering (high availability)`.
+
+Option List
+===========

doc/sphinx/Makefile

@@ -12,7 +12,7 @@ VERSION      := $(shell perl -e 'require "../../lib/perl/OVH/Bastion.pm"; print
 
 all: autogenerated default
 
-autogenerated: plugins bastion_conf
+autogenerated: plugins config_doc_ref
 
 default: Makefile
 	@for i in $(VERSION_FILES); do cp $$i $$i.bak; done
@@ -30,11 +30,18 @@ help:
 plugins:
 	@bash build-plugins-help.sh
 
-bastion_conf:
-	@env BASTION_CONF=1        perl build-bastion-conf-help.pl < ../../etc/bastion/bastion.conf.dist        > administration/configuration/bastion_conf.rst
-	@env OSH_HTTP_PROXY_CONF=1 perl build-bastion-conf-help.pl < ../../etc/bastion/osh-http-proxy.conf.dist > administration/configuration/osh-http-proxy_conf.rst
+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
 
-.PHONY: help Makefile plugins all autogenerated default bastion_conf
+reflist:
+	@python3 -m sphinx.ext.intersphinx _build/html/objects.inv
+
+.PHONY: help Makefile plugins all autogenerated default config_doc_ref reflist
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

doc/sphinx/administration/configuration/index.rst

@@ -7,3 +7,7 @@ Configuration files
 
    bastion_conf
    osh-http-proxy_conf
+   osh-encrypt-rsync_conf
+   osh-backup-acl-keys_conf
+   osh-piv-grace-reaper_conf
+   osh-sync-watcher_sh

doc/sphinx/administration/index.rst

@@ -4,10 +4,6 @@ Administration
 
 Here we make the assumption that you've already installed The Bastion, and would like to know more about administration topics.
 
-.. warning::
-   The options reference of the satellite configuration files (other than bastion.conf)
-   are not yet documented here, but directly in the configuration files themselves.
-
 .. toctree::
    :maxdepth: 2
 

doc/sphinx/build-config-doc-ref.pl

@@ -3,6 +3,8 @@
 use strict;
 use warnings;
 
+use FindBin;
+
 my %h;
 my @out;
 my $section;
@@ -10,6 +12,8 @@ my %sections;
 my %sectiondesc;
 my @orderedsections;
 
+my $document = $ARGV[0] || 'unknown';
+
 sub dumpdoc {
     if (!%h) {
         ;    # nothing to do
@@ -17,9 +21,12 @@ sub dumpdoc {
     elsif (defined $h{param} && defined $h{default} && defined $h{desc} && defined $h{type}) {
         die "attempting to dump data but section=$section" if !$section;
         push @{$sections{$section}}, $h{param};
-        push @out, ".. _$h{param}:\n\n", "$h{param}\n", "*" x length($h{param}), "\n\n", ":Type: ``$h{type}``\n\n", ":Default: ``$h{default}``\n\n";
-        push @out, ":Example: ``$h{example}``\n\n" if $h{example};
-        push @out, "$h{desc}\n\n";
+        push @out, ".. _$h{param}:\n", "\n"
+          if $ENV{'GLOBAL_REFS'};
+        push @out, "$h{param}\n", "*" x length($h{param}) . "\n", "\n", ":Type: ``$h{type}``\n", "\n", ":Default: ``$h{default}``\n", "\n";
+        push @out, ":Example: ``$h{example}``\n", "\n"
+          if $h{example};
+        push @out, "$h{desc}\n", "\n";
     }
     else {
         die "something is missing: " . ($h{param} ? "" : "param ") . ($h{default} ? "" : "default ") . ($h{desc} ? "" : "desc ") . ($h{type} ? "" : "type") . "\n";
@@ -30,31 +37,43 @@ sub dumpdoc {
 
 my $state = '';
 while (<STDIN>) {
+    $ENV{'DEBUG'} && print;
     next if /^\s*$/;
     if (m{^# ([a-zA-Z0-9_]+) \((.+)\)}) {
         $h{param} = $1;
         $h{type}  = $2;
-        $state    = 'name';
+        $ENV{'DEBUG'} && print "--- state=name\n";
+        $state = 'name';
     }
     elsif (m{^#\s+DESC:\s+(.+)$}) {
         $h{desc} = $1;
+        $ENV{'DEBUG'} && print "--- state=desc\n";
         $state = 'desc';
     }
     elsif (m{^#\s+EXAMPLE:\s+(.+)$}) {
         $h{example} = $1;
+        $ENV{'DEBUG'} && print "--- state=example\n";
         $state = 'example';
     }
     elsif (m{^#\s+DEFAULT:\s+(.+)$}) {
         $h{default} = $1;
+        $ENV{'DEBUG'} && print "--- state=default\n";
         $state = 'default';
     }
     elsif (m{^#\s{0,11}(.*)$} && exists $h{desc} && $state eq 'desc') {
         $h{desc} .= "\n$1";
     }
-    elsif (m{^"([^"]+)"} && $h{param} eq $1) {
+    elsif ((m{^"([^"]+)"} && $h{param} eq $1) || (m{^([A-Za-z0-9_]+)=} && $h{param} eq $1)) {
+        $ENV{'DEBUG'} && print "--- state=param\n";
+        $state = 'param';
+    }
+    elsif (m{^#$} && $state eq 'param') {
+        $ENV{'DEBUG'} && print "--- state=(empty)\n";
         $state = '';
         dumpdoc();
     }
+    elsif ($state eq 'param') {
+    }
     elsif (m{^# > (.+)$}) {
         if (%h or $state) { die "new section '$1' but we have pending data"; }
         $section = $1;
@@ -66,50 +85,25 @@ while (<STDIN>) {
         $sectiondesc{$section} = $1;
     }
     elsif (!/^##|^[{}]|^#\s*$/) {
-        die("\\--- lost here, state='$state'");
+        die("$_^^^ lost here, state='$state'");
     }
 }
 dumpdoc();
 
-if ($ENV{BASTION_CONF}) {
-    print <<'EOF';
-======================
-bastion.conf reference
-======================
-
-.. note::
-
-   The Bastion has a lot of configuration options so that you can tailor it to your needs.
-   However, if you're just starting and would like to get started quickly, just configure
-   the ``Main Options``. All the other options have sane defaults that can still be customized
-   at a later time.
-
-Option List
-===========
-
-EOF
+if (open(my $fh, "<", "$FindBin::Bin/../sphinx-reference-headers/$document.header")) {
+    local $/;
+    my $contents = <$fh>;
+    close($fh);
+    print $contents;
 }
-elsif ($ENV{OSH_HTTP_PROXY_CONF}) {
-    print <<'EOF';
-=============================
-osh-http-proxy.conf reference
-=============================
-
-.. note::
-
-   This module is optional, and disabled by default. To know more about the HTTP Proxy feature
-   of The Bastion, please check :doc:`/using/http_proxy`
-
-Option List
-===========
-
-EOF
+else {
+    print STDERR "No header found in '$FindBin::Bin/../sphinx-reference-headers/$document.header'\n";
 }
 
 foreach my $section (@orderedsections) {
     die "no description for section $section" if !$sectiondesc{$section};
-    print "\n", $section, "\n", "-" x length($section), "\n\n", $sectiondesc{$section}, "\n\n";
-    print "- :ref:`$_`\n" for @{$sections{$section}};
+    print "\n", "$section options\n", "-" x length("$section options"), "\n\n", $sectiondesc{$section}, "\n\n";
+    print "- `$_`_\n" for @{$sections{$section}};
 }
 print <<'EOF', join('', @out);