doc: use autosectionlabel

doc/sphinx/administration/configuration/bastion_conf.rst

@@ -12,127 +12,126 @@ bastion.conf reference
 Option List
 ===========
 
-
+Main Options options
-Main Options
+--------------------
-------------
 
 Those are the options you should customize when first setting up a bastion. All the other options have sane defaults and can be customized later if needed.
 
-- :ref:`bastionName`
+- `bastionName`_
-- :ref:`bastionCommand`
+- `bastionCommand`_
-- :ref:`readOnlySlaveMode`
+- `readOnlySlaveMode`_
-- :ref:`adminAccounts`
+- `adminAccounts`_
-- :ref:`superOwnerAccounts`
+- `superOwnerAccounts`_
 
-SSH Policies
+SSH Policies options
-------------
+--------------------
 
 All the options related to the SSH configuration and policies, both for ingress and egress connections.
 
-- :ref:`allowedIngressSshAlgorithms`
+- `allowedIngressSshAlgorithms`_
-- :ref:`allowedEgressSshAlgorithms`
+- `allowedEgressSshAlgorithms`_
-- :ref:`minimumIngressRsaKeySize`
+- `minimumIngressRsaKeySize`_
-- :ref:`maximumIngressRsaKeySize`
+- `maximumIngressRsaKeySize`_
-- :ref:`minimumEgressRsaKeySize`
+- `minimumEgressRsaKeySize`_
-- :ref:`maximumEgressRsaKeySize`
+- `maximumEgressRsaKeySize`_
-- :ref:`defaultAccountEgressKeyAlgorithm`
+- `defaultAccountEgressKeyAlgorithm`_
-- :ref:`defaultAccountEgressKeySize`
+- `defaultAccountEgressKeySize`_
-- :ref:`moshAllowed`
+- `moshAllowed`_
-- :ref:`moshTimeoutNetwork`
+- `moshTimeoutNetwork`_
-- :ref:`moshTimeoutSignal`
+- `moshTimeoutSignal`_
-- :ref:`moshCommandLine`
+- `moshCommandLine`_
 
-Global network policies
+Global network policies options
------------------------
+-------------------------------
 
 Those options can set a few global network policies to be applied bastion-wide.
 
-- :ref:`allowedNetworks`
+- `allowedNetworks`_
-- :ref:`forbiddenNetworks`
+- `forbiddenNetworks`_
-- :ref:`ingressToEgressRules`
+- `ingressToEgressRules`_
 
-Logging
+Logging options
--------
+---------------
 
 Options to customize how logs should be produced.
 
-- :ref:`enableSyslog`
+- `enableSyslog`_
-- :ref:`syslogFacility`
+- `syslogFacility`_
-- :ref:`syslogDescription`
+- `syslogDescription`_
-- :ref:`enableGlobalAccessLog`
+- `enableGlobalAccessLog`_
-- :ref:`enableAccountAccessLog`
+- `enableAccountAccessLog`_
-- :ref:`enableGlobalSqlLog`
+- `enableGlobalSqlLog`_
-- :ref:`enableAccountSqlLog`
+- `enableAccountSqlLog`_
-- :ref:`ttyrecFilenameFormat`
+- `ttyrecFilenameFormat`_
-- :ref:`ttyrecAdditionalParameters`
+- `ttyrecAdditionalParameters`_
 
-Other ingress policies
+Other ingress policies options
-----------------------
+------------------------------
 
 Policies applying to the ingress connections
 
-- :ref:`ingressKeysFrom`
+- `ingressKeysFrom`_
-- :ref:`ingressKeysFromAllowOverride`
+- `ingressKeysFromAllowOverride`_
 
-Other egress policies
+Other egress policies options
----------------------
+-----------------------------
 
 Policies applying to the egress connections
 
-- :ref:`defaultLogin`
+- `defaultLogin`_
-- :ref:`egressKeysFrom`
+- `egressKeysFrom`_
-- :ref:`keyboardInteractiveAllowed`
+- `keyboardInteractiveAllowed`_
-- :ref:`passwordAllowed`
+- `passwordAllowed`_
-- :ref:`telnetAllowed`
+- `telnetAllowed`_
 
-Session policies
+Session policies options
-----------------
+------------------------
 
 Options to customize the established sessions behaviour
 
