1 Upgrading to Version 3.0
2 ========================
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.
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::
28 As of version 3.0, the ``modules/`` directory no longer exists.
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.
34 Modules can be enabled by creating a soft link. For module ``foo``, do::
37 $ ln -s mods-available/foo mods-enabled/foo
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.
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``.
52 The SQL module configuration has been changed. The old connection
53 pool options are no longer understood::
56 connect_failure_retry_delay
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::
66 num_sql_socks -> pool { max }
67 connect_failure_retry_delay -> NOT SUPPORTED
68 lifetime -> pool { lifetime }
69 max_queries -> pool { uses }
71 The pool configuration adds a number of new configuration options,
72 which allow the administrator to better control how FreeRADIUS uses
75 The following parameters have been changed::
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``.
84 You can now use a NULL SQL database::
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::
95 logfile = ${radacctdir}/log.sql
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.
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.
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.
114 The mapping is as follows::
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
127 Alternatively a v2.x.x config may be patched to work with the
128 v3.x.x module by adding the following::
131 reference = "%{tolower:type.%{Acct-Status-Type}.query}"
134 query = "${....accounting_onoff_query}"
137 query = "${....accounting_onoff_query}"
140 query = "${....accounting_start_query}"
141 query = "${....accounting_start_query_alt}"
144 query = "${....accounting_update_query}"
145 query = "${....accounting_update_query_alt}"
148 query = "${....accounting_stop_query}"
149 query = "${....accounting_stop_query_alt}"
155 query = "${..postauth_query}"
161 The LDAP module configuration has been substantially changed. Please
162 read raddb/mods-available/ldap. It now uses a connection pool, just
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.
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.
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.
182 The EAP configuration has been moved from ``eap.conf`` to
183 ``mods-available/eap``. A new ``pwd`` subsection has been added for
186 It is otherwise unchanged. You chould be able to copy your old
187 ``eap.conf`` file directly to ``mods-enabled/eap``.
193 RadSec (or RADIUS over TLS) is now supported. RADIUS over bare TCP
194 is also supported, but is recommended only for secure networks.
196 See ``sites-available/tls`` for complete details on using TLS. The server
197 can both receive incoming TLS connections, and also originate outgoing
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.
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::
210 you will need to do::
212 $ radiusd -fxx -l stdout
215 PAP and User-Password
216 ---------------------
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.
223 If this is not done, authentication is likely to fail.
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
229 if (!control:Cleartext-Password && control:User-Password) {
231 Cleartext-Password := "%{control:User-Password}"
235 However, this should only be seen as a temporary, not permanent, fix.