From: nolade Date: Thu, 4 Dec 2025 22:11:10 +0000 (-0500) Subject: docs-v4: Reorganize the Howto/Upgrade section into smaller pages (HIVE-4049) X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d038f5b7571e819985c52fad2686bd62da4c8f77;p=thirdparty%2Ffreeradius-server.git docs-v4: Reorganize the Howto/Upgrade section into smaller pages (HIVE-4049) --- diff --git a/doc/antora/modules/howto/nav.adoc b/doc/antora/modules/howto/nav.adoc index 51877c2f3f2..7ffccecd939 100644 --- a/doc/antora/modules/howto/nav.adoc +++ b/doc/antora/modules/howto/nav.adoc @@ -9,43 +9,45 @@ **** xref:howto:installation/osx.adoc[OSX] ** xref:howto:upgrade/index.adoc[Upgrade from v3] -*** Configuration Files -**** radiusd.conf -*** Modules -**** client -**** radius -**** cache -**** couchbase -**** counter -**** eap -**** exec -**** mschap -**** expiration -**** ippool -**** ldap -**** logintime -**** perl -**** python -**** radutmp -**** rest -**** sql -***** Profiles -***** MySQL -***** PostgreSQL -**** sqlcounter -**** sqlippool -**** unix -**** winbind -*** Processing Sections -*** Unlang -**** "&" is no longer used -**** foreach -**** update -*** Dictionaries -*** xref:howto:upgrade/attribute_names.adoc[All Attribute Names Have Changed] -**** Deleted Virtual Attributes -*** Proxying -*** General Recommendations +*** xref:howto:upgrade/configfiles.adoc[Configuration Files] +**** xref:howto:upgrade/radiusconf.adoc[Radiusd.conf] +**** xref:howto:upgrade/virtualsvr.adoc[Virtual Servers] +*** xref:howto:upgrade/modules.adoc[Modules] +**** xref:howto:upgrade/modules.adoc#rlm_client[Client] +**** xref:howto:upgrade/modules.adoc#rlm_radius[Radius] +**** xref:howto:upgrade/modules.adoc#rlm_cache[Cache] +**** xref:howto:upgrade/modules.adoc#rlm_couchbase[Couchbase] +**** xref:howto:upgrade/modules.adoc#rlm_counter[Counter] +**** xref:howto:upgrade/modules.adoc#rlm_eap[EAP] +**** xref:howto:upgrade/modules.adoc#rlm_exec[Exec] +**** xref:howto:upgrade/modules.adoc#rlm_mschap[MSCHAP] +**** xref:howto:upgrade/modules.adoc#rlm_expiration[Expiration] +**** xref:howto:upgrade/modules.adoc#rlm_ippool[IP-POOL] +**** xref:howto:upgrade/modules.adoc#rlm_ldap[LDAP] +**** xref:howto:upgrade/modules.adoc#rlm_logintime[Logintime] +**** xref:howto:upgrade/modules.adoc#rlm_perl[Perl] +**** xref:howto:upgrade/modules.adoc#rlm_python[Python] +**** xref:howto:upgrade/modules.adoc#rlm_radutmp[Radutmp] +**** xref:howto:upgrade/modules.adoc#rlm_rest[REST] +**** xref:howto:upgrade/modules.adoc#rlm_sql[SQL] +***** xref:howto:upgrade/modules.adoc#profiles[Profiles] +***** xref:howto:upgrade/modules.adoc#rlm_sql_mysql[MYSQL] +***** xref:howto:upgrade/modules.adoc#PostgreSQL[PostgreSQL] +**** xref:howto:upgrade/modules.adoc#rlm_sqlcounter[SQL-Counter] +**** xref:howto:upgrade/modules.adoc#rlm_sqlippool[SQL-IP-POOL] +**** xref:howto:upgrade/modules.adoc#rlm_unix[Unix] +**** xref:howto:upgrade/modules.adoc#rlm_winbind[Winbind] +*** xref:howto:upgrade/processing.adoc[Processing Sections] +*** xref:howto:upgrade/unlang.adoc[Unlang Syntax] +**** xref:howto:upgrade/unlang.adoc#ampersand["&" is Deprecated] +**** xref:howto:upgrade/unlang.adoc#foreach[Foreach] +**** xref:howto:upgrade/unlang.adoc#update[Update] +*** xref:howto:upgrade/dict.adoc[Dictionaries] +*** xref:howto:upgrade/attributes.adoc[Attributes] +**** xref:howto:upgrade/attribute_names.adoc[Attribute Name Changes] +**** xref:howto:upgrade/attributes_deleted.adoc[Deleted Functionality] +*** xref:howto:upgrade/proxy.adoc[Proxying] +*** *** xref:howto:upgrade/recommendations.adoc[Recommendations] ** xref:modules/configuring_modules.adoc[Configure Modules] *** xref:modules/chap/index.adoc[CHAP] diff --git a/doc/antora/modules/howto/pages/upgrade/attribute_names.adoc b/doc/antora/modules/howto/pages/upgrade/attribute_names.adoc index da01b1dba7a..9245ee1cce7 100644 --- a/doc/antora/modules/howto/pages/upgrade/attribute_names.adoc +++ b/doc/antora/modules/howto/pages/upgrade/attribute_names.adoc @@ -1,4 +1,4 @@ -= Attribute name changes from v3 to v4 += Attribute Name Changes Version 4 has significantly changed much of the server internals. One part of that is renaming the dictionary attributes. In v3, the names diff --git a/doc/antora/modules/howto/pages/upgrade/attributes.adoc b/doc/antora/modules/howto/pages/upgrade/attributes.adoc new file mode 100644 index 00000000000..154cfa264a7 --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/attributes.adoc @@ -0,0 +1,80 @@ +[#v4attributes] += Attributes + +Much of the information in this section is also in the +`raddb/dictionary` file + +All of the attributes have been renamed from v3. This change was +necessary in order to support new functionality in v4. The +unfortunate side effect of this change is that all of the names in +SQL, LDAP, and the `files` module are incompatible with v4. + +We recognize that is is difficult to change every entry in a +database, especially when there's no clear mapping between the +"old" and "new" names. This renaming is made more complex because +the "new" names need to be grouped and arranged in ways that the +old ones were not. + +The "old" names were all in flat lists, so that `User-Name` appeared +next to `Cisco-AVPAir`. This organization was simple enough to work +for 20 years, but its time has come. The new names are hierarchical, +and are nested by definition. + +For v4, the `Cisco-AVPair` attribute is called `AVPair`, and it lives +inside of the `Cisco` namespace, which in turn lives inside of the +`Vendor-Specific` namespace. So the old `Cisco-AVPair` attribute is +now named `Vendor-Specific.Cisco.AVPair`. + +This renaming process continues for many thousands of vendor-specific +attributes. + +Happily, it is possible to (mostly) use the old names with v4. +There are limitations, but it will mostly work. The main reason +for enabling the old names is to try out v4 with a database which is +also used by v3. This lets you test that v4 works, without going +through a complex "upgrade everything" process. + +The old v3 names are in "alias" dictionaries, in the +`${dictdir}/alias/` directory. To find out where this directory is on +your local system, run "radiusd -h" or "radclient -h". Then look for +the "-D" command-line option, and it will tell you where the +dictionary files are located. + +The v3 names are in a file named `${dictdir}/radius/alias/VENDOR.txt` where +`VENDOR` is the name of the vendor, which is taken from the `VENDOR` +definition in the v3 dictionaries. + +You will need to add a `$INCLUDE` line for each vendor-specific +dictionary which is used by your local system. The default v4 +dictionaries do not enable all of v3 compatibility names. The reason +is simple: the alias names _mostly_ work, in most situations. But +there are situations where the aliases do not behave correctly. + +We recognize that this process is a bit of work. However, we wish to +encourage everyone using v4 to upgrade to using the new v4 features. +Our experience shows that if we automatically enable "compatibility +features", then those compatibility features will be used for a decade, +and no one will upgrade to use the new features. So we need to find a +balance between upgrades and ongoing support. Easy upgrades will mean +complex ongoing support. Complex upgrades make ongoing support +easier, but also make it less likely that people will upgrade. + +== Attribute References + +Use of attributes in xlats e.g. `%{User-Name}` remains unchanged. + +As of v3, the preferred format for `unknown` attributes is +`Attr-oid.oid.oid`, e.g. `Attr-26.11344.255`. However, v3 would +still parse (but not generate) attributes of the form +`Vendor-FreeRADIUS-Attr-255`. The `Vendor-` syntax has been removed in +version 4. The server would never produce such names, and allowing +them as input made attribute parsing significantly more complex. + +=== List references +The old-style `request:` and `reply:` syntax for lists has been +deprecated. Please use `request` and `reply` instead. + +Many lists have been removed. e.g._`proxy`, `proxy-reply`, `coa`, +`coa-reply`, `disconnect`, and `disconnect-reply`. The underlying +functionality still exists, but it has been moved to different +keywords, such as `subrequest`. diff --git a/doc/antora/modules/howto/pages/upgrade/attributes_deleted.adoc b/doc/antora/modules/howto/pages/upgrade/attributes_deleted.adoc new file mode 100644 index 00000000000..265adaa8c8c --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/attributes_deleted.adoc @@ -0,0 +1,24 @@ += Deleted Functionality + +Many "virtual" or "fake" attributes and configuration items have been removed or renamed in FreeRADIUS v4. + +[cols=",",options="header",] +|=== +| Old Attribute Name or Function | Replace with +| | +| `Module-Return-Code` | `%interpreter(rcode)` +| `Response-Packet-Type` | `reply.Packet-Type` +| `Virtual-Server` | `%interpreter(server)` +| | +| `Packet-Authentication-Vector` | `%radius.packet.vector()` +| `Packet-Dst-IP-Address` | `Net.Dst.IP` +| `Packet-Dst-IPv6-Address` | `Net.Dst.IP` +| `Packet-Dst-Port` | `Net.Dst.Port` +| `Packet-Src-IP-Address` | `Net.Src.IP` +| `Packet-Src-IPv6-Address` | `Net.Src.IP` +| `Packet-Src-Port` | `Net.Src.Port` +| `Post-Auth-Type Reject` | `send Access-Reject` +| `Post-Auth-Type Challenge` | `send Access-Challenge` +|=== + + diff --git a/doc/antora/modules/howto/pages/upgrade/configfiles.adoc b/doc/antora/modules/howto/pages/upgrade/configfiles.adoc new file mode 100644 index 00000000000..b6c269cce0b --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/configfiles.adoc @@ -0,0 +1,4 @@ += Configuration Files + +FreeRADIUS 4 organizes its configuration files in a specific directory structure, typically within /etc/freeradius/ (on Debian-based systems) or /etc/raddb/. The files are text-based and loaded once when the server starts; changes require a server restart to take effect. The files are text-based and include extensive comments to explain their purpose and usage. + diff --git a/doc/antora/modules/howto/pages/upgrade/dict.adoc b/doc/antora/modules/howto/pages/upgrade/dict.adoc new file mode 100644 index 00000000000..763d5ee2b45 --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/dict.adoc @@ -0,0 +1,53 @@ += Dictionaries + +The `struct` data type is now supported. See `man dictionary`. + +Bit fields are now support via a data type such as `bit[3]`. Not that +bit fields are _only_ supported inside of a `struct` definition. + +The dictionary parser includes many more sanity checks and helpful +messages for people who create new dictionaries. + +Dictionaries are now split up by protocol. +e.g._`share/freeradius/radius/dictionary*`. All protocol-specific +data types have been removed, and replaced with per-attribute flags. + +The old `abinary` data type has been removed. Attributes needing this +functionality should instead be marked with a flag, e.g._`string abinary`. + +The old `extended` data type has been removed. Attributes needing this +functionality should instead be marked with a flag, e.g._`tlv +extended`. + +== "Tagged" RADIUS Attributes + +The old-style "tagged" RADIUS format has been removed. Instead of using + +[source,unlang] +---- +Tunnel-Type:1 = PPTP +---- + +you should use + +[source,unlang] +---- +Tag-1.Tunnel-Type = PPTP +---- + +It is also possible to "group" tagged attributes together, as in the +following example: + +[source,unlang] +---- +Tag-1 = { Tunnel-Type = PPTP, Tunnel-Medium-Type = IPv4 } +---- + +There are 31 such attributes, `Tag-1` through `Tag-31`. There is no +`Tag-0` attribute, as it is not needed. + +After much investigation, it was unfortunately impossible to continue +supporting the `Attribute-Name:tag` syntax for tagged attributes. +This change requires modifications to all configuration files and +databases which use tags. This change means also that `detail` files +from v3 are not readable by v4. diff --git a/doc/antora/modules/howto/pages/upgrade/index.adoc b/doc/antora/modules/howto/pages/upgrade/index.adoc index 280ddca9aac..ac639a9f19e 100644 --- a/doc/antora/modules/howto/pages/upgrade/index.adoc +++ b/doc/antora/modules/howto/pages/upgrade/index.adoc @@ -1,34 +1,25 @@ -= Upgrade from v3 to v4 += Upgrade from v3 The configuration for v4 is _somewhat_ compatible with the v3 configuration. It should be possible to reuse most of a v3 reconfiguration with minor tweaks. -[NOTE] -==== -This file describes the differences between v3 and v4. It does not -contain a step-by-step process for upgrading the server. -==== - In general, we have the following changes: -* most module configuration is very close to v3. -* most of the `unlang` processing is very close to v3. +* Most module configuration is very close to v3. +* Most of the `unlang` processing is very close to v3. * `update` is now replaced just by editing the attribute in place. -* each `server` section need a `namespace` parameter. +* Each `server` section need a `namespace` parameter. * Packet processing sections are now `recv Access-Request`, etc. Not `authorize`, etc. -* each `listen` section needs to be converted to the v4 format. - -== Upgrade from older versions +* Each `listen` section needs to be converted to the v4 format. -=== Upgrade from v2 - -If you are upgrading from v2 you should read the v3 version of this -file. It describes changed from v2 to v3. This file describes only -the changes from v3 to v4. +[NOTE] +==== +If you are upgrading from v2 you need to read the https://www.freeradius.org/documentation/freeradius-server/3.2.9/installation/upgrade.html[Upgrade to v3] on the https://www.freeradius.org[Freeradius website]. This file describes only the changes from v3 to v4. +==== -=== Upgrade from v3 +== Use a v4 Default Configuration When upgrading, please start with the default configuration of v4. Then, move your v3 configuration over, one module at a time. Check this file @@ -37,612 +28,15 @@ the new configuration. Start the server after every change via `radiusd -XC` to see if the configuration is OK. Then, convert the `listen` sections, followed by the `server` sections. -Take your time. It is better to make small incremental progress, than -to make massive changes, and then to spend weeks debugging it. Use a -revision control system such as `git` to save and track your changes. -If the changes work as you expect, do `git commit`, and continue with -the next change. If the changes do not work, either keep at it, or -move to a different portion of the configuration +== New Attributes Names All of the attribute names used in v3 have been changed in v4. Please -see the xref:howto:upgrade/attribute_names.adoc[attribute names] document for more +see the xref:howto:upgrade/attribute_names.adoc[Attribute Names] for more information. This change was necessary in order to support the new "grouped" attributes, which are required for DHCPv6 and other protocols. - -== Attribute names - -Much of the information in this section is also in the -`raddb/dictionary` file - -All of the attributes have been renamed from v3. This change was -necessary in order to support new functionality in v4. The -unfortunate side effect of this change is that all of the names in -SQL, LDAP, and the `files` module are incompatible with v4. - -We recognize that is is difficult to change every entry in a -database, especially when there's no clear mapping between the -"old" and "new" names. This renaming is made more complex because -the "new" names need to be grouped and arranged in ways that the -old ones were not. - -The "old" names were all in flat lists, so that `User-Name` appeared -next to `Cisco-AVPAir`. This organization was simple enough to work -for 20 years, but its time has come. The new names are hierarchical, -and are nested by definition. - -For v4, the `Cisco-AVPair` attribute is called `AVPair`, and it lives -inside of the `Cisco` namespace, which in turn lives inside of the -`Vendor-Specific` namespace. So the old `Cisco-AVPair` attribute is -now named `Vendor-Specific.Cisco.AVPair`. - -This renaming process continues for many thousands of vendor-specific -attributes. - -Happily, it is possible to (mostly) use the old names with v4. -There are limitations, but it will mostly work. The main reason -for enabling the old names is to try out v4 with a database which is -also used by v3. This lets you test that v4 works, without going -through a complex "upgrade everything" process. - -The old v3 names are in "alias" dictionaries, in the -`${dictdir}/alias/` directory. To find out where this directory is on -your local system, run "radiusd -h" or "radclient -h". Then look for -the "-D" command-line option, and it will tell you where the -dictionary files are located. - -The v3 names are in a file named `${dictdir}/radius/alias/VENDOR.txt` where -`VENDOR` is the name of the vendor, which is taken from the `VENDOR` -definition in the v3 dictionaries. - -You will need to add a `$INCLUDE` line for each vendor-specific -dictionary which is used by your local system. The default v4 -dictionaries do not enable all of v3 compatibility names. The reason -is simple: the alias names _mostly_ work, in most situations. But -there are situations where the aliases do not behave correctly. - -We recognize that this process is a bit of work. However, we wish to -encourage everyone using v4 to upgrade to using the new v4 features. -Our experience shows that if we automatically enable "compatibility -features", then those compatibility features will be used for a decade, -and no one will upgrade to use the new features. So we need to find a -balance between upgrades and ongoing support. Easy upgrades will mean -complex ongoing support. Complex upgrades make ongoing support -easier, but also make it less likely that people will upgrade. - -== radiusd.conf - -The following configurations have been removed. See the new `listen` -sections for their replacements. - -[width="100%",cols="30%,70%",options="header",] -|=== -| v3 | v4 -| `cleanup_delay` | replaced with `cleanup_delay` in a `listen` section. -| `reject_delay` | see `mods-available/delay`. You should list `delay` - last in any `send Access-Reject` section. -| `status_server` | see `type = Status-Server` in a new `listen` section. -|=== - -The `log` section has been updated to remove many configuration items -which are specific to RADIUS, and to Access-Request packets. Please see -`sites-available/default`, and look for the `Access-Request` -subsection there. See also xref:reference:raddb/templates.conf.adoc[`templates.conf`] -for a way to regain one global configuration for `Access-Request` -packets. - -=== Instantiate section - -The `instantiate` section has been removed. It originally started out -as a way to ensure that modules were instantiated in a particular -order. A later use of the `instantiate` section was to define -"virtual modules" for dynamic expansion. That functionality has been -moved to the `mods-available/` and `mods-enabled/` directories. -i.e. in version 4, just list the virtual module in a file, as if it -was a real module. - -See the xref:reference:raddb/mods-available/redundant_sql.adoc[redundant_sql] module -for more information. In short, a virtual module can be put into -the `mods-enabled` directory as with any other module, as with the -following text: - -[source,unlang] ----- -redundant redundant_sql { - sql1 - sql2 -} ----- - -In this case, this definition creates a `redundant_sql` virtual module. - - -== Virtual servers - -There are some changes to the virtual servers in `v4`. First, every -virtual server has to begin with an entry: - -``` -namespace = ... -``` - -For RADIUS, use: - -``` -namespace = radius -``` - -This tells the server what protocol is being used in that virtual -server. This configuration was not necessary in v3, because each -protocol was pretending to be RADIUS. That was simple to program at -the time and worked for some things, but it was not the best approach. - -In v4, each protocol is completely independent, and RADIUS is no -longer built into the server core. i.e. The server core does modules, -configuration files, policies, etc. RADIUS has been relegated to just -another plug-in protocol, with the same status as DHCPv4 and DHCPv6. - -Every example virtual server in the `sites-enabled/` directory -contains a `namespace` parameter. Please look at those files for -examples of configuring and running each supported protocol. - -=== Listen sections - -The `listen` sections have changed. There is now a `type` entry, which -lists the packet type by their correct name (e.g._`Access-Request` -instead of `auth`). To accept multiple kinds of packets, just list -`type` multiple times: - -``` -type = Access-Request -type = Accounting-Request -``` - -Each `listen` section also has a `transport` entry. This -configuration can be left out for `headless` servers, such as -`inner-tunnel`. For example, setting UDP transport is done via: - -``` -transport = udp -``` - -Each type of transport has its configuration stored in a subsection -named for that transport: - -``` -transport = udp -udp { - ... udp transport configuration ... -} -``` - -For `udp`, the configuration entries are largely the same as for v3. -e.g. `ipaddr`, `port`, etc. - -The `listen` section then compiles each -xref:index.adoc#_processing_sections[Processing Section] based on the named packet -types. It has a `recv` section for receiving packets, and a `send` -section for sending packets, as seen in the following example: - -[source,unlang] ----- -recv Access-Request { - ... unlang ... -} - -send Access-Accept { - ... unlang ... -} ----- - -This configuration is different from v3. The benefit of the change is -that it is much easier to understand. Instead of using confusing names -such as `Post-Auth-Type Reject`, the server now just uses `send -Access-Reject`. - -See also xref:index.adoc#_processing_sections[Processing Section] for how the -`unlang` statements are parsed. - -=== Clients - -The server supports global clients in the `clients.conf` file, as with -v3. - -Client can also be defined in a `client` subsection of a virtual -server. Unlike `v3`, there is no need to have a `clients` section -which "wraps" one or more `client` definitions. See -`sites-available/default` for examples. - -The server also supports dynamic clients. See -`sites-available/dynamic_clients` for a worked example. There are many -changes from v3. First, there is no need to have a `client` definition -which contains a network. Instead, there is a `network` section which -has a number of `allow` and `deny` rules. Second, dynamic clients -can be defined on a per-connection basis. Finally, the -`sites-available/dynamic_clients` virtual server has full access to -the entire RADIUS packet. - -The result of these changes is that it is now possible to have multiple -clients behind a NAT gateway, and to have different shared secrets for -each client. e.g._by keying off of the `NAS-Identifier` attribute. - -The dynamic client functionality behaves the same for all protocols -supported by the server. e.g. RADIUS, DHCP, VMPS, TACACS+, etc. - -== Processing sections - -All of the processing sections have been renamed. Sorry, but this was -required for the new features in v4. - -[cols=",",options="header",] -|=== -| Old Name | New Name -| `authorize` | `recv Access-Request` -| `authenticate` | `authenticate ` -| `post-auth` | `send Access-Accept` -| | -| `preacct` | `recv Accounting-Request` -| `accounting` | `accounting %\{Acct-Status-Type\}` -| `accounting` | `send Accounting-Response` -| | -| `recv-coa` | `recv CoA-Request` -| `send-coa` | `send CoA-ACK` -| `send-coa` | `send CoA-NAK` -| | -| `Post-Auth-Type Reject` | `send Access-Reject` -| `Post-Auth-Type Challenge` | `send Access-Challenge` -|=== - -i.e. instead of the section names being (mostly) randomly named, the -names are now consistent. The `recv` sections receive packets from the -network. The `send` sections send packets back to the network. The -second name of the section is the _type_ of the packet that is being -received or sent. - -[NOTE] -==== -For accounting, packets are also processed through an -`accounting` section named after Acct-Status-Type. This process is -similar to `authenticate` for `Access-Request` packets. The goal -here is to allow a common pre-processing of accounting packets in the -`recv Accounting-Request` packet, followed by type-specific processing -in `accounting %{Acct-Status-Type}`. See sites-available/default for -examples and more information. -==== - -=== Update sections - -A major difference between v3 and v4 is that `update` sections are no -longer necessary. See the <> section below for full -details. - -== Proxy - -The proxy feature has undergone massive changes. The `proxy.conf` file no -longer exists, and everything in it has been removed. e.g. `realm`, -`home_server`, `home_server_pool` no longer exist. The old proxying -functionality was welded into the server core, which made many useful -features impossible to configure. - -The `radius` module now handles basic proxying to home servers. We -recommend creating one instance of the `radius` module per home -server. e.g. - -[source,unlang] ----- -radius home_server_1 { - ... configuration for home server 1 ... -} ----- - -You can then use `home_server_1` in any processing section, and the -request will be proxied when processing reaches the module. - -For ease of management, we recommend naming the modules for the host -name of the home server. - -It is often simplest to do proxying via an `authenticate proxy { ... }` -section, though that section can have any name. e.g. setting -`Auth-Type := proxy` will call the `authenticate proxy` section, and -is similar to the previous setting `Proxy-To-Realm`. - -[source,unlang] ----- -authenticate proxy { - home_server_1 -} ----- - -For more detailed examples, see the Wiki page: -https://wiki.freeradius.org/upgrading/version4/proxy. That page also -describes how to upgrade a v3 configuration to the new v4 style. - -The benefit of this approach is that the "RADIUS proxy" functionality -is just another module. It is now possible to not just fail over from -one home server to another, but also to proxy the same packet to -multiple destinations. - -=== home_server - -The `home_server` configuration has been replaced with the `radius` -module. See `raddb/mods-available/radius` for examples and -documentation. - -=== home_server_pool - -The `home_server_pool` configuration has been replaced with standard -unlang configurations. The various load-balancing options can be -re-created using in-place `unlang` configuration. - -The mappings for `type` are as follows: - -* `type = fail-over` - replaced with `unlang` - -[source,unlang] ----- -redundant { - home_server_1 - home_server_2 - home_server_3 -} ----- - -[NOTE] -==== -Of course, you will have to use the names of the `radius` -modules in your configuration, and not `home_server_1`, etc. -==== - -* `type = load-balance` - replaced with `unlang` - -[source,unlang] ----- -load-balance { - home_server_1 - home_server_2 - home_server_3 -} ----- - -* `type = client-balance` - replaced with `unlang` - -[source,unlang] ----- -load-balance "%{Net.Src.IP}" { - home_server_1 - home_server_2 - home_server_3 -} ----- - -* `type = client-port-balance` - replaced with `unlang` - -[source,unlang] ----- -load-balance "%%{Net.Src.IP}-%{Net.Src.Port}" { - home_server_1 - home_server_2 - home_server_3 -} ----- - -* `type = keyed-balance` - replaced with `unlang` - -[source,unlang] ----- -load-balance "%{Load-Balance-Key}" { - home_server_1 - home_server_2 - home_server_3 -} ----- - -While the `Load-Balance-Key` was a special attribute in v3, it has no -special meaning in v4. You can use any attribute or string expansion as -part of the `load-balance` key. - -=== Limitations in v3 - -In v3, it was impossible to proxy the same request to multiple -destinations. This is now trivial. In any processing section, do: - -[source,unlang] ----- -... -home_server_1 -home_server_2 -... ----- - -When processing reaches that point, it will proxy the request to -`home_server_1`, followed by `home_server_2`. - -This functionality can be used to send `Accounting-Request` packets to -multiple destinations. - -You can also catch _failed_ proxying, and do something else. In the -example below, try to proxy to `home_server_1`, if that fails, just -`accept` the request. - -[source,unlang] ----- -... -home_server_1 -if (fail) { - accept -} -... ----- - -=== CoA and Originate-Coa - -The `sites-available/originate-coa` virtual server has been updated to -use the new `subrequest` feature. Please see that virtual server, and -the `subrequest` keyword for details. - -== Dictionaries - -The `struct` data type is now supported. See `man dictionary`. - -Bit fields are now support via a data type such as `bit[3]`. Not that -bit fields are _only_ supported inside of a `struct` definition. - -The dictionary parser includes many more sanity checks and helpful -messages for people who create new dictionaries. - -Dictionaries are now split up by protocol. -e.g._`share/freeradius/radius/dictionary*`. All protocol-specific -data types have been removed, and replaced with per-attribute flags. - -The old `abinary` data type has been removed. Attributes needing this -functionality should instead be marked with a flag, e.g._`string abinary`. - -The old `extended` data type has been removed. Attributes needing this -functionality should instead be marked with a flag, e.g._`tlv -extended`. - -=== "Tagged" RADIUS attributes - -The old-style "tagged" RADIUS format has been removed. Instead of using - -[source,unlang] ----- -Tunnel-Type:1 = PPTP ----- - -you should use - -[source,unlang] ----- -Tag-1.Tunnel-Type = PPTP ----- - -It is also possible to "group" tagged attributes together, as in the -following example: - -[source,unlang] ----- -Tag-1 = { Tunnel-Type = PPTP, Tunnel-Medium-Type = IPv4 } ----- - -There are 31 such attributes, `Tag-1` through `Tag-31`. There is no -`Tag-0` attribute, as it is not needed. - -After much investigation, it was unfortunately impossible to continue -supporting the `Attribute-Name:tag` syntax for tagged attributes. -This change requires modifications to all configuration files and -databases which use tags. This change means also that `detail` files -from v3 are not readable by v4. - -== Attribute references - -In previous versions of the user attributes could be referred to by -their name only e.g. `if (User-Name == 'foo')`. - -To allow for more thorough error checking, it is now required to -prefix attribute references with `&`. Using bare names will result in -an error, and a suggestion to use `&`. - -Common places which will need to be checked and corrected are the left -and right hand side of `update {}` sections, along with `if` conditions. - -The v3 server has warned about using non prefixed attribute references -for some time. If users have addressed those warnings, few -modifications will be required. - -Use of attributes in xlats e.g. `%{User-Name}` remains unchanged. -There is no plan to require prefixes here. - -As of v3, the preferred format for `unknown` attributes is -`Attr-oid.oid.oid`, e.g. `Attr-26.11344.255`. However, v3 would -still parse (but not generate) attributes of the form -`Vendor-FreeRADIUS-Attr-255`. The `Vendor-` syntax has been removed in -version 4. The server would never produce such names, and allowing -them as input made attribute parsing significantly more complex. - -=== List references - -The old-style `request:` and `reply:` syntax for lists has been -deprecated. Please use `request` and `reply` instead. - -Many lists have been removed. e.g._`proxy`, `proxy-reply`, `coa`, -`coa-reply`, `disconnect`, and `disconnect-reply`. The underlying -functionality still exists, but it has been moved to different -keywords, such as `subrequest`. - -=== Recommendations - -We recommend manually converting the `update` sections to the new -method. The biggest change that confuses people is the old `+=` -operator does not work the same way as before. - -Instead of doing: - -``` -Reply-Message += "foo" -``` - -you should edit the `reply` list, using the `+=` operator: - -``` -reply += { - Reply-Message = "foo" -} -``` - -We also recommend removing double-quotes from xlat expansions where -possible. The temptation in v3 is to just add double quotes to -everything, and hope it all works out. This is no longer necessary in -v4. - -For example, in v3 you would do: - -``` -update reply { - Framed-IP-Address := "%{sql:SELECT ...}" -} -``` - -In v4, you can remove the `update`, and rewrite the SQL call to: - -``` -reply.Framed-IP-Address := %sql("SELECT ...") -``` - -Using double quotes everywhere means that every bit of data gets -converted to printable strings, and then back to it's real data type -(`ipaddr` in the above example). Removing the double quotes means -that there is less work going on, which means higher performance. - -== load-balance and redundant-load-balance sections - -Before v4, the `load-balance` sections implemented load balancing by -picking a child at random. This meant that load balancing was -probabilistically fair, but not perfectly fair. - -In v4, `load-balance` sections track how many requests are in each -sub-section, and pick the subsection which is used the least. This is -like the v3 proxy behavior of load balancing across home server pools. - -The `load-balance` and `redundant-load-balance` sections now allow -for a load-balance key: - -[source,unlang] ----- -load-balance "%{Calling-Station-Id}" { - module1 - module2 - module3 - ... -} ----- - -If the key exists, it is hashed, and used to pick one of the -subsections. This behavior allows for deterministic load-balancing of -modules, similar to the v3 proxy `keyed-balance` configuration. - -== Connection timeouts +== Connection Timeouts In v3 and earlier, the configuration items for configuring connection timeouts were either confusingly named, or completely absent in the case of many @@ -669,76 +63,9 @@ Some modules such as rlm_sql_postgresql can have their timeout set via an alternative configuration item (e.g. `radius_db` in the case of postgresql). -== Unlang syntax - -Many new xref:reference:unlang/index.adoc[unlang] keywords have been added. +== Xlat Expansions -Data type casts have changed from ` ...` to `(ipaddr) ...` - -== Keyword Changes - -=== foreach - -The xref:reference:unlang/foreach.adoc[foreach] keyword has changed syntax. - -Instead of - ----- -foreach &reply.Filter-Id { - if ("%{Foreach-Variable-0}" == ...) { -} ----- - -You can define a xref:reference:unlang/local.adoc[local variable] via -the following syntax: - ----- -foreach thing (reply.Filter-Id[*]) { - if (thing == ...) { -} ----- - -The result is much simpler and clearer. - -=== update - -The `update` sections are deprecated. The new way to -xref:reference:unlang/edit.adoc[edit] is much simpler. -See the xref:reference:unlang/update.adoc[update] documentation for a -description of what has changed, and how to use the attribute new -xref:reference:unlang/edit.adoc[edit] functionality. - -The server has limited support for "auto-conversion" of `update` -sections to the new syntax. Documentation is TBD. - -It is now possible to just edit attributes "in place". For example, -instead of doing this: - -[source,unlang] ----- -if (User-Name == "bob") { - update reply { - Reply-Message := "Hello, %{User-Name}" - } -} ----- - -You can now do this: - -[source,unlang] ----- -if (User-Name == "bob") { - reply.Reply-Message := "Hello, %{User-Name}" -} ----- - -As with any upgrade across major version numbers, there are caveats. -See the full xref:reference:unlang/update.adoc[update] documentation -for further information. - -== Xlat expansions - -xref:reference:xlat/index.adoc[xlat] expansions have been changed from syntax like `%{md5:...}` to `%hash.md5(...)`. +The xref:reference:xlat/index.adoc[xlat] expansions have been changed from syntax like `%{md5:...}` to `%hash.md5(...)`. === Removed expansions @@ -746,476 +73,27 @@ xref:reference:xlat/index.adoc[xlat] expansions have been changed from syntax li `%{expr:...}` has been removed. You can instead use in-place expressions, such as `%{1 + 2}` or `%{NAS-Port + 14}`. -== New modules - -The following modules are new in v4. - -=== rlm_client - -This module handles the `%{client:..}` xlat expansions. - -The `Client-Shortname` attribute has been removed. You should use `%client(shortname)` instead. - -=== rlm_radius - -The `radius` module has taken over much of the functionality of -`proxy.conf`. See `raddb/mods-available/radius` for documentation -and configuration examples. - -The `radius` module connects to one home server, just like the -`home_server` configuration in v3. Some of the configuration items are -similar to the `home_server` configuration, but not all. - -The module can send multiple packet types to one home server. -e.g. Access-Request and Accounting-Request. - -This module also replaces the old `coa` and `originate-coa` -configuration. See also `subrequest` for creating child requests that are -different from the parent requests. - -Unlike v3, the module can do asynchronous proxying. That is, proxying -where the server controls the retransmission behavior. In v3, the server -retransmitted proxied packets only when it received a retransmission -from the NAS. That behavior is good, but there are times where -retransmitting packets at the proxy is better. - -== Changed modules - -The following modules exhibit changed behaviour. - -=== rlm_cache - -`control.Cache-Merge` has been renamed to -`control.Cache-Merge-New` and controls whether new entries are merged -into the current request. It defaults to `no`. The primary use case, -is if you’re using xlat expansions in the cache module itself to -retrieve information for caching, and need the result of those -expansions to be available immediately. - -Two new control attributes `control.Cache-Allow-Merge` and -`control.Cache-Allow-Insert` have been added. These control whether -existing entries are to be merged, and new entries created on the next -call to a cache module instance. Both default to `yes`. - -=== rlm_eap - -All certificate attributes are available in the `session-state.` -list, immediately after they are parsed from their ASN1 form. - -The certificates are no longer added to the `request` list. Instead, -they are added to the `session-state` list. You are advised to update -any references during the upgrade to 4.0: - -``` -s/TLS-Cert-/session-state.TLS-Cert-/ -``` - -The `rlm_eap_ikev2` module was removed. It does not follow RFC 5106, -and no one was maintaining it. - -The `rlm_eap_tnc` module was removed. No one was using or maintaining -it. - -The in-memory SSL cache was removed. Changes in OpenSSL and FreeRADIUS -made it difficult to continue using the OpenSSL implementation of a -cache. See `raddb/sites-available/tls-cache` for a better replacement. -The OpenSSL cache can now be placed on disk, in memory, in memcache, -or in a redis cache. The result is both higher performance, and more -configurable. - -The `use_tunneled_reply` and `copy_request_to_tunnel` configuration -items have been removed. Their functionality has been replaced with the -`use_tunneled_reply` and `copy_request_to_tunnel` policies. See -`raddb/sites-available/inner-tunnel` and `raddb/policy.d/eap` for -more information. - -These configuration items were removed because they caused issues for a -number of users, and they made the code substantially more complicated. -Experience shows that having configurable policies in `unlang` is -preferable to having them hard-coded in C. - -=== rlm_eap_pwd - -The `virtual_server` configuration has been removed from EAP-PWD. The -module now looks for request.control.Password.Cleartext. - -=== rlm_eap_leap - -The LEAP protocol has been removed from the server. It is insecure, -non-standard, and should not be used. - -=== rlm_exec - -Exec-Program and Exec-Program-Wait have been removed. - -The `packet_type` configuration has been removed. Use `unlang` -checks to see if you want to execute the module. - -=== rlm_expr - -The `expr` module is no longer necessary and has been removed. - -The xref:reference:xlat/index.adoc[xlat] expansions just support math -natively. For example: - -``` -Reply-Message := "1 + 2 = %{1 + 2}" -``` - -will return the string `1 + 2 = 3`. The contents of the expansion can -be any math or condition. Attribute assignments in expansions are not -supported. - -=== rlm_expiration - -The `expiration` module has been replaced with an `unlang` policy. -The policy is located in `raddb/policy.d/time`. The `Expiration` -attribute should continue to work the same as with v3. - -=== rlm_ldap - -The `ldap` module provides an expansion `%ldap.group()` instead of -`LDAP-Group` for dynamically testing group membership. The old method of - -``` -if (LDAP-Group == "foo") { ... -``` - -will no longer work. Instead, use - -``` -if (%ldap.group(foo)) { ... -``` - -The caching of group membership into attributes in the `control` list is -still available, so - -``` -control.LDAP-Group[*] == "foo" -``` -can also be used to test membership after having called the `ldap` module, -if `cacheable_name` or `cacheable_dn` are enabled. - -=== rlm_mschap - -The `winbind_*` configuration options are now in a `winbind` -subsection. See `mods-available/mschap` for details. - -=== rlm_perl - -Attributes of type `octets` are now passed directly to Perl as binary -data, instead of as hex strings. - -All data received from the network is marked `tainted` by default. - -Rather than using the global hashes `%RAD_REQUEST` etc, Perl subroutines -called by FreeRADIUS during packet processing are passed a hash ref -representing the packet being processed. - -This hash ref contains four hashes representing the attribute lists. - -Manipulating the values of attributes is now done directly from the -Perl subroutines e.g. - -``` -$p->{'reply'}{'foo'}[0] = 'baa' -``` - -Will set the value of `reply.foo` to `"baa"`, creating the pair if -needed. - -=== rlm_python - -Rather than passing a tuple representing attributes in the `request` -list, an object is passsed to Python functions representing the request. -This object has members giving access to all the lists, for both -accessing and setting attributes. - -The module now only expects a single return value representing the module -`rcode` since attributes can be set directly within Python functions. - -See the xref:howto:modules/python/index.adoc[rlm_python] module documentation -for more details. - -=== rlm_radutmp - -The module has been removed. Many Unix distributions have moved away -from using flat-text files for `utmp`. We recommend using sqlite -to store session data, instead of radutmp. - -=== rlm_rest - -`REST-HTTP-Code` is now inserted into the `request` list instead -of the `reply.` list, to be compliant with the -https://wiki.freeradius.org/guide/List-Usage[list usage] guidelines. - -=== rlm_sql - -Driver-specific options have moved from `mods-available/sql` to -`mods-config/sql/driver/`. - -If caching is enabled, the `SQL-Group` attribute is cached in the -`control` list after the module has run. This means it is possible to -do regular expression comparison on group names. - -It also means that any comparison of `SQL-Group == "foo"` has to be -updated to use `control.SQL-Group == "foo"` instead. - -This caching also means that the group comparison will be done -internally, and will not result in a database lookup. This also means -that it is now possible to do group comparisons based on regular -expressions. - -It is possible to force a dynamic group lookup via the expansion -`%sql.group(foo)`. This expansion returns `true` if the user is a -member of that SQL group, and `false` otherwise. - -``` -if (%sql.group(sales)) { - ... -} -``` - -will return `true`. - -=== Accounting and Post-Auth module calls - -The `reference` option has been removed from `accounting` and `post-auth` -sql module configuration. - -Instead, the set of queries run depend on the section the module is called -from. E.g. calling from `accounting Start` will run the set of queries -defined as - -``` -accounting { - start { - query = ... - query = ... - } -} -``` - -The v3 `post-auth` configuration is now replaced with a set of `send` -queries, again with the queries run specific to the section that the -module is called from. - -``` -send { - access-accept { - query = ... - } - access-reject { - query = ... - } -} -``` - -=== Profiles - -The `default_user_profile` has been removed. No one used it, as that -behavior was already supported by the group functionality. See -rlm_sql and `User-Profile` for new, and superior, behavior. - -==== rlm_sql_mysql - -Now calls `mysql_real_escape_string` and no longer produces -`=` escape sequences in expanded values. The -`safe_characters` config item is ignored when using MySQL databases. - -=== rlm_sql_postgresql - -Now calls `PQescapeStringConn` and no longer produces -`=` escape sequences in expanded values. The -`safe_characters` config item is ignored when using PostgreSQL -databases. - -=== rlm_sqlcounter - -Attribute references: - -The following config items must now be defined as attribute references:: - -``` -counter_name -check_name -reply_name -``` - -For example where in v3 you would specify the attribute names as:: - -``` -counter_name = Daily-Session-Time -check_name = Max-Daily-Session -reply_name = Session-Timeout -key = User-Name -``` - -In v4 they must now be specified as:: - -``` -counter_name = control.Daily-Session-Time -check_name = control.Max-Daily-Session -reply_name = reply.Session-Timeout -key = "%{Stripped-User-Name || User-Name}" -``` - -Just adding the `&` prefix to the attribute name is not sufficient. -Attributes must be qualified with the list to search in, or add to. - -This allows significantly greater flexibility, and better integration -with newer features in the server such as CoA, where reply_name can now -be `coa:Session-Timeout`. That allows the server to send a CoA packet -which updates the `Session-Timeout` for the user. - -In v4, when the `key` field was set to `User-Name`, the module would -also look for `Stripped-User-Name` as the key. In v4, this -functionality has been moved to the configuration. To get the same -functionality, the key should now be specified as a dynamic expansion: - -``` -key = "%{Stripped-User-Name || User-Name}" -``` - -The `count_attribute` has been removed, as it is no longer necessary. - -The old expansions `%%b` and `%%e` have been removed. This should -only affect people who are editing the queries manually. See the file -`mods-availble/sqlcounter` for more information. - -The attribute comparison has been removed. It is no longer possible -to check `Daily-Session-Time > 4` everywhere. Instead, the attribute -exists only after the `sqlcounter` module has been run. - -=== rlm_sqlippool - -NOTE: The `ipv6` configuration item has been deleted. It was -deprecated in 3.0.16. - -Instead, use `attribute-name`. See `mods-available/sqlippool` for -more information. - -=== rlm_unix - -The `unix` module uses an expansion `%unix.group()` instead of -`Unix-Group`, `Group` or `Group-Name`. The old method of doing - -``` -Group == "foo" -``` - -will no longer work. - -=== rlm_winbind - -The `winbind` module uses an expansion `%winbind.group()` instead of -`Winbind-Group == `. - -== Deleted modules - -The following modules have been deleted - -=== rlm_couchbase - -This module used an old version of the Couchbase API, which is no -longer supported. Since no one stepped up to upgrade the module, it -has been removed. - -=== rlm_counter - -Instead of using this, please use the `sqlcounter` module with sqlite. - -It is difficult to maintain multiple implementations of the same -functionality. As a result, we have simplified the server by removing -duplicate functionality. - -=== rlm_ippool - -Instead of using this, please use the `sql_ippool` module with sqlite. - -It is difficult to maintain multiple implementations of the same -functionality. As a result, we have simplified the server by removing -duplicate functionality. - -=== rlm_logintime - -This module was poorly documented, and it appears that no one was using it. - -The attributes `Time-Of-Day`, `Login-Time`, and `Current-Time` have -also been removed. Any configuration which tries to use them will -result in an error. - -Dates and time attributes can be checked against date strings by -casting them: - -``` -if (Date-attribute < (date) 'Aug 1 2023 01:02:03 UTC') { - ... -} -``` - -The current time can also be checked: - -``` -if (%time() < (date) 'Aug 1 2023 01:02:03 UTC') { - ... -} -``` - -== Deleted functionality - -Many "virtual" or "fake" attributes have been removed or renamed. - -`Module-Return-Code` should be replaced by `%interpreter(rcode)`. - -`Response-Packet-Type` should be replaced by `reply.Packet-Type`. - -`Virtual-Server` should be replaced by `%interpreter(server)`. - -`Packet-Authentication-Vector` should be replaced by `%radius.packet.vector()`. - -`Packet-Dst-IP-Address` and `Packet-Dst-IPv6-Address` should be replaced by `Net.Dst.IP`. - -`Packet-Dst-Port` should be replaced by `Net.Dst.Port`. - -`Packet-Src-IP-Address` and `Packet-Src-IPv6-Address` should be replaced by `Net.Src.IP`. - -`Packet-Src-Port` should be replaced by `Net.Src.Port`. +== Upgrade Steps -== Recommended changes +. Start with the default configuration of v4. -In v3, many people had a habit of just adding `"..."` around _everything_. For example: +. Move your v3 configuration over, one module at a time. -.Bad practice - using "" everywhere -[source,unlang] ----- -update reply { - Reply-Message := "%{User-Name}" -} +. Check for differences in module configuration and update the selected module to use the new configuration. -... +. Start the server after every change via `radiusd -XC` to see if the configuration is OK. -if ("%{User-Name}" == "bob") { - ... -} ----- +. Convert the listen sections, followed by the server sections. -This practice is not recommended. It was never necessary, and it's not clear why it became a (bad) habit. +. Take your time and make small, incremental changes. This helps avoid major updates and reduces debugging problems. -In v4, it is clearer, simpler, and faster to just use `unlang` syntax correctly. +. Use a revision control system such as `git`` to save and track your changes. -.Good practice - just rely on the server to do the right thing +. If the changes work as expected, do a `git commit` and continue with the next change. -[source,unlang] ----- -reply.Reply-Message := User-Name +. If the changes do not work, either keep at it or move to a different part of the configuration. -... -if (User-Name == "bob") { - ... -} ----- // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/howto/pages/upgrade/modules.adoc b/doc/antora/modules/howto/pages/upgrade/modules.adoc new file mode 100644 index 00000000000..d8c2cdfc60b --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/modules.adoc @@ -0,0 +1,476 @@ += Modules + +FreeRADIUS 4 provides new and updated modules that improve its features and configuration options. This section lists these changes and highlights any deleted modules. Please check this section to stay informed about important updates. + +FreeRADIUS 4 focuses on easier module management. You can enable modules by creating soft links from mods-enabled/ to mods-available/. Another option is to copy the file and edit the configuration files in mods-enabled/. This method makes customisation simpler and prevents direct changes to default settings. + +== New Modules + +The following modules are new in v4. + +[#rlm_client] +=== rlm_client + +This module handles the `%{client:..}` xlat expansions. + +The `Client-Shortname` attribute has been removed. You should use `%client(shortname)` instead. + +[#rlm_radius] +=== rlm_radius + +The `radius` module has taken over much of the functionality of +`proxy.conf`. See `raddb/mods-available/radius` for documentation +and configuration examples. + +The `radius` module connects to one home server, just like the +`home_server` configuration in v3. Some of the configuration items are +similar to the `home_server` configuration, but not all. + +The module can send multiple packet types to one home server. +e.g. Access-Request and Accounting-Request. + +This module also replaces the old `coa` and `originate-coa` +configuration. See also `subrequest` for creating child requests that are +different from the parent requests. + +Unlike v3, the module can do asynchronous proxying. That is, proxying +where the server controls the retransmission behavior. In v3, the server +retransmitted proxied packets only when it received a retransmission +from the NAS. That behavior is good, but there are times where +retransmitting packets at the proxy is better. + +=== Load Balancing and Redundancy Sections + +Before v4, the `load-balance` sections implemented load balancing by +picking a child at random. This meant that load balancing was +probabilistically fair, but not perfectly fair. + +In v4, `load-balance` sections track how many requests are in each +sub-section, and pick the subsection which is used the least. This is +like the v3 proxy behavior of load balancing across home server pools. + +The `load-balance` and `redundant-load-balance` sections now allow +for a load-balance key: + +[source,unlang] +---- +load-balance "%{Calling-Station-Id}" { + module1 + module2 + module3 + ... +} +---- + +If the key exists, it is hashed, and used to pick one of the +subsections. This behavior allows for deterministic load-balancing of +modules, similar to the v3 proxy `keyed-balance` configuration. + +== Changed Modules + +The following modules exhibit changed behaviour. + +[#rlm_cache] +=== rlm_cache + +`control.Cache-Merge` has been renamed to +`control.Cache-Merge-New` and controls whether new entries are merged +into the current request. It defaults to `no`. The primary use case, +is if you’re using xlat expansions in the cache module itself to +retrieve information for caching, and need the result of those +expansions to be available immediately. + +Two new control attributes `control.Cache-Allow-Merge` and +`control.Cache-Allow-Insert` have been added. These control whether +existing entries are to be merged, and new entries created on the next +call to a cache module instance. Both default to `yes`. + +[#rlm_eap] +=== rlm_eap + +All certificate attributes are available in the `session-state.` +list, immediately after they are parsed from their ASN1 form. + +The certificates are no longer added to the `request` list. Instead, +they are added to the `session-state` list. You are advised to update +any references during the upgrade to 4.0: + +``` +s/TLS-Cert-/session-state.TLS-Cert-/ +``` + +The `rlm_eap_ikev2` module was removed. It does not follow RFC 5106, +and no one was maintaining it. + +The `rlm_eap_tnc` module was removed. No one was using or maintaining +it. + +The in-memory SSL cache was removed. Changes in OpenSSL and FreeRADIUS +made it difficult to continue using the OpenSSL implementation of a +cache. See `raddb/sites-available/tls-cache` for a better replacement. +The OpenSSL cache can now be placed on disk, in memory, in memcache, +or in a redis cache. The result is both higher performance, and more +configurable. + +The `use_tunneled_reply` and `copy_request_to_tunnel` configuration +items have been removed. Their functionality has been replaced with the +`use_tunneled_reply` and `copy_request_to_tunnel` policies. See +`raddb/sites-available/inner-tunnel` and `raddb/policy.d/eap` for +more information. + +These configuration items were removed because they caused issues for a +number of users, and they made the code substantially more complicated. +Experience shows that having configurable policies in `unlang` is +preferable to having them hard-coded in C. + +[#rlm_eap_pwd] +=== rlm_eap_pwd + +The `virtual_server` configuration has been removed from EAP-PWD. The +module now looks for request.control.Password.Cleartext. + +[#rlm_eap_leap] +=== rlm_eap_leap + +The LEAP protocol has been removed from the server. It is insecure, +non-standard, and should not be used. + +[#rlm_exec] +=== rlm_exec + +Exec-Program and Exec-Program-Wait have been removed. + +The `packet_type` configuration has been removed. Use `unlang` +checks to see if you want to execute the module. + +[#rlm_expr] +=== rlm_expr + +The `expr` module is no longer necessary and has been removed. + +The xref:reference:xlat/index.adoc[xlat] expansions just support math +natively. For example: + +``` +Reply-Message := "1 + 2 = %{1 + 2}" +``` + +will return the string `1 + 2 = 3`. The contents of the expansion can +be any math or condition. Attribute assignments in expansions are not +supported. + +[#rlm_expiration] +=== rlm_expiration + +The `expiration` module has been replaced with an `unlang` policy. +The policy is located in `raddb/policy.d/time`. The `Expiration` +attribute should continue to work the same as with v3. + +[#rlm_ldap] +=== rlm_ldap + +The `ldap` module provides an expansion `%ldap.group()` instead of +`LDAP-Group` for dynamically testing group membership. The old method of + +``` +if (LDAP-Group == "foo") { ... +``` + +will no longer work. Instead, use + +``` +if (%ldap.group(foo)) { ... +``` + +The caching of group membership into attributes in the `control` list is +still available, so + +``` +control.LDAP-Group[*] == "foo" +``` +can also be used to test membership after having called the `ldap` module, +if `cacheable_name` or `cacheable_dn` are enabled. + +[#rlm_mschap] +=== rlm_mschap + +The `winbind_*` configuration options are now in a `winbind` +subsection. See `mods-available/mschap` for details. + +[#rlm_perl] +=== rlm_per] + +Attributes of type `octets` are now passed directly to Perl as binary +data, instead of as hex strings. + +All data received from the network is marked `tainted` by default. + +Rather than using the global hashes `%RAD_REQUEST` etc, Perl subroutines +called by FreeRADIUS during packet processing are passed a hash ref +representing the packet being processed. + +This hash ref contains four hashes representing the attribute lists. + +Manipulating the values of attributes is now done directly from the +Perl subroutines e.g. + +``` +$p->{'reply'}{'foo'}[0] = 'baa' +``` + +Will set the value of `reply.foo` to `"baa"`, creating the pair if +needed. + +[#rlm_python] +=== xref:howto:modules/python/index.adoc[rlm_python] + +Rather than passing a tuple representing attributes in the `request` +list, an object is passsed to Python functions representing the request. +This object has members giving access to all the lists, for both +accessing and setting attributes. + +The module now only expects a single return value representing the module +`rcode` since attributes can be set directly within Python functions. + +[#rlm_radutmp] +=== rlm_radutmp + +The module has been removed. Many Unix distributions have moved away +from using flat-text files for `utmp`. We recommend using sqlite +to store session data, instead of radutmp. + +[#rlm_rest] +=== rlm_rest + +`REST-HTTP-Code` is now inserted into the `request` list instead +of the `reply.` list, to be compliant with the +https://wiki.freeradius.org/guide/List-Usage[list usage] guidelines. + +[#rlm_sql] +=== rlm_sql + +Driver-specific options have moved from `mods-available/sql` to +`mods-config/sql/driver/`. + +If caching is enabled, the `SQL-Group` attribute is cached in the +`control` list after the module has run. This means it is possible to +do regular expression comparison on group names. + +It also means that any comparison of `SQL-Group == "foo"` has to be +updated to use `control.SQL-Group == "foo"` instead. + +This caching also means that the group comparison will be done +internally, and will not result in a database lookup. This also means +that it is now possible to do group comparisons based on regular +expressions. + +It is possible to force a dynamic group lookup via the expansion +`%sql.group(foo)`. This expansion returns `true` if the user is a +member of that SQL group, and `false` otherwise. + +``` +if (%sql.group(sales)) { + ... +} +``` + +will return `true`. + +=== Accounting and Post-Auth module calls + +The `reference` option has been removed from `accounting` and `post-auth` +sql module configuration. + +Instead, the set of queries run depend on the section the module is called +from. E.g. calling from `accounting Start` will run the set of queries +defined as + +``` +accounting { + start { + query = ... + query = ... + } +} +``` + +The v3 `post-auth` configuration is now replaced with a set of `send` +queries, again with the queries run specific to the section that the +module is called from. + +``` +send { + access-accept { + query = ... + } + access-reject { + query = ... + } +} +``` +[#profiles] +==== Profiles + +The `default_user_profile` has been removed. No one used it, as that +behavior was already supported by the group functionality. See +rlm_sql and `User-Profile` for new, and superior, behavior. + +[#rlm_sql_mysql] +==== rlm_sql_mysql + +Now calls `mysql_real_escape_string` and no longer produces +`=` escape sequences in expanded values. The +`safe_characters` config item is ignored when using MySQL databases. + +[#rlm_sql_postgresql] +==== rlm_sql_postgresql + +Now calls `PQescapeStringConn` and no longer produces +`=` escape sequences in expanded values. The +`safe_characters` config item is ignored when using PostgreSQL +databases. + +[#rlm_sqlcounter] +=== rlm_sqlcounter + +Attribute references: + +The following config items must now be defined as attribute references:: + +``` +counter_name +check_name +reply_name +``` + +For example where in v3 you would specify the attribute names as:: + +``` +counter_name = Daily-Session-Time +check_name = Max-Daily-Session +reply_name = Session-Timeout +key = User-Name +``` + +In v4 they must now be specified as:: + +``` +counter_name = control.Daily-Session-Time +check_name = control.Max-Daily-Session +reply_name = reply.Session-Timeout +key = "%{Stripped-User-Name || User-Name}" +``` + +Attributes must be qualified with the list to search in, or add to. + +This allows significantly greater flexibility, and better integration +with newer features in the server such as CoA, where reply_name can now +be `coa:Session-Timeout`. That allows the server to send a CoA packet +which updates the `Session-Timeout` for the user. + +In v4, when the `key` field was set to `User-Name`, the module would +also look for `Stripped-User-Name` as the key. In v4, this +functionality has been moved to the configuration. To get the same +functionality, the key should now be specified as a dynamic expansion: + +``` +key = "%{Stripped-User-Name || User-Name}" +``` + +The `count_attribute` has been removed, as it is no longer necessary. + +The old expansions `%%b` and `%%e` have been removed. This should +only affect people who are editing the queries manually. See the file +`mods-availble/sqlcounter` for more information. + +The attribute comparison has been removed. It is no longer possible +to check `Daily-Session-Time > 4` everywhere. Instead, the attribute +exists only after the `sqlcounter` module has been run. + +[#rlm_sqlippool] +=== rlm_sqlippool + +[NOTE] +==== +The `ipv6` configuration item has been deleted. It was +deprecated in 3.0.16. +==== + +Instead, use `attribute-name`. See `mods-available/sqlippool` for +more information. + +[#unix] +=== rlm_unix + +The `unix` module uses an expansion `%unix.group()` instead of +`Unix-Group`, `Group` or `Group-Name`. The old method of doing + +``` +Group == "foo" +``` + +will no longer work. + +[#rlm_winbind] +=== rlm_winbind + +The `winbind` module uses an expansion `%winbind.group()` instead of +`Winbind-Group == `. + +== Deleted Modules + +The following modules have been deleted + +[#rlm_couchbase] +=== rlm_couchbase + +This module used an old version of the Couchbase API, which is no +longer supported. Since no one stepped up to upgrade the module, it +has been removed. + +[#rlm_counter] +=== rlm_counter + +Instead of using this, please use the `sqlcounter` module with sqlite. + +It is difficult to maintain multiple implementations of the same +functionality. As a result, we have simplified the server by removing +duplicate functionality. + +[#rlm_ippool] +=== rlm_ippool + +Instead of using this, please use the `sql_ippool` module with sqlite. + +It is difficult to maintain multiple implementations of the same +functionality. As a result, we have simplified the server by removing +duplicate functionality. + +[#rlm_logintime] +=== rlm_logintime + +This module was poorly documented, and it appears that no one was using it. + +The attributes `Time-Of-Day`, `Login-Time`, and `Current-Time` have +also been removed. Any configuration which tries to use them will +result in an error. + +Dates and time attributes can be checked against date strings by +casting them: + +``` +if (Date-attribute < (date) 'Aug 1 2023 01:02:03 UTC') { + ... +} +``` + +The current time can also be checked: + +``` +if (%time() < (date) 'Aug 1 2023 01:02:03 UTC') { + ... +} +``` + + + diff --git a/doc/antora/modules/howto/pages/upgrade/processing.adoc b/doc/antora/modules/howto/pages/upgrade/processing.adoc new file mode 100644 index 00000000000..64edafe1d70 --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/processing.adoc @@ -0,0 +1,49 @@ += Processing Sections + +All of the processing sections have been renamed. Sorry, but this was +required for the new features in v4. + +[cols=",",options="header",] +|=== +| Old Name | New Name +| `authorize` | `recv Access-Request` +| `authenticate` | `authenticate ` +| `post-auth` | `send Access-Accept` +| | +| `preacct` | `recv Accounting-Request` +| `accounting` | `accounting %\{Acct-Status-Type\}` +| `accounting` | `send Accounting-Response` +| | +| `recv-coa` | `recv CoA-Request` +| `send-coa` | `send CoA-ACK` +| `send-coa` | `send CoA-NAK` +| | +| `Post-Auth-Type Reject` | `send Access-Reject` +| `Post-Auth-Type Challenge` | `send Access-Challenge` +|=== + +So, instead of the section names being (mostly) randomly named, the +names are now consistent. The `recv` sections receive packets from the +network. The `send` sections send packets back to the network. The +second name of the section is the _type_ of the packet that is being +received or sent. + +[NOTE] +==== +For accounting, packets are also processed through an +`accounting` section named after Acct-Status-Type. This process is +similar to `authenticate` for `Access-Request` packets. The goal +here is to allow a common pre-processing of accounting packets in the +`recv Accounting-Request` packet, followed by type-specific processing +in `accounting %{Acct-Status-Type}`. See sites-available/default for +examples and more information. +==== + +== Update Sections + +A major difference between v3 and v4 is that `update` sections are no +longer necessary. See the xref:howto:upgrade/unlang.adoc[Unlang Syntax] pages for more guidance and +details. + + + diff --git a/doc/antora/modules/howto/pages/upgrade/proxy.adoc b/doc/antora/modules/howto/pages/upgrade/proxy.adoc new file mode 100644 index 00000000000..43df813c7c0 --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/proxy.adoc @@ -0,0 +1,163 @@ += Proxying + +The proxy feature has undergone massive changes. The `proxy.conf` file no +longer exists, and everything in it has been removed. e.g. `realm`, +`home_server`, `home_server_pool` no longer exist. The old proxying +functionality was welded into the server core, which made many useful +features impossible to configure. + +The `radius` module now handles basic proxying to home servers. We +recommend creating one instance of the `radius` module per home +server. e.g. + +[source,unlang] +---- +radius home_server_1 { + ... configuration for home server 1 ... +} +---- + +You can then use `home_server_1` in any processing section, and the +request will be proxied when processing reaches the module. + +For ease of management, we recommend naming the modules for the host +name of the home server. + +It is often simplest to do proxying via an `authenticate proxy { ... }` +section, though that section can have any name. e.g. setting +`Auth-Type := proxy` will call the `authenticate proxy` section, and +is similar to the previous setting `Proxy-To-Realm`. + +[source,unlang] +---- +authenticate proxy { + home_server_1 +} +---- + +For more detailed examples, see the Wiki page: +https://wiki.freeradius.org/upgrading/version4/proxy. That page also +describes how to upgrade a v3 configuration to the new v4 style. + +The benefit of this approach is that the "RADIUS proxy" functionality +is just another module. It is now possible to not just fail over from +one home server to another, but also to proxy the same packet to +multiple destinations. + +== home_server + +The `home_server` configuration has been replaced with the `radius` +module. See `raddb/mods-available/radius` for examples and +documentation. + +== home_server_pool + +The `home_server_pool` configuration has been replaced with standard +unlang configurations. The various load-balancing options can be +re-created using in-place `unlang` configuration. + +The mappings for `type` are as follows: + +* `type = fail-over` - replaced with `unlang` + +[source,unlang] +---- +redundant { + home_server_1 + home_server_2 + home_server_3 +} +---- + +[NOTE] +==== +Of course, you will have to use the names of the `radius` +modules in your configuration, and not `home_server_1`, etc. +==== + +* `type = load-balance` - replaced with `unlang` + +[source,unlang] +---- +load-balance { + home_server_1 + home_server_2 + home_server_3 +} +---- + +* `type = client-balance` - replaced with `unlang` + +[source,unlang] +---- +load-balance "%{Net.Src.IP}" { + home_server_1 + home_server_2 + home_server_3 +} +---- + +* `type = client-port-balance` - replaced with `unlang` + +[source,unlang] +---- +load-balance "%%{Net.Src.IP}-%{Net.Src.Port}" { + home_server_1 + home_server_2 + home_server_3 +} +---- + +* `type = keyed-balance` - replaced with `unlang` + +[source,unlang] +---- +load-balance "%{Load-Balance-Key}" { + home_server_1 + home_server_2 + home_server_3 +} +---- + +While the `Load-Balance-Key` was a special attribute in v3, it has no +special meaning in v4. You can use any attribute or string expansion as +part of the `load-balance` key. + +=== Limitations in v3 + +In v3, it was impossible to proxy the same request to multiple +destinations. This is now trivial. In any processing section, do: + +[source,unlang] +---- +... +home_server_1 +home_server_2 +... +---- + +When processing reaches that point, it will proxy the request to +`home_server_1`, followed by `home_server_2`. + +This functionality can be used to send `Accounting-Request` packets to +multiple destinations. + +You can also catch _failed_ proxying, and do something else. In the +example below, try to proxy to `home_server_1`, if that fails, just +`accept` the request. + +[source,unlang] +---- +... +home_server_1 +if (fail) { + accept +} +... +---- + +== CoA and Originate-Coa + +The `sites-available/originate-coa` virtual server has been updated to +use the new `subrequest` feature. Please see that virtual server, and +the `subrequest` keyword for details. diff --git a/doc/antora/modules/howto/pages/upgrade/radiusconf.adoc b/doc/antora/modules/howto/pages/upgrade/radiusconf.adoc new file mode 100644 index 00000000000..0150bb51d44 --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/radiusconf.adoc @@ -0,0 +1,45 @@ += Radiusd.conf + +The following configurations have been removed. See the new `listen` +sections for their replacements. + +[width="100%",cols="30%,70%",options="header",] +|=== +| v3 | v4 +| `cleanup_delay` | replaced with `cleanup_delay` in a `listen` section. +| `reject_delay` | see `mods-available/delay`. You should list `delay` + last in any `send Access-Reject` section. +| `status_server` | see `type = Status-Server` in a new `listen` section. +|=== + +The `log` section has been updated to remove many configuration items +which are specific to RADIUS, and to Access-Request packets. Please see +`sites-available/default`, and look for the `Access-Request` +subsection there. See also xref:reference:raddb/templates.conf.adoc[`templates.conf`] +for a way to regain one global configuration for `Access-Request` +packets. + +== Instantiate Section + +The `instantiate` section has been removed. It originally started out +as a way to ensure that modules were instantiated in a particular +order. A later use of the `instantiate` section was to define +"virtual modules" for dynamic expansion. That functionality has been +moved to the `mods-available/` and `mods-enabled/` directories. +i.e. in version 4, just list the virtual module in a file, as if it +was a real module. + +See the xref:reference:raddb/mods-available/redundant_sql.adoc[redundant_sql] module +for more information. In short, a virtual module can be put into +the `mods-enabled` directory as with any other module, as with the +following text: + +[source,unlang] +---- +redundant redundant_sql { + sql1 + sql2 +} +---- + +In this case, this definition creates a `redundant_sql` virtual module. diff --git a/doc/antora/modules/howto/pages/upgrade/recommendations.adoc b/doc/antora/modules/howto/pages/upgrade/recommendations.adoc new file mode 100644 index 00000000000..98b9f963851 --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/recommendations.adoc @@ -0,0 +1,79 @@ += Recommendations + +We recommend manually converting the `update` sections to the new +method. The biggest change that confuses people is the old `+=` +operator does not work the same way as before. + +Instead of doing: + +``` +Reply-Message += "foo" +``` + +you should edit the `reply` list, using the `+=` operator: + +``` +reply += { + Reply-Message = "foo" +} +``` + +We also recommend removing double-quotes from xlat expansions where +possible. The temptation in v3 is to just add double quotes to +everything, and hope it all works out. This is no longer necessary in +v4. + +For example, in v3 you would do: + +``` +update reply { + Framed-IP-Address := "%{sql:SELECT ...}" +} +``` + +In v4, you can remove the `update`, and rewrite the SQL call to: + +``` +reply.Framed-IP-Address := %sql("SELECT ...") +``` + +Using double quotes everywhere means that every bit of data gets +converted to printable strings, and then back to it's real data type +(`ipaddr` in the above example). Removing the double quotes means +that there is less work going on, which means higher performance. + + +== Best Practise + +In v3, many people had a habit of just adding `"..."` around _everything_. For example: + +.Bad practice - using "" everywhere +[source,unlang] +---- +update reply { + Reply-Message := "%{User-Name}" +} + +... + +if ("%{User-Name}" == "bob") { + ... +} +---- + +This practice is not recommended. It was never necessary, and it's not clear why it became a (bad) habit. + +In v4, it is clearer, simpler, and faster to just use `unlang` syntax correctly. + +.Good practice - just rely on the server to do the right thing + +[source,unlang] +---- +reply.Reply-Message := User-Name + +... + +if (User-Name == "bob") { + ... +} +---- diff --git a/doc/antora/modules/howto/pages/upgrade/unlang.adoc b/doc/antora/modules/howto/pages/upgrade/unlang.adoc new file mode 100644 index 00000000000..ca34ae9daa0 --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/unlang.adoc @@ -0,0 +1,89 @@ += Unlang Syntax + +Many new xref:reference:unlang/index.adoc[unlang] keywords have been added. + +Data type casts have changed from ` ...` to `(ipaddr) ...` + +[#ampersand] +== "&" is Deprecated + +In FreeRADIUS v4, the ampersand (&) is no longer used in configuration files. It doesn't reference specific attributes or define virtual attributes anymore. New features replace the "&" and allow for a more structured configuration. + +The main reasons for removing the "&" are to improve clarity and structure. In v3, attribute names were in a flat list, which could lead to naming conflicts. FreeRADIUS v4 introduces hierarchical attributes, making the old syntax unnecessary. + +The developers moved the functionality of the "&" into Unlang and other parts of the configuration. + +=== Attribute Aliases + +Old v3 attribute names are available through "alias" dictionaries for compatibility. However, using the new v4 hierarchical names is recommended. + +=== Virtual Modules + +The deprecated instantiate section sometimes used the & syntax for dynamic expansion. Now, FreeRADIUS lists virtual modules in the mods-available/ and mods-enabled/ directories. + +=== Unlang Policy Language + +The configuration language (Unlang) is now more consise and robust. You now edit attributes with specific statements in processing sections. The old-style `update` sections are deprecated. + +== Keyword Changes + +[#foreach] +=== `foreach` + +The xref:reference:unlang/foreach.adoc[foreach] keyword has changed syntax. + +Instead of + +---- +foreach &reply.Filter-Id { + if ("%{Foreach-Variable-0}" == ...) { +} +---- + +You can define a xref:reference:unlang/local.adoc[local variable] using +the following syntax: + +---- +foreach thing (reply.Filter-Id[*]) { + if (thing == ...) { +} +---- + +The result is much simpler and clearer. + +[#update] +=== `update` + +The `update` sections are deprecated. The new way to +xref:reference:unlang/edit.adoc[edit] is much simpler. +See the xref:reference:unlang/update.adoc[update] documentation for a +description of what has changed, and how to use the attribute new +xref:reference:unlang/edit.adoc[edit] functionality. + +The server has limited support for "auto-conversion" of `update` +sections to the new syntax. Documentation is TBD. + +It is now possible to just edit attributes "in place". For example, +instead of doing this: + +[source,unlang] +---- +if (User-Name == "bob") { + update reply { + Reply-Message := "Hello, %{User-Name}" + } +} +---- + +You can now do this: + +[source,unlang] +---- +if (User-Name == "bob") { + reply.Reply-Message := "Hello, %{User-Name}" +} +---- + +As with any upgrade across major version numbers, there are caveats. +See the full xref:reference:unlang/update.adoc[update] documentation +for further guidance. diff --git a/doc/antora/modules/howto/pages/upgrade/virtualsvr.adoc b/doc/antora/modules/howto/pages/upgrade/virtualsvr.adoc new file mode 100644 index 00000000000..dde6a77004b --- /dev/null +++ b/doc/antora/modules/howto/pages/upgrade/virtualsvr.adoc @@ -0,0 +1,113 @@ += Virtual Servers + +There are some changes to the virtual servers in `v4`. First, every +virtual server has to begin with an entry: + +``` +namespace = ... +``` + +For RADIUS, use: + +``` +namespace = radius +``` + +This tells the server what protocol is being used in that virtual +server. This configuration was not necessary in v3, because each +protocol was pretending to be RADIUS. That was simple to program at +the time and worked for some things, but it was not the best approach. + +In v4, each protocol is completely independent, and RADIUS is no +longer built into the server core. i.e. The server core does modules, +configuration files, policies, etc. RADIUS has been relegated to just +another plug-in protocol, with the same status as DHCPv4 and DHCPv6. + +Every example virtual server in the `sites-enabled/` directory +contains a `namespace` parameter. Please look at those files for +examples of configuring and running each supported protocol. + +== Listen Sections + +The `listen` sections have changed. There is now a `type` entry, which +lists the packet type by their correct name (e.g._`Access-Request` +instead of `auth`). To accept multiple kinds of packets, just list +`type` multiple times: + +``` +type = Access-Request +type = Accounting-Request +``` + +Each `listen` section also has a `transport` entry. This +configuration can be left out for `headless` servers, such as +`inner-tunnel`. For example, setting UDP transport is done via: + +``` +transport = udp +``` + +Each type of transport has its configuration stored in a subsection +named for that transport: + +``` +transport = udp +udp { + ... udp transport configuration ... +} +``` + +For `udp`, the configuration entries are largely the same as for v3. +e.g. `ipaddr`, `port`, etc. + +The `listen` section then compiles each +xref:index.adoc#_processing_sections[Processing Section] based on the named packet +types. It has a `recv` section for receiving packets, and a `send` +section for sending packets, as seen in the following example: + +[source,unlang] +---- +recv Access-Request { + ... unlang ... +} + +send Access-Accept { + ... unlang ... +} +---- + +This configuration is different from v3. The benefit of the change is +that it is much easier to understand. Instead of using confusing names +such as `Post-Auth-Type Reject`, the server now just uses `send +Access-Reject`. + +See also xref:index.adoc#_processing_sections[Processing Section] for how the +`unlang` statements are parsed. + +[#clients] +== Clients + +The server supports global clients in the `clients.conf` file, as with +v3. + +Client can also be defined in a `client` subsection of a virtual +server. Unlike `v3`, there is no need to have a `clients` section +which "wraps" one or more `client` definitions. See +`sites-available/default` for examples. + +The server also supports dynamic clients. See +`sites-available/dynamic_clients` for a worked example. There are many +changes from v3. First, there is no need to have a `client` definition +which contains a network. Instead, there is a `network` section which +has a number of `allow` and `deny` rules. Second, dynamic clients +can be defined on a per-connection basis. Finally, the +`sites-available/dynamic_clients` virtual server has full access to +the entire RADIUS packet. + +The result of these changes is that it is now possible to have multiple +clients behind a NAT gateway, and to have different shared secrets for +each client. e.g._by keying off of the `NAS-Identifier` attribute. + +The dynamic client functionality behaves the same for all protocols +supported by the server. e.g. RADIUS, DHCP, VMPS, TACACS+, etc. +