-- :ref:`displayLastLogin`
+- `displayLastLogin`_
-- :ref:`fanciness`
+- `fanciness`_
-- :ref:`interactiveModeAllowed`
+- `interactiveModeAllowed`_
-- :ref:`interactiveModeTimeout`
+- `interactiveModeTimeout`_
-- :ref:`interactiveModeByDefault`
+- `interactiveModeByDefault`_
-- :ref:`idleLockTimeout`
+- `idleLockTimeout`_
-- :ref:`idleKillTimeout`
+- `idleKillTimeout`_
-- :ref:`warnBeforeLockSeconds`
+- `warnBeforeLockSeconds`_
-- :ref:`warnBeforeKillSeconds`
+- `warnBeforeKillSeconds`_
-- :ref:`accountExternalValidationProgram`
+- `accountExternalValidationProgram`_
-- :ref:`accountExternalValidationDenyOnFailure`
+- `accountExternalValidationDenyOnFailure`_
-- :ref:`alwaysActiveAccounts`
+- `alwaysActiveAccounts`_
 
-Account policies
+Account policies options
-----------------
+------------------------
 
 Policies applying to the bastion accounts themselves
 
-- :ref:`accountMaxInactiveDays`
+- `accountMaxInactiveDays`_
-- :ref:`accountExpiredMessage`
+- `accountExpiredMessage`_
-- :ref:`accountCreateSupplementaryGroups`
+- `accountCreateSupplementaryGroups`_
-- :ref:`accountCreateDefaultPersonalAccesses`
+- `accountCreateDefaultPersonalAccesses`_
-- :ref:`ingressRequirePIV`
+- `ingressRequirePIV`_
-- :ref:`accountMFAPolicy`
+- `accountMFAPolicy`_
-- :ref:`MFAPasswordMinDays`
+- `MFAPasswordMinDays`_
-- :ref:`MFAPasswordMaxDays`
+- `MFAPasswordMaxDays`_
-- :ref:`MFAPasswordWarnDays`
+- `MFAPasswordWarnDays`_
-- :ref:`MFAPasswordInactiveDays`
+- `MFAPasswordInactiveDays`_
-- :ref:`MFAPostCommand`
+- `MFAPostCommand`_
 
-Other options
+Other options options
--------------
+---------------------
 
 These options are either discouraged (in which case this is explained in the description) or rarely need to be modified.
 
-- :ref:`accountUidMin`
+- `accountUidMin`_
-- :ref:`accountUidMax`
+- `accountUidMax`_
-- :ref:`ttyrecGroupIdOffset`
+- `ttyrecGroupIdOffset`_
-- :ref:`documentationURL`
+- `documentationURL`_
-- :ref:`debug`
+- `debug`_
-- :ref:`remoteCommandEscapeByDefault`
+- `remoteCommandEscapeByDefault`_
-- :ref:`sshClientDebugLevel`
+- `sshClientDebugLevel`_
-- :ref:`sshClientHasOptionE`
+- `sshClientHasOptionE`_
 
 Option Reference
 ================

doc/sphinx/administration/configuration/osh-http-proxy_conf.rst

