UCI，Unified Configuration Interface，统一配置接口，是一个集中配置OpenWrt服务的系统。

UCI是OpenWrt中基于NVRAM配置的继承者，是OpenWrt主要系统功能配置的用户接口，包括网络、无线、日志以及远程访问等等。

简介

OpenWrt存储库中的许多软件包已与UCI系统兼容。

兼容方式：根据相应的UCI配置文件中所选的配置项写入到应用程序的原始配置文件，即可使应用程序与UCI兼容。该操作是通过运行/etc/init.d/中的初始化脚本来完成的。因此，每次运行该脚本时，程序的原始配置文件会被覆盖。

应用程序的配置文件通常存储在RAM中（例如/var目录下）而不是闪存中，因为它不需要存储在非易失性存储器中，并且在每次更改后都会根据UCI文件进行覆盖。

例如，对于Samba/CIFS，运行/etc/init.d/samba start时，原始配置文件/etc/samba/smb.conf会被UCI配置文件/etc/config/samba中的相应设置进行覆盖。

root@OpenWrt:/etc/init.d# ls -l /etc/samba/smb.conf
lrwxrwxrwx    1 root     root            17 Aug  2 06:22 /etc/samba/smb.conf -> /var/etc/smb.conf

如果想要对应用程序设置没有UCI选项的配置，则需要禁用UCI，即通过禁用掉/etc/init.d下对应脚本的运行，然后手动设置应用程序的默认配置文件。

配置文件

OpenWrt的基于UCI的集中配置文件被划分为存放在/etc/config/目录下的多个文件。每个文件大致与其配置的系统功能相关。

可以使用文本编辑器修改配置文件或使用命令行工具uci修改它们。

UCI配置文件还可以通过各种编程API（如Shell、Lua和C）进行修改，即LuCI等Web界面对UCI文件进行更改的方式。

UCI配置文件无论是通过哪种方式发生变更，都需要调用/etc/init.d中的相应脚本，以使其生效。

如果不调用/etc/init.d中的脚本，而仅仅重启进程，会导致UCI配置文件没有覆盖进程的默认配置文件中，即配置不会生效。

下面是修改LAN口IP地址为192.168.0.111的方式：

  1. 首先将/etc/config/network中lan配置中的ipaddr设置为192.168.0.111。
  2. 其次使用/etc/init.d/network restart重启网络。
root@OpenWrt:/etc/init.d# cat /etc/config/network
...
config interface 'lan'
        option device 'eth0'
        option proto 'static'
        option ipaddr '192.168.0.111'
        option netmask '255.255.255.0'
        option ip6assign '60'
...

数据模型

术语说明
config配置文件，如network、system、firewall等。每种功能配置在/etc/config中都有自己的文件。
section配置文件内容会以section来划分，具有命名或匿名两种类型。
type每个section都具有一个type。
option每个section中具有多个option，用于以键值方式配置具体选项。
valueoption的值。

section可以命名，也可以匿名。匿名section自动生成的一个ID/CFGID（例如cfg073777），并具有一个匿名名称(例如@switch[0]）。

下面是一个匿名section的示例

root@OpenWrt:/etc/init.d# uci show network
...
network.@device[0]=device
network.@device[0].name='br-lan'
network.@device[0].type='bridge'
network.@device[0].ports='eth0'
network.lan=interface
network.lan.device='eth0'
network.lan.proto='static'
network.lan.ipaddr='192.168.0.111'
network.lan.netmask='255.255.255.0'
network.lan.ip6assign='60'

root@OpenWrt:/etc/init.d# uci show network.@device[0]
network.cfg030f15=device
network.cfg030f15.name='br-lan'
network.cfg030f15.type='bridge'
network.cfg030f15.ports='eth0'

示例中cfg030f15为自动生成的ID/CFGID，@device[0]为自动生成的匿名名称。

文件语法

UCI配置文件通常由一个或多个config组成，该config被称为为section。

每个section中包含一个或多个option，option用来指定具体的配置值。

以#开头的配置会被注释。

下面是一个简单配置示例

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

在上面的例子中：

  1. section以config 'example' 'test'行开始，其中example为section-type的，test为section-name。仅有type的section称为匿名section。
  2. option 'string' 'some value'和option 'boolean' '1'这两行定义了普通的参数配置。其中文本和布尔选项之间没有语法差异。
  3. 以list关键字开头的行，适用于配置具有多个值的option，其中option的键要相同。
  4. option和list的缩进用于增强可读性，不是语法必备的。

常用配置文件

文件说明
/etc/config/dhcpDnsmasq和odhcpd的配置：DNS、DHCP、DHCPv6
/etc/ocnfig/dropbearSSH Server配置
/etc/config/firewallNAT，包过滤，端口映射等配置
/etc/config/network网络接口以及路由的配置：IPv4、IPv6、Routes、Rules、WAN、VLAN等
/etc/config/system系统设置，例如NTP
/etc/config/wireless无线网络配置
/etc/config/ddns动态域名配置
/etc/config/fstab挂载点和交换空间配置
/etc/config/httpdWeb服务器配置
/etc/config/luciLuCI基础配置
/etc/config/uhttpdWeb服务器配置（uhttpd）
/etc/config/sambaSAMBA服务配置
/etc/config/snmpdSNMPd配置

命令行工具

用法

root@OpenWrt:~# 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
        -t <path>  set save path for config change files
        -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'

当配置中有多个type相同的section时，UCI支持以数组的方式进行引用。

例如，如果/etc/config/system中定义了8个NTP服务器，可以通过system.@timeserver[0]引用第一个，system.@timeserver[7]引用最后一个。也可以使用负索引，system.@timeserver[-1]引用最后一个，system.@timeserver[-2]引用倒数第二个，以此类推。

示例

增加新的option=enable并设置值为1：

# @dropbear[0]是section name
root@OpenWrt:/etc/config# uci set dropbear.@dropbear[0].enable=1
root@OpenWrt:/etc/config# uci commit dropbear
root@OpenWrt:/etc/config# cat dropbear

config dropbear
        option PasswordAuth 'on'
        option RootPasswordAuth 'on'
        option Port '22'
        option enable '1'

新增section，其中自动生成的CFGID为cfg0254fe，引用方式为@section_demo[0]：

root@OpenWrt:/etc/config# uci add dropbear section_demo
cfg0254fe
root@OpenWrt:/etc/config# cat dropbear

config dropbear
        option PasswordAuth 'on'
        option RootPasswordAuth 'on'
        option Port '22'
        option enable '1'

root@OpenWrt:/etc/config# uci commit dropbear
root@OpenWrt:/etc/config# cat dropbear

config dropbear
        option PasswordAuth 'on'
        option RootPasswordAuth 'on'
        option Port '22'
        option enable '1'

config section_demo
root@OpenWrt:/etc/config# uci show dropbear
dropbear.@dropbear[0]=dropbear
dropbear.@dropbear[0].PasswordAuth='on'
dropbear.@dropbear[0].RootPasswordAuth='on'
dropbear.@dropbear[0].Port='22'
dropbear.@dropbear[0].enable='1'
dropbear.@section_demo[0]=section_demo

删除section=@section_demo[0]：

root@OpenWrt:/etc/config# uci delete dropbear.@section_demo[0]
root@OpenWrt:/etc/config# uci commit dropbear
root@OpenWrt:/etc/config# cat dropbear

config dropbear
        option PasswordAuth 'on'
        option RootPasswordAuth 'on'
        option Port '22'
        option enable '1'