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 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
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
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
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
====
----
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
====
----
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"
----
====
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
}
}
----
+====
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
are supported.
.References to the Name of a Section
+====
----
modules {
example foo {
}
}
----
+====
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 {
}
}
----
+====
Will set variable `file` to the instance name of the containing
section, in this case `foo`.
.Combining References
+====
----
modules {
example foo {
}
}
----
+====
Will set variable `file` to the name of the parent of the containing
section, in this case `modules`.
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
-= 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/`
=== `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.
=== `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]
projects / thirdparty / freeradius-server.git / commitdiff
