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/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
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).
|/etc/config/dhcp||Dnsmasq configuration and DHCP settings|
|/etc/config/dropbear||SSH server options|
|/etc/config/firewall||NAT, packet filter, port forwarding, etc.|
|/etc/config/network||Switch, interface and route configuration|
|/etc/config/system||Misc. system settings|
|/etc/config/timeserver||Time server list for rdate|
|/etc/config/wireless||Wireless settings and wifi network definition|
|/etc/config/6relayd||IPv6-Server and Relay (RD, DHCPv6 & NDP)|
|/etc/config/ahcpd||Ad-Hoc Configuration Protocol (AHCP) server and forwarder configuration|
|/etc/config/aiccu||AICCU client configuration|
|/etc/config/gw6c||GW6c client configuration|
|/etc/config/radvd||Router Advertisement (radvd) configuration|
|/etc/config/bbstored||BoxBackup server configuration|
|/etc/config/fstab||Mount points and swap|
|/etc/config/hd-idle||Another idle-daemon for attached hard drives|
|/etc/config/httpd||Web server options (Busybox httpd, deprecated)|
|/etc/config/luci||Base LuCI config|
|/etc/config/luci_statistics||Configuration of Statistics packet|
|/etc/config/mjpg-streamer||Streaming application for Linux-UVC compatible webcams|
|/etc/config/mountd||OpenWrt automount daemon|
|/etc/config/mroute||Configuration files for multiple WAN routes|
|/etc/config/multiwan||Simple multi WAN configuration|
|/etc/config/ntpclient||Getting the correct time|
|/etc/config/p910nd||config for non-spoooling Printer daemon p910nd.server|
|/etc/config/pure-ftpd||Pure-FTPd server config|
|/etc/config/qos||Implementing Quality of Service for the upload|
|/etc/config/racoon||racoon IPsec daemon|
|/etc/config/samba||settings for the Microsoft file and print services daemon|
|/etc/config/sshtunnel||Settings for the package
|/etc/config/stund||STUN server configuration|
|/etc/config/uhttpd||Web server options (uHTTPd)|
|/etc/config/upnpd||miniupnpd UPnP server settings|
|/etc/config/users||user database for different services|
|/etc/config/ushare||uShare UPnP server settings|
|/etc/config/vblade||vblade userspace AOE target|
|/etc/config/vnstat||vnstat downloader settings|
|/etc/config/wifitoggle||Script to toogle WiFi with a button|
|/etc/config/wshaper||wondershaper qos script settings|
|/etc/config/znc||ZNC bouncer configuration|
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'
config 'example' 'test'statement defines the start of a section with the type
exampleand 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.
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
listkeyword an option with multiple values is defined. All
liststatements that share the same name,
collectionin our example, will be combined into a single list of values with the same order as in the configuration file.
- The indentination of the
liststatements 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
_. 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 for the first or timeserver.@timeserver 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.
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'
||Writes changes of the given configuration file, or if none is given, all configration files, to the filesystem. All "uci set", "uci add", "uci rename" and "uci delete" commands are staged into a temporary location and written to flash at once with "uci commit". This is not needed after editing configuration files with a text editor, but for scripts, GUIs and other programs working directly with UCI files.|
||-||Executes a multi-line UCI script which is typically wrapped into a here document syntax.|
||Exports the configuration in a machine readable format. It is used internally to evaluate configuration files as shell scripts.|
||Imports configuration files in UCI syntax.|
||List staged changes to the given configuration file or if none given, all configuration files.|
||Add an anonymous section of type
||Add the given string to an existing list option.|
||Show the given option, section or configuration in compressed notation.|
||Get the value of the given option or the type of the given section.|
||Set the value of the given option, or add a new section with the type set to the given value.|
||Delete the given section or option.|
||Rename the given option or section to the given name.|
||Revert the given option, section or configuration file.|
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", you will see:
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.
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/All scripts in that folder are automatically executed by
/etc/init.d/S10bootand if they exited with code 0 deleted afterwards (scripts that did not exit with code 0 are not deleted and will be re-executed during the next boot until they also successfully exit).
doc/uci.txt · Last modified: 2013/05/23 16:15 by nousername