1. Introduction to UCI
Unified Configuration Interface (UCI) is one of the key technologies for OpenWrt's success, and it has been ported to support thousands of software. It uses a plain text file to save the configuration, and provides a command line and C language programming call interface for management. The purpose of UCI is to centralize the configuration of the OpenWrt system. In this way, each developer only needs to learn once, which reduces the cost of learning.
UCI is simple, practical, and straightforward. UCI is the main configuration user interface on OpenWrt. It is used as the main system settings. These settings are usually critical to the device. For example, the network interface, wireless settings, remote login permission settings, etc. are all configured through UCI. He is an essential part of building a complete system.
Two, UCI configuration file format
- The configuration section (section) is an independent configuration unit of UCI configuration. The UCI configuration file is composed of one or more configuration sections. The configuration section has a configuration type attribute that starts with "config" and has an optional name. The configuration section contains one or more configuration option statements.
Format: The configuration file is composed of a configuration section (section), which is composed of multiple "name/values" option pairs (option)
# root@OpenWrt:~# cat /etc/config/network
config interface 'loopback'
option ifname 'lo'
option proto 'static'
option ipaddr '127.0.0.1'
option netmask '255.0.0.0'
config globals 'globals'
option ula_prefix 'fd06:7893:cd7f::/48'
config interface 'lan'
option type 'bridge'
option ifname 'eth0 eth1 eth2 eth4'
option proto 'static'
option ipaddr '192.168.155.1'
option netmask '255.255.255.0'
option ip6assign '60'
config interface 'wan'
option ifname 'eth3'
option proto 'dhcp'
config interface 'wan6'
option ifname 'eth3'
option proto 'dhcpv6'
- Each configuration section (section) needs to have a type identifier (type), but not necessarily a name (name)
- Each option pair (option) has a name (name) and value (value), which are written in the configuration section to which it belongs
- The name of the UCI identifier and configuration file can only contain the letters a~z, 0~9 and _. For example, hyphen (-) is not allowed
- Option values can contain any characters, but they need to be quoted correctly
- Configuration section without name identification is called anonymous configuration section
- The meaning of type (type) and option (option) are determined by the application, and the type is generally used by the application to decide how to deal with the configuration options contained in the configuration section
- If an option (type) does not exist and is required, the application usually triggers an exception or records an exception log, and then the program exits
- Usually options (options) are identified by spaces or tabs indentation in configuration files, but this is not a grammatical requirement, just to increase the readability of the configuration file
- option and list are used to improve the readability of the configuration file, and also require the use of keywords in the syntax to indicate the beginning of the configuration option
Three, UCI configuration principle
-> UCI configuration file loading process:
the UCI configuration file of the application, the /etc/init.d/xxx script is called when the program is running, and the UCI configuration file is parsed into a general software configuration file. If you just start the executable file directly, it does not pass init. .d call, will not update a UCI configuration file to the corresponding configuration file location of the specific program, and the modification in /etc/config/ will not have any impact on the existing process.
-> Modification of the CI configuration file:
The core configuration of the OpenWrt system is divided into many files, and they are all located in the /etc/config directory. Each file refers to a certain part of the system configuration. You can use a text editor to modify, or use the command line utility UCI to edit the configuration file. UCI configuration files can also be modified through various programming APIs (such as shell, Lua, and C, etc.). This is also the way for Web interfaces such as LuCI to modify UCI files.
-> The default "/etc/config" directory of the configuration file:
| Document road diameter | meaning |
|---|---|
| /etc/config/dhcp | Dnsmasq package configuration, including DHCP and DNS settings |
| /etc/config/dropbear | SSH server options |
| /etc/config/firewall | Firewall configuration, including network address translation, packet filtering and port forwarding, etc. |
| /etc/config/network | Network configuration, including bridging, interface and routing configuration |
| /etc/config/system | System settings, including host name, network time synchronization, etc. |
| /etc/config/timeserver | List of time services for rdate |
| /etc/config/luci | Basic LuCI configuration |
| /etc/config/wireless | Wireless settings and Wi-Fi network definition |
| /etc/config/uhttpd | Web server option configuration |
| /etc/config/upnpd | miniupnpd UPnP service settings |
| /etc/config/qos | Profile definition of network service quality |
Four, UCI command
Using vi, scripts, lua and other tools to modify UCI configuration files is troublesome and error-prone. Openwrt provides uci command tools to manipulate UCI configuration files. The uci tool can get a value, set a value and other functions. Run the uci command in the terminal to view his help instructions.
Usage :uci [ < options >] < command> [< arguments>]
root@OpenWrt:/etc/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>
del_list <config>.<section>.<option>=<string>
show [<config>[.<section>[.<option>]]]
get <config>.<section>[.<option>]
set <config>.<section>[.<option>]=<value>
delete <config>[.<section>[[.<option>][=<id>]]]
rename <config>.<section>[.<option>]=<name>
revert <config>[.<section>[.<option>]]
reorder <config>.<section>=<position>
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'
Give examples to illustrate some commonly used usage
# root@OpenWrt:~# uci export rpcd
package rpcd
config rpcd
option socket '/var/run/ubus.sock'
option timeout '30'
config login
option username 'root'
option password '$p$root'
list read '*'
list write '*'
#root@OpenWrt:/etc/config# uci show network
network.loopback=interface
network.loopback.ifname='lo'
network.loopback.proto='static'
network.loopback.ipaddr='127.0.0.1'
network.loopback.netmask='255.0.0.0'
network.globals=globals
network.globals.ula_prefix='fd06:7893:cd7f::/48'
network.lan=interface
network.lan.type='bridge'
network.lan.ifname='eth0 eth1 eth2 eth4'
network.lan.proto='static'
network.lan.ipaddr='192.168.155.1'
network.lan.netmask='255.255.255.0'
network.lan.ip6assign='60'
network.wan=interface
network.wan.ifname='eth3'
network.wan.proto='dhcp'
network.wan6=interface
network.wan6.ifname='eth3'
network.wan6.proto='dhcpv6'
#root@OpenWrt:/etc/config# uci get network.lan.ipaddr
192.168.155.1