diff options
Diffstat (limited to 'raddb/README.rst')
| -rw-r--r-- | raddb/README.rst | 665 |
1 files changed, 665 insertions, 0 deletions
diff --git a/raddb/README.rst b/raddb/README.rst new file mode 100644 index 0000000..e3c41a7 --- /dev/null +++ b/raddb/README.rst @@ -0,0 +1,665 @@ +Upgrading to Version 3.2 +======================== + +.. contents:: Sections + :depth: 2 + +.. important:: + The configuration for 3.2 is compatible with 3.0. The only change + is that the `correct_escapes` configuration has been removed, and + is not the default. + +Security +-------- + +A number of configuration items have moved into the "security" +subsection of radiusd.conf. If you use these, you should move them. +Otherwise, they can be ignored. + +The list of moved options is:: + + chroot + user + group + allow_core_dumps + reject_delay + status_server + +These entries should be moved from "radiusd.conf" to the "security" +subsection of that file. + +Naming +------ + +Many names used by configuration items were inconsistent in earlier +versions of the server. These names have been unified in version 3. + +If a file is being referenced or created the config item ``filename`` +is used. + +If a file is being created, the initial permissions are set by the +``permissions`` config item. + +If a directory hierarchy needs to be created, the permissions are set +by ``dir_permissions``. + +If an external host is referenced in the context of a module the +``server`` config item is used. + +Unless the config item is a well recognised portmanteau +(as ``filename`` is for example), it must be written as multiple +distinct words separated by underscores ``_``. + +The configuration items ``file``, ``script_file``, ``module``, +``detail``, ``detailfile``, ``attrsfile``, ``perm``, ``dirperm``, +``detailperm``, and ``hostname`` are deprecated. As well as any false +portmanteaus, and configuration items that used hyphens as word +delimiters. e.g. ``foo-bar`` has been changed to ``foo_bar``. Please +update your module configuration to use the new syntax. + +In most cases the server will tell you the replacement config item to +use. As always, run the server in debugging mode to see these +messages. + +Modules Directory +----------------- + +As of version 3, the ``modules/`` directory no longer exists. + +Instead, all "example" modules have been put into the +``mods-available/`` directory. Modules which can be loaded by the +server are placed in the ``mods-enabled/`` directory. All of the +modules in that directory will be loaded. This means that the +``instantiate`` section of radiusd.conf is less important. The only +reason to list a module in the ``instantiate`` section is to force +ordering when the modules are loaded. + +Modules can be enabled by creating a soft link. For module ``foo``, do:: + + $ cd raddb/mods-enabled + $ ln -s ../mods-available/foo + +To create "local" versions of the modules, we suggest copying the file +instead. This leaves the original file (with documentation) in the +``mods-available/`` directory. Local changes should go into the +``mods-enabled/`` directory. + +Module-specific configuration files are now in the ``mods-config/`` +directory. This change allows for better organization, and means that +there are fewer files in the main ``raddb`` directory. See +``mods-config/README.rst`` for more details. + +Changed Modules +--------------- + +The following modules have been changed. + + +rlm_sql +~~~~~~~ + +The SQL configuration has been moved from ``sql.conf`` to +``mods-available/sql``. The ``sqlippool.conf`` file has also been +moved to ``mods-available/sqlippool``. + +The SQL module configuration has been changed. The old connection +pool options are no longer accepted:: + + num_sql_socks + connect_failure_retry_delay + lifetime + max_queries + +Instead, a connection pool configuration is used. This configuration +contains all of the functionality of the previous configuration, but +in a more generic form. It also is used in multiple modules, meaning +that there are fewer different configuration items. The mapping +between the configuration items is:: + + num_sql_socks -> pool { max } + connect_failure_retry_delay -> pool { retry_delay } + lifetime -> pool { lifetime } + max_queries -> pool { uses } + +The pool configuration adds a number of new configuration options, +which allow the administrator to better control how FreeRADIUS uses +SQL connection pools. + +The following parameters have been changed:: + + trace -> removed + tracefile -> logfile + +The logfile is intended to log SQL queries performed. If you need to +debug the server, use debugging mode. If ``logfile`` is set, then +*all* SQL queries will go to ``logfile``. + +You can now use a NULL SQL database:: + + driver = rlm_sql_null + +This is an empty driver which will always return "success". It is +intended to be used to replace the ``sql_log`` module, and to work in +conjunction with the ``radsqlrelay`` program. Simply take your normal +configuration for raddb/mods-enabled/sql, and set:: + + driver = rlm_sql_null + ... + logfile = ${radacctdir}/sql.log + +All of the SQL queries will be logged to that file. The connection +pool does not need to be configured for the ``null`` SQL driver. It +can be left as-is, or deleted from the SQL configuration file. + +rlm_sql_sybase +~~~~~~~~~~~~~~ + +The ``rlm_sql_sybase`` module has been renamed to ``rlm_sql_freetds`` +and the old ``rlm_sql_freetds`` module has been removed. + +``rlm_sql_sybase`` used the newer ct-lib API, and ``rlm_sql_freetds`` +used an older API and was incomplete. + +The new ``rlm_sql_freetds`` module now also supports database +selection on connection startup so ``use`` statements no longer +have to be included in queries. + +sql/dialup.conf +~~~~~~~~~~~~~~~ + +Queries for post-auth and accounting calls have been re-arranged. The +SQL module will now expand the 'reference' configuration item in the +appropriate sub-section, and resolve this to a configuration +item. This behaviour is similar to rlm_linelog. This dynamic +expansion allows for a dynamic mapping between accounting types and +SQL queries. Previously, the mapping was fixed. Any "new" accounting +type was ignored by the module. Now, support for any accounting type +can be added by just adding a new target, as below. + +Queries from v2 may be manually copied to the new v3 +``dialup.conf`` file (``raddb/mods-config/sql/main/<dialect>/queries.conf``). +When doing this you may also need to update references to the +accounting tables, as their definitions will now be outside of +the subsection containing the query. + +The mapping from old "fixed" query to new "dynamic" query is as follows:: + + accounting_onoff_query -> accounting.type.accounting-on.query + accounting_update_query -> accounting.type.interim-update.query + accounting_update_query_alt +> accounting.type.interim-update.query + accounting_start_query -> accounting.type.start.query + accounting_start_query_alt +> accounting.type.start.query + accounting_stop_query -> accounting.type.stop.query + accounting_stop_query_alt +> accounting.type.stop.query + postauth_query -> post-auth.query + +Alternatively a v2 config may be patched to work with the +v3 module by adding the following:: + + accounting { + reference = "%{tolower:type.%{Acct-Status-Type}.query}" + type { + accounting-on { + query = "${....accounting_onoff_query}" + } + accounting-off { + query = "${....accounting_onoff_query}" + } + start { + query = "${....accounting_start_query}" + query = "${....accounting_start_query_alt}" + } + interim-update { + query = "${....accounting_update_query}" + query = "${....accounting_update_query_alt}" + } + stop { + query = "${....accounting_stop_query}" + query = "${....accounting_stop_query_alt}" + } + } + } + + post-auth { + query = "${..postauth_query}" + } + +In general, it is safer to migrate the configuration rather than +trying to "patch" it, to make it look like a v2 configuration. + +Note that the sub-sections holding the queries are labelled +``accounting-on``, and not ``accounting_on``. The reason is that the +names of these sections are taken directly from the +``Accounting-Request`` packet, and the ``Acct-Status-Type`` field. +The ``sql`` module looks at the value of that field, and then looks +for a section of that name, in order to find the query to use. + +That process means that the server can be extended to support any new +value of ``Acct-Status-Type``, simply by adding a named sub-section, +and a query. This behavior is preferable to that of v2, which had +hard-coded queries for certain ``Acct-Status-Type`` values, and was +ignored all other values. + +rlm_ldap +~~~~~~~~ + +The LDAP module configuration has been substantially changed. Please +read ``raddb/mods-available/ldap``. It now uses a connection pool, +just like the SQL module. + +Many of the configuration items remain the same, but they have been +moved into subsections. This change is largely cosmetic, but it makes +the configuration clearer. Instead of having a large set of random +configuration items, they are now organized into logical groups. + +You will need to read your old LDAP configuration, and migrate it +manually to the new configuration. Simply copying the old +configuration WILL NOT WORK. + +Users upgrading from v2 who used to call the ldap module in +``post-auth`` should now set ``edir_autz = yes``, and remove the ``ldap`` +module from the ``post-auth`` section. + +rlm_ldap and LDAP-Group +~~~~~~~~~~~~~~~~~~~~~~~ + +In v2 the registration of the ``LDAP-Group`` pair comparison was done +by the last instance of rlm_ldap to be instantiated. In v3 this has +changed so that only the default ``ldap {}`` instance registers +``LDAP-Group``. + +If ``<instance>-LDAP-Group`` is already used throughout your configuration +no changes will be needed. + +rlm_ldap authentication +~~~~~~~~~~~~~~~~~~~~~~~ + +In v2 the LDAP module had a ``set_auth_type`` configuration item, +which forced ``Auth-Type := ldap``. This was removed in 3.x.x as it +often did not work, and was not consistent with the rest of the +server. We generally recommend that LDAP should be used as a +database, and that FreeRADIUS should do authentication. + +The only reason to use ``Auth-Type := ldap`` is when the LDAP server +will not supply the "known good" password to FreeRADIUS, *and* where +the Access-Request contains User-Password. This situation happens +only for Active Directory. If you think you need to force ``Auth-Type +:= ldap`` in other situations, you are very likely to be wrong. + +The following is an example of what should be inserted into the +``authorize {}`` and ``authenticate {}`` sections of the relevant +virtual-servers, to get functionality equivalent to v2.x:: + + authorize { + ... + ldap + if ((ok || updated) && User-Password) { + update control { + Auth-Type := ldap + } + } + ... + } + + authenticate { + ... + Auth-Type ldap { + ldap + } + ... + } + +rlm_eap +~~~~~~~ + +The EAP configuration has been moved from ``eap.conf`` to +``mods-available/eap``. A new ``pwd`` subsection has been added for +EAP-PWD. + +rlm_expiration & rlm_logintime +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The rlm_expiration and rlm_logintime modules no longer add a ``Reply-Message``, +the same behaviour can be achieved checking the return code of the module and +adding the ``Reply-Message`` with unlang:: + + expiration + if (userlock) { + update reply { + Reply-Message := "Your account has expired" + } + } + +rlm_unix +~~~~~~~~ + +The ``unix`` module does not have an ``authenticate`` section. So you +cannot set ``Auth-Type := System``. The ``unix`` module has also been +deleted from the examples in ``sites-available/``. Listing it there +has been deprecated for many years. + +The PAP module can do crypt authentication. It should be used instead +of Unix authentication. + +The Unix module still can pull the passwords from ``/etc/passwd``, or +``/etc/shadow``. This is done by listing it in the ``authorize`` +section, as is done in the examples in ``sites-available/``. However, +some systems using NIS or NSS will not supply passwords to the +``unix`` module. For those systems, we recommend putting users and +passwords into a database, instead of relying on ``/etc/passwd``. + +rlm_preprocess +~~~~~~~~~~~~~~ + +In v2 ``huntroups`` and ``users`` files were loaded from default locations +without being configured explicitly. Since 3.x.x you need to set +``huntgroups`` and ``users`` configuration item(s) in module section in order +to get them being processed. + +New Modules +----------- + +rlm_date +~~~~~~~~ + +Instances of rlm_date register an xlat method which can translate +integer and date values to an arbitrarily formatted date time +string, or an arbitrarily formated time string to an integer, +depending on the attribute type passed. + +rlm_rest +~~~~~~~~ + +The ``rest`` module is used to translate RADIUS requests into +RESTfull HTTP requests. Currently supported body types are JSON +and POST. + +rlm_unpack +~~~~~~~~~~ + +The ``unpack`` module is used to turn data buried inside of binary +attributes. e.g. if we have ``Class = 0x00000001020304`` then:: + + Tmp-Integer-0 := "%{unpack:&Class 4 short}" + +will unpack octets 4 and 5 as a "short", which has value 0x0304. +All integers are assumed to be in network byte order. + +rlm_yubikey +~~~~~~~~~~~ + +The ``yubikey`` module can be used to forward yubikey OTP token +values to a Yubico validation server, or decrypt the token +using a PSK. + +Deleted Modules +--------------- + +The following modules have been deleted, and are no longer supported +in Version 3. If you are using one of these modules, your +configuration can probably be changed to not need it. Otherwise email +the freeradius-devel list, and ask about the module. + +rlm_acct_unique +~~~~~~~~~~~~~~~ + +This module has been replaced by the "acct_unique" policy. See +raddb/policy.d/accounting. + +The method for calculating the value of acct_unique has changed. +However, as this method was configurable, this change should not +matter. The only issue is in having a v2 and v3 server writing to the +same database at the same time. They will calculate different values +for Acct-Unique-Id. + +rlm_acctlog +~~~~~~~~~~~ + +You should use rlm_linelog instead. That module has a superset of the +acctlog functionality. + +rlm_attr_rewrite +~~~~~~~~~~~~~~~~ + +The attr_rewrite module looked for an attribute, and then re-wrote it, +or created a new attribute. All of that can be done in "unlang". + +A sample configuration in "unlang" is:: + + if (request:Calling-Station-Id) { + update request { + Calling-Station-Id := "...." + } + } + +We suggest updating all uses of attr_rewrite to use unlang instead. + +rlm_checkval +~~~~~~~~~~~~ + +The checkval module compared two attributes. All of that can be done in "unlang":: + + if (&request:Calling-Station-Id == &control:Calling-Station-Id) { + ok + } + +We suggest updating all uses of checkval to use unlang instead. + +rlm_dbm +~~~~~~~ + +No one seems to use it. There is no sample configuration for it. +There is no speed advantage to using it over the "files" module. +Modern systems are fast enough that 10K entries can be read from the +"users" file in about 10ms. If you need more users than that, use a +real database such as SQL. + +rlm_fastusers +~~~~~~~~~~~~~ + +No one seems to use it. It has been deprecated since Version 2.0.0. +The "files" module was rewritten so that the "fastusers" module was no +longer necessary. + +rlm_policy +~~~~~~~~~~ + +No one seems to use it. Almost all of its functionality is available +via "unlang". + +rlm_sim_files +~~~~~~~~~~~~~ + +The rlm_sim_files module has been deleted. It was never marked "stable", +and was never used in a production environment. There are better ways +to test EAP. + +If you want similar functionality, see rlm_passwd. It can read CSV +files, and create attributes from them. + +rlm_sql_log +~~~~~~~~~~~ + +This has been replaced with the "null" sql driver. See +raddb/mods-available/sql for an example configuration. + +The main SQL module has more functionality than rlm_sql_log, and +results in less code in the server. + +Other Functionality +------------------- + +The following is a list of new / changed functionality. + +RadSec +~~~~~~ + +RadSec (or RADIUS over TLS) is now supported. RADIUS over bare TCP +is also supported, but is recommended only for secure networks. + +See ``sites-available/tls`` for complete details on using TLS. The server +can both receive incoming TLS connections, and also originate outgoing +TLS connections. + +The TLS configuration is taken from the old EAP-TLS configuration. It +is largely identical to the old EAP-TLS configuration, so it should be +simple to use and configure. It re-uses much of the EAP-TLS code, +so it is well-tested and reliable. + +Once RadSec is enabled, normal debugging mode will not work. This is +because the TLS code requires threading to work properly. Instead of doing:: + + $ radiusd -X + +you will need to do:: + + $ radiusd -fxx -l stdout + +That's the price to pay for using RadSec. This limitation may be +lifted in a future version of the server. + + +PAP and User-Password +~~~~~~~~~~~~~~~~~~~~~ + +From version 3 onwards the server no longer supports authenticating +against a cleartext password in the 'User-Password' attribute. Any +occurences of this (for instance, in the users file) should now be changed +to 'Cleartext-Password' instead. + +e.g. change entries like this:: + + bob User-Password == "hello" + +to ones like this:: + + bob Cleartext-Password := "hello" + + +If this is not done, authentication will likely fail. The server will +also print a helpful message in debugging mode. + +If it really is impossible to do this, the following unlang inserted above +the call to the pap module may be used to copy User-Password to the correct +attribute:: + + if (!control:Cleartext-Password && control:User-Password) { + update control { + Cleartext-Password := "%{control:User-Password}" + } + } + +However, this should only be seen as a temporary, not permanent, fix. +It is better to fix your databases to use the correct configuration. + +Unlang +~~~~~~ + +The unlang policy language is compatible with v2, but has a number of +new features. See ``man unlang`` for complete documentation. + +ERRORS + +Many more errors are caught when the server is starting up. Syntax +errors in ``unlang`` are caught, and a helpful error message is +printed. The error message points to the exact place where the error +occurred:: + + ./raddb/sites-enabled/default[230]: Parse error in condition + ERROR: if (User-Name ! "bob") { + ERROR: ^ Invalid operator + +``update`` sections are more generic. Instead of doing ``update +reply``, you can do the following:: + + update { + reply:Class := 0x0000 + control:Cleartext-Password := "hello" + } + +This change means that you need fewer ``update`` sections. + +COMPARISONS + +Attribute comparisons can be done via the ``&`` operator. When you +needed to compare two attributes, the old comparison style was:: + + if (User-Name == "%{control:Tmp-String-0}") { + +This syntax is inefficient, as the ``Tmp-String-0`` attribute would be +printed to an intermediate string, causing unnecessary work. You can +now instead compare the two attributes directly:: + + if (&User-Name == &control:Tmp-String-0) { + +See ``man unlang`` for more details. + +CASTS + +Casts are now permitted. This allows you to force type-specific +comparisons:: + + if (<ipaddr>"%{sql: SELECT...}" == 127.0.0.1) { + +This forces the string returned by the SELECT to be treated as an IP +address, and compare to ``127.0.0.1``. Previously, the comparison +would have been done as a simple string comparison. + +NETWORKS + +IP networks are now supported:: + + if (127.0.0.1/32 == 127.0.0.1) { + +Will be ``true``. The various comparison operators can be used to +check IP network membership:: + + if (127/8 > 127.0.0.1) { + +Returns ``true``, because ``127.0.0.1`` is within the ``127/8`` +network. However, the following comparison will return ``false``:: + + if (127/8 > 192.168.0.1) { + +because ``192.168.0.1`` is outside of the ``127/8`` network. + +OPTIMIZATION + +As ``unlang`` is now pre-compiled, many compile-time optimizations are +done. This means that the debug output may not be exactly the same as +what is in the configuration files:: + + if (0 && (User-Name == "bob')) { + +The result will always be ``false``, as the ``if 0`` prevents the +following ``&& ...`` from being evaluated. + +Not only that, but the entire contents of that section will be ignored +entirely:: + + if (0) { + this_module_does_not_exist + and_this_one_does_not_exist_either + } + +In v2, that configuration would result in a parse error, as there is +no module called ``this_module_does_not_exist``. In v3, that text is +ignored. This ability allows you to have dynamic configurations where +certain parts are used (or not) depending on compile-time configuration. + +Similarly, conditions which always evaluate to ``true`` will be +optimized away:: + + if (1) { + files + } + +That configuration will never show the ``if (1)`` output in debugging mode. + + +Dialup_admin +------------ + +The dialup_admin directory has been removed. No one stepped forward +to maintain it, and the code had not been changed in many years. + |