From: Alan T. DeKok Date: Mon, 3 Aug 2026 14:40:37 +0000 (-0400) Subject: reformat radiusd.conf.in and regenerate antora docs X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;p=thirdparty%2Ffreeradius-server.git reformat radiusd.conf.in and regenerate antora docs --- diff --git a/doc/antora/modules/reference/pages/raddb/radiusd.conf.adoc b/doc/antora/modules/reference/pages/raddb/radiusd.conf.adoc index 7422f62528..0121fd72ae 100644 --- a/doc/antora/modules/reference/pages/raddb/radiusd.conf.adoc +++ b/doc/antora/modules/reference/pages/raddb/radiusd.conf.adoc @@ -4,47 +4,45 @@ = FreeRADIUS server configuration file - 4.0 -Read `man radiusd` before editing this file. See the section -titled DEBUGGING. It outlines a method where you can quickly -obtain the configuration you want, without running into -trouble. +Read `man radiusd` before editing this file. See the section titled +DEBUGGING. It outlines a method where you can quickly obtain the +configuration you want, without running into trouble. Run the server in debugging mode, and READ the output. $ radiusd -X -We cannot emphasize this point strongly enough. The vast -majority of problems can be solved by carefully reading the -debugging output, which includes warnings about common issues, -and suggestions for how they may be fixed. +We cannot emphasize this point strongly enough. The vast majority +of problems can be solved by carefully reading the debugging +output, which includes warnings about common issues, and +suggestions for how they may be fixed. There may be a lot of output, but look carefully for words like: -`warning`, `error`, `reject`, or `failure`. The messages there -will usually be enough to guide you to a solution. +`warning`, `error`, `reject`, or `failure`. The messages there will +usually be enough to guide you to a solution. If you are going to ask a question on the mailing list, then explain what you are trying to do, and include the output from -debugging mode (`radiusd -X`). Failure to do so means that all -of the responses to your question will be people telling you -to _post the output of `radiusd -X`_. +debugging mode (`radiusd -X`). Failure to do so means that all of +the responses to your question will be people telling you to _post +the output of `radiusd -X`_. == Default instance -The location of other config files and logfiles are declared -in this file. +The location of other config files and logfiles are declared in +this file. -Also general configuration for modules can be done in this -file, it is exported through the API to modules that ask for -it. +Also general configuration for modules can be done in this file, it +is exported through the API to modules that ask for it. See `man radiusd.conf` for documentation on the format of this -file. Note that the individual configuration items are NOT -documented in that "man" page. They are only documented here, -in the comments. +file. Note that the individual configuration items are NOT +documented in that "man" page. They are only documented here, in +the comments. -The `unlang` policy language can be used to create complex -if / else policies. For more information, see +The `unlang` policy language can be used to create complex if / +else policies. For more information, see https://www.freeradius.org/documentation/freeradius-server/4.0/ @@ -68,26 +66,26 @@ libdir:: Where to find the rlm_* modules. This should be automatically set at configuration time. -If the server builds and installs, but fails at execution time -with an 'undefined symbol' error, then you can use the `libdir` +If the server builds and installs, but fails at execution time with +an 'undefined symbol' error, then you can use the `libdir` directive to work around the problem. The cause is usually that a library has been installed on your -system in a place where the dynamic linker *cannot* find it. When +system in a place where the dynamic linker *cannot* find it. When executing as root (or another user), your personal environment - *may* be set up to allow the dynamic linker to find the -library. When executing as a daemon, FreeRADIUS *may not* have -the same personalized configuration. + *may* be set up to allow the dynamic linker to find the library. +When executing as a daemon, FreeRADIUS *may not* have the same +personalized configuration. -To work around the problem, find out which library contains -that symbol, and add the directory containing that library to -the end of `libdir`, with a colon separating the directory -names. *No* spaces are allowed. e.g. +To work around the problem, find out which library contains that +symbol, and add the directory containing that library to the end of +`libdir`, with a colon separating the directory names. *No* spaces +are allowed. e.g. libdir = /usr/local/lib:/opt/package/lib -You can also try setting the `LD_LIBRARY_PATH` environment -variable in a script which starts the server. +You can also try setting the `LD_LIBRARY_PATH` environment variable +in a script which starts the server. If that does not work, then you can re-configure and re-build the server to NOT use shared libraries, via: @@ -100,12 +98,11 @@ server to NOT use shared libraries, via: pidfile:: Where to place the PID of the RADIUS server. -The server may be signalled while it's running by using this -file. +The server may be signalled while it's running by using this file. This file is written when _only_ running in daemon mode. -e.g.: `kill -HUP $(cat /var/run/radiusd/radiusd.pid)` +e.g.: `kill -HUP $(cat /var/run/radiusd/radiusd.pid)` @@ -113,21 +110,21 @@ panic_action:: Command to execute if the server dies unexpectedly. [WARNING] ==== -FOR PRODUCTION SYSTEMS, ACTIONS SHOULD ALWAYS EXIT. -AN INTERACTIVE ACTION MEANS THE SERVER IS NOT RESPONDING TO REQUESTS. -AN INTERACTICE ACTION MEANS THE SERVER WILL NOT RESTART. +FOR PRODUCTION SYSTEMS, ACTIONS SHOULD ALWAYS EXIT. AN INTERACTIVE +ACTION MEANS THE SERVER IS NOT RESPONDING TO REQUESTS. AN +INTERACTICE ACTION MEANS THE SERVER WILL NOT RESTART. THE SERVER MUST NOT BE ALLOWED EXECUTE UNTRUSTED PANIC ACTION CODE PATTACH CAN BE USED AS AN ATTACK VECTOR. ==== The panic action is a command which will be executed if the server -receives a fatal, non user generated signal, i.e. `SIGSEGV`, `SIGBUS`, -`SIGABRT` or `SIGFPE`. +receives a fatal, non user generated signal, i.e. `SIGSEGV`, +`SIGBUS`, `SIGABRT` or `SIGFPE`. -This can be used to start an interactive debugging session so -that information regarding the current state of the server can -be acquired. +This can be used to start an interactive debugging session so that +information regarding the current state of the server can be +acquired. The following string substitutions are available: - `%e` The currently executing program e.g. `/sbin/radiusd` @@ -135,12 +132,14 @@ The following string substitutions are available: Standard `${}` substitutions are also allowed. -An example panic action for opening an interactive session in GDB would be: +An example panic action for opening an interactive session in GDB +would be: Again, don't use that on a production system. -An example panic action for opening an automated session in GDB would be: +An example panic action for opening an automated session in GDB +would be: NOTE: That command can be used on a production system. @@ -151,25 +150,24 @@ request:: Configuration for request handling. These items control how requests are allocated and processed. -NOTE: Most of these configuration items are per-worker. To get the -true number of requests you need to multiply the value by the number -of workers (or the number of cores). +NOTE: Most of these configuration items are per-worker. To get the +true number of requests you need to multiply the value by the +number of workers (or the number of cores). -max:: The maximum number of requests which the server -keeps track of. This should be at least `256` multiplied by the -number of clients. e.g. With `4` clients, this number should be -`1024`. +max:: The maximum number of requests which the server keeps track +of. This should be at least `256` multiplied by the number of +clients. e.g. With `4` clients, this number should be `1024`. -If this number is too low, then when the server becomes busy, -it will not respond to any new requests, until the 'cleanup_delay' +If this number is too low, then when the server becomes busy, it +will not respond to any new requests, until the 'cleanup_delay' time has passed, and it has removed the old requests. -If this number is set too high, then the server will use a bit more -memory for no real benefit. +If this number is set too high, then the server will use a bit +more memory for no real benefit. If you aren't sure what it should be set to, it's better to set it -too high than too low. Setting it to `1000` per client is probably +too high than too low. Setting it to `1000` per client is probably the highest it should be. Unlike v3, this setting is per worker thread, and is not global to @@ -181,27 +179,28 @@ Useful range of values: `256` to `infinity` timeout:: The maximum time (in seconds) to handle a request. -Requests which take more time than this to process may be killed, and -a REJECT message is returned. +Requests which take more time than this to process may be killed, +and a REJECT message is returned. -WARNING: If you notice that requests take a long time to be handled, -then this MAY INDICATE a bug in the server, in one of the modules -used to handle a request, OR in your local configuration. +WARNING: If you notice that requests take a long time to be +handled, then this MAY INDICATE a bug in the server, in one of the +modules used to handle a request, OR in your local configuration. -This problem is most often seen when using an SQL database. If it takes -more than a second or two to receive an answer from the SQL database, -then it probably means that you haven't indexed the database. See your -SQL server documentation for more information. +This problem is most often seen when using an SQL database. If it +takes more than a second or two to receive an answer from the SQL +database, then it probably means that you haven't indexed the +database. See your SQL server documentation for more information. Useful range of values: `5` to `120` -Instead of requests being freed at the end of processing, they can be -returned to a list of requests to reuse. +Instead of requests being freed at the end of processing, they can +be returned to a list of requests to reuse. -As with `request.max` reuse values apply on a per-worker basis, so the -true number of cached requests is `request.reuse.max * `. +As with `request.max` reuse values apply on a per-worker basis, so +the true number of cached requests is `request.reuse.max * `. min:: The minimum number of requests to keep in the reuse list. @@ -210,11 +209,10 @@ min:: The minimum number of requests to keep in the reuse list. max:: The maximum number of reusable requests. -Any requests being processed by a worker beyond -this number will cause a temporary request to be allocated. -This is less efficient than the block allocation so -`max` should be set to reflect the number of outstanding -requests expected at peak load. +Any requests being processed by a worker beyond this number will +cause a temporary request to be allocated. This is less efficient +than the block allocation so `max` should be set to reflect the +number of outstanding requests expected at peak load. FIXME: Should likely default to request.max @@ -222,29 +220,30 @@ FIXME: Should likely default to request.max cleanup_interval:: How often to free un-used requests. -Every `cleanup_interval` a cleanup routine runs which -will free any blocks of handles which are not in use, -ensuring that at least `min` handles are kept. +Every `cleanup_interval` a cleanup routine runs which will free +any blocks of handles which are not in use, ensuring that at +least `min` handles are kept. This ensures that the server's memory usage does not remain permanently bloated after a load spike. -reverse_lookups:: Log the names of clients or just their IP addresses +reverse_lookups:: Log the names of clients or just their IP +addresses e.g., www.freeradius.org (`on`) or 206.47.27.232 (`off`). The default is `off` because it would be overall better for the net if people had to knowingly turn this feature on, since enabling it means that each client request will result in AT LEAST one lookup -request to the nameserver. Enabling `hostname_lookups` will also +request to the nameserver. Enabling `hostname_lookups` will also mean that your server may stop randomly for `30` seconds from time to time, if the DNS requests take too long. Turning hostname lookups off also means that the server won't block -for `30` seconds, if it sees an IP address which has no name associated -with it. +for `30` seconds, if it sees an IP address which has no name +associated with it. allowed values: {no, yes} @@ -252,17 +251,17 @@ allowed values: {no, yes} hostname_lookups:: Global toggle for preventing hostname resolution -The default is `on` because people often use hostnames in configuration -files. The main disadvantage of enabling this is the server may block -at inopportune moments (like opening new connections) if the DNS servers -are unavailable +The default is `on` because people often use hostnames in +configuration files. The main disadvantage of enabling this is the +server may block at inopportune moments (like opening new +connections) if the DNS servers are unavailable allowed values: {no, yes} -Logging section. The various `log_*` configuration items -will eventually be moved here. +Logging section. The various `log_*` configuration items will +eventually be moved here. destination:: Destination for log messages. @@ -282,18 +281,19 @@ logging to go to stdout. -colourise:: Highlight important messages sent to stderr and stdout. +colourise:: Highlight important messages sent to stderr and +stdout. -Option will be ignored (disabled) if output of `TERM` is not -an xterm or output is not to a TTY. +Option will be ignored (disabled) if output of `TERM` is not an +xterm or output is not to a TTY. timestamp:: Add a timestamp to the start of every log message. -By default this is done with log levels of `-Xx` or `-xxx` -where the destination is not syslog, or at all levels where the -output is a file. +By default this is done with log levels of `-Xx` or `-xxx` where +the destination is not syslog, or at all levels where the output +is a file. The config option below forcefully enables or disables timestamps irrespective of the log destination. @@ -305,51 +305,48 @@ NOTE: Is overridden by the `-T` command line option. file:: The logging messages for the server are appended to the tail of this file `if ${destination} == "file"` -NOTE: If the server is running in debugging mode, this file is -NOT used. +NOTE: If the server is running in debugging mode, this file is NOT +used. -syslog_facility:: Which syslog facility to use, `if ${destination} == "syslog"`. +syslog_facility:: Which syslog facility to use, `if ${destination} +== "syslog"`. -The exact values permitted here are _OS-dependent_. You probably +The exact values permitted here are _OS-dependent_. You probably don't want to change this. -suppress_secrets:: Suppress "secret" values when printing -them in debug mode. +suppress_secrets:: Suppress "secret" values when printing them in +debug mode. NOTE: Note that when running the server at debug level 3 or higher, this configuration ite, is ignored. -Setting this to `yes` means that the server does not print -the contents of "secret" values such as passwords. It -instead prints a place-holder value "<<< secret >>>", as -follows: +Setting this to `yes` means that the server does not print the +contents of "secret" values such as passwords. It instead prints a +place-holder value "<<< secret >>>", as follows: -... +``` User-Password = "<<< secret >>>" -... +``` Secret values are tracked across string expansions, string -modifications, concatenations, etc. i.e. if a -`link:https://freeradius.org/rfc/rfc2865.html#User-Password[User-Password]` is placed into a `link:https://freeradius.org/rfc/rfc2865.html#Reply-Message[Reply-Message]`, then the -value of the `link:https://freeradius.org/rfc/rfc2865.html#Reply-Message[Reply-Message]` will also be marked as -"secret". +modifications, concatenations, etc. i.e. if a `link:https://freeradius.org/rfc/rfc2865.html#User-Password[User-Password]` is +placed into a `link:https://freeradius.org/rfc/rfc2865.html#Reply-Message[Reply-Message]`, then the value of the +`link:https://freeradius.org/rfc/rfc2865.html#Reply-Message[Reply-Message]` will also be marked as "secret". -This configuration is enabled by default. While doing this -can make it harder to debug the server (as passwords are -omitted from the debug output), the servers defaults are as -secure as possible. +This configuration is enabled by default. While doing this can +make it harder to debug the server (as passwords are omitted from +the debug output), the servers defaults are as secure as possible. -In many cases it is not useful to suppress secrets in an -attempt to "be more secure". Any administrator who can see -the debug ouput is usually also able to view and/or modify -the servers configuration (including passwords in -databases!). And any "low level" administrator who can -only see the debug output will usually need to see the -actual passwords in order to verify what the user is -entering. +In many cases it is not useful to suppress secrets in an attempt +to "be more secure". Any administrator who can see the debug ouput +is usually also able to view and/or modify the servers +configuration (including passwords in databases!). And any "low +level" administrator who can only see the debug output will +usually need to see the actual passwords in order to verify what +the user is entering. @@ -360,35 +357,35 @@ For example, the following function calls can be placed in an `unlang` block, where it will: -The file will be closed when the request exits. It is the admins -responsibility to ensure that the debug files are periodically cleaned up. -The server does not do this automatically. +The file will be closed when the request exits. It is the admins +responsibility to ensure that the debug files are periodically +cleaned up. The server does not do this automatically. -.ENVIRONMENT VARIABLES += ENVIRONMENT VARIABLES You can reference environment variables using an expansion like -`$ENV{PATH}`. However it is sometimes useful to be able to also set -environment variables. This section lets you do that. +`$ENV{PATH}`. However it is sometimes useful to be able to also set +environment variables. This section lets you do that. The main purpose of this section is to allow administrators to keep RADIUS-specific configuration in the RADIUS configuration files. For example, if you need to set an environment variable which is -used by a module. You could put that variable into a shell script, -but that's awkward. Instead, just list it here. +used by a module. You could put that variable into a shell script, +but that's awkward. Instead, just list it here. Note that these environment variables are set AFTER the -configuration file is loaded. So you cannot set FOO here, and -expect to reference it via `$ENV{FOO}` in another configuration file. -You should instead just use a normal configuration variable for -that. +configuration file is loaded. So you cannot set FOO here, and +expect to reference it via `$ENV{FOO}` in another configuration +file. You should instead just use a normal configuration variable +for that. Set environment variable `FOO` to value '/bar/baz'. -NOTE: Note that you MUST use '='. You CANNOT use '+=' to append +NOTE: Note that you MUST use '='. You CANNOT use '+=' to append values. @@ -405,10 +402,10 @@ run in debug mode. -`LD_PRELOAD` is special. It is normally set before the -application runs, and is interpreted by the dynamic linker. -Which means you cannot set it inside of an application, and -expect it to load libraries. +`LD_PRELOAD` is special. It is normally set before the application +runs, and is interpreted by the dynamic linker. Which means you +cannot set it inside of an application, and expect it to load +libraries. Since this functionality is useful, we extend it here. @@ -416,17 +413,17 @@ You can set LD_PRELOAD = /path/to/library.so -and the server will load the named libraries. Multiple -libraries can be loaded by specificing multiple individual -`LD_PRELOAD` entries. +and the server will load the named libraries. Multiple libraries +can be loaded by specificing multiple individual `LD_PRELOAD` +entries. -.Templates += Templates Template files hold common definitions that can be used in other -server sections. When a template is referenced, the configuration +server sections. When a template is referenced, the configuration items within the referenced template are copied to the referencing section. @@ -438,50 +435,56 @@ referencing syntax. -.Security Configuration += Security Configuration -There may be multiple methods of attacking on the server. This -section holds the configuration items which minimize the impact -of those attacks +There may be multiple methods of attacking on the server. This +section holds the configuration items which minimize the impact of +those attacks user:: -group:: -The name (or `#number`) of the `user`/`group` to run `radiusd` as. +The name (or `#number`) of the `user` to use as the uid of the +server. -If these are commented out, the server will run as the -user/group that started it. In order to change to a -different user/group, you MUST be root ( or have root -privileges ) to start the server. +If the user/group fields are commented out, the server will run as +the user/group that started it. In order to change to a different +user/group, the server MUST start as root (or have permissions to +change UID / GID) We STRONGLY recommend that you run the server with as few -permissions as possible. That is, if you're not using -shadow passwords, the user and group items below should be -set to radius'. +permissions as possible. That is, if you're not using shadow +passwords, the `user` and `group` items should be set to `radius`. -NOTE: Some kernels refuse to `setgid(group)` when the -value of (unsigned)group is above 60000; don't use group -`nobody` on these systems! -On systems with shadow passwords, you might have to set -`group = shadow` for the server to be able to read the -shadow password file. If you can authenticate users while -in debug mode, but not in daemon mode, it may be that the -debugging mode server is running as a user that can read -the shadow info, and the user listed below can not. -The server will also try to use `initgroups` to read -/etc/groups. It will join all groups where "user" is a -member. This can allow for some finer-grained access -controls. +group:: + +The name (or `#number`) of the `user` to use as the gid. + +See the `user` configuration above for additional information. +NOTE: Some kernels refuse to `setgid(group)` when the value of +(unsigned)group is above 60000; don't use group `nobody` on these +systems! +On systems with shadow passwords, you might have to set `group = +shadow` for the server to be able to read the shadow password +file. If you can authenticate users while in debug mode, but not +in daemon mode, it may be that the debugging mode server is +running as a user that can read the shadow info, and the user +listed below can not. -After the server has changed to the final user/group, it -can also set the current working directory. While not -necessary, changing the working directory means that the -server does not have any dangling paths. +The server will also try to use `initgroups` to read /etc/groups. +It will join all groups where "user" is a member. This can allow +for some finer-grained access controls. + + + +After the server has changed to the final user/group, it can also +set the current working directory. While not necessary, changing +the working directory means that the server does not have any +dangling paths. The directory here should either be "/", or ${confdir} @@ -489,74 +492,76 @@ The directory here should either be "/", or ${confdir} limit files:: Limit the directories for function calls -The server provides functions such as %file.touch() to read -files, write files, make directories, etc. For security, -this ability can be limited to specific directories. +The server provides functions such as %file.touch() to read files, +write files, make directories, etc. For security, this ability can +be limited to specific directories. -If this section is missing, then the server allows the -%file...() APIs to read and write any directory. +If this section is missing, then the server allows the %file...() +APIs to read and write any directory. -If the section exists but is empty, then the server does -not allow the %file...() APIs to read and write any -directory. +If the section exists but is empty, then the server does not allow +the %file...() APIs to read and write any directory. -Note that you should NOT list ${confdir} here. The -configuration files should NEVER be writable by the server. +Note that you should NOT list ${confdir} here. The configuration +files should NEVER be writable by the server. + +If this section is configured, then these limits are always +applied, even if the filename comes from the configuration files, +and would normally be considered "safe". limit exec:: Limit the programs which can be executed -The server provides functions such as %exec() to run -external programs. For security, this ability can be -limited to specific directories. +The server provides functions such as %exec() to run external +programs. For security, this ability can be limited to specific +directories. -If this section is missing, then the server allows the -%exec() APIs to run any program on the system. +If this section is missing, then the server allows the %exec() +APIs to run any program on the system. -If this section exists but is empty, then the server does -not allow the %exec() APIs to run any program. +If this section exists but is empty, then the server does not +allow the %exec() APIs to run any program. -The entries here can be directories or specific -programs. +The entries here can be directories or specific programs. allow_core_dumps:: Core dumps are a bad thing. -This should only be set to `yes` if you're debugging -a problem with the server. +This should only be set to `yes` if you're debugging a problem +with the server. allowed values: {no, yes} -max_attributes:: The maximum number of attributes -permitted in a RADIUS packet. Packets which have MORE -than this number of attributes in them will be dropped. +max_attributes:: The maximum number of attributes permitted in a +RADIUS packet. Packets which have MORE than this number of +attributes in them will be dropped. -If this number is set too low, then no RADIUS packets -will be accepted. +If this number is set too low, then no RADIUS packets will be +accepted. -If this number is set too high, then an attacker may be -able to send a small number of packets which will cause -the server to use all available memory on the machine. +If this number is set too high, then an attacker may be able to +send a small number of packets which will cause the server to use +all available memory on the machine. Setting this number to 0 means "allow any number of attributes" -.Clients Configuration += Clients Configuration Client configuration is defined in `clients.conf`. [WARNING] ==== -The `clients.conf` file contains all of the information from the old -`clients` and `naslist` configuration files. We recommend that you -do NOT use `client's` or `naslist`, although they are still +The `clients.conf` file contains all of the information from the +old `clients` and `naslist` configuration files. We recommend that +you do NOT use `client's` or `naslist`, although they are still supported. Anything listed in 'clients.conf' will take precedence over the @@ -565,9 +570,9 @@ information from the old-style configuration files. -.Thread Pool Configuration += Thread Pool Configuration -In v4, the thread pool does not change size dynamically. Instead, +In v4, the thread pool does not change size dynamically. Instead, there are a small number of threads which read from the network, and a slightly larger number of threads which process a request. @@ -576,69 +581,71 @@ num_networks:: Only one network thread is supported for now. -num_workers:: The worker threads can be varied. It should be -at least one, and no more than 128. Since each request is -non-blocking, there is no reason to run hundreds of threads -as in v3. +num_workers:: The worker threads can be varied. It should be at +least one, and no more than 128. Since each request is +non-blocking, there is no reason to run hundreds of threads as in +v3. -Defaults to the number of cores available on the system, or, -1, if this cannot be determined. +Defaults to the number of cores available on the system, or, 1, if +this cannot be determined. openssl_async_pool_init:: Controls the initial number of async -contexts that are allocated when a worker thread is created. -One async context is required for every TLS session (every -RADSEC connection, every TLS based method still in progress). +contexts that are allocated when a worker thread is created. One +async context is required for every TLS session (every RADSEC +connection, every TLS based method still in progress). openssl_async_pool_max:: Controls the maximum number of async -contexts which are allocated to a worker thread. -If the maximum is reached, then no more TLS sessions can be -created. +contexts which are allocated to a worker thread. If the maximum is +reached, then no more TLS sessions can be created. -NOTE: Setting this to 0 will mean unlimited async contexts -will be created. But as of 3.0.0, OpenSSL has no mechanism -to shrink the async pool. This means if there's a -significant traffic spike the process will continue to use -large amounts of memory until it's restarted. +NOTE: Setting this to 0 will mean unlimited async contexts will be +created. But as of 3.0.0, OpenSSL has no mechanism to shrink the +async pool. This means if there's a significant traffic spike the +process will continue to use large amounts of memory until it's +restarted. -.SNMP notifications. += Triggers and SNMP notifications. -Uncomment the following line to enable snmptraps. Note that you -MUST also configure the full path to the `snmptrap` command in -the `trigger.conf` file. +Uncomment the following line to enable snmptraps. Note that you +MUST also configure the full path to the `snmptrap` command in the +`trigger.conf` file. +$INCLUDE trigger.conf -.Global Library Settings +.= Global Library Settings -Each library which has global settings will have its own configuration -file in global.d +Each library which has global settings will have its own +configuration file in global.d -.Migration Flags += Migration Flags -These flags are only for the "alpha" release of v4. They will be +These flags are only for the "alpha" release of v4. They will be removed (and made into errors!) in the final release. -Some of these flags can also be passed on the command line as -`-S flag=value`. +Some of these flags can also be passed on the command line as `-S +flag=value`. -Dictionary migration instructions can be found in `${confdir}/dictionary`. +Dictionary migration instructions can be found in +`${confdir}/dictionary`. -.Module Configuration += Module Configuration -The names and configuration of each module is located in this section. +The names and configuration of each module is located in this +section. -After the modules are defined here, they may be referred to by name, -in other sections of this configuration file. +After the modules are defined here, they may be referred to by +name, in other sections of this configuration file. Each module has a configuration as follows: @@ -650,53 +657,51 @@ name [ instance ] { } ``` -The `name` is used to load the `rlm_name` library -which implements the functionality of the module. +The `name` is used to load the `rlm_name` library which implements +the functionality of the module. -The 'instance' is optional. To have two different instances -of a module, it first must be referred to by 'name'. -The different copies of the module are then created by -inventing two 'instance' names, e.g. 'instance1' and 'instance2' +The 'instance' is optional. To have two different instances of a +module, it first must be referred to by 'name'. The different +copies of the module are then created by inventing two 'instance' +names, e.g. 'instance1' and 'instance2' -The instance names can then be used in later configuration -INSTEAD of the original 'name'. e.g. instead of `pap { ...}`, -you can use `pap other {...}`. The `other` name will then be -a reference to the second PAP module. +The instance names can then be used in later configuration INSTEAD +of the original 'name'. e.g. instead of `pap { ...}`, you can use +`pap other {...}`. The `other` name will then be a reference to +the second PAP module. Some modules have ordering issues. -e.g. `sqlippool` uses the configuration from `sql`. -In that case, the `sql` module must be read off of disk before -the `sqlippool`. +e.g. `sqlippool` uses the configuration from `sql`. In that case, +the `sql` module must be read off of disk before the `sqlippool`. -However, the directory inclusion below just reads the -directory from start to finish. Which means that the -modules are read off of disk randomly. +However, the directory inclusion below just reads the directory +from start to finish. Which means that the modules are read off of +disk randomly. As of `>= 3.0.18`, you can list individual modules *before* the -directory inclusion. Those modules will be loaded first. -Then, when the directory is read, those modules will be -skipped and not read twice. +directory inclusion. Those modules will be loaded first. Then, +when the directory is read, those modules will be skipped and not +read twice. -Modules are in mods-enabled/. Files matching -the regex /[a-zA-Z0-9_.]+/ are loaded. The modules are -initialized ONLY if they are referenced in a processing -section, such as authorize, authenticate, accounting, -pre/post-proxy, etc. +Modules are in mods-enabled/. Files matching the regex +/[a-zA-Z0-9_.]+/ are loaded. The modules are initialized ONLY if +they are referenced in a processing section, such as authorize, +authenticate, accounting, pre/post-proxy, etc. -.Policies += Policies Policies are virtual modules. -Defining a policy in one of the `policy.d` files means that it can be -referenced in multiple places as a *name*, rather than as a series of -conditions to match, and actions to take. +Defining a policy in one of the `policy.d` files means that it can +be referenced in multiple places as a *name*, rather than as a +series of conditions to match, and actions to take. Policies are something like subroutines in a normal language, but they cannot be called recursively. They MUST be defined in order. @@ -704,13 +709,13 @@ If policy A calls policy B, then B MUST be defined before A. -.Load virtual servers. += Load virtual servers. -This next $INCLUDE line loads files in the directory that -match the regular expression: /[a-zA-Z0-9_.]+/ +This next $INCLUDE line loads files in the directory that match the +regular expression: /[a-zA-Z0-9_.]+/ -It allows you to define new virtual servers simply by placing -a file into the sites-enabled/ directory. +It allows you to define new virtual servers simply by placing a +file into the sites-enabled/ directory. All of the other configuration sections like: @@ -723,9 +728,9 @@ Have been moved to the file: xref:reference:raddb/sites-available/default.adoc[sites-available/default] This is the `default` virtual server that has the same -configuration as in version 1.0.x and 1.1.x. The default -installation enables this virtual server. You should -edit it to create policies for your local site. +configuration as in version 1.0.x and 1.1.x. The default +installation enables this virtual server. You should edit it to +create policies for your local site. == Default Configuration @@ -813,7 +818,6 @@ thread pool { # openssl_async_pool_init = 64 # openssl_async_pool_max = 1024 } -#$INCLUDE trigger.conf global { $INCLUDE global.d/ } diff --git a/raddb/radiusd.conf.in b/raddb/radiusd.conf.in index eb2b502fe3..46fa2b8714 100644 --- a/raddb/radiusd.conf.in +++ b/raddb/radiusd.conf.in @@ -7,47 +7,45 @@ # # = FreeRADIUS server configuration file - @RADIUSD_VERSION_MAJOR@.@RADIUSD_VERSION_MINOR@ # -# Read `man radiusd` before editing this file. See the section -# titled DEBUGGING. It outlines a method where you can quickly -# obtain the configuration you want, without running into -# trouble. +# Read `man radiusd` before editing this file. See the section titled +# DEBUGGING. It outlines a method where you can quickly obtain the +# configuration you want, without running into trouble. # # Run the server in debugging mode, and READ the output. # # $ radiusd -X # -# We cannot emphasize this point strongly enough. The vast -# majority of problems can be solved by carefully reading the -# debugging output, which includes warnings about common issues, -# and suggestions for how they may be fixed. +# We cannot emphasize this point strongly enough. The vast majority +# of problems can be solved by carefully reading the debugging +# output, which includes warnings about common issues, and +# suggestions for how they may be fixed. # # There may be a lot of output, but look carefully for words like: -# `warning`, `error`, `reject`, or `failure`. The messages there -# will usually be enough to guide you to a solution. +# `warning`, `error`, `reject`, or `failure`. The messages there will +# usually be enough to guide you to a solution. # # If you are going to ask a question on the mailing list, then # explain what you are trying to do, and include the output from -# debugging mode (`radiusd -X`). Failure to do so means that all -# of the responses to your question will be people telling you -# to _post the output of `radiusd -X`_. +# debugging mode (`radiusd -X`). Failure to do so means that all of +# the responses to your question will be people telling you to _post +# the output of `radiusd -X`_. # # == Default instance # -# The location of other config files and logfiles are declared -# in this file. +# The location of other config files and logfiles are declared in +# this file. # -# Also general configuration for modules can be done in this -# file, it is exported through the API to modules that ask for -# it. +# Also general configuration for modules can be done in this file, it +# is exported through the API to modules that ask for it. # # See `man radiusd.conf` for documentation on the format of this -# file. Note that the individual configuration items are NOT -# documented in that "man" page. They are only documented here, -# in the comments. +# file. Note that the individual configuration items are NOT +# documented in that "man" page. They are only documented here, in +# the comments. # -# The `unlang` policy language can be used to create complex -# if / else policies. For more information, see +# The `unlang` policy language can be used to create complex if / +# else policies. For more information, see # # https://www.freeradius.org/documentation/freeradius-server/@RADIUSD_DOC_VERSION@/ # @@ -85,26 +83,26 @@ db_dir = ${localstatedir}/lib/${name} # # This should be automatically set at configuration time. # -# If the server builds and installs, but fails at execution time -# with an 'undefined symbol' error, then you can use the `libdir` +# If the server builds and installs, but fails at execution time with +# an 'undefined symbol' error, then you can use the `libdir` # directive to work around the problem. # # The cause is usually that a library has been installed on your -# system in a place where the dynamic linker *cannot* find it. When +# system in a place where the dynamic linker *cannot* find it. When # executing as root (or another user), your personal environment -# *may* be set up to allow the dynamic linker to find the -# library. When executing as a daemon, FreeRADIUS *may not* have -# the same personalized configuration. +# *may* be set up to allow the dynamic linker to find the library. +# When executing as a daemon, FreeRADIUS *may not* have the same +# personalized configuration. # -# To work around the problem, find out which library contains -# that symbol, and add the directory containing that library to -# the end of `libdir`, with a colon separating the directory -# names. *No* spaces are allowed. e.g. +# To work around the problem, find out which library contains that +# symbol, and add the directory containing that library to the end of +# `libdir`, with a colon separating the directory names. *No* spaces +# are allowed. e.g. # # libdir = /usr/local/lib:/opt/package/lib # -# You can also try setting the `LD_LIBRARY_PATH` environment -# variable in a script which starts the server. +# You can also try setting the `LD_LIBRARY_PATH` environment variable +# in a script which starts the server. # # If that does not work, then you can re-configure and re-build the # server to NOT use shared libraries, via: @@ -118,12 +116,11 @@ libdir = @libdir@ # # pidfile:: Where to place the PID of the RADIUS server. # -# The server may be signalled while it's running by using this -# file. +# The server may be signalled while it's running by using this file. # # This file is written when _only_ running in daemon mode. # -# e.g.: `kill -HUP $(cat /var/run/radiusd/radiusd.pid)` +# e.g.: `kill -HUP $(cat /var/run/radiusd/radiusd.pid)` # pidfile = ${run_dir}/${name}.pid @@ -132,21 +129,21 @@ pidfile = ${run_dir}/${name}.pid # # [WARNING] # ==== -# FOR PRODUCTION SYSTEMS, ACTIONS SHOULD ALWAYS EXIT. -# AN INTERACTIVE ACTION MEANS THE SERVER IS NOT RESPONDING TO REQUESTS. -# AN INTERACTICE ACTION MEANS THE SERVER WILL NOT RESTART. +# FOR PRODUCTION SYSTEMS, ACTIONS SHOULD ALWAYS EXIT. AN INTERACTIVE +# ACTION MEANS THE SERVER IS NOT RESPONDING TO REQUESTS. AN +# INTERACTICE ACTION MEANS THE SERVER WILL NOT RESTART. # # THE SERVER MUST NOT BE ALLOWED EXECUTE UNTRUSTED PANIC ACTION CODE # PATTACH CAN BE USED AS AN ATTACK VECTOR. # ==== # # The panic action is a command which will be executed if the server -# receives a fatal, non user generated signal, i.e. `SIGSEGV`, `SIGBUS`, -# `SIGABRT` or `SIGFPE`. +# receives a fatal, non user generated signal, i.e. `SIGSEGV`, +# `SIGBUS`, `SIGABRT` or `SIGFPE`. # -# This can be used to start an interactive debugging session so -# that information regarding the current state of the server can -# be acquired. +# This can be used to start an interactive debugging session so that +# information regarding the current state of the server can be +# acquired. # # The following string substitutions are available: # - `%e` The currently executing program e.g. `/sbin/radiusd` @@ -154,13 +151,15 @@ pidfile = ${run_dir}/${name}.pid # # Standard `${}` substitutions are also allowed. # -# An example panic action for opening an interactive session in GDB would be: +# An example panic action for opening an interactive session in GDB +# would be: # #panic_action = "gdb %e %p" # # Again, don't use that on a production system. # -# An example panic action for opening an automated session in GDB would be: +# An example panic action for opening an automated session in GDB +# would be: # #panic_action = "gdb -silent -x ${confdir}/panic.gdb %e %p 2>&1 | tee ${logdir}/gdb-${name}-%p.log" # @@ -172,26 +171,25 @@ pidfile = ${run_dir}/${name}.pid # # These items control how requests are allocated and processed. # -# NOTE: Most of these configuration items are per-worker. To get the -# true number of requests you need to multiply the value by the number -# of workers (or the number of cores). +# NOTE: Most of these configuration items are per-worker. To get the +# true number of requests you need to multiply the value by the +# number of workers (or the number of cores). # request { # - # max:: The maximum number of requests which the server - # keeps track of. This should be at least `256` multiplied by the - # number of clients. e.g. With `4` clients, this number should be - # `1024`. + # max:: The maximum number of requests which the server keeps track + # of. This should be at least `256` multiplied by the number of + # clients. e.g. With `4` clients, this number should be `1024`. # - # If this number is too low, then when the server becomes busy, - # it will not respond to any new requests, until the 'cleanup_delay' + # If this number is too low, then when the server becomes busy, it + # will not respond to any new requests, until the 'cleanup_delay' # time has passed, and it has removed the old requests. # - # If this number is set too high, then the server will use a bit more - # memory for no real benefit. + # If this number is set too high, then the server will use a bit + # more memory for no real benefit. # # If you aren't sure what it should be set to, it's better to set it - # too high than too low. Setting it to `1000` per client is probably + # too high than too low. Setting it to `1000` per client is probably # the highest it should be. # # Unlike v3, this setting is per worker thread, and is not global to @@ -204,28 +202,29 @@ request { # # timeout:: The maximum time (in seconds) to handle a request. # - # Requests which take more time than this to process may be killed, and - # a REJECT message is returned. + # Requests which take more time than this to process may be killed, + # and a REJECT message is returned. # - # WARNING: If you notice that requests take a long time to be handled, - # then this MAY INDICATE a bug in the server, in one of the modules - # used to handle a request, OR in your local configuration. + # WARNING: If you notice that requests take a long time to be + # handled, then this MAY INDICATE a bug in the server, in one of the + # modules used to handle a request, OR in your local configuration. # - # This problem is most often seen when using an SQL database. If it takes - # more than a second or two to receive an answer from the SQL database, - # then it probably means that you haven't indexed the database. See your - # SQL server documentation for more information. + # This problem is most often seen when using an SQL database. If it + # takes more than a second or two to receive an answer from the SQL + # database, then it probably means that you haven't indexed the + # database. See your SQL server documentation for more information. # # Useful range of values: `5` to `120` # timeout = 30 # - # Instead of requests being freed at the end of processing, they can be - # returned to a list of requests to reuse. + # Instead of requests being freed at the end of processing, they can + # be returned to a list of requests to reuse. # - # As with `request.max` reuse values apply on a per-worker basis, so the - # true number of cached requests is `request.reuse.max * `. + # As with `request.max` reuse values apply on a per-worker basis, so + # the true number of cached requests is `request.reuse.max * `. # reuse { # @@ -236,11 +235,10 @@ request { # # max:: The maximum number of reusable requests. # - # Any requests being processed by a worker beyond - # this number will cause a temporary request to be allocated. - # This is less efficient than the block allocation so - # `max` should be set to reflect the number of outstanding - # requests expected at peak load. + # Any requests being processed by a worker beyond this number will + # cause a temporary request to be allocated. This is less efficient + # than the block allocation so `max` should be set to reflect the + # number of outstanding requests expected at peak load. # # FIXME: Should likely default to request.max # @@ -249,9 +247,9 @@ request { # # cleanup_interval:: How often to free un-used requests. # - # Every `cleanup_interval` a cleanup routine runs which - # will free any blocks of handles which are not in use, - # ensuring that at least `min` handles are kept. + # Every `cleanup_interval` a cleanup routine runs which will free + # any blocks of handles which are not in use, ensuring that at + # least `min` handles are kept. # # This ensures that the server's memory usage does not remain # permanently bloated after a load spike. @@ -261,20 +259,21 @@ request { } # -# reverse_lookups:: Log the names of clients or just their IP addresses +# reverse_lookups:: Log the names of clients or just their IP +# addresses # # e.g., www.freeradius.org (`on`) or 206.47.27.232 (`off`). # # The default is `off` because it would be overall better for the net # if people had to knowingly turn this feature on, since enabling it # means that each client request will result in AT LEAST one lookup -# request to the nameserver. Enabling `hostname_lookups` will also +# request to the nameserver. Enabling `hostname_lookups` will also # mean that your server may stop randomly for `30` seconds from time # to time, if the DNS requests take too long. # # Turning hostname lookups off also means that the server won't block -# for `30` seconds, if it sees an IP address which has no name associated -# with it. +# for `30` seconds, if it sees an IP address which has no name +# associated with it. # # allowed values: {no, yes} # @@ -283,18 +282,18 @@ reverse_lookups = no # # hostname_lookups:: Global toggle for preventing hostname resolution # -# The default is `on` because people often use hostnames in configuration -# files. The main disadvantage of enabling this is the server may block -# at inopportune moments (like opening new connections) if the DNS servers -# are unavailable +# The default is `on` because people often use hostnames in +# configuration files. The main disadvantage of enabling this is the +# server may block at inopportune moments (like opening new +# connections) if the DNS servers are unavailable # # allowed values: {no, yes} # hostname_lookups = yes # -# Logging section. The various `log_*` configuration items -# will eventually be moved here. +# Logging section. The various `log_*` configuration items will +# eventually be moved here. # log { # @@ -316,19 +315,20 @@ log { destination = file # - # colourise:: Highlight important messages sent to stderr and stdout. + # colourise:: Highlight important messages sent to stderr and + # stdout. # - # Option will be ignored (disabled) if output of `TERM` is not - # an xterm or output is not to a TTY. + # Option will be ignored (disabled) if output of `TERM` is not an + # xterm or output is not to a TTY. # colourise = yes # # timestamp:: Add a timestamp to the start of every log message. # - # By default this is done with log levels of `-Xx` or `-xxx` - # where the destination is not syslog, or at all levels where the - # output is a file. + # By default this is done with log levels of `-Xx` or `-xxx` where + # the destination is not syslog, or at all levels where the output + # is a file. # # The config option below forcefully enables or disables timestamps # irrespective of the log destination. @@ -341,53 +341,50 @@ log { # file:: The logging messages for the server are appended to the # tail of this file `if ${destination} == "file"` # - # NOTE: If the server is running in debugging mode, this file is - # NOT used. + # NOTE: If the server is running in debugging mode, this file is NOT + # used. # file = ${logdir}/radius.log # - # syslog_facility:: Which syslog facility to use, `if ${destination} == "syslog"`. + # syslog_facility:: Which syslog facility to use, `if ${destination} + # == "syslog"`. # - # The exact values permitted here are _OS-dependent_. You probably + # The exact values permitted here are _OS-dependent_. You probably # don't want to change this. # syslog_facility = daemon - # suppress_secrets:: Suppress "secret" values when printing - # them in debug mode. + # suppress_secrets:: Suppress "secret" values when printing them in + # debug mode. # # NOTE: Note that when running the server at debug level 3 or # higher, this configuration ite, is ignored. # - # Setting this to `yes` means that the server does not print - # the contents of "secret" values such as passwords. It - # instead prints a place-holder value "<<< secret >>>", as - # follows: + # Setting this to `yes` means that the server does not print the + # contents of "secret" values such as passwords. It instead prints a + # place-holder value "<<< secret >>>", as follows: # # ``` # User-Password = "<<< secret >>>" # ``` # # Secret values are tracked across string expansions, string - # modifications, concatenations, etc. i.e. if a - # `User-Password` is placed into a `Reply-Message`, then the - # value of the `Reply-Message` will also be marked as - # "secret". - # - # This configuration is enabled by default. While doing this - # can make it harder to debug the server (as passwords are - # omitted from the debug output), the servers defaults are as - # secure as possible. - # - # In many cases it is not useful to suppress secrets in an - # attempt to "be more secure". Any administrator who can see - # the debug ouput is usually also able to view and/or modify - # the servers configuration (including passwords in - # databases!). And any "low level" administrator who can - # only see the debug output will usually need to see the - # actual passwords in order to verify what the user is - # entering. + # modifications, concatenations, etc. i.e. if a `User-Password` is + # placed into a `Reply-Message`, then the value of the + # `Reply-Message` will also be marked as "secret". + # + # This configuration is enabled by default. While doing this can + # make it harder to debug the server (as passwords are omitted from + # the debug output), the servers defaults are as secure as possible. + # + # In many cases it is not useful to suppress secrets in an attempt + # to "be more secure". Any administrator who can see the debug ouput + # is usually also able to view and/or modify the servers + # configuration (including passwords in databases!). And any "low + # level" administrator who can only see the debug output will + # usually need to see the actual passwords in order to verify what + # the user is entering. # suppress_secrets = yes } @@ -405,9 +402,9 @@ log { # * set the debug level for this request to '2' # * over-ride the log file, and set it to be based on the `User-Name`. # -# The file will be closed when the request exits. It is the admins -# responsibility to ensure that the debug files are periodically cleaned up. -# The server does not do this automatically. +# The file will be closed when the request exits. It is the admins +# responsibility to ensure that the debug files are periodically +# cleaned up. The server does not do this automatically. # # %file.rm("${logdir}/debug/%{User-Name}.log") # %log.destination('debug', 2, "${logdir}/debug/%{User-Name}.log") @@ -422,26 +419,26 @@ log debug { # = ENVIRONMENT VARIABLES # # You can reference environment variables using an expansion like -# `$ENV{PATH}`. However it is sometimes useful to be able to also set -# environment variables. This section lets you do that. +# `$ENV{PATH}`. However it is sometimes useful to be able to also set +# environment variables. This section lets you do that. # # The main purpose of this section is to allow administrators to keep # RADIUS-specific configuration in the RADIUS configuration files. # For example, if you need to set an environment variable which is -# used by a module. You could put that variable into a shell script, -# but that's awkward. Instead, just list it here. +# used by a module. You could put that variable into a shell script, +# but that's awkward. Instead, just list it here. # # Note that these environment variables are set AFTER the -# configuration file is loaded. So you cannot set FOO here, and -# expect to reference it via `$ENV{FOO}` in another configuration file. -# You should instead just use a normal configuration variable for -# that. +# configuration file is loaded. So you cannot set FOO here, and +# expect to reference it via `$ENV{FOO}` in another configuration +# file. You should instead just use a normal configuration variable +# for that. # ENV { # # Set environment variable `FOO` to value '/bar/baz'. # - # NOTE: Note that you MUST use '='. You CANNOT use '+=' to append + # NOTE: Note that you MUST use '='. You CANNOT use '+=' to append # values. # # FOO = '/bar/baz' @@ -461,10 +458,10 @@ ENV { # KRB5_CLIENT_KTNAME = ${confdir}/radiusd.keytab # - # `LD_PRELOAD` is special. It is normally set before the - # application runs, and is interpreted by the dynamic linker. - # Which means you cannot set it inside of an application, and - # expect it to load libraries. + # `LD_PRELOAD` is special. It is normally set before the application + # runs, and is interpreted by the dynamic linker. Which means you + # cannot set it inside of an application, and expect it to load + # libraries. # # Since this functionality is useful, we extend it here. # @@ -472,9 +469,9 @@ ENV { # # LD_PRELOAD = /path/to/library.so # - # and the server will load the named libraries. Multiple - # libraries can be loaded by specificing multiple individual - # `LD_PRELOAD` entries. + # and the server will load the named libraries. Multiple libraries + # can be loaded by specificing multiple individual `LD_PRELOAD` + # entries. # # # LD_PRELOAD = /path/to/library1.so @@ -485,7 +482,7 @@ ENV { # = Templates # # Template files hold common definitions that can be used in other -# server sections. When a template is referenced, the configuration +# server sections. When a template is referenced, the configuration # items within the referenced template are copied to the referencing # section. # @@ -502,26 +499,25 @@ templates { # # = Security Configuration # -# There may be multiple methods of attacking on the server. This -# section holds the configuration items which minimize the impact -# of those attacks +# There may be multiple methods of attacking on the server. This +# section holds the configuration items which minimize the impact of +# those attacks # security { # # user:: # - # The name (or `#number`) of the `user` to use as the uid of - # the server. + # The name (or `#number`) of the `user` to use as the uid of the + # server. # - # If the user/group fields are commented out, the server will - # run as the user/group that started it. In order to change - # to a different user/group, the server MUST start as root - # (or have permissions to change UID / GID) + # If the user/group fields are commented out, the server will run as + # the user/group that started it. In order to change to a different + # user/group, the server MUST start as root (or have permissions to + # change UID / GID) # # We STRONGLY recommend that you run the server with as few - # permissions as possible. That is, if you're not using - # shadow passwords, the `user` and `group` items should be - # set to `radius`. + # permissions as possible. That is, if you're not using shadow + # passwords, the `user` and `group` items should be set to `radius`. # # user = radius @@ -530,32 +526,30 @@ security { # # The name (or `#number`) of the `user` to use as the gid. # - # See the `user` configuration above for additional - # information. + # See the `user` configuration above for additional information. # - # NOTE: Some kernels refuse to `setgid(group)` when the - # value of (unsigned)group is above 60000; don't use group - # `nobody` on these systems! + # NOTE: Some kernels refuse to `setgid(group)` when the value of + # (unsigned)group is above 60000; don't use group `nobody` on these + # systems! # - # On systems with shadow passwords, you might have to set - # `group = shadow` for the server to be able to read the - # shadow password file. If you can authenticate users while - # in debug mode, but not in daemon mode, it may be that the - # debugging mode server is running as a user that can read - # the shadow info, and the user listed below can not. + # On systems with shadow passwords, you might have to set `group = + # shadow` for the server to be able to read the shadow password + # file. If you can authenticate users while in debug mode, but not + # in daemon mode, it may be that the debugging mode server is + # running as a user that can read the shadow info, and the user + # listed below can not. # - # The server will also try to use `initgroups` to read - # /etc/groups. It will join all groups where "user" is a - # member. This can allow for some finer-grained access - # controls. + # The server will also try to use `initgroups` to read /etc/groups. + # It will join all groups where "user" is a member. This can allow + # for some finer-grained access controls. # # group = radius # - # After the server has changed to the final user/group, it - # can also set the current working directory. While not - # necessary, changing the working directory means that the - # server does not have any dangling paths. + # After the server has changed to the final user/group, it can also + # set the current working directory. While not necessary, changing + # the working directory means that the server does not have any + # dangling paths. # # The directory here should either be "/", or ${confdir} # @@ -564,23 +558,22 @@ security { # # limit files:: Limit the directories for function calls # - # The server provides functions such as %file.touch() to read - # files, write files, make directories, etc. For security, - # this ability can be limited to specific directories. + # The server provides functions such as %file.touch() to read files, + # write files, make directories, etc. For security, this ability can + # be limited to specific directories. # - # If this section is missing, then the server allows the - # %file...() APIs to read and write any directory. + # If this section is missing, then the server allows the %file...() + # APIs to read and write any directory. # - # If the section exists but is empty, then the server does - # not allow the %file...() APIs to read and write any - # directory. + # If the section exists but is empty, then the server does not allow + # the %file...() APIs to read and write any directory. # - # Note that you should NOT list ${confdir} here. The - # configuration files should NEVER be writable by the server. + # Note that you should NOT list ${confdir} here. The configuration + # files should NEVER be writable by the server. # # If this section is configured, then these limits are always - # applied, even if the filename comes from the configuration - # files, and would normally be considered "safe". + # applied, even if the filename comes from the configuration files, + # and would normally be considered "safe". # limit files { allow = ${logdir} @@ -590,20 +583,19 @@ security { # # limit exec:: Limit the programs which can be executed # - # The server provides functions such as %exec() to run - # external programs. For security, this ability can be - # limited to specific directories. + # The server provides functions such as %exec() to run external + # programs. For security, this ability can be limited to specific + # directories. # - # If this section is missing, then the server allows the - # %exec() APIs to run any program on the system. + # If this section is missing, then the server allows the %exec() + # APIs to run any program on the system. # - # If this section exists but is empty, then the server does - # not allow the %exec() APIs to run any program. + # If this section exists but is empty, then the server does not + # allow the %exec() APIs to run any program. # limit exec { # - # The entries here can be directories or specific - # programs. + # The entries here can be directories or specific programs. # allow = "/bin" allow = "/usr/bin" @@ -612,24 +604,24 @@ security { # # allow_core_dumps:: Core dumps are a bad thing. # - # This should only be set to `yes` if you're debugging - # a problem with the server. + # This should only be set to `yes` if you're debugging a problem + # with the server. # # allowed values: {no, yes} # allow_core_dumps = @allow_core_dumps@ # - # max_attributes:: The maximum number of attributes - # permitted in a RADIUS packet. Packets which have MORE - # than this number of attributes in them will be dropped. + # max_attributes:: The maximum number of attributes permitted in a + # RADIUS packet. Packets which have MORE than this number of + # attributes in them will be dropped. # - # If this number is set too low, then no RADIUS packets - # will be accepted. + # If this number is set too low, then no RADIUS packets will be + # accepted. # - # If this number is set too high, then an attacker may be - # able to send a small number of packets which will cause - # the server to use all available memory on the machine. + # If this number is set too high, then an attacker may be able to + # send a small number of packets which will cause the server to use + # all available memory on the machine. # # Setting this number to 0 means "allow any number of attributes" # @@ -645,9 +637,9 @@ security { # # [WARNING] # ==== -# The `clients.conf` file contains all of the information from the old -# `clients` and `naslist` configuration files. We recommend that you -# do NOT use `client's` or `naslist`, although they are still +# The `clients.conf` file contains all of the information from the +# old `clients` and `naslist` configuration files. We recommend that +# you do NOT use `client's` or `naslist`, although they are still # supported. # # Anything listed in 'clients.conf' will take precedence over the @@ -659,7 +651,7 @@ $INCLUDE clients.conf # # = Thread Pool Configuration # -# In v4, the thread pool does not change size dynamically. Instead, +# In v4, the thread pool does not change size dynamically. Instead, # there are a small number of threads which read from the network, # and a slightly larger number of threads which process a request. # @@ -670,35 +662,34 @@ thread pool { # num_networks = 1 # - # num_workers:: The worker threads can be varied. It should be - # at least one, and no more than 128. Since each request is - # non-blocking, there is no reason to run hundreds of threads - # as in v3. + # num_workers:: The worker threads can be varied. It should be at + # least one, and no more than 128. Since each request is + # non-blocking, there is no reason to run hundreds of threads as in + # v3. # - # Defaults to the number of cores available on the system, or, - # 1, if this cannot be determined. + # Defaults to the number of cores available on the system, or, 1, if + # this cannot be determined. # # num_workers = 1 # # openssl_async_pool_init:: Controls the initial number of async - # contexts that are allocated when a worker thread is created. - # One async context is required for every TLS session (every - # RADSEC connection, every TLS based method still in progress). + # contexts that are allocated when a worker thread is created. One + # async context is required for every TLS session (every RADSEC + # connection, every TLS based method still in progress). # # openssl_async_pool_init = 64 # # openssl_async_pool_max:: Controls the maximum number of async - # contexts which are allocated to a worker thread. - # If the maximum is reached, then no more TLS sessions can be - # created. + # contexts which are allocated to a worker thread. If the maximum is + # reached, then no more TLS sessions can be created. # - # NOTE: Setting this to 0 will mean unlimited async contexts - # will be created. But as of 3.0.0, OpenSSL has no mechanism - # to shrink the async pool. This means if there's a - # significant traffic spike the process will continue to use - # large amounts of memory until it's restarted. + # NOTE: Setting this to 0 will mean unlimited async contexts will be + # created. But as of 3.0.0, OpenSSL has no mechanism to shrink the + # async pool. This means if there's a significant traffic spike the + # process will continue to use large amounts of memory until it's + # restarted. # # openssl_async_pool_max = 1024 } @@ -706,17 +697,17 @@ thread pool { # # = Triggers and SNMP notifications. # -# Uncomment the following line to enable snmptraps. Note that you -# MUST also configure the full path to the `snmptrap` command in -# the `trigger.conf` file. +# Uncomment the following line to enable snmptraps. Note that you +# MUST also configure the full path to the `snmptrap` command in the +# `trigger.conf` file. # -#$INCLUDE trigger.conf +# $INCLUDE trigger.conf # # .= Global Library Settings # -# Each library which has global settings will have its own configuration -# file in global.d +# Each library which has global settings will have its own +# configuration file in global.d # global { $INCLUDE global.d/ @@ -725,13 +716,14 @@ global { # # = Migration Flags # -# These flags are only for the "alpha" release of v4. They will be +# These flags are only for the "alpha" release of v4. They will be # removed (and made into errors!) in the final release. # -# Some of these flags can also be passed on the command line as -# `-S flag=value`. +# Some of these flags can also be passed on the command line as `-S +# flag=value`. # -# Dictionary migration instructions can be found in `${confdir}/dictionary`. +# Dictionary migration instructions can be found in +# `${confdir}/dictionary`. # migrate { } @@ -739,10 +731,11 @@ migrate { # # = Module Configuration # -# The names and configuration of each module is located in this section. +# The names and configuration of each module is located in this +# section. # -# After the modules are defined here, they may be referred to by name, -# in other sections of this configuration file. +# After the modules are defined here, they may be referred to by +# name, in other sections of this configuration file. # modules { # @@ -755,44 +748,42 @@ modules { # } # ``` # - # The `name` is used to load the `rlm_name` library - # which implements the functionality of the module. + # The `name` is used to load the `rlm_name` library which implements + # the functionality of the module. # - # The 'instance' is optional. To have two different instances - # of a module, it first must be referred to by 'name'. - # The different copies of the module are then created by - # inventing two 'instance' names, e.g. 'instance1' and 'instance2' + # The 'instance' is optional. To have two different instances of a + # module, it first must be referred to by 'name'. The different + # copies of the module are then created by inventing two 'instance' + # names, e.g. 'instance1' and 'instance2' # - # The instance names can then be used in later configuration - # INSTEAD of the original 'name'. e.g. instead of `pap { ...}`, - # you can use `pap other {...}`. The `other` name will then be - # a reference to the second PAP module. + # The instance names can then be used in later configuration INSTEAD + # of the original 'name'. e.g. instead of `pap { ...}`, you can use + # `pap other {...}`. The `other` name will then be a reference to + # the second PAP module. # # # Some modules have ordering issues. # - # e.g. `sqlippool` uses the configuration from `sql`. - # In that case, the `sql` module must be read off of disk before - # the `sqlippool`. + # e.g. `sqlippool` uses the configuration from `sql`. In that case, + # the `sql` module must be read off of disk before the `sqlippool`. # - # However, the directory inclusion below just reads the - # directory from start to finish. Which means that the - # modules are read off of disk randomly. + # However, the directory inclusion below just reads the directory + # from start to finish. Which means that the modules are read off of + # disk randomly. # # As of `>= 3.0.18`, you can list individual modules *before* the - # directory inclusion. Those modules will be loaded first. - # Then, when the directory is read, those modules will be - # skipped and not read twice. + # directory inclusion. Those modules will be loaded first. Then, + # when the directory is read, those modules will be skipped and not + # read twice. # # $INCLUDE mods-enabled/sql # - # Modules are in mods-enabled/. Files matching - # the regex /[a-zA-Z0-9_.]+/ are loaded. The modules are - # initialized ONLY if they are referenced in a processing - # section, such as authorize, authenticate, accounting, - # pre/post-proxy, etc. + # Modules are in mods-enabled/. Files matching the regex + # /[a-zA-Z0-9_.]+/ are loaded. The modules are initialized ONLY if + # they are referenced in a processing section, such as authorize, + # authenticate, accounting, pre/post-proxy, etc. # $INCLUDE mods-enabled/ } @@ -802,9 +793,9 @@ modules { # # Policies are virtual modules. # -# Defining a policy in one of the `policy.d` files means that it can be -# referenced in multiple places as a *name*, rather than as a series of -# conditions to match, and actions to take. +# Defining a policy in one of the `policy.d` files means that it can +# be referenced in multiple places as a *name*, rather than as a +# series of conditions to match, and actions to take. # # Policies are something like subroutines in a normal language, but # they cannot be called recursively. They MUST be defined in order. @@ -817,11 +808,11 @@ policy { # # = Load virtual servers. # -# This next $INCLUDE line loads files in the directory that -# match the regular expression: /[a-zA-Z0-9_.]+/ +# This next $INCLUDE line loads files in the directory that match the +# regular expression: /[a-zA-Z0-9_.]+/ # -# It allows you to define new virtual servers simply by placing -# a file into the sites-enabled/ directory. +# It allows you to define new virtual servers simply by placing a +# file into the sites-enabled/ directory. # # All of the other configuration sections like: # @@ -834,8 +825,8 @@ policy { # `sites-available/default` # # This is the `default` virtual server that has the same -# configuration as in version 1.0.x and 1.1.x. The default -# installation enables this virtual server. You should -# edit it to create policies for your local site. +# configuration as in version 1.0.x and 1.1.x. The default +# installation enables this virtual server. You should edit it to +# create policies for your local site. # $INCLUDE sites-enabled/