代码收藏家技术教程 2023-12-31

OpenWrt中使用UCI指令的方法详解

UCI简介

UCI是集中式配置信息管理接口（Unified Configuration Interface）的缩写，他是OpenWrt引进的一套配置参数管理系统。UCI管理了OpenWrt下最主要的系统配置参数并且提供了简单、容易、标准化的人机交互接口。UCI中已经包含了网络配置、无线配置、系统信息配置等作为基本路由器所需的主要配置参数。同时UCI也可以帮助开发人员快速的建立一套基于OpenWrt的智能路由产品控制界面。

文件语法

语法格式

    config <type> ["<name>"]        # 配置节(Section)
        option <name> "value"       # 选项对(option)
        list <name> "value"         # 选项对(option)

语法解析

UCI的配置文件由配置节组成，配置节由多个选项对组成。

配置节：配置节是UCI配置的一个独立配置单元，UCI配置文件是由一个或多个配置节组成。配置节有一个配置类型属性“type”，是以“config”开头，并且有一个可选名称，如果配置节不带名称标识，这样的配置节称为匿名配置节。

选项对：每一个选项对都有名称“name”和值“value”，写在其所属的配置节中。选项对一般以“option”与“list”开始。

注意事项

配置节的类型（type）和选项对（option）的含义均由应用程序来决定。
类型一般用于应用程序决定如何处理配置节包含的配置选项对。
如果缺少了一个必需的选项对，那应用程序通常会触发一个异常或者记录一个异常的日志，然后程序退出。
通常选项对在配置文件中都是使用空格或制表符缩进来标识，但这个并非是语法要求，仅仅是为了增加配置文件的可读性。
option和list用来提高配置文件的可读性，并且在语法上也要求使用关键字来表示选项对的开始。
通常不需要使用引号引上类型标识符的值，引号只在封闭的值包含空格或制表符的情况下需要。可以合法地使用双引号或单引号。
UCI标识符和配置文件的名称只能包含字母a～z、0～9和_。例如连字符（-）是不允许的。
选项对的值需要包含任何字符，但需要正确加上引号。

语法实例

我们可以看一下实际的配置文件的内容。

    root@OpenWrt:/# cat etc/config/system 
    config system
            option hostname 'OpenWrt'
            option ttylogin '0'
            option log_size '64'
            option urandom_seed '0'
            option zonename 'UTC'
            option log_proto 'udp'
            option conloglevel '8'
            option cronloglevel '5'

    config timeserver 'ntp'
            list server '0.openwrt.pool.ntp.org'
            list server '1.openwrt.pool.ntp.org'
            list server '2.openwrt.pool.ntp.org'
            list server '3.openwrt.pool.ntp.org'

统一配置原则

Openwrt有很多独立的第三方应用程序，大多数应用程序的软件包维护者已经制作了UCI兼容的配置文件，启动时由UCI配置文件转换为软件包的原始配置文件。这是在运行初始化脚本/etc/init.d/中执行的。

