doc/proxy.rst

   1 FreeRADIUS as a proxy RADIUS server.
   2 ====================================
   3
   4
   5 Introduction
   6 ------------
   7
   8 It is possible to use FreeRADIUS as a proxy RADIUS server. This
   9 means that it can consult a remote RADIUS server to validate a user.
  10 This is handy for roaming setups, or for renting ports to someone else.
  11
  12 Files
  13 -----
  14
  15 If a user logs in with a defined realm syntax, the "realm" portion is
  16 matched against the configuration to determine how the request should
  17 be handled.  Common realm formats are:
  18
  19 ::
  20
  21   username@realm
  22   realm/username
  23   username%realm
  24   realm\username
  25
  26 The realm parsing syntax ( and search order ) is user definable via the
  27 realm module config in the ``/etc/raddb/radiusd.conf`` configuration file.
  28
  29 You can define multiple instances of the realm module to support multiple
  30 realm syntax's at the same time.  Be sure to pay close attention to the
  31 search order that you define, as you may inadvertently get unexpected
  32 behaviour ( by having a user use ``realm1/username@realm2`` for instance ).
  33 If you need to proxy to IPASS, it should go first, because usernames will
  34 be in the form ``IPASS/username@realm`` and you want to proxy these users to
  35 IPASS, not to the realm behind the ``@``.
  36
  37 The realms are configured in the file ``/etc/raddb/proxy.conf``, which is
  38 included by ``radiusd.conf``. The formats and sample configurations are
  39 included as comments.
  40
  41 The realm ``DEFAULT`` (without the quotes) matches all realms.
  42 The realm ``NULL`` matches any requests WITHOUT a realm.
  43
  44 If you set the remote server to ``LOCAL``, the request will be handled
  45 locally as usual, without sending it to a remote radius server.
  46
  47 There are several options you can add in both files:
  48
  49 - nostrip:
  50   By default the realm is stripped from the username before sending it
  51   on to the remote radius server. By specifying the "nostrip" option
  52   the @realm suffix will not be stripped.
  53 - hints
  54   By default the original username is sent to the remote radius
  55   server. By specifying the "hints" option the username will be
  56   sent as it is after the "hints" file was processed.
  57 - notrealm:
  58   By default if a realm is matched, it will be proxied to the server
  59   specified.  However, if you are using Replication functionality, you
  60   may want to override this behaviour.  This option will prevent a
  61   user who enters ``user@foobar`` from being proxied if the ``foobar``
  62   realm configuration contains ``notrealm``.  This function used to be
  63   called ``notsuffix``, and the old syntax is still supported.
  64
  65 The ``/etc/raddb/realms`` file is deprecated and should not be used anymore.
  66 If you use the ``/etc/raddb/realms`` file to enter realm configurations you will
  67 need to add the hostname and secret for the remote server in the
  68 file ``/etc/raddb/clients.conf``.
  69 It is not recommended to use both the realms file and the proxy.conf file,
  70 as that could cause confusion.
  71
  72 Accounting
  73 ----------
  74
  75 All accounting data for proxied requests does `not` get stored in the
  76 standard logfiles, but in a separate directory. The name of this
  77 directory is the name of the remote radius server.
  78
  79 Remote Server
  80 ----------------
  81
  82 When your server proxies requests to another server, it acts as a NAS for
  83 the remote server. On the remote server, you need to add the hostname of
  84 your server and the same secret to ``/etc/raddb/clients.conf`` as well.
  85
  86 As you might not control the remote radius server, you might want to
  87 control the attributes sent back by the remote server in an Access-Accept
  88 packet. Have a look at the attrs file for this!
  89
  90 What Happens
  91 ---------------
  92 The exact thing that happens is this:
  93
  94 - A user logs in with a realm
  95 - The hints file gets processed as usual
  96 - The user is checked against the huntgroups file. At this point
  97   the user `might` already be rejected.
  98 - The realm is looked up in the realms file. If it isn't defined,
  99   the users file is processed normally.
 100 - If the ``notrealm`` option is defined, the user is processed
 101   locally.
 102 - The realm is stripped from the username unless ``nostrip`` was
 103   set, and the request is sent to a remote radius server. Note that
 104   any stripping done in the hints file doesn't have an effect on the
 105   username sent to the remote radius server unless you set the
 106   ``hints`` option.
 107 - The remote server replies with Access-Accept or Access-Reject
 108
 109 ::
 110
 111   On Access-Accept:    The initial Auth-Type is set to Accept
 112   On Access-Reject:    The initial Auth-Type is set to Reject
 113
 114 Then the users file is processed as usual. The username used at
 115 this point is the one after hints file processing (regardless of
 116 the ``hints`` option). It also includes the realm (regardless of the
 117 setting of the ``nostrip`` option) unless the realm is ``LOCAL``.