From: aBainbridge11 <113794078+aBainbridge11@users.noreply.github.com> Date: Tue, 30 Jul 2024 19:54:34 +0000 (-0400) Subject: Update index.adoc X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=10771279fb97dd483cd16098700e6e3b7fec0cbe;p=thirdparty%2Ffreeradius-server.git Update index.adoc --- diff --git a/doc/antora/modules/installation/pages/index.adoc b/doc/antora/modules/installation/pages/index.adoc index 04c86a86d22..4f9f726daa3 100644 --- a/doc/antora/modules/installation/pages/index.adoc +++ b/doc/antora/modules/installation/pages/index.adoc @@ -1,4 +1,4 @@ -== Installation += Installation FreeRADIUS is available from multiple sources: @@ -13,6 +13,191 @@ The documents in this section cover details of the above installation methods, as well as instructions on building packages locally. +== Getting Started + +This page describes how to perform the initial configuration of +FreeRADIUS. It assumes a basic knowledge of Unix system administration. +No RADIUS knowledge is required. + +## Installing the Server + +Where possible, while learning the basics, it is suggested 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 +exception to this is if your operating system supplies an older +major version, as you will then be learning an obsolete +configuration. + +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. + +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. + +## Some background + +Once the server has been installed, the first thing to do is *change as +little as possible*. The default configuration is designed to work +everywhere, and to perform nearly every authentication method. + +*** + +*Do not edit the default configuration files until you understand what +they do. This means reading the documentation contained in the comments +of the configuration files.* + +*** + +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`: + + # 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. + +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). + + +## 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. + +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 + +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.* + +*** + +## 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! *These instructions cover installing FreeRADIUS 4.x, which is still @@ -32,3 +217,13 @@ 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.