start of asciidoc conversion

diff --git a/raddb/clients.conf b/raddb/clients.conf
index 95bae930e1ed4801049f30515ec4253430de1ecb..ec1bc3399d6979c516071686194c37e1129a29da 100644 (file)
--- a/raddb/clients.conf
+++ b/raddb/clients.conf
@@ -1,60 +1,65 @@
 # -*- text -*-
-##
-## clients.conf -- client configuration directives
-##
-##     $Id$
-
-#######################################################################
-#
-#  Define RADIUS clients (usually a NAS, Access Point, etc.).
-
 #
-#  Defines a RADIUS client.
+# # Client Definitions
 #
-#  '127.0.0.1' is another name for 'localhost'.  It is enabled by default,
-#  to allow testing of the server after an initial installation.  If you
-#  are not going to be permitting RADIUS queries from localhost, we suggest
-#  that you delete, or comment out, this entry.
+#      $Id$
+
+#######################################################################
 #
+#  The `clients.conf file defines global clients.  These clients are
+#  systems which are permitted to send packets to the server.  For
+#  security, packets from other IP addresses are ignored.
 #
-
+# ## client section
 #
-#  Each client has a "short name" that is used to distinguish it from
-#  other clients.
+#  A client is defined via a section called `client NAME { ... }`.
+#  The NAME field is mandatory, and is used as the "short name" of the
+#  client.
 #
-#  In version 1.x, the string after the word "client" was the IP
-#  address of the client.  In 2.0, the IP address is configured via
-#  the "ipaddr" or "ipv6addr" fields.  For compatibility, the 1.x
-#  format is still accepted.
+#  The default configuration allows packets from 127.0.0.1, and no
+#  other IP address.  This configuration is to allow testing of the
+#  server after an initial installation.  If you are not going to be
+#  permitting RADIUS queries from localhost, we suggest that you
+#  delete, or comment out, the 'localhost' entry.
 #
 client localhost {
-       #  Only *one* of ipaddr, ipv4addr, ipv6addr may be specified for
-       #  a client.
+       # ipaddr:: define the unique IP address (or network) for this client.
+       #
+       #  NOTE: Only *one* of ipaddr, ipv4addr, ipv6addr may be
+       #  specified for a client.
        #
        #  ipaddr will accept IPv4 or IPv6 addresses with optional CIDR
-       #  notation '/<mask>' to specify ranges.
+       #  notation `/<mask>` to specify ranges.
        #
-       #  ipaddr will accept domain names e.g. example.org resolving
-       #  them via DNS.
+       #  `ipaddr` will accept domain names e.g. `example.org`, and
+       #  will resolve the name via DNS.
        #
        #  If both A and AAAA records are found, A records will be
        #  used in preference to AAAA.
        ipaddr = 127.0.0.1
 
-       #  Same as ipaddr but allows v4 addresses only. Requires A
-       #  record for domain names.
-#      ipv4addr = *    # any.  127.0.0.1 == localhost
+       #  ipv4addr:: Similar to `ipaddr`, but allows v4 addresses
+       #  only. Looks up A record for domain names.
+       #
+       #  * `*` is "any" address.
+       #  * `127.0.0.1` is localhost.
+       #
+#      ipv4addr = *
 
-       #  Same as ipaddr but allows v6 addresses only. Requires AAAA
-       #  record for domain names.
-#      ipv6addr = ::   # any.  ::1 == localhost
+       #  ipv6addr:: Similar to `ipaddr` but allows v6 addresses
+       #  only. Looks up AAAA record for domain names.
+       #
+       #  * `::` is "any" address.
+       #  * `::1` is localhost.
+       #
+#      ipv6addr = ::
 
        #
-       #  A note on DNS:  We STRONGLY recommend using IP addresses
-       #  rather than host names.  Using host names means that the
-       #  server will do DNS lookups when it starts, making it
-       #  dependent on DNS.  i.e. If anything goes wrong with DNS,
-       #  the server won't start!
+       #  NOTE: We STRONGLY recommend using IP addresses instead of
+       #  host names.  Using host names means that the server will do
+       #  DNS lookups when it starts, making it dependent on DNS.
+       #  i.e. If anything goes wrong with DNS, the server won't
+       #  start!
        #
        #  The server also looks up the IP address from DNS once, and
        #  only once, when it starts.  If the DNS record is later
@@ -62,7 +67,7 @@ client localhost {
        #
 
        #
-       #  The transport protocol.
+       #  proto:: The transport protocol used by this client.
        #
        #  If unspecified, defaults to "udp", which is the traditional
        #  RADIUS transport.  It may also be "tcp", in which case the