diff options
Diffstat (limited to 'doc/antora/modules/installation')
| -rw-r--r-- | doc/antora/modules/installation/nav.adoc | 5 | ||||
| -rw-r--r-- | doc/antora/modules/installation/pages/dependencies.adoc | 58 | ||||
| -rw-r--r-- | doc/antora/modules/installation/pages/index.adoc | 15 | ||||
| -rw-r--r-- | doc/antora/modules/installation/pages/packages.adoc | 22 | ||||
| -rw-r--r-- | doc/antora/modules/installation/pages/source.adoc | 199 | ||||
| -rw-r--r-- | doc/antora/modules/installation/pages/upgrade.adoc | 737 |
6 files changed, 1036 insertions, 0 deletions
diff --git a/doc/antora/modules/installation/nav.adoc b/doc/antora/modules/installation/nav.adoc new file mode 100644 index 0000000..26ce32e --- /dev/null +++ b/doc/antora/modules/installation/nav.adoc @@ -0,0 +1,5 @@ +* xref:index.adoc[Installing and upgrading] +** xref:packages.adoc[Install from packages] +** xref:dependencies.adoc[Dependencies] +** xref:source.adoc[Build from source] +** xref:upgrade.adoc[Upgrading to v3] diff --git a/doc/antora/modules/installation/pages/dependencies.adoc b/doc/antora/modules/installation/pages/dependencies.adoc new file mode 100644 index 0000000..e910e76 --- /dev/null +++ b/doc/antora/modules/installation/pages/dependencies.adoc @@ -0,0 +1,58 @@ += FreeRADIUS Dependencies + +Some external dependencies must be installed before building or +running FreeRADIUS. The core depends on two mandatory libraries: +`libtalloc` for memory management and `libkqueue` for event +handling. + +Many of the modules also have optional dependencies. For example, +the LDAP module requires LDAP client libraries to be installed +and database modules need their respective database client +libraries. + +If building from source code, the configure stage will check for +the optional dependencies. Any missing libraries will cause that +particular module to be skipped. + +== Libraries + +=== libtalloc + +Talloc is a memory allocation library available at +https://talloc.samba.org/talloc/doc/html/index.html + +*OSX* + +`# brew install talloc` + +*Debian, Ubuntu and `dpkg`-based systems* + +`# apt-get install libtalloc-dev` + +*RedHat or CentOS* + +``` +# subscription-manager repos --enable rhel-7-server-optional-rpms +# yum install libtalloc-dev +``` + +=== kqueue + +Kqueue is an event / timer API originally written for BSD systems. +It is _much_ simpler to use than third-party event libraries. A +library, `libkqueue`, is available for Linux systems. + +*OSX* + +_kqueue is already available, there is nothing to install._ + +*Debian, Ubuntu and `dpkg`-based systems* + +`# apt-get install libkqueue-dev` + +*RedHat or CentOS* + +``` +# subscription-manager repos --enable rhel-7-server-optional-rpms +# yum install libkqueue-dev +``` diff --git a/doc/antora/modules/installation/pages/index.adoc b/doc/antora/modules/installation/pages/index.adoc new file mode 100644 index 0000000..b810078 --- /dev/null +++ b/doc/antora/modules/installation/pages/index.adoc @@ -0,0 +1,15 @@ +== Installation + +FreeRADIUS is available from multiple sources: + +* Official xref:packages.adoc[Network RADIUS packages] +* xref:source.adoc[Source code] +* Many Operating System distributions + +We highly recommend using the official packages from Network +RADIUS, where available. + +The documents in this section cover details of the above +installation methods, as well as instructions on building +packages locally. + diff --git a/doc/antora/modules/installation/pages/packages.adoc b/doc/antora/modules/installation/pages/packages.adoc new file mode 100644 index 0000000..ffc52cd --- /dev/null +++ b/doc/antora/modules/installation/pages/packages.adoc @@ -0,0 +1,22 @@ +== Install from packages + +Network RADIUS provide pre-built binary packages of FreeRADIUS for +common Linux distributions. This is the recommended installation +method when packages are available for your system. + +The official http://packages.networkradius.com[Network RADIUS +packages] page contains recent FreeRADIUS packages and +installation instructions. + +=== Distribution-supplied packages + +While many Operating System distributions ship FreeRADIUS +packages, the versions they include are often years out of date. +As well as missing out on the latest bug fixes and features, this +also means that it is very hard to know if an issue encountered is +still a problem or if it is fixed in the latest release. + +Therefore, whilst the distribution-supplied packages can often be +the most convenient to install, we do not usually recommend using +them. + diff --git a/doc/antora/modules/installation/pages/source.adoc b/doc/antora/modules/installation/pages/source.adoc new file mode 100644 index 0000000..cf40a79 --- /dev/null +++ b/doc/antora/modules/installation/pages/source.adoc @@ -0,0 +1,199 @@ +== Building from Source + +We recommend xref:packages.adoc[installing from packages] if +possible. Full instructions on building and installing from source +code follow. + +The mandatory xref:installation:dependencies.adoc[dependencies] +must be installed before FreeRADIUS can be built. These dependencies +are `libtalloc` and `libkqueue`, which FreeRADIUS uses for memory +management, and platform-independent event handling. + +Per-module dependencies that enable support for external services +such as LDAP, SQL, etc, are optional. They must be installed for +any modules that are to be used. The FreeRADIUS `./configure` step +will automatically detect if each module has its dependencies met +and automatically enable support for them. If the features you +require are not enabled you should inspect the configure script +output to figure out which additional development libraries need +to be installed. + +The FreeRADIUS source may be obtained from a number of locations: + +* Download the latest version of the FreeRADIUS source from + https://www.freeradius.org/releases/[the FreeRADIUS web site]; or +* download directly from the + ftp://ftp.freeradius.org/pub/freeradius/[FreeRADIUS FTP site]; or +* download from + https://github.com/FreeRADIUS/freeradius-server/[GitHub]. + +The file wil be name something like: `freeradius-server-3.0.22.tar.gz`. +Later versions will be `3.0.23`, or `4.0.0`, etc. PGP signatures are +also provided for official releases from the FTP site; these are +named e.g. `freeradius-server-3.0.22.tar.gz.sig`. + +Un-tar the file, and change to the FreeRADIUS directory (where +`VERSION` below is the version of the server that you have +downloaded). + +[source,shell] +---- +tar -zxf freeradius-server-VERSION.tar.gz +cd freeradius-server-VERSION +---- + +Take the following steps to build and install the server from source: + +[source,shell] +---- +./configure +make +sudo make install +---- + +=== Custom build + +FreeRADIUS has GNU autoconf support. This means you have to run +`./configure`, and then run `make`. To see which configuration +options are supported, run `./configure --help`, and read its output. + +The `make install` stage will install the binaries, the "man" pages, +and _may_ install the configuration files. If you have not installed a +RADIUS server before, then the configuration files for FreeRADIUS will +be installed. + +If you already have a RADIUS server installed, then *FreeRADIUS +WILL NOT over-write your current configuration.* + +The `make install` process will warn you about the files it could not +install. + +If you see a warning message about files that could not be +installed, then you *must* ensure that the new server is using the +new configuration files and not the old configuration files, as +this may cause undesired behavior and failure to operate correctly. + +The initial output from running in debugging mode (`radiusd -X`) +will tell you which configuration files are being used. See +xref:installation:upgrade.adoc[Upgrading] for information about +upgrading from older versions. There _may_ be changes in the +dictionary files which are required for a new version of the +software. These files will not be installed over your current +configuration, so you *must* verify and install any problem files by +hand, for example using `diff(1)` to check for changes. + +When installing from source, it is _extremely_ helpful to read the +output of `./configure`, `make`, and `make install`. If a +particular module you expected to be installed was not installed, +then the output will tell you why that module was not installed. +The most likely reason is that required libraries (including their +development header files) are not available. + +Please do _not_ post questions to the FreeRADIUS users list +without first carefully reading the output of this process as it +often contains the information needed to resolve a problem. + +== Upgrading To A New Minor Release + +The installation process will not over-write your existing configuration +files. It will, however, warn you about the files it did not install. +These will require manual integration with the existing files. + +It is not possible to re-use configurations between different major +versions of the server. + +For details on what has changed between the version, see the +xref:installation:upgrade.adoc[upgrade] guide. + +We _strongly_ recommend that new major versions be installed in a +different location than any existing installations. Any local policies +can then be migrated gradually to the configuration format of the new +major version. The number of differences in the new configuration mean +that is is both simpler and safer to migrate your configurations rather +than to try and just get the old configuration to work. + +== Running the server + +If the server builds and installs, but doesn’t run correctly, then +you should first use debugging mode (`radiusd -X`) to figure out +the problem. + +This is your best hope for understanding the problem. Read _all_ +of the messages which are printed to the screen, the answer to +your problem will often be in a warning or error message. + +We really cannot emphasize that last sentence enough. Configuring +a RADIUS server for complex local authentication isn’t a trivial +task. Your _best_ and _only_ method for debugging it is to read +the debug messages, where the server will tell you exactly what +it’s doing, and why. You should then compare its behaviour to what +you intended, and edit the configuration files as appropriate. + +If you don’t use debugging mode, and ask questions on the mailing +list, then the responses will all tell you to use debugging mode. +The server prints out a lot of information in this mode, including +suggestions for fixes to common problems. Look especially for +`WARNING` and `ERROR` messages in the output, and read the related +messages. + +Since the main developers of FreeRADIUS use debugging mode to +track down their configuration problems with the server, it’s a +good idea for you to use it, too. If you don’t, there is little +hope for you to solve any configuration problem related to the +server. + +To start the server in debugging mode, do: + +[source,shell] +---- +radiusd -X +---- + +You should see a lot of text printed on the screen as it starts up. If +you don’t, or if you see error messages, please read the FAQ: + +https://wiki.freeradius.org/guide/FAQ + +If the server says `Ready to process requests.`, then it is running +properly. From another shell (or another window), type + +[source,shell] +---- +radtest test test localhost 0 testing123 +---- + +You should see the server print out more messages as it receives the +request, and responds to it. The `radtest` program should receive the +response within a few seconds. It doesn’t matter if the authentication +request is accepted or rejected, what matters is that the server +received the request, and responded to it. + +You can now edit the configuration files for your local system. You will +usually want to start with `sites-enabled/default` for main +configurations. To set which NASes (clients) can communicate with this +server, edit `raddb/clients.conf`. Please read the configuration files +carefully, as many configuration options are only documented in comments +in the file. + +Note that is is _highly_ recommended that you use some sort of version +control system to manage your configuration, such as git or Subversion. +You should then make small changes to the configuration, checking in and +testing as you go. When a config change causes the server to stop +working, you will be able to easily step back and find out what update +broke the configuration. + +It is also considered a best practice to maintain a staging or +development environment. This allows you to test and integrate your +changes without impacting your active production environment. You should +make the appropirate investment in order to properly support a critical +resource such as your authentication servers. + +Configuring and running the server MAY be complicated. Many modules have +`man` pages. See `man rlm_pap`, or `man rlm_*` for information. +Please read the documentation in the doc/ directory. The comments in the +configuration files also contain a lot of documentation. + +If you have any additional issues, the FAQ is also a good place to +start. + +https://wiki.freeradius.org/guide/FAQ diff --git a/doc/antora/modules/installation/pages/upgrade.adoc b/doc/antora/modules/installation/pages/upgrade.adoc new file mode 100644 index 0000000..67874c8 --- /dev/null +++ b/doc/antora/modules/installation/pages/upgrade.adoc @@ -0,0 +1,737 @@ += Upgrading from v2 to v3 + +The configuration for 3.0 is *largely* compatible with the 2.x.x +configuration. However, it is NOT possible to simply use the 2.x.x +configuration as-is. Instead, you should re-create it. + +== 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.0. + +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.0, 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: + +[source,shell] +---- +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 in this version. + +=== 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: + +.Example +---- +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: + +.Example +---- +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.x.x may be manually copied to the new v3.0 +`dialup.conf` file (`raddb/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 2.x.x config may be patched to work with the +3.0 module by adding the following: + +.Example +[source,unlang] +---- + 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 2.x.x 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 2.x.x the registration of the `LDAP-Group` pair comparison was done +by the last instance of rlm_ldap to be instantiated. In 3.0 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 2.x.x 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: + +.Example +[source,unlang] +---- +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: + +.Example +[source,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 2.x.x `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: + +.Example +[source,unlang] +---- +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: + +.Example +[source,unlang] +---- +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": + +.Example +[source,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: + +.Example +[source,shell] +---- +radiusd -X +---- + +you will need to do: + +.Example +[source,shell] +---- +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.0 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: + +.Example +[source,unlang] +---- +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: + +.Example +[source,unlang] +---- +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: + +.Example +[source,unlang] +---- +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: + +.Example +[source,unlang] +---- +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: + +.Example +[source,unlang] +---- +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:: + +.Example +[source,unlang] +---- +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`:: + +.Example +[source,unlang] +---- +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: + +.Example +[source,unlang] +---- +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: + + +.Example +[source,unlang] +---- +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. + |