This Wiki is available to view at but still under maintenance. PLEASE DO NOT EDIT THE WIKI UNTIL FURTHER NOTICE. We are attempting to restore missing edits which took place between Monday 8 and Thursday 11 April 2019, therefore the site is likely to be taken off line at any time. Updated 20:43 CEST 16 April 2019.
Child pages
  • radiator-flr
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 11 Next »

Operating a federation-level RADIUS server (FLR)

Federation-level servers (FLRs) are used to connect eduroam Identity Providers and eduroam Service Providers with each other, and also provide an uplink from the federation to all other eduroam federations.They are managed by National Roaming Organisations (NROs). The NRO may outsource the operation to a third-party, but will remain responsible.

Since the concept of an eduroam federation geographically usually maps to a country, FLRs are central to the deployment of eduroam in a country; there is conceptually only one FLR per country - but for resiliency reasons, it is recommended to provide multiple instances in a failover setup.

An eduroam federation comes with administrative requirements as well as technical ones. The exact requirements may differ between world regions. This document uses the European definitions and documents; which are believed to provide a good initial insight for the world-wide eduroam community. Readers from outside the GEANT service region should consult the responsible regional operator for their world region for further details after reading this document.

Hardware requirements

RADIUS is a very lightweight protocol, and does not require expensive hardware setups. Even the busiest eduroam federations operate their server on a single contemporary hardware or Virtual Machine, without experiencing overload conditions.

As with every other professionally-operated service though, you should keep in mind that service uptime is paramount, and plan your procurement accordingly. Examples:

  • In the case of virtual machines, use an underlying infrastructure which enables you to migrate machines without VM downtime, if possible.
  • In the case of physical machines, use hot-pluggable parts where possible; and ideally, keep either spare hardware parts at hand or a set up a decent service contract.

eduroam Europe is in the process of migrating to RADIUS/TLS for its federation servers. In the course of this process, hardware requirements for the servers may change. This section will be updated as necessary.

Software requirements and setup

eduroam does not prescribe any particular RADIUS implementation. The technical requirements for eduroam however narrow the set of usable RADIUS server implementations, and the observed deployment of eduroam federation-level servers shows patterns regarding implementation popularity.

This section will present a few typical implementation setups. Note, however, that a federation is free to use a different implementation so long as the implementation can satisfy the eduroam technical requirements.

The sections for each implementation are accompanied by a skeleton configuration file, which should be usable almost as-is. However, please read and try to understand the entire corresponding section before applying the template - the information presented is valuable for daily operation and troubleshooting.

Radiator

Radiator is perhaps the most popular server software in eduroam federations. The config file and examples below assume deployment on a UNIX-like platform, such as Linux or FreeBSD. Radiator can also be used on Windows; in which case you will have to adapt some path names etc.

Base configuration / logging / F-Ticks

Radiator expects the configuration to be in file /etc/radiator/radius.cfg.

The parameter LogDir defines the directory in which start-up logs and PID file reside. DbDir defines the path to Radiator's data files, such as dictionaries.

LogDir    /var/log/radiator
DbDir     /usr/share/radiator

Throughout the configuration file, you may want to use DNS names instead of IP addresses. For RADIUS/TLS with dynamic discovery, it is even required to use DNS. The configuration for DNS is as follows (replace the IP addresses with your own):

<Resolver>
        Nameservers     1.2.3.4
        Nameservers     2001:db8:1:1::25
        NAPTR-Pattern x-eduroam:(radius)\.(tls)
        Debug
</Resolver>

The logs during normal operation are defined separately in <Log> stanzas. The verbosity of logging depends on the Trace level in the configuration: Trace 3 logs are recommended for normal operation, while Trace 4 logs provide verbosity for debugging, if needed. You can define several <Log> instances with different destinations. Let's define logging to syslog with verbosity level 3, and logging to a file for debugging purposes with verbosity level 4. We also define that the log file name changes on a daily basis to enable easy deletion of old files:

<Log SYSLOG>
      Facility      local7
      LogIdent   log-syslog
     Trace        3
</Log>

<Log FILE>
      Filename   /var/log/radiator/radiator.%Y%m_%d.log_
      LogIdent   log-file
     Trace        4
</Log>

 You can also log authentication events in one line per authentication separately. The eduroam statistics system, F-Ticks, makes use of that feature. The F-Ticks logging facility is defined as follows:

<AuthLog SYSLOG>
        Identifier TICKS
        LogSuccess 1
        LogFailure 1
        LogSock udp
        LogHost 1.2.3.4
        SuccessFormat F-TICKS/eduroam/1.0#REALM=%R#VISCOUNTRY=%{eduroam-SP-Country}#VISINST=%{Operator-Name}#CSI=%{Calling-Station-Id}#RESULT=OK#
        FailureFormat F-TICKS/eduroam/1.0#REALM=%R#VISCOUNTRY=%{eduroam-SP-Country}#VISINST=%{Operator-Name}#CSI=%{Calling-Station-Id}#RESULT=FAIL#
