From 710eb2e4cbed2c1662b9f8c83704a69f2a6899d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Lesimple?= Date: Fri, 30 Jul 2021 11:55:03 +0000 Subject: [PATCH] doc: use autosectionlabel --- .../configuration/bastion_conf.rst | 171 +++++++++--------- .../configuration/osh-http-proxy_conf.rst | 59 ++---- doc/sphinx/conf.py | 5 + etc/bastion/bastion.conf.dist | 2 +- 4 files changed, 107 insertions(+), 130 deletions(-) diff --git a/doc/sphinx/administration/configuration/bastion_conf.rst b/doc/sphinx/administration/configuration/bastion_conf.rst index 8a44aae..2f98d90 100644 --- a/doc/sphinx/administration/configuration/bastion_conf.rst +++ b/doc/sphinx/administration/configuration/bastion_conf.rst @@ -12,127 +12,126 @@ bastion.conf reference Option List =========== - -Main Options ------------- +Main Options 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` -- :ref:`bastionCommand` -- :ref:`readOnlySlaveMode` -- :ref:`adminAccounts` -- :ref:`superOwnerAccounts` +- `bastionName`_ +- `bastionCommand`_ +- `readOnlySlaveMode`_ +- `adminAccounts`_ +- `superOwnerAccounts`_ -SSH Policies ------------- +SSH Policies options +-------------------- All the options related to the SSH configuration and policies, both for ingress and egress connections. -- :ref:`allowedIngressSshAlgorithms` -- :ref:`allowedEgressSshAlgorithms` -- :ref:`minimumIngressRsaKeySize` -- :ref:`maximumIngressRsaKeySize` -- :ref:`minimumEgressRsaKeySize` -- :ref:`maximumEgressRsaKeySize` -- :ref:`defaultAccountEgressKeyAlgorithm` -- :ref:`defaultAccountEgressKeySize` -- :ref:`moshAllowed` -- :ref:`moshTimeoutNetwork` -- :ref:`moshTimeoutSignal` -- :ref:`moshCommandLine` +- `allowedIngressSshAlgorithms`_ +- `allowedEgressSshAlgorithms`_ +- `minimumIngressRsaKeySize`_ +- `maximumIngressRsaKeySize`_ +- `minimumEgressRsaKeySize`_ +- `maximumEgressRsaKeySize`_ +- `defaultAccountEgressKeyAlgorithm`_ +- `defaultAccountEgressKeySize`_ +- `moshAllowed`_ +- `moshTimeoutNetwork`_ +- `moshTimeoutSignal`_ +- `moshCommandLine`_ -Global network policies ------------------------ +Global network policies options +------------------------------- Those options can set a few global network policies to be applied bastion-wide. -- :ref:`allowedNetworks` -- :ref:`forbiddenNetworks` -- :ref:`ingressToEgressRules` +- `allowedNetworks`_ +- `forbiddenNetworks`_ +- `ingressToEgressRules`_ -Logging -------- +Logging options +--------------- Options to customize how logs should be produced. -- :ref:`enableSyslog` -- :ref:`syslogFacility` -- :ref:`syslogDescription` -- :ref:`enableGlobalAccessLog` -- :ref:`enableAccountAccessLog` -- :ref:`enableGlobalSqlLog` -- :ref:`enableAccountSqlLog` -- :ref:`ttyrecFilenameFormat` -- :ref:`ttyrecAdditionalParameters` +- `enableSyslog`_ +- `syslogFacility`_ +- `syslogDescription`_ +- `enableGlobalAccessLog`_ +- `enableAccountAccessLog`_ +- `enableGlobalSqlLog`_ +- `enableAccountSqlLog`_ +- `ttyrecFilenameFormat`_ +- `ttyrecAdditionalParameters`_ -Other ingress policies ----------------------- +Other ingress policies options +------------------------------ Policies applying to the ingress connections -- :ref:`ingressKeysFrom` -- :ref:`ingressKeysFromAllowOverride` +- `ingressKeysFrom`_ +- `ingressKeysFromAllowOverride`_ -Other egress policies ---------------------- +Other egress policies options +----------------------------- Policies applying to the egress connections -- :ref:`defaultLogin` -- :ref:`egressKeysFrom` -- :ref:`keyboardInteractiveAllowed` -- :ref:`passwordAllowed` -- :ref:`telnetAllowed` +- `defaultLogin`_ +- `egressKeysFrom`_ +- `keyboardInteractiveAllowed`_ +- `passwordAllowed`_ +- `telnetAllowed`_ -Session policies ----------------- +Session policies options +------------------------ Options to customize the established sessions behaviour -- :ref:`displayLastLogin` -- :ref:`fanciness` -- :ref:`interactiveModeAllowed` -- :ref:`interactiveModeTimeout` -- :ref:`interactiveModeByDefault` -- :ref:`idleLockTimeout` -- :ref:`idleKillTimeout` -- :ref:`warnBeforeLockSeconds` -- :ref:`warnBeforeKillSeconds` -- :ref:`accountExternalValidationProgram` -- :ref:`accountExternalValidationDenyOnFailure` -- :ref:`alwaysActiveAccounts` +- `displayLastLogin`_ +- `fanciness`_ +- `interactiveModeAllowed`_ +- `interactiveModeTimeout`_ +- `interactiveModeByDefault`_ +- `idleLockTimeout`_ +- `idleKillTimeout`_ +- `warnBeforeLockSeconds`_ +- `warnBeforeKillSeconds`_ +- `accountExternalValidationProgram`_ +- `accountExternalValidationDenyOnFailure`_ +- `alwaysActiveAccounts`_ -Account policies ----------------- +Account policies options +------------------------ Policies applying to the bastion accounts themselves -- :ref:`accountMaxInactiveDays` -- :ref:`accountExpiredMessage` -- :ref:`accountCreateSupplementaryGroups` -- :ref:`accountCreateDefaultPersonalAccesses` -- :ref:`ingressRequirePIV` -- :ref:`accountMFAPolicy` -- :ref:`MFAPasswordMinDays` -- :ref:`MFAPasswordMaxDays` -- :ref:`MFAPasswordWarnDays` -- :ref:`MFAPasswordInactiveDays` -- :ref:`MFAPostCommand` +- `accountMaxInactiveDays`_ +- `accountExpiredMessage`_ +- `accountCreateSupplementaryGroups`_ +- `accountCreateDefaultPersonalAccesses`_ +- `ingressRequirePIV`_ +- `accountMFAPolicy`_ +- `MFAPasswordMinDays`_ +- `MFAPasswordMaxDays`_ +- `MFAPasswordWarnDays`_ +- `MFAPasswordInactiveDays`_ +- `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` -- :ref:`accountUidMax` -- :ref:`ttyrecGroupIdOffset` -- :ref:`documentationURL` -- :ref:`debug` -- :ref:`remoteCommandEscapeByDefault` -- :ref:`sshClientDebugLevel` -- :ref:`sshClientHasOptionE` +- `accountUidMin`_ +- `accountUidMax`_ +- `ttyrecGroupIdOffset`_ +- `documentationURL`_ +- `debug`_ +- `remoteCommandEscapeByDefault`_ +- `sshClientDebugLevel`_ +- `sshClientHasOptionE`_ Option Reference ================ diff --git a/doc/sphinx/administration/configuration/osh-http-proxy_conf.rst b/doc/sphinx/administration/configuration/osh-http-proxy_conf.rst index ffb2718..0ccaf7b 100644 --- a/doc/sphinx/administration/configuration/osh-http-proxy_conf.rst +++ b/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 ------------------------- +HTTP Proxy configuration options +-------------------------------- These options modify the behavior of the HTTP Proxy, an optional module of The Bastion -- :ref:`enabled` -- :ref:`port` -- :ref:`ssl_certificate` -- :ref:`ssl_key` -- :ref:`ciphers` -- :ref:`insecure` -- :ref:`min_servers` -- :ref:`max_servers` -- :ref:`min_spare_servers` -- :ref:`max_spare_servers` -- :ref:`timeout` -- :ref:`log_request_response` -- :ref:`log_request_response_max_size` +- `enabled`_ +- `port`_ +- `ssl_certificate`_ +- `ssl_key`_ +- `ciphers`_ +- `insecure`_ +- `min_servers`_ +- `max_servers`_ +- `min_spare_servers`_ +- `max_spare_servers`_ +- `timeout`_ +- `log_request_response`_ +- `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 ***************************** diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index 62d847c..8b8b26d 100644 --- a/doc/sphinx/conf.py +++ b/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'] diff --git a/etc/bastion/bastion.conf.dist b/etc/bastion/bastion.conf.dist index 85ff978..ead3356 100644 --- a/etc/bastion/bastion.conf.dist +++ b/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