Skip to content
Permalink
Browse files

clarifications and cleanups

  • Loading branch information
alandekok committed Aug 22, 2019
1 parent 8edaae8 commit bcdea70b9ff4dafe6d776cfc8f20b4f74a55eda6
Showing with 151 additions and 62 deletions.
  1. +85 −7 doc/antora/modules/raddb/pages/format.adoc
  2. +66 −55 doc/antora/modules/raddb/pages/index.adoc
@@ -62,38 +62,44 @@ 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

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

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 <<Variable References>> 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
----
<name> [<instance>] {
[ statements ]
}
----

<name>:: The name of this configuration section. The set of allowed
names depends on the context.

<instance>:: 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 <filename>
-$INCLUDE <filename>
----

$INCLUDE:: Key word to load the *<filename>*, and to fail if the file does
not exist, or cannot be parsed

-$INCLUDE:: Key word to load the *<filename>*, and to silently do
nothing if the file does not exist. If the file does exist, this
keyword behaves exactly the same as `$INCLUDE`.

<filename>:: The filename to include
+
If *<filename>* 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 *<filename>* 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,37 +346,43 @@ using a `:` after the section reference. Currently `:name` and `:instance`
are supported.

.References to the Name of a Section
====
----
modules {
example foo {
file = ${.:name}
}
}
----
====

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 {
file = ${.:instance}
}
}
----
====

Will set variable `file` to the instance name of the containing
section, in this case `foo`.

.Combining References
====
----
modules {
example foo {
file = ${..:name}
}
}
----
====

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
@@ -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/` - <<mods-available/README.adoc#,Available modules>>, 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]

0 comments on commit bcdea70

Please sign in to comment.
You can’t perform that action at this time.