== Building from Source

We recommend xref:packages.adoc[installing from packages] if
possible. Full instructions on building and installing from source
code follow.

The mandatory xref:installation:dependencies.adoc[dependencies]
must be installed before FreeRADIUS can be built. These dependencies
are `libtalloc` and `libkqueue`, which FreeRADIUS uses for memory
management, and platform-independent event handling.

Per-module dependencies that enable support for external services
such as LDAP, SQL, etc, are optional. They must be installed for
any modules that are to be used. The FreeRADIUS `./configure` step
will automatically detect if each module has its dependencies met
and automatically enable support for them. If the features you
require are not enabled you should inspect the configure script
output to figure out which additional development libraries need
to be installed.

The FreeRADIUS source may be obtained from a number of locations:

* Download the latest version of the FreeRADIUS source from
  https://www.freeradius.org/releases/[the FreeRADIUS web site]; or
* download directly from the
  ftp://ftp.freeradius.org/pub/freeradius/[FreeRADIUS FTP site]; or
* download from
  https://github.com/FreeRADIUS/freeradius-server/[GitHub].

The file will be named something like: `freeradius-server-4.0.0.tar.gz`.
Later version will be `4.0.1`, or `4.1.0`, etc. PGP signatures are
also provided for official releases from the FTP site; these are
named e.g. `freeradius-server-4.0.0.tar.gz.sig`.

Un-tar the file, and change to the FreeRADIUS directory (where
`VERSION` below is the version of the server that you have
downloaded).

[source,shell]
----
tar -zxf freeradius-server-VERSION.tar.gz
cd freeradius-server-VERSION
----

Take the following steps to build and install the server from source:

[source,shell]
----
./configure
make
sudo make install
----

=== Custom build

FreeRADIUS has GNU autoconf support. This means you have to run
`./configure`, and then run `make`. To see which configuration
options are supported, run `./configure --help`, and read its output.

The `make install` stage will install the binaries, the "man" pages,
and _may_ install the configuration files. If you have not installed a
RADIUS server before, then the configuration files for FreeRADIUS will
be installed.

If you already have a RADIUS server installed, then *FreeRADIUS
WILL NOT over-write your current configuration.*

The `make install` process will warn you about the files it could not
install.

If you see a warning message about files that could not be
installed, then you *must* ensure that the new server is using the
new configuration files and not the old configuration files, as
this may cause undesired behavior and failure to operate correctly.

The initial output from running in debugging mode (`radiusd -X`)
will tell you which configuration files are being used. See
xref:installation:upgrade.adoc[Upgrading] for information about
upgrading from older versions. There _may_ be changes in the
dictionary files which are required for a new version of the
software. These files will not be installed over your current
configuration, so you *must* verify and install any problem files by
hand, for example using `diff(1)` to check for changes.

When installing from source, it is _extremely_ helpful to read the
output of `./configure`, `make`, and `make install`. If a
particular module you expected to be installed was not installed,
then the output will tell you why that module was not installed.
The most likely reason is that required libraries (including their
development header files) are not available.

Please do _not_ post questions to the FreeRADIUS users list
without first carefully reading the output of this process as it
often contains the information needed to resolve a problem.

== Upgrading To A New Minor Release

The installation process will not over-write your existing configuration
files. It will, however, warn you about the files it did not install.
These will require manual integration with the existing files.

It is generally not possible to reuse configurations between different
major versions of the server. (For example - version 2 to version 3, or
version 3 to version 4.

For details on what has changed between the version, see the
xref:installation:upgrade.adoc[upgrade] guide.

We _strongly_ recommend that new major versions be installed in a
different location than any existing installations. Any local policies
can then be migrated gradually to the configuration format of the new
major version. The number of differences in the new configuration mean
that is is both simpler and safer to migrate your configurations rather
than to try and just get the old configuration to work.

== Running the server

If the server builds and installs, but doesn’t run correctly, then
you should first use debugging mode (`radiusd -X`) to figure out
the problem.

This is your best hope for understanding the problem. Read _all_
of the messages which are printed to the screen, the answer to
your problem will often be in a warning or error message.

We really cannot emphasize that last sentence enough. Configuring
a RADIUS server for complex local authentication isn’t a trivial
task. Your _best_ and _only_ method for debugging it is to read
the debug messages, where the server will tell you exactly what
it’s doing, and why. You should then compare its behaviour to what
you intended, and edit the configuration files as appropriate.

If you don’t use debugging mode, and ask questions on the mailing
list, then the responses will all tell you to use debugging mode.
The server prints out a lot of information in this mode, including
suggestions for fixes to common problems. Look especially for
`WARNING` and `ERROR` messages in the output, and read the related
messages.

Since the main developers of FreeRADIUS use debugging mode to
track down their configuration problems with the server, it’s a
good idea for you to use it, too. If you don’t, there is little
hope for you to solve any configuration problem related to the
server.

To start the server in debugging mode, do:

[source,shell]
----
radiusd -X
----

You should see a lot of text printed on the screen as it starts up. If
you don’t, or if you see error messages, please read the FAQ:

https://wiki.freeradius.org/guide/FAQ

If the server says `Ready to process requests.`, then it is running
properly. From another shell (or another window), type

[source,shell]
----
radtest test test localhost 0 testing123
----

You should see the server print out more messages as it receives the
request, and responds to it. The `radtest` program should receive the
response within a few seconds. It doesn’t matter if the authentication
request is accepted or rejected, what matters is that the server
received the request, and responded to it.

You can now edit the configuration files for your local system. You will
usually want to start with `sites-enabled/default` for main
configurations. To set which NASes (clients) can communicate with this
server, edit `raddb/clients.conf`. Please read the configuration files
carefully, as many configuration options are only documented in comments
in the file.

Note that is is _highly_ recommended that you use some sort of version
control system to manage your configuration, such as git or Subversion.
You should then make small changes to the configuration, checking in and
testing as you go. When a config change causes the server to stop
working, you will be able to easily step back and find out what update
broke the configuration.

It is also considered a best practice to maintain a staging or
development environment. This allows you to test and integrate your
changes without impacting your active production environment. You should
make the appropriate investment in order to properly support a critical
resource such as your authentication servers.

Configuring and running the server MAY be complicated. Many modules have
`man` pages. See `man rlm_pap`, or `man rlm_*` for information.
Please read the documentation in the doc/ directory. The comments in the
configuration files also contain a lot of documentation.

If you have any additional issues, the FAQ is also a good place to
start.

https://wiki.freeradius.org/guide/FAQ