Openwrt系统的核心配置分成很多个文件，并且都位于 **/etc/config/**目录下。每个文件涉及系统配置的某一部分。你可以用一个文件编辑器修改，或者用命令行实用程序UCI编辑配置文件。UCI的配置文件也可通过各种编程API来修改。

    ls /etc/config/
    attendedsysupgrade  mosquitto           ucitest         dhcp                network             ucitrack
    dropbear            openssl             uhttpd          firewall            rpcd                wireless
    luci                system

无论是通过一个文本编辑器还是命令行工具修改配置文件，在改变一个UCI的配置文件后，受影响的服务或者可执行程序必须由init.d进行重启。这样更新的UCI配置才会真正生效。

常用功能配置文件含义

基本配置

路径	含义
/etc/config/dhcp	dnsmasq和DHCP的配置
/etc/config/dropbear	SSH服务端选项
/etc/config/firewall	中央防火墙配置
/etc/config/network	交换，接口和路由配置
/etc/config/system	杂项与系统配置
/etc/config/timeserver	rdate的时间服务器列表
/etc/config/wireless	无线设置和无线网络的定义

IPv6

路径	含义
/etc/config/ahcpd	Ad-Hoc配置协议(AHCP) 服务端配置以及转发器配置
/etc/config/aiccu	AICCU 客户端配置
/etc/config/dhcp6c	WIDE-DHCPv6 客户端配置
/etc/config/dhcp6s	WIDE-DHCPv6 服务端配置
/etc/config/gw6c	GW6c 客户端配置
/etc/config/radvd	路由通告 (radvd) 配置

其他

路径	含义
/etc/config/etherwake	以太网唤醒: etherwake
/etc/config/fstab	挂载点及swap
/etc/config/hd-idle	另一个可选的硬盘空闲休眠进程(需要路由器支持usb硬盘)
/etc/config/httpd	网页服务器配置选项(Busybox 自带httpd, 已被舍弃)
/etc/config/luci	基础 LuCI 配置
/etc/config/luci_statistics	包统计配置
/etc/config/mini_snmpd	mini_snmpd 配置
/etc/config/mountd	OpenWrt 自动挂载进程(类似autofs)
/etc/config/multiwan	简单多WAN出口配置
/etc/config/ntpclient	ntp客户端配置，用以获取正确时间
/etc/config/pure-ftpd	Pure-FTPd 服务端配置
/etc/config/qos	QoS配置(流量限制与整形)
/etc/config/samba	samba配置(Microsoft文件共享)
/etc/config/snmpd	SNMPd(snmp服务进程) 配置
/etc/config/sshtunnel	sshtunnel配置
/etc/config/stund	STUN 服务端配置
/etc/config/transmission	BitTorrent配置
/etc/config/uhttpd	Web服务器配置(uHTTPd)
/etc/config/upnpd	miniupnpd UPnP服务器配置
/etc/config/ushare	uShare UPnP 服务器配置
/etc/config/vblade	vblade 用户空间AOE(ATA over Ethernet)配置
/etc/config/vnstat	vnstat 下载器配置
/etc/config/wifitoogle	使用按钮来开关WiFi的脚本
/etc/config/wol	Wake-on-Lan: wol
/etc/config/znc	ZNC 配置

配置服务示例

首先使用UCI命令行工具修改network服务

    root@OpenWrt:/# uci set network.lan.ipaddr='192.168.1.1'
    root@OpenWrt:/# uci commit network

修改完以后还没有生效，必须要重启network服务才能生效修改

    root@OpenWrt:/# /etc/init.d/network restart

UCI工具

下面是UCI工具选项对含义和基本使用方法，以及一些如何使用这个命令行接口工具的示例。

    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'

UCI命令含义

命令	含义
export	导出一个机器可读的配置。它是作为操作配置的shell脚本而在内部使用，导出配置内容时会在前面加“package”和文件名
import	以UCI语法导入配置文件
show	显示指定的选项、配置节或配置文件。以key=value的方式输出
get	这个指令跟show有点像，但是是用来打印指定的配置配置节类型或者指定的选项对的值。
set	设置指定配置节选项对的值，或者说增加一个配置节，类型设置为指定的值
changes	列出配置文件分阶段修改内容，即未使用“uci commit”提交的修改。如果没有指定配置文件，则指所有的配置文件的修改部分
commit	对已给定的配置文件写入修改，如果没有指定参数则将所有的配置文件写入文件系统。所有的“uci set”“uci add”“uci rename”和“uci delete”命令将配置写入一个临时位置，在运行“uci commit”以后写入到实际的存储位置
add	增加指定配置文件的类型为 section-type 的匿名区段
add_list	对已存在的list选项增加字符串
del_list	对已存在的list选项删除指定字符串
delete	删除指定的配置节或选项
rename	对指定的选项或配置节重命名为指定的名字
revert	恢复指定的选项，配置节或配置文件

UCI命令实例

新增一个匿名配置节

    uci add test type
    uci add /etc/config/test type

新增一个选项对

    uci set test.@type[0].Enable=1
    uci set /etc/config/test.@type[0].Enable=1

新增一个选项对列表

    uci add_list test.@type[0].list="01 url"
    uci add_list /etc/config/test.@type[0].list="01 url"

显示已经修改的配置

    uci changes

提交已经修改的配置

    uci commit

显示现有配置、配置节或选项对

    uci show test
    uci show test.@type[0]
    uci show test.@type[0].Enable

显示现有配置节的类型与指定选项对的值

    uci get test.@type[0]
    uci get test.@type[0].Enable

删除指定配置节或选项对

    uci delete test.@type[0]
    uci delete test.@type[-1].Enable

删除指定选项对列表其中一个值

    uci del_list test.@type[0].list="01 url"

修改指定配置节或选项对的名称

    uci rename test.@type[0]="newsection"
    uci rename test.@type[0].list="url"

修改指定配置节的类型

    uci set test.@type[0]="newtype"

恢复未提交的配置文件、配置节或选项对

    uci revert test
    uci revert test.@type[0]
    uci revert test.@type[0].Enable

导出配置文件

    uci export test >> test

导入配置文件

    root@OpenWrt:~# uci import test
    config system 
            option hostname 'OpenWrt'
            option ttylogin '0'      
            option log_size '64'     
            option urandom_seed '0'
            option zonename 'UTC'  
            option log_proto 'udp' 
            option conloglevel '8'
            option cronloglevel '5'
                                
    config timeserver 'ntp'        
            list server '0.openwrt.pool.ntp.org'
            list server '1.openwrt.pool.ntp.org'
            list server '2.openwrt.pool.ntp.org'

    # 此指令需要自己输入配置文件，输入完以后按“Ctrl+D”组合键结束