Update raddb/mods-available/ippool

diff --git a/raddb/mods-available/ippool b/raddb/mods-available/ippool
index 1d3305ba45ec71336f55f8f1db05f183772e1b82..575376f4531e24c6ff0e6ae6039099f3cf18c11a 100644 (file)
--- a/raddb/mods-available/ippool
+++ b/raddb/mods-available/ippool
@@ -1,66 +1,104 @@
 # -*- text -*-
 #
+# :toc:
+#
 #  $Id$
 
-#  Do server side ip pool management. Should be added in
-#  post-auth and accounting sections.
+#######################################################################
+#
+#  = IPPool Module
+#
+#  The `ippool` module does server side ip pool management. Should be
+#  added in `post-auth` and `accounting` sections.
+#
+#  The module also requires the existence of the `Pool-Name` attribute.
+#  That way the administrator can add the `Pool-Name` attribute in the
+#  user profiles and use different pools for different users.
+#  The `Pool-Name` attribute is a *check* item not a reply item.
 #
-#  The module also requires the existence of the Pool-Name
-#  attribute. That way the administrator can add the Pool-Name
-#  attribute in the user profiles and use different pools for
-#  different users. The Pool-Name attribute is a *check* item
-#  not a reply item.
+#  NOTE: The `Pool-Name` should be set to the ippool module instance
+#  name or to `DEFAULT` to match any module.
 #
-#  The Pool-Name should be set to the ippool module instance
-#  name or to DEFAULT to match any module.
 
 #
-# Example:
-# radiusd.conf: ippool students { [...] }
-#              ippool teachers { [...] }
-# users file  : DEFAULT Group == students, Pool-Name := "students"
-#              DEFAULT Group == teachers, Pool-Name := "teachers"
-#              DEFAULT Group == other, Pool-Name := "DEFAULT"
+#  ## Sample
+#
+#  <1> The FreeRADIUS service expects some statement into the `radiusd.conf` as below.
+#
+#  [source, unlang]
+#  ----
+#  ippool students { [...] }
+#  
+#  ippool teachers { [...] }
+#  ----
+#
+#  <2> Then the `raddb/users` should have.
+#
+#  [source, unlang]
+#  ----
+#  DEFAULT Group == students, Pool-Name := "students"
+#  DEFAULT Group == teachers, Pool-Name := "teachers"
+#  DEFAULT Group == other, Pool-Name := "DEFAULT"
+#  ----
 #
-# Note: If you change the range parameters you must then erase the
-#       db files.
+#  NOTE: If you change the range parameters you must then erase the db files.
+#
+
+#
+#  ## Default instance
 #
 ippool main_pool {
-       #  The main db file used to allocate addresses.
+       #
+       #  filename:: The main db file used to allocate addresses.
+       #
        filename = ${db_dir}/db.ippool
 
-       #  The start and end ip addresses for this pool.
+       #
+       #  range_start:: The start ip addresses for this pool.
+       #
        range_start = 192.0.2.1
+
+       #
+       #  range_start:: The end ip addresses for this pool.
+       #
        range_stop = 192.0.2.254
 
-       #  The network mask used for this pool.
+       #
+       #  netmask:: The network mask used for this pool.
+       #
        netmask = 255.255.255.0
 
-       #  The gdbm cache size for the db files. Should
-       #  be equal to the number of ip's available in
-       #  the ip pool
+       #
+       #  cache_size:: The `gdbm` cache size for the db files.
+       #  Should be equal to the number of ip's available in the ip pool.
+       #
        cache_size = 800
 
-       #  Helper db index file used in multilink
+       #
+       #  ip_index:: Helper db index file used in multilink.
+       #
        ip_index = ${db_dir}/db.ipindex
 
-       #  If set, the Framed-IP-Address already in the
-       #  reply (if any) will be discarded, and replaced
-       #  ith a Framed-IP-Address assigned here.
+       #
+       #  override:: If set, the `Framed-IP-Address` already in the reply (if any)
+       #  will be discarded, and replaced with a `Framed-IP-Address` assigned here.
+       #
        override = no
 
-       #  Specifies the maximum time in seconds that an
-       #  entry may be active.  If set to zero, means
-       #  "no timeout".  The default value is 0
+       #
+       #  maximum_timeout:: Specifies the maximum time in seconds that an entry
+       #  may be active.  If set to zero, means _no timeout_. 
+       #  The default value is 0
+       #
        maximum_timeout = 0
 
-       #  The key to use for the session database (which
-       #  holds the allocated ip's) normally it should
-       #  just be the nas ip/port (which is the default).
-       #
-       #  If your NAS sends the same value of NAS-Port
-       #  all requests, the key should be based on some
-       #  other attribute that is in ALL requests, AND
-       #  is unique to each machine needing an IP address.
+       #
+       #  key:: The `key` to use for the session database (which holds the allocated ip's)
+       #  normally it should just be the nas ip/port (which is the default).
+       #
+       #  NOTE: If your NAS sends the same value of `NAS-Port` all requests, the key should be
+       #  based on some other attribute that is in *ALL* requests, *AND* is unique to each
+       #  machine needing an IP address.
+       #
 #      key = "%{NAS-IP-Address} %{NAS-Port}"
 }