1 Upgrading to Version 3.0
2 ========================
8 The configuration for 3.0 is *largely* compatible with the 2.x.x
9 configuration. However, it is NOT possible to simply use the 2.x.x
10 configuration as-is. Instead, you should re-create it.
15 A number of configuration items have moved into the "security"
16 subsection of radiusd.conf. If you use these, you should move them.
17 Otherwise, they can be ignored.
19 The list of moved options is::
28 These entries should be moved from "radiusd.conf" to the "security"
29 subsection of that file.
34 Many names used by configuration items were inconsistent in earlier
35 versions of the server. These names have been unified in version 3.0.
37 If a file is being referenced or created the config item ``filename``
40 If a file is being created, the initial permissions are set by the
41 ``permissions`` config item.
43 If a directory hierarchy needs to be created, the permissions are set
44 by ``dir_permissions``.
46 If an external host is referenced in the context of a module the
47 ``server`` config item is used.
49 Unless the config item is a well recognised portmanteau
50 (as ``filename`` is for example), it must be written as multiple
51 distinct words separated by underscores ``_``.
53 The configuration items ``file``, ``script_file``, ``module``,
54 ``detail``, ``detailfile``, ``attrsfile``, ``perm``, ``dirperm``,
55 ``detailperm``, and ``hostname`` are deprecated. As well as any false
56 portmanteaus, and configuration items that used hyphens as word
57 delimiters. e.g. ``foo-bar`` has been changed to ``foo_bar``. Please
58 update your module configuration to use the new syntax.
60 In most cases the server will tell you the replacement config item to
61 use. As always, run the server in debugging mode to see these
67 As of version 3.0, the ``modules/`` directory no longer exists.
69 Instead, all "example" modules have been put into the
70 ``mods-available/`` directory. Modules which can be loaded by the
71 server are placed in the ``mods-enabled/`` directory. All of the
72 modules in that directory will be loaded. This means that the
73 ``instantiate`` section of radiusd.conf is less important. The only
74 reason to list a module in the ``instantiate`` section is to force
75 ordering when the modules are loaded.
77 Modules can be enabled by creating a soft link. For module ``foo``, do::
80 $ ln -s mods-available/foo mods-enabled/foo
82 To create "local" versions of the modules, we suggest copying the file
83 instead. This leaves the original file (with documentation) in the
84 ``mods-available/`` directory. Local changes should go into the
85 ``mods-enabled/`` directory.
87 Module-specific configuration files are now in the ``mods-config/``
88 directory. This change allows for better organization, and means that
89 there are fewer files in the main ``raddb`` directory. See
90 ``mods-config/README.rst`` for more details.
95 The following modules have been changed.
101 The SQL configuration has been moved from ``sql.conf`` to
102 ``mods-available/sql``. The ``sqlippool.conf`` file has also been
103 moved to ``mods-available/sqlippool``.
105 The SQL module configuration has been changed. The old connection
106 pool options are no longer accepted::
109 connect_failure_retry_delay
113 Instead, a connection pool configuration is used. This configuration
114 contains all of the functionality of the previous configuration, but
115 in a more generic form. It also is used in multiple modules, meaning
116 that there are fewer different configuration items. The mapping
117 between the configuration items is::
119 num_sql_socks -> pool { max }
120 connect_failure_retry_delay -> pool { retry_delay }
121 lifetime -> pool { lifetime }
122 max_queries -> pool { uses }
124 The pool configuration adds a number of new configuration options,
125 which allow the administrator to better control how FreeRADIUS uses
126 SQL connection pools.
128 The following parameters have been changed::
133 The logfile is intended to log SQL queries performed. If you need to
134 debug the server, use debugging mode. If ``logfile`` is set, then
135 *all* SQL queries will go to ``logfile``.
137 You can now use a NULL SQL database::
139 driver = rlm_sql_null
141 This is an empty driver which will always return "success". It is
142 intended to be used to replace the ``sql_log`` module, and to work in
143 conjunction with the ``radsqlrelay`` program. Simply take your normal
144 configuration for raddb/mods-enabled/sql, and set::
146 driver = rlm_sql_null
148 logfile = ${radacctdir}/sql.log
150 All of the SQL queries will be logged to that file. The connection
151 pool does not need to be configured for the ``null`` SQL driver. It
152 can be left as-is, or deleted from the SQL configuration file.
157 The ``rlm_sql_sybase`` module has been renamed to ``rlm_sql_freetds``
158 and the old ``rlm_sql_freetds`` module has been removed.
160 ``rlm_sql_sybase`` used the newer ct-lib API, and ``rlm_sql_freetds``
161 used an older API and was incomplete.
163 The new ``rlm_sql_freetds`` module now also supports database
164 selection on connection startup so ``use`` statements no longer
165 have to be included in queries.
170 Queries for post-auth and accounting calls have been re-arranged. The
171 SQL module will now expand the 'reference' configuration item in the
172 appropriate sub-section, and resolve this to a configuration
173 item. This behaviour is similar to rlm_linelog. This dynamic
174 expansion allows for a dynamic mapping between accounting types and
175 SQL queries. Previously, the mapping was fixed. Any "new" accounting
176 type was ignored by the module. Now, support for any accounting type
177 can be added by just adding a new target, as below.
179 Queries from v2.x.x may be manually copied to the new v3.0
180 ``dialup.conf`` file (``raddb/sql/main/<dialect>/queries.conf``).
181 When doing this you may also need to update references to the
182 accounting tables, as their definitions will now be outside of
183 the subsection containing the query.
185 The mapping from old "fixed" query to new "dynamic" query is as follows::
187 accounting_onoff_query -> accounting.type.accounting-on.query
188 accounting_update_query -> accounting.type.interim-update.query
189 accounting_update_query_alt +> accounting.type.interim-update.query
190 accounting_start_query -> accounting.type.start.query
191 accounting_start_query_alt +> accounting.type.start.query
192 accounting_stop_query -> accounting.type.stop.query
193 accounting_stop_query_alt +> accounting.type.stop.query
194 postauth_query -> post-auth.query
196 Alternatively a 2.x.x config may be patched to work with the
197 3.0 module by adding the following::
200 reference = "%{tolower:type.%{Acct-Status-Type}.query}"
203 query = "${....accounting_onoff_query}"
206 query = "${....accounting_onoff_query}"
209 query = "${....accounting_start_query}"
210 query = "${....accounting_start_query_alt}"
213 query = "${....accounting_update_query}"
214 query = "${....accounting_update_query_alt}"
217 query = "${....accounting_stop_query}"
218 query = "${....accounting_stop_query_alt}"
224 query = "${..postauth_query}"
227 In general, it is safer to migrate the configuration rather than
228 trying to "patch" it, to make it look like a v2 configuration.
230 Note that the sub-sections holding the queries are labelled
231 ``accounting-on``, and not ``accounting_on``. The reason is that the
232 names of these sections are taken directly from the
233 ``Accounting-Request`` packet, and the ``Acct-Status-Type`` field.
234 The ``sql`` module looks at the value of that field, and then looks
235 for a section of that name, in order to find the query to use.
237 That process means that the server can be extended to support any new
238 value of ``Acct-Status-Type``, simply by adding a named sub-section,
239 and a query. This behavior is preferable to that of v2, which had
240 hard-coded queries for certain ``Acct-Status-Type`` values, and was
241 ignored all other values.
246 The LDAP module configuration has been substantially changed. Please
247 read ``raddb/mods-available/ldap``. It now uses a connection pool,
248 just like the SQL module.
250 Many of the configuration items remain the same, but they have been
251 moved into subsections. This change is largely cosmetic, but it makes
252 the configuration clearer. Instead of having a large set of random
253 configuration items, they are now organized into logical groups.
255 You will need to read your old LDAP configuration, and migrate it
256 manually to the new configuration. Simply copying the old
257 configuration WILL NOT WORK.
259 Users upgrading from 2.x.x who used to call the ldap module in
260 ``post-auth`` should now set ``edir_autz = yes``, and remove the ``ldap``
261 module from the ``post-auth`` section.
263 rlm_ldap and LDAP-Group
264 ~~~~~~~~~~~~~~~~~~~~~~~
266 In 2.x.x the registration of the ``LDAP-Group`` pair comparison was done
267 by the last instance of rlm_ldap to be instantiated. In 3.0 this has
268 changed so that only the default ``ldap {}`` instance registers
271 If ``<instance>-LDAP-Group`` is already used throughout your configuration
272 no changes will be needed.
274 rlm_ldap authentication
275 ~~~~~~~~~~~~~~~~~~~~~~~
277 In 2.x.x the LDAP module had a ``set_auth_type`` configuration item,
278 which forced ``Auth-Type := ldap``. This was removed in 3.x.x as it
279 often did not work, and was not consistent with the rest of the
280 server. We generally recommend that LDAP should be used as a
281 database, and that FreeRADIUS should do authentication.
283 The only reason to use ``Auth-Type := ldap`` is when the LDAP server
284 will not supply the "known good" password to FreeRADIUS, *and* where
285 the Access-Request contains User-Password. This situation happens
286 only for Active Directory. If you think you need to force ``Auth-Type
287 := ldap`` in other situations, you are very likely to be wrong.
289 The following is an example of what should be inserted into the
290 ``authorize {}`` and ``authenticate {}`` sections of the relevant
291 virtual-servers, to get functionality equivalent to v2.x::
296 if ((ok || updated) && User-Password) {
315 The EAP configuration has been moved from ``eap.conf`` to
316 ``mods-available/eap``. A new ``pwd`` subsection has been added for
319 rlm_expiration & rlm_logintime
320 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
322 The rlm_expiration and rlm_logintime modules no longer add a ``Reply-Message``,
323 the same behaviour can be achieved checking the return code of the module and
324 adding the ``Reply-Message`` with unlang::
329 Reply-Message := "Your account has expired"
336 The ``unix`` module does not have an ``authenticate`` section. So you
337 cannot set ``Auth-Type := System``. The ``unix`` module has also been
338 deleted from the examples in ``sites-available/``. Listing it there
339 has been deprecated for many years.
341 The PAP module can do crypt authentication. It should be used instead
342 of Unix authentication.
344 The Unix module still can pull the passwords from ``/etc/passwd``, or
345 ``/etc/shadow``. This is done by listing it in the ``authorize``
346 section, as is done in the examples in ``sites-available/``. However,
347 some systems using NIS or NSS will not supply passwords to the
348 ``unix`` module. For those systems, we recommend putting users and
349 passwords into a database, instead of relying on ``/etc/passwd``.
357 Instances of rlm_date register an xlat method which can translate
358 integer and date values to an arbitrarily formatted date time
359 string, or an arbitrarily formated time string to an integer,
360 depending on the attribute type passed.
365 The ``rest`` module is used to translate RADIUS requests into
366 RESTfull HTTP requests. Currently supported body types are JSON
372 The ``unpack`` module is used to turn data buried inside of binary
373 attributes. e.g. if we have ``Class = 0x00000001020304`` then::
375 Tmp-Integer-0 := "%{unpack:&Class 4 short}"
377 will unpack octets 4 and 5 as a "short", which has value 0x0304.
378 All integers are assumed to be in network byte order.
383 The ``yubikey`` module can be used to forward yubikey OTP token
384 values to a Yubico validation server, or decrypt the token
390 The following modules have been deleted, and are no longer supported
391 in Version 3. If you are using one of these modules, your
392 configuration can probably be changed to not need it. Otherwise email
393 the freeradius-devel list, and ask about the module.
398 This module has been replaced by the "acct_unique" policy. See
399 raddb/policy.d/accounting.
401 The method for calculating the value of acct_unique has changed.
402 However, as this method was configurable, this change should not
403 matter. The only issue is in having a v2 and v3 server writing to the
404 same database at the same time. They will calculate different values
410 You should use rlm_linelog instead. That module has a superset of the
411 acctlog functionality.
416 The attr_rewrite module looked for an attribute, and then re-wrote it,
417 or created a new attribute. All of that can be done in "unlang".
419 A sample configuration in "unlang" is::
421 if (request:Calling-Station-Id) {
423 Calling-Station-Id := "...."
427 We suggest updating all uses of attr_rewrite to use unlang instead.
432 The checkval module compared two attributes. All of that can be done in "unlang"::
434 if (&request:Calling-Station-Id == &control:Calling-Station-Id) {
438 We suggest updating all uses of checkval to use unlang instead.
443 No one seems to use it. There is no sample configuration for it.
444 There is no speed advantage to using it over the "files" module.
445 Modern systems are fast enough that 10K entries can be read from the
446 "users" file in about 10ms. If you need more users than that, use a
447 real database such as SQL.
452 No one seems to use it. It has been deprecated since Version 2.0.0.
453 The "files" module was rewritten so that the "fastusers" module was no
459 No one seems to use it. Almost all of its functionality is available
465 The rlm_sim_files module has been deleted. It was never marked "stable",
466 and was never used in a production environment. There are better ways
469 If you want similar functionality, see rlm_passwd. It can read CSV
470 files, and create attributes from them.
475 This has been replaced with the "null" sql driver. See
476 raddb/mods-available/sql for an example configuration.
478 The main SQL module has more functionality than rlm_sql_log, and
479 results in less code in the server.
484 The following is a list of new / changed functionality.
489 RadSec (or RADIUS over TLS) is now supported. RADIUS over bare TCP
490 is also supported, but is recommended only for secure networks.
492 See ``sites-available/tls`` for complete details on using TLS. The server
493 can both receive incoming TLS connections, and also originate outgoing
496 The TLS configuration is taken from the old EAP-TLS configuration. It
497 is largely identical to the old EAP-TLS configuration, so it should be
498 simple to use and configure. It re-uses much of the EAP-TLS code,
499 so it is well-tested and reliable.
501 Once RadSec is enabled, normal debugging mode will not work. This is
502 because the TLS code requires threading to work properly. Instead of doing::
506 you will need to do::
508 $ radiusd -fxx -l stdout
510 That's the price to pay for using RadSec. This limitation may be
511 lifted in a future version of the server.
514 PAP and User-Password
515 ~~~~~~~~~~~~~~~~~~~~~
517 From version 3.0 onwards the server no longer supports authenticating
518 against a cleartext password in the 'User-Password' attribute. Any
519 occurences of this (for instance, in the users file) should now be changed
520 to 'Cleartext-Password' instead.
522 e.g. change entries like this::
524 bob User-Password == "hello"
528 bob Cleartext-Password := "hello"
531 If this is not done, authentication will likely fail. The server will
532 also print a helpful message in debugging mode.
534 If it really is impossible to do this, the following unlang inserted above
535 the call to the pap module may be used to copy User-Password to the correct
538 if (!control:Cleartext-Password && control:User-Password) {
540 Cleartext-Password := "%{control:User-Password}"
544 However, this should only be seen as a temporary, not permanent, fix.
545 It is better to fix your databases to use the correct configuration.
550 The unlang policy language is compatible with v2, but has a number of
551 new features. See ``man unlang`` for complete documentation.
555 Many more errors are caught when the server is starting up. Syntax
556 errors in ``unlang`` are caught, and a helpful error message is
557 printed. The error message points to the exact place where the error
560 ./raddb/sites-enabled/default[230]: Parse error in condition
561 ERROR: if (User-Name ! "bob") {
562 ERROR: ^ Invalid operator
564 ``update`` sections are more generic. Instead of doing ``update
565 reply``, you can do the following::
568 reply:Class := 0x0000
569 control:Cleartext-Password := "hello"
572 This change means that you need fewer ``update`` sections.
576 Attribute comparisons can be done via the ``&`` operator. When you
577 needed to compare two attributes, the old comparison style was::
579 if (User-Name == "%{control:Tmp-String-0}") {
581 This syntax is inefficient, as the ``Tmp-String-0`` attribute would be
582 printed to an intermediate string, causing unnecessary work. You can
583 now instead compare the two attributes directly::
585 if (&User-Name == &control:Tmp-String-0) {
587 See ``man unlang`` for more details.
591 Casts are now permitted. This allows you to force type-specific
594 if (<ipaddr>"%{sql: SELECT...}" == 127.0.0.1) {
596 This forces the string returned by the SELECT to be treated as an IP
597 address, and compare to ``127.0.0.1``. Previously, the comparison
598 would have been done as a simple string comparison.
602 IP networks are now supported::
604 if (127.0.0.1/32 == 127.0.0.1) {
606 Will be ``true``. The various comparison operators can be used to
607 check IP network membership::
609 if (127/8 > 127.0.0.1) {
611 Returns ``true``, because ``127.0.0.1`` is within the ``127/8``
612 network. However, the following comparison will return ``false``::
614 if (127/8 > 192.168.0.1) {
616 because ``192.168.0.1`` is outside of the ``127/8`` network.
620 As ``unlang`` is now pre-compiled, many compile-time optimizations are
621 done. This means that the debug output may not be exactly the same as
622 what is in the configuration files::
624 if (0 && (User-Name == "bob')) {
626 The result will always be ``false``, as the ``if 0`` prevents the
627 following ``&& ...`` from being evaluated.
629 Not only that, but the entire contents of that section will be ignored
633 this_module_does_not_exist
634 and_this_one_does_not_exist_either
637 In v2, that configuration would result in a parse error, as there is
638 no module called ``this_module_does_not_exist``. In v3, that text is
639 ignored. This ability allows you to have dynamic configurations where
640 certain parts are used (or not) depending on compile-time configuration.
642 Similarly, conditions which always evaluate to ``true`` will be
649 That configuration will never show the ``if (1)`` output in debugging mode.
655 The dialip_admin directory has been removed. No one stepped forward
656 to maintain it, and the code had not been changed in many years.