From: Alan T. DeKok Date: Tue, 21 Feb 2023 19:16:30 +0000 (-0500) Subject: Start of documentation on creating and debugging complex policies. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e7ebe0eba28764ca0010daa1f9d1b622b7af5dcb;p=thirdparty%2Ffreeradius-server.git Start of documentation on creating and debugging complex policies. --- diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index 05acd69fac5..7d53b2f2d3c 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -66,12 +66,6 @@ *** xref:xlat/attribute.adoc[Attribute References] *** xref:xlat/module.adoc[Module References] -** xref:man/index.adoc["man" pages] -*** xref:man/radclient.adoc[radclient] -*** xref:man/radiusd.adoc[radiusd] -*** xref:man/radmin.adoc[radmin] -*** xref:man/radsniff.adoc[radsniff] - ** xref:dictionary/index.adoc[Dictionaries] *** xref:dictionary/alias.adoc[ALIAS] *** xref:dictionary/attribute.adoc[ATTRIBUTE] @@ -90,3 +84,12 @@ *** xref:dictionary/end-tlv.adoc[END-TLV] *** xref:dictionary/begin-vendor.adoc[BEGIN-VENDOR] *** xref:dictionary/end-vendor.adoc[END-VENDOR] + +** xref:policy/index.adoc[Policies] +*** xref:policy/different.adoc[Why FreeRADIUS is different] + +** xref:man/index.adoc["man" pages] +*** xref:man/radclient.adoc[radclient] +*** xref:man/radiusd.adoc[radiusd] +*** xref:man/radmin.adoc[radmin] +*** xref:man/radsniff.adoc[radsniff] diff --git a/doc/antora/modules/reference/pages/dictionary/index.adoc b/doc/antora/modules/reference/pages/dictionary/index.adoc index e3efc82329c..4be2f8f4c1b 100644 --- a/doc/antora/modules/reference/pages/dictionary/index.adoc +++ b/doc/antora/modules/reference/pages/dictionary/index.adoc @@ -160,3 +160,7 @@ The following keywords still XXX | xref:dictionary/begin-vendor.adoc[BEGIN-VENDOR] | Begin defining vendor-specific attributes | xref:dictionary/end-vendor.adoc[END-VENDOR] | End defining vendor-specific attributes |===== + + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// Development of this documentation was sponsored by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/policy/different.adoc b/doc/antora/modules/reference/pages/policy/different.adoc new file mode 100644 index 00000000000..7746c4d6211 --- /dev/null +++ b/doc/antora/modules/reference/pages/policy/different.adoc @@ -0,0 +1,75 @@ += Why FreeRADIUS is different + +The creation of policies is what makes FreeRADIUS different from other +products just as DNS or DHCP servers. With some artistic license, we +can say that those products are much simpler to configure than +FreeRADIUS. + +This simplicity comes not from the choice of implementation, where +those products have chosen to make themselves easy to configure, and +FreeRADIUS has chosen to be difficult. Instead, the simplicity comes +largely from how the protocols work. + +If we over-simplify DNS, we can say that the bulk of DNS traffic is +queries like "please tell me the IP address of `google.com` ", with +responses containing addresses such as `8.8.8.8`. For those +situations, a simple configuration format is best. A DNS "zone" file +can contain a simple mapping between names and IP addresses. That +mapping can then serve the needs of most users. + +Similar arguments can be made for DHCP. Most DHCP queries are of the +form "here's my MAC, can I please get an IP address?". The responses +are then "here's your IP, gateway, netmask, and expiry time". A DHCP +configuration file can then be little more than defining a range of +IPs, along with associated gateway and netmask. + +This is not to say that all DNS and DHCP configuration is trivial, +it's not. The protocols can be complicated, which leads to complex +configurations. However, the bulk of what most people want to do is +relatively simple. + +That is not always the case for RADIUS. + +With RADIUS, it is true that basic configuration is simple. For +example, policies such as "I have users in LDAP, and I want +authenticated users to access the network". For this policy, the +administrator configures the xref:raddb:mods-available/ldap.adoc[LDAP] +module, adds some xref:raddb:clients.conf.adoc[client] definitions, +and _everything just works_. + +The problem comes when people need policies like "allow users onto the +network for six hours, except for alternate Tuesdays between 9am and +5pm, where they can get on the network for 8 hours". While this +example is contrived, the underlying complexity is realistic. + +This last piece is what makes FreeRADIUS difficult to configure. The +issue is not FreeRADIUS, the complexity comes from the differences in +_configuration styles_. + +For DNS, DHCP, and simple RADIUS policies, the configuration is +*declarative*. + +A declarative configuration is where you declare what you want, such +as "`google.com` has IP address `8.8.8.8`", and the server just "does +the right thing". There is no need to design complex policies, the +declaration that `google.com==8.8.8.8` is enough for the server to +know what to do. + +For complex RADIUS policies, the configuration is *procedural*. + +i.e. programming. + +Outside of esoteric languages and research projects, it is not +possible to simply "declare" what you want, and have the computer +"figure it out". Even if that does work, the solution may be +inefficient and therefore unusable. Or the effort required to create +a complex "declaration" may be no easier then effort required to +simply program a procedural solution. + +In the end, the difficulty of configuring FreeRADIUS comes in part +from the procedural nature of the `unlang` configuration language. +The remainder of the difficulty is almost always because of poorly +specified requirements. + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// Development of this documentation was sponsored by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/policy/index.adoc b/doc/antora/modules/reference/pages/policy/index.adoc new file mode 100644 index 00000000000..212d92609e2 --- /dev/null +++ b/doc/antora/modules/reference/pages/policy/index.adoc @@ -0,0 +1,131 @@ += Policies + +The core functionality of the server is implemented in _policies_. +These policies are written in `unlang`. In addition to documenting +the default policies, this section describes how and why to write good +policies. + +== Concepts versus Configuration + +A common concern around FreeRADIUS is that the learning curve is not +just steep, it is a cliff. The "cliff" means that some simple things are very +simple to do, but anything more complex is extremely difficult. + +While FreeRADIUS can be complex, we believe that the reason for this +difficulty is related to the _creation of policies_, and not (so much) +in the difficulty of _configuring the server_. + +In other words, once you know what you want to do, the problem is +limited to "How do I make FreeRADIUS do X?" If you don't know what +you want to do, then you are left staring at the FreeRADIUS +configuration, and wondering "What magic flag do I set to make +FreeRADIUS do what I want?" + +In the end, there is no magic flag. Once you understand _conceptually_ +what you want to do, then _configuring_ the server is a much more +straightforward process. + +== The only working process to configure FreeRADIUS + +The process for configuring FreeRADIUS should follow the steps below: + +1. *Find out what you have, and write it down.* ++ +For example, read the debug output to see what is in the RADIUS +packets. What information is there? What information is missing? ++ +Write down where user information will be taken from, or where +accounting data will be stored. ++ +Write down information about the network. What are the RADIUS clients +and their IP addresses andshared secrets. What are the databases, and +credentials needed to access them. ++ +This information is the basic facts you will use to build the +FreeRADIUS policies. + +2. *Write down what you want FreeRADIUS to do in plain English.* ++ +For example, "When the user comes in, the server should look up the +password in LDAP. If the password matches, the user gets accepted. +If the password does not match, the user is rejected." ++ +Mark up those sentences with the bits of information from step (1). +Does the RADIUS packet contain a "password" for the user? If so, +where is it? Where is the LDAP database? How does FreeRADIUS connect +to the database? What credentials does it use to connect to the +database? ++ +These descriptions will form the basis for `unlang` policies. + +3. *A little bit at a time, convert the English statements to `unlang`.* ++ +The important piece of information here is not "convert to `unlang`", +but instead "take it a step at a time". ++ +Convert one piece to `unlang`, and make sure you understand what it's +supposed to do, and what you expect the result will be. + +4. *Test it.* ++ +Test that the change does what you expect. If it the change works, great. ++ +If the change does not work, then read the debug output to see what +happened. Ask yourself some questions. Is the server missing +information which it needs to make a decision? What errors does the +server produce? Were your assumptions wrong? What can you learn from +what the server is doing? ++ +Then go back to step (1) for this portion of the policy. Update the +information you have, and double-check the English statements you +wrote. Check that those statements were translated correctly into +`unlang`. ++ +Also test that _previous_ configurations still work! Sometimes +changing one thing will break something else. + +5. *If the configuration works, save a copy.* ++ +Saving a copy of the configuration means that you can always revert +the your changes to a "known working" version. It doesn't matter how +the files are saved. You cna use a revision control system like +`git`, or `tar` files, or even just copying the files to a different +directory (named for the current time/date). ++ +If you don't save a copy of the working configuration, then it is +possible to spend hours of time creating something works, only to have +it stop working after a few more changes. You then have no idea what +was changed, and what change broke the configuration. ++ +If you do save a copy of the working configuration, then if a change +breaks anything, you can just throw away that change and revert to a +"known working" system. It is better to fix issues by reverting bugs, +rather than trying to debug complex systems at 2am, on a production +machine! ++ +When the entire configuration works, you should also save a copy +remotely, on another machine. + +While this process may sound heavy-weight, it is much simpler than +randomly poking the server until it works. The "just bash at it" +approach can seem productive for simple configurations and short +periods of time. However, it is guaranteed to be a massive time sink +(and waste of time) for complex configurations. + +== Required Concepts + +The first concept to understand in creating policies is why +xref:policy/different.adoc[FreeRADIUS is different] from other +networking programs. The summary is that most other networking +programs use a _declarative_ configuration, as in a web server "pages +under `~user` are served from directory `/home/user/public_html` ". +In contrast, complex policies are _procedural_, which is programming, +with all the difficulties of designing and debugging complex "if / +then / else" statements. + +The second concept to understand in creating policies is that a +methodical approach is critical. + + +// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// Development of this documentation was sponsored by Network RADIUS SAS.