raddb/README.rst

   1 Upgrading to Version 3.0
   2 ========================
   3
   4 The configuration for 3.0 is *largely* compatible with the 2.x
   5 configuration.  However, it is NOT possible to simply use the 2.x
   6 configuration as-is.  Instead, you should re-create it.
   7
   8 Security
   9 --------
  10
  11 A number of configuration items have moved into the "security"
  12 subsection of radiusd.conf.  If you use these, you should move them.
  13 Otherwise, they can be ignored.
  14
  15 The list of moved options is::
  16
  17   chroot
  18   user
  19   group
  20   allow_core_dumps
  21   reject_delay
  22   status_server
  23
  24
  25 Modules Directory
  26 -----------------
  27
  28 As of version 3.0, the ``modules/`` directory no longer exists.
  29
  30 Instead, all "example" modules have been put into the
  31 ``mods-available/`` directory.  Modules which can be loaded by the server
  32 are placed in the ``mods-enabled/`` directory.
  33
  34 Modules can be enabled by creating a soft link.  For module ``foo``, do::
  35
  36   $ cd raddb
  37   $ ln -s mods-available/foo mods-enabled/foo
  38
  39 To create "local" versions of the modules, we suggest copying the file
  40 instead.  This leaves the original file (with documentation) in the
  41 ``mods-available/`` directory.  Local changes should go into the
  42 ``mods-enabled/`` directory.
  43
  44
  45 SQL
  46 ---
  47
  48 The SQL configuration has been moved from ``sql.conf`` to
  49 ``mods-available/sql``.  The ``sqlippool.conf`` file has also been
  50 moved to ``mods-available/sqlippool``.
  51
  52 The SQL module configuration has been changed.  The old connection
  53 pool options are no longer understood::
  54
  55   num_sql_socks
  56   connect_failure_retry_delay
  57   lifetime
  58   max_queries
  59
  60 Instead, a connection pool configuration is used.  This configuration
  61 contains all of the functionality of the previous configuration, but
  62 in a more generic form.  It also is used in multiple modules, meaning
  63 that there are fewer different configuration items.  The mapping
  64 between the configuration items is::
  65
  66   num_sql_socks                 -> pool { max }
  67   connect_failure_retry_delay   -> NOT SUPPORTED
  68   lifetime                      -> pool { lifetime }
  69   max_queries                   -> pool { uses }
  70
  71 The pool configuration adds a number of new configuration options,
  72 which allow the administrator to better control how FreeRADIUS uses
  73 SQL connection pools.
  74
  75 The following parameters have been changed::
  76
  77   trace                         -> removed
  78   tracefile                     -> logfile
  79
  80 The logfile is intended to log SQL queries performed.  If you need to
  81 debug the server, use debugging mode.  If ``logfile`` is set, then
  82 *all* SQL queries will go to ``logfile``.
  83
  84 You can now use a NULL SQL database::
  85
  86   driver = rlm_sql_null
  87
  88 This is an empty driver which will always return "success".  It is
  89 intended to be used to replace the ``sql_log`` module, and in
  90 conjunction with the ``radsqlrelay`` program.  Simply take your normal
  91 configuration for raddb/mods-enabled/sql, and set::
  92
  93   driver = rlm_sql_null
  94   ...
  95   logfile = ${radacctdir}/log.sql
  96
  97 And all of the SQL queries will be logged to that file.  The
  98 connection pool will still need to be configured for the NULL SQL
  99 driver, but the defaults will work.
 100
 101 SQL-dialup.conf
 102 ---------------
 103
 104 Queries for post-auth and accounting calls have been re-arranged.
 105 The SQL module will now expand the 'reference' configuration item
 106 in the appropriate sub-section, and resolve this to a configuration
 107 item. This behaviour is similar to rlm_linelog.
 108
 109 The queries can manually be moved to copy of the v3.0.x ``dialup.conf`` file.
 110 The mapping is as follows::
 111
 112   accounting_onoff_query                -> accounting.type.accounting-on.query
 113   accounting_update_query               -> accounting.type.interim-update.query
 114   accounting_update_query_alt           +> accounting.type.interim-update.query
 115   accounting_start_query                -> accounting.type.start.query
 116   accounting_start_query_alt            +> accounting.type.start.query
 117   accounting_stop_query                 -> accounting.type.stop.query
 118   accounting_stop_query_alt             +> accounting.type.stop.query
 119   postauth_query                        -> post-auth.query
 120
 121 References to to the accounting tables may also need to be updated.
 122
 123 Alternitavely a v2.1.x may be patched to work with the v3.0.x module.
 124 Add the following at the bottom of your ``dialup.conf`` file::
 125
 126   accounting {
 127         reference = "%{tolower:type.%{Acct-Status-Type}.query}"
 128         type {
 129                 accounting-on {
 130                         query = "${....accounting_onoff_query}"
 131                 }
 132                 accounting-off {
 133                         query = "${....accounting_onoff_query}"
 134                 }
 135                 start {
 136                         query = "${....accounting_start_query}"
 137                         query = "${....accounting_start_query_alt}"
 138                 }
 139                 interim-update {
 140                         query = "${....accounting_update_query}"
 141                         query = "${....accounting_update_query_alt}"
 142                 }
 143                 stop {
 144                         query = "${....accounting_stop_query}"
 145                         query = "${....accounting_stop_query_alt}"
 146                 }
 147         }
 148   }
 149
 150   post-auth {
 151         query = "${..postauth_query}"
 152   }
 153
 154 LDAP
 155 ----
 156
 157 The LDAP module configuration has been substantially changed.  Please
 158 read raddb/mods-available/ldap.  It now uses a connection pool, just
 159 like the SQL module.
 160
 161 Many of the configuration items remain the same, but they have been
 162 moved into subsections.  This change is largely cosmetic, but it makes
 163 the configuration clearer.  Instead of having a large set of random
 164 configuration items, they are now organized into logical groups.
 165
 166 You will need to read your old LDAP configuration, and migrate it
 167 manually to the new configuration.  Simply copying the old
 168 configuration WILL NOT WORK.
 169
 170 The eDirectory support has been removed.  It was written by
 171 duplicating large amounts of code in the module.  As a result, it was
 172 incomprehensible, and unmaintainable.  It's probably easy to add the
 173 code back, but doing so requires access to an eDirectory server.
 174
 175 As always, patches are welcome.
 176
 177
 178 EAP
 179 ---
 180
 181 The EAP configuration has been moved from ``eap.conf`` to
 182 ``mods-available/eap``.  A new ``pwd`` subsection has been added for
 183 EAP-PWD.
 184
 185 It is otherwise unchanged.  You chould be able to copy your old
 186 ``eap.conf`` file directly to ``mods-enabled/eap``.
 187
 188
 189 RadSec
 190 ------
 191
 192 RadSec (or RADIUS over TLS) is now supported.  RADIUS over bare TCP
 193 is also supported, but is recommended only for secure networks.
 194
 195 See ``sites-available/tls`` for complete details on using TLS.  The server
 196 can both receive incoming TLS connections, and also originate outgoing
 197 TLS connections.
 198
 199 The TLS configuration is taken from the old EAP-TLS configuration.  It
 200 is largely identical to the old EAP-TLS configuration, so it should be
 201 simple to use and configure.  It re-uses much of the EAP-TLS code,
 202 so it is well-tested and reliable.
 203
 204 Once RadSec is enabled, normal debugging mode will not work.  This is
 205 because the TLS code requires threading to work properly.  Instead of doing::
 206
 207   $ radiusd -X
 208
 209 you will need to do::
 210
 211   $ radiusd -fxx -l stdout
 212
 213
 214 PAP and User-Password
 215 ---------------------
 216
 217 From version 3.0 onwards the server no longer supports authenticating
 218 against a cleartext password in the 'User-Password' attribute. Any
 219 occurances of this (for instance, in the users file) should now be changed
 220 to 'Cleartext-Password' instead.
 221
 222 If this is not done, authentication is likely to fail.
 223
 224 If it really is impossible to do this, the following unlang inserted above
 225 the call to the pap module may be used to copy User-Password to the correct
 226 attribute::
 227
 228   if (!control:Cleartext-Password && control:User-Password) {
 229     update control {
 230       Cleartext-Password := "%{control:User-Password}"
 231     }
 232   }
 233
 234 However, this should only be seen as a temporary, not permanent, fix.