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 EAP
 155 ---
 156
 157 The EAP configuration has been moved from ``eap.conf`` to
 158 ``mods-available/eap``.  A new ``pwd`` subsection has been added for
 159 EAP-PWD.
 160
 161 It is otherwise unchanged.  You chould be able to copy your old
 162 ``eap.conf`` file directly to ``mods-enabled/eap``.
 163
 164
 165 RadSec
 166 ------
 167
 168 RadSec (or RADIUS over TLS) is now supported.  RADIUS over bare TCP
 169 is also supported, but is recommended only for secure networks.
 170
 171 See ``sites-available/tls`` for complete details on using TLS.  The server
 172 can both receive incoming TLS connections, and also originate outgoing
 173 TLS connections.
 174
 175 The TLS configuration is taken from the old EAP-TLS configuration.  It
 176 is largely identical to the old EAP-TLS configuration, so it should be
 177 simple to use and configure.  It re-uses much of the EAP-TLS code,
 178 so it is well-tested and reliable.
 179
 180 Once RadSec is enabled, normal debugging mode will not work.  This is
 181 because the TLS code requires threading to work properly.  Instead of doing::
 182
 183   $ radiusd -X
 184
 185 you will need to do::
 186
 187   $ radiusd -fxx -l stdout