Add OS specific install/build instructions

Author: nolade

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]

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

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

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.