From: Alan T. DeKok Date: Thu, 2 Oct 2025 16:34:52 +0000 (-0400) Subject: reformat and word wrap X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7e430159650f32cbc7ad3afa6754912c7b06f51d;p=thirdparty%2Ffreeradius-server.git reformat and word wrap --- diff --git a/doc/antora/modules/ROOT/pages/index.adoc b/doc/antora/modules/ROOT/pages/index.adoc index fd7a05d154..a8e911c43d 100644 --- a/doc/antora/modules/ROOT/pages/index.adoc +++ b/doc/antora/modules/ROOT/pages/index.adoc @@ -11,57 +11,175 @@ RELEASED. USE AT YOUR OWN RISK.* Please wait for an official release before using version 4 (v4). ==== -FreeRADIUS is a free and open-source implementation of the RADIUS (Remote Authentication Dial In User Service) protocol. It provides centralised authentication, authorisation, and accounting (AAA) support for network access management. FreeRADIUS is a robust, modular, high-performance server that's deployed in VPNs, Wi-Fi, and enterprise networks.  - -The default settings are sufficient for a simple install and basic functionality. The software’s flexibility presents challenges when configuring it for advanced or specialized environments. There are many options and customisations for the FreeRADIUS server. Administrators must decide how and what settings to change, which may be complex and problematic. - -The FreeRADIUS v4 documentation has been significantly revised compared to version 3. The updated documentation addresses both basic and advanced questions, covering topics such as how the software works, how to configure it, and various use cases. Additionally, the FreeRADIUS team has provided practical examples, developer-focused information, and extra resources to help users better understand and deploy the software. This ensures that users of all experience levels can find the information they need. +FreeRADIUS is a free and open-source implementation of the RADIUS +(Remote Authentication Dial In User Service) protocol. It provides +centralised authentication, authorisation, and accounting (AAA) +support for network access management. FreeRADIUS is a robust, +modular, high-performance server that's deployed in VPNs, Wi-Fi, and +enterprise networks. + +The default settings are sufficient for a simple install and basic +functionality. The software’s flexibility presents challenges when +configuring it for advanced or specialized environments. There are +many options and customisations for the FreeRADIUS +server. Administrators must decide how and what settings to change, +which may be complex and problematic. + +The FreeRADIUS v4 documentation has been significantly revised +compared to version 3. The updated documentation addresses both basic +and advanced questions, covering topics such as how the software +works, how to configure it, and various use cases. Additionally, the +FreeRADIUS team has provided practical examples, developer-focused +information, and extra resources to help users better understand and +deploy the software. This ensures that users of all experience levels +can find the information they need. == Sections in this guide -* xref:getstarted.adoc[Getting Started] guides you through a basic install, xref:debugging/radiusd_X.adoc[debugging], and xref:trouble-shooting/index.adoc[troubleshooting] the server. More information about where to xref:gethelp.adoc[get help], xref:bestpractices.adoc[best practices], and a xref:faq.adoc[FAQ] are found here to help you resolve issues. -* xref:concepts:index.adoc[Concepts] explains the xref:concepts:freeradius.adoc[FreeRADIUS] server, xref:concepts:aaa/aaa.adoc[AAA] services, and it's related xref:concepts:components/architecture.adoc[system components] for newcomers. A description of the xref:concepts:session/radius_session.adoc[sessions], xref:concepts:protocol/authproto.adoc[protocols], and xref:concepts:resources.adoc[resources] help further your understanding of FreeRADIUS. -* xref:reference:index.adoc[Reference documentation] outlines the entire xref:reference:unlang/index.adoc[unlang policy language] syntax and xref:reference:raddb/index.adoc[configuration files]. More configuration information for xref:reference:policy/index.adoc[policies], xref:reference:raddb/mods-available/index.adoc[modules], xref:reference:raddb/mods-available/doc/datastore.adoc[datastores] and xref:reference:raddb/sites-available/index.adoc[virtual servers] is accessed here. -* xref:howto:index.adoc[Howto Guides] gives step-by-step instructions on how to xref:howto:installation/index.adoc[install and upgrade] FreeRADIUS. Many other configuration guides are here for configuring xref:howto:modules/configuring_modules.adoc[modules], xref:howto:datastores/index.adoc[datastores], xref:howto:protocols/index.adoc[protocols], xref:howto:os/index.adoc[certificates], and xref:howto:optimization/index.adoc[optimisation]. -* xref:tutorials:new_user.adoc[Tutorials] show real-world configurations through setups, debugging, and exercises. -* xref:developers:index.adoc[Developers] outlines the xref:developers:coding-methods.adoc[coding standards], xref:developers:coverage.adoc[coverage], and xref:developers:coccinelle.adoc[patches] used when developing. This guide includes information about xref:developers:bugs.adoc[bugs reports], and xref:developers:contributing.adoc[contributing] to the project using GitHub. +* xref:getstarted.adoc[Getting Started] guides you through a basic + install, xref:debugging/radiusd_X.adoc[debugging], and + xref:trouble-shooting/index.adoc[troubleshooting] the server. More + information about where to xref:gethelp.adoc[get help], + xref:bestpractices.adoc[best practices], and a xref:faq.adoc[FAQ] + are found here to help you resolve issues. + +* xref:concepts:index.adoc[Concepts] explains the + xref:concepts:freeradius.adoc[FreeRADIUS] server, + xref:concepts:aaa/aaa.adoc[AAA] services, and it's related + xref:concepts:components/architecture.adoc[system components] for + newcomers. A description of the + xref:concepts:session/radius_session.adoc[sessions], + xref:concepts:protocol/authproto.adoc[protocols], and + xref:concepts:resources.adoc[resources] help further your + understanding of FreeRADIUS. + +* xref:reference:index.adoc[Reference documentation] outlines the + entire xref:reference:unlang/index.adoc[unlang policy language] + syntax and xref:reference:raddb/index.adoc[configuration + files]. More configuration information for + xref:reference:policy/index.adoc[policies], + xref:reference:raddb/mods-available/index.adoc[modules], + xref:reference:raddb/mods-available/doc/datastore.adoc[datastores] + and xref:reference:raddb/sites-available/index.adoc[virtual servers] + is accessed here. + +* xref:howto:index.adoc[Howto Guides] gives step-by-step instructions + on how to xref:howto:installation/index.adoc[install and upgrade] + FreeRADIUS. Many other configuration guides are here for configuring + xref:howto:modules/configuring_modules.adoc[modules], + xref:howto:datastores/index.adoc[datastores], + xref:howto:protocols/index.adoc[protocols], + xref:howto:os/index.adoc[certificates], and + xref:howto:optimization/index.adoc[optimisation]. + +* xref:tutorials:new_user.adoc[Tutorials] show real-world + configurations through setups, debugging, and exercises. + +* xref:developers:index.adoc[Developers] outlines the + xref:developers:coding-methods.adoc[coding standards], + xref:developers:coverage.adoc[coverage], and + xref:developers:coccinelle.adoc[patches] used when developing. This + guide includes information about xref:developers:bugs.adoc[bugs + reports], and xref:developers:contributing.adoc[contributing] to the + project using GitHub. == Why v4? -It's obvious why a new major release is a good idea. FreeRADIUS v4 was necessary to improve protocol support and enhance security. Using a modernized codebase, a more flexible configuration is available using virtual servers. This change extends the protocol support for DHCP, VMPS, and TACAS+, as they are no longer hardcoded into the server core. Perhaps, a better question is, "Why is v4 taking so long? - -Initially, the FreeRADIUS team planned only a minor release of version 3.x. As we examined the codebase, there were many long-standing issues that needed fixing. Because the core team is small, the v4 rework required significant time and effort. The team still released a minor version 3.2 while simultaneously developing version 4. The good news is that, most of the problematic issues are fixed in v4. The FreeRADIUS software is more reliable and easier to use. +It's obvious why a new major release is a good idea. FreeRADIUS v4 was +necessary to improve protocol support and enhance security. Using a +modernized codebase, a more flexible configuration is available using +virtual servers. This change extends the protocol support for DHCP, +VMPS, and TACAS+, as they are no longer hardcoded into the server +core. Perhaps, a better question is, "Why is v4 taking so long? + +Initially, the FreeRADIUS team planned only a minor release of version +3.x. As we examined the codebase, there were many long-standing issues +that needed fixing. Because the core team is small, the v4 rework +required significant time and effort. The team still released a minor +version 3.2 while simultaneously developing version 4. The good news +is that, most of the problematic issues are fixed in v4. The +FreeRADIUS software is more reliable and easier to use. Here's a short list of the most confusing or complicated v3 issues: -* Access-Request packets are processed though an `authorize` section. This legacy naming convention goes back to 2001. -* Run-time functions (dynamic expansions) have a syntax of `%{name: args...}`. The reasons for this are many, but are no longer valid. -* Attributes can't be assigned new values like normal programming languages. You have to use an `update` section. -* Expressions are not supported. You can't do `foo = 1 + 2`. You have to do `update { foo = %{expr: 1 + 2} }`. This is terrible and convoluted. -* Proxying is welded into the server core, which makes it difficult to run policies around proxying. - * There is a `fallback` configuration, but this is specific to proxying, and doesn't use the standard module failover mechanisms. - * It's impossible to send packets as a client, packets can only be proxied. Except for `CoA-Request`, which has a magic `originate-coa` functionality. -* Much of the configuration has special-purpose flags or settings for special cases. +* Access-Request packets are processed though an `authorize` section. + This legacy naming convention goes back to 2001. -The result is that configuring the server is more difficult than it needs to be. These issues needed to be fixed, and they have been resolved in v4. +* Run-time functions (dynamic expansions) have a syntax of `%{name: + args...}`. The reasons for this are many, but are no longer valid. -Here is a *complete* list of issues remaining in v4, as compared to most programming languages: +* Attributes can't be assigned new values like normal programming + languages. You have to use an `update` section. -* xref:reference:raddb/mods-available/all_modules.adoc[Modules] are run in-place, i.e., they act like language keywords on their own. -* The interpreter tracks xref:reference:unlang/return_codes.adoc[return codes] for each instruction it runs. -* xref:reference:xlat/all.adoc[Function] calls use a leading `%`, e.g., `%length('foo')`. +* Expressions are not supported. You can't do `foo = 1 + 2`. You have + to do `update { foo = %{expr: 1 + 2} }`. This is terrible and + convoluted. -That's it. +* Proxying is welded into the server core, which makes it difficult to + run policies around proxying. + * There is a `fallback` configuration, but this is specific to + proxying, and doesn't use the standard module failover mechanisms. + * It's impossible to send packets as a client, packets can only be + proxied. Except for `CoA-Request`, which has a magic + `originate-coa` functionality. -As a result of recent improvements, the server has become much simpler to understand and configure. However, there are many more benefits to version 4 as discussed in <>. +* Much of the configuration has special-purpose flags or settings for + special cases. -Additionally, the documentation is now structured to help users navigate and find information efficiently. The content is divided into main sections and further broken down into sub-sections with smaller, focused pages. As well, there are links to related topics, making it easier to access relevant details. This hierarchy allows users to find the instructions or guidance they need. For example, all the xref:howto:index.adoc[Howto] guides are a series of small steps to guide you through a task. +The result is that configuring the server is more difficult than it +needs to be. These issues needed to be fixed, and they have been +resolved in v4. -The xref:reference:unlang/index.adoc[unlang policy language] is thorough and *complete*. All xref:reference:raddb/index.adoc[configuration files] are fully documented along with configuration items such as xref:reference:policy/index.adoc[policies], xref:reference:raddb/mods-available/index.adoc[modules], xref:reference:raddb/mods-available/doc/datastore.adoc[datastores] and xref:reference:raddb/sites-available/index.adoc[virtual servers]. +Here is a *complete* list of issues remaining in v4, as compared to +most programming languages: -Each xref:reference:unlang/keywords.adoc[keyword] and every xref:reference:xlat/index.adoc[dynamic expansion] function has a dedicated documentation page, making it easy for users to find detailed information about specific features. Additionally, all xref:reference:raddb/index.adoc[configuration files] are *automatically* converted to HTML and included in the documentation tree. This approach ensures that users have convenient access to up-to-date and comprehensive reference material for every aspect of the software. +* xref:reference:raddb/mods-available/all_modules.adoc[Modules] are + run in-place, i.e., they act like language keywords on their own. + +* The interpreter tracks + xref:reference:unlang/return_codes.adoc[return codes] for each + instruction it runs. + +* xref:reference:xlat/all.adoc[Function] calls use a leading `%`, + e.g., `%length('foo')`. + +That's it. -However, some documentation pages may still reference the older version 3 syntax and examples. These outdated pages are clearly labeled, and the FreeRADIUS team is actively working to update them. +As a result of recent improvements, the server has become much simpler +to understand and configure. However, there are many more benefits to +version 4 as discussed in <>. + +Additionally, the documentation is now structured to help users +navigate and find information efficiently. The content is divided into +main sections and further broken down into sub-sections with smaller, +focused pages. As well, there are links to related topics, making it +easier to access relevant details. This hierarchy allows users to find +the instructions or guidance they need. For example, all the +xref:howto:index.adoc[Howto] guides are a series of small steps to +guide you through a task. + +The xref:reference:unlang/index.adoc[unlang policy language] is +thorough and *complete*. All +xref:reference:raddb/index.adoc[configuration files] are fully +documented along with configuration items such as +xref:reference:policy/index.adoc[policies], +xref:reference:raddb/mods-available/index.adoc[modules], +xref:reference:raddb/mods-available/doc/datastore.adoc[datastores] and +xref:reference:raddb/sites-available/index.adoc[virtual servers]. + +Each xref:reference:unlang/keywords.adoc[keyword] and every +xref:reference:xlat/index.adoc[dynamic expansion] function has a +dedicated documentation page, making it easy for users to find +detailed information about specific features. Additionally, all +xref:reference:raddb/index.adoc[configuration files] are +*automatically* converted to HTML and included in the documentation +tree. This approach ensures that users have convenient access to +up-to-date and comprehensive reference material for every aspect of +the software. + +However, some documentation pages may still reference the older +version 3 syntax and examples. These outdated pages are clearly +labeled, and the FreeRADIUS team is actively working to update them. We hope that this discussion explains why v4 took so long. We believe that the result is worth the wait. @@ -95,47 +213,74 @@ As of the time of this release, FreeRADIUS: * RADIUS/TLS (RadSec) isn't available. * The "haproxy" and "reverse CoA" features aren't implemented. -Administrators using version 3 that wish to upgrade to version 4 -must read the xref:howto:installation/upgrade.adoc[upgrade] guide. -This guide explains the differences between the two versions and -how an existing configuration is reproduced in the latest -release. Do *not* use version 3 configuration files with version 4. These configuration files are *not* compatible on this major version upgrade. +Administrators using version 3 that wish to upgrade to version 4 must +read the xref:howto:installation/upgrade.adoc[upgrade] guide. This +guide explains the differences between the two versions and how an +existing configuration is reproduced in the latest release. Do *not* +use version 3 configuration files with version 4. These configuration +files are *not* compatible on this major version upgrade. -FreeRADIUS version 4 took a long time to incorporate all these changes. We're confident that the improvements and new features introduced in version 4 make the extended development period worthwhile for users. +FreeRADIUS version 4 took a long time to incorporate all these +changes. We're confident that the improvements and new features +introduced in version 4 make the extended development period +worthwhile for users. [WARNING] ==== -*Don't* open bug reports about previous features as missing. All such bug reports will be closed without comment. +*Don't* open bug reports about previous features as missing. All such + bug reports will be closed without comment. -*Don't* create 4.0.0-alpha packages for your operating systems or Linux distributions. Creating "alpha" packages results in upset users that install that package. The users believed that the package is stable and they run into issues. +*Don't* create 4.0.0-alpha packages for your operating systems or + Linux distributions. Creating "alpha" packages results in upset users + that install that package. The users believed that the package is + stable and they run into issues. ==== == Network requirements -A RADIUS server requires a network connection with access to UDP ports 1812 for authentication and 1813 for the accounting traffic. These ports must be reachable by network devices like access points or VPN gateways that send authentication requests to the server. All network devices are configured with the appropriate IP address and network settings to facilitate communication with clients on the network. +A RADIUS server requires a network connection with access to UDP ports +1812 for authentication and 1813 for the accounting traffic. These +ports must be reachable by network devices like access points or VPN +gateways that send authentication requests to the server. All network +devices are configured with the appropriate IP address and network +settings to facilitate communication with clients on the network. === Operating systems -The FreeRADIUS protocol works on all Unix based systems. FreeRADIUS doesn't -run natively under Windows. +The FreeRADIUS protocol works on all Unix based systems. FreeRADIUS +doesn't run natively under Windows. If you received a Windows version +of FreeRADIUS, it is illegal. === CPU/RAM/disk space requirements -A FreeRADIUS server has minimal requirements. A FreeRADIUS installation uses 8 MB of RAM, less than 100 MB of disk space, and minimal CPU power. An Internet Service Provider (ISP) with less than 10,000 users have no issues with a basic setup. ISPs with more than 10,000 users, focuses on system design such as more servers and databases. +A FreeRADIUS server has minimal requirements. A FreeRADIUS +installation uses 8 MB of RAM, less than 100 MB of disk space, and +minimal CPU power. An Internet Service Provider (ISP) with less than +10,000 users have no issues with a basic setup. ISPs with more than +10,000 users, focuses on system design such as more servers and +databases. === Datastores -The server reads or writes to any database and both LDAP and SQL can be in the same configuration simultaneously. The database queries are customizable and can be adapted to any custom schema. The server supports fail-over and load balancing across multiple databases. There are no pre-set limits to the number, or type, of databases used. +The server reads or writes to any database and both LDAP and SQL can +be in the same configuration simultaneously. The database queries are +customizable and can be adapted to any custom schema. The server +supports fail-over and load balancing across multiple databases. There +are no pre-set limits to the number, or type, of databases used. == Debugging -If you have *any* issues with your server, then restart the server -in xref:debugging/radiusd_X.adoc[debugging] mode. Review the logs to determine what the root cause is and make changes. Do only *one* change -at a time and restart your server. +If you have *any* issues with your server, then restart the server in +xref:debugging/radiusd_X.adoc[debugging] mode. Review the logs to +determine what the root cause is and make changes. Do only *one* +change at a time and restart your server. == More information -The https://www.inkbridge.io/[InkBridge Networks] FreeRADIUS experts are available to help you with your software deplyments, configurations, and ongoing support. See xref:gethelp.adoc[Get Help] for more information and details. +The https://www.inkbridge.io/[InkBridge Networks] FreeRADIUS experts +are available to help you with your software deplyments, +configurations, and ongoing support. See xref:gethelp.adoc[Get Help] +for more information and details. // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS.