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``.
354 In 2.x.x ``huntroups`` and ``users`` files were loaded from default locations
355 without being configured explicitly. Since 3.x.x you need to set
356 ``huntgroups`` and ``users`` configuration item(s) in module section in order
357 to get them being processed.
365 Instances of rlm_date register an xlat method which can translate
366 integer and date values to an arbitrarily formatted date time
367 string, or an arbitrarily formated time string to an integer,
368 depending on the attribute type passed.
373 The ``rest`` module is used to translate RADIUS requests into
374 RESTfull HTTP requests. Currently supported body types are JSON
380 The ``unpack`` module is used to turn data buried inside of binary
381 attributes. e.g. if we have ``Class = 0x00000001020304`` then::
383 Tmp-Integer-0 := "%{unpack:&Class 4 short}"
385 will unpack octets 4 and 5 as a "short", which has value 0x0304.
386 All integers are assumed to be in network byte order.
391 The ``yubikey`` module can be used to forward yubikey OTP token
392 values to a Yubico validation server, or decrypt the token
398 The following modules have been deleted, and are no longer supported
399 in Version 3. If you are using one of these modules, your
400 configuration can probably be changed to not need it. Otherwise email
401 the freeradius-devel list, and ask about the module.
406 This module has been replaced by the "acct_unique" policy. See
407 raddb/policy.d/accounting.
409 The method for calculating the value of acct_unique has changed.
410 However, as this method was configurable, this change should not
411 matter. The only issue is in having a v2 and v3 server writing to the
412 same database at the same time. They will calculate different values
418 You should use rlm_linelog instead. That module has a superset of the
419 acctlog functionality.
424 The attr_rewrite module looked for an attribute, and then re-wrote it,
425 or created a new attribute. All of that can be done in "unlang".
427 A sample configuration in "unlang" is::
429 if (request:Calling-Station-Id) {
431 Calling-Station-Id := "...."
435 We suggest updating all uses of attr_rewrite to use unlang instead.
440 The checkval module compared two attributes. All of that can be done in "unlang"::
442 if (&request:Calling-Station-Id == &control:Calling-Station-Id) {
446 We suggest updating all uses of checkval to use unlang instead.
451 No one seems to use it. There is no sample configuration for it.
452 There is no speed advantage to using it over the "files" module.
453 Modern systems are fast enough that 10K entries can be read from the
454 "users" file in about 10ms. If you need more users than that, use a
455 real database such as SQL.
460 No one seems to use it. It has been deprecated since Version 2.0.0.
461 The "files" module was rewritten so that the "fastusers" module was no
467 No one seems to use it. Almost all of its functionality is available
473 The rlm_sim_files module has been deleted. It was never marked "stable",
474 and was never used in a production environment. There are better ways
477 If you want similar functionality, see rlm_passwd. It can read CSV
478 files, and create attributes from them.
483 This has been replaced with the "null" sql driver. See
484 raddb/mods-available/sql for an example configuration.
486 The main SQL module has more functionality than rlm_sql_log, and
487 results in less code in the server.
492 The following is a list of new / changed functionality.
497 RadSec (or RADIUS over TLS) is now supported. RADIUS over bare TCP
498 is also supported, but is recommended only for secure networks.
500 See ``sites-available/tls`` for complete details on using TLS. The server
501 can both receive incoming TLS connections, and also originate outgoing
504 The TLS configuration is taken from the old EAP-TLS configuration. It
505 is largely identical to the old EAP-TLS configuration, so it should be
506 simple to use and configure. It re-uses much of the EAP-TLS code,
507 so it is well-tested and reliable.
509 Once RadSec is enabled, normal debugging mode will not work. This is
510 because the TLS code requires threading to work properly. Instead of doing::
514 you will need to do::
516 $ radiusd -fxx -l stdout
518 That's the price to pay for using RadSec. This limitation may be
519 lifted in a future version of the server.
522 PAP and User-Password
523 ~~~~~~~~~~~~~~~~~~~~~
525 From version 3.0 onwards the server no longer supports authenticating
526 against a cleartext password in the 'User-Password' attribute. Any
527 occurences of this (for instance, in the users file) should now be changed
528 to 'Cleartext-Password' instead.
530 e.g. change entries like this::
532 bob User-Password == "hello"
536 bob Cleartext-Password := "hello"
539 If this is not done, authentication will likely fail. The server will
540 also print a helpful message in debugging mode.
542 If it really is impossible to do this, the following unlang inserted above
543 the call to the pap module may be used to copy User-Password to the correct
546 if (!control:Cleartext-Password && control:User-Password) {
548 Cleartext-Password := "%{control:User-Password}"
552 However, this should only be seen as a temporary, not permanent, fix.
553 It is better to fix your databases to use the correct configuration.
558 The unlang policy language is compatible with v2, but has a number of
559 new features. See ``man unlang`` for complete documentation.
563 Many more errors are caught when the server is starting up. Syntax
564 errors in ``unlang`` are caught, and a helpful error message is
565 printed. The error message points to the exact place where the error
568 ./raddb/sites-enabled/default[230]: Parse error in condition
569 ERROR: if (User-Name ! "bob") {
570 ERROR: ^ Invalid operator
572 ``update`` sections are more generic. Instead of doing ``update
573 reply``, you can do the following::
576 reply:Class := 0x0000
577 control:Cleartext-Password := "hello"
580 This change means that you need fewer ``update`` sections.
584 Attribute comparisons can be done via the ``&`` operator. When you
585 needed to compare two attributes, the old comparison style was::
587 if (User-Name == "%{control:Tmp-String-0}") {
589 This syntax is inefficient, as the ``Tmp-String-0`` attribute would be
590 printed to an intermediate string, causing unnecessary work. You can
591 now instead compare the two attributes directly::
593 if (&User-Name == &control:Tmp-String-0) {
595 See ``man unlang`` for more details.
599 Casts are now permitted. This allows you to force type-specific
602 if (<ipaddr>"%{sql: SELECT...}" == 127.0.0.1) {
604 This forces the string returned by the SELECT to be treated as an IP
605 address, and compare to ``127.0.0.1``. Previously, the comparison
606 would have been done as a simple string comparison.
610 IP networks are now supported::
612 if (127.0.0.1/32 == 127.0.0.1) {
614 Will be ``true``. The various comparison operators can be used to
615 check IP network membership::
617 if (127/8 > 127.0.0.1) {
619 Returns ``true``, because ``127.0.0.1`` is within the ``127/8``
620 network. However, the following comparison will return ``false``::
622 if (127/8 > 192.168.0.1) {
624 because ``192.168.0.1`` is outside of the ``127/8`` network.
628 As ``unlang`` is now pre-compiled, many compile-time optimizations are
629 done. This means that the debug output may not be exactly the same as
630 what is in the configuration files::
632 if (0 && (User-Name == "bob')) {
634 The result will always be ``false``, as the ``if 0`` prevents the
635 following ``&& ...`` from being evaluated.
637 Not only that, but the entire contents of that section will be ignored
641 this_module_does_not_exist
642 and_this_one_does_not_exist_either
645 In v2, that configuration would result in a parse error, as there is
646 no module called ``this_module_does_not_exist``. In v3, that text is
647 ignored. This ability allows you to have dynamic configurations where
648 certain parts are used (or not) depending on compile-time configuration.
650 Similarly, conditions which always evaluate to ``true`` will be
657 That configuration will never show the ``if (1)`` output in debugging mode.
663 The dialip_admin directory has been removed. No one stepped forward
664 to maintain it, and the code had not been changed in many years.