The abbreviation "uci" stands for "Unified Configuration Interface" and is intended to centralize the whole configuration of your OpenWrt. Configuring should be easy, more straight forward and documented here, thereby making your life easier! (It is the successor of the nvram based configuration found in the White Russian series of OpenWrt.)

Many programs have their own config-file lying around somewhere, like /etc/network/interfaces or /etc/exports or /etc/dnsmasq.conf /etc/samba/samba.conf and sometimes they use slightly different syntaxes. On OpenWrt you don't have to bother with them, we only edit the uci-files!

You do not have to reboot your system for a change to take place! Look further down below command.line.utility: how it is done.

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. Editing the configuration files is possible with a text editor, the "uci" utility program or 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

uci commit uhttpd

And then a

sh /etc/init.d/uhttpd restart

Done. No reboot needed.

root@OpenWrt:~# uci export httpd package 'httpd' config 'httpd' option 'port' '80' option 'home' '/www' root@OpenWrt:~#

root@OpenWrt:~# uci show httpd httpd.@httpd[0]=httpd httpd.@httpd[0].port=80 httpd.@httpd[0].home=/www root@OpenWrt:~#

root@OpenWrt:~# uci get httpd.@httpd[0].port 80 root@OpenWrt:~#

root@OpenWrt:~# uci -P/var/state show network.wan network.wan=interface network.wan.ifname=eth0.1 network.wan.proto=dhcp network.wan.defaultroute=0 network.wan.peerdns=0 network.wan.device=eth0.1 network.wan.ipaddr=10.11.12.13 network.wan.broadcast=255.255.255.255 network.wan.netmask=255.255.255.0 network.wan.gateway=10.11.12.1 network.wan.dnsdomain= network.wan.dns=10.11.12.100 10.11.12.200 network.wan.up=1 network.wan.lease_gateway=10.11.12.1 network.wan.lease_server=10.11.12.25 network.wan.lease_acquired=1262482940 network.wan.lease_lifetime=5400 network.wan.lease_hostname=x-10-11-12-13 root@OpenWrt:~#

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.

root@OpenWrt:~# uci add firewall rule root@OpenWrt:~# uci set firewall.@rule[-1].src=wan root@OpenWrt:~# uci set firewall.@rule[-1].target=ACCEPT root@OpenWrt:~# uci set firewall.@rule[-1].proto=tcp root@OpenWrt:~# uci set firewall.@rule[-1].dest_port=22 root@OpenWrt:~# uci commit firewall root@OpenWrt:~# /etc/init.d/firewall restart