-= Getting Started with FreeRADIUS
+= Getting Started
-This page describes how to perform the initial install and
-configuration of FreeRADIUS using a package. FreeRADIUS pre-built
-packages are available from
-https://packages.inkbridgenetworks.com[InkBridge Networks]. This site
-contains the most current packages for all common OS platforms for the
-latest FreeRADIUS release.
+To begin with FreeRADIUS, install it on your system and configure a basic setup with a test user and client. Next, test the server’s functionality in debug mode (`radiusd -X`). This process includes editing the client and users files to add a test user and client.
-== Get the Source
+== Get the source
-This page describes how to perform the initial install and
-configuration of FreeRADIUS. FreeRADIUS can be installed using the
-pre-built packages available from
-https://packages.inkbridgenetworks.com[InkBridge Networks]. This site
+FreeRADIUS can be installed using the pre-built packages available from
+https://packages.inkbridgenetworks.com[InkBridge Networks]. This site
contains packages for all common OS platforms and has the most current
packages for the latest release.
the output from `radiusd -X`, refer to the
xref:debugging/radiusd_X.adoc[debugging] page for more details.
-== Initial Tests
+== Initial tests
Test basic authentication by editing the
xref:reference:raddb/mods-config/files/users.adoc[users] file and add the
testing Password.Cleartext := "password"
```
-Save the file and restart the server in debugging mode (`radiusd -X`).
+Save the file and restart the server in xref:debugging/radiusd_X.adoc[debugging mode] (`radiusd -X`).
Open a second terminal window and run radtest by issuing the command:
```
Your next step is to add more users.
-== Add a Client
+== Add a client
Devices that communicate directly with the RADIUS server are the
clients that we need to configure next. These clients can be a
minimum of effort. Failure to follow them leads to days of frustration
and wasted effort.
-## Configure the Server
+## Configure the server
To create complex configurations with a minimum of effort, follow the
steps to configure the server *ONE* change at a time:
Your next step is to configure more server components.
-## More Information
+## More information
-For specific problem solving, we recommend the xref:howto:index.adoc[Howto] guide.
-For configuring and testing individual modules, refer to
+For specific problem solving, we recommend the xref:howto:index.adoc[Howto] guide. For configuring and testing individual modules, refer to
xref:howto:modules/configuring_modules.adoc[Modules].
All of the xref:reference:raddb/index.adoc[Configuration Files] are
available in hypertext format.
-A detailed xref:reference:unlang/index.adoc[unlang] reference guide
+A detailed xref:reference:unlang/index.adoc[Unlang] reference guide
that describes the syntax and functionality of the keywords, data
-types, etc. used in the `unlang` processing language.
+types, etc. used in the `unlang` policy language.
There is also xref:developers:index.adoc[Developers] documentation
that includes the APIs references.
*VERSION 4 IS IN DEVELOPMENT AND HAS NOT BEEN OFFICIALLY
RELEASED. USE AT YOUR OWN RISK.*
-Please wait for an official release before using version 4 (v4)
+Please wait for an official release before using version 4 (v4).
====
-FreeRADIUS is a complex piece of software with many configuration
-options. In most circumstances, the default configuration works with
-minimal effort to install a server. For more complex requirements,
-FreeRADIUS can be difficult to setup because of more features and
-infinite configurations. The question for an administrator, then, is
-what piece of the configuration to change, and how to change it.
-
-This updated documentation answers your basic and advanced questions about
-functionality, configuration, and other scenarios. The FreeRADIUS team
-included examples, developer information,
-and extra resources to assist you.
-
-These documentation pages have had many updates from version 3. The
-xref:reference:unlang/index.adoc[Unlang] policy language is fully
-documented. There is complete documentation for all
-xref:reference:raddb/index.adoc[configuration files], including all
-configuration items. However, there may still be some pages which
-still refer to the old v3 syntax and examples. We will be updating
-those over time, as we can.
-
-The documentation is organized into main sections, sub-sections with smaller pages, and links to pertinent information. This hierarchy ensures that
-you can find information easily and extract the instructions you need. For example, all the Howto guides are a series of small steps to guide you through a task. The main sections by subject area and organized by
-task-based results as follows:
-
-* xref:getstarted.adoc[Getting Started] helps you install the server, along with a xref:faq.adoc[FAQ] to answer your questions, and xref:trouble-shooting/index.adoc[Troubleshooting] tips to resolve any issues.
-* xref:concepts:index.adoc[Concepts] provides a high level explanation for newcomers and additional RADIUS xref:concepts:resources.adoc[Resources] for further reading.
-* xref:reference:index.adoc[Reference Documentation] details the xref:reference:unlang/index.adoc[Unlang] syntax and xref:reference:raddb/index.adoc[Configuration Files].
-* xref:howto:index.adoc[Howto] gives step-by-step instructions and includes xref:howto:installation/index.adoc[Installing] and xref:howto:installation/upgrade.adoc[Upgrading] guides.
-* xref:tutorials:new_user.adoc[Tutorials] explain real-world configurations through setups, debugging, and exercises.
-* xref:developers:index.adoc[Developers] outlines coding standards, raising defects, and using GitHub.
+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.
== Why v4?
-It's obvious why a new major release is a good idea. Perhaps a better question is "Why is v4 taking so long?"
+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?
-The original intention was to do a 3.1 release. However, as we dug
-into the code, we realized that there were a large number of
-long-standing issues that we would like to solve. As the core
-FreeRADIUS team is very small, this rework has taken a lot of time.
+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.
-The good news is that we have fixed pretty much all of the "weird"
-things which confused people in v3. Here is a short list of the top
-things are confusing or weird in v3:
+Here's a short list of the most confusing or complicated v3 issues:
-* Access-Request packets were processed though an `authorize` section. This naming goes back to 2001.
-* Run-time functions (dynamic expansions) had a syntax of `%{name: args...}`. The reasons for this are many, but are no longer valid.
-* attributes cannot be assigned new values like normal programming languatges. 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 pretty terrible.
+* 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 normal module failover mechanisms
- * It is impossible to send packets as a client, packets can only be proxied. Except for `CoA-Request`, which has a magic `originate-coa` functionality.
+ * 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.
-The result is that configuring the server is more difficult than it needs to be. Those issues needed to be fixed.
+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.
-Here is a _complete_ list of oddities and weirdness in v4, as compared to most programming languages:
+Here is a *complete* list of issues remaining in v4, as compared to most programming languages:
-* 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.
-* function calls use a leading `%`, e.g. `%length('foo')`.
+* 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.
-The result is that the server is much easier to understand and
-configure. But we're not done explaining the benefits of v4.
+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 <<whatsnew, What's new in FreeRADIUS v4>>.
+
+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.
-While the documentation in v3 was pretty good, the documentation in v4
-is _complete_. Every single xref:reference:unlang/keywords.adoc[keyword] has
-its own documentation page. Every single xref:reference:xlat/index.adoc[dynamic
-expansion] function has its own documentation page. Every single
-xref:reference:raddb/index.adoc[configuration file] is _automatically_ converted
-to HTML and placed into the documentation tree.
+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].
-Plus, all of the documentation is organized and cross referenced.
-This means that it is easy to find documentation for anything that the
-server does, and the documentation explains exactly how that thing
-works.
+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.
-The documentation isn't perfect, of course. We are still working on
-the xref:howto:index.adoc[How-To] documentation. Some of those pages
-still contain documentation for v3, but they are being actively worked
-on.
+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.
+[#whatsnew]
== What's new in FreeRADIUS v4
FreeRADIUS v4 is in "alpha" right now. If FreeRADIUS v4 works,
* 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[upgrading] guide.
+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.
+
[WARNING]
====
*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.
====
-== Network Requirements
+== 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.
-=== Operating Systems
+=== Operating systems
The FreeRADIUS protocol works on all Unix based systems. FreeRADIUS doesn't
run natively under Windows.
=== 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
+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
+== More information
-The https://www.inkbridge.io/[RADIUS experts] are available to help you with your FreeRADIUS. See xref:gethelp.adoc[Getting 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.
projects / thirdparty / freeradius-server.git / commitdiff
