The load-balance Statement

Syntax

load-balance [ <name> ] [ <key> ] {
    [ statements ]
}

The load-balance section is similar to the redundant section except that only one statement in the subsection is ever called.

In general, the redundant-load-balance statement is more useful than this one.

<name>: The instance name of the load-balance section. This name is only used when the load-balance keyword is used inside of a virtual module. In other situations, it is not permitted.

The name must be a fixed string.
<key>: An attribute reference or expansion which will be hashed in order to select the statement to execute. Fixed strings or data are not permitted, as that would cause load-balancing to always select the same statement.

The hash will be used to pick a particular statement within the load-balance section. This "keyed" load-balance can be used to deterministically shard requests across multiple modules.

When the <key> field is omitted, or the key is not found, the a random statement is chosen instead.
[ statements ]: One or more unlang commands. Only one of the statements is executed.

The statements should all be different. Attribute assignments should be placed inside of a group section, otherwise an error will be generated.

Examples

load-balance User-Name {
    sql1
    sql2
}

Virtual Modules

It can be useful to use the same load-balance section in multiple places. Instead of copying the same text multiple times, a load-balance section can be defined as a module in the mods-enabled/ directory.

For example, the following text can be placed into the file mods-enabled/sql_all. Once it is there, it can be used as a module named sql_all, and used anywhere a module is allowed to use.

Example of Load-Balance SQL module

load-balance sql_all {
    sql1
    sql2
    sql3
}

In previous versions of the server, this definition would be placed into the instantiate section of radiusd.conf. This configuration is no longer used, and the `sql_all definition can just be placed as a module definition into the mods-enabled/ directory.

Load-Balance Expansions

When the sql_all module is defined as above, it can also be used as in a dynamic expansion:

Example of Load-Balance SQL module

Reply-Message := %sql_all("SELECT message FROM table WHERE name='%{User-Name}'")
}

The expansion works exactly like a load-balance block. One of the modules is chosen to run the expansion, in load-balance fashion.