1 Upgrading to Version 3.0
2 ========================
4 The configuration for 3.0 is *largely* compatible with the 2.x.x
5 configuration. However, it is NOT possible to simply use the 2.x.x
6 configuration as-is. Instead, you should re-create it.
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.
15 The list of moved options is::
24 These entries should be moved from "radiusd.conf" to the "security"
25 subsection of that file
30 As of version 3.0, the ``modules/`` directory no longer exists.
32 Instead, all "example" modules have been put into the
33 ``mods-available/`` directory. Modules which can be loaded by the
34 server are placed in the ``mods-enabled/`` directory. All of the
35 modules in that directory will be loaded. This means that the
36 "instantiate" section of radiusd.conf is less important.
38 Modules can be enabled by creating a soft link. For module ``foo``, do::
41 $ ln -s mods-available/foo mods-enabled/foo
43 To create "local" versions of the modules, we suggest copying the file
44 instead. This leaves the original file (with documentation) in the
45 ``mods-available/`` directory. Local changes should go into the
46 ``mods-enabled/`` directory.
48 Module-specific configuration files are now in the ``mods-config/``
49 directory. This change allows for better organization, and means that
50 there are fewer files in the main ``raddb`` directory. See
51 ``mods-config/README.rst`` for more details.
56 Many names used by configuration items were inconsistent in earlier
57 versions of the server. These names have been unified in version 3.0.
59 If a file is being referenced or created the config item ``filename``
62 If a file is being created, the initial permissions are set by the
63 ``permissions`` config item.
65 If a directory hierarchy needs to be created, the permissions are set
66 by ``dir_permissions``.
68 If an external host is referenced in the context of a module the
69 ``server`` config item is used.
71 Unless the config item is a well recognised portmanteau
72 (as ``filename`` is for example), it must be written as multiple
73 distinct words separated by underscores ``_``.
75 The configuration items ``file``, ``script_file``, ``module``,
76 ``detail``, ``detailfile``, ``attrsfile``, ``perm``, ``dirperm``,
77 ``detailperm``, and ``hostname`` are deprecated. As well as any
78 faux portmanteaus, and configuration items that used hyphens
80 Please update your module configuration to use the new syntax.
82 In most cases the server will tell you the replacement config item to
83 use. As always, run the server in debugging mode to see these
89 The SQL configuration has been moved from ``sql.conf`` to
90 ``mods-available/sql``. The ``sqlippool.conf`` file has also been
91 moved to ``mods-available/sqlippool``.
93 The SQL module configuration has been changed. The old connection
94 pool options are no longer accepted::
97 connect_failure_retry_delay
101 Instead, a connection pool configuration is used. This configuration
102 contains all of the functionality of the previous configuration, but
103 in a more generic form. It also is used in multiple modules, meaning
104 that there are fewer different configuration items. The mapping
105 between the configuration items is::
107 num_sql_socks -> pool { max }
108 connect_failure_retry_delay -> NOT SUPPORTED
109 lifetime -> pool { lifetime }
110 max_queries -> pool { uses }
112 The pool configuration adds a number of new configuration options,
113 which allow the administrator to better control how FreeRADIUS uses
114 SQL connection pools.
116 The following parameters have been changed::
121 The logfile is intended to log SQL queries performed. If you need to
122 debug the server, use debugging mode. If ``logfile`` is set, then
123 *all* SQL queries will go to ``logfile``.
125 You can now use a NULL SQL database::
127 driver = rlm_sql_null
129 This is an empty driver which will always return "success". It is
130 intended to be used to replace the ``sql_log`` module, and in
131 conjunction with the ``radsqlrelay`` program. Simply take your normal
132 configuration for raddb/mods-enabled/sql, and set::
134 driver = rlm_sql_null
136 logfile = ${radacctdir}/log.sql
138 And all of the SQL queries will be logged to that file. The
139 connection pool will still need to be configured for the NULL SQL
140 driver, but the defaults will work.
145 The ``rlm_sql_sybase`` module has been renamed to ``rlm_sql_freetds``
146 and the old ``rlm_sql_freetds`` module has been removed.
148 ``rlm_sql_sybase`` used the newer ct-lib API, and ``rlm_sql_freetds``
149 used and older API and was incomplete.
151 The new ``rlm_sql_freetds`` module now also supports database
152 selection on connection startup so ``use`` statements no longer
153 have to be included in queries.
158 Queries for post-auth and accounting calls have been re-arranged. The
159 SQL module will now expand the 'reference' configuration item in the
160 appropriate sub-section, and resolve this to a configuration
161 item. This behaviour is similar to rlm_linelog. This dynamic
162 expansion allows for a dynamic mapping between accounting types and
163 SQL queries. Previously, the mapping was fixed. Any "new" accounting
164 type was ignored by the module. Now, support for any accounting type
165 can be added by just adding a new target, as below.
167 Queries from v2.x.x may be manually copied to the new v3.0
168 ``dialup.conf`` file (``raddb/sql/main/<dialect>/queries.conf``).
169 When doing this you may also need to update references to the
170 accounting tables, as their definitions will now be outside of
171 the subsection containing the query.
173 The mapping from old "fixed" query to new "dynamic" query is as follows::
175 accounting_onoff_query -> accounting.type.accounting-on.query
176 accounting_update_query -> accounting.type.interim-update.query
177 accounting_update_query_alt +> accounting.type.interim-update.query
178 accounting_start_query -> accounting.type.start.query
179 accounting_start_query_alt +> accounting.type.start.query
180 accounting_stop_query -> accounting.type.stop.query
181 accounting_stop_query_alt +> accounting.type.stop.query
182 postauth_query -> post-auth.query
184 Alternatively a 2.x.x config may be patched to work with the
185 3.0 module by adding the following::
188 reference = "%{tolower:type.%{Acct-Status-Type}.query}"
191 query = "${....accounting_onoff_query}"
194 query = "${....accounting_onoff_query}"
197 query = "${....accounting_start_query}"
198 query = "${....accounting_start_query_alt}"
201 query = "${....accounting_update_query}"
202 query = "${....accounting_update_query_alt}"
205 query = "${....accounting_stop_query}"
206 query = "${....accounting_stop_query_alt}"
212 query = "${..postauth_query}"
215 In general, it is safer to migrate the configuration rather than
216 trying to "patch" it, to make it look like a v2 configuration.
221 The LDAP module configuration has been substantially changed. Please
222 read ``raddb/mods-available/ldap``. It now uses a connection pool,
223 just like the SQL module.
225 Many of the configuration items remain the same, but they have been
226 moved into subsections. This change is largely cosmetic, but it makes
227 the configuration clearer. Instead of having a large set of random
228 configuration items, they are now organized into logical groups.
230 You will need to read your old LDAP configuration, and migrate it
231 manually to the new configuration. Simply copying the old
232 configuration WILL NOT WORK.
234 Users upgrading from 2.x.x who used to call the ldap module in
235 ``post-auth`` should now set ``edir_autz = yes``, and remove the ``ldap``
236 module from the ``post-auth`` section.
241 In 2.x.x the registration of the ``LDAP-Group`` pair comparison was done
242 by the last instance of rlm_ldap to be instantiated. In 3.0 this has
243 changed so that only the default ``ldap {}`` instance registers
246 If ``<instance>-LDAP-Group`` is already used throughout your configuration
247 no changes need to be made.
252 The EAP configuration has been moved from ``eap.conf`` to
253 ``mods-available/eap``. A new ``pwd`` subsection has been added for
256 rlm_expiration & rlm_logintime
257 -------------------------------
259 The rlm_expiration and rlm_logintime modules no longer add a ``Reply-Message``,
260 the same behaviour can be achieved checking the return code of the module and
261 adding the ``Reply-Message`` with unlang::
266 Reply-Message := "Your account has expired"
273 The unix module does not have an "authenticate" section. So you
274 cannot set "Auth-Type := System". The "unix" module has also been
275 deleted from the examples in sites-available/. Listing it there has
276 been deprecated for many years.
278 The PAP module can do crypt authentication. It should be used instead
279 of Unix authentication.
281 The Unix module still can pull the passwords from /etc/passwd, or
282 /etc/shadow. This is done by listing it in the "authorize" section,
283 as is done in the sites-available/ examples.
289 RadSec (or RADIUS over TLS) is now supported. RADIUS over bare TCP
290 is also supported, but is recommended only for secure networks.
292 See ``sites-available/tls`` for complete details on using TLS. The server
293 can both receive incoming TLS connections, and also originate outgoing
296 The TLS configuration is taken from the old EAP-TLS configuration. It
297 is largely identical to the old EAP-TLS configuration, so it should be
298 simple to use and configure. It re-uses much of the EAP-TLS code,
299 so it is well-tested and reliable.
301 Once RadSec is enabled, normal debugging mode will not work. This is
302 because the TLS code requires threading to work properly. Instead of doing::
306 you will need to do::
308 $ radiusd -fxx -l stdout
310 Sorry, but that's the price to pay for using RadSec.
312 PAP and User-Password
313 ---------------------
315 From version 3.0 onwards the server no longer supports authenticating
316 against a cleartext password in the 'User-Password' attribute. Any
317 occurences of this (for instance, in the users file) should now be changed
318 to 'Cleartext-Password' instead.
320 If this is not done, authentication will likely fail. The server will
321 also print a helpful message in debugging mode.
323 If it really is impossible to do this, the following unlang inserted above
324 the call to the pap module may be used to copy User-Password to the correct
327 if (!control:Cleartext-Password && control:User-Password) {
329 Cleartext-Password := "%{control:User-Password}"
333 However, this should only be seen as a temporary, not permanent, fix.
334 It is better to fix your databases to contain the correct
340 The following modules have been deleted, and are no longer supported
341 in Version 3. If you are using one of these modules, your
342 configuration can probably be changed to not need it. Otherwise email
343 the freeradius-devel list, and ask about the module.
348 This module has been replaced by the "acct_unique" policy. See
349 raddb/policy.d/accounting.
351 The method for calculating the value of acct_unique has changed.
352 However, as this method was configurable, this change should not
353 matter. The only issue is in having a v2 and v3 server writing to the
354 same database at the same time. They will calculate different values
360 You should use rlm_linelog instead. That module has a superset of the
361 acctlog functionality.
366 The attr_rewrite module looked for an attribute, and then re-wrote it,
367 or created a new attribute. All of that can be done in "unlang".
369 A sample configuration in "unlang" is::
371 if (request:Calling-Station-Id) {
373 Calling-Station-Id := "...."
377 We suggest updating all uses of attr_rewrite to use unlang instead.
382 The checkval module compared two attributes. All of that can be done in "unlang"::
384 if (&request:Calling-Station-Id == &control:Calling-Station-Id) {
388 We suggest updating all uses of checkval to use unlang instead.
393 No one seems to use it. There is no sample configuration for it.
394 There is no speed advantage to using it over the "files" module.
395 Modern systems are fast enough that 10K entries can be read from the
396 "users" file in about 10ms. If you need more users than that, use a
397 real database such as SQL.
402 No one seems to use it. It has been deprecated since Version 2.0.0.
403 The "files" module was rewritten so that the "fastusers" module was no
409 No one seems to use it. Almost all of its functionality is available
415 The rlm_sim_files module has been deleted. It was never marked "stable",
416 and was never used in a production environment. There are better ways
419 If you want similar functionality, see rlm_passwd. It can read CSV
420 files, and create attributes from them.
425 This has been replaced with the "null" sql driver. See
426 raddb/mods-available/sql for an example configuration.
428 The main SQL module has more functionality than rlm_sql_log, and
429 results in less code in the server.