note recent changes

[freeradius.git] / raddb / proxy.conf

# -*- text -*-
##
## proxy.conf -- proxy radius and realm configuration directives
##
##      $Id$

#######################################################################
#
#  Proxy server configuration
#
#  This entry controls the servers behaviour towards ALL other servers
#  to which it sends proxy requests.
#
proxy server {
        #
        #  Note that as of 2.0, the "synchronous", "retry_delay",
        #  "retry_count", and "dead_time" have all been deprecated.
        #  For backwards compatibility, they are are still accepted
        #  by the server, but they ONLY apply to the old-style realm
        #  configuration.  i.e. realms with "authhost" and/or "accthost"
        #  entries.
        #
        #  i.e. "retry_delay" and "retry_count" have been replaced
        #  with per-home-server configuration.  See the "home_server"
        #  example below for details.
        #
        #  i.e. "dead_time" has been replaced with a per-home-server
        #  "revive_interval".  We strongly recommend that this not
        #  be used, however.  The new method is much better.

        #
        #  In 2.0, the server is always "synchronous", and setting
        #  "synchronous = no" is impossible.  This simplifies the
        #  server and increases the stability of the network.
        #  However, it means that the server (i.e. proxy) NEVER
        #  originates packets.  It proxies packets ONLY when it receives
        #  a packet or a re-transmission from the NAS.  If the NAS never
        #  re-transmits, the proxy never re-transmits, either.  This can
        #  affect fail-over, where a packet does *not* fail over to a
        #  second home server.. because the NAS never retransmits the
        #  packet.
        #
        #  If you need to set "synchronous = no", please send a
        #  message to the list <freeradius-users@lists.freeradius.org>
        #  explaining why this feature is vital for your network.

        #
        #  If a realm exists, but there are no live home servers for
        #  it, we can fall back to using the "DEFAULT" realm.  This is
        #  most useful for accounting, where the server can proxy
        #  accounting requests to home servers, but if they're down,
        #  use a DEFAULT realm that is LOCAL (i.e. accthost = LOCAL),
        #  and then store the packets in the "detail" file.  That data
        #  can be later proxied to the home servers by radrelay, when
        #  those home servers come back up again.       

        #  Setting this to "yes" may have issues for authentication.
        #  i.e. If you are proxying for two different ISP's, and then
        #  act as a general dial-up for Gric.  If one of the first two
        #  ISP's has their RADIUS server go down, you do NOT want to
        #  proxy those requests to GRIC.  Instead, you probably want
        #  to just drop the requests on the floor.  In that case, set
        #  this value to 'no'.
        #
        #  allowed values: {yes, no}
        #
        default_fallback = no

}

#######################################################################
#
#  Configuration for the proxy realms.
#
#  As of 2.0. the old-style "realms" file is deprecated, and is not
#  used by FreeRADIUS.
#
#  As of 2.0, the "realm" configuration has changed.  Instead of
#  specifying "authhost" and "accthost" in a realm section, the home
#  servers are specified seperately in a "home_server" section.  For
#  backwards compatibility, you can still use the "authhost" and
#  "accthost" directives.  If you only have one home server for a
#  realm, it is easier to use the old-style configuration.
#
#  However, if you have multiple servers for a realm, we STRONGLY
#  suggest moving to the new-style configuration.
#
#
#  Load-balancing and failover between home servers is handled via
#  a "home_server_pool" section.
#
#  Finally, The "realm" section defines the realm, some options, and
#  indicates which server pool should be used for the realm.
#
#  This change means that simple configurations now require multiple
#  sections to define a realm.  However, complex configurations
#  are much simpler than before, as multiple realms can share the same
#  server pool.
#
#  That is, realms point to server pools, and server pools point to
#  home servers.  Multiple realms can point to one server pool.  One
#  server pool can point to multiple home servers.  Each home server
#  can appear in one or more pools.
#

