From: Alan T. DeKok <aland@freeradius.org>
Date: Sun, 10 Jun 2018 16:52:23 +0000 (-0400)
Subject: start of asciidoc conversion
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=26e2de388d06d61cfc73e9aa069d67eef372a67e;p=thirdparty%2Ffreeradius-server.git

start of asciidoc conversion
---

diff --git a/raddb/clients.conf b/raddb/clients.conf
index 95bae930e1e..ec1bc3399d6 100644
--- 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