The abbreviation UCI stands for Unified Configuration Interface and is intended to centralize the configuration of OpenWrt.

Configuration should be easy, straightforward and documented here, making life easier! UCI is the successor to the NVRAM-based configuration found in the White Russian series of OpenWrt.

Many programs have their own configuration files lying around somewhere, like /etc/network/interfaces, /etc/exports, /etc/dnsmasq.conf or /etc/samba/samba.conf and they often use different syntaxes. With OpenWrt you don't have to bother with any of them and only need to change the UCI configuration files.

You no longer have to reboot your system to make configuration changes. You can use the UCI command line utility instead. And please do not forget that quite some daemons are included in the official binaries, but they are not enabled by default! For example the cron daemon is not activated by default, thus only editing the crontab won't do anything. You have to either start the daemon with /etc/init.d/cron start or enable it with /etc/init.d/cron enable. You can disable, stop and restart most of those daemons, too. There are some not UCI configuration files you may want to tend to.

OpenWrt's central configuration is split into several files located in the /etc/config/ directory. Each file roughly relates to the part of the system it configures. You can edit the configuration files with a text editor or with the command line utility program uci or through various programming APIs (like Shell, Lua and C).

The uci configuration files usually consist of one or more config statements, so called sections with one or more option statements defining the actual values.

Below is an example of a simple configuration file:

package 'example'

config 'example' 'test'
        option   'string'      'some value'
        option   'boolean'     '1'
        list     'collection'  'first item'
        list     'collection'  'second item'

• The config 'example' 'test' statement defines the start of a section with the type example and the name test. There can also be so called anonymous sections with only a type, but no name identifier. The type is important for the processing programs to decide how to treat the enclosed options.

• The option 'string' 'some value' and option 'boolean' '1' lines define simple values within the section. Note that there are no syntactical differences between text- and boolean options. Per convention, boolean options may have one of the values '0', 'no', 'off' or 'false' to specify a false value or '1' , 'yes', 'on' or 'true' to specify a true value.

• In the lines starting with a list keyword an option with multiple values is defined. All list statements that share the same name, collection in our example, will be combined into a single list of values with the same order as in the configuration file.

• The indentination of the option and list statements is a convention to improve the readability of the configuration file but it's not syntactically required.

Usually you do not need to enclose identifiers or values in quotes. Quotes are only required if the enclosed value contains spaces or tabs. Also it's legal to use double- instead of single-quotes when typing configuration options.

All of the examples below are valid uci syntax:

• option example value
• option 'example' value
• option example "value"
• option "example" 'value'
• option 'example' "value"

In contrast, the following examples are not valid syntax:

• option 'example" "value' (quotes are unbalanced)
• option example some value with space (note the missing quotes around the value)

It is important to know that UCI identifiers and config file names may only contain the characters a-z, 0-9 and _. Option values may contain any character (as long they are properly quoted).

It is redundant, unwise, and inefficient to use awk and grep to parse OpenWrt's config files. Use the uci utility instead to get what you need!

Below is the usage, as well as some useful examples of how to use this powerful utility. Remember, friends don't let friends parse their own config files!

When there are multiple rules next to each other, uci uses array-like references for them. If there are 8 NTP servers, uci will let you reference their sections as timeserver.@timeserver[0] for the first or timeserver.@timeserver[7] for the last one. You can also use negative indexes, such as timeserver.@timeserver[-1]. "-1" means "the last one, and "-2" means the second-to-last one. This comes in very handy when appending new rules to the end of a list. See examples below.

root@OpenWrt:/lib/config# uci

Usage: uci [<options>] <command> [<arguments>]

Commands:
	batch
	export     [<config>]
	import     [<config>]
	changes    [<config>]
	commit     [<config>]
	add        <config> <section-type>
	add_list   <config>.<section>.<option>=<string>
	show       [<config>[.<section>[.<option>]]]
	get        <config>.<section>[.<option>]
	set        <config>.<section>[.<option>]=<value>
	delete     <config>[.<section[.<option>]]
	rename     <config>.<section>[.<option>]=<name>
	revert     <config>[.<section>[.<option>]]

Options:
	-c <path>  set the search path for config files (default: /etc/config)
	-d <str>   set the delimiter for list values in uci show
	-f <file>  use <file> as input instead of stdin
	-m         when importing, merge data into an existing package
	-n         name unnamed sections on export (default)
	-N         don't name unnamed sections
	-p <path>  add a search path for config change files
	-P <path>  add a search path for config change files and use as default
	-q         quiet mode (don't print error messages)
	-s         force strict mode (stop on parser errors, default)
	-S         disable strict mode
	-X         do not use extended syntax on 'show'

After changing the port uhttpd listens on from 80 to 8080 in the file /etc/config/uhttpd, save it. Then do

And then a

Done. No reboot needed.

Consider this example config file:

Then the paths below are equal in every group:

If you show it, you get :

But if you used "uci show foo.@bar[0]", you will see:

# uci show foo.@bar[0] foo.first=bar foo.first.name=Mr. First

This is a good example of both adding a firewall rule to forward the TCP SSH port, and of the negative (-1) syntax used with uci.

• Backfire

  uci -P/var/state get network.wan.ipaddr

• Trunk (not really uci)

  . /lib/functions/network.sh; network_get_ipaddr ip wan; echo $ip

 uci get wireless.@wifi-iface[-1].ssid

To set some system defaults the first time the device boots, create a script in the folder

/etc/uci-defaults/

• https://forum.openwrt.org/viewtopic.php?id=15243