######################################################################
#
#  This section defines a "Home Server" which is another RADIUS
#  server that gets sent proxied requests.  In earlier versions
#  of FreeRADIUS, home servers were defined in "realm" sections,
#  which was awkward.  In 2.0, they have been made independent
#  from realms, which is better for a number of reasons.
#
home_server localhost {
        #
        #  Home servers can be sent Access-Request packets
        #  or Accounting-Request packets.
        #
        #  Allowed values are:
        #       auth      - Handles Access-Request packets
        #       acct      - Handles Accounting-Request packets
        #       auth+acct - Handles Access-Request packets at "port",
        #                   and Accounting-Request packets at "port + 1"
        #       coa       - Handles CoA-Request and Disconnect-Request packets.
        #                   See also raddb/sites-available/originate-coa
        type = auth

        #
        #  Configure ONE OF the following entries:
        #
        #       IPv4 address
        #
        ipaddr = 127.0.0.1

        #       OR IPv6 address
        # ipv6addr = ::1

        #       OR virtual server       
        # virtual_server = foo

        #       Note that while both ipaddr and ipv6addr will accept
        #       both addresses and host names, we do NOT recommend
        #       using host names.  When you specify a host name, the
        #       server has to do a DNS lookup to find the IP address
        #       of the home server.  If the DNS server is slow or
        #       unresponsive, it means that FreeRADIUS will NOT be
        #       able to determine the address, and will therefore NOT
        #       start.
        #
        #       Also, the mapping of host name to address is done ONCE
        #       when the server starts.  If DNS is later updated to
        #       change the address, FreeRADIUS will NOT discover that
        #       until after a re-start, or a HUP.
        #
        #       If you specify a virtual_server here, then requests
        #       will be proxied internally to that virtual server.
        #       These requests CANNOT be proxied again, however.  The
        #       intent is to have the local server handle packets
        #       when all home servers are dead.
        #
        #       Requests proxied to a virtual server will be passed
        #       through the pre-proxy and post-proxy sections, just
        #       like any other request.  See also the sample "realm"
        #       configuration, below.
        #
        #       None of the rest of the home_server configuration is used
        #       for the "virtual_server" configuration.

        #
        #  The port to which packets are sent.
        #
        #  Usually 1812 for type "auth", and  1813 for type "acct".
        #  Older servers may use 1645 and 1646.
        #  Use 3799 for type "coa"
        #
        port = 1812

        #
        #  The shared secret use to "encrypt" and "sign" packets between
        #  FreeRADIUS and the home server.
        #
        #  The secret can be any string, up to 8k characters in length.
        #
        #  Control codes can be entered vi octal encoding,
        #       e.g. "\101\102" == "AB"
        #  Quotation marks can be entered by escaping them,
        #       e.g. "foo\"bar"
        #  Spaces or other "special" characters can be entered
        #  by putting quotes around the string.
        #       e.g. "foo bar"
        #            "foo;bar"
        #
        secret = testing123

        ############################################################
        #
        #  The rest of the configuration items listed here are optional,
        #  and do not have to appear in every home server definition.
        #
        ############################################################

        #
        #  You can optionally specify the source IP address used when
        #  proxying requests to this home server.  When the src_ipaddr
        #  it set, the server will automatically create a proxy
        #  listener for that IP address.
        #
        #  If you specify this field for one home server, you will
        #  likely need to specify it for ALL home servers.
        #
        #  If you don't care about the source IP address, leave this
        #  entry commented.
        #
#       src_ipaddr = 127.0.0.1

        #  RFC 5080 suggests that all clients SHOULD include it in an
        #  Access-Request.  The configuration item below tells the
        #  proxying server (i.e. this one) whether or not the home
        #  server requires a Message-Authenticator attribute.  If it
        #  is required (value set to "yes"), then all Access-Request
        #  packets sent to that home server will have a
        #  Message-Authenticator attribute.
        #
        #  We STRONGLY recommend that this flag be set to "yes"
        #  for ALL home servers.  Doing so will have no performance
        #  impact on the proxy or on the home servers.  It will,
        #  however, allow administrators to detect problems earlier.
        #
        #  allowed values: yes, no
        require_message_authenticator = yes

        #
        #  If the home server does not respond to a request within
        #  this time, this server will initiate "zombie_period".
        #
        #  The response window is large because responses MAY be slow,
        #  especially when proxying across the Internet.
        #
        #  Useful range of values: 5 to 60
        response_window = 20

        #
        #  If you want the old behavior of the server rejecting
        #  proxied requests after "response_window" timeout, set
        #  the following configuration item to "yes".
        #
        #  This configuration WILL be removed in a future release
        #  If you believe you need it, email the freeradius-users
        #  list, and explain why it should stay in the server.
        #
#       no_response_fail = no

        #
        #  If the home server does not respond to ANY packets during
        #  the "zombie period", it will be considered to be dead.
        #
        #  A home server that is marked "zombie" will be used for
        #  proxying as a low priority.  If there are live servers,
        #  they will always be preferred to a zombie.  Requests will
        #  be proxied to a zombie server ONLY when there are no
        #  live servers.
        #
        #  Any request that is proxied to a home server will continue
        #  to be sent to that home server until the home server is
        #  marked dead.  At that point, it will fail over to another
        #  server, if a live server is available.  If none is available,
        #  then the "post-proxy-type fail" handler will be called.
        #
        #  If "status_check" below is something other than "none", then
        #  the server will start sending status checks at the start of
        #  the zombie period.  It will continue sending status checks
        #  until the home server is marked "alive".
        #
        #  Useful range of values: 20 to 120
        zombie_period = 40

        ############################################################
        #
        #  As of 2.0, FreeRADIUS supports RADIUS layer "status
        #  checks".  These are used by a proxy server to see if a home
        #  server is alive.
        #
        #  These status packets are sent ONLY if the proxying server
        #  believes that the home server is dead.  They are NOT sent
        #  if the proxying server believes that the home server is
        #  alive.  They are NOT sent if the proxying server is not
        #  proxying packets.
        #
        #  If the home server responds to the status check packet,
        #  then it is marked alive again, and is returned to use.
        #
        ############################################################

        #
        #  Some home servers do not support status checks via the
        #  Status-Server packet.  Others may not have a "test" user
        #  configured that can be used to query the server, to see if
        #  it is alive.  For those servers, we have NO WAY of knowing
        #  when it becomes alive again.  Therefore, after the server
        #  has been marked dead, we wait a period of time, and mark
        #  it alive again, in the hope that it has come back to
        #  life.
        #
        #  If it has NOT come back to life, then FreeRADIUS will wait
        #  for "zombie_period" before marking it dead again.  During
        #  the "zombie_period", ALL AUTHENTICATIONS WILL FAIL, because
        #  the home server is still dead.  There is NOTHING that can
        #  be done about this, other than to enable the status checks,
        #  as documented below.
        #
        #  e.g. if "zombie_period" is 40 seconds, and "revive_interval"
        #  is 300 seconds, the for 40 seconds out of every 340, or about
        #  10% of the time, all authentications will fail.
        #
        #  If the "zombie_period" and "revive_interval" configurations
        #  are set smaller, than it is possible for up to 50% of
        #  authentications to fail.
        #
        #  As a result, we recommend enabling status checks, and
        #  we do NOT recommend using "revive_interval".
        #
        #  The "revive_interval" is used ONLY if the "status_check"
        #  entry below is "none".  Otherwise, it will not be used,
        #  and should be deleted.
        #
        #  Useful range of values: 60 to 3600
        revive_interval = 120

        #
        #  The proxying server (i.e. this one) can do periodic status
        #  checks to see if a dead home server has come back alive.
        #
        #  If set to "none", then the other configuration items listed
        #  below are not used, and the "revive_interval" time is used
        #  instead.
        #
        #  If set to "status-server", the Status-Server packets are
        #  sent.  Many RADIUS servers support Status-Server.  If a
        #  server does not support it, please contact the server
        #  vendor and request that they add it.
        #
        #  If set to "request", then Access-Request, or Accounting-Request
        #  packets are sent, depending on the "type" entry above (auth/acct).
        #  
        #  Allowed values: none, status-server, request
        status_check = status-server

        #
        #  If the home server does not support Status-Server packets,
        #  then the server can still send Access-Request or
        #  Accounting-Request packets, with a pre-defined user name.
        #
        #  This practice is NOT recommended, as it may potentially let
        #  users gain network access by using these "test" accounts!
        #
        #  If it is used, we recommend that the home server ALWAYS
        #  respond to these Access-Request status checks with
        #  Access-Reject.  The status check just needs an answer, it
        #  does not need an Access-Accept.
        #
        #  For Accounting-Request status checks, only the username
        #  needs to be set.  The rest of the accounting attribute are
        #  set to default values.  The home server that receives these
        #  accounting packets SHOULD NOT treat them like normal user
        #  accounting packets.  i.e It should probably NOT log them to
        #  a database.
        #
        # username = "test_user_please_reject_me"
        # password = "this is really secret"

        #
        #  Configure the interval between sending status check packets.
        #
        #  Setting it too low increases the probability of spurious
        #  fail-over and fallback attempts.
        #
        #  Useful range of values: 6 to 120
        check_interval = 30

        #
        #  Configure the number of status checks in a row that the
        #  home server needs to respond to before it is marked alive.
        #
        #  If you want to mark a home server as alive after a short
        #  time period of being responsive, it is best to use a small
        #  "check_interval", and a large value for
        #  "num_answers_to_alive".  Using a long "check_interval" and
        #  a small number for "num_answers_to_alive" increases the
        #  probability of spurious fail-over and fallback attempts.
        #
        #  Useful range of values: 3 to 10
        num_answers_to_alive = 3

        #
        #  Limit the total number of outstanding packets to the home
        #  server.
        #
        #  if ((#request sent) - (#requests received)) > max_outstanding
        #       then stop sending more packets to the home server
        #
        #  This lets us gracefully fall over when the home server
        #  is overloaded.
        max_outstanding = 65536

        #
        #  The configuration items in the next sub-section are used ONLY
        #  when "type = coa".  It is ignored for all other type of home
        #  servers.
        #
        #  See RFC 5080 for the definitions of the following terms.
        #  RAND is a function (internal to FreeRADIUS) returning
        #  random numbers between -0.1 and +0.1
        #
        #  First Re-transmit occurs after:
        #
        #        RT = IRT + RAND*IRT
        #
        #  Subsequent Re-transmits occur after:
        #
        #       RT = 2 * RTprev + RAND * RTprev
        #
        #  Re-trasnmits are capped at:
        #
        #       if (MRT && (RT > MRT)) RT = MRT + RAND * MRT
        #
        #  For a maximum number of attempts: MRC
        #
        #  For a maximum (total) period of time: MRD.
        #
        coa {
                # Initial retransmit interval: 1..5
                irt = 2

                # Maximum Retransmit Timeout: 1..30 (0 == no maximum)
                mrt = 16

                # Maximum Retransmit Count: 1..20 (0 == retransmit forever)
                mrc = 5

                # Maximum Retransmit Duration: 5..60
                mrd = 30
        }
}