@@ -5,30 +5,29 @@ 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`
+   of The Bastion, please check the :doc:`/using/http_proxy` section
 
 Option List
 ===========
 
-
+HTTP Proxy configuration options
-HTTP Proxy configuration
+--------------------------------
-------------------------
 
 These options modify the behavior of the HTTP Proxy, an optional module of The Bastion
 
-- :ref:`enabled`
+- `enabled`_
-- :ref:`port`
+- `port`_
-- :ref:`ssl_certificate`
+- `ssl_certificate`_
-- :ref:`ssl_key`
+- `ssl_key`_
-- :ref:`ciphers`
+- `ciphers`_
-- :ref:`insecure`
+- `insecure`_
-- :ref:`min_servers`
+- `min_servers`_
-- :ref:`max_servers`
+- `max_servers`_
-- :ref:`min_spare_servers`
+- `min_spare_servers`_
-- :ref:`max_spare_servers`
+- `max_spare_servers`_
-- :ref:`timeout`
+- `timeout`_
-- :ref:`log_request_response`
+- `log_request_response`_
-- :ref:`log_request_response_max_size`
+- `log_request_response_max_size`_
 
 Option Reference
 ================
@@ -36,8 +35,6 @@ Option Reference
 HTTP Proxy configuration
 ------------------------
 
-.. _enabled:
-
 enabled
 *******
 
@@ -47,8 +44,6 @@ enabled
 
 Whether the HTTP proxy daemon daemon is enabled or not. If it's not enabled, it'll exit when started. Of course, if you want to enable this daemon, you should **also** configure your init system to start it for you. Both sysV-style scripts and systemd unit files are provided. For systemd, using `systemctl enable osh-http-proxy.service` should be enough. For sysV-style inits, it depends on the scripts provided for your distro, but usually `update-rc.d osh-http-proxy defaults` then `update-rc.d osh-http-proxy enable` should do the trick.
 
-.. _port:
-
 port
 ****
 
@@ -58,8 +53,6 @@ port
 
 The port to listen to. You can use ports < 1024, in which case privileges will be dropped after binding, but please ensure your systemd unit file starts the daemon as root in that case.
 
-.. _ssl_certificate:
-
 ssl_certificate
 ***************
 
@@ -69,8 +62,6 @@ ssl_certificate
 
 The file that contains the server SSL certificate in PEM format. For tests, install the ``ssl-cert`` package and point this configuration item to the snakeoil certs (which is the default).
 
-.. _ssl_key:
-
 ssl_key
 *******
 
@@ -80,8 +71,6 @@ ssl_key
 
 The file that contains the server SSL key in PEM format. For tests, install the ``ssl-cert`` package and point this configuration item to the snakeoil certs (which is the default).
 
-.. _ciphers:
-
 ciphers
 *******
 
@@ -94,8 +83,6 @@ ciphers
 The ordered list the TLS server ciphers, in ``openssl`` classic format. Use ``openssl ciphers`` to see what your system supports,
 an empty list leaves the choice to your openssl libraries default values (system-dependent)
 
-.. _insecure:
-
 insecure
 ********
 
@@ -105,8 +92,6 @@ insecure
 
 Whether to ignore SSL certificate verification for the connection between the bastion and the devices
 
-.. _min_servers:
-
 min_servers
 ***********
 
@@ -116,8 +101,6 @@ min_servers
 
 Number of child processes to start at launch
 
-.. _max_servers:
-
 max_servers
 ***********
 
@@ -127,8 +110,6 @@ max_servers
 
 Hard maximum number of child processes that can be active at any given time no matter what
 
-.. _min_spare_servers:
-
 min_spare_servers
 *****************
 
@@ -138,8 +119,6 @@ min_spare_servers
 
 The daemon will ensure that there is at least this number of children idle & ready to accept new connections (as long as max_servers is not reached)
 
-.. _max_spare_servers:
-
 max_spare_servers
 *****************
 
@@ -149,8 +128,6 @@ max_spare_servers
 
 The daemon will kill *idle* children to keep their number below this maximum when traffic is low
 
-.. _timeout:
-
 timeout
 *******
 
@@ -160,8 +137,6 @@ timeout
 
 Timeout delay (in seconds) for the connection between the bastion and the devices
 
-.. _log_request_response:
-
 log_request_response
 ********************
 
@@ -171,8 +146,6 @@ log_request_response
 
 When enabled, the complete response of the device to the request we forwarded will be logged, otherwise we'll only log the response headers
 
-.. _log_request_response_max_size:
-
 log_request_response_max_size
 *****************************
 

doc/sphinx/conf.py

@@ -43,7 +43,12 @@ smartquotes = False
 # ones.
 extensions = [
     'sphinx.ext.githubpages',
+    # see https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#automatically-label-sections
+    'sphinx.ext.autosectionlabel',
 ]
+# Make sure the target is unique
+# Sphinx will create explicit targets for all your sections, the name of target has the form {path/to/page}:{title-of-section}
+autosectionlabel_prefix_document = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

etc/bastion/bastion.conf.dist

@@ -223,7 +223,7 @@
 #          Note that when no user-specified ``from="..."`` appears, the value of ``ingressKeysFrom`` is still used, regardless of this option.
 # DEFAULT: false
 "ingressKeysFromAllowOverride": false,
-
+#
 #########################
 # > Other egress policies
 # >> Policies applying to the egress connections