diff --git a/doc/antora/modules/ROOT/nav.adoc b/doc/antora/modules/ROOT/nav.adoc index 601682c8141e..25b777e10201 100644 --- a/doc/antora/modules/ROOT/nav.adoc +++ b/doc/antora/modules/ROOT/nav.adoc @@ -1,3 +1,5 @@ * xref:index.adoc[Introduction] -** xref:radiusd_x.adoc[radiusd -X] +** xref:getstarted.adoc[Getting Started] +*** xref:radiusd_x.adoc[Debugging] +*** xref:gethelp.adoc[Getting Help] ** xref:faq.adoc[FAQ] diff --git a/doc/antora/modules/ROOT/pages/gethelp.adoc b/doc/antora/modules/ROOT/pages/gethelp.adoc new file mode 100644 index 000000000000..1575868ea32b --- /dev/null +++ b/doc/antora/modules/ROOT/pages/gethelp.adoc @@ -0,0 +1,59 @@ +# Getting Help + +## Official Documentation + +A lot of information can be found online for FreeRADIUS, but most of this information is out-of-date or +incorrect. Avoid third party documentation refer to the documentation created by FreeRADIUS and InkBridge Networks +as outlined below: + +* https://www.freeradius.org[FreeRADIUS] +* https://www.inkbridgenetworks.com[InkBridge Networks] + +## What Email list do I use? + +There are several mailing lists associated with the FreeRADIUS server project. The lists are on +the http://freeradius.org/list/[freeRADIUS] website. The current lists are: + +* *mailto:freeradius-users@lists.freeradius.org[freeradius-users]* +This list is for all users of FreeRADIUS and deals with general questions related to FreeRADIUS +* *mailto:freeradius-devel@lists.freeradius.org[freeradius-devel]* +This list is for developers who are writing code for FreeRADIUS.The content is highly technical and is +not suited to the average user. +* *mailto:freeradius-announce@lists.freeradius.org[reeradius-announce]* +This list is for all users of FreeRADIUS. Announcements about FreeRADIUS, including new versions +and security issues, are made here. + +## How can I get training for my staff? + +https://www.inkbridgenetworks.com/[Inkbridge Networks] offers a range of training courses to meet your needs. Courses include: + +* *Introduction to RADIUS* is an introductory course for all administrators who are unfamiliar with +RADIUS. Basic RADIUS concepts that are key to understanding RADIUS-based systems are +introduced. +* *Advanced RADIUS* is a course for senior administrators who are already familiar with RADIUS. It +introduces advanced RADIUS concepts that will help system administrators design, deploy, maintain +and debug their systems. +* *Programming with RADIUS* is a course for developers who wish to create their own customized +solutions. + +## How do I get support from a consultant? + +Our goal at https://www.inkbridgenetworks.com/support[InkBridge Networks] is to help you build a world-class system and to make sure it operates +smoothly. InkBridge Networks are experts at designing a customized RADIUS solution that meet your needs. Your customized network will include +the appropriate number of RADIUS and database servers for your particular business needs. We install the RADIUS server and database and generate +the necessary tables, schemas, queries, and replication. + +We can configure multiple forms of authorization on the same system simultaneously. The system can +include: + +* 802.1x +* PEAP +* EAP-TTLS +* EAP-TLS +* Authentication against Active Directory +* MAC authentication +* MAC auth bypass (MAB) + +Existing systems can be migrated to our product or we can configure our product to work with your +databases. The final result is a system that is robust, high performance, and easy to maintain. Contact us +at sales@networkradius.com for more information. diff --git a/doc/antora/modules/ROOT/pages/getstarted.adoc b/doc/antora/modules/ROOT/pages/getstarted.adoc new file mode 100644 index 000000000000..ccb497c6c19f --- /dev/null +++ b/doc/antora/modules/ROOT/pages/getstarted.adoc @@ -0,0 +1,97 @@ + += Getting Started with FreeRADIUS + +This page describes how to perform the initial install and configuration of FreeRADIUS using a package. +FreeRADIUS pre-built packages are available from https://packages.inkbridgenetworks.com[InkBridge Networks]. +This site contains the most current packages for all common OS platforms for the latest FreeRADIUS release. + +FreeRADIUS can also be installed from the source code. Please see the + xref:howto:installation/index.adoc[installation guide] for instructions. + + == Get the Source + +This page describes how to perform the initial install and configuration of FreeRADIUS. +FreeRADIUS can be installed using the pre-built packages available from https://packages.inkbridgenetworks.com[InkBridge Networks]. +This site contains packages for all common OS platforms and has the most current packages +for the latest release. + +FreeRADIUS can also be installed from the source code. Please see the + xref:howto:installation/index.adoc[installation guide] for instructions. + +[NOTE] +==== +Debian-based systems call the server daemon *freeradius* instead of radiusd and the configuration files are located in *`/etc/freeradius/`* instead of `/etc/raddb/`. +==== + +== Start the server + +Once the server has been downloaded and installed, start the server in debugging mode (as user root) by issuing the command: + +. `radiusd -X` + +If the message on your screen says *Ready to process requests*, the server is installed and configured properly. +For help decoding the the output from radiusd -X, refer to the xref:radiusd_x.adoc[Debugging] for more details. + +== Initial Tests + +Test basic authentication by editing the users file (raddb/mods-config/files/authorize) and add the following line at the top of the file: + +. testing Cleartext-Password := "password" + +Save the file and restart the server in debugging mode (radiusd -X). +Open a second terminal window and run radtest by issuing the command: + +. `radtest testing password 127.0.0.1 0 testing123` + +The expected result is that the server responds with an Access-Accept. If it doesn't, the debug log will show why. + +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. + +Your next step is to add more users. + + +== Add a Client + +Devices that communicate directly with the RADIUS server are the clients that we need to configure next. These clients can be a wireless access point(WAP) or network access switch(NAS). or other form of NAS. The network clients or end-users such as laptops, tablets, etc. 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. + +## Configure the Server + +To create complex configurations with a minimum of effort, follow the steps to configure the server *ONE* change at a time: + +. Start with a "known working" configuration, such as supplied by the default installation. +. Make one small change to the configuration file. +. Start the server in debugging mode (radiusd -X). +. Verify that the results are what you expect. + +Your next step is to configure more server components. + +## More Information + +For specific problem solving, we recommend the xref:howto:index.adoc[Howto] guide. +For configuring and testing individual modules, refer to +xref:howto:modules/configuring_modules.adoc[Modules]. + +All of the xref:reference:raddb/index.adoc[Configuration Files] are available in +hypertext format. + +A detailed xref:reference:unlang/index.adoc[unlang] reference guide that describes the syntax and functionality of the keywords, +data types, etc. used in the `unlang` processing language. + +There is also xref:developers:index.adoc[Developers] documentation that includes +the APIs references. diff --git a/doc/antora/modules/ROOT/pages/index.adoc b/doc/antora/modules/ROOT/pages/index.adoc index 91b75bf000c6..01fbaad5571e 100644 --- a/doc/antora/modules/ROOT/pages/index.adoc +++ b/doc/antora/modules/ROOT/pages/index.adoc @@ -11,76 +11,76 @@ documentation may change. Please wait for an official release before using version 4. ==== -This is the documentation for FreeRADIUS, version 4. The documentation -is available under the Creative Commons Non-Commercial license, as given -in the `LICENSE` file in this directory. +This is the FreeRADIUS version 4 documentation that is available under +the Creative Commons Non-Commercial xref:LICENSE[license]. FreeRADIUS is a complex piece of software with many configuration -options. However, we have taken great care to make the default -configuration work in most circumstances. The result is that for most -simple systems, it is trivial to install and configure the server. For -those situations, this documentation will serve to answer basic -questions about functionality, configuration, etc. - +options. In most circumstances, the default configuration works with +minimal effort to install a server. For more complex requirements, FreeRADIUS can be difficult to -configure. The reason for this difficulty is that the server can do -almost anything, which means that there are a near-infinite number of -ways to configure it. The question for an administrator, then, is what +setup because of more features and infinite configurations. The question for an administrator, then, is what piece of the configuration to change, and how to change it. -This documentation will answer those questions. The FreeRADIUS team has -put substantial effort into writing the documentation for this release. -Everything in the server is fully documented, and there are many -`how-to` guides available. - -The documentation is split into sections by subject area, oganized by -desired outcome. At a high level, the subject areas describe: - -* xref:concepts:index.adoc[Concepts] and introduction for newcomers -* The xref:reference:raddb/index.adoc[configuration files] located in `/etc/raddb/`, or `/etc/freeradius/` -* The syntax of the xref:reference:unlang/index.adoc[unlang] processing language -* Various xref:howto:index.adoc[how-to] guides -* xref:howto:installation/index.adoc[Installing] and xref:howto:installation/upgrade.adoc[upgrading] FreeRADIUS -* xref:developers:index.adoc[Developer documentation] - -This organization means that for example, the `ldap` module will have -documentation located in multiple places. We feel that organizing the -documentation by desired _goal_ is better than the alternatives. - -Within each section, the documentation is split into small pages, which -are generally no more than a few screens worth of information. We feel -that having multiple small pages with cross-links is more helpful than -having a smaller number of enormous pages. This division ensures that -(for example) the `how-to` guides are split into a series of small +This documentation answers your basic and advanced questions about functionality, configuration, and +other scenarios. The FreeRADIUS team has updated the documentation for this major release. +Everything in the server is fully documented with examples, developer information, and additional resources to help you. + +This documentation is divided into sections by subject area and organized by +task-based results as follows: + +* xref:getstarted.adoc[Getting Started] guide and FAQ to help you get setup in record time. +* xref:concepts:index.adoc[Concepts] and overview provides a high level explanation for newcomers. +* xref:reference:index.adoc[Reference] documentation includes the xref:reference:unlang/index.adoc[Unlang] syntax and xref:reference:raddb/index.adoc[Configuration Files]. +* xref:howto:index.adoc[Howto] guides step you through various tasks and includes xref:howto:installation/index.adoc[Installing] and xref:howto:installation/upgrade.adoc[Upgrade] guide. +* xref:tutorials:new_user.adoc[Tutorials] task based learning with real-world configurations and debugging exercises. +* xref:developers:index.adoc[Developers] section outlines coding standards, raising bugs, and contributing with GitHub. +* xref:ts.adoc[Troubleshooting] section to help you resolve the most common issues with FreeRADIUS installations and configurations. + +Within each section, the documentation is organized into subsections, smaller pages, and relavent cross-links. +This hierarchy ensures that you can find information quickly and extract the instructions you need. +For example, the Howto guides are split into a series of small steps, each of which can be performed quickly. -We hope that this extended documentation will address any lingering -concerns about the quality of the FreeRADIUS documentation. +== What's new in FreeRADIUS version 4 -== Current Limitations of 4.0.0 +FreeRADIUS version 4 is in "alpha" right now. If version 4 works, continue to use. +If you have issues, *return* to using FreeRADIUS version 3. -As of the time of writing this documentation, the server has the -following limitations: +As of the time of this release, FreeRADIUS: -* RADIUS/TLS (RadSec) is not implemented. -* TEAP, and EAP-FAST are not implemented. -* The "haproxy" and "reverse CoA' features are not implemented -* The Python, and Lua modules do not fully support the v4 "nested" attributes. -* Enums are now prefixed with `::`, as in `Service-Type == ::Framed-User`. +* It's possible to proxy one packet to multiple destinations. +* Can capture a `failed` proxy, and fall back to local + authentication. +* The server supports multiple clients with different shared + secrets behind one NAT gateway. +* DHCP and VMPS are integrated with full functionality and features. +* The server supports TACACS+. +* Connections to databases are `asynchronous` to ensure stable access, + and prevents server lockups. +* The Python and Lua modules do not fully support the v4 "nested" attributes. +* Enums are prefixed with `::`, as in `Service-Type == ::Framed-User`. * The server still does not always require (or print) the `::` prefix. That will change. -* As a result of adding `::` for enums, we can then remove the requirement to use `&` as a prefix for attribute names. +* By implementing `::` for enums, the requirement to use `&` as a prefix for attribute names is not needed. * This change may require changes to all of the configuration. We will try to allow `&` or not, but that may not be possible. -* Dynamic expansions have changed from `%{md5:foo}` to a slightly more standard syntax of `%md5(foo)`. - * The new syntax is much clearer, and supports multiple comma-separated arguments: `%function(a, b, c)` - * Expansions such as `%{User-Name}` will still work. Expressions like `%{1+2}` now work, too. - * Alternation `%{%{foo}:-%{bar}}` has been replaced by `%{&foo || &bar}`, which is clearer and uses less nesting. +* Dynamic expansions have changed from `%{md5:foo}` to a more standard syntax of `%md5(foo)`. +* The new syntax supports multiple comma-separated arguments such as `%function(a, b, c)`. +* Expansions such as `%{User-Name}` still work in addition to expressions like `%{1+2}` too. +* Alternation `%{%{foo}:-%{bar}}` has been replaced by `%{&foo || &bar}`, which is clearer and uses less nesting. +* RADIUS/TLS (RadSec) is not implemented. +* TEAP and EAP-FAST are not implemented. +* the "haproxy" and "reverse CoA' features are not implemented. -Please be aware that v4 is in "alpha" right now. If it works, great. -If it doesn't work, then please return to using v3. +Administrators who have version 3 and wish to upgrade to version 4 +must read the xref:howto:installation/upgrade.adoc[Upgrade] guide. +This guide explains the differences between the two versions, and +how an existing configuration can be reproduced in the latest +release. Do *not* use version 3 configuration files +with version 4. These configuration files are *not* compatible on a +major version upgrade. [WARNING] ==== -Please do not open bug reports about those features being missing. +Do not open bug reports about those features being missing. All such bug reports will be closed without comment. We do not recommend that operating systems or Linux distributions @@ -92,109 +92,35 @@ it is packaged". They will then run into issues, and will blame us. Such behavior is antisocial and is strongly discouraged. ==== -== Changes From Earlier Versions - -In previous releases, FreeRADIUS had the following limitations: - -* it was impossible to proxy one packet to multiple destinations -* it was impossible to catch a `failed` proxy, and fall back to local - authentication -* the server could not support multiple clients with different shared - secrets behind one NAT gateway -* the DHCP and VMPS was implemented by making them pretend to be RADIUS, - which limited their functionality -* the server did not support TACACS+ -* connections to databases were `synchronous`. If a database blocked, - it could eventually lock up the server - -All of these limitations and more have been removed. The downside of -these changes is that the some of the configuration has been changed. - -Administrators who have version 3 and wish to upgrade to version 4 -should read the xref:howto:installation/upgrade.adoc[upgrading] documentation. -That documentation explains the differences between the two versions, and -how an existing configuration can be reproduced in the latest -release. We do _not_ recommend using version 3 configuration files -with version 4. The configuration files are _not_ compatible across a -major version upgrade. - -== Getting Started with FreeRADIUS - -FreeRADIUS can be installed using the pre-built packages available -from https://packages.networkradius.com[Network RADIUS, -window="_blank"]. That page contains packages for all common OS -distributions. New packages are available as soon as a new version -has been released. Packages for older releases are also available for -historical purposes. - -FreeRADIUS can also be installed from the source code. Please see the - xref:howto:installation/index.adoc[installation guide] for instructions. - -WARNING: Many Operating System distributions ship versions of FreeRADIUS -which are years out of date. Those versions may contain bugs which have -been fixed in newer releases. We recommend using the -https://packages.networkradius.com[Network RADIUS, window="_blank"] packages where -possible. +== Network Prequesites -Administrators who are new to FreeRADIUS should read the -xref:concepts:index.adoc[concepts section] as it describes the concepts behind -FreeRADIUS. It is vital for newcomers to understand these concepts, as the rest -of the documentation assumes familiarity with them. +=== Operating Systems -A detailed xref:reference:unlang/index.adoc[unlang] reference guide is also available. -This section describes the syntax and functionality of the keywords, -data types, etc. used in the `unlang` processing language. +The FreeRADIUS protocol works on all Unix based systems. Selecting a familiar operating system is +A FreeRADIUS server has minimal requirements. A basic FreeRADIUS installation uses 8 megabytes of +RAM, under one hundred megabytes of disk space, and minimal CPU power. An Internet Service Provider +with 10,000 or fewer users will not have any problems with any commodity system available at the time +of this printing. -All of the xref:reference:raddb/index.adoc[configuration files] are available in -hypertext format. It can often be easier to read the configuration files -in a nicely formatted version, instead of as a fixed-width font in a -text editor. +If the ISP has more than 10,000 users, the overall system design becomes much more +important than the specifications of an individual server. Windows does not currently support FreeRADIUS. -For specific problem solving, we recommend the xref:howto:index.adoc[how-to] -guides. These guides give instructions for reaching high-level goals, or for -configuring and testing individual -xref:howto:modules/configuring_modules.adoc[modules]. +=== CPU/RAM/disk space requirements +A FreeRADIUS server has minimal requirements. A basic FreeRADIUS installation uses 8 megabytes of +RAM, under one hundred megabytes of disk space, and minimal CPU power. An Internet Service Provider +with 10,000 or fewer users will not have any problems with any commodity system available at the time +of this printing. If the ISP has more than 10,000 users, the overall system design becomes much more +important than the specifications of an individual server. -There is also xref:developers:index.adoc[developer documentation]. This section -documents the APIs for developers. Most people can ignore it. +=== Datastores == Debugging -If you have ANY problems, concerns, or surprises when running the -server, the the server should be run in debugging mode as root, from the -command line: - -``` -# radiusd -X -``` - -It will produce a large number of messages. The answers to many -questions, and the solution to many problems, can usually be found in -these messages. When run in a terminal window, error messages will be -shown in red text, and warning messages will be shown in yellow text. - -For other use-cases, please look for `ERROR` or `WARNING` in the -debug output. In many cases, those messages describe exactly what is -going wrong, and how to fix it. - -For further details, about the debug output see the -https://wiki.freeradius.org/radiusd-X[radiusd-X, window="_blank"] page on the -https://wiki.freeradius.org[wiki, window="_blank"]. - -== Getting Help - -We also recommend joining the -https://lists.freeradius.org/mailman/listinfo/freeradius-users[mailing -list] in order to ask questions and receive answers. The developers are -not on Stack Overflow, IRC, or other web sites. While the FreeRADIUS -source is available on -https://github.com/FreeRADIUS/freeradius-server/[GitHub, window="_blank"], questions -posted there will not be answered. +If you have ANY issues with your server, then restart the server +in xref:radiusd_x.adoc[Debugging] mode. Review the logs to determine what +the root problem is and make changes accordingly. Do only *ONE* change +at a time and restart your server. -Before posting to the list, please read the -https://wiki.freeradius.org/list-help[list help, window="_blank"] page. That page explains -how to run the server in debugging mode; how to understand the debug -output; and what information to post to the list. +== More Information -Commercial support for FreeRADIUS is available from -https://networkradius.com/freeradius-support/[Network RADIUS, window="_blank"]. +Many resources, https://www.inkbridge.io/[experts], and documentation sets are available to help you with your RADIUS server. Refer to xref:gethelp.adoc[Getting Help] for more details. diff --git a/doc/antora/modules/ROOT/pages/radiusd_x.adoc b/doc/antora/modules/ROOT/pages/radiusd_x.adoc index d380a4946753..e7067f67478d 100644 --- a/doc/antora/modules/ROOT/pages/radiusd_x.adoc +++ b/doc/antora/modules/ROOT/pages/radiusd_x.adoc @@ -1,11 +1,31 @@ -# How to use `radiusd -X` (debug mode) +# Debugging -This page explains how to read the output of `radiusd -X`. +This debugging section outlines the steps to take if you run into issues starting or configuring the FreeRADIUS server. +If your server starts up successfully, save a copy of the configuration so you always have a "known working" configuration. +When the server doesn't start up, go back and verify the configuration and read the entire debug output. If you have issues, the initial steps to troubleshoot or debug the server are: + +* Make small, discrete changes to the configuration files. +* Start the server in debugging mode by entering the command *radiusd -X* +* Verify that the results are what you expect +* The debug output shows any configuration changes you have made: +** Datastores 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 contain the attributes you expect to see. + +If you can't make any progress, replace your configuration with a saved copy of a "known working" configuration, and start the server again. This process can clean up errors caused by temporary or forgotten edits. +If you are still having issues, ask for help on the mailto:freeradius-users@lists.freeradius.org[freeradius-users] list. Include a description of what you are trying to do, and the entire debugging output that includes the server receiving and processing test packets. + +## How to use `radiusd -X` (debug mode) + +This next section explains how to read the output of `radiusd -X`. The first part of the debug output is the *startup* text. Once the server is started, it prints `Ready to receive requests`. The next part of the debug output is the *packet processing* text. Both parts need to be read (and posted to the list!) in order to solve issues. ## If it doesn't start +If the server does not start at all, verify that you are running the server with sudo. If the server reboots correctly after this switch, then the problem was that the server was running as an unprivileged user. + If the server does not start up correctly, *the debug output will tell you why*. It will produce long descriptive error messages, telling you exactly what's wrong. In some cases, it will tell you how to fix it. Look for messages like *Error* or *Warning*. If you are running the server in a terminal console, those messages will appear in red or yellow. It should be simple to scroll through the output, ignoring most of it, and looking for red *Error* text. @@ -14,7 +34,7 @@ Fixing those errors will usually allow the server to start correctly. ## Startup text -We start the server with `-X`. This option gives us the best combination of useful output, and readable output. Adding more `-x` gives *more complex output*, not *more useful output*. +We start the server with *`-X`*. This option gives us the best combination of useful output, and readable output. Adding more `-x` gives *more complex output*, not *more useful output*. $ radiusd -X 2>&1 | tee debugfile @@ -576,7 +596,7 @@ The `suffix` module splits the `User-Name` into a `Stripped-User-Name` and `Real (2) suffix: Adding Stripped-User-Name = "bob" (2) suffix: Adding Realm = "int" (2) suffix: Proxying request from user bob to realm int - (2) suffix: Preparing to proxy authentication request to realm "int" + (2) suffix: Preparing to proxy authentication request to realm "int" (2) [suffix] = updated (2) [files] = noop (2) } # authorize = updated @@ -635,7 +655,7 @@ Because this is a proxied request, it now runs the `post-proxy` section of the ` (2) if ("%{debug_attr:reply:}" == '') { (2) Attributes matching "reply:" (2) EXPAND %{debug_attr:reply:} - (2) --> + (2) --> (2) if ("%{debug_attr:reply:}" == '') -> TRUE (2) if ("%{debug_attr:reply:}" == '') { (2) [noop] = noop diff --git a/doc/antora/modules/ROOT/pages/ts.adoc b/doc/antora/modules/ROOT/pages/ts.adoc new file mode 100644 index 000000000000..ac6ee82b4878 --- /dev/null +++ b/doc/antora/modules/ROOT/pages/ts.adoc @@ -0,0 +1,850 @@ +## FreeRADIUS Frequently Asked Questions + +This is the FAQ (Frequently Asked Questions) for the FreeRADIUS Server (freeradius for short) development project. It contains both general and technical information about the FreeRADIUS projects' status, what it is and what it does, how to obtain and configure and run it, and more. Please read this FAQ carefully before you post questions about FreeRADIUS to the mailing lists to see if your question is already answered here first. + +## FreeRADIUS Overview + +### What is FreeRADIUS and what is it supposed to do + +The FreeRADIUS Server is a daemon for unix and unix like operating systems which allows one to set up a radius protocol server, which can be used for Authentication and Accounting various types of network access. +To use the server, you also need a correctly setup client which will talk to it, including terminal servers, Ethernet Switches, Wireless Access Points or a PC with appropriate software which emulates it (PortSlave, radiusclient etc). + +FreeRADIUS is being developed by a group of people who call themselves "the FreeRADIUS project". + +### How does it differ from other radius servers? + +First of all, FreeRADIUS is an open-source product, and has all the benefits open-source provides. + +Also, it has many features not found in free servers and many commercial ones, like: + +* Access based on huntgroups +* Multiple DEFAULT entries in raddb/users file +* All users file entries can optionally "fall through" +* Caches all config files in-memory +* Supports Simultaneous-Use = X parameter. Yes, this means that you can now prevent double logins! +* Supports Vendor-Specific attributes, including USR non-standard ones. +* Supports proxying +* Supports the "Alive" packet +* Exec-Program-Wait, allows you to set up an external program which is executed after authentication and outputs a list of A/V pairs which is then added to the reply. +* Supports PAM + +### What platforms does it run on? + +FreeRADIUS runs on a large number of 32 and 64bit Unix-like platforms. + +## Where to get information +### Is there a FreeRADIUS Web site? + +Yes, the FreeRADIUS Server site is at http://www.freeradius.org/ + +It contains the server, documentation, and additional RADIUS programs. + +### Is there any mailing list for FreeRADIUS? + +Yes, there are mailing lists for announcements, users and developers, they can all be subscribed to freely, and they all have web archives. + +Please see the description of FreeRADIUS mailing lists. + +## How to Find and Install FreeRADIUS? +### Where can I get FreeRADIUS? + +You can find it, along with some useful links and documentation, at the official FreeRADIUS WWW site: + +* http://www.freeradius.org/ + +Sources are available at: + +* ftp://ftp.freeradius.org/pub/radius/ + +### Where can I get binary packages of FreeRADIUS + +Please see the list of available packages. + +You may also easily build a package from source. + +### How do I build and install FreeRADIUS from source? + +See the instructions on how to build FreeRADIUS. + +## Common system setup issues + +### Is there a way to bind FreeRADIUS to a specific IP address? + +Yes - there are several ways to accomplish this. + +* The deprecated old way is to specify an IP address with the `_-i {IP}` command-line option. +* The better way is to use the `listen` directive in radiusd.conf. + listen { + ipaddr = 192.168.1.250 + port = 1817 + type = auth + } + +You may specify multiple `listen` directives. + +* The third way + bind_address = 192.168.1.250 + port = 1817 + +**Note!** + +If you have a multi-homed server and specify an explicit address to bind to. It may happen that the server does not respond with the right source ip address. Thus the client will likely ignore the server's response. +On Linux and FreeBSD you can solve this by specifying `./configure --with-udpfromto` during compilation. + +Then the server will always respond with the correct address. + +### Can I run FreeRADIUS under daemontools control? + +Yes, you can. Assuming you already have daemontools installed, configured and running in your system (see http://cr.yp.to/daemontools.html), you will have to make two decisions: +1. The log account and group name (_log.log_ is used in this example). Logging programs run under this _account.group_. If this _account.group pair_ does not exist yet, create it now. +2. The radiusd local service directory (_/etc/radiusd_ is used in this example). This is where radiusd will store logs and a few configuration files. + +Then perform these steps: + + groupadd log + useradd -g log log + mkdir /etc/radiusd + mkdir /etc/radiusd/log + mkdir /etc/radiusd/log/main + chmod +t+s /etc/radiusd /etc/radiusd/log + chown log.log /etc/radiusd/log/main + +The supervise program starts radiusd by running a shell script called "run" from _/etc/radiusd_. Here are the contents of _/etc/radiusd/run_: + + shell# cd /etc/radiusd + shell# cat run + #!/bin/sh + exec 2>&1 + exec /usr/sbin/radiusd -fyz -lstderr + +It is important to add -f and -l stderr to argument list of radiusd or svc and logging functions will not work properly. + +The logging feature is also started by a "run" script. This one is located in _/etc/radiusd/log_. Here are the contents of _/etc/radiusd/log/run_ + + shell# cd /etc/radiusd/log + shell# cat run + #!/bin/sh + exec setuidgid log multilog t ./main + +To set the service to start, issue the following command: + + ln -sf /etc/radiusd /service + +Now you can send signals to radiusd using the `svc` program. Here are some interesting ones: + +To hang-up (HUP) it, reloading the config, do: + + svc -h /service/radiusd + +To temporarly disable it (down) do: + + svc -d /service/radiusd + +To reenable it (up) do: + + svc -u /service/radius + +## Common problems and their solutions +### Incoming Authentication-Request passwords are all garbage. Why? + +The shared secret is incorrect. This is a text string which is a "secret" (in the raddb/clients file) shared by both the NAS and the server. It is used to authenticate and to encrypt/decrypt packets. + +Run the server in debugging mode: + + radiusd -X + +The first password you see will be in a RADIUS attribute: + + Password = "dsa2\2223jdfjs"' + +The second password will be in a log message, e.g.: + + Login failed [user/password] ... + +If the text AFTER the slash is garbage then the shared secret is wrong. Delete it on BOTH the NAS and the raddb/clients file and re-enter it. Do NOT check to see if they are the same, as there may be hidden spaces or other characters. + +Another cause of garbage passwords being logged is the secret being too long. Certain NAS boxes have limitations on the length of the secret and don't complain about it. FreeRADIUS is limited to 31 characters for the shared secret. + +### Why do Acct-Input-Octets and Acct-Output-Octets wrap at 4 GB? + +There are two possible causes of this problem. + +#### Gigawords not enabled on NAS + +Some NAS do not send "Gigawords" attributes by default. Read your NAS documentation and configure it to send the attributes Acct-Input-Gigawords and Acct-Output-Gigawords. + +For Cisco IOS, this usually achieved by entering + + aaa accounting gigawords + +(which, by "ingenious" design, requires a reload of the device on certain IOS versions). + +#### Old FreeRADIUS SQL Queries and Table Structure + +Older versions of FreeRADIUS (prior to 1.1.7) include support for logging 64-Bit counters to both the detail file and SQL modules but only the PostgreSQL module had this support configured by default. + +The detail files will simply log two distinct Attributes (Acct-Input-Octets + Acct-Input-Gigawords and Acct-Output-Octets + Acct-Output-Gigawords). + +The PostgreSQL module stores the data as a 64-bit integer (BIGINT) in one column each: AcctInputOctets and AcctOutputOctets. + +FreeRADIUS 1.1.7 and greater supports 64-bit counters in other SQL modules, with the same semantics as PostgreSQL. + +The following procedure is recommended to enable proper support for 64-bit counters in FreeRADIUS 1.1.6 and earlier: + +### Modify Database Schema + +Firstly, modify the _radacct_ table schema to be able to store 64bit integers (or 19 digit numeric fields on databases not supporting BIGINT) in the AcctInputOctets and AcctOutputOctets columns using the `ALTER TABLE` command: + +#### MySQL + + ALTER TABLE radacct CHANGE AcctInputOctets AcctInputOctets BIGINT(20); + ALTER TABLE radacct CHANGE AcctOutputOctets AcctOutputOctets BIGINT(20); + +#### Oracle + + ALTER TABLE radacct MODIFY (AcctInputOctets NUMERIC(19)); + ALTER TABLE radacct MODIFY (AcctOutputOctets NUMERIC(19)); + +### Modify FreeRADIUS Queries + +Secondly, modify the accounting queries in sql.conf to make the SQL database perform the computation that is required to merge the two values sent as attributes by the [[NAS]] into one single 64-bit integer stored in the database. + +All occurences of `'%{Acct-Input-Octets}'` need to be replaced with: + + '%{Acct-Input-Gigawords:-0}' << 32 | '%{Acct-Input-Octets:-0}' + +The same thing needs to be done for `'%{Acct-Output-Octets}'`: + + '%{Acct-Output-Gigawords:-0}' << 32 | '%{Acct-Output-Octets:-0}' + +### Why does the NAS ignore the RADIUS server's reply? + +Symptom: you are seeing lots of duplicate requests in radius.log, yet users can not login, and/or you are seeing duplicated accounting messages (up to 50 times the same accounting record as if the NAS doesn't realize you received the packet). + +Perhaps your server has multiple IP addresses, perhaps even multiple network cards. If a request comes in on IP address a.b.c.d but the server replies with as source IP address w.x.y.z most NAS won't accept the answer. + +The simplest solution is to have radiusd bind to a specific address. +It will only listen to that address and replies will always go out with that address as the source address. See Is there a way to bind FreeRADIUS to a specific IP address? there a way to bind FreeRADIUS to a specific IP address? + +The above solution is not always possible. If you have multiple IPs and want FreeRADIUS to listen on all of them. Make sure that `./configure --with-udpfromto` +was specified during compilation (see Is there a way to bind FreeRADIUS to a specific IP address? there a way to bind FreeRADIUS to a specific IP address?). On Linux and FreeBSD this will make FreeRADIUS to respond from the IP the initial request was received to. + +### VSA in Access-Reject + +Symptom: FreeRADIUS is not including VSA attributes in Access-Reject packets. (but it worked in earlier versions of FreeRADIUS) + +According RFC 2865 (section 5.44) Vendor-Specific Attributes aren't allow in Access-Reject packets. + +This behaviour was fixed in newer versions of FreeRADIUS + +### How can I disconnect user with FreeRADIUS? + +The RADIUS server receives information about user sessions from your NAS but does not actually actively maintain the users sessions. This means that you have to signal your NAS to disconnect sessions. + +Depending on your NAS type and it's configuration there are a number of ways to disconnect sessions. + +#### Packet of Disconnect + +Packet of Disconnect is the standard and recommended method to disconnect users. It is supported by many newer NAS and uses a RADIUS packet (usually sent to port 3799 although some NAS use 1700 (Mikrotik for example)) to signal that a NAS should terminate an active session. + +#### SNMP + +Many NAS support SNMP which can usually (among other things) be used to disconnect users, however implimentation details vary. Read your NAS documentation to find out whether it supports this, and which MIB to use. + +#### radkill + +radkill is a TCL program written by Jason Straight for FreeRADIUS users that monitors ISP users' online times and disconnects them if they are over their call limit. It also monitors the number of users online and will disconnect the users with the least time left to always keep lines open. It's very configurable for multiple NAS setups. + +The source archive should be available for download at: +ftp://ftp.nmo.net/pub/radkill/radkill-latest.tar.gz + +### PAP authentication works but CHAP fails + +You're not using plaintext passwords in the raddb/users file Or other password store). + +The CHAP protocol requires a plaintext password on the radius server side, for PAP it doesn't matter. + +So, if you're using CHAP, for each user entry you must use: + + Auth-Type = Local, Password = "stealme" + +If you're using only PAP, you can get away with: + + Auth-Type = System + +or anything else that tickles your fancy. + +#### But CHAP is more secure, isn't it? + +Not really. + +Q: So doesn't using CHAP really mean I must leave a file lying around with cleartext passwords for the hundreds/thousands of people who'll be using this thing? + +A: Yes. + +So what do ISP with (tens of?) thousands of customers do? + +You have 2 choices: + +* You allow CHAP and store all the passwords plaintext + * Advantage: passwords don't go cleartext over the phone line between the user and the terminal server + * Disadvantage: You have to store the passwords in cleartext on the server + +* You don't allow CHAP, just PAP + * Advantage: you don't store cleartext passwords on your system + * Disadvantage: passwords going cleartext over the phone line between the user and the terminal server + +Now, people say CHAP is more secure. Now you decide which is more likely: + +* The phone line between the user and the terminal server gets sniffed and a cracker (a GOOD one) intercepts just one password +* Your radius server is hacked into and a cracker gets ALL passwords of ALL users. + +Right. Still think CHAP is more secure? I thought so. + +This is a limitation of the CHAP protocol itself, not the [[RADIUS]] protocol. The CHAP protocol **requires** that you store the passwords in plain-text format. + +### What's with the commas in the raddb/users file? + +Commas link lists of attributes together. The general format for a raddb/users file entry is: + + name Check-Item = Value, ..., Check-Item = Value + Reply-Item = Value, + . + . + . + Reply-Item = Value + +Where the dots means repetition of attributes. + +* The first line contains check-items ONLY. +* Commas go BETWEEN check-items. +* The first line ends WITHOUT a comma. +* The next number of lines are reply-items ONLY. +* Commas go BETWEEN reply-items. +* The last line of the reply-item list ends WITHOUT a comma. + +Check-items are used to match attributes in a request packet or to set server parameters. Reply-items are used to set attributes which are to go in the reply packet. So things like Simultaneous-Use go on the first line of a raddb/users file entry and Framed-IP-Address goes on any following line. + +### How do the Attribute Operators work? + +All the attribute operators `:=,==,+=` and their meanings are listed in _man 5 users_ on machines that have FreeRADIUS installed and at the [[Operators]] page in the wiki. + +### 3Com/USR HiPerArc doesn't work + +I'm using a 3Com/USR HiPerArc and I keep getting this message on radius.log: + + Mon Jul 26 15:18:54 1999: Error: Accounting: logout: entry for NAS tc-if5 port 1 has wrong ID + +What should I do to get rid of these messages? + +You are using HiPer ARC 4.1.11, right? Version 4.1.11 has a problem reporting NAS-port numbers to Radius. Upgrade the firmware from http://totalservice.usr.com to at least 4.1.59. If you are in Europe you can telephone to 3Com Global Response Center (phone number: 800 879489), and tell them that you have bought it in the last 90 days. They will help you, step by step, to do the upgrade. + +### Simultaneous-Use doesn't work + +Here is a check list: + +1. Check that you added your NAS to _raddb/clients.conf_ and selected correct NAS type, also check the password +2. Run `radiusd -X` and see if it parses the Simultaneous-Use line. +3. Try to run `checkrad` manually; maybe you may have a wrong version of perl, don't have cmu-snmp installed etc. +4. Check the database. If it says no one is logged in, Simultaneous-Use won't work. +5. Verify that the NAS is sending accounting packets. Without accounting packets, Simultaneous-Use will NOT work. +6. Verify that the accounting packets are accepted by the datavase module. If the module returns "noop", it means that the accounting packets do not have enough information for the server to perform Simultaneous-Use enforcement. +7. In case you have SQL as a database, and you have accounting records in radacct table, you'll need to uncomment sql in session section of radiusd.conf file. Also, you'll need to uncomment Simutaneus check query in sql.conf file. + +The radius server calls the checkrad script when it thinks the user is already logged on on one or more other ports/terminal servers to verify that the user is indeed still online on that *other* port/server. If Simultaneous-Use > 1, then it might be that checkrad is called several times to verify each existing session. + +This method successfully prevents a user from logging in multiple times across multiple NAS boxes. + +#### 3Com/USR HiPerArc Simultaneous-Use doesn't work + +by Robert Dalton support at accesswest dot com + +Verify if you are using HiPerArc software version V4.2.32 release date 09/09/99 + +In order for simultaneous logins to be prevented reported port density must be set to 256 using the command : + + set pbus reported_port_density 256 + +Otherwise it changes the calculations of the SNMP object ID's. + +There is a bug in effected versions of checkrad namely the line under the subroutine "sub_usrhiper". The line that should be commented out is: + + ($login) = /^.*\"([^"]+)".*$/; + +#### Cisco Simultaneous-Use doesn't work + +Q: I am getting the following in radius.log file: + + Thu Oct 21 10:59:01 1999: Error: Check-TS: timeout waiting for checkrad + +What's wrong? + +A: Verify if you have SNMP enabled on your CISCO router, check the existence of the following line: + + snmp-server community public RO 97 + +where 97 is the access-list that specifies who gets access to the SNMP info. You should also have a line like this: + + access-list 97 permit A.B.C.D + +where A.B.C.D is the ip address of the host running the radius server. + +#### Ascend MAX 4048 Simultaneous-Use doesn't work + +Q: I am getting the following in radius.log file: + +Thu Oct 21 10:59:01 1999: Error: Check-TS: timeout waiting for checkrad + +What's wrong? + +A: Verify that you have the MAX 4048 setup in your naslist as max40xx and that you have Finger turned on. + + Ethernet->Mod Config->Finger=Yes + +### The server is complaining about invalid user route-bps-asc1-1, along with lots of others + +Ascend decided to have the 4000 series NAS boxes retrieve much of their configuration from the RADIUS server. To disable this "feature", set: + + Ethernet->Mod Config->Auth->Allow Auth Config Rqsts = No + +### Why FreeRADIUS is taking so long to start? + +This is generally caused by an incorrect named configuration. Check your named files and look for invalid entries. + +Another file to investigate is raddb/naslist. All entries there must be resolved by a DNS query. + +### PEAP or EAP-TLS Doesn't Work with a Windows machine + +The most common problem with PEAP is that the client sends a series of Access-Request messages, the server sends an series of Access-Challenge responses, and then... nothing happens. After a little wait, it all starts again. + +If you see this happening STOP! + +The RADIUS server certificate has to have special OID's in it, or else the Microsoft clients will silently fail. See the "scripts/xpextensions" file in the server "tar" file for examples, and the following page on Microsoft's site: + +http://support.microsoft.com/kb/814394/en-us + +If the clients are running Windows XP SP2, see also: + +http://support.microsoft.com/kb/885453/en-us + +You MUST follow the instructions on the first page, and install the hot fix from the second page for PEAP or EAP-TLS to work with a Windows machine. + +### It still doesn't work! + +Stop right there. Before going any further, be sure that you have included the following items in your request for help: + +* relevant portion from the raddb/users file +* debugging output (using flag -X) from radiusd +* output from radtest, when run on the same machine as radiusd + +Too many people post questions saying "something's wrong, how do I fix it?" with NO background information. This is worse than useless, it's annoying. + +Now that you have prepared all the information, post your question to the freeradius-users mailing list(http://lists.freeradius.org/mailman/listinfo/freeradius-users) + +### Debugging it yourself + +If you're REALLY interested in knowing how to debug the RADIUS server yourself, then the following steps will help you: + +1. Install "screen" (if not already installed). +2. Run a new screen and name it something convenient (eg. `screen -S radiusd`) +3. Hit "Ctrl+A-H" to log all console output to a file. +4. Start "radiusd -X" (FreeRADIUS is now running in this screen, and everything is being stored to log file. At any time, you can detach from the screen with Ctrl+A-d and reattach to the screen (both from local and over SSH) with `screen -r` to see what is going on in real time.) +5. The server SHOULD print out: + Ready to process requests. + * If it doesn't, then it should print out an error message. Read it. + * If it takes a long time to start up, and THEN prints out the message, then your DNS is broken. +6. Ensure that you have localhost in your _raddb/clients_ file. FreeRADIUS comes configured this way, so it should be there. +7. Ensure you have a valid user in your _raddb/users_ file. If everything else fails, go to the top of the file and add the following entry: + bob Cleartext-Password := "bob" + Reply-Message = "Hello, bob" +8. Run the radtest program from the LOCAL machine, in another window. This will tell you if the server is alive and is answering requests. + radtest bob bob localhost 0 testing123 +9. Ensure that you see the Reply-Message above and that you do NOT see an "Access denied" message. If you get an Access-Accept message, this means that the server is running properly. +10. Configure another machine as a RADIUS client and run radtest from that machine too. You SHOULD see the server receive the request and send a reply. + * If the server does NOT receive the request then the ports are confused. RADIUS historically uses 1645/UDP, where RFC 2138 and many new systems use the proper value of 1812/UDP. See _/etc/services_ or use the -p option to specify a different port. + * Run tcpdump in another window on the RADIUS client machine. Use the command: + * `tcpdump udp` + * Look CAREFULLY at the packets coming from the RADIUS server. Which address are they coming from? Which port? +11. If authentication works from a different machine then you have the server set up correctly. +12. Now you should use a more complicated configuration to see if the server receives and replies with the attributes you want. There is little information that can be offered here in the FAQ as your individual systems configuration can not be predicted. However, a few hints can help: + * ALWAYS test your configurations running the server in debugging mode if you want to debug a problem. If you do not do so then DO NOT expect anyone else to be able to help you. + * `radiusd -X` + * Read RFC 2138 to see what the RADIUS attributes are and how they work + * ALWAYS starts with a simple configuration in place of a more complicated one. You should not expect to be able to debug a complicated configuration entry by sending one packet, and looking at the trace. + * Make the configuration as simple as possible, EVEN IF it doesn't do exactly what you want. Then, repeatedly, try to authenticate and see if it works. If authentication succeeds, then you can gradually add more attributes to the configuration to get the entry you desire. + +### But it worked with another RADIUS server! + +After upgrading to FreeRADIUS, you may discover that some users are unable to fully use the network, but it worked fine with the previous RADIUS server you were using. + +The NAS has no idea which RADIUS server you use, and it doesn't care. The entire problem is that the responses to the NAS from the servers are different. Since FreeRADIUS only sends the attributes in a response that you tell it to send, the conclusion is that your local configuration of FreeRADIUS is incomplete. + +Use 'tcpdump' http://www.tcpdump.org to snoop the RADIUS responses from each server. Once you discover which attributes are missing from the response of FreeRADIUS, you can add them to it's configuration. Re-start the server, and your users should have full access to the network again. + + +### It says "Could not link ... file not found", what do I do? + +You may see an error message like the one below, when you try to run the server: + + Module: Loaded SQL + rlm_sql: Could not link driver rlm_sql_mysql: file not found + rlm_sql: Make sure it (and all its dependent libraries!) are in the search path of your system's ld. + radiusd.conf[50]: sql: Module instantiation failed. + +There are only a few things that can be happening: + +1) The 'mysql_config' cannot be found in $PATH. Try running "./configure | grep mysql_config" and see if you get the following: + + checking for mysql_config... no + configure: WARNING: mysql libraries not found. Use --with-mysql-lib-dir=. + configure: WARNING: sql submodule 'mysql' disabled + +If it is, simply do something like "export $PATH=$PATH:/usr/local/mysql/bin" and "./configure | grep mysql_config" again to make sure you get: + + checking for mysql_config... yes + + +Then you should run "make;make install" again. + +2) You put shared libraries into a place where your linker cannot find them. + +Everyone blames FreeRADIUS because it's the one printing the error message. But it just gets the error message from your linker. + +3) You don't have static libraries for SQL clients on your system. So doing `./configure --disable-shared;make` doesn't help. + +The 'make' process WILL print out error messages saying it's creating a static library which links to a dynamic one. If your linker is misconfigured (see #1), then FreeRADIUS still won't work. + +So you probably ignored the error/warning messages produced during the 'make' stage. That's bad. + +And libtool still does dynamic linking when told to do static linking, instead of failing to do the build. It should be taken out and shot. + +There is nothing you can do to FreeRADIUS to fix issues with non-FreeRADIUS shared libraries. Fix your SQL libraries so that: + +a) your linker can find them + +or + +b) There are static versions of those libraries available. + + +You can use the LD_LIBRARY_PATH environment variable in a script which starts the server, to set the paths where these libraries may be found. + +One some systems, you can edit /etc/ld.so.conf, ('man ld.so', or 'man ldconfig'), and add the directory containing the dynamic libraries to that list. + +See also the 'libdir' configuration directive in the 'radiusd.conf' file which is distributed with the server. It contains additional information. + +If none of these solutions work, then your ONLY option is to build FreeRADIUS without dynamic libraries. This may be done via: + + ./configure --disable-shared + make + make install + +Please READ the messages produced during the 'make' and 'make install' stages. While there is a lot of text to wade through, these messages may be the ONLY source of information as to what's wrong your system. + +### I see only one radiusd in the process list. What is wrong? + +If you have configured [[FreeRADIUS]] to use threads, then nothing is wrong. Newer Linux kernels / procps utilities report one thread by default. You can execute `ps` in the following ways to see all threads: + +For older versions of `ps` / kernel (2.4), use: + +* `ps -efm` +* `ps auxm` + +For newer versions of ps / kernel (2.6+), you may prefer to use: + +* `ps -efL` +* `ps auxH` + +## How do I ... ? +### How do I send a message to PPP users? + +On Windows, the short answer is that you don't. + +RADIUS defines a Reply-Message attribute, which you can often use to +send text messages in a RADIUS reply packet. PPP has provisions for +passing text messages back to the user. + +Unfortunately, Microsoft decided to ignore that part of the PPP +protocol. So you CAN send messages to Windows PPP users. But Windows +will throw the message away, and never show it to the user. + +If you don't like this behaviour, call Microsoft and complain. + +On the Mac side, the only dialer that shows up the server's message +is FreePPP at http://www.rockstar.com. + +### How do I deny access to a specific user, or group of users? + +You need to use the Group check item to match a group. You also need to use the Auth-Type := Reject check item to deny them access. A short message explaining why they were rejected wouldn't hurt, so a Reply-Message reply attribute would be nice. This rule needs to match for all users, so it should be a DEFAULT entry. You want to apply it *instead* of any other authentication type, so it should be listed BEFORE any other entry which contains an Auth-Type. It doesn't need a Fall-Through, because you're not giving the user any permission to do anything, you're just rejecting them. + +The following entry denies access to one specific user. Note that it MUST be put before ANY other entry with an Auth-Type attribute. + + foo Auth-Type := Reject + Reply-Message = "foo is not allowed to dial-in" + +The following entry denies access to a group of users. The same restrictions as above on location in the raddb/users file also apply: + + DEFAULT Group == "disabled", Auth-Type := Reject + Reply-Message = "Your account has been disabled" + +### How do I log failed login attempts in a SQL database? + +You may run a SQL query each time a user has an access denied. First you need to write your SQL statement in the directive *postauth_query* of the module rlm_sql. For example: + + postauth_query = "INSERT into radpostauth (user, pass, date) values ('%{User-Name}', '%{User-Password:-Chap-Password}', '%S')" + +Then add the sql module to the *post-auth* section of radiusd.conf. Since we want to run the SQL query only on failed login, we need to use the sub-section Post-Auth-Type REJECT. For example: + + post-auth { + # Login successful: get an address from the IP pool. + ippool + + Post-Auth-Type REJECT { + # Login failed: log to SQL database. + sql + } + } + +Note: This option is usable if you want to detect fraud or similar activities from your users. Keep in mind that this table can become very large in case you disable too many user accounts, in case of ddos attack, etc. Every rejected attempt will be logged. + +### How do I use Login-Time for groups, not for users? + +Limit logons between 08:00am and 08:00pm for Unix group "daysonly" + + DEFAULT Group == "daysonly", Login-Time := "0800-2000" + +or + + DEFAULT Group == "daysonly", Login-Time := "Any0800-2000" + +Limit logons between 08:00am and 08:00pm, from Monday to Friday for Unix group "weekdays" + + DEFAULT Group == "weekdays", Login-Time := "Wk0800-2000" + +Limit logons between 08:00am and 08:00pm, in Saturday and Sunday for Unix group "weekends" + + DEFAULT Group == "weekends", Login-Time := "Sa-Su0800-2000" + +### How do I enable FreeRADIUS to log accounting attribute type X? + +You can't. A RADIUS server will only log the messages which a NAS sends to it. If your NAS is not sending those messages or attributes, then the RADIUS server will not log them. + +You must configure your NAS to send the information you want to the RADIUS server. Once the NAS is sending the information, the server can then log it. + +### How do I permit access to any user regardless of password? + +Edit raddb/users, on top of it put + + DEFAULT Auth-Type := Accept + +That will accept everybody. If you want this to apply to a single user replace DEFAULT with username. You can also add Auth-Type Accept to radcheck or radgroupcheck entries in order to accept that user/group. This only works for PAP, and does NOT work for EAP-TLS, CHAP, MSCHAP, or WIMAX authentication. + +### How do I limit access to only POP3 and SMTP? + +Q: I need to limit some users to be able only to use our POP3 and SMTP server. + +The most common approach is to just assign non-globally-routable IP addresses to those users, such as RFC1918 addresses. Depending on your internal network configuration, you may need to set up internal routes for those addresses, and if you don't want them to do anything besides SMTP and POP3 within your network, you'll have to set up ACLs on your dialup interfaces allowing only ports 25 and 110 through. + +Make sure you have RADIUS authorization enabled on your NAS. + +Example user entry in raddb/users file: + + foo Auth-Type := System + Framed-Filter-Id += "160.in" + Framed-Filter-Id += "161.out" + Fall-Through = Yes + +CISCO's config must have: + + aaa authorization network default radius + ip access-list extended 160 + permit ip ... + ip access-list extended 161 + permit ip ... + +The access list 160 gets applied on inbound packets and 161 on outbound packets. + +### How do I use PAM with FreeRADIUS? + +You'll need the redhat/radiusd.pam file from the distribution. It should go into a new file, /etc/pam.d/radiusd. + +If you have 100's to 1000's of users in /etc/passwd, you'll want to replace the pam_pwdb.so entries with pam_unix_auth.so, pam_unix_acct.so etc. The pam_pwdb module is INCREDIBLY SLOW for authenticating users from a large /etc/passwd file. + +Bruno Lopes F. Cabral|mailto:bruno-at-openline-dot-com-dot-br also says: + +Now I can emulate group behaviour using just PAM and some tricks, like + + auth required /lib/security/pam_userdb.so crypt db=/etc/raddb/data/users + auth required /lib/security/pam_listfile.so item=user sense=allow file=/etc/raddb/data/somehunt.allow onerr=fail + auth required /lib/security/pam_nologin.so + account required /lib/security/pam_userdb.so + +and + + DEFAULT Huntgroup-Name ="somehunt", Auth-Type=PAM, Pam-Auth="radhunt", Simultaneous-Use=1 + Fall-Through = Yes + +this way I have NO users on /etc/password and NO need for lots of lines on /etc/raddb/users. time to search for a db enabled pam_listfile module + +### How do I get radius to pick up changes in the raddb/users file? + + +The server reads the config files just once, at startup. This is very efficient, but you need to tell the server somehow to re-read its config files after you made a change. This can be done by sending the server a SIGHUP (signal '1' on almost if not all UNIX systems). The server writes its PID in +`/var/run/radiusd.pid`, so a simple UNIX command to do this would be: + + kill -1 `cat /var/run/radiusd.pid` + + +Some people would be tempted to do this every 5 minutes so that changes come through automatically. That is not a good idea as it might take some time to re-read the config files and the server may drop a few authentication requests at that time. A better idea is to use a so-called "timestamp file" and only send a SIGHUP if the raddb/users file changed since the last time. For example a script like this, to be run every 5 minutes: + + #! /bin/sh + cd /etc/raddb + if [ ! -e .last-reload ] || [ "`find users -nt .last-reload`" ]; then + if radiusd -C > .last-reload 2>&1; then + kill -1 `cat /var/run/radiusd.pid` + else + mail -s "radius reload failed!" root < .last-reload + fi + fi + touch .last-reload + +Of course a Makefile is suited perfectly for this kind of stuff. + +### How do I check the configuration before sending a HUP to the server? + + +Some administrators have automated scripts to update the radius servers +configuration files. The server can then be signalled via a HUP signal to +re-read certain configuration files (see below). + +The problem with this approach is that any syntax errors in the configuration +file may cause your main radius server to die. Therefore there should be some process of checking the configuration files prior to re-starting the server. + +With FreeRADIUS 2.0.0 and up you can use the -C option for radiusd to check +certain parts of your configuration files. See the radiusd(8) manpage for further details +and limitations of the -C option. Related posts on freeradius-users: +067362(http://lists.freeradius.org/pipermail/freeradius-users/2007-November/067362.html) +067279(http://lists.freeradius.org/pipermail/freeradius-users/2007-November/067279.html) + +#### Example for broken configuration (users) file: + + shell# freeradius -XC; echo $? + FreeRADIUS Version 2.0.0-beta, for host i486-pc-linux-gnu, built on Nov 12 2007 at 17:25:45 + [...] + /etc/freeradius/users[5]: Syntax error: Previous line is missing a trailing comma for entry DEFAULT + Errors reading /etc/freeradius/users + /etc/freeradius/radiusd.conf[1033]: Instantiation failed for module "files" + [...] + Errors initializing modules + 1 + +#### Example for working configuration: + + shell# freeradius -XC; echo $? + FreeRADIUS Version 2.0.0-beta, for host i486-pc-linux-gnu, built on Nov 12 2007 at 17:25:45 + [...] + Configuration appears OK. + 0 + +Note however, that this option is not available in freeradius 1.x. The freeradius distribution contains a _check-radiusd-config_ script which checks the configuration by starting a second server on a different port and waiting for it to crash or not to crash... + +### How do I send multiple values for an attribute ? + +Use the following configuration : + + Framed-Route := "10.130.1.252/32 0.0.0.0 5", + Framed-Route += "10.130.0.252/32 0.0.0.0 10", + +Which gives : (tcpdump output) + + Framed Route Attribute (22), length: 28, Value: 10.130.1.252/32 0.0.0.0 5 + 0x0000: 3130 2e31 3330 2e31 2e32 3532 2f33 3220 + 0x0010: 302e 302e 302e 3020 2035 + Framed Route Attribute (22), length: 28, Value: 10.130.0.252/32 0.0.0.0 10 + 0x0000: 3130 2e31 3330 2e30 2e32 3532 2f33 3220 + 0x0010: 302e 302e 302e 3020 3130 + +### How do I tell the user what to use for an IP netmask? + +The whole netmask business is a complicated one. An IP interface has an IP address and usually a netmask associated with it. Netmasks on point-to-point interfaces like a PPP link are generally not used. + +If you set the Framed-IP-Netmask attribute in a radius profile, you are setting the netmask of the interface on the side of the NAS. The Framed-IP-Netmask attribute is NOT something you can set to influence the netmask on the side of the dialin user. And usually, that makes no sense anyway even if you could set it. + +The result of this on most NAS is that they start to route a subnet (the subnet that contains the assigned IP address and that is as big as the netmask indicates) to that PPP interface and thus to the user. If that is exactly what you want, then that's fine, but if you do not intend to route a whole subnet to the user, then by all means do NOT use the Framed-IP-Netmask attribute. + +Many NAS interpret a left-out Framed-IP-Netmask as if it were set to 255.255.255.255, but to be certain you should set the Framed-IP-Netmask to 255.255.255.255. + +For example, the following entries do almost the same on most NAS: + + user Cleartext-Password := "blegh" + Service-Type = Framed-User, + Framed-Protocol = PPP, + Framed-IP-Address = 192.168.5.78, + Framed-IP-Netmask = 255.255.255.240 + + user Cleartext-Password := "blegh" + Service-Type = Framed-User, + Framed-Protocol = PPP, + Framed-IP-Address = 192.168.5.78, + Framed-Route = "192.168.5.64/28 0.0.0.0 1" + +The result is that the end user gets IP address 192.168.5.78 and that the whole network with IP addresses 192.168.5.64 - 195.64.5.79 is routed over the PPP link to the user (see the RADIUS RFCs for the exact syntax of the Framed-Route attribute). + +### How do I make CHAP work with LDAP? + +The ldap module can only work with PAP passwords since it needs to send the clear text user password to the LDAP server to authenticate the user. +There are however provisions to extract the user password from the LDAP and make it available to the server core and the chap module. +See [[rlm_ldap]] for more details on how to configure the ldap module to do that. + +There are a few things that the administrator should watch out for though: + +* Add the chap module in the authorize section of radiusd.conf before any other modules which set the Auth-Type attribute. That way the chap module can check if the current request contains a PAP or CHAP password and if it contains the former then it will set the Auth-Type to CHAP. +* The := operator should not be used in the users file to set the Auth-Type since it will set the Auth-Type regardless of wether it has already being set to some other value. +* An 'authtype CHAP' subcomponent should be added in the authenticate section of [[radiusd.conf]] which will contain the chap module. + +### How do I make Windows XP clients use only PAP (Not CHAP) + +* Go to Network Connections an open Properties for this connection. +* Select Security tab +* Click on Advanced radio button, and then on Settings button +* Leave only PAP ticked +* Click OK, OK to set it + +If you have control over NAS, then set it to accept only PAP authentication. If you do that, all clients will "listen" and use only PAP. In that case there is no need to configure anything on the client(s). + +### How do I enable logging of 64 bit counters, a.k.a. `Acct-{Input|Output}-Gigawords?` + +Please see: Why do Acct-Input-Octets and Acct-Output-Octets wrap at 4 GB? + +### Does FreeRADIUS Support IPv6? + +FreeRADIUS 1.1.x does not particularly care if the host it runs on is dual-stack. It will work just fine, but only use the IPv4 stack of the machine. It will also transport IPv6 RADIUS attributes just fine but will NOT send packets over IPv6. + +FreeRADIUS Server 2.0.0 and greater has full support for both IPv6 attributes and IPv6 network packets. + +## References + +### FreeRADIUS Related Web Pages + +* FreeRADIUS Web Page +* FreeRADIUS Wiki +* Cistron RADIUS Web Page +* FreeRADIUS on Red Hat systems + +### Mailing Lists + +* FreeRADIUS Users Mailing List Subscription(http://lists.freeradius.org/mailman/listinfo/freeradius-users) +* FreeRADIUS Users Mailing List Archive(http://lists.freeradius.org/pipermail/freeradius-users/) +* FreeRADIUS Developers Mailing List Subscription(http://lists.freeradius.org/mailman/listinfo/freeradius-devel) +* FreeRADIUS Developers Mailing List Archive(http://lists.freeradius.org/pipermail/freeradius-devel/) + +### RADIUS RFC and Drafts + +RADIUS related RFCs and Drafts are archived at: +* http://www.freeradius.org/rfc/ + +## Acknowledgments + +FreeRADIUS is the result of the work done by a large number of people. + +The major contributors are listed on the Acknowledgments page. diff --git a/doc/antora/modules/concepts/nav.adoc b/doc/antora/modules/concepts/nav.adoc index 493b95664176..72b8253b50f9 100644 --- a/doc/antora/modules/concepts/nav.adoc +++ b/doc/antora/modules/concepts/nav.adoc @@ -1,6 +1,11 @@ * xref:index.adoc[Concepts] -** General -*** xref:aaa.adoc[AAA] +** xref:overview.adoc[General] +*** xref:architecture.adoc[Architecture] +*** xref:authproto.adoc[Protocols] +*** xref:database.adoc[Datastores] +** xref:aaa.adoc[AAA] +*** xref:processing.adoc[Processing] ** Modules *** LDAP **** xref:modules/ldap/authentication.adoc[Authentication] +** xref:resources.adoc[Resources] diff --git a/doc/antora/modules/concepts/pages/aaa.adoc b/doc/antora/modules/concepts/pages/aaa.adoc index aff877ad6bb3..d6957805d619 100644 --- a/doc/antora/modules/concepts/pages/aaa.adoc +++ b/doc/antora/modules/concepts/pages/aaa.adoc @@ -57,3 +57,23 @@ xref:reference:unlang/list.adoc[attribute lists]: All of these lists are available to all modules. All of these lists are available in xref:reference:unlang/index.adoc[Unlang] +=== Accounting + +Accounting refers to the recording of resources a user consumes during the time they are on the network. +The information gathered can include the amount of system time used, the amount of data sent, or the +quantity of data received by the user during a session. + +During a network session, the NAS periodically sends an accounting of user activity to the server. This +accounting is a summary, and the collected data is used for billing purposes. +ISPs are a large consumer of accounting data, because each user is billed for every minute of network +access. However, corporations have not, historically, relied on network accounting information gathered +by RADIUS because employees were not traditionally billed for network access. As their need for ongoing +network monitoring increases, though, so does the need to store and process accounting information. +The accounting summary sent by the NAS to the server does not include detailed information such as web +sites visited or even how many bytes were transferred using a particular protocol (SMTP, HTTP, and so +forth). That type of detailed information is only available to the NAS, and it does not send that data to the +server. + +If detailed information about user activity is required, network administrators can obtain it through other +protocols such as sFlow or NetFlow. Network administrators may find it difficult to tie the pieces together to get a more comprehensive +understanding of user activity. diff --git a/doc/antora/modules/concepts/pages/architecture.adoc b/doc/antora/modules/concepts/pages/architecture.adoc new file mode 100644 index 000000000000..93471adc92e3 --- /dev/null +++ b/doc/antora/modules/concepts/pages/architecture.adoc @@ -0,0 +1,39 @@ += Architecture + +RADIUS is a network protocol, a system that defines rules and conventions for communication between +network device. Like many protocols, RADIUS uses a client-server model. A RADIUS client (also called a +Network Access Server, or NAS) sends requests to a RADIUS server. The RADIUS server then processes the +request and sends back a response. + +Common NAS products include wireless access points such as the Linksys WRT54G and dial-up +equipment commonly available from large network manufacturers. Common RADIUS server products +include Cisco ACS, Microsoft IAS, Funk (now Juniper) Steel Belted RADIUS, Open Systems Radiator, and +FreeRADIUS. + +== RADIUS Components + +The RADIUS protocol shares the general concept of client-server communication with many other +protocols such as HTTP and SMTP, the specifics of RADIUS communications differ. This section describes +the RADIUS system in more detail, including the specific roles of the NAS, the server, and datastores such +as MySQL and Lightweight Directory Access Protocol (LDAP). + +=== User / Device + +Requests access to the network. A device may be a laptop, modem, or VOIP Phone + +=== Network Access Server (NAS) + +Provides access to the network for the user/device. The NAS can be a switch, Wireless Access Point, or VPN Terminator. + +=== Authentication Server + +Receives authentication requests from the NAS and returns authentication results to the NAS. +Optionally requests user and configuration information from the database or directory. The server may +return configuration parameters to the NAS. Receives accounting information from the NAS. Some exanples of a RADIUS server +are FreeRADIUS, Radiator, NPS, or IAS. + +=== Datastore + +Optional database or directory with user authentication and authorisation information. RADIUS server communicates with the +data store using DB API or LDAP. Types of data stores include SQL Database, Kerberos Service Server, or an +LDAP Directory. diff --git a/doc/antora/modules/concepts/pages/authproto.adoc b/doc/antora/modules/concepts/pages/authproto.adoc new file mode 100644 index 000000000000..3141a74666f5 --- /dev/null +++ b/doc/antora/modules/concepts/pages/authproto.adoc @@ -0,0 +1,34 @@ += PROTOCOLS + +== RADIUS Protocol + +RADIUS is a protocol for remote user Authorization, Authentication, and Accounting. Its primary use is for Internet Service Providers, though it may as well be used on any network that needs a centralised authentication and/or accounting service for its workstations. + +RADIUS is often used in larger Wi-Fi (wireless) networks for authentication purposes, replacing the simple shared key methods which are uncomfortable if a Wi-Fi network reaches a specific size. + +The protocol originally was designed by the well known terminal server manufacturer Livingston for use with their Portmaster series of terminal servers. Since then it has been implemented by hundreds other vendors and has a become an Internet Standard RFC. The DIAMETER protocol is the designated successor, but RADIUS is still commonly used today. + +=== Radius Protocol dependencies + +UDP: RADIUS uses UDP as its underlying protocol. The registered UDP port for RADIUS traffic is 1812; the early deployment of RADIUS used UDP port 1645, which conflicted with the "datametrics" service. When RADIUS is used for accounting rather than authentication and configuration, the registered UDP port is 1813; the early deployment used port 1646, which conflicted with the "sa-msg-port" service. + +== Authentication PROTOCOLS + +In order for RADIUS authentication to work, user passwords need to be stored in a format that is understood by the authentication protocol used by the client. Many protocols integrated with RADIUS include: + +* PAP +* CHAP +* MS-CHAP +* EAP + +Authentication protocols used in RADIUS are not always compatible with the way the passwords have been stored. The following table shows which protocol is compatible with what kind of password. + +== More Information + +Refer to xref:reference:dictionary/index.adoc[Attributes] for more protocol attribute details. +https://www.iana.org/assignments/radius-types/radius-types.xhtml[RADIUS Packet Types] +https://datatracker.ietf.org/doc/html/rfc2867[RFC 2867] RADIUS Accounting Modifications for Tunnel Protocol Support +https://datatracker.ietf.org/doc/html/rfc2868[RFC 2868] RADIUS Attributes for Tunnel Protocol Support +https://datatracker.ietf.org/doc/html/rfc2869[RFC 2869] RADIUS Extensions +https://datatracker.ietf.org/doc/html/rfc3758[RFC 3748] Extensible Authentication Protocol (EAP) +https://datatracker.ietf.org/doc/html/rfc3579[RFC 3579] - RADIUS (Remote Authentication Dial In User Service) Support For Extensible Authentication Protocol (EAP) diff --git a/doc/antora/modules/concepts/pages/database.adoc b/doc/antora/modules/concepts/pages/database.adoc new file mode 100644 index 000000000000..0450339ebe8f --- /dev/null +++ b/doc/antora/modules/concepts/pages/database.adoc @@ -0,0 +1,9 @@ += Databases + +== RADIUS Information + +https://www.freeradius.org/[FreeRADIUS] + +https://www.inkbridgenetworks.com/[Inkbridge Networks] + + diff --git a/doc/antora/modules/concepts/pages/index.adoc b/doc/antora/modules/concepts/pages/index.adoc index f798e98bf1d1..192ad24f5321 100644 --- a/doc/antora/modules/concepts/pages/index.adoc +++ b/doc/antora/modules/concepts/pages/index.adoc @@ -1,8 +1,12 @@ = Concepts -This section documents concerning the protocols and modules used by the -FreeRADIUS server. +This section introduces you to the main concepts behind RADIUS and it's related components. +It is intended for users with limited RADIUS knowledge or experience. The information provided +will help us understand the basic concepts and how RADIUS works in a network environment. -It is intended to provide more theoretical information about particular subjects -than would be appropriate to include inline in module configurations or as -sidebars in howto guides. +The following sections are: + +* xref:concepts:overview.adoc[Overview] outlines the RADIUS protocol, features, and benefits. +* xref:concepts:architecture.adoc[Architecture] explains the RADIUS design and components. +* xref:concepts:autoproto.adoc[Protocols] defines the protocols used in the RADIUS environment. +* xref:concepts:database.adoc[Datastores] details how datastores work and what's supported.S diff --git a/doc/antora/modules/concepts/pages/overview.adoc b/doc/antora/modules/concepts/pages/overview.adoc index d1a248e41031..5bab0b4bfcf7 100644 --- a/doc/antora/modules/concepts/pages/overview.adoc +++ b/doc/antora/modules/concepts/pages/overview.adoc @@ -1,39 +1,130 @@ = Overview -FreeRADIUS is a modular, high performance and feature-rich [[RADIUS|glossary/RADIUS]] suite including [[server|config/radiusd]], [[radius client|Radclient]], development libraries and numerous additional [[RADIUS|glossary/RADIUS]] related utilities. +The server is written in a “plug in” model. The server core does the basic RADIUS and network handling. +Almost everything else is managed as a plug-in module. This design is what enables the policy +language to be incredibly exible. The policy language can simply run one or more plug-in modules, in any +order. Each plug-in module can be responsible for onelogical unit of functionality. +For example, each of the authentication methods (PAP,CHAP, MS-CHAP, TOTP, and EAP) are individual plug- +in modules. Similarly, each database connector (SQL,Redis, LDAP, etc.) are individual plug-in modules. +In many cases, no code changes to the server core have to be made in order to support +complex new functionality. -As the premiere open source RADIUS suite it is included as a [[standard package|building/packages]] with numerous Operating Systems, has binary packages for many others and has source available which is known to [[build|building/build]] on almost anything. Production deployments include large scale installations comprising multiple [[AAA|glossary/AAA]] servers with over ten million users and millions of requests per day. It supports request [[proxying|config/proxy]], with [[fail-over|config/fail-over]] and [[load balancing|config/load balancing]], as well as the ability to access many types of back-end databases. Different classes of [[authentication|glossary/Authentication]] requests can trigger access of different [[authentication|glossary/Authentication]] and [[authorization|glossary/Authorization]] databases (with cascaded fall back), and [[Accounting|glossary/Accounting]] records can be simultaneously recorded in multiple different storage databases and directories. +== What is RADIUS? -[[Other RADIUS Servers|glossary/Other RADIUS Servers]] are available. +RADIUS, which stands for “Remote Authentication Dial In User Service”, is a network protocol - a system +that defines rules and conventions for communication between network devices - for remote user +authentication and accounting. Commonly used by Internet Service Providers (ISPs), cellular network +providers, and corporate and educational networks, the RADIUS protocol serves three primary functions: -We also keep a list of [[acknowledgements|project/Acknowledgements]] of contributions to FreeRADIUS development. +* Authenticates users or devices before allowing them access to a network +* Authorizes those users or devices for specific network services +* Accounts for and tracks the usage of those services. -== Features +=== History + +In 1991, Merit Network, a non-profit internet provider, required a creative way to manage dial-in access to +various Points-Of-Presence (POPs) across its network. In response to this need, RADIUS was created by +Livingston Enterprises. +At the time RADIUS was created, network access systems were distributed across a wide area and were +run by multiple independent organizations. Central administrators wanted to prevent problems with +security and scalability, and thus did not want to distribute user names and passwords; instead, they +wanted the remote access servers to contact a central server to authorize access to the requested system +or service. In response to contact from the remote access server, the central server would return a +“success” or “failure” message, and the remote machines would be in charge of enforcing this response +for each end user. +The goal of RADIUS was, therefore, to create a central location for user authentication, wherein users from +many locations could request network access. +The simplicity, efficiency, and usability of the RADIUS system led to its widespread adoption by network +equipment vendors, to the extent that currently, RADIUS is considered an industry standard and is also +positioned to become an Internet Engineering Task Force (IETF) standard. + +=== Customers + +A wide and varied array of businesses currently utilize the RADIUS protocol for their authentication and +accounting needs. Some examples of RADIUS customers are: + +* Cellular network providers with millions of users +* Small WISP start-up providing the local neighborhood with Internet connectivity +* Enterprise networks implementing Network Access Control (NAC) using 802.1x to ring fence their +network + +=== Benefits + +The RADIUS client server protocol contains many technological advantages for customers, including: -- Complete support for RFC 2865 and RFC 2866 attributes. -- [[EAP|protocol/EAP]] with EAP-MD5, EAP-SIM, EAP-TLS, EAP-TTLS, [[EAP-PEAP|protocol/EAP-PEAP]], and Cisco [[LEAP|protocol/LEAP]] EAP sub-types -- [[Vendor Specific Attributes|glossary/Vendor-Specific Attributes]] for almost one hundred vendors, including BinTec, Foundry, [[Cisco|vendor/Cisco]], Juniper, Lucent/Ascend, [[HP ProCurve|vendor/HP]], Microsoft, USR/3Com, Acc/Newbridge and many more. +* An open and scalable solution +* Broad support by a large vendor base +* Easy modification +* Separation of security and communication processes +* Adaptable to most security systems +* Workable with any communication device that supports RADIUS client protocol -All known [[RADIUS Clients|glossary/RADIUS Clients]] are supported. +The RADIUS client-server architecture provides an open and scalable solution that is broadly supported +by a large vendor base. It can be readily modified to meet a variety of situations. Customers can modify +RADIUS-based authentication servers to work with a large number of security systems on the market. +RADIUS servers work with any communications device that supports the RADIUS client protocol. +In addition, the flexibility of the RADIUS authentication mechanisms allows an organization to maintain +any investment they may have made in an existing security technology: customers can modify the +RADIUS server to run with any type of security technology. The flexible authentication mechanisms +inherent in the RADIUS server facilitate its integration with existing and legacy systems when required. -- [[RADIUS Clients|glossary/RADIUS Clients]] -- [[EAP Clients|guide/EAP Clients]] +Another advantage of the RADIUS architecture is that any component of a security system that supports +the RADIUS protocols can derive authentication and authorization from the central RADIUS server. +Alternatively, the central server can integrate with a separate authentication mechanism. +The utility of the RADIUS protocol extends beyond those systems that utilize network access devices and +terminal servers for network access. RADIUS has been widely accepted by Internet Service Providers (ISPs) +to provide Virtual Private Network (VPN) services. In this context, RADIUS technology allows an organization to use ISP infrastructure for communications securely. +The distributive nature of RADIUS effectively separates the security processes (carried out on the authentication server) from the communications processes (implemented by the modem pool or the Network +Access Server (NAS)), allowing for a single centralized information store for authorization and authentication information. This centralization can significantly lessen the administrative burden of providing +appropriate access control for a large number of remote users. If ensuring high availability is not a priority, +then redundancy is not required; this centralization can thus be maximized, since all RADIUS-compatible +hardware on a LAN can derive authentication services from a single server. -.Flexible Configuration +== What is FreeRADIUS? -FreeRADIUS provides a wide range of methods to select user configurations. The server can select a configuration based on any of the following criteria : +FreeRADIUS is the most popular and the most widely deployed open source RADIUS server in the world. +It serves as the basis for multiple commercial offerings, and it supplies the authentication, authorization, +and accounting (AAA) needs of many Fortune 500 companies and Tier 1 ISPs. It is also widely used by the +academic community (i.e., eduroam, the world-wide roaming access service developed for the international research and education community, utilizes FreeRADIUS software). +FreeRADIUS was started in August 1999 by Alan DeKok and Miquel van Smoorenburg. Miquel had +previously written the Cistron RADIUS server software, which had been widely adopted when the +Livingston server was no longer in service. FreeRADIUS was developed using a modular design, to +encourage more active community involvement. -- [[attributes|protocol/Attributes]] which have a given value -- [[attributes|protocol/Attributes]] which do not have a given value -- [[attributes|protocol/Attributes]] which are in the request (independent of their value) -- [[attributes|protocol/Attributes]] which are not in the request -- String [[attributes|protocol/attributes]] which match a regular expression -- Integer [[attributes|protocol/attributes]] which match a range (e.g. , =) -- Source IP address of the request. (This can be different from the NAS-IP-Address) -- Shortname defined for a NAS box. (This can be different from the NAS-Identifier) -- Group of NAS boxes. (These may be grouped based on Source IP address, NAS-IP-Address, or any other configuration) -- User-Name -- DEFAULT template configuration -- multiple cascading DEFAULT template configurations +=== Features + +More authentication types are supported by FreeRADIUS than by any other open source server. For +example, FreeRADIUS is the only open source RADIUS server to support Extensible Authentication +Protocol (EAP). +FreeRADIUS is also the only open source RADIUS server to support virtual servers. The use of virtual +servers means that complex implementations are simplified and ongoing support and maintenance costs +for network administrators are greatly reduced; thus, the ability of FreeRADIUS to support virtual servers +gives it a huge advantage over the competition. + +=== Modularity + +The modular design protocol makes FreeRADIUS easy to understand. The modular interface also +simplifies adding or removing modules - for example, if a feature is not needed for a particular configuration, the module is easily removed. Once the module is removed, it does not affect server performance, +memory use, or security. This flexibility enables the server to run on platforms ranging from embedded +systems to multi-core machines with gigabytes of RAM. + +=== Scalability + +A single RADIUS server can easily transition from handling one request every few seconds to handling +thousands of requests per second, simply by reconfiguring a few default settings. Many large organizations (those with more than 10 million customers) are dependent on FreeRADIUS for their AAA needs. +Often, only a single FreeRADIUS server is required to fill the needs of these large organizations. +While many commercial severs offer different versions of their software to handle different needs, only +the latest version of FreeRADIUS is needed to obtain better performance, more realms, more RADIUS +clients, and many other features, with no need to purchase additional product licenses. + +== Features -In addition, FreeRADIUS supports [[virtual servers|config/virtual server]] which allow several separate sets of configuration data to coexist inside the same server instance. +* Complete support for https://datatracker.ietf.org/doc/html/rfc2865[RFC 2865] and https://datatracker.ietf.org/doc/html/rfc2866[RFC 2866] attributes. +* Authentication Protocol supports for : +** EAP or protocol/EAP with EAP-MD5, EAP-SIM, EAP-TLS, EAP-TTLS +** EAP-PEAP or protocol/EAP-PEAP +** Cisco LEAP or protocol/LEAP and EAP sub-types +* Vendor Specific Attributes for over a hundred vendors including BinTec, Foundry, Cisco, Juniper, Lucent/Ascend, HP ProCurve, Microsoft, USR/3Com, Acc/Newbridge. +* All known RADIUS Clients +* Flexible configurations using attribute pairs +* Supports virtual servers diff --git a/doc/antora/modules/concepts/pages/processing.adoc b/doc/antora/modules/concepts/pages/processing.adoc index 4e37c2c47ab9..f4e7a526c308 100644 --- a/doc/antora/modules/concepts/pages/processing.adoc +++ b/doc/antora/modules/concepts/pages/processing.adoc @@ -1,5 +1,6 @@ -= RADIUS Concepts += Processing +Get this diagram or redo ![FreeRADIUS flow diagram](request_flow.svg "Railroad diagram") Users new to RADIUS, EAP or AAA in general are encouraged to read the following standards: @@ -17,7 +18,6 @@ This should provide a solid foundation in RADIUS and EAP at a protocol level. The client sends the server a RADIUS authentication request. You don't decide what's in the request, the client does. The server doesn't decide what's in the request, the client does. The client is 100% responsible for everything in the request. - == Picking an Auth-Type - authorize {} The radius server looks at the request and says: diff --git a/doc/antora/modules/concepts/pages/resources.adoc b/doc/antora/modules/concepts/pages/resources.adoc new file mode 100644 index 000000000000..dd3695a0c0ee --- /dev/null +++ b/doc/antora/modules/concepts/pages/resources.adoc @@ -0,0 +1,21 @@ += RESOURCES + +== Main sites + +https://www.freeradius.org/[FreeRADIUS] +https://www.inkbridgenetworks.com/[Inkbridge Networks] +https://www.iana.org/assignments/radius-types/radius-types.xhtml[RADIUS Packet Types] + +== RFCs + +https://datatracker.ietf.org/doc/html/rfc2865[RFC 2865] Remote Authentication Dial In User Service (RADIUS) +https://datatracker.ietf.org/doc/html/rfc2866[RFC 2866] RADIUS Accounting +https://datatracker.ietf.org/doc/html/rfc2867[RFC 2867] RADIUS Accounting Modifications for Tunnel Protocol Support +https://datatracker.ietf.org/doc/html/rfc2868[RFC 2868] RADIUS Attributes for Tunnel Protocol Support +https://datatracker.ietf.org/doc/html/rfc2869[RFC 2869] RADIUS Extensions + +https://datatracker.ietf.org/doc/html/rfc3758[RFC 3748] Extensible Authentication Protocol (EAP) +https://datatracker.ietf.org/doc/html/rfc3579[RFC 3579] - RADIUS (Remote Authentication Dial In User Service) Support For Extensible Authentication Protocol (EAP) + + + diff --git a/doc/antora/modules/developers/pages/index.adoc b/doc/antora/modules/developers/pages/index.adoc index 660c08d44673..9b9c9f309fb4 100644 --- a/doc/antora/modules/developers/pages/index.adoc +++ b/doc/antora/modules/developers/pages/index.adoc @@ -1,3 +1,4 @@ + = FreeRADIUS Development List with some usual howtos for FreeRADIUS. diff --git a/doc/antora/modules/howto/pages/troubleshoot.adoc b/doc/antora/modules/howto/pages/troubleshoot.adoc new file mode 100644 index 000000000000..2cac3438e92e --- /dev/null +++ b/doc/antora/modules/howto/pages/troubleshoot.adoc @@ -0,0 +1,70 @@ +# Troubleshooting + +## The server isn't starting. What should I do? + +Do the following: + +* Use sudo to switch to the root context. +* If the server starts correctly, the problem is the server is running as an unprivileged user. +* Log in as that user, and run it in debugging mode. Any errors or warnings will be appear on the monitor. + +## Why is the server is sending an Access-Reject message when the user should be accepted. + +Do the following to gather enough information to diagnose the problem: + +* Run the server in debugging mode and observe what happens when the user logs in. +* If the control socket is configured, run `raddebug -u USERNAME` to gather the same information from a running server. + +## The server is sending Access-Accept packets with some attributes, but the user is not getting the correct kind of service (or is getting rejected). Why? + +Check the NAS logs to determine why the NAS is ignoring instructions from the server. The NAS documentation outlines the attributes it needs to provide certain services. These attributes can sometimes +be in unusual formats, so be sure to consult the NAS documentation. + +##The accounting logs do not contain the information I want to see. How can I make the server log the correct information? + +A FreeRADIUS server can only log the information it receives. If the information isn't in the accounting packets, then it wasn’t sent by the NAS. + +## How can I restrict a users network access after authentication? + +Configure FreeRADIUS to send the appropriate filtering rules to the NAS. The NAS enforces these rules +after authentication. Consult the NAS documentation for the names and format of the attributes. There +are no accepted standards for these attributes, so be sure to consult the NAS documentation. + +## How can I configure a captive portal for users? + +Consult the NAS documentation on how to configure a captive portal. Each NAS requires different action. +Another option is to use an Open Source captive portal solution. FreeRADIUS only provides a Yes or No +response to authentication requests. FreeRADIUS does not act as a firewall to block network access and +does not support HTTP. + +## How can I disconnect a user after they have logged in? + +See the NAS documentation. If the specific NAS supports Disconnect-Request, you can use radclient +to send that packet. If the NAS doesn't support the Disconnect-Request, take the appropriate action specific to that particular +NAS. Some NASs support SNMP writes, while other NASs require the administrator to log into the NAS +console and forcibly reset the port. Refer to the specific NAS documentation for more details. + +## The server logs have many numerous messages about request timeout or blocked child. How can I fix this? + +These blockages generally occur because the server is using a database for authentication that is inactive +or slow. To solve this problem, increase the database’s response speed. As a rough guideline, if a query +takes more than a second, something is catastrophically wrong with the database. Possible solutions +include: + +* Add more indexes +* Adg more RAM +* Make sure that other systems are not accessing the database when FreeRADIUS needs to use it + +## How many authentications per second can the server handle? + +This is largely dependent on the CPU power of the host system, the type of database, and the authenti- +cation protocol. Typically, a new server with all users in memory and PAP authentication can do tens of thousands of authentications per second. +When using PEAP, the system can be CPU bound and may only do thousands of authentications per second. + +If the users are stored in a database, FreeRADIUS is limited to the speed of the database. For +example, a database that performs a thousand queries per second limits FreeRADIUS to the same number. + +## How many accounting packets per second can the server handle? +The host system’s CPU power and database determines how many accounting packets the server can +handle per second. If the database is limited to a thousand writes per second, the FreeRADIUS accounting +requests is also limited to a thousand writes per second. diff --git a/doc/antora/modules/reference/assets/images/request_flow.svg b/doc/antora/modules/reference/assets/images/request_flow.svg new file mode 100644 index 000000000000..2dccf5d82afe --- /dev/null +++ b/doc/antora/modules/reference/assets/images/request_flow.svg @@ -0,0 +1,3 @@ + + + Produced by OmniGraffle 6.2 2015-04-15 01:50:58 +0000Canvas 1Railroadmodule xmodule yserver {}Post-Proxy-Type Fail {}Authenticate {}module zAuth-Type z {}Listener proto aAuthor Arran Cudbard-BellCopyright 2014-2015 The FreeRADIUS projectCreative commons license CC BYAuth-Type y {}Auth-Type x {}Post-Proxy {}Listener proto aRequest flow FreeRADIUS 2.2.x-3.0.xPost-Auth-Type Reject {}Post-Auth {}Reject path is followed if the rcode set for a section when the request leaves, is not ok or updatedPre-Proxy-Type x {}Pre-Proxy-Type z {}Pre-Proxy-Type y {}Autz-Type a {}Autz-Type b {}Autz-Type c {}Pre-Proxy {}Authorize {} diff --git a/src/modules/rlm_couchbase/all.mk b/src/modules/rlm_couchbase/all.mk new file mode 100644 index 000000000000..bd75fe1ae603 --- /dev/null +++ b/src/modules/rlm_couchbase/all.mk @@ -0,0 +1,27 @@ +# This needs to be cleared explicitly, as the libfreeradius-json.mk +# might not always be available, and the TARGETNAME from the previous +# target may stick around. +TARGETNAME := +-include $(top_builddir)/src/lib/json/all.mk +TARGET := + +# Check the targetname defined by libfreeradius-json.mk +# to verify we have json-c and the libfreeradius-json library. +ifneq "$(TARGETNAME)" "" + TARGETNAME := + + # Check the targetname from the local configure script + ifneq "$(TARGETNAME)" "" + TARGET := $(TARGETNAME)$(L) + endif +endif + +SOURCES := $(TARGETNAME).c mod.c couchbase.c + +SRC_CFLAGS := +TGT_LDLIBS := +TGT_PREREQS := libfreeradius-json.a + +# TODO: create man page +#MAN := rlm_couchbase.8 +LOG_ID_LIB = 7