# Sample virtual home server.
# 
#
#home_server virtual.example.com {
#           virtual_server = virtual.example.com
#}

######################################################################
#
#  This section defines a pool of home servers that is used
#  for fail-over and load-balancing.  In earlier versions of
#  FreeRADIUS, fail-over and load-balancing were defined per-realm.
#  As a result, if a server had 5 home servers, each of which served
#  the same 10 realms, you would need 50 "realm" entries.
#
#  In version 2.0, you would need 5 "home_server" sections,
#  10 'realm" sections, and one "home_server_pool" section to tie the
#  two together.
#
home_server_pool my_auth_failover {
        #
        #  The type of this pool controls how home servers are chosen.
        #
        #  fail-over - the request is sent to the first live
        #       home server in the list.  i.e. If the first home server
        #       is marked "dead", the second one is chosen, etc.
        #
        #  load-balance - the least busy home server is chosen,
        #       where "least busy" is counted by taking the number of
        #       requests sent to that home server, and subtracting the
        #       number of responses received from that home server.
        #
        #       If there are two or more servers with the same low
        #       load, then one of those servers is chosen at random.
        #       This configuration is most similar to the old
        #       "round-robin" method, though it is not exactly the same.
        #
        #       Note that load balancing does not work well with EAP,
        #       as EAP requires packets for an EAP conversation to be
        #       sent to the same home server.  The load balancing method
        #       does not keep state in between packets, meaning that
        #       EAP packets for the same conversation may be sent to
        #       different home servers.  This will prevent EAP from
        #       working.
        #
        #       For non-EAP authentication methods, and for accounting
        #       packets, we recommend using "load-balance".  It will
        #       ensure the highest availability for your network.
        #
        #  client-balance - the home server is chosen by hashing the
        #       source IP address of the packet.  If that home server
        #       is down, the next one in the list is used, just as
        #       with "fail-over".
        #
        #       There is no way of predicting which source IP will map
        #       to which home server.
        #
        #       This configuration is most useful to do simple load
        #       balancing for EAP sessions, as the EAP session will
        #       always be sent to the same home server.
        #
        #  client-port-balance - the home server is chosen by hashing
        #       the source IP address and source port of the packet.
        #       If that home server is down, the next one in the list
        #       is used, just as with "fail-over".
        #
        #       This method provides slightly better load balancing
        #       for EAP sessions than "client-balance".  However, it
        #       also means that authentication and accounting packets
        #       for the same session MAY go to different home servers.
        #
        #  keyed-balance - the home server is chosen by hashing (FNV)
        #       the contents of the Load-Balance-Key attribute from the
        #       control items.  The  request is then sent to home server
        #       chosen by taking:
        #
        #               server = (hash % num_servers_in_pool).
        #
        #       If there is no Load-Balance-Key in the control items,
        #       the load balancing method is identical to "load-balance".
        #
        #       For most non-EAP authentication methods, The User-Name
        #       attribute provides a good key.  An "unlang" policy can
        #       be used to copy the User-Name to the Load-Balance-Key
        #       attribute.  This method may not work for EAP sessions,
        #       as the User-Name outside of the TLS tunnel is often
        #       static, e.g. "anonymous@realm".
        #
        #
        #  The default type is fail-over.
        type = fail-over

        #
        #  A virtual_server may be specified here.  If so, the
        #  "pre-proxy" and "post-proxy" sections are called when
        #  the request is proxied, and when a response is received.
        #
        #  This lets you have one policy for all requests that are proxied
        #  to a home server.  This policy is completely independent of
        #  any policies used to receive, or process the request.
        #
        #virtual_server = pre_post_proxy_for_pool

        #
        #  Next, a list of one or more home servers.  The names
        #  of the home servers are NOT the hostnames, but the names
        #  of the sections.  (e.g. home_server foo {...} has name "foo".
        #
        #  Note that ALL home servers listed here have to be of the same
        #  type.  i.e. they all have to be "auth", or they all have to
        #  be "acct", or the all have to be "auth+acct".
        #
        home_server = localhost

        #  Additional home servers can be listed.
        #  There is NO LIMIT to the number of home servers that can
        #  be listed, though using more than 10 or so will become
        #  difficult to manage.
        #
        # home_server = foo.example.com
        # home_server = bar.example.com
        # home_server = baz.example.com
        # home_server = ...


        #
        #  If ALL home servers are dead, then this "fallback" home server
        #  is used.  If set, it takes precedence over any realm-based
        #  fallback, such as the DEFAULT realm.
        #
        #  For reasons of stability, this home server SHOULD be a virtual
        #  server.  Otherwise, the fallback may itself be dead!
        #
        #fallback = virtual.example.com
}

