= Introduction

This is the documentation for FreeRADIUS, version 3. 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 easy 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
`Howto` guides available.

include::ROOT:partial$externaldoc.adoc[]

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

* xref:installation:index.adoc[Install and Upgrade] Guides.
* xref:concepts:index.adoc[Concepts] provides an high level explanation for newcomers .
* The syntax of the xref:unlang:index.adoc[Unlang] Policy Language.
* The https://github.com/FreeRADIUS/freeradius-server/tree/v3.2.x/raddb[configuration files] located in `/etc/raddb/`, or `/etc/freeradius/`.
* Various xref:howto:index.adoc[Howto Guides] gives step-by-step instructions on how to complete tasks.
* xref:developers:index.adoc[Developers] documentation outlines coding standards, raising defects, and using GitHub.

This organization means that for example, the `ldap` module has
documention 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 `Howto` 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.

== Changes From Earlier Versions

Administrators who have version 2 and wish to upgrade to version 3
should read the xref:installation:upgrade.adoc[Upgrade to v3] 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 2 configuration files
with version 3. 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.inkbridgenetworks.com/[InkBridge Networks]. 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.inkbridgenetworks.com/[InkBridge Networks] packages where possible.
====

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

A detailed xref: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 https://github.com/FreeRADIUS/freeradius-server/tree/v3.2.x/raddb[configuration files] are available in GitHub.

For specific problem solving, we recommend the xref:howto:index.adoc[Howto]
guides. These guides give instructions for reaching high-level goals, or
for configuring and testing individual https://github.com/FreeRADIUS/freeradius-server/tree/v3.2.x/doc/modules[modules].

There is also xref:developers:index.adoc[Developers] documentation. This section
documents the APIs for developers. Most people can bypass this section.

== 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
refer to the https://www.freeradius.org/documentation/freeradius-server/3.2.8/radiusd_x.html[debug output] page on the
http://www.freeradius.org[freeradius org] website.

== Getting Help

We also recommend joining the
http://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://www.freeradius.org/documentation/freeradius-server/3.2.8/radiusd_x.html[debugging] 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://packages.inkbridgenetworks.com/[InkBridge Networks].
