]> git.ipfire.org Git - thirdparty/freeradius-server.git/commitdiff
a number of raddb comment updates and tidying for v4
authorMatthew Newton <matthew-git@newtoncomputing.co.uk>
Wed, 8 Nov 2017 13:35:26 +0000 (13:35 +0000)
committerMatthew Newton <matthew-git@newtoncomputing.co.uk>
Wed, 8 Nov 2017 13:58:08 +0000 (13:58 +0000)
raddb/mods-available/attr_filter
raddb/mods-available/chap
raddb/mods-available/csv
raddb/mods-available/delay
raddb/mods-available/detail
raddb/mods-available/detail.example.com
raddb/mods-available/detail.log
raddb/sites-available/default

index 1caff077b2429c948a04777fcd619be901ac83dc..0714837f53bda6964c088e8eac40da3fa7470a94 100644 (file)
@@ -6,43 +6,51 @@
 #  This file defines a number of instances of the "attr_filter" module.
 #
 
-# attr_filter - filters the attributes received in replies from
-# proxied servers, to make sure we send back to our RADIUS client
-# only allowed attributes.
-attr_filter attr_filter.post-proxy {
+#
+#  Filters the attributes in the packets we send to
+#  the RADIUS home servers.
+#
+#  Add this before calling rlm_radius for proxying.
+#
+attr_filter attr_filter.pre-proxy {
        key = "%{Realm}"
-       filename = ${modconfdir}/${.:name}/post-proxy
+       filename = ${modconfdir}/${.:name}/pre-proxy
 }
 
-# attr_filter - filters the attributes in the packets we send to
-# the RADIUS home servers.
-attr_filter attr_filter.pre-proxy {
+#
+#  Filters the attributes received in replies from proxied
+#  servers, to make sure we send back to our RADIUS client
+#  only allowed attributes.
+#
+#  Add this after calling rlm_radius for proxying.
+#
+attr_filter attr_filter.post-proxy {
        key = "%{Realm}"
-       filename = ${modconfdir}/${.:name}/pre-proxy
+       filename = ${modconfdir}/${.:name}/post-proxy
 }
 
-# Enforce RFC requirements on the contents of Access-Reject
-# packets.  See the comments at the top of the file for
-# more details.
+#
+#  Enforce RFC requirements on the contents of Access-Reject
+#  packets. This should be called from "send Access-Reject".
 #
 attr_filter attr_filter.access_reject {
        key = "%{User-Name}"
        filename = ${modconfdir}/${.:name}/access_reject
 }
 
-# Enforce RFC requirements on the contents of Access-Challenge
-# packets.  See the comments at the top of the file for
-# more details.
+#
+#  Enforce RFC requirements on the contents of Access-Challenge
+#  packets. This is called from "send Access-Challenge".
 #
 attr_filter attr_filter.access_challenge {
        key = "%{User-Name}"
        filename = ${modconfdir}/${.:name}/access_challenge
 }
 
-
+#
 #  Enforce RFC requirements on the contents of the
-#  Accounting-Response packets.  See the comments at the
-#  top of the file for more details.
+#  Accounting-Response packets. Called from the
+#  "send Accounting-Response" section.
 #
 attr_filter attr_filter.accounting_response {
        key = "%{User-Name}"
index e2a3cd3b110ffffdbcff86c7fc65a9275ddc3379..54b296466b7712b59ac67e865f1065e9b3300a42 100644 (file)
@@ -2,10 +2,11 @@
 #
 #  $Id$
 
-# CHAP module
 #
-#  To authenticate requests containing a CHAP-Password attribute.
+#  CHAP module
+#
+#  This module authenticates requests containing a CHAP-Password
+#  attribute. There is no configuration.
 #
 chap {
-       # no configuration
 }
index f1fcf745bdfbb79c9f34a3cf346c17302f715131..b54d9b30cf229901d79cc17c0dbf52928d593188 100644 (file)
@@ -1,4 +1,7 @@
 # -*- text -*-
+#
+#  $Id$
+
 #
 #  Read CSV files and use them in maps.
 #
@@ -6,19 +9,14 @@
 #
 #  Multi-line fields are NOT allowed.
 #
-#
-#
-#
-#  $Id$
-
 csv {
        #
-       #  The field delimiter.  MUST be a one-character string
+       #  The field delimiter. MUST be a one-character string.
        #
        delimiter = ","
 
        #
-       #  The file which contains the CSV data
+       #  The file which contains the CSV data.
        #
        filename = ${modconfdir}/csv/${.:instance}
 
@@ -29,15 +27,16 @@ csv {
        #
        #  MUST NOT include whitespace.
        #
-       #  Fields which are not used should have no name
-       #       e.g. "foo,,bar" defines 3 fields, where the second
-       #       is unused.
+       #  Fields which are not used should have no name,
+       #  e.g. "foo,,bar" defines 3 fields, where the second
+       #  is unused.
        #
        header = "field1,,field3,field4"
 
        #
-       #  The name of the key field.  It is used to index the entries.
-       #  It can be any one of the field names defined above.
+       #  The name of the key field, which is used to index the
+       #  entries. It can be any one of the field names defined
+       #  above.
        #
        key_field = "field1"
 }
index 9e4f19f51c8f91e6f305e321d90e7066121280fd..152c3d4ed217c3144bd9f74cd22451b302242b73 100644 (file)
@@ -2,36 +2,39 @@
 #
 #  $Id$
 
-# Delay the progression of a request in a non-blocking fashion.
 #
-# This module is useful for rate limiting, and introducing artificial jitter
-# into responses.
+#  Delay the progression of a request in a non-blocking fashion.
+#
+#  This module is useful for rate limiting, and introducing
+#  artificial jitter into responses.
 #
 delay {
-               #
-               #  How long to delay request processing for
-               #
-               delay = 1.0
-               
-               #
-               #  Whether the request should be rescheduled even if no delay is needed.
-               #  This introduces a small delay, and allows processing of other requests
-               #  ahead of this one.
-               #
-#              force_reschedule = no
-               
-               #
-               #  Whether delay should be calculated relative to when the request was
-               #  received.  This can be useful for rate limiting, as most NAS will only
-               #  allow a limited number of request to be in flight.
-               #
-#              relative = no
+       #
+       #  How long to delay request processing for.
+       #
+       delay = 1.0
+
+       #
+       #  Whether the request should be rescheduled even if no
+       #  delay is needed. This introduces a small delay, and
+       #  allows processing of other requests ahead of this one.
+       #
+#      force_reschedule = no
+
+       #
+       #  Whether delay should be calculated relative to when
+       #  the request was received. This can be useful for rate
+       #  limiting, as most NAS will only allow a limited number
+       #  of request to be in flight.
+       #
+#      relative = no
 }
 
 delay delay_reject {
-               #
-               #  How long to delay request processing for
-               #
-               delay = "%{reply:Response-Delay:-1}"
-               relative = yes
-}
\ No newline at end of file
+       #
+       #  How long to delay request processing for.
+       #
+       delay = "%{reply:Response-Delay:-1}"
+
+       relative = yes
+}
index 4a05c1a4018179ae89d004edbdaf59219cba18d2..048462d56757f2def1fad79c05954e091aa1359d 100644 (file)
@@ -2,47 +2,48 @@
 #
 #  $Id$
 
-# Write a detailed log of all accounting records received.
+#
+#  Write a detailed log of all accounting records received.
 #
 detail {
-       #  Note that we do NOT use NAS-IP-Address here, as
-       #  that attribute MAY BE from the originating NAS, and
-       #  NOT from the proxy which actually sent us the
-       #  request.
        #
-       #  The following line creates a new detail file for
-       #  every radius client (by IP address or hostname).
-       #  In addition, a new detail file is created every
-       #  day, so that the detail file doesn't have to go
-       #  through a 'log rotation'
+       #  Note that we do NOT use NAS-IP-Address here, as that
+       #  attribute MAY BE from the originating NAS, and NOT from
+       #  the proxy which actually sent us the request.
+       #
+       #  The following line creates a new detail file for every
+       #  radius client (by IP address or hostname). In addition,
+       #  a new detail file is created every day, so that the
+       #  detail file doesn't have to go through a 'log rotation'
        #
-       #  If your detail files are large, you may also want
-       #  to add a ':%H' (see doc/configuration/variables.rst) to the end
-       #  of it, to create a new detail file every hour, e.g.:
+       #  If your detail files are large, you may also want to
+       #  add a ':%H' (see doc/configuration/variables.rst) to
+       #  the end of it, to create a new detail file every hour,
+       #  e.g.:
        #
-       #   ..../detail-%Y%m%d:%H
+       #      ..../detail-%Y%m%d:%H
        #
        #  This will create a new detail file for every hour.
        #
        #  If you are reading detail files via the "listen" section
        #  (e.g. as in raddb/sites-available/robust-proxy-accounting),
-       #  you MUST use a unique directory for each combination of a
-       #  detail file writer, and reader.  That is, there can only
-       #  be ONE "listen" section reading detail files from a
-       #  particular directory.
+       #  you MUST use a unique directory for each combination of
+       #  a detail file writer, and reader. That is, there can
+       #  only be ONE "listen" section reading detail files from
+       #  particular directory.
        #
        filename = ${radacctdir}/%{%{Packet-Src-IP-Address}:-%{Packet-Src-IPv6-Address}}/detail-%Y%m%d
 
        #
-       #  If you are using radrelay, delete the above line for "file",
-       #  and use this one instead:
+       #  If you are using radrelay, delete the above line for
+       #  "file", and use this one instead:
        #
 #      filename = ${radacctdir}/detail
 
        #
-       #  Most file systems can handly nearly the full range of UTF-8
-       #  characters.  Ones that can deal with a limited range should
-       #  set this to "yes".
+       #  Most file systems can handly nearly the full range of
+       #  UTF-8 characters. Ones that can deal with a limited
+       #  range should set this to "yes".
        #
        escape_filenames = no
 
@@ -50,25 +51,28 @@ detail {
        #  The Unix-style permissions on the 'detail' file.
        #
        #  The detail file often contains secret or private
-       #  information about users.  So by keeping the file
+       #  information about users. So by keeping the file
        #  permissions restrictive, we can prevent unwanted
        #  people from seeing that information.
+       #
        permissions = 0600
 
-       # The Unix group of the log file.
        #
-       # The user that the server runs as must be in the specified
-       # system group otherwise this will fail to work.
+       #  The Unix group of the log file.
+       #
+       #  The user that the server runs as must be in the
+       #  specified system group otherwise this will fail
+       #  to work.
        #
 #      group = ${security.group}
 
        #
-       #  Every entry in the detail file has a header which
-       #  is a timestamp.  By default, we use the ctime
-       #  format (see "man ctime" for details).
+       #  Every entry in the detail file has a header which is a
+       #  timestamp.  By default, we use the ctime format (see
+       #  "man ctime" for details).
        #
-       #  The header can be customised by editing this
-       #  string.  See "doc/configuration/variables.rst" for a description
+       #  The header can be customised by editing this string.
+       #  See "doc/configuration/variables.rst" for a description
        #  of what can be put here.
        #
        header = "%t"
@@ -80,21 +84,20 @@ detail {
 #      locking = yes
 
        #
-       #  Log the Packet src/dst IP/port.  This is disabled by
+       #  Log the Packet src/dst IP/port. This is disabled by
        #  default, as that information isn't used by many people.
        #
 #      log_packet_header = yes
 
        #
-       # Certain attributes such as User-Password may be
-       # "sensitive", so they should not be printed in the
-       # detail file.  This section lists the attributes
-       # that should be suppressed.
+       #  Certain attributes such as User-Password may be
+       #  "sensitive", so they should not be printed in the
+       #  detail file. This section lists the attributes that
+       #  should be suppressed.
        #
-       # The attributes should be listed one to a line.
+       #  The attributes should be listed one to a line.
        #
-       #suppress {
-               # User-Password
-       #}
-
+#      suppress {
+#              User-Password
+#      }
 }
index 827cdf57e70dc2ff2252016194f4bb846eecead2..699b7bb64f570733bf3769916080038b696e1d10 100644 (file)
@@ -1,26 +1,29 @@
 # -*- text -*-
+#
+#  $Id$
+
 #
 #  Detail file writer, used in the following examples:
 #
-#      raddb/sites-available/robust-proxy-accounting
-#      raddb/sites-available/decoupled-accounting
+#      raddb/sites-available/robust-proxy-accounting
+#      raddb/sites-available/decoupled-accounting
 #
 #  Note that this module can write detail files that are read by
-#  only ONE "listen" section.  If you use BOTH of the examples
+#  only ONE "listen" section. If you use BOTH of the examples
 #  above, you will need to define TWO "detail" modules.
 #
 #  e.g. detail1.example.com && detail2.example.com
 #
 #
-#  We write *multiple* detail files here.  They will be processed by
-#  the detail "listen" section in the order that they were created.
-#  The directory containing these files should NOT be used for any
-#  other purposes.  i.e. It should have NO other files in it.
+#  We write *multiple* detail files here. They will be processed
+#  by the detail "listen" section in the order that they were
+#  created. The directory containing these files should NOT be
+#  used for any other purposes, i.e. it should have NO other
+#  files in it.
 #
-#  Writing multiple detail enables the server to process the pieces
-#  in smaller chunks.  This helps in certain catastrophic corner cases.
-#
-#  $Id$
+#  Writing multiple detail enables the server to process the
+#  pieces in smaller chunks. This helps in certain catastrophic
+#  corner cases.
 #
 detail detail.example.com {
        filename = ${radacctdir}/detail.example.com/detail-%Y%m%d:%H:%G
index b91cf7cb24744ee96e390aa4d7bd5f3ad4c0c0ee..1db7dfba3f3fadf71631be937bb27e7c068f2fb8 100644 (file)
@@ -4,37 +4,43 @@
 
 #
 #  More examples of doing detail logs.
+#
 
 #
-#  Many people want to log authentication requests.
-#  Rather than modifying the server core to print out more
-#  messages, we can use a different instance of the 'detail'
-#  module, to log the authentication requests to a file.
+#  Many people want to log authentication requests. Different
+#  instances of the 'detail' module can be used to log the
+#  authentication requests to one or more files.
+#
+#  You will also need to un-comment the 'auth_log' line in the
+#  'recv Access-Request' section of raddb/sites-enabled/default.
 #
-#  You will also need to un-comment the 'auth_log' line
-#  in the 'authorize' section, below.
+#  For full explanation of the configuration options, see
+#  the comments in raddb/mods-available/detail.
 #
 detail auth_log {
        filename = ${radacctdir}/%{%{Packet-Src-IP-Address}:-%{Packet-Src-IPv6-Address}}/auth-detail-%Y%m%d
 
        #
-       #  This MUST be 0600, otherwise anyone can read
-       #  the users passwords!
+       #  This should be 0600 to ensure private data in the
+       #  detail logs cannot be read by other users of the
+       #  system.
+       #
        permissions = 0600
 
-       # You may also strip out passwords completely
+       #
+       #  This will stop passwords being written to the log.
+       #
        suppress {
                User-Password
        }
 }
 
 #
-#  This module logs authentication reply packets sent
-#  to a NAS.  Both Access-Accept and Access-Reject packets
-#  are logged.
+#  This module logs authentication reply packets sent to a NAS.
+#  Both Access-Accept and Access-Reject packets are logged.
 #
-#  You will also need to un-comment the 'reply_log' line
-#  in the 'post-auth' section, below.
+#  You will also need to un-comment the 'reply_log' line in the
+#  'send Access-Accept' section of raddb/sites-enabled/default.
 #
 detail reply_log {
        filename = ${radacctdir}/%{%{Packet-Src-IP-Address}:-%{Packet-Src-IPv6-Address}}/reply-detail-%Y%m%d
@@ -45,28 +51,24 @@ detail reply_log {
 #
 #  This module logs packets proxied to a home server.
 #
-#  You will also need to un-comment the 'pre_proxy_log' line
-#  in the 'pre-proxy' section, below.
+#  You will need to call it before rlm_radius is used for
+#  proxying. See the example in raddb/sites-available/default.
 #
 detail pre_proxy_log {
        filename = ${radacctdir}/%{%{Packet-Src-IP-Address}:-%{Packet-Src-IPv6-Address}}/pre-proxy-detail-%Y%m%d
 
-       #
-       #  This MUST be 0600, otherwise anyone can read
-       #  the users passwords!
        permissions = 0600
 
-       # You may also strip out passwords completely
-       #suppress {
-               # User-Password
-       #}
+#      suppress {
+#              User-Password
+#      }
 }
 
 #
 #  This module logs response packets from a home server.
 #
-#  You will also need to un-comment the 'post_proxy_log' line
-#  in the 'post-proxy' section, below.
+#  You will need to call it after rlm_radius is used for proxying.
+#  See the example in raddb/sites-available/default.
 #
 detail post_proxy_log {
        filename = ${radacctdir}/%{%{Packet-Src-IP-Address}:-%{Packet-Src-IPv6-Address}}/post-proxy-detail-%Y%m%d
index 907d321516bc76134bacd09eada5ddb314824b2a..acad8470eb9c1b21d92f345a44cc42a78523e88a 100644 (file)
@@ -98,90 +98,118 @@ server default {
                }
        }
 
+
+
+######################################################################
+#
+#  Authentication and Authorization requests
 #
-#  Authorization.
+#
+#  The sections below are called when a RADIUS packet has been
+#  received.
+#
+#  recv Access-Request - for authorization and authentication
+#  recv Status-Server  - for checking the server is responding
+#
+######################################################################
+
+#
+#  This section is processed when the server receives an
+#  Access-Request authentication packet.
 #
 recv Access-Request {
        #
-       #  Take a User-Name, and perform some checks on it, for spaces and other
-       #  invalid characters.  If the User-Name appears invalid, reject the
-       #  request.
+       #  Take a User-Name, and perform some checks on it, for
+       #  spaces and other invalid characters. If the User-Name
+       #  appears invalid, reject the request.
        #
-       #  See policy.d/filter for the definition of the filter_username policy.
+       #  See policy.d/filter for the definition of the
+       #  filter_username policy.
        #
        filter_username
 
        #
-       #  Some broken equipment sends passwords with embedded zeros.
-       #  i.e. the debug output will show
+       #  Some broken equipment sends passwords with embedded
+       #  zeros, i.e. the debug output will show:
        #
-       #       User-Password = "password\000\000"
+       #      User-Password = "password\000\000"
        #
        #  This policy will fix it to just be "password".
        #
 #      filter_password
 
-       #  If you intend to use CUI and you require that the Operator-Name
-       #  be set for CUI generation and you want to generate CUI also
-       #  for your local clients then uncomment the operator-name
-       #  below and set the operator-name for your clients in clients.conf
+       #
+       #  If you intend to use CUI and you require that the
+       #  Operator-Name be set for CUI generation and you want to
+       #  generate CUI also for your local clients, then uncomment
+       #  operator-name below and set the operator-name for
+       #  your clients in clients.conf.
+       #
 #      operator-name
 
        #
-       #  If you want to generate CUI for some clients that do not
-       #  send proper CUI requests, then uncomment the
-       #  cui below and set "add_cui = yes" for these clients in clients.conf
+       #  If you want to generate CUI for some clients that do
+       #  not send proper CUI requests, then uncomment cui below
+       #  and set "add_cui = yes" for these clients in
+       #  clients.conf.
+       #
 #      cui
 
        #
-       #  If you want to have a log of authentication requests,
-       #  un-comment the following line.
+       #  Uncomment to have a log of authentication requests. See
+       #  raddb/mods-available/detail.log.
+       #
 #      auth_log
 
        #
        #  The chap module will set 'Auth-Type := CHAP' if we are
-       #  handling a CHAP request and Auth-Type has not already been set
+       #  handling a CHAP request and Auth-Type has not already
+       #  been set.
+       #
        chap
 
        #
        #  If the users are logging in with an MS-CHAP-Challenge
-       #  attribute for authentication, the mschap module will find
-       #  the MS-CHAP-Challenge attribute, and add 'Auth-Type := MS-CHAP'
-       #  to the request, which will cause the server to then use
-       #  the mschap module for authentication.
+       #  attribute for authentication, the mschap module will
+       #  add 'Auth-Type := MS-CHAP' to the request, which will
+       #  cause the server to then use the mschap module for
+       #  authentication.
+       #
        mschap
 
        #
        #  If you have a Cisco SIP server authenticating against
-       #  FreeRADIUS, the digest module will set 'Auth-Type := Digest'
-       #  if we are handling an HTTP Digest request and the Auth-Type
-       #  has not already been set.
+       #  FreeRADIUS, the digest module will set Auth-Type to
+       #  "Digest" if we are handling an HTTP Digest request and
+       #  the Auth-Type has not already been set.
+       #
        digest
 
        #
        #  The WiMAX specification says that the Calling-Station-Id
        #  is 6 octets of the MAC.  This definition conflicts with
-       #  RFC 3580, and all common RADIUS practices.  Un-commenting
+       #  RFC 3580, and all common RADIUS practices. Un-commenting
        #  the "wimax" module here means that it will fix the
        #  Calling-Station-Id attribute to the normal format as
-       #  specified in RFC 3580 Section 3.21
+       #  specified in RFC 3580 Section 3.21.
+       #
 #      wimax
 
        #
-       #  This module takes care of EAP-MD5, EAP-TLS, and EAP-LEAP
-       #  authentication.
+       #  This module takes care of all EAP authentication,
+       #  including EAP-MD5, EAP-TLS, PEAP and EAP-TTLS.
        #
        #  It also sets the EAP-Type attribute in the request
        #  attribute list to the EAP type from the packet.
        #
        #  The EAP module returns "ok" if it is not yet ready to
-       #  authenticate the user.  The configuration below checks for
-       #  that code, and stops processing the "authorize" section if
-       #  so.
+       #  authenticate the user. The configuration below checks
+       #  for that code, and stops processing the "authorize"
+       #  section if so.
        #
-       #  Any LDAP and/or SQL servers will not be queried for the
-       #  initial set of packets that go back and forth to set up
-       #  TTLS or PEAP.
+       #  Any LDAP and/or SQL servers will not be queried during
+       #  the initial set of packets that go back and forth to
+       #  set up EAP-TTLS or PEAP.
        #
        eap {
                ok = return
@@ -189,106 +217,139 @@ recv Access-Request {
 
        #
        #  Pull crypt'd passwords from /etc/passwd or /etc/shadow,
-       #  using the system API's to get the password.  If you want
-       #  to read /etc/passwd or /etc/shadow directly, see the
-       #  mods-available/passwd module.
+       #  using the system API's to get the password. See
+       #  raddb/mods-available/unix for more details.
+       #
+       #  If you want to read the /etc/passwd or /etc/shadow
+       #  files directly, see the passwd module in
+       #  raddb/mods-available/passwd.
        #
 #      unix
 
        #
-       #  Read the 'users' file.  In v3, this is located in
-       #  raddb/mods-config/files/authorize
+       #  Read the 'users' file. Since v3, this is located in
+       #  raddb/mods-config/files/authorize.
+       #
        files
 
        #
-       #  Look in an SQL database.  The schema of the database
-       #  is meant to mirror the "users" file.
+       #  Look in an SQL database. The schema of the database is
+       #  meant to mirror the "users" file.
+       #
+       #  See "Authorization Queries" in raddb/mods-available/sql.
        #
-       #  See "Authorization Queries" in mods-available/sql
        -sql
 
        #
        #  If you are using /etc/smbpasswd, and are also doing
        #  mschap authentication, the un-comment this line, and
-       #  configure the 'smbpasswd' module.
+       #  see the configuration in raddb/mods-available/smbpasswd.
+       #
 #      smbpasswd
 
        #
-       #  The ldap module reads passwords from the LDAP database.
+       #  The ldap module reads passwords from an LDAP database.
+       #
        -ldap
 
        #
-       #  Enforce daily limits on time spent logged in.
+       #  Enforce daily limits on time spent logged in. This uses
+       #  the 'counter' module.
+       #
 #      daily
 
+       #
+       #  See if the account has expired: check the time in the
+       #  Expiration attribute and reject if we are past it.
+       #  If the account has not expired, set Session-Timeout.
        #
        expiration
+
+       #
+       #  Look at the Login-Time attribute and reject if the user
+       #  is not allowed access at the present time. Otherwise,
+       #  set Session-Timeout to the end of the permitted time span.
+       #
        logintime
 
        #
        #  If no other module has claimed responsibility for
-       #  authentication, then try to use PAP.  This allows the
-       #  other modules listed above to add a "known good" password
-       #  to the request, and to do nothing else.  The PAP module
-       #  will then see that password, and use it to do PAP
-       #  authentication.
+       #  authentication, then try to use PAP. This allows the
+       #  other modules listed above to add a "known good"
+       #  password to the request, and to do nothing else. The
+       #  PAP module will then see that password, and use it to
+       #  do PAP authentication.
        #
-       #  This module should be listed last, so that the other modules
-       #  get a chance to set Auth-Type for themselves.
+       #  This module should be listed last, so that the other
+       #  modules get a chance to set Auth-Type for themselves.
        #
        pap
 }
 
+
+#
+#  This section is processed when the server receives a
+#  Status-Server packet.
+#
 recv Status-Server {
+       #
+       #  We are still here and responding.
+       #
        ok
 }
 
-#  Authentication.
+
+
+######################################################################
 #
+#  Authentication
 #
-#  This section lists which modules are available for authentication.
-#  Note that it does NOT mean 'try each module in order'.  It means
-#  that a module from the 'authorize' section adds a configuration
-#  attribute 'Auth-Type := FOO'.  That authentication type is then
-#  used to pick the appropriate module from the list below.
 #
-
-#  In general, you SHOULD NOT set the Auth-Type attribute.  The server
-#  will figure it out on its own, and will do the right thing.  The
-#  most common side effect of erroneously setting the Auth-Type
-#  attribute is that one authentication method will work, but the
-#  others will not.
+#  The sections below are called based on the value of the
+#  Auth-Type attribute, which should have been set by "recv
+#  Access-Request", above.
+#
+#  Since version 4, proxying also happens in this section.
+#
+#  For authentication, you should generally NOT set the Auth-Type
+#  attribute. The server will figure it out on its own, and will
+#  do the right thing. The most common side effect of erroneously
+#  setting the Auth-Type attribute is that one authentication
+#  method will work, but the others will not.
 #
-#  The common reasons to set the Auth-Type attribute by hand
-#  is to either forcibly reject the user (Auth-Type := Reject),
-#  or to or forcibly accept the user (Auth-Type := Accept).
+#  The common reasons to set the Auth-Type attribute by hand are
+#  to forcibly reject the user (Auth-Type := Reject), to or
+#  forcibly accept the user (Auth-Type := Accept), or for
+#  proxying.
 #
 #  Note that Auth-Type := Accept will NOT work with EAP.
 #
-#  Please do not put "unlang" configurations into the "authenticate"
-#  section.  Put them in the "post-auth" section instead.  That's what
-#  the post-auth section is for.
+#  unlang configuration should generally go in the "send" sections
+#  below, after authentication has completed, not here.
 #
+######################################################################
 
 #
-#  PAP authentication, when a back-end database listed
-#  in the 'authorize' section supplies a password.  The
-#  password can be clear-text, or encrypted.
+#  PAP authentication, for when a back-end database listed in the
+#  "recv Access-Request" section supplies a password. The password
+#  can be clear-text, or encrypted.
+#
 authenticate pap {
        pap
 }
 
 #
-#  Most people want CHAP authentication
-#  A back-end database listed in the 'authorize' section
-#  MUST supply a CLEAR TEXT password.  Encrypted passwords
-#  won't work.
+#  For users that are using CHAP authentication. A back-end
+#  database listed in the "recv Access-Request" section MUST
+#  supply a CLEAR TEXT password. Encrypted passwords won't work.
+#
 authenticate chap {
        chap
 }
 
 #
-#  MSCHAP authentication.
+#  Handle MS-CHAP authentication.
+#
 authenticate mschap {
        mschap
 }
@@ -296,54 +357,70 @@ authenticate mschap {
 #
 #  If you have a Cisco SIP server authenticating against
 #  FreeRADIUS, the following line, and the 'digest' line in
-#  the 'authorize' section will be required.
+#  the "recv Access-Request" section will be required.
+#
 authenticate digest {
        digest
 }
 
 #
-#  Pluggable Authentication Modules.
+#  Authenticate with PAM (Pluggable Authentication Modules).
+#
 authenticate pam {
        pam
 }
 
-#  Uncomment it if you want to use ldap for authentication
 #
-#  Note that this means "check plain-text password against
-#  the ldap database", which means that EAP won't work,
-#  as it does not supply a plain-text password.
+#  Use this if you want to use LDAP for authentication.
+#
+#  Note that this means "check plain-text password by trying to
+#  bind to the LDAP directory". This means that EAP won't work, as
+#  it does not supply a plain-text password.
 #
-#  We do NOT recommend using this.  LDAP servers are databases.
-#  They are NOT authentication servers.  FreeRADIUS is an
-#  authentication server, and knows what to do with authentication.
-#  LDAP servers do not.
+#  We do NOT recommend using this. LDAP servers are databases, not
+#  authentication servers.
 #
 authenticate ldap {
        -ldap
 }
 
 #
-#  Allow EAP authentication, and remove all attributes
-#  from Access-Challenge
+#  Allow EAP authentication, and remove all attributes from
+#  Access-Challenge.
 #
 authenticate eap {
        eap
 }
 
+
+
+######################################################################
+#
+#  Authentication responses
+#
+######################################################################
+
+#
+#  This section is called when sending an Access-Challenge
+#  response. Filter out any attributes that should not be in the
+#  packet.
+#
 send Access-Challenge {
        attr_filter.access_challenge.post-auth
        handled
 }
 
-
-#  Post-Authentication
-#  Once we KNOW that the user has been authenticated, there are
-#  additional steps we can take.
+#
+#  Post-Authentication, Access-Accept
+#
+#  Once we KNOW that the user has been authenticated successfully,
+#  there are additional steps we can take.
+#
 send Access-Accept {
        #
-       #  If you need to have a State attribute, you can
-       #  add it here.  e.g. for later CoA-Request with
-       #  State, and Service-Type = Authorize-Only.
+       #  If you need to have a State attribute, you can add it
+       #  here. e.g. for later CoA-Request with State, and
+       #  Service-Type = Authorize-Only.
        #
 #      if (!&reply:State) {
 #              update reply {
@@ -352,253 +429,329 @@ send Access-Accept {
 #      }
 
        #
-       #  For EAP-TTLS and PEAP, add the cached attributes to the reply.
-       #  The "session-state" attributes are automatically cached when
-       #  an Access-Challenge is sent, and automatically retrieved
+       #  For EAP-TTLS and PEAP, add any cached attributes to the
+       #  reply. The "session-state" attributes are automatically
+       #  cached when an Access-Challenge is sent, and retrieved
        #  when an Access-Request is received.
        #
-       #  The session-state attributes are automatically deleted after
-       #  an Access-Reject or Access-Accept is sent.
+       #  The session-state attributes are deleted after an
+       #  Access-Reject or Access-Accept has been sent.
        #
        update {
                &reply: += &session-state:
        }
 
+       #
        #  Get an address from the IP Pool.
+       #
 #      main_pool
 
 
-       #  Create the CUI value and add the attribute to Access-Accept.
-       #  Uncomment the line below if *returning* the CUI.
+       #
+       #  Create the CUI value and add the attribute to
+       #  Access-Accept. Uncomment the line below if
+       #  *returning* the CUI to the NAS.
+       #
 #      cui
 
        #
        #  If you want to have a log of authentication replies,
-       #  un-comment the following line, and enable the
-       #  'detail reply_log' module.
+       #  un-comment the following line. This is defined in
+       #  raddb/mods-available/detail.log.
+       #
 #      reply_log
 
        #
        #  After authenticating the user, do another SQL query.
        #
-       #  See "Authentication Logging Queries" in mods-available/sql
+       #  See "Authentication Logging Queries" in
+       #  raddb/mods-available/sql.
+       #
        -sql
 
        #
-       #  Instead of sending the query to the SQL server,
-       #  write it into a log file.
+       #  Instead of sending the query to the SQL server in
+       #  real-time, write it into a log file to be picked up and
+       #  sent to the database later.
        #
 #      sql_log
 
        #
-       #  Un-comment the following if you want to modify the user's object
-       #  in LDAP after a successful login.
+       #  Un-comment the following if you want to modify the
+       #  user's object in LDAP after a successful login.
        #
 #      ldap
 
        #
-       #  Calculate the various WiMAX keys.  In order for this to work,
-       #  you will need to define the WiMAX NAI, usually via
+       #  Calculate the various WiMAX keys. In order for this to
+       #  work, you will need to define the WiMAX NAI, usually
+       #  via:
        #
-       #       update request {
-       #              WiMAX-MN-NAI = "%{User-Name}"
-       #       }
+       #      update request {
+       #          WiMAX-MN-NAI = "%{User-Name}"
+       #      }
        #
-       #  If you want various keys to be calculated, you will need to
-       #  update the reply with "template" values.  The module will see
-       #  this, and replace the template values with the correct ones
-       #  taken from the cryptographic calculations.  e.g.
+       #  If you want various keys to be calculated, you will
+       #  need to update the reply with "template" values. The
+       #  module will see this, and replace the template values
+       #  with the correct ones taken from the cryptographic
+       #  calculations, e.g.
        #
-       #       update reply {
-       #               WiMAX-FA-RK-Key = 0x00
-       #               WiMAX-MSK = "%{EAP-MSK}"
-       #       }
+       #      update reply {
+       #          WiMAX-FA-RK-Key = 0x00
+       #          WiMAX-MSK = "%{EAP-MSK}"
+       #      }
        #
-       #  You may want to delete the MS-MPPE-*-Keys from the reply,
-       #  as some WiMAX clients behave badly when those attributes
-       #  are included.  See "raddb/modules/wimax", configuration
-       #  entry "delete_mppe_keys" for more information.
+       #  You may want to delete the MS-MPPE-*-Keys from the
+       #  reply, as some WiMAX clients behave badly when those
+       #  attributes are included. See the configuration entry
+       #  "delete_mppe_keys" in raddb/mods-available/wimax for
+       #  more information.
        #
 #      wimax
 
-
-       #  If there is a client certificate (EAP-TLS, sometimes PEAP
-       #  and TTLS), then some attributes are filled out after the
-       #  certificate verification has been performed.  These fields
-       #  MAY be available during the authentication, or they may be
-       #  available only in the "post-auth" section.
        #
-       #  The first set of attributes contains information about the
-       #  issuing certificate which is being used.  The second
+       #  If there is a client certificate (EAP-TLS, and very
+       #  occasionally PEAP and EAP-TTLS), then some attributes
+       #  are filled out after the certificate verification has
+       #  been performed. These fields MAY be available during
+       #  the authentication, or they may be available only in
+       #  the appropriate "send" section.
+       #
+       #  The first set of attributes contains information about
+       #  the issuing certificate which is being used. The second
        #  contains information about the client certificate (if
        #  available).
-#
+       #
 #      update reply {
-#             Reply-Message += "%{session-state:TLS-Cert-Serial}"
-#             Reply-Message += "%{session-state:TLS-Cert-Expiration}"
-#             Reply-Message += "%{session-state:TLS-Cert-Subject}"
-#             Reply-Message += "%{session-state:TLS-Cert-Issuer}"
-#             Reply-Message += "%{session-state:TLS-Cert-Common-Name}"
-#             Reply-Message += "%{session-state:TLS-Cert-Subject-Alt-Name-Email}"
-#
-#             Reply-Message += "%{session-state:TLS-Client-Cert-Serial}"
-#             Reply-Message += "%{session-state:TLS-Client-Cert-Expiration}"
-#             Reply-Message += "%{session-state:TLS-Client-Cert-Subject}"
-#             Reply-Message += "%{session-state:TLS-Client-Cert-Issuer}"
-#             Reply-Message += "%{session-state:TLS-Client-Cert-Common-Name}"
-#             Reply-Message += "%{session-state:TLS-Client-Cert-Subject-Alt-Name-Email}"
+#              Reply-Message += "%{session-state:TLS-Cert-Serial}"
+#              Reply-Message += "%{session-state:TLS-Cert-Expiration}"
+#              Reply-Message += "%{session-state:TLS-Cert-Subject}"
+#              Reply-Message += "%{session-state:TLS-Cert-Issuer}"
+#              Reply-Message += "%{session-state:TLS-Cert-Common-Name}"
+#              Reply-Message += "%{session-state:TLS-Cert-Subject-Alt-Name-Email}"
+#
+#              Reply-Message += "%{session-state:TLS-Client-Cert-Serial}"
+#              Reply-Message += "%{session-state:TLS-Client-Cert-Expiration}"
+#              Reply-Message += "%{session-state:TLS-Client-Cert-Subject}"
+#              Reply-Message += "%{session-state:TLS-Client-Cert-Issuer}"
+#              Reply-Message += "%{session-state:TLS-Client-Cert-Common-Name}"
+#              Reply-Message += "%{session-state:TLS-Client-Cert-Subject-Alt-Name-Email}"
 #      }
 
-       #  Insert class attribute (with unique value) into response,
-       #  aids matching auth and acct records, and protects against duplicate
-       #  Acct-Session-Id. Note: Only works if the NAS has implemented
-       #  RFC 2865 behaviour for the class attribute, AND if the NAS
-       #  supports long Class attributes.  Many older or cheap NASes
-       #  only support 16-octet Class attributes.
+       #
+       #  Insert Class attribute (with a unique value) into the
+       #  response, which aids matching auth and acct records and
+       #  protects against duplicate Acct-Session-Id.
+       #
+       #  Note: This only works if the NAS has implemented RFC
+       #  2865 behaviour for the Class attribute, AND if the NAS
+       #  supports long Class attributes. Many older or cheap
+       #  NASes only support 16-octet Class attributes.
+       #
 #      insert_acct_class
 
-       #  MacSEC requires the use of EAP-Key-Name.  However, we don't
-       #  want to send it for all EAP sessions.  Therefore, the EAP
-       #  modules put required data into the EAP-Session-Id attribute.
-       #  This attribute is never put into a request or reply packet.
        #
-       #  Uncomment the next few lines to copy the required data into
-       #  the EAP-Key-Name attribute
+       #  MacSEC requires the use of EAP-Key-Name. However, we
+       #  don't want to send it for all EAP sessions. Therefore,
+       #  the EAP modules put required data into the
+       #  EAP-Session-Id attribute. This attribute is never put
+       #  into a request or reply packet.
+       #
+       #  Uncomment the next few lines to copy the required data
+       #  into the EAP-Key-Name attribute.
+       #
 #      if (&reply:EAP-Session-Id) {
 #              update reply {
 #                      EAP-Key-Name := &reply:EAP-Session-Id
 #              }
 #      }
 
-       #  Remove reply message if the response contains an EAP-Message
+       #
+       #  Remove Reply-Message if the response contains an
+       #  EAP-Message.
+       #
        remove_reply_message_if_eap
 }
 
 #
-#  Access-Reject packets are sent through the REJECT sub-section of the
-#  post-auth section.
+#  This section is called before an Access-Reject packet is sent.
 #
 #  Add the ldap module name (or instance) if you have set
-#  'edir_account_policy_check = yes' in the ldap module configuration
+#  'edir_account_policy_check = yes' in the ldap module
+#  configuration.
 #
 #  The "session-state" attributes are not available here.
 #
 send Access-Reject {
-       # log failed authentications in SQL, too.
+       #
+       # Log failed authentications in SQL, too.
+       #
        -sql
+
+       #
+       # Filter out attributes that should not be in
+       # Access-Reject packets.
+       #
        attr_filter.access_reject
 
-       # Insert EAP-Failure message if the request was
-       # rejected by policy instead of because of an
-       # authentication failure
+       #
+       # Insert EAP-Failure message if the request was rejected
+       # by policy rather than because of an authentication
+       # failure.
+       #
        eap
 
-       #  Remove reply message if the response contains an EAP-Message
+       #
+       #  Remove Reply-Message if the response contains an
+       #  EAP-Message attribute.
+       #
        remove_reply_message_if_eap
 }
 
 
+
+######################################################################
 #
-#  Pre-accounting.  Decide which accounting type to use.
+#  Accounting
+#
+#
+#  This section deals with receiving Accounting requests and
+#  sending Accounting responses.
+#
+######################################################################
+
+#
+#  An Accounting-Request packet has been received. Decide which
+#  accounting type to use.
 #
 recv Accounting-Request {
        #
-       #  Merge Acct-[Input|Output]-Gigawords and Acct-[Input-Output]-Octets
-       #  into a single 64bit counter Acct-[Input|Output]-Octets64.
+       #  Merge Acct-[Input|Output]-Gigawords and
+       #  Acct-[Input-Output]-Octets into a single 64-bit
+       #  counter, Acct-[Input|Output]-Octets64.
        #
 #      acct_counters64
 
        #
-       #  Session start times are *implied* in RADIUS.
-       #  The NAS never sends a "start time".  Instead, it sends
-       #  a start packet, *possibly* with an Acct-Delay-Time.
-       #  The server is supposed to conclude that the start time
-       #  was "Acct-Delay-Time" seconds in the past.
+       #  Session start times are *implied* in RADIUS. The NAS
+       #  never sends a "start time". Instead, it sends a start
+       #  packet, *possibly* with an Acct-Delay-Time. The server
+       #  is supposed to conclude that the start time was
+       #  "Acct-Delay-Time" seconds in the past.
        #
-       #  The code below creates an explicit start time, which can
-       #  then be used in other modules.  It will be *mostly* correct.
-       #  Any errors are due to the 1-second resolution of RADIUS,
-       #  and the possibility that the time on the NAS may be off.
+       #  The unlang below creates an explicit start time, which
+       #  can then be used in other modules. It will be *mostly*
+       #  correct. Any errors are due to the 1-second resolution
+       #  of RADIUS, and the possibility that the time on the NAS
+       #  may be off.
        #
        #  The start time is: NOW - delay - session_length
        #
-
 #      update request {
-#              &FreeRADIUS-Acct-Session-Start-Time = "%{expr: %l - %{%{Acct-Session-Time}:-0} - %{%{Acct-Delay-Time}:-0}}"
+#              &FreeRADIUS-Acct-Session-Start-Time = "%{expr: %l - %{%{Acct-Session-Time}:-0} - %{%{Acct-Delay-Time}:-0}}"
 #      }
 
-
        #
        #  Ensure that we have a semi-unique identifier for every
-       #  request, and many NAS boxes are broken.
+       #  request, as many NAS boxes are broken.
+       #
        acct_unique
 
        #
-       #  Read the 'acct_users' file
+       #  Read the 'acct_users' file.
+       #
        files
 }
 
 #
-#  Accounting.  Log the accounting data.
+#  Send Accounting-Response.
+#
+#  Log the accounting data before replying. If logging fails then
+#  the reply will not be sent, which means the NAS will send the
+#  request again.
 #
 send Accounting-Response {
-       #  Update accounting packet by adding the CUI attribute
-       #  recorded from the corresponding Access-Accept
-       #  use it only if your NAS boxes do not support CUI themselves
+       #
+       #  Add the CUI attribute from the corresponding
+       #  Access-Accept to the Accouning-Response.
+       #
+       #  Use it only if your NAS boxes do not support CUI
+       #  themselves.
+       #
 #      cui
+
+       #
+       #  Create a 'detail'ed log of the packets. Note that
+       #  accounting requests which are proxied are also logged
+       #  in the detail file.
        #
-       #  Create a 'detail'ed log of the packets.
-       #  Note that accounting requests which are proxied
-       #  are also logged in the detail file.
        detail
+
+       #
+       #  Update counters for daily usage calculations.
+       #
 #      daily
 
-       #  Update the wtmp file
+       #
+       #  Update the wtmp file.
        #
        #  If you don't use "radlast", you can delete this line.
+       #
        unix
 
        #
        #  For Simultaneous-Use tracking.
        #
-       #  Due to packet losses in the network, the data here
-       #  may be incorrect.  There is little we can do about it.
+       #  Due to packet losses in the network, the data here may
+       #  be incorrect. There is little we can do about it.
+       #
 #      radutmp
 #      sradutmp
 
-       #  Return an address to the IP Pool when we see a stop record.
+       #
+       #  Return an address to the IP Pool when we see a stop
+       #  record.
+       #
 #      main_pool
 
        #
        #  Log traffic to an SQL database.
        #
-       #  See "Accounting queries" in mods-available/sql
+       #  See "Accounting Queries" in raddb/mods-available/sql.
+       #
        -sql
 
        #
        #  If you receive stop packets with zero session length,
-       #  they will NOT be logged in the database.  The SQL module
-       #  will print a message (only in debugging mode), and will
-       #  return "noop".
+       #  they will NOT be logged in the database. The SQL
+       #  module will print a message (only in debugging mode),
+       #  and will return "noop".
        #
-       #  You can ignore these packets by uncommenting the following
-       #  three lines.  Otherwise, the server will not respond to the
-       #  accounting request, and the NAS will retransmit.
+       #  You can ignore these packets by uncommenting the
+       #  following three lines. Otherwise, the server will not
+       #  respond to the accounting request, and the NAS will
+       #  retransmit.
        #
 #      if (noop) {
 #              ok
 #      }
 
        #
-       #  Instead of sending the query to the SQL server,
-       #  write it into a log file.
+       #  Instead of sending the query to the SQL server in
+       #  real-time, write it into a log file to be picked up and
+       #  sent to the database later.
        #
 #      sql_log
 
-       #  Cisco VoIP specific bulk accounting
+       #
+       #  Cisco VoIP specific bulk accounting.
+       #
 #      pgsql-voip
 
+       #
        #  Filter attributes from the accounting response.
+       #
        attr_filter.accounting_response
 }
 }