</AuthLog>

Here, you need to adapt LogHost to the eduroam F-Ticks logging server (whose address you'll receive from eduroam operations), and the attribute marked with read. Its contents will become clearer later in the configuration file.

It is also useful to log each authentication locally, with more detail than is needed for F-Ticks. We suggest using the following log definition – it generates one single line of log output per authentication, which is very parser-friendly if logs need to be evaluated later: 

<AuthLog SYSLOG>
        Identifier            defaultAuthLog
        Facility              local7
        LogIdent              radiator
        FailureFormat         Access-Reject for %u (User-Name=%{Reply:User-Name}) at Proxy=%c (CSI=%{Calling-Station-Id}NAS=%{NAS-Identifier}/%N)
        SuccessFormat         Access-Accept for %u (User-Name=%{Reply:User-Name}) at Proxy=%c (CSI=%{Calling-Station-Id}NAS=%{NAS-Identifier}/%N) EAP=%{HexAddress:EAP-Message}
        LogSuccess            1
        LogFailure            1
</AuthLog>

You may also want to configure SNMP access to your server. SNMP allows remote monitoring of activity on a RADIUS server with tools such as RADAR from OSC (http://www.open.com.au/radar/index.html), or drawing simple graphs of activity by rgraph from CESNET (http://www.eduroam.cz/rgraph/).

<SNMPAgent>
      ROCommunity xxxxxxxxxxxxxxxxxxxxxxxxx
      Managers        localhost 127.0.0.1
</SNMPAgent>

Next, the ports Radiator will use to listen for Authentication and Accounting requests must be defined. The port numbers 1812 and 1813 were assigned to the RADIUS protocol by IANA. Note: Exceptionally, you may come across very old RADIUS equipment which uses non-standard ports 1645 and 1646. Please see the Radiator documentation how to handle these, or consider upgrading the corresponding equipment.

AuthPort    1812
AcctPort    1813
Client definition

In the client section, all possible peers from which the FLR server is going to accept requests, are listed. I.e. it includes all eduroam SPs in the federation and the uplink to the other federations (in Europe, to the ETLR servers).

For RADIUS, individual clients with their IP address have to be listed and a "secret" has to be assigned to them. As this secret is the only thing that protects the communication between the RADIUS servers from eavesdropping, it must be cryptographically strong (suggested: exactly 16 characters) and well protected.

The clients should also be tagged with the attribute Operator-Name. which takes the format "1<domainname>", and for F-Ticks classification reasons, also with the country the eduroam SP is located in (or UNKNOWN for clients whose geographic location isn't known).

Example: you have an eduroam SP which operates on the address 1.3.5.7 and have negotiated the shared secret "adf7856asdcvxb5p" with it. The SP is based in Antarctica, and uses the domain name "foo.aq". You want it to show up in log files as "icecold-radius".

# my eduroam SP in Antarctica

<Client 1.3.5.7>
      Secret           adf7856asdcvxb5p
      Identifier       icecold-radius
      AddToRequest     Operator-Name=foo.aq,eduroam-SP-Country=AQ
</Client>

The clients for your uplink to ETLRs will look similar to the following. Note they are tagged with Country=UNKNOWN because requests coming from these countries can originate from all over the world (they connect all other federations). For the same reason, it also does not make sense to set the Operator-Name attribute.

<Client etlr1.eduroam.org>
      IdenticalClients etlr2.eduroam.org
      Secret           (as negotiated with eduroam OT)
      Identifier       etlr1.eduroam.org
      AddToRequest     eduroam-SP-Country=UNKNOWN
</Client>

Two additional clients are useful: one client for localhost, which can be used for local debugging purposes (and which doesn't need a strong secret); and the client which used for European FLR monitoring (negotiate the client address eduroam OT) at

<Client 1.2.3.4>
        Secret (as negotiated with eduroam OT)
        Identifier Monitoring-ETLR
        AddToRequest eduroam-SP-Country=NONE
</Client>

<Client localhost>
        Secret         mysecret
        DupInterval    0
        AddToRequest   eduroam-SP-Country=NONE
</Client>

Note: all the Identifier names in the configuration need to be unique, and should be meaningful to you, the server operator.

Finally, to enable RADIUS/TLS clients to communicate with your server, you need an additional section for RADIUS/TLS like the following. Replace your server's IP address(es) and paths to the certificate files as necessary - please refer to the "Certificates" section for details on how to obtain and manage RADIUS/TLS certificates.

<ServerRADSEC>
        Port                2083
        BindAddress         4.5.6.8, ipv6:2001:db8:1::26
        Secret              radsec
        Protocol            tcp      
        UseTLS
        TLS_CAPath          /etc/radiator/certs/CAs/       
        TLS_CertificateFile /etc/radiator/certs/server.pem
        TLS_CertificateType PEM
        TLS_PrivateKeyFile  /etc/radiator/certs/server.key
        TLS_RequireClientCert
        Identifier RadSec
        AddToRequest eduroam-SP-Country=UNKNOWN
</ServerRADSEC>
Request forwarding

Your eduroam IdPs

eduroam authentication requests are routed based on the User-Name attribute in the request. Radiator will extract the realm from the User-Name attribute. Radiator uses <Handler> definitions for routing decisions. Even though routing may seem straight-forward since it is based on a single string, it is unfortunately easy to introduce routing loops. Therefore, special care should be taken to prevent this. There are several approaches to that. The one presented here involves regular expressions. The following example shows these, based on the hyptothetical eduroam IdP realm "foo.aq" in Antarctica, and one authoritative RADIUS server for this realm. That same IdP is also an SP and could originate requests. The handler will then look like the following:

<Handler Realm=/^foo\.aq$/i,Client-Identifier=/^(?!icecold-radius$)/>
      <AuthBy RADIUS>
                RetryTimeout          3
                Retries               1
                FailureBackoffTime    0
                UseExtendedIds
                <Host 1.3.5.9>
                          AuthPort           1812
                          AcctPort           1813
                          Secret             xxxxxxxxxxxxxxxxxxxxxxxxx
                </Host>
      </AuthBy>
      AuthLog TICKS
      AuthLog defaultAuthLog
</Handler>

Note the regular expression: it matches only exactly "foo.aq" - not "barfoo.aq" or "foo.aqx". It also contains a safety measure: since the FLR operator can make the link that the realm "foo.aq" is colocated with a eduroam SP whose Client Identifier is "icecold-radius", it can spot that there must be an error if requests for the realm "foo.aq" leave the server in question. Therefore, the Handler clause will only match if the Client-Identifier is NOT "icecold-radius".

If the eduroam IdP provides multiple servers for resiliency reasons, you can specify this in the Handler as well. Please consult the Radiator manual for further details.

Handlers are evaluated in-order, so you should list all known eduroam IdPs one after another in one big block.

You should also add several "catch-all" realms for unknown realms. They are listed below.

Handling empty realms

Empty realms means User-Name requests that do not carry the @... suffix. In a well-behaved eduroam IdP, empty realms should not reach the FLR server (they would be discarded by the IdP already), but if they do, this following realm definition will catch them and reject the request. A reply will be added to the rejected requests explaining the reason for rejection. Replace <TLD> with the federation top-level domain you are authoritative for.

<Handler Realm=/^$/>
      AccountingHandled
      StripFromReply         Reply-Message
      AddToReply              Reply-Message="Misconfigured client: empty realm! Rejected by <TLD>."
      AuthLog defaultAuthLog
</Handler>


Handling unknown realms in the own federation

After the last connected realm, it makes sense to reject all known-bad realms and all unknown realms which end in the own federation's top-level domain. One such invalid realm is seen quite often due to supplicant misconfiguration: myabc.com (this is the default realm in an unconfigured Intel PRO/Set Wireless supplicant). The following stanza rejects this realm with an appropriate error message and blindly acknowledges all Accounting requests.

<Handler Realm=/myabc\.com$/i>
          AccountingHandled
                           StripFromReply   Reply-Message
                          AddToReply         Reply-Message=" Misconfigured client: default realm of Intel PRO/Wireless supplicant! Rejected by <TLD>."
                         AuthLog defaultAuthLog
</Handler>

Add the following stanza after the last valid realm to catch and reject all unknown realms that end in the own TLD:

<Handler Realm=/.*\.tld$/i>
         AccountingHandled
                         StripFromReply    Reply-Message
                         AddToReply         Reply-Message=" Misconfigured supplicant or downstream server: uses non-existing realm in <TLD> federation!"
                         AuthLog defaultAuthLog

</Handler>

The following directive (DefineFormattedGlobalVar) defines the variable dr_TOPLEVEL_server_list and assigns a list of servers responsible for the handler marked as TOPLEVEL to this variable.

DefineFormattedGlobalVar          dr_TOPLEVEL_server_list __ etlr1.eduroam.org,etlr2.eduroam.org

The handler with the filter Realm=/.+$/ will receive any request that will not be caught by more specific filters before (Realm=/^orgA.tld$/i, Realm=/.\.tld{*}$/, Realm=/$/). In this example it will be all requests that belong to other TLD's than the ones defined on this server – requests that have to be forwarded to top-level servers.

RequestHook will use the value of Identifier (= TOPLEVEL) defined in this handler to search the variable dr_TOPLEVEL_server_list holding the list of servers. It will forward the request to a server not marked dead, or if all are marked dead the one with the oldest dead-realm mark.

<Handler Realm=/.+$/>                    Client-Identifier=/(?!etlr1.eduroam.org$)/>
                    Client-Identifier=/^(?!etlr2.eduroam.org$)/>

           Identifier TOPLEVEL

           <AuthBy INTERNAL>
_                             RequestHook sub

Unknown macro: { DeadRealm}

_

Caveats

Operator-Name & eduroam-SP-Country: describe dictionary mods

  • No labels