######################################################################
#
#
#  This section defines a new-style "realm".  Note the in version 2.0,
#  there are many fewer configuration items than in 1.x for a realm.
#
#  Automatic proxying is done via the "realms" module (see "man
#  rlm_realm").  To manually proxy the request put this entry in the
#  "users" file:

#
#
#DEFAULT        Proxy-To-Realm := "realm_name"
#
#
realm example.com {
        #
        #  Realms point to pools of home servers.
#
        #  For authentication, the "auth_pool" configuration item
        #  should point to a "home_server_pool" that was previously
        #  defined.  All of the home servers in the "auth_pool" must
        #  be of type "auth".
        #
        #  For accounting, the "acct_pool" configuration item
        #  should point to a "home_server_pool" that was previously
        #  defined.  All of the home servers in the "acct_pool" must
        #  be of type "acct".
        #
        #  If you have a "home_server_pool" where all of the home servers
        #  are of type "auth+acct", you can just use the "pool"
        #  configuration item, instead of specifying both "auth_pool"
        #  and "acct_pool".

        auth_pool = my_auth_failover
#       acct_pool = acct

        #
        #  Normally, when an incoming User-Name is matched against the
        #  realm, the realm name is "stripped" off, and the "stripped"
        #  user name is used to perform matches.
        #
        #  e.g. User-Name = "bob@example.com" will result in two new
        #  attributes being created by the "realms" module:
        #
        #       Stripped-User-Name = "bob"
        #       Realm = "example.com"
        #
        #  The Stripped-User-Name is then used as a key in the "users"
        #  file, for example.
        #
        #  If you do not want this to happen, uncomment "nostrip" below.
        #
        # nostrip

        #  There are no more configuration entries for a realm.
}


