From: nolade Date: Wed, 19 Mar 2025 22:33:16 +0000 (-0400) Subject: Add OS specific install/build instructions X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ab6ddb329eee00993921289a5c2e9ab79d4e7e33;p=thirdparty%2Ffreeradius-server.git Add OS specific install/build instructions --- diff --git a/doc/antora/modules/howto/nav.adoc b/doc/antora/modules/howto/nav.adoc index bfd2021cce3..4791a12e996 100644 --- a/doc/antora/modules/howto/nav.adoc +++ b/doc/antora/modules/howto/nav.adoc @@ -1,17 +1,16 @@ * xref:index.adoc[Howto Guides] -** xref:howto:installation/index.adoc[Installing and upgrading] -*** xref:howto:installation/packages.adoc[Install from packages] +** xref:howto:installation/index.adoc[Installing and Upgrading] *** xref:howto:installation/dependencies.adoc[Dependencies] -*** xref:howto:installation/source.adoc[Build from source] -*** xref:howto:installation/upgrade.adoc[Upgrading from v3 to v4] -*** xref:howto:installation/attribute_names.adoc[Attribute name changes from v3 to v4] -*** Building Packages +*** xref:howto:installation/packages.adoc[Install from Packages] +*** xref:howto:installation/source.adoc[Build from Source] **** xref:howto:installation/debian.adoc[Debian and Ubuntu] -**** xref:howto:installation/redhat.adoc[RedHat and CentOS] +**** xref:howto:installation/redhat.adoc[RedHat and Rocky] +**** xref:howto:installation/osx.adoc[OSX] +*** xref:howto:installation/upgrade.adoc[Upgrading from v3 to v4] +**** xref:howto:installation/attribute_names.adoc[Attribute Name Changes from v3 to v4] -** Modules -*** xref:modules/configuring_modules.adoc[Configuring Modules] +** xref:modules/configuring_modules.adoc[Configuring Modules] *** xref:modules/chap/index.adoc[CHAP] *** xref:modules/eap/index.adoc[EAP] *** xref:modules/expiration/index.adoc[Expiration] diff --git a/doc/antora/modules/howto/pages/index.adoc b/doc/antora/modules/howto/pages/index.adoc index 78d939ce0ab..22928913c19 100644 --- a/doc/antora/modules/howto/pages/index.adoc +++ b/doc/antora/modules/howto/pages/index.adoc @@ -1,16 +1,49 @@ = Howto Guides -The documents in this section describe how to perform various common tasks with -FreeRADIUS. They also provide worked examples on using the various modules in -common deployment scenarios. +This section describe how to perform various common tasks with +FreeRADIUS. Each sub-section provides worked examples such as using the modules in common deployment scenarios or building packages. + +The section is broken down into the following top-level areas: + +xref:howto:installation/index.adoc[Installing and Upgrading] contains instructions for building and installing freeRADIUS from packages and source. + +xref:modules/configuring_modules.adoc[Configuring Modules] provides worked examples on using the various modules in common deployment scenarios. + +xref:protocols/index.adoc[Protocols] +*** xref:protocols/dhcp/index.adoc[DHCP] +**** xref:protocols/dhcp/prepare.adoc[Preparation] +**** xref:protocols/dhcp/enable.adoc[Enabling the DHCP service] +**** xref:protocols/dhcp/test.adoc[Testing the DHCP service] +**** xref:protocols/dhcp/policy.adoc[Defining the DHCP policy] +***** xref:protocols/dhcp/policy_ippool_creation.adoc[IP pool creation] +***** xref:protocols/dhcp/policy_common_options.adoc[Common options] +***** xref:protocols/dhcp/policy_network_options.adoc[Network options and IP pool selection] +***** xref:protocols/dhcp/policy_subnet_options.adoc[Subnet options] +***** xref:protocols/dhcp/policy_device_options.adoc[Device, class and group options] +***** xref:protocols/dhcp/policy_ippool_access.adoc[IP pool access restriction] + +** Security Certificates +*** xref:os/letsencrypt.adoc[Using LetsEncrypt certificates] + +** Vendors +*** xref:vendors/ascend.adoc[Ascend] +*** xref:vendors/bay.adoc[Bay] +*** xref:vendors/cisco.adoc[Cisco] +*** xref:vendors/proxim.adoc[ProxIM] + +** Optimization +*** xref:monitoring/index.adoc[Monitoring] +**** xref:monitoring/statistics.adoc[Server Statistics] +*** xref:tuning/performance-testing.adoc[Performance Testing] +*** xref:tuning/tuning_guide.adoc[Tuning Guide] If you have a topic you'd like to see included in the list of howtos, contact the developers on the -link:https://lists.freeradius.org/mailman/listinfo/freeradius-users[User's +https://lists.freeradius.org/mailman/listinfo/freeradius-users[User's mailing list]. Some of the documents here started life as pages on -link:https://wiki.freeradius.org[wiki.freeradius.org]. If you've just been +https://wiki.freeradius.org[wiki.freeradius.org]. If you've just been through a particularly arduous service configuration and deployment, and would like to help your fellow users, then please create a new how to on the wiki. If it's popular enough, we'll include it in the official documentation for the diff --git a/doc/antora/modules/howto/pages/installation/debian.adoc b/doc/antora/modules/howto/pages/installation/debian.adoc index 765cce19c9d..ac0be7da38f 100644 --- a/doc/antora/modules/howto/pages/installation/debian.adoc +++ b/doc/antora/modules/howto/pages/installation/debian.adoc @@ -1,20 +1,19 @@ -= Installing FreeRadius on Ubuntu += Build and Install FreeRadius on Ubuntu -* Installing from repositories -* Installing from source +* Install from repositories +* Build and Install from Source -== Installing from repositories +== Installing from repositories -This is usually the easiest solution, but at the moment of writing (2016-06) both Ubuntu 16.04 and Ubuntu 14.04.4 contain packages which are EOL and which are not the latest in their own main version. So building from source is recommended as it will contain the latest version, which probably got most of the bugs sorted. +This is usually the easiest solution, as long as the system packages are the latest in their own main version, or can be updated before building. Building from source is recommended as it will contain the latest version, that contains the most recent bug fixes. -To Install : +To begin your install, enter the command below to get the latest info about packages from Ubuntu: -Get the latest info about packages from Ubuntu : ---- -sudo apt-get update +sudo apt-get update ---- -Then make sure the system is fully upgraded before installing freeradius : +Then make sure the system is fully upgraded before installing freeradius: ---- sudo apt-get upgrade ---- @@ -24,19 +23,19 @@ or sudo apt-get dist-upgrade ---- -After that has been done we can use _apt_ to install freeradius : +After that has been done we can use _apt_ to install freeradius: ---- -sudo apt-get install freeradius +sudo apt-get install freeradius ---- This will install the common,utils, ssl-cert, libdbi-perl, and libfreeradius2 packages. As you probably going to connect to a database or use perl, you should probably also install (some of) the suggested packages. Such as: freeradius-ldap, freeradius-postgresql and freeradius-mysql. ---- -sudo apt-get install freeradius-ldap +sudo apt-get install freeradius-ldap ---- The 'apt install freeradius' command will list all the suggested packages. -If all went well freeradius should now be installed and started. You can start or stop the server with : +If all went well freeradius should now be installed and started. You can start or stop the server with: ---- sudo service freeradius stop ---- @@ -51,24 +50,13 @@ Suggested is to stop the service and until all is working use freeradius in debu sudo freeradius -X ---- -Right now your config files are in : ----- -cd /etc/freeradius ----- -Documentation and files for creation of certificates are in : ----- -cd /usr/share/doc/freeradius ----- - -== Installing from source +== Installing from Source -Installing from source can be daunting for people who never did it but as long as you read the output of the building process, it should tell you what went wrong or what is missing. +Installing from source can be daunting for first time users, but as long as you read the output of the building process, it tell you what went wrong or what is missing. Your first step is to download the source files which can be found on one of the following sites: - 1. http://freeradius.org/download.html[Freeradius.org] - Choose the latest release by selecting the relevant button. - - 2. https://github.com/FreeRADIUS/freeradius-server[Github] - Select the branch you wish to install and press clone or download. +include::partial$get_the_source.adoc[] Make sure unzip or any other utility that can extract the zip is installed. If not : ---- @@ -114,7 +102,7 @@ In the file _debian/rules_ we might need to make some changes depending on other pico debian/rules ---- -And just before +And just before ---- --without-rlm_eap_ikev2 \ ---- @@ -134,7 +122,7 @@ sudo apt-get install libcurl4-openssl-dev libcap-dev libgdbm-dev libiodbc2-dev l After that we try again to build. ---- -fakeroot dpkg-buildpackage -b -uc +fakeroot dpkg-buildpackage -b -uc ---- If it errors out after it has already started building the deb files, you are sometimes better off starting anew. If that happens : @@ -158,28 +146,19 @@ sudo dpkg -i *freeradius*_W.X.Y*_*.deb The install might show errors. Read the error !! Ask questions on freeradius list if you cannot figure it out. v2 will fail install often on open_ssl issues. Quick thing to change to prevent just that error is to edit a config file so freeradius will not complain about ssl that might be vulnerable. ( /etc/freeradius/eap.conf (v2) or /etc/freeradius/modules-enabled/eap ) - - - - - - - - - == Building on Debian or Ubuntu Building Debian packages (including Ubuntu) of FreeRADIUS from source is kept as simple as possible. == Building the stable release (v3.0) -Building packages should be very simple. First obtain a copy of the source and unpack it. Second, build the packages. +Building packages is very simple. First obtain a copy of the source and unpack it. Second, build the packages. == Getting the source -include:Getting-the-Source +include::partial$get_the-source -== Installing build dependencies +== Build dependencies Use the following to make sure that all build dependencies are all installed: @@ -213,31 +192,15 @@ make sudo make install ---- - == Building development versions (v4.0) Note that version 4 is for developers only. **Do not use these versions unless you know what you are doing.** == Upgrading GCC -Older versions of Debian and Ubuntu use GCC < 4.8, which lacks support for the C11 features needed to build FreeRADIUS >= v4.0.x. - -In order to switch to GCC 4.9 ----- -sudo apt-get install software-properties-common python-software-properties -sudo add-apt-repository ppa:ubuntu-toolchain-r/test -sudo apt-get update -sudo apt-get install g++-4.9 - -# Then select GCC 4.9 -sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.8 100 --slave /usr/bin/g++ g++ /usr/bin/g++-4.8 -sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.9 50 --slave /usr/bin/g++ g++ /usr/bin/g++-4.9 -sudo update-alternatives --config gcc - -# Choose option 3 from the dialogue ----- +include::partial$upgrade_gcc.adoc[] -== Installing hard dependencies +== Hard Dependencies ---- sudo apt-get install libssl-dev libtalloc-dev libkqueue-dev diff --git a/doc/antora/modules/howto/pages/installation/dependencies.adoc b/doc/antora/modules/howto/pages/installation/dependencies.adoc index 6623dafefd4..f4e57c817fb 100644 --- a/doc/antora/modules/howto/pages/installation/dependencies.adoc +++ b/doc/antora/modules/howto/pages/installation/dependencies.adoc @@ -1,4 +1,4 @@ -= FreeRADIUS Dependencies += Dependencies Some external dependencies must be installed before building or running FreeRADIUS. The core depends on two libraries: @@ -18,44 +18,56 @@ particular module to be skipped. === libtalloc -Talloc is a memory allocation library available at -https://talloc.samba.org/talloc/doc/html/index.html +Talloc is a memory allocation library available from +https://talloc.samba.org/talloc/doc/html/index.html[Samba] -*OSX* -`# brew install talloc` - -*Debian, Ubuntu and `dpkg`-based systems* +==== Debian, Ubuntu and `dpkg`-based systems `# apt-get install libtalloc-dev` -*RedHat or CentOS* +==== RHEL, Rocky, or Alma ``` # subscription-manager repos --enable rhel-7-server-optional-rpms # dnf install libtalloc-dev ``` +==== OSX + +`# brew install talloc` + === kqueue Kqueue is an event / timer API originally written for BSD systems. It is _much_ simpler to use than third-party event libraries. A library, `libkqueue`, is available for Linux systems. -*OSX* - -_kqueue is already available, there is nothing to install._ - -*Debian, Ubuntu and `dpkg`-based systems* +==== Debian, Ubuntu and `dpkg`-based systems `# apt-get install libkqueue-dev` -*RedHat or CentOS* +==== RHEL, Rocky, or Alma ``` # subscription-manager repos --enable rhel-7-server-optional-rpms # dnf install libkqueue-dev ``` +==== OSX + +Kqueue is already available, there is nothing to install. + +== Compilers + +=== GNU Compiler Collection (GCC) + +FreeRADIUS v4 requires at least GCC 4.9 to support the C11 features introduced in version 3. + +Update your version to GCC 4.9 with these commands: + +include::partial$upgrade_gcc.adoc[] + + // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/howto/pages/installation/index.adoc b/doc/antora/modules/howto/pages/installation/index.adoc index e9242c2a243..c32e9a668a5 100644 --- a/doc/antora/modules/howto/pages/installation/index.adoc +++ b/doc/antora/modules/howto/pages/installation/index.adoc @@ -1,13 +1,15 @@ -= Installation += Installing and Upgrading -FreeRADIUS is available from multiple sources: +FreeRADIUS is available from many locations. Select one of the options below to begin installing your server: -* Official xref:howto:installation/packages.adoc[Network RADIUS packages] +* xref:howto:installation/packages.adoc[Inbridge Networks packages] * xref:howto:installation/source.adoc[Source code] * Many Operating System distributions -We highly recommend using the official packages from Network -RADIUS, where available. +Get the FreeRADIUS source from one of the following locations: +include::partial$get_the_source.adoc[] + +We recommend using the official https://packages.inkbridgenetworks.com/[InkBridge Networks packages] where available. The documents in this section cover details of the above installation methods, as well as instructions on building @@ -15,38 +17,38 @@ packages locally. == Getting Started -This page describes how to perform the initial configuration of +This page describes how to perform the first install of FreeRADIUS. It assumes a basic knowledge of Unix system administration. No RADIUS knowledge is required. -## Installing the Server +## Install the Server -Where possible, while learning the basics, it is suggested that +Where possible, while learning the basics, it's recommended that beginners use the packaging system that is used by your operating system. The version that is supplied by your OS might be out of -date, but it is likely to work "out of the box". The only +date, but ususally works "out of the box". The only exception to this is if your operating system supplies an older major version, as you will then be learning an obsolete -configuration. +configuration. See xref:howto:installation/packages.adoc[install from packages] for a more current version. Once you have learnt how FreeRADIUS works, it is then highly recommended to move to the latest released stable version before moving into production. -If you need to install it yourself, the Wiki -building and installing(http://wiki.freeradius.org/building/Home) -page contains detailed instructions for a number of platforms. +If you need to install it yourself, the [building from source] page contains detailed instructions for a number of platforms. Otherwise, we assume that you can install the server via something like `yum install freeradius`, or `apt-get install freeradius`. -Note that in Debian-based systems, the server daemon is called -`freeradius` instead of `radiusd` The configuration files are also -located in `/etc/freeradius/` instead of `/etc/raddb/`. We use -`radiusd` and `/etc/raddb/` in this guide, and trust that Debian -administrators can translate to their system. +[NOTE] +==== +Debian-based systems refer to the server daemon as +`freeradius` instead of `radiusd`. The debian configuration files are +located in `/etc/freeradius/` instead of `/etc/raddb/`. The terms +`radiusd` and `/etc/raddb/` are used in this guide for simplicity. +==== -## Some background +### Best Practice Once the server has been installed, the first thing to do is *change as little as possible*. The default configuration is designed to work @@ -64,169 +66,56 @@ Many common configurations are documented as suggestions or examples in the configuration files. Many common problems are discussed in the configuration files, along with suggested solutions. -We recommend reading the configuration files, in large part because most -of the configuration items are documented *only* in the comments in the -configuration files. - We recommend *reading the debug output of the server*. While it contains a lot of text, it describes exactly what is happening within the server and usually contains error messages which describe what went wrong, and how to fix it. -## Starting the server - -When the server has been installed on a new machine, the first step is -to start it in debugging mode, as user `root`: +## Start the server - # radiusd -X - -This step demonstrates that the server is installed and configured -properly. If the output says `Ready to process requests`, then all is -well. +include::partial$start_server.adoc[] Otherwise, typical errors include `Address already in use`, which means that there is another RADIUS server already running. You will need to find that one and stop it before running the server in debugging mode. -The output from `radiusd -X` can sometimes be confusing at first, -so there is a page with an [explanation of the debug output](/radiusd-X). +The output from `radiusd -X` is very verbose, see the xref:ROOT:debugging/radiusd_X.adoc[debugging page] for an +explanation of the debug output. ## Initial Tests -Testing authentication is simple. Edit the `users` file (in v3 this has -been moved to `raddb/mods-config/files/authorize`), and add the -following line of text at the top of the file, before anything else: - - testing Cleartext-Password := "password" - -Start the server in debugging mode (`radiusd -X`), and run `radtest` -from another terminal window: - - $ radtest testing password 127.0.0.1 0 testing123 - -You *should* see the server respond with an `Access-Accept`. If it -doesn't, the debug log will show why. In version 2, you can paste the -output into the [debug form](http://networkradius.com/freeradius-debugging/), -and a colorized HTML version will be produced. In version 3, the -output will already be colorized in the terminal. Look for red or -yellow text, and read the relevant messages. They should describe -exactly what went wrong, and how to fix the problem. - -If you do see an `Access-Accept`, then *congratulations*, the following -authentication methods now work for the `testing` user: - - PAP, CHAP, MS-CHAPv1, MS-CHAPv2, PEAP, EAP-TTLS, EAP-GTC, EAP-MD5. +Once your server is up and running, test basic authentication. +include::partial$initial_tests.adoc[] -The next step is to add more users, and to configure databases. Those -steps are outside of the scope of this short web page, but the general -method to use is important, and is outlined in the next section. -## Adding a client +## Add a client -When we discuss clients, we mean clients of the RADIUS server, e.g. -wireless access point, network switch or other form of NAS. NOT the -network clients - such as laptops, tablets etc - they do not talk -directly to the RADIUS server. - -The above test runs `radtest` from localhost. It is useful to add a new -client, which can be done by editing the `clients.conf` file. Add the -following content: - - client new { - ipaddr = 192.0.2.1 - secret = testing123 - } - -You should change the IP address `192.0.2.1` to be the address of the -client which will be sending `Access-Request` packets. - -The client should also be configured to talk to the RADIUS server, by -using the IP address of the machine running the RADIUS server. The -client must use the same secret as configured above in the `client` -section. - -Then restart the server in debugging mode, and run a simple test using -the `testing` user. You should see an `Access-Accept` in the server -output +After a successful authentication, add a client, and verify that packets are successfully sent and received. +include::partial$add_client.adoc[] *** -*The following steps outline the best known method for configuring the -server. Following them lets you create complex configurations with a -minimum of effort. Failure to follow them leads to days of frustration -and wasted effort.* +## Configure the Server -*** - -## Configuring the Server - -Changing the server configuration should be done via the following -steps: - -1. Start with a "known working" configuration, such as supplied by the - default installation. -2. Make one *small* change to the configuration files. -3. Start the server in debugging mode (`radiusd -X`). -4. Verify that the results are what you expect - - The debug output shows any configuration changes you have made. - - Databases (if used) are connected and operating. - - Test packets are accepted by the server. - - The debug output shows that the packets are being processed as - you expect. - - The response packets are contain the attributes you expect - to see. - -5. If everything is OK, save a copy of the configuration, go back to - step (2), and make another change. -6. If anything goes wrong, - - double-check the configuration; - - read the *entire* debug output, looking for words like `error` - or `warning`. These messages usually contain descriptions of - what went wrong, and suggestions for how it can be fixed. - Also see [an explanation of the debug output](/radiusd-X) and - the [debug form](http://networkradius.com/freeradius-debugging/); - - try replacing your configuration with a saved copy of a "known - working" configuration, and start again. This process can clean - up errors caused by temporary edits, or edits that you have - forgotten about; - - ask for help on the - [freeradius-users](http://freeradius.org/support/) mailing - list. Include a description of what you are trying to do, and - the *entire debugging output*, especially output showing the - server receiving and processing test packets. You may want to - scrub "secret" information from the output before posting it - (shared secrets, passwords, etc). - -== Warning! + include::partial$config_server.adoc[] +[WARNING] +==== *These instructions cover installing FreeRADIUS 4.x, which is still in heavy development. Other than exceptional circumstances, you should use https://freeradius.org/releases/[version 3].* -FreeRADIUS 4 is actively used in multiple high profile client -deployments (who have -https://networkradius.com/freeradius-support/[purchased a support -contract] from Network RADIUS). It, however, otherwise demands a -user that seeks danger and enjoys deploying a highly volatile -evolving codebase in environments where traditionally stability is -sought. If this describes you, then version 4 is for you! (But -don't come complaining if it breaks.) - -Hopefully it is clear, *we recommend 99.9%+ of users use -https://freeradius.org/releases/[FreeRADIUS 3.2.x]* and the -https://packages.networkradius.com/[pre-built packages] -available from https://networkradius.com/[Network RADIUS]. - -## Other Resources - -A number of guides are available from Network -RADIUS. In particular, we recommend -the Technical -Guide(http://networkradius.com/doc/FreeRADIUS%20Technical%20Guide.pdf), -which should be read by every new RADIUS administrator. It explains -RADIUS concepts, and covers how to perform introductory administation -and maintenance. More in-depth guides are available on the same page. +FreeRADIUS 4 is actively used in many high profile client +deployments who have +https://www.inkbridgenetworks.com/support/freeradius-support[purchased a support +contract] from InkBridge Networks. + +*We recommend to 99.9%+ of our customers to use the latest release +https://freeradius.org/releases/[FreeRADIUS 3.2.x]* and the InkBridge Networks +https://packages.inkbridgenetworks.com/[pre-built packages] +==== + // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/howto/pages/installation/osx.adoc b/doc/antora/modules/howto/pages/installation/osx.adoc index 4cd16961cd8..6a155bf3b89 100644 --- a/doc/antora/modules/howto/pages/installation/osx.adoc +++ b/doc/antora/modules/howto/pages/installation/osx.adoc @@ -1,24 +1,62 @@ -# Building on macOS += Building on OSX -## Hard dependencies +FreeRADIUS can be installed on OSX platforms, however some environment setup is required. Additional dev tools are also configured before the server installation. -If you don't have homebrew package manager installed, [do it now](http://brew.sh)... it'll make your life on macOS far simpler. +== Hard Dependencies + +=== Homebrew + +Install the https://brew.sh[Homebrew] package manager to streamline the installation process on OSX platforms. It'll make your life on macOS far simpler. Once you've installed Homebrew, you can install more from the command line: ```bash brew install talloc ``` +=== Install Script -## Getting the source +Run the `install_deps.sh` script to install the build dependencies. It's recommended to create a copy of this file and edit locally. You can remove apps, libs, or utilites that you don't need such as postgresql. Ensure that you use the updated file when running the script. -include:Getting-the-Source +=== Xcode Tools -## Building from source +Install Xcode from the https://www.apple.com/ca/app-store/[app store]. This tool is used to help develop, test, and manage your applications. -```bash -# Use ./configure --enable-developer if you're debugging issues, or using unstable code. +Install the xcode command-line tools. + +``` +xcode-select --install +``` + +Update the `~/.zshrc` file. + +``` +cat scripts/osx/bash_profile >> ~/.zshrc +``` +[NOTE] +==== +If using a different shell, ensure you copy the environment paramenters to your current shell. +==== + +=== Getting the Source + +Get the FreeRADIUS source from one of these methods: +include::partial$get_the_source.adoc[] + +=== Build= from Source and Install + +To begin the install process, enter the following commands: + +``` +cd freeradius-server ./configure make -sudo make install +``` + +=== Running FreeRADIUS in the background all of the time. + +The information below is for future reference. + +``` +cp ./org.freeradius.radius.plist /Library/LaunchDaemons +launchctl load -w Library/LaunchDaemons/org.freeradius.radiusd.plist ``` // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. diff --git a/doc/antora/modules/howto/pages/installation/packages.adoc b/doc/antora/modules/howto/pages/installation/packages.adoc index 72dc54bff56..8ee3729a1d6 100644 --- a/doc/antora/modules/howto/pages/installation/packages.adoc +++ b/doc/antora/modules/howto/pages/installation/packages.adoc @@ -1,16 +1,22 @@ == Install from packages -Network RADIUS provide pre-built binary packages of FreeRADIUS for -common Linux distributions. This is the recommended installation -method when packages are available for your system. +https://www.inkbridgenetworks.com/[InkBridge Networks] provides pre-built binary packages of FreeRADIUS for common Linux distributions. This is the recommended installation method when packages are available for your system. -The official http://packages.networkradius.com[Network RADIUS -packages] page contains recent FreeRADIUS packages and +The official https://packages.inkbridgenetworks.com/[InkBridge Networks +packages] page contains the most recent FreeRADIUS packages and installation instructions. +The current packages available include: + +* https://packages.inkbridgenetworks.com/#fr32-ubuntu[Ubuntu] +* https://packages.inkbridgenetworks.com/#fr32-debian[Debian] +* https://packages.inkbridgenetworks.com/#fr32-rocky[Rocky] +* https://packages.inkbridgenetworks.com/#fr32-centos[Centos] +* https://packages.inkbridgenetworks.com/#fr32-rhel[RHEL] + === Distribution-supplied packages -While many Operating System distributions ship FreeRADIUS +While many operating system distributions ship FreeRADIUS packages, the versions they include are often years out of date. As well as missing out on the latest bug fixes and features, this also means that it is very hard to know if an issue encountered is diff --git a/doc/antora/modules/howto/pages/installation/redhat.adoc b/doc/antora/modules/howto/pages/installation/redhat.adoc index 3082576e340..2026727241e 100644 --- a/doc/antora/modules/howto/pages/installation/redhat.adoc +++ b/doc/antora/modules/howto/pages/installation/redhat.adoc @@ -1,41 +1,43 @@ -= Building on RHEL7 or Centos7 += Building on RHEL7 -There are only a few requirements to building on RHEL, or CentoS +There are minimal requirements to building on RHEL, including Rocky or Alma versions. -== Hard dependencies +[NOTE] +==== +Centos Stream is now a rolling release, feeder distribution for RHEL and no longer supported. +==== + +== Hard Dependencies + +=== libtalloc ---- yum -y install libtalloc-devel ---- -== Getting the source +=== libkqueue -include:/building/Getting-the-Source +> libkqueue required for >= v4.0.x, you can skip this step for v3.0.x and below. + +Unfortunately neither RHEL nor Centos provide an RPM for libkqueue. The instructions below will produce a libkqueue RPM, which can then be installed for building from source, or distributed with the FreeRADIUS RPMs when building packages. -== Building from source +Building the libkqueue RPM requires these packages: ---- -# Use ./configure --enable-developer if you're debugging issues, or using unstable code. -./configure -make -sudo make install +yum -y install cmake3 ---- -== Building Packages - -=== With Oracle support - -include:RPMs-with-Oracle-support +include::partial$libkqueue-rpm.adoc -== Upgrading GCC (>= v4.0.x and master branch only) +=== Upgrading GCC (>= v4.0.x and master branch only) > GCC upgrade only required for versions >= v4.0.x you can skip this step for v3.0.x and below. -RHE7 ships with GCC 4.8.5 but we require GCC >= 4.9.0 for FreeRADIUS >= v4.0.x. +RHE7 ships with GCC 4.8.5 but FreeRADIUS v4 requires GCC >= 4.9.0. -Fortunately, the ``devtoolset-3`` series of packages provides a later version of GCC. +The ``devtoolset-3`` series of packages provides a later version of GCC. -Follow the instructions here to enable the [devtoolset-3 repository](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-3/). + https://www.softwarecollections.org/en/scls/rhscl/devtoolset-3/[devtoolset-3 repository][Follow these instructions] to enable the toolset. To install: @@ -53,20 +55,25 @@ Or can set ``CC=/opt/rh/devtoolset-3/root/usr/bin/gcc`` in your environment, whi If you're building on older versions of RedHat then you'll need to compile GCC from source. +== Getting the source -=== libkqueue - -> libkqueue required for >= v4.0.x, you can skip this step for v3.0.x and below. +include::partial$get_the_source.adoc[] -Unfortunately neither RHEL nor Centos provide an RPM for libkqueue. The instructions below will produce a libkqueue RPM, which can then be installed for building from source, or distributed with the FreeRADIUS RPMs when building packages. +== Build from Source and Install -Building the libkqueue RPM will require these packages: +If you're using unstable code or encountering issues with the install, use `configure --enable-developer` option. ---- -yum -y install cmake3 +./configure +make +sudo make install ---- -include:libkqueue-rpm +== Building Packages + +=== With Oracle support + +include:RPMs-with-Oracle-support // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/howto/pages/installation/source.adoc b/doc/antora/modules/howto/pages/installation/source.adoc index bff097b2709..4911f1ebdc7 100644 --- a/doc/antora/modules/howto/pages/installation/source.adoc +++ b/doc/antora/modules/howto/pages/installation/source.adoc @@ -4,7 +4,7 @@ We recommend xref:howto:installation/packages.adoc[installing from packages] if possible. Full instructions on building and installing from source code follow. -The required xref:howto:installation/dependencies.adoc[dependencies] +The hard xref:howto: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. @@ -12,20 +12,14 @@ 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 +automatically detects if each module has its dependencies met +and automatically enable support for them. If the required features you +require are not enabled, 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]. +Get the FreeRADIUS source from one of the following sites: +include::partial$get_the_source.adoc[] 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 @@ -73,9 +67,9 @@ 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`) +The initial output from running in xref:ROOT:debugging/radiusd_X.adoc[debugging mode] will tell you which configuration files are being used. See - xref:howto:installation/upgrade.adoc[Upgrading] for information about + xref:howto: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 @@ -100,11 +94,10 @@ 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 +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:howto:installation/upgrade.adoc[upgrade] guide. +For details on what has changed between the version, see xref:howto:installation/upgrade.adoc[Upgrading from v3 to v4]. We _strongly_ recommend that new major versions be installed in a different location than any existing installations. Any local policies @@ -116,21 +109,20 @@ 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 +you should first use xref:ROOT:debugging/radiusd_X.adoc[debugging mode] 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 +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 +If you don’t use xref:ROOT:debugging/radiusd_X.adoc[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 @@ -151,9 +143,7 @@ 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 +you don’t, or if you see error messages, please read the xref:ROOT:faq.adoc[FAQ] and xref:ROOT:trouble-shooting/index.adoc[troubleshooting] sections. If the server says `Ready to process requests.`, then it is running properly. From another shell (or another window), type @@ -194,7 +184,7 @@ Configuring and running the server MAY be complicated. Many modules have 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, refer to the https://wiki.freeradius.org/guide/FAQ[FAQ] for more help. +If you have any additional issues, refer to the xref:ROOT:faq.adoc[FAQ] for more help. // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/howto/pages/installation/upgrade.adoc b/doc/antora/modules/howto/pages/installation/upgrade.adoc index a1b224090f8..b83a62aaac8 100644 --- a/doc/antora/modules/howto/pages/installation/upgrade.adoc +++ b/doc/antora/modules/howto/pages/installation/upgrade.adoc @@ -4,8 +4,11 @@ The configuration for v4 is _somewhat_ compatible with the v3 configuration. It should be possible to reuse most of a v3 reconfiguration with minor tweaks. -NOTE: This file describes the differences between v3 and v4. It does not +[NOTE] +==== +This file describes the differences between v3 and v4. It does not contain a step-by-step process for upgrading the server. +==== In general, we have the following changes: @@ -19,6 +22,12 @@ In general, we have the following changes: == Upgrading from older versions +=== Upgrading from v2 + +If you are upgrading from v2 you should read the v3 version of this +file. It describes changed from v2 to v3. This file describes only +the changes from v3 to v4. + === Upgrading from v3 When upgrading, please start with the default configuration of v4. Then, @@ -41,11 +50,6 @@ information. This change was necessary in order to support the new "grouped" attributes, which are required for DHCPv6 and other protocols. -=== Upgrading from v2 - -If you are upgrading from v2 you should read the v3 version of this -file. It describes changed from v2 to v3. This file describes only -the changes from v3 to v4. == Attribute Names @@ -296,13 +300,22 @@ network. The `send` sections send packets back to the network. The second name of the section is the _type_ of the packet that is being received or sent. -NOTE: For accounting, packets are also processed through an +[NOTE] +==== +For accounting, packets are also processed through an `accounting` section named after Acct-Status-Type. This process is similar to `authenticate` for `Access-Request` packets. The goal here is to allow a common pre-processing of accounting packets in the `recv Accounting-Request` packet, followed by type-specific processing in `accounting %{Acct-Status-Type}`. See sites-available/default for examples and more information. +==== + +=== Update Sections + +A major difference between v3 and v4 is that `update` sections are no +longer necessary. See the <> section below for full +details. == Proxying @@ -665,7 +678,7 @@ Data type casts have changed from ` ...` to `(ipaddr) ...` The xref:reference:unlang/foreach.adoc[foreach] keyword has changed syntax. -Instead of +Instead of ---- foreach &reply.Filter-Id { diff --git a/doc/antora/modules/howto/pages/vendors/index.adoc b/doc/antora/modules/howto/pages/vendors/index.adoc new file mode 100644 index 00000000000..2855aab8f01 --- /dev/null +++ b/doc/antora/modules/howto/pages/vendors/index.adoc @@ -0,0 +1,8 @@ += Vendors + +FreeRADIUS provides vendor-specific attributes and protocols to support many common vendors that include: + +* xref:vendors/ascend.adoc[Ascend] +* xref:vendors/bay.adoc[Bay] +* xref:vendors/cisco.adoc[Cisco] +* xref:vendors/proxim.adoc[ProxIM] diff --git a/doc/antora/modules/howto/partials/add_client.adoc b/doc/antora/modules/howto/partials/add_client.adoc new file mode 100644 index 00000000000..46cef99b6f9 --- /dev/null +++ b/doc/antora/modules/howto/partials/add_client.adoc @@ -0,0 +1,32 @@ +When we discuss clients, we mean clients of the RADIUS server, e.g. +wireless access point, network switch or other form of NAS. NOT the +network clients - such as laptops, tablets etc - they do not talk +directly to the RADIUS server. + +The above test runs `radtest` from localhost. It is useful to add a new +client, which can be done by editing the `clients.conf` file. Add the +following content: + + client new { + ipaddr = 192.0.2.1 + secret = testing123 + } + +You should change the IP address `192.0.2.1` to be the address of the +client which will be sending `Access-Request` packets. + +The client should also be configured to talk to the RADIUS server, by +using the IP address of the machine running the RADIUS server. The +client must use the same secret as configured above in the `client` +section. + +Then restart the server in debugging mode, and run a simple test using +the `testing` user. You should see an `Access-Accept` in the server +output + +*** + +*The following steps outline the best known method for configuring the +server. Following them lets you create complex configurations with a +minimum of effort. Failure to follow them leads to days of frustration +and wasted effort.* diff --git a/doc/antora/modules/howto/partials/config_server.adoc b/doc/antora/modules/howto/partials/config_server.adoc new file mode 100644 index 00000000000..9650c722e69 --- /dev/null +++ b/doc/antora/modules/howto/partials/config_server.adoc @@ -0,0 +1,35 @@ +Changing the server configuration should be done via the following +steps: + +1. Start with a "known working" configuration, such as supplied by the + default installation. +2. Make one *small* change to the configuration files. +3. Start the server in debugging mode with `radiusd -X`. +4. Verify that the results are what you expect + - The debug output shows any configuration changes you have made. + - Databases (if used) are connected and operating. + - Test packets are accepted by the server. + - The debug output shows that the packets are being processed as + you expect. + - The response packets are contain the attributes you expect + to see. + +5. If everything is OK, save a copy of the configuration, go back to + step (2), and make another change. +6. If anything goes wrong, + - double-check the configuration; + - read the *entire* debug output, looking for words like `error` + or `warning`. These messages usually contain descriptions of + what went wrong, and suggestions for how it can be fixed. + See xref:debugging/radiusd_X.adoc[an explanation of the debug output] for more details; + - try replacing your configuration with a saved copy of a "known + working" configuration, and start again. This process can clean + up errors caused by temporary edits, or edits that you have + forgotten about; + - ask for help on the + http://freeradius.org/support/[freeradius-users] mailing + list. Include a description of what you are trying to do, and + the *entire debugging output*, especially output showing the + server receiving and processing test packets. You may want to + scrub "secret" information from the output before posting it + (shared secrets, passwords, etc). diff --git a/doc/antora/modules/howto/partials/get_the_source.adoc b/doc/antora/modules/howto/partials/get_the_source.adoc new file mode 100644 index 00000000000..39cdedc27d6 --- /dev/null +++ b/doc/antora/modules/howto/partials/get_the_source.adoc @@ -0,0 +1,6 @@ +Download the latest version of the FreeRADIUS source from one of these sites: + +* https://www.freeradius.org/releases/[the FreeRADIUS web site]; or +* directly from the + ftp://ftp.freeradius.org/pub/freeradius/[FreeRADIUS FTP site]; or +* from https://github.com/FreeRADIUS/freeradius-server/[GitHub]. diff --git a/doc/antora/modules/howto/partials/initial_tests.adoc b/doc/antora/modules/howto/partials/initial_tests.adoc new file mode 100644 index 00000000000..1f870aab583 --- /dev/null +++ b/doc/antora/modules/howto/partials/initial_tests.adoc @@ -0,0 +1,27 @@ +Testing authentication is simple. Edit the `users` file (in v3 this has +been moved to `raddb/mods-config/files/authorize`), and add the +following line of text at the top of the file, before anything else: + + testing Cleartext-Password := "password" + +Start the server in debugging mode (`radiusd -X`), and run `radtest` +from another terminal window: + + $ radtest testing password 127.0.0.1 0 testing123 + +You *should* see the server respond with an `Access-Accept`. If it +doesn't, the debug log will show why. In version 2, you can paste the +output into the [debug form](http://networkradius.com/freeradius-debugging/), +and a colorized HTML version will be produced. In version 3, the +output will already be colorized in the terminal. Look for red or +yellow text, and read the relevant messages. They should describe +exactly what went wrong, and how to fix the problem. + +If you do see an `Access-Accept`, then *congratulations*, the following +authentication methods now work for the `testing` user: + + PAP, CHAP, MS-CHAPv1, MS-CHAPv2, PEAP, EAP-TTLS, EAP-GTC, EAP-MD5. + +The next step is to add more users, and to configure databases. Those +steps are outside of the scope of this short web page, but the general +method to use is important, and is outlined in the next section. diff --git a/doc/antora/modules/howto/partials/libkqueue-rpm.adoc b/doc/antora/modules/howto/partials/libkqueue-rpm.adoc new file mode 100644 index 00000000000..f97fc6976b0 --- /dev/null +++ b/doc/antora/modules/howto/partials/libkqueue-rpm.adoc @@ -0,0 +1,9 @@ +# Replace v2.6.1 with latest version +VERSION=2.6.1 +wget https://github.com/mheily/libkqueue/archive/v${VERSION}.tar.gz +tar -xvzf v${VERSION}.tar.gz +cd ./libkqueue-${VERSION} +cmake3 -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_INSTALL_LIBDIR=lib . +make +cpack3 -G RPM +yum install *.rpm diff --git a/doc/antora/modules/howto/partials/optional_packages.adoc b/doc/antora/modules/howto/partials/optional_packages.adoc new file mode 100644 index 00000000000..c3035861f63 --- /dev/null +++ b/doc/antora/modules/howto/partials/optional_packages.adoc @@ -0,0 +1,19 @@ +The following optional packages may also be needed for certain FreeRADIUS utilities or modules (e.g. particular databases). + +freeradius-krb5 (Kerberos 5 support: rlm_krb5) +freeradius-ldap (LDAP support: rlm_ldap) +freeradius-redis (Redis database support: rlm_redis) +freeradius-rest (HTTP REST support: rlm_rest) +freeradius-utils (Many useful utilities such as radtest and radclient) +SQL Database drivers: + +freeradius-freetds (Microsoft SQL Server support: rlm_sql_freetds) +freeradius-mysql (MariaDB / MySQL support: rlm_sql_mysql) +freeradius-postgresql (PostgreSQL: rlm_sql_postgresql) +freeradius-sqlite (SQlite support: rlm_sql_sqlite) +freeradius-unixODBC (SQL ODBC support: rlm_sql_unixODBC) +Languages: + +freeradius-perl (Perl support: rlm_perl) +freeradius-perl-util (Perl rlm_sqlippool_tool utility) +freeradius-python (Python 2 and 3: rlm_python, rlm_python3) diff --git a/doc/antora/modules/howto/partials/pre_test.adoc b/doc/antora/modules/howto/partials/pre_test.adoc index 92a7879e441..4de8bcd6f7e 100644 --- a/doc/antora/modules/howto/partials/pre_test.adoc +++ b/doc/antora/modules/howto/partials/pre_test.adoc @@ -1,4 +1,4 @@ -The default server configuration should be tested via the following +The default server configuration can be tested with this command: [source,shell] diff --git a/doc/antora/modules/howto/partials/start_server.adoc b/doc/antora/modules/howto/partials/start_server.adoc new file mode 100644 index 00000000000..821abad5cd0 --- /dev/null +++ b/doc/antora/modules/howto/partials/start_server.adoc @@ -0,0 +1,7 @@ +When the server has been installed on a new machine, the first step is +to start it in debugging mode, as user `root`: + + # radiusd -X + +This step demonstrates that the server is installed and configured +properly. If the output says `Ready to process requests`, then the installation was successful. diff --git a/doc/antora/modules/howto/partials/upgrade_gcc.adoc b/doc/antora/modules/howto/partials/upgrade_gcc.adoc new file mode 100644 index 00000000000..ab5f4b98d58 --- /dev/null +++ b/doc/antora/modules/howto/partials/upgrade_gcc.adoc @@ -0,0 +1,15 @@ +Depending on your OS, select the commands required to upgrade to GCC 4.9: + +---- +sudo apt-get install software-properties-common python-software-properties +sudo add-apt-repository ppa:ubuntu-toolchain-r/test +sudo apt-get update +sudo apt-get install g++-4.9 + +# Then select GCC 4.9 +sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.8 100 --slave /usr/bin/g++ g++ /usr/bin/g++-4.8 +sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.9 50 --slave /usr/bin/g++ g++ /usr/bin/g++-4.9 +sudo update-alternatives --config gcc + +# Choose option 3 from the dialogue +---- diff --git a/doc/antora/modules/installation/nav.adoc b/doc/antora/modules/installation/nav.adoc index 38cffc8514a..f932f45657c 100644 --- a/doc/antora/modules/installation/nav.adoc +++ b/doc/antora/modules/installation/nav.adoc @@ -1,12 +1,13 @@ -* xref:howto:installation/index.adoc[Installing and upgrading] -** xref:howto:installation/packages.adoc[Install from packages] +* xref:howto:installation/index.adoc[Installing and Upgrading] ** xref:howto:installation/dependencies.adoc[Dependencies] -** xref:howto:installation/source.adoc[Build from source] +** xref:howto:installation/source.adoc[Build and Install from Source] +*** Building Packages +**** xref:howto:installation/debian.adoc[Debian and Ubuntu] +**** xref:howto:installation/redhat.adoc[RedHat and CentOS] +** xref:howto:installation/packages.adoc[Install from packages] ** xref:howto:installation/upgrade.adoc[Upgrading from v3 to v4] -** xref:howto:installation/attribute_names.adoc[Attribute name changes from v3 to v4] -** Building Packages -*** xref:howto:installation/debian.adoc[Debian and Ubuntu] -*** xref:howto:installation/redhat.adoc[RedHat and CentOS] +*** xref:howto:installation/attribute_names.adoc[Attribute Name Changes from v3 to v4] + // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS.