OpenWrt offers a set of standard shell procedures to interface with UCI in order to efficiently read and process configuration files from within shell scripts.

To be able to load UCI configuration files, you need to include the common functions with:

Then you can use config_load name to load config files.

The function first checks for name as absolute filename and falls back to loading it from /etc/config/ (which is the most common way of using it).

If you want to use special callbacks for sections and/or options, you need to redefine the shell functions explained below before running config_load, but after including /etc/functions.sh.

The config_cb procedure is called every time a UCI section heading is encountered during parsing.

When called, the procedure receives two arguments:

1. Type, the section type, e.g. interface for config interface wan
2. Name, the section name, e.g. wan for config interface wan or an autogenerated ID like cfg13abef for anonymous sections like config route

Similar to config_cb, the option_cb procedure is called each time a UCI option (or list) is encountered.

When called, the procedure receives two arguments:

1. Name, the option name, e.g. ifname for option ifname eth0
2. Value, the option value, e.g. eth0 for option ifname eth0

You can also alter option_cb from config_cb based on the section type. This allows you to process every single config section based on its type individually.

Within the callbacks, the ID of the current section is accessible via the CONFIG_SECTION variable. Also an extra call to config_cb (without a new section) is generated after config_load is done - this allows you to process sections both before and after all options were processed.

An alternative approach to callback based parsing is iterating the configuration sections with the config_foreach procedure.

The config_foreach procedure takes at least one argument:

1. Function, name of a previously defined procedure called for each encountered section
2. Type (optional), only iterate sections of the given type, skip others
3. Additional arguments (optional), all following arguments are passed to the callback procedure as-is

In the example below, the handle_interface procedure is called for each config interface section in /etc/config/network. The string test is passed as second argument on each invocation.

It is possible to abort the iteration from within the callback by returning a non-zero value (return 1).

Within the per-section callback, the config_get or config_set procedures may be used to read or set values belonging to the currently processed section.

The config_get procedure takes at least three arguments:

1. Name of a variable to store the retrieved value in
2. ID of the section to read the value from
3. Name of the option to read the value from
4. Default (optional), value to return instead if option is unset

The config_set procedure takes three arguments:

1. ID of the section to set the option in
2. Name of the option to assign the value to
3. Value to assign

Note that values changed with config_set are only kept in memory. Subsequent calls to config_get will return the updated values but the underlying configuration files are not altered. If you want to alter values, use the uci_* functions from /lib/config/uci.sh which are automatically included by /etc/functions.sh.

If the name of a configuration section is known in advance (it is named), options can be read directly without using a section iterator callback.

The example below reads "option proto" from the "config interface wan" section.

Some UCI configurations may contain list options in the form:

Calling config_get on the network list will return the list values separated by space, lan wifi in this example.

However, this behaviour might break values if the list items itself contain spaces like illustrated below:

The config_get approach would return the values in the form White Elephant Mighty Unicorn and the original list items are not clearly separated anymore.

To circumvent this problem, the config_list_foreach iterator can be used. It works similar to config_foreach but operates on list values instead of config sections.

The config_list_foreach procedure takes at least three arguments:

1. ID of the section to read the list from
2. Name of the list option to read items from
3. Procedure to call for each list item
4. Additional arguments (optional), all following arguments are passed to the callback procedure as-is

Boolean options may contain various values to signify a true value like on, true, enabled or 1.

The config_get_bool procedure simplifies the process of reading a boolean option and casting it to a plain integer value (1 for true and 0 for false).

At least three arguments are expected by the procedure:

1. Name of a variable to store the retrieved value in
2. ID of the section to read the value from
3. Name of the option to read the value from
4. Default (optional), boolean value to return if option is unset