Die Abkürzung steht für “Unified Configuration Interface” was sich in etwa mit “Schnittstelle zur vereinheitlichten Konfiguration” übersetzen lässt. Das UCI besteht aus etlichen Skripten, die dazu dienen die UCI-Konfigurationsdateien in die eigentlichen Konfigurationsdateien zu übersetzen bzw. den jeweiligen daemon mit den eingestellten Befehlszeilenparametern zu starten. Der Zweck besteht darin, möglichst die komplette Konfiguration von OpenWrt zu zentralisieren, zu entmystifizieren und zu vereinfachen. Die Konfiguration wird hier erklärt und sollte anschließend gerade heraus und einfach vonstatten gehen.

Viele Programme habe ihre Konfigurationsdateien in /etc/, wie z.B. /etc/network/interfaces oder /etc/exports oder /etc/dnsmasq.conf oder /etc/samba/samba.conf. Sie sind oft zwar ähnlich aufgebaut aber die Syntax unterscheidet sich doch gelegentlich. Unter OpenWrt müssen wir uns damit nicht mehr auseinandersetzen, sondern erledigen möglichst alles im UCI mit Hilfe dieses Wikis.

Hinweis Sie müssen nicht jedes mal, wenn Sie Änderungen vorgenommen haben, Ihren Router rebooten! Lesen Sie mehr dazu weiter unten command.line.utility:.

Die Konfiguration wird in mehreren Dateien vorgenommen, die sich alle im Verzeichnis /etc/config befinden. Die Dateinamen entsprechen jeweils grob dem System, welches sie konfigurieren. Es handelt sich um ganz gewöhnliche Text-Dateien, die mit jedem Texteditor, mit dem UCI-eigenen utility Programm und natürlich auch mit diversen programmier-APIs (wie Shell, Lua, C) editiert werden können.

Die UCI-Konfiguration besteht aus einer oder mehreren Sektionen, die jeweils mehrere Optionen haben.

Hier ein Beispiel:

Paket 'beispiel'

config 'beispiel' 'grob'
        option   'string'      'Folge von Zeichen'
        option   'boolean'     '1'
        list     'collection'  'erstes item'
        list     'collection'  'zweites 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:~#

Notiz: Die UCI-Status-Variablen sind veraltet und werden nicht mehr für Netzwerk-basierte Informationen benutzt. Man nehme stattdessen /lib/functions/network.sh:

. /lib/functions/network.sh; network_get_device if_wan wan; echo $if_wan

In r36817 verfügbar sind:

network_get_ipaddr
network_get_ipaddr6
network_get_subnet
network_get_subnet6
network_get_prefix6
network_get_gateway
network_get_gateway6
network_get_dnsserver
network_get_dnssearch
network_get_device
network_get_physdev

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