From: Alan T. DeKok Date: Thu, 22 Aug 2019 15:08:55 +0000 (-0400) Subject: clarifications and cleanups X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bcdea70b9ff4dafe6d776cfc8f20b4f74a55eda6;p=thirdparty%2Ffreeradius-server.git clarifications and cleanups --- diff --git a/doc/antora/modules/raddb/pages/format.adoc b/doc/antora/modules/raddb/pages/format.adoc index c598fa9701b..b82762b85b5 100644 --- a/doc/antora/modules/raddb/pages/format.adoc +++ b/doc/antora/modules/raddb/pages/format.adoc @@ -62,12 +62,14 @@ be interpreted as being in the correct format. For example, when a configuration variable is documented as taking an IP address, all of the following examples result in the same configuration: -.Examples +.Equivalent Configurations +==== ---- ipaddr = 192.0.2.2 ipaddr = '192.0.2.2' ipaddr = " 192.0.2.2" ---- +==== === Unquoted Strings @@ -75,13 +77,15 @@ Unquoted strings delimited by spaces, or by other tokens. This unquoted text is interpreted as a simple string and are generally equivalent to placing the string in single quotes. -.Examples +.Unquoted Strings +==== ---- ipaddr = 192.168.0.2 delay = 1 locking = yes filename = /path/ ---- +==== === Single-Quoted Strings @@ -89,11 +93,13 @@ A single-quoted string allow it to contain spaces, among other special characters. The single quote character can be placed in such a string by escaping it with a backslash. -.Examples +.Single-Quoted Strings +==== ---- message = 'Hello there' filter = 'yes \` is allowed` ---- +==== === Double-Quoted Strings @@ -108,6 +114,14 @@ see the <> section for more information. The contents of a double-quoted can be interpreted as a string, a number, or an IP address, depending on the configuration varible. +.Double-Quoted Strings +==== +---- +message = "Hello there" +filter = "yes \" is allowed" +---- +==== + === Escape sequences Escape sequences in double-quoted strings allow characters which may @@ -136,6 +150,22 @@ A configuration section begins with a section name, followed on the same line by an open bracket `{`. A section ends with a close bracket `}`. +.Syntax +---- + [] { + [ statements ] +} +---- + +:: The name of this configuration section. The set of allowed +names depends on the context. + +:: An optional secton name. + +[ statements ]:: Zero or more statements, including comments, variable +assignments, and other sections. + + .Configuration Section ==== ---- @@ -191,7 +221,44 @@ This example will set the value of the variable `foo` to `blah blah blah`. Any CR or LF is not turned into a space, but all other whitespace is preserved in the final value. -=== Contents of the Configuration Files +=== Including other files + +As noted above, the configuration is logically one global "server +configuration", but is split up into multiple files on disk. This +splitting is done by the use of a `$INCLUDE` statement. + +.Syntax +---- +$INCLUDE +-$INCLUDE +---- + +$INCLUDE:: Key word to load the **, and to fail if the file does +not exist, or cannot be parsed + +-$INCLUDE:: Key word to load the **, and to silently do +nothing if the file does not exist. If the file does exist, this +keyword behaves exactly the same as `$INCLUDE`. + +:: The filename to include ++ +If ** begins with a `/` character, then it is +assumed to be a full path to the file, starting at the "root" +directory of the file system. ++ +If ** does not begin with a `/` character, then it is +assumed to be a path relative to the current file being read. + + +.Including other files +==== +---- +foo = bar +$INCLUDE other.conf +---- +==== + +=== Configuration as a Database The configuration file parser is independent of the server configuration. This means that you can put almost anything into the @@ -226,9 +293,7 @@ examples. ==== ---- foo = bar # set variable 'foo' to value 'bar' - who = ${foo} # sets variable 'who' to value of variable 'foo' - my = "${foo} a" # sets variable 'my' to "bar a" ---- ==== @@ -241,13 +306,16 @@ Relative references are allowed, by prepending the name with one or more periods. .References in the Current Section +==== ---- foo = bar blogs = ${.foo} # set 'blogs' to 'bar' ergo = "${foo}" # set 'ergo' to 'bar' ---- +==== .Parent References +==== ---- group { foo = bar @@ -256,15 +324,18 @@ group { } } ---- +==== Will set variable `blogs` to the value `bar`. That value is taken from the variable `foo`, which is contained in the a parent section of the section containing `blogs` .References to Other Sections +==== ---- blogs = ${modules.detail.filename} ---- +==== Will set variable `blogs` to the value of variable `filename`, of the `detail` module, which is in the `modules` section of the @@ -275,6 +346,7 @@ using a `:` after the section reference. Currently `:name` and `:instance` are supported. .References to the Name of a Section +==== ---- modules { example foo { @@ -282,11 +354,13 @@ modules { } } ---- +==== Will set variable `file` to the name of the containing section, in this case, `example`. .References to the Instance of a Section +==== ---- modules { example foo { @@ -294,11 +368,13 @@ modules { } } ---- +==== Will set variable `file` to the instance name of the containing section, in this case `foo`. .Combining References +==== ---- modules { example foo { @@ -306,6 +382,7 @@ modules { } } ---- +==== Will set variable `file` to the name of the parent of the containing section, in this case `modules`. @@ -314,11 +391,12 @@ A string can contain multiple references, which will all be expanded. .Multiple References +==== ---- foo = bar baz = bug blogs = "this ${foo} is ${baz}" ---- +==== Will set variable `blogs` to the string `this bar is bug`. -x \ No newline at end of file diff --git a/doc/antora/modules/raddb/pages/index.adoc b/doc/antora/modules/raddb/pages/index.adoc index 2f0e1e96d37..81b17b42139 100644 --- a/doc/antora/modules/raddb/pages/index.adoc +++ b/doc/antora/modules/raddb/pages/index.adoc @@ -1,56 +1,39 @@ -= Welcome to Version 4.0 of FreeRADIUS += Configuration Files This section documents the format and content of the configuration files. -== Configuring the server +== Format and Layout -When configuring the server, please start with the default -configuration. It is intended to work in the widest possible -circumstances, with minimal site-local changes. Most sites can just -configure a few modules such as `ldap` and `sql`, and the server -will do everything you need. More complex configurations require more -effort, of course. - -For more complex configurations, the best approach is to make a series -of small changes. Start the server after every change via -`radiusd -XC` to see if the configuration is OK. Use `radclient` to -send the server test packets. Read the debug output (`radiusd -X`) to -verify that the server is doing what you expect. +The configuration files are in a simple text-based +xref:format.adoc[format]. They are loaded once when the server +starts, and then are static for the duration of the server. Changes +to the configuration file are picked up only when the server restarts. -For complex policies, it is best to write down what you want in plain -English. Be specific. Write down what the server receives in a packet, -which databases are used, and what the database should return. The more -detailed these explanations, the easier it will be to create a working -configuration. +The configuration files are organized into groups, generally by +directory, as discussed below. -Take your time. It is better to make small incrementatal progress, than -to make massive changes, and then to spend weeks debugging it. - -== Organization +=== radiusd.conf -The files in this directory are organized into logical groups, as -follows. +The xref:radiusd.conf.adoc[radiusd.conf] file is the main server +configuration file. When the server starts, it reads this file. This +file then loads all of the other configuration files. -* `mods-available/` - <>, with example configuration. -* `mods-enabled/` - Enabled modules that are being used by FreeRADIUS. -* `sites-available/` - xref:raddb:sites-available/index.adoc[Available virtual servers], with example configuration. -* `sites-enabled/` - Enabled virtual servers that are being used by FreeRADIUS. -* `policy.d/` - example and live policies which implement standard rules and checks. -* `certs/` - Certificiates for EAP and for RADIUS over TLS. +=== dictionary -The directories are descrived in more detail below. +Site-local dictionary entries are placed in the +xref:dictionary.adoc[dictionary] file. === `mods-available/` -The `mods-available/` directory contains configuration for all of the -available modules. Each module configuration is different. Each file -contains documentation that describes what the module is, and how it -works. +The xref:mods-available/index.adoc[mods-available/] directory contains +configuration for all of the available modules. Each module +configuration is different. Each file contains documentation that +describes what the module is, and how it works. -The directory contains almost 100 modules. Most configurations will only -use a few modules. The rest exist in order to serve as documentation and -worked examples. +The directory contains almost 100 modules. Most configurations will +only use a few modules. The remaining module configurations exist in +order to serve as documentation and worked examples. === `mods-enabled/` @@ -94,14 +77,18 @@ policies are loaded by the server, and unused ones are ignored. === `sites-available/` The `sites-available/` directory contains virtual servers which -process packets. They are similar to the virtual servers used by Apache -or Nginx. +process packets. They are similar in concept to the virtual servers +used by Apache and Nginx. -Each virtual server will begin with a `server` declaration, along with it’s name. e.g. `server default { ...`. The declaration is then followed by a `namespace =` -parameter, which describes which application protocol is being used in that virtual server. +Each virtual server will begin with a `server` declaration, along with +it’s name. e.g. `server default { ...`. The declaration is then +followed by a `namespace =` parameter, which describes which +application protocol is being used in that virtual server. e.g. `namespace = radius`. -The virtual server will then contain zero or more `listen` subsections. Each `listen` subsection defines a network socket which is used to receive packets. +The virtual server will then contain zero or more `listen` +subsections. Each `listen` subsection defines a network socket which +is used to receive packets. The virtual server will then contain multiple `recv { ... }` and `send { ... }` subsections. These subsections are used to process packets. @@ -135,16 +122,40 @@ The standard installation of FreeRADIUS enables only a few virtual servers. === `certs/` -This directory contains certificates and configuration for EAP and RADIUS over TLS (i.e. RadSec). +This directory contains certificates and configuration for EAP and +RADIUS over TLS (i.e. RadSec). + +== Additional Configuration Files + +* xref:clients.conf.adoc[clients.conf] +* xref:debug.conf.adoc[debug.conf] +* xref:experimental.conf.adoc[experimental.conf] +* xref:panic.gdb.adoc[panic.gdb] +* xref:radrelay.conf.adoc[radrelay.conf] +* xref:templates.conf.adoc[templates.conf] +* xref:trigger.conf.adoc[trigger.conf] -== List of config files +== Changing the Configuration + +When configuring the server, please start with the default +configuration. It is intended to work in the widest possible +circumstances, with minimal site-local changes. Most sites can just +configure a few modules such as `ldap` and `sql`, and the server +will do everything you need. More complex configurations require more +effort, of course. + +For more complex configurations, the best approach is to make a series +of small changes. Start the server after every change via +`radiusd -XC` to see if the configuration is OK. Use `radclient` to +send the server test packets. Read the debug output (`radiusd -X`) to +verify that the server is doing what you expect. + +For complex policies, it is best to write down what you want in plain +English. Be specific. Write down what the server receives in a packet, +which databases are used, and what the database should return. The more +detailed these explanations, the easier it will be to create a working +configuration. + +Take your time. It is better to make small incrementatal progress, than +to make massive changes, and then to spend weeks debugging it. -* xref:raddb:clients.conf.adoc[clients.conf] -* xref:raddb:debug.conf.adoc[debug.conf] -* xref:raddb:dictionary.adoc[dictionary] -* xref:raddb:experimental.conf.adoc[experimental.conf] -* xref:raddb:panic.gdb.adoc[panic.gdb] -* xref:raddb:radiusd.conf.adoc[radiusd.conf] -* xref:raddb:radrelay.conf.adoc[radrelay.conf] -* xref:raddb:templates.conf.adoc[templates.conf] -* xref:raddb:trigger.conf.adoc[trigger.conf]