From af754e596a8dbb05ed8580c342e7fe02e08b28e0 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 13 Apr 2024 16:11:00 +0200 Subject: Adding upstream version 3.2.3+dfsg. Signed-off-by: Daniel Baumann --- doc/antora/modules/installation/pages/source.adoc | 199 ++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 doc/antora/modules/installation/pages/source.adoc (limited to 'doc/antora/modules/installation/pages/source.adoc') diff --git a/doc/antora/modules/installation/pages/source.adoc b/doc/antora/modules/installation/pages/source.adoc new file mode 100644 index 0000000..cf40a79 --- /dev/null +++ b/doc/antora/modules/installation/pages/source.adoc @@ -0,0 +1,199 @@ +== 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 wil be name something like: `freeradius-server-3.0.22.tar.gz`. +Later versions will be `3.0.23`, or `4.0.0`, etc. PGP signatures are +also provided for official releases from the FTP site; these are +named e.g. `freeradius-server-3.0.22.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 not possible to re-use configurations between different major +versions of the server. + +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 appropirate 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 -- cgit v1.2.3