= Introduction

[WARNING]
====
*VERSION 4 IS IN DEVELOPMENT AND HAS NOT BEEN OFFICIALLY
RELEASED. USE AT YOUR OWN RISK.*

The configuration may change. The behavior may change. The
documentation may change.

Please wait for an official release before using version 4.
====

This is the documentation for FreeRADIUS, version 4. The documentation
is available under the Creative Commons Non-Commercial license, as given
in the `LICENSE` file in this directory.

FreeRADIUS is a complex piece of software with many configuration
options. However, we have taken great care to make the default
configuration work in most circumstances. The result is that for most
simple systems, it is trivial to install and configure the server. For
those situations, this documentation will serve to answer basic
questions about functionality, configuration, etc.

For more complex requirements, FreeRADIUS can be difficult to
configure. The reason for this difficulty is that the server can do
almost anything, which means that there are a near-infinite number of
ways to configure it. The question for an administrator, then, is what
piece of the configuration to change, and how to change it.

This documentation will answer those questions. The FreeRADIUS team has
put substantial effort into writing the documentation for this release.
Everything in the server is fully documented, and there are many
`how-to` guides available.

The documentation is split into sections by subject area, oganized by
desired outcome. At a high level, the subject areas describe:

* xref:concepts:index.adoc[Concepts] and introduction for newcomers.
* xref:installation:index.adoc[Installing] and xref:installation:upgrade.adoc[upgrading] FreeRADIUS.
* The syntax of the xref:reference:unlang/index.adoc[unlang] processing language.
* The xref:raddb:index.adoc[configuration files] located in `/etc/raddb/`, or `/etc/freeradius/`
* Various xref:howto:index.adoc[how-to] guides.
* xref:developers:index.adoc[Developer documentation].

This organization means that for example, the `ldap` module will have
documentation located in multiple places. We feel that organizing the
documentation by desired _goal_ is better than the alternatives.

Within each section, the documentation is split into small pages, which
are generally no more than a few screens worth of information. We feel
that having multiple small pages with cross-links is more helpful than
having a smaller number of enormous pages. This division ensures that
(for example) the `how-to` guides are split into a series of small
steps, each of which can be performed quickly.

We hope that this extended documentation will address any lingering
concerns about the quality of the FreeRADIUS documentation.

== Current Limitations of 4.0.0

As of the time of writing this documentation, the server has the
following limitations:

* RADIUS/TLS (RadSec) is not implemented.
* TTLS, PEAP, TEAP, and EAP-FAST are not implemented.
* The "haproxy" and "reverse CoA' features are not implemented
* The Perl, Python, and Lua modules do not fully support the v4 "nested" attributes.
* Enums are now prefixed with `::`, as in `Service-Type == ::Framed-User`.
  * The server still does not always require (or print) the `::` prefix.  That will change.
* As a result of adding `::` for enums, we can then remove the requirement to use `&` as a prefix for attribute names.
  * This change may require changes to all of the configuration.  We will try to allow `&` or not, but that may not be possible.
* Dynamic expansions have changed from `%{md5:foo}` to `%md5(foo)`.
  * The new syntax is much clearer, and supports multiple comma-separated arguments: `%function(a, b, c)`
  * Expansions such as `%{User-Name}` will still work.  We plan on making `%{1+2}` work, too.
  * Alternation `%{%{foo}:-%{bar}}` has been replaced by `%{&foo || &bar}`, which is clearer and uses less nesting.

Please be aware that v4 is in "alpha" right now.  If it works, great.
If it doesn't work, then please return to using v3.

[WARNING]
====
Please do not open bug reports about those features being missing.
All such bug reports will be closed without comment.

We do not recommend that operating systems or Linux distributions
create their own packages for 4.0.0-alpha.  Our experience has been
that packaging "alpha" releases results in confused and upset users.
People _will_ install it due to the belief that "it's stable because
it is packaged".  They will then run into issues, and will blame us.

Such behavior is antisocial and is strongly discouraged.
====

