]> git.ipfire.org Git - thirdparty/freeradius-server.git/commitdiff
Update raddb/mods-available/eap
authorJorge Pereira <jpereira@freeradius.org>
Mon, 4 Feb 2019 23:29:44 +0000 (21:29 -0200)
committerJorge Pereira <jpereira@freeradius.org>
Mon, 4 Feb 2019 23:29:44 +0000 (21:29 -0200)
raddb/mods-available/eap

index e95607a33345c2fa80be19bc85cd7fd103079b6a..33136e7362088c1f9e7938d8de04ae9861cc2f3b 100644 (file)
@@ -1,58 +1,73 @@
 # -*- text -*-
-##
-##  eap.conf -- Configuration for EAP types (PEAP, TTLS, etc.)
-##
-##     $Id$
+#
+# :toc:
+#
+#  $Id$
 
 #######################################################################
 #
+#  = EAP Module
+#
+#  The `eap` module takes care of all EAP authentication as described in RFC 3579.
+#
+#  [WARNING]
+#  ====
 #  Whatever you do, do NOT set 'Auth-Type := EAP'.  The server is smart enough
 #  to figure this out on its own.
 #
 #  The most common side effect of setting 'Auth-Type := EAP' is that the users
 #  then cannot use ANY other authentication method.
+#  ====
+#
+
+#
+#  # Default instance
 #
 eap {
        #
-       #  Invoke the default supported EAP type when EAP-Identity response is
-       #  received.
+       #  default_eap_type::: Invoke the default supported EAP type when `EAP-Identity`
+       #  response is received.
        #
-       #  The incoming EAP messages DO NOT specify which EAP type they will be
-       #  using, so it MUST be set here.
+       #  The incoming EAP messages *DO NOT* specify which EAP type they will be using,
+       #  so it MUST be set here.
        #
        #  For now, only one default EAP type may be used at a time.
        #
-       #  If the EAP-Type attribute is set by another module, then that EAP
+       #  If the `EAP-Type` attribute is set by another module, then that EAP
        #  type takes precedence over the default type configured here.
        #
        default_eap_type = md5
 
+       #
+       #  ignore_unknown_eap_types::
        #
        #  There are many EAP types, but the server has support for only a
        #  limited subset.  If the server receives a request for an EAP type it
        #  does not support, then it normally rejects the request.  By setting
-       #  this configuration to "yes", you can tell the server to instead keep
+       #  this configuration to `yes`, you can tell the server to instead keep
        #  processing the request.  Another module MUST then be configured to
        #  proxy the request to another RADIUS server which supports that EAP
        #  type.
        #
-       #  If another module is NOT configured to handle the request, then the
+       #  NOTE: If another module is NOT configured to handle the request, then the
        #  request will still end up being rejected.
        #
        ignore_unknown_eap_types = no
 
        #
-       #  Cisco AP1230B firmware 12.2(13)JA1 has a bug.  When given a User-Name
-       #  attribute in an Access-Accept, it copies one more byte than it should.
+       #  cisco_accounting_username_bug::
+       #
+       #  Cisco AP1230B firmware 12.2(13)JA1 has a bug.  When given a `User-Name`
+       #  attribute in an `Access-Accept`, it copies one more byte than it should.
        #
        #  We can work around it by configurably adding an extra zero byte.
        #
        cisco_accounting_username_bug = no
 
        #
-       #  Allowed EAP-types
+       #  ## Allowed EAP-types
        #
-       #  Only EAP types listed below with a 'type = <EAP-Type>' pair will be allowed.
+       #  type:: Only EAP types listed below with a `type = <EAP-Type>` pair will be allowed.
        #
        type = md5
 #      type = pwd
@@ -67,19 +82,22 @@ eap {
        type = sim
 
        #
-       #  EAP-MD5 authentication cannot be used for wireless
-       #  connections.  It is insecure, and does not provide for
-       #  dynamic WEP keys or WPA enterprise.
+       #  ### EAP-MD5
+       #
+       #  WARNING: EAP-MD5 authentication cannot be used for wireless
+       #  connections.  It is insecure, and does not provide for dynamic WEP
+       #  keys or WPA enterprise.
+
        #
        md5 {
        }
 
-       ## EAP-PWD (Secure password-based authentication)
        #
-       #  In v4, the "known good" password is taken from the
-       #  &request.control:Cleartext-Password list, as is done by
-       #  other modules.  The change from v3 is that the
-       #  "inner-tunnel" virtual server is not used.
+       #  ### EAP-PWD (Secure password-based authentication)
+       #
+       #  In v4, the "known good" password is taken from the `&request.control:Cleartext-Password` list,
+       #  as is done by other modules. The change from v3 is that the `inner-tunnel` virtual server
+       #  is no not used.
        #
 #      pwd {
 #              group = 19
@@ -87,15 +105,19 @@ eap {
 #              server_id = theserver@example.com
 
                #
-               #  This has the same meaning as for TLS.
+               #  fragment_size:: This has the same meaning as for TLS.
                #
 #              fragment_size = 1020
 #      }
 
-       ## Cisco LEAP
        #
-       #  We do not recommend using LEAP in new deployments.  See:
-       #  http://www.securiteam.com/tools/5TP012ACKE.html
+       #  ### Cisco LEAP
+       #
+       #  [WARNING]
+       #  ====
+       #  We do not recommend using LEAP in new deployments.
+       #  See: http://www.securiteam.com/tools/5TP012ACKE.html
+       #  ====
        #
        #  Cisco LEAP uses the MS-CHAP algorithm (but not the MS-CHAP
        #  attributes) to perform it's authentication.
@@ -106,49 +128,55 @@ eap {
 #      leap {
 #      }
 
-       ## Generic Token Card.
        #
-       #  Currently, this is only permitted inside of EAP-TTLS, or EAP-PEAP.
-       #  The module "challenges" the user with text, and the response from the
-       #  user is taken to be the User-Password.
+       #  ### Generic Token Card
+       #
+       #  Currently, this is only permitted inside of `EAP-TTLS`, or `EAP-PEAP`.
+       #  The module `challenges` the user with text, and the response from the
+       #  user is taken to be the `User-Password`.
        #
-       #  Proxying the tunneled EAP-GTC session is a bad idea, the users
+       #  WARNING: Proxying the tunneled `EAP-GTC` session is a bad idea, the users
        #  password will go over the wire in plain-text, for anyone to see.
        #
        gtc {
-               #  The default challenge, which many clients ignore..
+               #
+               #  challenge:: The default challenge, which many clients ignore.
+               #
 #              challenge = "Password: "
 
+               #
+               #  auth_type::
                #
                #  The plain-text response which comes back is put into a
-               #  User-Password attribute, and passed to another module for
-               #  authentication.  This allows the EAP-GTC response to be
+               #  `User-Password` attribute, and passed to another module for
+               #  authentication.  This allows the `EAP-GTC` response to be
                #  checked against plain-text, or crypt'd passwords.
                #
                #  If you say "Local" instead of "PAP", then the module will
-               #  look for a User-Password configured for the request, and do
+               #  look for a `User-Password` configured for the request, and do
                #  the authentication itself.
                #
                auth_type = PAP
        }
 
-       ## Common TLS configuration for TLS-based EAP types
        #
-       #  See raddb/certs/README for additional comments on certificates.
+       #  ## Common TLS configuration for TLS-based EAP types
+       #
+       #  See `raddb/certs/README` for additional comments on certificates.
        #
-       #  If OpenSSL was not found at the time the server was built, the "tls",
-       #  "ttls", and "peap" sections will be ignored.
+       #  If OpenSSL was not found at the time the server was built, the `tls`,
+       #  `ttls`, and `peap` sections will be ignored.
        #
        #  If you do not currently have certificates signed by a trusted CA you
        #  may use the 'snakeoil' certificates. Included with the server in
-       #  raddb/certs.
+       #  `raddb/certs`.
        #
        #  If these certificates have not been auto-generated:
        #
        #    cd raddb/certs
        #    make
        #
-       #  These test certificates SHOULD NOT be used in a normal
+       #  These test certificates *SHOULD NOT* be used in a normal
        #  deployment.  They are created only to make it easier to
        #  install the server, and to perform some simple tests with
        #  EAP-TLS, TTLS, or PEAP.
@@ -160,19 +188,21 @@ eap {
        #  want.
        #
        tls-config tls-common {
+               #
+               #  auto_chain::
                #
                #  OpenSSL will automatically create certificate chains, unless
                #  we tell it to not do that.  The problem is that it sometimes
                #  gets the chains right from a certificate signature view, but
                #  wrong from the clients view.
                #
-               #  When setting "auto_chain = no", the server chain {} section(s)
-               #  below MUST include the full certificate chain.
+               #  NOTE: When setting `auto_chain = no`, the server `chain {}`
+               #  section(s) below MUST include the full certificate chain.
                #
 #              auto_chain = no
 
                #
-               #  A chain of certificates to present to the client.
+               #  .A chain of certificates to present to the client
                #
                #  Multiple chain sections can be specified to allow different
                #  chains for different key types (RSA, DSA, DH, EC).
@@ -193,27 +223,32 @@ eap {
                #
                chain rsa {
                        #
-                       #  The format of the certificate(s) and private key file.
-                       #  May be one of PEM, DER or ASN1 (ASN1 is an alias for DER).
+                       #  format:: The format of the certificate(s) and private key file.
+                       #
+                       #  May be one of `PEM`, `DER` or `ASN1` (ASN1 is an alias for `DER`).
                        #
 #                      format = "PEM"
 
                        #
-                       #  If PEM is being used the "certificate_file" specified below
+                       #  certificate_file::
+                       #
+                       #  If PEM is being used the `certificate_file` specified below
                        #  should contain the server certificates, and any intermediary CAs
                        #  which are not available to the client.
                        #
-                       #  If verify_mode (below) is set to "hard" or "soft" all
+                       #  [NOTE]
+                       #  ====
+                       #  If `verify_mode` (below) is set to `hard` or `soft` all
                        #  intermediary CAs and the Root CA should be included.
                        #
                        #  Any certificate chain MUST be in order from server
                        #  certificate (first in the file) to intermediary CAs (second) to
-                       #  Root CA (last in the file) as per RFC 4346 (see certificate_list)
-                       #  http://tools.ietf.org/html/rfc4346#section-7.4.2 )
+                       #  Root CA (last in the file) as per RFC 4346 Section 7.4.2 (see certificate_list)
                        #
-                       #  If DER is being used the "certificate_file" should contain ONLY
-                       #  the server's certificate, and one or more "ca_file" items should be
+                       #  If DER is being used the `certificate_file` should contain ONLY
+                       #  the server's certificate, and one or more `ca_file` items should be
                        #  used to load intermediary CAs and the Root CA.
+                       #  ====
                        #
                        #  We recommend using `ca_file` to load the
                        #  root CAs, instead of putting them in
@@ -221,70 +256,83 @@ eap {
                        #
                        certificate_file = ${certdir}/rsa/server.pem
 
+                       #
+                       #  ca_file::
                        #
                        #  Load an additional intermediary CA or Root CA for consideration in
                        #  chain compilation.  Multiple "ca_file" config items may be used
                        #  to load multiple certificates.
                        #
-                       #  When multiple `ca_file`s are used, the
-                       #  server will still present only one
-                       #  `certificate_file` to the clients.  The
-                       #  main use of multiple `ca_file` is to permit
-                       #  the use of EAP-TLS with client certificates
-                       #  from multiple Root CAs.
+                       #  When multiple `ca_file`s are used, the server will still present only one
+                       #  `certificate_file` to the clients.  The main use of multiple `ca_file` is
+                       #  to permit the use of EAP-TLS with client certificates from multiple Root CAs.
                        #
                        ca_file = ${certdir}/rsa/ca.pem
 
                        #
-                       #  Password used to encrypt the private key.  If the private key is
-                       #  not encrypted, this configuration item will have no effect.
+                       #  private_key_password:: Password used to encrypt the private key.
+                       #  If the private key is not encrypted, this configuration item
+                       #  will have no effect.
                        #
                        private_key_password = whatever
 
+                       #
+                       #  private_key_file::
                        #
                        #  If the Private key & Certificate are located in the same file,
-                       #  then 'private_key_file' & 'certificate_file' must contain the
+                       #  then `private_key_file` & `certificate_file` must contain the
                        #  same file name.
                        #
                        private_key_file = ${certdir}/rsa/server.key
 
+                       #
+                       #  verify_mode::
                        #
                        #  During startup we attempt to precompile the certificate chain
                        #  from server certificate to Root CA.  This configuration item specifies
                        #  what happens if compilation fails.
                        #
-                       #    hard - Error out if we cannot build a complete certificate chain.
-                       #    soft - Warn if we cannot build a complete certificate chain.
-                       #    none - Stay silent if we cannot build a complete certificate chain.
+                       #  [options="header,autowidth"]
+                       #  |===
+                       #  | Error | Description
+                       #  | hard  | Error out if we cannot build a complete certificate chain.
+                       #  | soft  | Warn if we cannot build a complete certificate chain.
+                       #  | none  | Stay silent if we cannot build a complete certificate chain.
+                       #  |===
                        #
-                       #  The default is "hard".  The only time this should be changed is if
+                       #  The default is `hard`.  The only time this should be changed is if
                        #  you want to limit the number of intermediary CAs sent to the
                        #  client by not including them in the chain.
                        #
-                       #  Note: Depending on the value of "auto_chain" we may still be able to
-                       #  build a complete chain, but this will be done at runtime.
+                       #  [NOTE]
+                       #  ====
+                       #  * Depending on the value of `auto_chain` we may still be able to
+                       #    build a complete chain, but this will be done at runtime.
                        #
-                       #  Note: "auto_chain" has no effect on which certificates are considered
-                       #  for pre-compilation.  Only those listed in this chain {} section will be
-                       #  used.
+                       #  * `auto_chain` has no effect on which certificates are considered
+                       #  for pre-compilation.  Only those listed in this `chain {}` section
+                       #  will be used.
+                       #  ====
                        #
 #                      verify_mode = "hard"
 
+                       #
+                       #  include_root_ca::
                        #
                        #  Omit the Root CA from the compiled certificate chain.
                        #  The Root CA should already be known/trusted by the client so it is
                        #  usually not needed unless the client is particularly poorly behaved.
                        #
-                       #  Note: The Root CA must still be available for chain compilation to
-                       #  succeed even if "include_root_ca = no".
+                       #  NOTE: The Root CA must still be available for chain compilation to
+                       #  succeed even if `include_root_ca = no`.
                        #
-                       #  The default here is "no".
+                       #  Default: `no`.
                        #
                        include_root_ca = no
                }
 
                #
-               #  Load the ECC certificate chain for key agility
+               #  ### ECC certificate chain for key agility
                #
                #  This is disabled by default, see the warning above.
                #  If your supplicants propose a mix of different
@@ -299,6 +347,8 @@ eap {
 #                      private_key_file = ${certdir}/ecc/server.key
 #              }
 
+               #
+               #  ## Server certificate
                #
                #  The server certificate may also be specified at
                #  runtime on a per session basis.  In that use-case,
@@ -321,24 +371,25 @@ eap {
                #  verifying that the supplicant returns the correct
                #  TLS alert (available in Module-Failure-Message).
                #
-               #  Note that after receiving a fatal alert, TLS
-               #  negotiation cannot continue.  However, as most
-               #  supplicants will immediately retry authenticaton,
-               #  this failure will likely not be an issue.
+               #  NOTE: After receiving a fatal alert, TLS negotiation
+               #  cannot continue, but as most supplicants retry
+               #  enthusiastically this probably won't be an issue.
                #
 
                #
-               #  Trusted Root CA list
+               #  ca_file:: Trusted Root CA list
                #
                #  ALL of the CA's in this list will be trusted to issue client
                #  certificates for authentication.
                #
-               #  You should not use a public CA here.  This should either be
+               #  NOTE: You should not use a public CA here.  This should either be
                #  set to a certificate chain for your institution's CA
                #  or a self signed Root CA.
-               #
+               #               #
                ca_file = ${cadir}/rsa/ca.pem
 
+               #
+               #  psk_identity:::
                #
                #  If OpenSSL supports TLS-PSK, then we can use a PSK identity
                #  and (hex) password.
@@ -350,9 +401,14 @@ eap {
 #              psk_identity = "test"
 #              psk_hexphrase = "036363823"
 
-               #  Dynamic queries for the PSK.  If TLS-PSK is used,
-               #  and psk_query is set, then you MUST NOT use
-               #  psk_identity or psk_hexphrase.
+               #
+               #  WARNING: Dynamic queries for the `PSK`.  If `TLS-PSK` is used,
+               #  and `psk_query` is set, then you MUST NOT use
+               #  `psk_identity` or `psk_hexphrase`.
+               #
+
+               #
+               #  psk_query::
                #
                #  Instead, use a dynamic expansion similar to the one
                #  below.  It keys off of TLS-PSK-Identity.  It should
@@ -365,7 +421,6 @@ eap {
                #
 #              psk_query = "%{sql:select hex(key) from psk_keys where keyid = '%{TLS-PSK-Identity}'}"
 
-
                #
                #  For DH cipher suites to work, you have to run OpenSSL to
                #  create the DH file first:
@@ -374,69 +429,83 @@ eap {
                #
                dh_file = ${certdir}/dh
 
+               #
+               #  fragment_size::
                #
                #  This can never exceed the size of a RADIUS packet (4096
                #  bytes), and is preferably half that, to accommodate other
                #  attributes in RADIUS packet.  On most APs the MAX packet
-               #  length is configured between 1500 - 1600 In these cases,
-               #  fragment size should be 1024 or less.
+               #  length is configured between `1500 - 1600` In these cases,
+               #  fragment size should be `1024` or less.
                #
 #              fragment_size = 1024
 
                #
-               #  Check the Certificate Revocation List
+               #  check_crl:: Check the Certificate Revocation List.
                #
                #  Will check CRLs for all certificates in the certificate chain.
                #
-               #  1) Copy CA certificates and CRLs to same directory.
-               #  2) Execute 'c_rehash <CA certs&CRLs Directory>'. 'c_rehash' is
+               #  <1> Copy CA certificates and CRLs to same directory.
+               #  <2> Execute `c_rehash <CA certs&CRLs Directory>`. `c_rehash` is
                #     OpenSSL's command.
-               #  3) uncomment the lines below.
-               #  4) Restart radiusd
+               #  <3> uncomment the lines below.
+               #  <4> Restart radiusd.
                #
 #              check_crl = yes
 
+               #
+               #  ca_path:: Full path to the CA file.
+               #
                ca_path = ${cadir}
 
-               # Accept an expired Certificate Revocation List
+               #
+               #  allow_expired_crl:: Accept an expired Certificate Revocation List.
                #
 #              allow_expired_crl = no
 
                #
-               #  If check_cert_issuer is set, the value will be checked
+               #  check_cert_issuer::
+               #
+               #  If `check_cert_issuer` is set, the value will be checked
                #  against the DN of the issuer in the client certificate.  If
                #  the values do not match, the certificate verification will
                #  fail, rejecting the user.
                #
                #  This check can be done more generally by checking the value
-               #  of the TLS-Client-Cert-Issuer attribute.  This check can be
+               #  of the `TLS-Client-Cert-Issuer` attribute.  This check can be
                #  done via any mechanism you choose.
                #
 #              check_cert_issuer = "/C=GB/ST=Berkshire/L=Newbury/O=My Company Ltd"
 
                #
-               #  If check_cert_cn is set, the value will be xlat'ed and
+               #  check_cert_cn::
+               #
+               #  If `check_cert_cn` is set, the value will be xlat'ed and
                #  checked against the CN in the client certificate.  If the
                #  values do not match, the certificate verification will fail
                #  rejecting the user.
                #
-               #  This check is done only if the previous "check_cert_issuer"
+               #  This check is done only if the previous `check_cert_issuer`
                #  is not set, or if the check succeeds.
                #
                #  This check can be done more generally by checking the value
-               #  of the TLS-Client-Cert-Common-Name attribute.  This check can be done
+               #  of the `TLS-Client-Cert-Common-Name` attribute.  This check can be done
                #  via any mechanism you choose.
                #
 #              check_cert_cn = %{User-Name}
 
+               #
+               #  cipher_list::
                #
                #  Set this option to specify the allowed TLS cipher suites.
-               #  The format is listed in "man 1 ciphers".
+               #  The format is listed in `man 1 ciphers`.
                #
-               # For EAP-FAST, use "ALL:!EXPORT:!eNULL:!SSLv2"
+               #  NOTE: For `EAP-FAST`, use "ALL:!EXPORT:!eNULL:!SSLv2"
                #
                cipher_list = "DEFAULT"
 
+               #
+               #  cipher_server_preference::
                #
                #  If enabled, OpenSSL will use server cipher list
                #  (possibly defined by cipher_list option above)
@@ -448,16 +517,25 @@ eap {
                cipher_server_preference = yes
 
                #
-               #  Work-arounds for OpenSSL nonsense OpenSSL 1.0.1f and 1.0.1g do
-               #  not calculate the EAP keys correctly.  The fix is to upgrade
+               #  tls_max_version::
+               #
+               #  [NOTE]
+               #  ====
+               #  * Work-arounds for OpenSSL nonsense OpenSSL 1.0.1f and 1.0.1g do
+               #  not calculate the `EAP` keys correctly.  The fix is to upgrade
                #  OpenSSL, or disable TLS 1.2 here.
                #
-               #  SSLv2 and SSLv3 are permanently disabled due to security
+               #  SSLv2 and SSLv3 are permanently disabled due to security
                #  issues.
+               #  ====
                #
 #              tls_max_version = 1.1
 
                #
+               #  tls_min_version::
+               #
+               #  [NOTE]
+               #  ====
                #  Prevents versions < tls_min_version from being negotiated.
                #  In general the higher the tls_min_version the more secure
                #  the protocol, but the narrower the range of supported TLS
@@ -465,18 +543,19 @@ eap {
                #
                #  SSLv2 and SSLv3 are permanently disabled due to security
                #  issues.
+               #  ====
                #
 #              tls_min_version = 1.0
 
                #
-               #  Elliptical cryptography configuration
+               #  ecdh_curve:: Elliptical cryptography configuration.
                #
                #  Only for OpenSSL >= 0.9.8.f
                #
                ecdh_curve = "prime256v1"
 
                #
-               #  TLS Session resumption
+               #  ### TLS Session resumption
                #
                #  We currently support RFC 5246 style TLS session resumption
                #  only.
@@ -490,28 +569,30 @@ eap {
                #  session.
                #
                #  Resuming a TLS session avoids the certificate exchange and in
-               #  the case PEAP and TTLS, allows the client to skip the inner
-               #  EAP method.
+               #  the case `PEAP` and `TTLS`, allows the client to skip the inner
+               #  `EAP` method.
                #
-               #  Enabling Session-Resumption is highly recommended for sites
+               #  Enabling `Session-Resumption` is highly recommended for sites
                #  using slow authentication backends such as winbindd/Active
                #  Directory, and for access federations operating over the
                #  internet, such as Eduroam.
                #
-               #  Note: You must ensure any attributes required for policy
+               #  NOTE: You must ensure any attributes required for policy
                #  decisions are cached at the same time as the TLS session
-               #  data. See sites-available/tls-cache for documentation on
+               #  data. See `sites-available/tls-cache` for documentation on
                #  how TLS cache now works.
                #
-               #  If using the default tls-cache virtual server and
+               #  If using the default `tls-cache` virtual server and
                #  cache module config, policy attributes may be stored in the
-               #  &session-state: list.
+               #  `&session-state:` list.
                #
                cache {
+                       #
+                       #  virtual_server::
                        #
                        #  To enable session resumption, uncomment the virtual
                        #  server entry below, and link
-                       #  sites-available/tls-cache to sites-enabled/tls-cache.
+                       #  `sites-available/tls-cache` to `sites-enabled/tls-cache`.
                        #
                        #  You can disallow resumption for a particular user by
                        #  adding the following attribute to the control item
@@ -519,14 +600,14 @@ eap {
                        #
                        #    Allow-Session-Resumption = No
                        #
-                       #  If no virtual_server is specified you CANNOT enable
+                       #  NOTE: If no virtual_server is specified you *CANNOT* enable
                        #  resumption for just one user by setting the above
-                       #  attribute to "yes".
+                       #  attribute to `yes`.
                        #
 #                      virtual_server = 'tls-cache'
 
                        #
-                       #  Name of the context TLS sessions are created under.
+                       #  name:: Name of the context TLS sessions are created under.
                        #
                        #  Qualifies TLS sessions so that they can't be used for
                        #  purposes for which they were not intended.
@@ -537,28 +618,30 @@ eap {
                        #
                        #  To disable - set to a zero length string "".
                        #
-                       #  Note: OpenSSL only allows 32 bytes of session ctx, so
-                       #        the value provided here is digested with SHA256.
+                       #  NOTE: OpenSSL only allows 32 bytes of session ctx, so
+                       #  the value provided here is digested with SHA256.
                        #
 #                      name = "%{EAP-Type}%{Virtual-Server}"
 
+                       #
+                       #  lifetime::
                        #
                        #  The period for which a resumable session remains valid.
                        #  The actual period is the lower of this value, and the
-                       #  ttl set in rlm_cache.
+                       #  ttl set in `rlm_cache`.
                        #
-                       #  Default is 24hrs inline with RFC4346.
+                       #  Default is 24hrs inline with RFC 4346.
                        #
 #                      lifetime = 86400
 
                        #
-                       #  Revalidate client's certificate chain each time a session
-                       #  is resumed.
+                       #  verify:: Revalidate client's certificate chain each time
+                       #  a session is resumed.
                        #
                        #  Intermediaries provided by the client are not cached,
                        #  or copied to the server's certificate store, so
                        #  rebuilding the certificate chain will fail if we don't
-                       #  have the intermediaries loaded from ca_file or ca_path.
+                       #  have the intermediaries loaded from `ca_file` or `ca_path`.
                        #
                        #  This is useful with long cache lifetimes, where a
                        #  certificate may be revoked in the interim between the
@@ -566,6 +649,8 @@ eap {
                        #
 #                      verify = no
 
+                       #
+                       #  require_extended_master_secret::
                        #
                        #  Only allow session resumption if an extended master
                        #  secret has been created.  This requires client support.
@@ -575,32 +660,40 @@ eap {
                        #  a session if it can insert itself into the path between
                        #  the TLS client and TLS server.
                        #
-                       #    https://mitls.org/pages/attacks/3SHAKE
+                       #  See more at https://mitls.org/pages/attacks/3SHAKE
                        #
-                       #  Note: This attack is undetectable by the client.
+                       #  WARNING: This attack is undetectable by the client.
                        #
 #                      require_extended_master_secret = yes
 
+                       #
+                       #  require_perfect_forward_secrecy::
                        #
                        #  Only allow session resumption if a cipher which would
                        #  allow perfect forward secrecy has been selected.
                        #
 #                      require_perfect_forward_secrecy = no
 
+                       #
+                       #  [NOTE]
+                       #  ====
                        #  As of 4.0 OpenSSL's internal cache has been disabled due to
                        #  scoping/threading issues.
                        #
                        #  The following configuration options are deprecated.  TLS
-                       #  session caching is now handled by the "cache" module.
+                       #  session caching is now handled by the `cache` module.
                        #  That module is more configurable, and has more back-ends
                        #  than the simple configurations below.
                        #
-                       #    enable
-                       #    persist_dir
-                       #    max_entries
+                       #  * `enable`
+                       #  * `persist_dir`
+                       #  * `max_entries`
+                       #  ====
                        #
                }
 
+               #
+               #  ### Dynamic CRLs or OCSP
                #
                #  As of version 2.1.10, client certificates can be validated
                #  via an external command.  This allows dynamic CRLs or OCSP to
@@ -611,12 +704,14 @@ eap {
                #  below to enable it.
                #
                verify {
+                       #
+                       #  tmpdir::
                        #
                        #  A temporary directory where the client certificates
                        #  are stored.  This directory MUST be owned by the UID
                        #  of the server, and MUST not be accessible by any
                        #  other users.  When the server starts, it will do
-                       #  "chmod go-rwx" on the directory, for security
+                       #  `chmod go-rwx` on the directory, for security
                        #  reasons.  The directory MUST exist when the server
                        #  starts.
                        #
@@ -625,14 +720,16 @@ eap {
                        #
 #                      tmpdir = /tmp/radiusd
 
+                       #
+                       #  client::
                        #
                        #  The command used to verify the client cert. We
                        #  recommend using the OpenSSL command-line tool.
                        #
-                       #  The ${..ca_path} text is a reference to the ca_path
+                       #  The `${..ca_path}` text is a reference to the ca_path
                        #  variable defined above.
                        #
-                       #  The %{TLS-Client-Cert-Filename} is the name of the
+                       #  The `%{TLS-Client-Cert-Filename}` is the name of the
                        #  temporary file containing the cert in PEM format.
                        #  This file is automatically deleted by the server when
                        #  the command returns.
@@ -641,7 +738,7 @@ eap {
                }
 
                #
-               #  OCSP Configuration
+               #  ### OCSP Configuration
                #
                #  Certificates can be verified against an OCSP Responder.
                #  This makes it possible to immediately revoke certificates without
@@ -650,36 +747,49 @@ eap {
                #  In addition to the configuration items below, the behaviour of
                #  OCSP can be altered by runtime attributes.
                #
-               #  If OCSP is enabled, the &reply:TLS-OCSP-Cert-Valid attribute will
+               #  If OCSP is enabled, the `&reply:TLS-OCSP-Cert-Valid` attribute will
                #  be added after OCSP completes.  One of the following values will
                #  be set:
                #
-               #    - no      OCSP responder indicated the certificate is not valid.
-               #    - yes     OCSP responder indicated the certificate is valid.
-               #    - skipped OCSP checks were skipped.
+               #  [options="header,autowidth"]
+               #  |===
+               #  | Value   | Description
+               #  | no      | OCSP responder indicated the certificate is not valid.
+               #  | yes     | OCSP responder indicated the certificate is valid.
+               #  | skipped | OCSP checks were skipped.
+               #  |===
                #
-               #  If an OCSP check is performed, the &reply:TLS-OCSP-Next-Update
+               #  If an OCSP check is performed, the `&reply:TLS-OCSP-Next-Update`
                #  attribute will also be added.  The value of this will attribute
                #  be the number of seconds until the certificate state need be refreshed.
-               #  This can be used as a Cache-TTL value if you wish to use the cache
+               #  This can be used as a `Cache-TTL` value if you wish to use the cache
                #  module to store OCSP certificate validation status.
                #
-               #  If when the OCSP check is performed, a &control:TLS-OCSP-Cert-Valid
+               #  If when the OCSP check is performed, a `&control:TLS-OCSP-Cert-Valid`
                #  attribute is present, its value will force the outcome of the OCSP
                #  check, and the OCSP responder will not be contacted.
                #  Values map to the following OCSP responses:
                #
-               #    - no      Invalid.
-               #    - yes     Valid.
-               #    - skipped If softfail = yes value else invalid.
+               #  [options="header,autowidth"]
+               #  |===
+               #  | Value   | Description
+               #  | no      | Invalid.
+               #  | yes     | Valid.
+               #  | skipped | If `softfail = yes` value else invalid.
+               #  |===
                #
                ocsp {
                        #
-                       #  Enable it.  The default is "no". Deleting the entire
-                       #  "ocsp" subsection also disables ocsp checking
+                       #  enable::
+                       #
+                       #  Deleting the entire `ocsp` subsection also disables ocsp checking.
+                       #
+                       #  Default is `no`.
                        #
 #                      enable = no
 
+                       #
+                       #  virtual_server::
                        #
                        #  OCSP checks are performed immediately after the
                        #  complete certificate is received from the supplicant,
@@ -689,78 +799,100 @@ eap {
                        #  In order to retrieve cached OCSP states, a virtual
                        #  server must be defined here.
                        #
-                       #  See raddb/sites-available/tls-cache for details.
+                       #  See `raddb/sites-available/tls-cache` for details.
                        #
 #                      virtual_server = 'tls-cache'
 
+                       #
+                       #  override_cert_url::
                        #
                        #  The OCSP Responder URL can be automatically extracted
                        #  from the certificate in question. To override the
-                       #  OCSP Responder URL set "override_cert_url = yes".
+                       #  OCSP Responder URL set `override_cert_url = yes`.
                        #
                        override_cert_url = yes
 
+                       #
+                       #  url::
                        #
                        #  If the OCSP Responder address is not extracted from
                        #  the certificate, the URL can be defined here.
                        #
                        url = "http://127.0.0.1/ocsp/"
 
+                       #
+                       #  use_nonce::
                        #
                        #  If the OCSP Responder can not cope with nonce in the
                        #  request, then it can be disabled here.
                        #
-                       #  For security reasons, disabling this option is not
+                       #  [WARNING]
+                       #  ====
+                       #  * For security reasons, disabling this option is not
                        #  recommended as nonce protects against replay attacks.
                        #
-                       #  Note that Microsoft AD Certificate Services OCSP
+                       #  * Microsoft AD Certificate Services OCSP
                        #  Responder does not enable nonce by default. It is more
                        #  secure to enable nonce on the responder than to
-                       #  disable it in the query here. See
-                       #  http://technet.microsoft.com/en-us/library/cc770413%28WS.10%29.aspx
+                       #  disable it in the query here.
+                       #
+                       #  See http://technet.microsoft.com/en-us/library/cc770413%28WS.10%29.aspx
+                       #  ====
                        #
 #                      use_nonce = yes
 
+                       #
+                       #  timeout::
                        #
                        #  Number of seconds before giving up waiting for OCSP
-                       #  response. 0 uses system default.
+                       #  response.
+                       #
+                       #  Default is `0`.
                        #
 #                      timeout = 0
 
+                       #
+                       #  softfail::
                        #
                        #  Normally an error in querying the OCSP responder (no
                        #  response from server, server did not understand the
                        #  request, etc) will result in a validation failure.
                        #
-                       #  To treat these errors as 'soft' failures and still
+                       #  To treat these errors as `soft` failures and still
                        #  accept the certificate, enable this option.
                        #
-                       #  Warning: this may enable clients with revoked
+                       #  WARNING: this may enable clients with revoked
                        #  certificates to connect if the OCSP responder is not
-                       #  available. Use with caution.
+                       #  available. *Use with caution*.
                        #
 #                      softfail = no
                }
 
-
                #
-               #  Configures OCSP stapling for server certificates.
+               #  ### OCSP stapling for server certificates
                #
                #  If requested, we query either the server listed below (as url),
                #  or the one specified in our server certificate, to retrieve an
                #  OCSP response to pass back to the TLS client.
                #
+               #  staple { ... }::
+               #               
                #  This allows TLS clients to check for certificate revocation before
                #  divulging credentials to a (possibly rogue) server, that may be
                #  presenting a compromised certificate.
                #
                staple {
                        #
-                       #  Enable it.  The default is "no". Deleting the entire
-                       #  "ocsp" subsection also disables ocsp checking
+                       #  enable::
+                       #
+                       #  Enable it. Deleting the entire `ocsp` subsection also disables ocsp checking.
+                       #
+                       #  Default is `no`.
                        #
 #                      enable = no
 
+                       #
+                       #  virtual_server::
                        #
                        #  OCSP checks are performed whenever a TLS client includes
                        #  an OCSP stapling extension.
@@ -771,47 +903,60 @@ eap {
                        #  The same virtual server can be used for caching
                        #  client OCSP response states, and stapling information.
                        #
-                       #  See raddb/sites-available/tls-cache for details.
+                       #  See `raddb/sites-available/tls-cache` for details.
                        #
 #                      virtual_server = 'tls-cache'
 
+                       #
+                       #  override_cert_url::
                        #
                        #  The OCSP Responder URL can be automatically extracted
                        #  from the certificate in question. To override the
-                       #  OCSP Responder URL set "override_cert_url = yes".
+                       #  OCSP Responder URL set `override_cert_url = yes`.
                        #
                        override_cert_url = yes
 
+                       #
+                       #  url::
                        #
                        #  If the OCSP Responder address is not extracted from
                        #  the certificate, the URL can be defined here.
                        #
                        url = "http://127.0.0.1/ocsp/"
 
+                       #
+                       #  use_nonce::
                        #
                        #  If the OCSP Responder can not cope with nonce in the
                        #  request, then it can be disabled here.
                        #
-                       #  For security reasons, disabling this option is not
+                       #  [WARNING]
+                       #  ====
+                       #  * For security reasons, disabling this option is not
                        #  recommended as nonce protects against replay attacks.
                        #
-                       #  Note that Microsoft AD Certificate Services OCSP
+                       #  * Microsoft AD Certificate Services OCSP
                        #  Responder does not enable nonce by default. It is more
                        #  secure to enable nonce on the responder than to
                        #  disable it in the query here. See
                        #  http://technet.microsoft.com/en-us/library/cc770413%28WS.10%29.aspx
+                       #  ====
                        #
 #                      use_nonce = yes
 
                        #
                        #  Number of seconds before giving up waiting for OCSP
-                       #  response. 0 uses system default.
+                       #  response.
+                       #
+                       #  Default is `0`.
                        #
 #                      timeout = 0
 
+                       #
+                       #  softfail::
                        #
                        #  Normally if we can't query the OCSP Responder
-                       #  we issue a fatal alert, and abort.  Set this to true
+                       #  we issue a fatal alert, and abort.  Set this to `true`
                        #  to allow the session to continue without an OCSP
                        #  stapling response being sent to the TLS client.
                        #
@@ -819,20 +964,23 @@ eap {
                }
        }
 
-       ## EAP-TLS
        #
-       #  As of Version 3.0, the TLS configuration for TLS-based
-       #  EAP types is above in the "tls-config" section.
+       # ### EAP-TLS
+       #
+       #  As of Version 3.0, the TLS configuration for `TLS-based`
+       #  EAP types is above in the `tls-config { ... }` section.
        #
        tls {
                # Point to the common TLS configuration
                tls = tls-common
 
                #
-               #  EAP-TLS can work without a client certificate, but situations
+               #  require_client_cert::
+               #
+               #  `EAP-TLS` can work without a client certificate, but situations
                #  whether this is useful are quite limited.
                #
-               #  Currently only the Hotspot 2.0 R2 standard utilises EAP-TLS
+               #  Currently only the Hotspot 2.0 R2 standard utilises `EAP-TLS`
                #  without a peer certificate.
                #
                #  This is to secure the SSID used to provide connectivity to the OSU
@@ -840,41 +988,46 @@ eap {
                #
                #  You can override this option by setting:
                #
-               #       EAP-TLS-Require-Client-Cert = Yes/No
+               #    EAP-TLS-Require-Client-Cert = Yes/No
                #
                #  in the control items for a request.
                #
 #              require_client_cert = yes
 
                #
-               #  Include_length is a flag which is by default set to yes If
-               #  set to yes, Total Length of the message is included in EVERY
-               #  packet we send. If set to no, Total Length of the message is
+               #  include_length::
+               #
+               #  flag which is by default set to yes If set to `yes`,
+               #  Total length of the message is included in EVERY
+               #  packet we send. If set to `no`, Total length of the message is
                #  included ONLY in the First packet of a fragment series.
                #
 #              include_length = yes
 
                #
-               #  As part of checking a client certificate, the EAP-TLS sets
-               #  some attributes such as TLS-Client-Cert-Common-Name. This virtual
+               #  virtual_server::
+               #
+               #  As part of checking a client certificate, the `EAP-TLS` sets
+               #  some attributes such as `TLS-Client-Cert-Common-Name`. This virtual
                #  server has access to these attributes, and can be used to
                #  accept or reject the request.
                #
 #              virtual_server = check-eap-tls
        }
 
-       ## EAP-TTLS
        #
-       #  Note: To use EAP-TTLS you must also configure an inner method in
-       #  mods-enabled/eap_inner.
+       #  ### EAP-TTLS
        #
-       #  The TTLS module implements the EAP-TTLS protocol, which can be
+       #  The TTLS module implements the `EAP-TTLS` protocol, which can be
        #  described as EAP inside of Diameter, inside of TLS, inside of EAP,
-       #  inside of RADIUS...
+       #  inside of RADIUS.
+       #
+       #  NOTE: To use `EAP-TTLS `you must also configure an `inner` method in
+       #  `mods-enabled/eap_inner`.
        #
        #  Surprisingly, it works quite well.
        #
-       #  When using PAP, GTC, or MSCAHPv2 as an inner method EAP-TTLS is
+       #  When using `PAP`, `GTC`, or `MSCAHPv2` as an inner method `EAP-TTLS` is
        #  only secure if the supplicant is configured to validate the the
        #  server certificate presented.
        #
@@ -883,26 +1036,33 @@ eap {
        #
        ttls {
                #
-               #  Which tls-config section the TLS negotiation parameters
-               #  are in - see EAP-TLS above for an explanation.
+               #  tls::
+               #
+               #  Which `tls-config` section the TLS negotiation parameters
+               #  are in - see `EAP-TLS` above for an explanation.
                #
                #  In the case that an old configuration from FreeRADIUS
-               #  v2.x is being used, all the options of the tls-config
+               #  v2.x is being used, all the options of the `tls-config { ... }`
                #  section may also appear instead in the 'tls' section
-               #  above. If that is done, the tls= option here (and in
-               #  tls above) MUST be commented out.
+               #  above. If that is done, the `tls=` option here (and in tls above)
+               #  MUST be commented out.
                #
                tls = tls-common
 
                #
-               #  Both copy_request_to_tunnel and use_tunneled_reply have been
+               #  [WARNING]
+               #  ====
+               #  Both `copy_request_to_tunnel` and `use_tunneled_reply` have been
                #  removed in v4.0.
                #
-               #  See the new policy "copy_request_to_tunnel" in
-               #  sites-available/inner-tunnel, and in policy.d/eap
+               #  See the new policy `copy_request_to_tunnel` in
+               #  `sites-available/inner-tunnel`, and in `policy.d/eap`
                #  for more information.
+               #  ====
                #
 
+               #
+               #  virtual_server::
                #
                #  The inner tunneled request can be sent through a virtual
                #  server constructed specifically for this purpose.
@@ -913,92 +1073,90 @@ eap {
                #
                virtual_server = "inner-tunnel"
 
+               #
+               #  include_length::
                #
                #  This has the same meaning, and overwrites, the same field in
-               #  the "tls" configuration, above. The default value here is
-               #  "yes".
+               #  the `tls` configuration, above. The default value here is
+               #  `yes`.
                #
 #              include_length = yes
 
                #
-               #  EAP-TTLS does not require a client certificate.
+               #  require_client_cert::
+               #
+               #  `EAP-TTLS` does not require a client certificate.
                #  However, you can require one by setting the
                #  following option. You can also override this option by
                #  setting
                #
-               #       EAP-TLS-Require-Client-Cert = Yes
+               #    EAP-TLS-Require-Client-Cert = Yes
                #
                #  in the control items for a request.
                #
-               #  Note that the majority of supplicants do not support using a
-               #  client certificate with EAP-TTLS, so this option is unlikely
+               #  NOTE: The majority of supplicants do not support using a
+               #  client certificate with `EAP-TTLS`, so this option is unlikely
                #  to be usable for most people.
                #
 #              require_client_cert = yes
        }
 
-
-       ## EAP-PEAP
        #
-       ###########################################################################
+       #  ### EAP-PEAP
        #
-       #  !!!!!             WARNINGS for Windows compatibility               !!!!!
-       #
-       ###########################################################################
-       #
-       #  If you see the server send an Access-Challenge, and the client never
-       #  sends another Access-Request, then
+       #  The tunneled `EAP` session needs a default `EAP` type which is separate
+       #  from the one for the non-tunneled EAP module.  Inside of the TLS/PEAP
+       #  tunnel, we recommend using `EAP-MS-CHAPv2`.
        #
-       #               STOP!
+       #  When using `GTC`, or `MSCAHPv2` as an inner method, `PEAP` is only secure
+       #  if the supplicant is configured to validate the server certificate.
        #
-       #  The server certificate has to have special OID's in it, or else the
-       #  Microsoft clients will silently fail.  See the "scripts/xpextensions"
-       #  file for details, and the following page:
+       #  It is trivial to retrieve the user's credentials from these inner
+       #  methods, if the user connects to a rogue server.
        #
-       #       http://support.microsoft.com/kb/814394/en-us
+       #  #### Windows compatibility
        #
-       #  For additional Windows XP SP2 issues, see:
+       #  [IMPORTANT]
+       #  ====
+       #  * If you see the server send an `Access-Challenge`, and the client never
+       #  sends another `Access-Request`, then *STOP*!
        #
-       #       http://support.microsoft.com/kb/885453/en-us
+       #  * The server certificate has to have special OID's in it, or else the
+       #  Microsoft clients will silently fail.  See the `scripts/xpextensions`
+       #  file for details, and the following page
+       #  http://support.microsoft.com/kb/814394/en-us .
        #
-       #  If is still doesn't work, and you're using Samba, you may be
-       #  encountering a Samba bug.  See:
+       #  * For additional Windows XP SP2 issues,
+       #  see: http://support.microsoft.com/kb/885453/en-us
        #
-       #       https://bugzilla.samba.org/show_bug.cgi?id=6563
+       #  * If is still doesn't work, and you're using Samba, you may be
+       #  encountering a Samba bug.
+       #  see: https://bugzilla.samba.org/show_bug.cgi?id=6563
        #
-       #  Note that we do not necessarily agree with their explanation... but
+       #  * Note that we do not necessarily agree with their explanation. but
        #  the fix does appear to work.
+       #  ====
        #
-       ##########################################################################
-
-       #
-       #
-       #  Note: To use EAP-TTLS you must also configure an inner method in
-       #  mods-enabled/eap_inner.
-       #
-       #  The tunneled EAP session needs a default EAP type which is separate
-       #  from the one for the non-tunneled EAP module.  Inside of the TLS/PEAP
-       #  tunnel, we recommend using EAP-MS-CHAPv2.
-       #
-       #  When using GTC, or MSCAHPv2 as an inner method, PEAP is only secure if
-       #  the supplicant is configured to validate the server certificate.
-       #
-       #  It is trivial to retrieve the user's credentials from these inner
-       #  methods, if the user connects to a rogue server.
+       #  NOTE: To use `EAP-TTLS` you must also configure an inner method in
+       #  `mods-enabled/eap_inner`.
        #
        peap {
                #
-               #  Which tls-config section the TLS negotiation parameters are
-               #  in - see EAP-TLS above for an explanation.
+               #  tls::
+               #
+               #  Which `tls-config` section the TLS negotiation parameters are
+               #  in - see `EAP-TLS` above for an explanation.
                #
                #  In the case that an old configuration from FreeRADIUS v2.x is
-               #  being used, all the options of the tls-config section may
-               #  also appear instead in the 'tls' section above. If that is
+               #  being used, all the options of the `tls-config` section may
+               #  also appear instead in the `tls` section above. If that is
                #  done, the tls= option here (and in tls above) MUST be
                #  commented out.
                #
                tls = tls-common
 
+               #
+               #  default_eap_type::
                #
                #  The tunneled EAP session needs a default EAP type which is
                #  separate from the one for the non-tunneled EAP module.
@@ -1008,21 +1166,28 @@ eap {
                default_eap_type = mschapv2
 
                #
-               #  Both copy_request_to_tunnel and use_tunneled_reply have been
+               #  [NOTE]
+               #  ====
+               #  Both `copy_request_to_tunnel` and `use_tunneled_reply` have been
                #  removed in v4.0.
                #
-               #  See the new policy "copy_request_to_tunnel" in
-               #  sites-available/inner-tunnel, and in policy.d/eap
+               #  See the new policy `copy_request_to_tunnel` in
+               #  `sites-available/inner-tunnel`, and in `policy.d/eap`
                #  for more information.
+               #  ====
                #
 
+               #
+               #  proxy_tunneled_request_as_eap::
                #
                #  When the tunneled session is proxied, the home server may not
-               #  understand EAP-MSCHAP-V2. Set this entry to "no" to proxy the
-               #  tunneled EAP-MSCHAP-V2 as normal MSCHAPv2.
+               #  understand `EAP-MSCHAP-V2`. Set this entry to `no` to proxy the
+               #  tunneled `EAP-MSCHAP-V2` as normal`MSCHAPv2`.
                #
 #              proxy_tunneled_request_as_eap = yes
 
+               #
+               #  virtual_server::
                #
                #  The inner tunneled request can be sent through a virtual
                #  server constructed specifically for this purpose.
@@ -1034,153 +1199,182 @@ eap {
                virtual_server = "inner-tunnel"
 
                #
-               #  This option enables support for MS-SoH see doc/SoH.txt for
+               #  soh::
+               #
+               #  This option enables support for `MS-SoH` see `doc/SoH.txt` for
                #  more info. It is disabled by default.
                #
 #              soh = yes
 
                #
-               #  The SoH reply will be turned into a request which can be sent
+               #  soh_virtual_server::
+               #
+               #  The `SoH` reply will be turned into a request which can be sent
                #  to a specific virtual server:
                #
 #              soh_virtual_server = "soh-server"
 
                #
-               #  Unlike EAP-TLS, PEAP does not require a client certificate.
+               #  require_client_cert::
+               #
+               #  Unlike `EAP-TLS`, `PEAP `does not require a client certificate.
                #  However, you can require one by setting the following
                #  option. You can also override this option by setting
                #
                #       EAP-TLS-Require-Client-Cert = Yes
                #
-               #  in the control items for a request.
+               #  in the `control` items for a request.
                #
-               #  Note that the majority of supplicants do not support using a
-               #  client certificate with PEAP, so this option is unlikely to
+               #  NOTE: The majority of supplicants do not support using a
+               #  client certificate with `PEAP`, so this option is unlikely to
                #  be usable for most people.
                #
 #              require_client_cert = yes
        }
 
+       #
+       #  ### EAP MS-CHAPv2
        #
        #  This takes no configuration.
        #
-       #  Note that it is the EAP MS-CHAPv2 sub-module, not the main 'mschap'
+       #  NOTE: It is the EAP MS-CHAPv2 sub-module, not the main `mschap`
        #  module.
        #
        #  Note also that in order for this sub-module to work, the main
-       #  'mschap' module MUST ALSO be configured.
+       #  `mschap` module MUST ALSO be configured.
        #
-       #  This module is the *Microsoft* implementation of MS-CHAPv2 in EAP.
-       #  There is another (incompatible) implementation of MS-CHAPv2 in EAP by
-       #  Cisco, which FreeRADIUS does not currently support.
+       #  This module is the *Microsoft* implementation of `MS-CHAPv2` in `EAP`.
+       #  There is another (*incompatible*) implementation of `MS-CHAPv2 in `EAP` by
+       #  Cisco, which *FreeRADIUS does not currently support*.
        #
        mschapv2 {
+               #
+               #  send_error::
+               #
                #  Prior to version 2.1.11, the module never sent the
-               #  MS-CHAP-Error message to the client.  This worked, but it had
+               #  `MS-CHAP-Error` message to the client.  This worked, but it had
                #  issues when the cached password was wrong.  The server
-               #  *should* send "E=691 R=0" to the client, which tells it to
+               #  *should* send `E=691 R=0` to the client, which tells it to
                #  prompt the user for a new password.
                #
-               #  The default is to behave as in 2.1.10 and earlier, which is
-               #  known to work.  If you set "send_error = yes", then the error
+               #  CAUTION: The default is to behave as in `2.1.10` and earlier, which is
+               #  known to work.  If you set `send_error = yes`, then the error
                #  message will be sent back to the client. This *may* help some
                #  clients work better, but *may* also cause other clients to
                #  stop working.
                #
 #              send_error = no
 
+               #
+               #  identity::
+               #
                #  Server identifier to send back in the challenge. This should
                #  generally be the host name of the RADIUS server.  Or, some
                #  information to uniquely identify it.
+               #
 #              identity = "FreeRADIUS"
        }
 
-       ## EAP-FAST
        #
-       #  Note: To use EAP-FAST you must also configure an inner method in
-       #  mods-enabled/eap_inner.
+       #  ### EAP-FAST
        #
-       #  The FAST module implements the EAP-FAST protocol
+       #  The FAST module implements the EAP-FAST protocol.
+       #
+       #  NOTE: To use `EAP-FAST` you must also configure an `inner` method in
+       #  `mods-enabled/eap_inner`.
        #
        fast {
-               # Point to the common TLS configuration
+               #
+               #  tls::
+               #
+               #  Point to the common TLS configuration.
                #
                tls = tls-common
 
                #
-               #  If 'cipher_list' is set here, it will over-ride the
-               #  'cipher_list' configuration from the 'tls-common'
-               #  configuration.  The EAP-FAST module has it's own
-               #  over-ride for 'cipher_list' because the
+               #  cipher_list::
+               #
+               #  If `cipher_list` is set here, it will over-ride the
+               #  `cipher_list` configuration from the `tls-common`
+               #  configuration.  The `EAP-FAST` module has it's own
+               #  over-ride for `cipher_list` because the
                #  specifications mandata a different set of ciphers
-               #  than are used by the other EAP methods.
+               #  than are used by the other `EAP` methods.
                #
-               #  cipher_list though must include "ADH" for anonymous provisioning.
+               #  `cipher_list` though must include "ADH" for anonymous provisioning.
                #  This is not as straight forward as appending "ADH" alongside
                #  "DEFAULT" as "DEFAULT" contains "!aNULL" so instead it is
                #  recommended "ALL:!EXPORT:!eNULL:!SSLv2" is used
                #
-               #  Note - for OpenSSL 1.1.0 and above you may need
-               #  to add ":@SECLEVEL=0"
+               #  NOTE: for OpenSSL 1.1.0 and above you may need to add ":@SECLEVEL=0"
                #
                cipher_list = "ALL:!EXPORT:!eNULL:!SSLv2"
 
-               # PAC lifetime in seconds (default: seven days)
+               #
+               #  pac_lifetime:: PAC lifetime in seconds.
+               #
+               #  Default is: `seven days`
                #
                pac_lifetime = 604800
 
-               # Authority ID of the server
                #
-               # if you are running a cluster of RADIUS servers, you should make
-               # the value chosen here (and for "pac_opaque_key") the same on all
-               # your RADIUS servers.  This value should be unique to your
-               # installation.  We suggest using a domain name.
+               #  authority_identity:: Authority ID of the server.
+               #
+               #  if you are running a cluster of RADIUS servers, you should make
+               #  the value chosen here (and for `pac_opaque_key`) the same on all
+               #  your RADIUS servers.  This value should be unique to your
+               #  installation.  We suggest using a domain name.
                #
                authority_identity = "1234"
 
-               # PAC Opaque encryption key (must be exactly 32 bytes in size)
                #
-               # This value MUST be secret, and MUST be generated using
-               # a secure method, such as via 'openssl rand -hex 32'
+               #  pac_opaque_key::
+               #
+               #  PAC Opaque encryption key (must be exactly 32 bytes in size).
+               #
+               #  This value MUST be secret, and MUST be generated using
+               #  a secure method, such as via `openssl rand -hex 32`
                #
                pac_opaque_key = "0123456789abcdef0123456789ABCDEF"
 
-               # Same as for TTLS, PEAP, etc.
+               #
+               # virtual_server:: Same as for `TTLS`, `PEAP`, etc.
                #
                virtual_server = inner-tunnel
        }
 
-       ## EAP-SIM
+       #
+       #  ### EAP-SIM
        #
        #  Triplets can be provided using control attributes:
        #
-       #  - &control:EAP-SIM-KC
-       #  - &control:EAP-SIM-RAND
-       #  - &control:EAP-SIM-SRES
+       #  * `&control:EAP-SIM-KC`
+       #  * `&control:EAP-SIM-RAND`
+       #  * `&control:EAP-SIM-SRES`
        #
-       #  Note: Three instances of each attribute must be provided.
+       #  NOTE: Three instances of each attribute must be provided.
        #
        #  Alternatively triplets can be generated locally using
        #  control attributes:
        #
-       #  - &control:SIM-Ki
-       #  - &control:SIM-OPc
-       #  - &control:SIM-Algo-Version (optional - see defaults below)
+       #  * `&control:SIM-Ki`
+       #  * `&control:SIM-OPc`
+       #  * `&control:SIM-Algo-Version` (optional - see defaults below)
        #
        #  UMTS Milenage inputs (AMF, SQN) are ignored.
        #
-       #  &control:SIM-Algo-Version selects the SIM algorithm used,
+       #  `&control:SIM-Algo-Version` selects the SIM algorithm used,
        #  it must match the algorithm used by the SIM.
        #
-       #  Accepted values for SIM-Algo-Versio are:
+       #  Accepted values for `SIM-Algo-Versio` are:
        #
-       #  - Comp128v1
-       #  - Comp128v2
-       #  - Comp128v3 (default if no &control:SIM-OPc)
-       #  - Milenage (default if &control:SIM-OPc is available)
+       #  * `Comp128v1`
+       #  * `Comp128v2`
+       #  * `Comp128v3` (default if no &control:SIM-OPc)
+       #  * `Milenage` (default if &control:SIM-OPc is available)
        #
-       #  Note: In general operators will not provide the Ki (subscriber
-       #  key) for their SIM cards, as the Ki is considered highly
+       #  NOTE: In general operators will not provide the Ki (subscriber
+       #  key) for their `SIM cards`, as the Ki is considered highly
        #  sensitive.
        #
        #  Local triplet generation is intended for testing and
@@ -1188,20 +1382,24 @@ eap {
        #  are in use.
        #
        sim {
-               ## Send a protected success message
                #
-               #  If true - indicate to the peer that we'd like to send
+               #  send_result_ind:: Send a protected success message.
+               #
+               #  If `yes` - indicate to the peer that we'd like to send
                #  a protected success message.  If the peer agrees and
-               #  authentication succeeds, send a SIM-Notification (Success)
-               #  packet protected with an AT_MAC attribute.
+               #  authentication succeeds, send a `SIM-Notification` (Success)
+               #  packet protected with an `AT_MAC` attribute.
+               #
+               #  After the Notification is `ACKed` by the peer, we send
+               #  the final `EAP-Success` packet containing `MPPE` keys.
                #
-               #  After the Notification is ACKed by the peer, we send
-               #  the final EAP-Success packet containing MPPE keys.
 #              send_result_ind = yes
        }
 
-       ## EAP-AKA
        #
+       #  ### EAP-AKA
+       #
+       #  This takes no configuration.
        #
        aka {