The load-balance Statement

Syntax

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

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

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

<key>: An attribute reference or expansion which will be hashed in order to select the statement to execute.

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, the module is chosen randomly, in a "load balanced" manner.
[ statements ]: One or more unlang commands. Only one of the statements is executed.

Examples

load-balance &User-Name {
    sql1
    sql2
}

load-balance Sections as 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/sql123. Once it is there, it can be used as a module named sql123, and used anywhere a module is allowed to use.

Example of Load-Balance SQL module

load-balance sql123 {
    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 `sql123 definition can just be placed as a module definition into the mods-enabled/ directory.

Load-Balance Expansions

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

Example of Load-Balance SQL module

&Reply-Message := %sql123("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.