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 Queries from v2.x.x should be manually copied to the new v3.x.x
 110 ``dialup.conf`` file. When doing this you may also need to update
 111 references to the accounting tables, as their definitions will
 112 now be outside of the subsection containing the query.
 113
 114 The mapping is as follows::
 115
 116   accounting_onoff_query                -> accounting.type.accounting-on.query
 117   accounting_update_query               -> accounting.type.interim-update.query
 118   accounting_update_query_alt           +> accounting.type.interim-update.query
 119   accounting_start_query                -> accounting.type.start.query
 120   accounting_start_query_alt            +> accounting.type.start.query
 121   accounting_stop_query                 -> accounting.type.stop.query
 122   accounting_stop_query_alt             +> accounting.type.stop.query
 123   postauth_query                        -> post-auth.query
 124
 125
 126
 127 Alternatively a v2.x.x config may be patched to work with the
 128 v3.x.x module by adding the following::
 129
 130   accounting {
 131         reference = "%{tolower:type.%{Acct-Status-Type}.query}"
 132         type {
 133                 accounting-on {
 134                         query = "${....accounting_onoff_query}"
 135                 }
 136                 accounting-off {
 137                         query = "${....accounting_onoff_query}"
 138                 }
 139                 start {
 140                         query = "${....accounting_start_query}"
 141                         query = "${....accounting_start_query_alt}"
 142                 }
 143                 interim-update {
 144                         query = "${....accounting_update_query}"
 145                         query = "${....accounting_update_query_alt}"
 146                 }
 147                 stop {
 148                         query = "${....accounting_stop_query}"
 149                         query = "${....accounting_stop_query_alt}"
 150                 }
 151         }
 152   }
 153
 154   post-auth {
 155         query = "${..postauth_query}"
 156   }
 157
 158 LDAP
 159 ----
 160
 161 The LDAP module configuration has been substantially changed.  Please
 162 read raddb/mods-available/ldap.  It now uses a connection pool, just
 163 like the SQL module.
 164
 165 Many of the configuration items remain the same, but they have been
 166 moved into subsections.  This change is largely cosmetic, but it makes
 167 the configuration clearer.  Instead of having a large set of random
 168 configuration items, they are now organized into logical groups.
 169
 170 You will need to read your old LDAP configuration, and migrate it
 171 manually to the new configuration.  Simply copying the old
 172 configuration WILL NOT WORK.
 173
 174 Users upgrading from 2.0.0 who used to call the ldap module in
 175 post-auth should now set ``edir_autz = yes``, and remove the ``ldap``
 176 module from the post-auth section.
 177
 178
 179 EAP
 180 ---
 181
 182 The EAP configuration has been moved from ``eap.conf`` to
 183 ``mods-available/eap``.  A new ``pwd`` subsection has been added for
 184 EAP-PWD.
 185
 186 It is otherwise unchanged.  You chould be able to copy your old
 187 ``eap.conf`` file directly to ``mods-enabled/eap``.
 188
 189
 190 RadSec
 191 ------
 192
 193 RadSec (or RADIUS over TLS) is now supported.  RADIUS over bare TCP
 194 is also supported, but is recommended only for secure networks.
 195
 196 See ``sites-available/tls`` for complete details on using TLS.  The server
 197 can both receive incoming TLS connections, and also originate outgoing
 198 TLS connections.
 199
 200 The TLS configuration is taken from the old EAP-TLS configuration.  It
 201 is largely identical to the old EAP-TLS configuration, so it should be
 202 simple to use and configure.  It re-uses much of the EAP-TLS code,
 203 so it is well-tested and reliable.
 204
 205 Once RadSec is enabled, normal debugging mode will not work.  This is
 206 because the TLS code requires threading to work properly.  Instead of doing::
 207
 208   $ radiusd -X
 209
 210 you will need to do::
 211
 212   $ radiusd -fxx -l stdout
 213
 214
 215 PAP and User-Password
 216 ---------------------
 217
 218 From version 3.0 onwards the server no longer supports authenticating
 219 against a cleartext password in the 'User-Password' attribute. Any
 220 occurances of this (for instance, in the users file) should now be changed
 221 to 'Cleartext-Password' instead.
 222
 223 If this is not done, authentication is likely to fail.
 224
 225 If it really is impossible to do this, the following unlang inserted above
 226 the call to the pap module may be used to copy User-Password to the correct
 227 attribute::
 228
 229   if (!control:Cleartext-Password && control:User-Password) {
 230     update control {
 231       Cleartext-Password := "%{control:User-Password}"
 232     }
 233   }
 234
 235 However, this should only be seen as a temporary, not permanent, fix.