From: nolade Date: Wed, 6 Aug 2025 16:39:10 +0000 (-0400) Subject: docs: Reference landing page Updates PR #5678 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1772ce550bb1f06fa0ffeca676f00eb2190d58d9;p=thirdparty%2Ffreeradius-server.git docs: Reference landing page Updates PR #5678 --- diff --git a/doc/antora/modules/reference/nav.adoc b/doc/antora/modules/reference/nav.adoc index acef07d9c5a..a934a9a767c 100644 --- a/doc/antora/modules/reference/nav.adoc +++ b/doc/antora/modules/reference/nav.adoc @@ -1,9 +1,7 @@ * xref:index.adoc[Reference Documentation] ** xref:unlang/index.adoc[Unlang Policy Language] - *** xref:unlang/interpreter.adoc[Interpreter] - *** xref:unlang/keywords.adoc[Keywords] **** xref:unlang/break.adoc[break] **** xref:unlang/call.adoc[call] @@ -65,10 +63,10 @@ *** xref:type/numb.adoc[Numbers] *** xref:type/string/single.adoc[Single Quoted Strings] *** xref:type/string/double.adoc[Double Quoted Strings] -*** xref:type/string/backticks.adoc[Backtick Quoted String] +*** xref:type/string/backticks.adoc[Backtick Quoted Strings] *** xref:type/string/unquoted.adoc[Unquoted Strings] -** xref:xlat/index.adoc[Dynamic Expansion] +** xref:xlat/index.adoc[Dynamic Expansions] *** xref:xlat/all.adoc[Summary of Built-in Functions] *** xref:xlat/alternation.adoc[Alternation Syntax] *** xref:xlat/attribute.adoc[Attribute References] @@ -140,15 +138,6 @@ *** xref:dictionary/begin-vendor.adoc[BEGIN-VENDOR] *** xref:dictionary/end-vendor.adoc[END-VENDOR] -** xref:policy/index.adoc[Create Policy Rules] -*** 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] - ** xref:raddb/index.adoc[Configuration Files] *** xref:raddb/format.adoc[Format of the Configuration Files] *** xref:raddb/certs/index.adoc[Certificates] @@ -156,9 +145,9 @@ **** xref:raddb/global.d/ldap.adoc[Ldap] **** xref:raddb/global.d/python.adoc[Python] + ** xref:raddb/mods-available/index.adoc[Modules] *** xref:raddb/mods-available/all_modules.adoc[Summary of Modules] - *** xref:raddb/mods-available/doc/authentication.adoc[Authentication] **** xref:raddb/mods-available/chap.adoc[CHAP module] **** xref:raddb/mods-available/crl.adoc[CRL] @@ -178,7 +167,7 @@ **** xref:raddb/mods-available/winbind.adoc[Winbind] **** xref:raddb/mods-available/yubikey.adoc[Yubikey] -*** xref:raddb/mods-available/doc/datastore.adoc[Datastore] +*** xref:raddb/mods-available/doc/datastore.adoc[Datastores] **** xref:raddb/mods-available/cache.adoc[Cache] ***** xref:raddb/mods-available/cache_eap.adoc[Cache EAP] ***** xref:raddb/mods-available/cache_tls.adoc[Cache TLS Session] @@ -227,13 +216,14 @@ ***** xref:raddb/mods-available/detail.example.com.adoc[Example] ***** xref:raddb/mods-available/detail.log.adoc[Log Example] + *** xref:raddb/mods-available/doc/policy.adoc[Policy] **** xref:raddb/mods-available/always.adoc[Always] **** xref:raddb/mods-available/attr_filter.adoc[Attr_filter] **** xref:raddb/mods-available/idn.adoc[IDN] **** xref:raddb/mods-available/sometimes.adoc[Sometimes] -*** xref:raddb/mods-available/doc/protocol.adoc[Protocol] +*** xref:raddb/mods-available/doc/protocol.adoc[Protocols] **** xref:raddb/mods-available/dhcpv4.adoc[DHCPv4] ***** xref:raddb/mods-available/isc_dhcp.adoc[ISC DHCP] **** xref:raddb/mods-available/radius.adoc[RADIUS] @@ -246,9 +236,12 @@ **** xref:raddb/mods-available/stats.adoc[Stats] **** xref:raddb/mods-available/unbound.adoc[Unbound] + ** xref:raddb/policy.d/index.adoc[Policies] -*** xref:raddb/policy.d/at_reference.adoc[@policy] -*** xref:raddb/policy.d/method.adoc[Method Override] +*** xref:policy/index.adoc[Create Policy Rules] +**** xref:policy/different.adoc[Why FreeRADIUS is different] +**** xref:raddb/policy.d/at_reference.adoc[@policy] +**** xref:raddb/policy.d/method.adoc[Method Override] ** xref:raddb/sites-available/index.adoc[Virtual Servers] *** xref:raddb/sites-available/arp.adoc[ARP] @@ -283,12 +276,21 @@ **** xref:raddb/sites-available/dynamic-clients.adoc[Dynamic Clients] *** xref:raddb/clients.conf.adoc[Clients] -*** xref:raddb/debug.conf.adoc[Debugging Configuration] +*** xref:raddb/debug.conf.adoc[Debugging Configuration File] *** xref:raddb/dictionary.adoc[Local Dictionary Definitions] *** xref:raddb/radrelay.conf.adoc[Radrelay Configuration] *** xref:raddb/radiusd.conf.adoc[Server Configuration File] *** xref:raddb/templates.conf.adoc[Templates] *** xref:raddb/trigger.conf.adoc[Triggers] + +** xref:man/index.adoc[Man Pages] +*** xref:man/dictionary.adoc[dictionary] +*** xref:man/radclient.adoc[radclient] +*** xref:man/radiusd.adoc[radiusd] +*** xref:man/radmin.adoc[radmin] +*** xref:man/radsniff.adoc[radsniff] +*** xref:man/unlang.adoc[unlang] + // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/dictionary/index.adoc b/doc/antora/modules/reference/pages/dictionary/index.adoc index b9c38bc1336..eb5bd68e368 100644 --- a/doc/antora/modules/reference/pages/dictionary/index.adoc +++ b/doc/antora/modules/reference/pages/dictionary/index.adoc @@ -1,4 +1,4 @@ -== Dictionaries += Dictionaries The `dictionary` files define names, numbers, and xref:type/index.adoc[data types] for use in the server. In general, @@ -78,13 +78,13 @@ Vendors can submit new dictionaries to us via mailto:dictionary@freeradius.org[email], or via https://github.com/FreeRADIUS/freeradius-server/[GitHub]. -=== Names are Case-insensitive +=== Names are case-insensitive When names are printed, they are printed as the name given in the dictionaries. When a name is looked up in the dictionaries, the lookup is done in a case-insensitive manner. -=== Names are Hierarchical +=== Names are hierarchical In earlier versions of FreeRADIUS, the names were global. The global names for attributes caused issue with implementations, as noted in diff --git a/doc/antora/modules/reference/pages/index.adoc b/doc/antora/modules/reference/pages/index.adoc index c1376da109a..5ea6a1d6fd6 100644 --- a/doc/antora/modules/reference/pages/index.adoc +++ b/doc/antora/modules/reference/pages/index.adoc @@ -1,36 +1,48 @@ = Reference Documentation -There are small number of high-level concepts associated with the server, as outlined below. - -* xref:unlang/index.adoc[Unlang] syntax -* xref:reference:raddb/index.adoc[Configuration Files] -* xref:dictionary/index.adoc[Dictionary] where attribute names and data types are defined -* xref:type/index.adoc[Data Types] in the server -* xref:xlat/index.adoc[Dynamic expansions] i.e. "xlat"s. - -The server includes a large number of -xref:reference:raddb/index.adoc[configuration files]. These files are -automatically converted to HTML for the on-line documentation. - -During normal operation, the server receives packets of information -from the network. Data in the packets is usually encoded in -pre-defined "attributes" (RADIUS), or "options" (DHCP). The -definitions are loaded from xref:dictionary/index.adoc[dictionary] -files. +This comprehensive reference documents all aspects of the unlang syntax and its features. These details help the readers’ understanding and use of the configuration language. Additionally, the FreeRADIUS configuration is organised into directories for modules, virtual servers, and policies. To enable specific modules or virtual servers, create symbolic links in the mods-enabled and sites-enabled directories. This hierarchy ensures clarity and manageability during setup. The man pages offer a quick way to look up functionality and options, serving as a handy reference for administrators. + +== xref:unlang/index.adoc[Unlang Policy Language] + +The full syntax of unlang is described in this section. Packets are processed via the xref:unlang/index.adoc[Unlang Policy Language], also referred to as xref:unlang/index.adoc[unlang]. Policies allow the server to read information in databases, perform if / then / else checks, add content to replies, along with many other actions. -These definitions are strongly typed. That is, each attribute has a +== xref:type/index.adoc[Data Types] + +Many data type definitions are packaged in the FreeRADIUS server. These definitions are strongly typed. That is, each attribute has a pre-defined xref:type/index.adoc[data type]. For example, an attribute "Framed-IP-Address" has data type xref:type/ip.adoc[ipaddr]. -Packets are processed via the xref:unlang/index.adoc[Unlang] policy -language. Policies allow the server to read information in databases, -perform if / then / else checks, add content to replies, along with -many other actions. +== xref:xlat/index.adoc[Dynamic Expansions] + +Dynamic expansions may also be referred to as "xlats" for historical reasons.When processing packets, it's possible to call functions or do string +manipulation with attribute contents. The xref:xlat/index.adoc[dynamic expansion] documentation describes how this is done. + +== xref:dictionary/index.adoc[Dictionaries] + +Where attribute names and data types are defined. During normal operation, the server receives packets of information from the network. Data in the packets is usually encoded in pre-defined "attributes" (RADIUS), or "options" (DHCP). The definitions are loaded from xref:dictionary/index.adoc[dictionary] +files. + +== xref:reference:raddb/index.adoc[Configuration Files] + +The server includes a large number of xref:reference:raddb/index.adoc[configuration files]. These files are automatically converted to HTML for the on-line documentation. + +== xref:raddb/mods-available/index.adoc[Modules] + +The FreeRADIUS server uses modules to manage different functions and tasks. Most of the xref:raddb/mods-available/index.adoc[modules] are enabled ensuring compatibility with most authentication protocols. FreeRADIUS supports conditional module loading, enhancing flexibility and configuration management. + +== xref:raddb/mods-available/doc/policy.adoc[Policies] + +Contains policies, written in unlang, that determine how the server processes messages. For example, policy.d/debug determines what information to print to the terminal when the server is run in debug mode. >It’s important to note that the policy.d directory is not the only place containing policies. Policies are anything written in Unlang, throughout the configuration files, which describes how data should be processed as it flows through the processing sections. + +== xref:raddb/sites-available/index.adoc[Virtual Servers] + +Describes how configuration files are used to manage virtual servers in FreeRADIUS. Each virtual server has its own configuration file, ensuring settings organized and easy to manage. FreeRADIUS provides default configurations for over 30 virtual servers, giving users a wide range of ready-to-use examples and templates. + +== xref:man/index.adoc[Man Pages] + +These man pages are for quick reference and maintaining compatibility over time. You can type `man radiusd` on the command line to access the same information. The man pages offer concise summaries of their features. + -When processing packets, it's possible to call functions or do string -manipulation with attribute contents. The -xref:xlat/index.adoc[dynamic expansion] documentation describes how -this is done. // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/man/index.adoc b/doc/antora/modules/reference/pages/man/index.adoc index 7c59f77a05d..1bb33719157 100644 --- a/doc/antora/modules/reference/pages/man/index.adoc +++ b/doc/antora/modules/reference/pages/man/index.adoc @@ -1,4 +1,4 @@ -= Man pages += Man Pages These `man` pages are provided for quick reference, and for historical compatibility. In some cases, it is easier to type `man radiusd` than @@ -8,6 +8,8 @@ That being said, the 'man' pages provide only brief summaries of functionality. The main documentation pages provide for significantly more content and explanation. +The format of the xref:man/dictionary.adoc[dictionary] files. + The xref:man/radclient.adoc[radclient] program. The main xref:man/radiusd.adoc[radiusd] server. @@ -18,7 +20,7 @@ A RADIUS-aware packet capture tool, xref:man/radsniff.adoc[radsniff]. A simple summary of xref:man/unlang.adoc[unlang]. -The format of the xref:man/dictionary.adoc[dictionary] files. + // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/reference/pages/policy/index.adoc b/doc/antora/modules/reference/pages/policy/index.adoc index f5a1cfa6b1d..c4f54651de8 100644 --- a/doc/antora/modules/reference/pages/policy/index.adoc +++ b/doc/antora/modules/reference/pages/policy/index.adoc @@ -1,6 +1,6 @@ = Policies -The core functionality of the server is implemented in _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. diff --git a/doc/antora/modules/reference/pages/raddb/policy.d/index.adoc b/doc/antora/modules/reference/pages/raddb/policy.d/index.adoc index edc4417594c..2c6bc6b6c15 100644 --- a/doc/antora/modules/reference/pages/raddb/policy.d/index.adoc +++ b/doc/antora/modules/reference/pages/raddb/policy.d/index.adoc @@ -1,3 +1,14 @@ # Policies -TBD +FreeRADIUS includes a powerful and advanced policy language. Policies can be run at any stage during the handling of a request: + +* before authentication +* during authentication +* after authentication +* during accounting + +Policies can be based on any attribute in a request or response, include checking both the existence of (or lack of) an attribute, and the contents of an attribute. They can filter out attributes, or re-write the contents of attributes. + +Attributes can be created, deleted, or edited in a policy. Policies can leverage information in SQL, LDAP, flat-text files, or any other source of data. + +Policies can be based on identities (user, group, or role), location (client IP, port, etc.), time (date, time of day), authentication method (PAP, CHAP, MS-CHAP, EAP type, etc.), or any other piece of information that is in a RADIUS packet or in a database. Policies can enforce VLAN capabilities, filtering QoS, etc. diff --git a/doc/antora/modules/reference/pages/xlat/index.adoc b/doc/antora/modules/reference/pages/xlat/index.adoc index e02d6898b21..ece2f87115b 100644 --- a/doc/antora/modules/reference/pages/xlat/index.adoc +++ b/doc/antora/modules/reference/pages/xlat/index.adoc @@ -1,4 +1,4 @@ -= Dynamic Expansion += Dynamic Expansions Dynamic expansion is a feature that allows values to be dynamically expanded at run time. For historical reasons, these string expansions diff --git a/man/man5/dictionary.5 b/man/man5/dictionary.5 index b8b64f2c072..10cc1c9e65d 100644 --- a/man/man5/dictionary.5 +++ b/man/man5/dictionary.5 @@ -107,12 +107,12 @@ Vendors can submit new dictionaries to us via .MTO "dictionary\(atfreeradius.org" "email" "," or via .URL "https://github.com/FreeRADIUS/freeradius\-server/" "GitHub" "." -.SS "Names are Case\-insensitive" +.SS "Names are case\-insensitive" .sp When names are printed, they are printed as the name given in the dictionaries. When a name is looked up in the dictionaries, the lookup is done in a case\-insensitive manner. -.SS "Names are Hierarchical" +.SS "Names are hierarchical" .sp In earlier versions of FreeRADIUS, the names were global. The global names for attributes caused issue with implementations, as noted in @@ -328,4 +328,4 @@ The FreeRADIUS Server Project (\c .URL "https://freeradius.org" "" ")" .SH "AUTHOR" .sp -Alan DeKok \ No newline at end of file +Alan DeKok