== Changes From Earlier Versions

In previous releases, FreeRADIUS had the following limitations:

* it was impossible to proxy one packet to multiple destinations
* it was impossible to catch a `failed` proxy, and fall back to local
  authentication
* the server could not support multiple clients with different shared
  secrets behind one NAT gateway
* the DHCP and VMPS was implemented by making them pretend to be RADIUS,
  which limited their functionality
* the server did not support TACACS+
* connections to databases were `synchronous`. If a database blocked,
  it could eventually lock up the server

All of these limitations and more have been removed. The downside of
these changes is that the some of the configuration has been changed.

Administrators who have version 3 and wish to upgrade to version 4
should read the xref:installation:upgrade.adoc[upgrading] documentation.
That documentation explains the differences between the two versions, and
how an existing configuration can be reproduced in the latest
release. We do _not_ recommend using version 3 configuration files
with version 4. The configuration files are _not_ compatible across a
major version upgrade.

== Getting Started with FreeRADIUS

FreeRADIUS can be installed using the pre-built packages available
from https://packages.networkradius.com[Network RADIUS,
window="_blank"]. That page contains packages for all common OS
distributions.  New packages are available as soon as a new version
has been released.  Packages for older releases are also available for
historical purposes.

FreeRADIUS can also be installed from the source code.  Please see the
xref:installation:index.adoc[installation guide] for instructions.

WARNING: Many Operating System distributions ship versions of FreeRADIUS
which are years out of date. Those versions may contain bugs which have
been fixed in newer releases. We recommend using the
https://packages.networkradius.com[Network RADIUS, window="_blank"] packages where
possible.

Administrators who are new to FreeRADIUS should read the
xref:concepts:index.adoc[concepts section] as it describes the concepts behind
FreeRADIUS. It is vital for newcomers to understand these concepts, as the rest
of the documentation assumes familiarity with them.

A detailed xref:reference:unlang/index.adoc[unlang] reference guide is also available.
This section describes the syntax and functionality of the keywords,
data types, etc. used in the `unlang` processing language.

All of the xref:raddb:index.adoc[configuration files] are available in
hypertext format. It can often be easier to read the configuration files
in a nicely formatted version, instead of as a fixed-width font in a
text editor.

For specific problem solving, we recommend the xref:howto:index.adoc[how-to]
guides. These guides give instructions for reaching high-level goals, or for
configuring and testing individual
xref:howto:modules/configuring_modules.adoc[modules].

There is also xref:developers:index.adoc[developer documentation]. This section
documents the APIs for developers. Most people can ignore it.

== Debugging

If you have ANY problems, concerns, or surprises when running the
server, the the server should be run in debugging mode as root, from the
command line:

```
# radiusd -X
```

It will produce a large number of messages. The answers to many
questions, and the solution to many problems, can usually be found in
these messages. When run in a terminal window, error messages will be
shown in red text, and warning messages will be shown in yellow text.

For other use-cases, please look for `ERROR` or `WARNING` in the
debug output. In many cases, those messages describe exactly what is
going wrong, and how to fix it.

For further details, about the debug output see the
https://wiki.freeradius.org/radiusd-X[radiusd-X, window="_blank"] page on the
https://wiki.freeradius.org[wiki, window="_blank"].

== Getting Help

We also recommend joining the
https://lists.freeradius.org/mailman/listinfo/freeradius-users[mailing
list] in order to ask questions and receive answers. The developers are
not on Stack Overflow, IRC, or other web sites. While the FreeRADIUS
source is available on
https://github.com/FreeRADIUS/freeradius-server/[GitHub, window="_blank"], questions
posted there will not be answered.

Before posting to the list, please read the
https://wiki.freeradius.org/list-help[list help, window="_blank"] page. That page explains
how to run the server in debugging mode; how to understand the debug
output; and what information to post to the list.

Commercial support for FreeRADIUS is available from
https://networkradius.com/freeradius-support/[Network RADIUS, window="_blank"].