#
#  This is a sample entry for iPass.
#  Note that you have to define "ipass_auth_pool" and
#  "ipass_acct_pool", along with home_servers for them, too.
#
#realm IPASS {
#       nostrip
#
#       auth_pool = ipass_auth_pool
#       acct_pool = ipass_acct_pool
#}

#
#  This realm is used mainly to cancel proxying.  You can have
#  the "realm suffix" module configured to proxy all requests for
#  a realm, and then later cancel the proxying, based on other
#  configuration.
#
#  For example, you want to terminate PEAP or EAP-TTLS locally,
#  you can add the following to the "users" file:
#
#  DEFAULT EAP-Type == PEAP, Proxy-To-Realm := LOCAL
#
realm LOCAL {
        #  If we do not specify a server pool, the realm is LOCAL, and
        #  requests are not proxied to it.
}

#
#  This realm is for requests which don't have an explicit realm
#  prefix or suffix.  User names like "bob" will match this one.
#
#realm NULL {
#       authhost        = radius.company.com:1600
#       accthost        = radius.company.com:1601
#       secret          = testing123
#}

#
#  This realm is for ALL OTHER requests.
#
#realm DEFAULT {
#       authhost        = radius.company.com:1600
#       accthost        = radius.company.com:1601
#       secret          = testing123
#}


