From: aland Date: Tue, 12 Jun 2007 13:16:48 +0000 (+0000) Subject: Clarify the configuration file syntax enormously X-Git-Tag: release_2_0_0_pre2~254 X-Git-Url: http://www.project-moonshot.org/gitweb/?p=freeradius.git;a=commitdiff_plain;h=89dd97ada38c555b5d49a726f207381f79b7f3b7 Clarify the configuration file syntax enormously --- diff --git a/man/man5/radiusd.conf.5 b/man/man5/radiusd.conf.5 index d064c4f..5e89e74 100644 --- a/man/man5/radiusd.conf.5 +++ b/man/man5/radiusd.conf.5 @@ -1,98 +1,154 @@ -.TH radiusd.conf 5 "23 Jan 2004" "" "FreeRADIUS configuration file" +.TH radiusd.conf 5 "12 Jun 2007" "" "FreeRADIUS configuration file" .SH NAME radiusd.conf \- configuration file for the FreeRADIUS server .SH DESCRIPTION The \fBradiusd.conf\fP file resides in the radius database directory, by default \fB/etc/raddb\fP. It defines the global configuration for -the FreeRADIUS server. - +the FreeRADIUS RADIUS server. +.SH "CONTENTS" +There are a large number of configuration parameters for the server. +Most are documented in the file itself as comments. This page +documents only the format of the file. Please read the +\fBradiusd.conf\fP file itself for more information. + +The configuration file parser is independent of the server +configuration. This means that you can put almost anything into the +configuration file. So long as it is properly formatted, the server +will start. + +When the server parses the configuration file, it looks only for those +configurations it understands. Extra configuration items are ignored. +This "feature" can be (ab)used in certain interesting ways. .SH "FILE FORMAT" -The file consists of attribute-value pairs, sections, and comments. +The file format is line-based, like many other Unix configuration +files. Each entry in the file must be placed on a line by itself, +although continuations are supported. -Attribute-value pairs are of the form \fBname = value\fP. +The file consists of configuration items (variable = value pairs), +sections, and comments. +.IP Variables +Variables can be set via: -A section begins with a section name, followed on the same line by an -open bracket \fB{\fP. The section may contain other -sections, or attribute-value pairs. The section ends with a close -bracket \fB}\fP, on a line by itself. +.DS +.br + name = value +.DE + +Single and double-quoted strings are permitted: -Any line beginning with a (\fB#\fP) is deemed to be a comment, and is -ignored. Lines containing only whitespace are also ignored. - -The file is line-based. That is, each newline-terminated line -represents either a comment, a section name, or an attribute-value -pair. It is not possible to specify multiple items on the same line, -and there are no continuation lines. - -The value for a particular attribute may reference a previously -defined attribute by name. The standard shell reference format -\fB${name}\fP is used. When the variable is in a section or -subsection, it may be referenced as \fB${section.subsection.name}\fP. -Forward references are not allowed. Relative references are allowed, -via pre-pending the name with one or more of '.'. - -The individidual configuration directives are too numerous to list -here, so this manual page only documents the file format. Please read -the sample configuration file distributed with the server for comments -describing each of the allowed configuration directives. - -.SH EXAMPLES -.PP .DS - foo = bar +.br + string1 = "hello world" +.br + string2 = 'hello mom' +.DE +.IP Sections +A section begins with a section name, followed on the same line by an +open bracket '\fB{\fP'. Section may contain other sections, comments, or +variables. Sections may be nested to any depth, limited +only by available memory. A section ends with a close bracket +'\fB}\fP', on a line by itself. +.DS +.br + section { +.br + ... +.br + } .DE -Sets variable \fBfoo\fP to have text value \fBbar\fP. + +Sections can sometimes have a second name following the first one. +The situations where this is legal depend on the context. See the +examples and comments in the \fBradiusd.conf\fP file for more +information. .DS - blogs = ${foo} +.br + section foo { +.br + ... +.br + } +.DE +.IP Comments +Any line beginning with a (\fB#\fP) is deemed to be a comment, and is +ignored. Comments can appear after a variable or section definitions. +.DS +.br + # comment +.br + foo = bar # set variable 'foo' to value 'bar' +.br + section { # start of section +.br + ... +.br + } # end of section .DE -Sets variable \fBblogs\fP to the value of variable \fBfoo\fP from the -current section. If there is no variable \fBfoo\fP in the current -section, then it looks for that variable in the body of the main -configuration file, e.g. \f${Blogdir}\fP +.IP Continuations +Long lines can be broken up via continuations, using '\\' as the last +character of the line. For example, the following entry: .DS - my_section { .br - baz = bud + foo = "blah \\ .br - } + blah \\ +.br + blah" +.DE + +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. +.SH "REFERENCES" +The value of a variable can reference another variable. These +references are evaluated when the configuration file is loaded, which +means that there is no run-time cost associated with them. This +feature is most useful for turning long, repeated pieces of text into +short ones. +Variables are referenced by ${variable_name}, as in the following examples. + +.DS + foo = bar # set variable 'foo' to value 'bar' +.br + who = ${foo} # sets variable 'who' to value of variable 'foo' +.br + my = "${foo} a" # sets variable 'my' to "bar a" .DE -Defines a section named \fBmy_section\fP, containing variable -\fBbaz\fP. + +If the variable exists in a section or subsection, it can be +referenced as ${section.subsection.variable}. Forward references are +not allowed. Relative references are allowed, by pre-pending the name +with one or more period. .DS blogs = ${.foo} .DE -Sets variable \fBblogs\fP to the value of variable \fBfoo\fP, +Will set variable \fBblogs\fP to the value of variable \fBfoo\fP, from the current section. .DS blogs = ${..foo} .DE -Sets variable \fBblogs\fP to the value of variable \fBfoo\fP, from the +Will set variable \fBblogs\fP to the value of variable \fBfoo\fP, from the section which contains the current section. .DS blogs = ${modules.detail.detailfile} .DE -Sets variable \fBblogs\fP to the value of variable \fBdetailfile\fP, +Will set variable \fBblogs\fP to the value of variable \fBdetailfile\fP, of the \fBdetail\fP module, which is in the \fBmodules\fP section of the configuration file. - -.PP .SH FILES /etc/raddb/radiusd.conf .SH "SEE ALSO" -.BR radiusd (8), -.BR users (5) -.BR clients (5) - +.BR radiusd (8) .SH AUTHOR -Alan DeKok +Alan DeKok