# -*- 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 # 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 # # Whether or not we allow dynamic home servers. # # This setting should be "no" by default. If set to "yes", # it can slow the server down, due to mutex locking across # multiple threads. # # Dynamic servers will work ONLY with the "directory" # configuration below. # # dynamic = yes # # The directory which contains dynamic home servers. Each # file in the directory should be a normal "home_server" # definitions. This directory does not exist by default. # # e.g: The content of home_servers/example.com should be # a home server definition. # # The name of the home server MUST be the same as the # filename. # # Each home server must be set to only one type. e.g. # "type = auth", and not "type = auth+acct" # # For example: # # home_server example.com { # type = auth # ipaddr = ... # ... # } # # For complete documentation, please see # # doc/configuration/dynamic_home_servers.md # # directory = ${confdir}/home_servers } ####################################################################### # # Configuration for the proxy realms. # # As of 2.0, the "realm" configuration has changed. Instead of # specifying "authhost" and "accthost" in a realm section, the home # servers are specified separately 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. # # See sites-available/tls for an example of configuring home servers, # pools, and realms with TLS. # ###################################################################### # # 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. # # You can proxy to a specific home server by doing: # # update control { # Home-Server-Name = "name of home server" # } # 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. # # Unlike proxying to a regular home server, requests # proxied to a virtual server will be passed through # pre-proxy and post-proxy sections in the # destination virtual server, rather than those in # the virtual server currently processing the 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 transport protocol. # # If unspecified, defaults to "udp", which is the traditional # RADIUS transport. It may also be "tcp", in which case TCP # will be used to talk to this home server. # # When home servers are put into pools, the pool can contain # home servers with both UDP and TCP transports. # #proto = udp # # 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 # # If the home server does not respond to a request within # this time, the server marks the request as timed out. # After "response_timeouts", the home server is marked # as being "zombie", and "zombie_period" starts. # # The response window can be a number between 0.001 and 60.000 # Values on the low end are discouraged, as they will likely # not work due to limitations of operating system timers. # # The default 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 # # Start "zombie_period" after this many responses have # timed out. # # response_timeouts = 1 # # 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: 10 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. With status-server if # the home server is marked as a zombie and a status-server # response is received, it will be immediately marked as live. # # This prevents spurious failovers in federations such as # eduroam, where intermediary proxy servers may be functional # but the servers of a home institution may not be, # # 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 # # Wait "check_timeout" seconds for a reply to a status check # packet. # check_timeout = 4 # # 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-transmits 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 } # # Connection limiting for home servers with "proto = tcp". # # This section is ignored for other home servers. # limit { # # Limit the number of TCP connections to the home server. # # The default is 16. # Setting this to 0 means "no limit" max_connections = 16 # # Limit the total number of requests sent over one # TCP connection. After this number of requests, the # connection will be closed. Any new packets that are # proxied to the home server will result in a new TCP # connection being made. # # Setting this to 0 means "no limit" max_requests = 0 # # The lifetime, in seconds, of a TCP connection. After # this lifetime, the connection will be closed. # # Setting this to 0 means "forever". lifetime = 0 # # The idle timeout, in seconds, of a TCP connection. # If no packets have been sent over the connection for # this time, the connection will be closed. # # Setting this to 0 means "no timeout". idle_timeout = 0 } } # 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. # # You can proxy to a specific home server pool by doing: # # update control { # Home-Server-Pool = "name of pool" # } # 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 from the destination # virtual server are run 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! # # Note: When packets are proxied to this fallback home server, # if it is a virtual server, the pre-proxy and post-proxy sections # from the destination virtual server will be run instead of those # in the current virtual server. # #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 # The server can proxy CoA packets based on the Operator-Name # attribute. This requires that the "suffix" module be # listed in the "recv-coa" section. # # See raddb/sites-available/coa # # coa_pool = name_of_coa_pool # # 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. # # Note that if the system is doing EAP, you MUST set the "nostrip" # option for realms used in EAP. Otherwise EAP will fail. # # 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.example.com:1600 # accthost = radius.example.com:1601 # secret = testing123 #} # # This realm is for ALL OTHER requests. # #realm DEFAULT { # authhost = radius.example.com:1600 # accthost = radius.example.com:1601 # secret = testing123 #} # This realm "proxies" requests internally to a virtual server. # The pre-proxy and post-proxy sections from the destination # virtual server are run rather than those in the current # virtual server. The destination 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. # # Realms are almost always domain names, and therefore realm names # are compared in a case-insensitive fashion. # #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. # # - 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 #}