#  This realm "proxies" requests internally to a virtual server.
#  The pre-proxy and post-proxy sections are run just as with any
#  other kind of home server.  The virtual server then receives
#  the request, and replies, just as with any other packet.
#
#  Once proxied internally like this, the request CANNOT be proxied
#  internally or externally.
#
#realm virtual.example.com {
#       virtual_server = virtual.example.com
#}
#

#
#  Regular expressions may also be used as realm names.  If these are used,
#  then the "find matching realm" process is as follows:
#
#    1) Look for a non-regex realm with an *exact* match for the name.
#       If found, it is used in preference to any regex matching realm.
#
#    2) Look for a regex realm, in the order that they are listed
#       in the configuration files.  Any regex match is performed in
#       a case-insensitive fashion.
#
#    3) If no realm is found, return the DEFAULT realm, if any.
#
#  The order of the realms matters in step (2).  For example, defining
#  two realms ".*\.example.net$" and ".*\.test\.example\.net$" will result in
#  the second realm NEVER matching.  This is because all of the realms
#  which match the second regex also match the first one.  Since the
#  first regex matches, it is returned.
#
#  The solution is to list the realms in the opposite order,. e.g.
#  ".*\.test\.example.net$", followed by ".*\.example\.net$".
#
#
#  Some helpful rules:
#
#   - always place a '~' character at the start of the realm name.
#     This signifies that it is a regex match, and not an exact match
#     for the realm.
#
#   - place the regex in double quotes.  This helps the configuration
#     file parser ignore any "special" characters in the regex.
#     Yes, this rule is different than the normal "unlang" rules for
#     regular expressions.  That may be fixed in a future release.
#
#   - use two back-slashes '\\' whenever you need one backslash in the
#     regex.  e.g. "~.*\\.example\\.net$", and not "~\.example\.net$".
#     This is because the regex is in a double-quoted string, and normal
#     rules apply for double-quoted strings.
#
#   - If you are matching domain names, use two backslashes in front of
#     every '.' (dot or period).  This is because '.' has special meaning
#     in a regular expression: match any character.  If you do not do this,
#     then "~.*.example.net$" will match "fooXexampleYnet", which is likely
#     not what you want
#
#   - If you are matching domain names, put a '$' at the end of the regex
#     that matches the domain name.  This tells the regex matching code
#     that the realm ENDS with the domain name, so it does not match
#     realms with the domain name in the middle.  e.g. "~.*\\.example\\.net"
#     will match "test.example.netFOO", which is likely not what you want.
#     Using "~(.*\\.)example\\.net$" is better.
#
#  The more regex realms that are defined, the more time it takes to
#  process them.  You should define as few regex realms as possible
#  in order to maximize server performance.
#
#realm "~(.*\\.)*example\\.net$" {
#      auth_pool = my_auth_failover
#}