UCI命令系统

《MakerRouter 创客路由教程》3.2 入门：UCI命令系统

3.2 入门：UCI命令系统

UCI命令

一个众所周知的原因，在Linux下各种软件包有各种不同的配置脚本，每个配置脚本的语法格式和操作方式不同，这样的设计虽然可以体现出各软件包自身的优势，同时也增加了学习曲线。在这一点上OpenWrt的UCI无疑处理的更胜一筹。

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

UCI的文件和流程

UCI的配置文件全部存储在/etc/config目录下。

root@OpenWrt:/# ls /etc/config/
dhcp dropbear firewall network system wireless

目前已有大量软件包支持UCI模式管理，但不是所有的软件包，支持的软件包是这样来完成启动的(以samba举例)：
1. 启动脚本/etc/init.d/samba
2. 启动脚本通过UCI分析库从/etc/config/samba获得启动参数
3. 启动脚本完成正常启动

由于UCI的数据文件较为简单，并且具备了很nice的直接观感，所以配置文件既可以使用UCI命令进行修改，也可以使用VI编辑器直接修改文件。但如果两种方式都是用时需要注意UCI命令修改会产生缓存，每次修改好要尽快确认保存避免出现冲突。

最常见的几个UCI配置作用说明：
文件 作用
/etc/config/dhcp 面向LAN口提供的IP地址分配服务配置
/etc/config/dropbear SSH服务配置
/etc/config/firewall 路由转发，端口转发，防火墙规则
/etc/config/network 自身网络接口配置
/etc/config/system 时间服务器时区配置
/etc/config/wireless 无线网络配置

UCI的文件语法

UCI文件语法举例
config 'section-type' 'section'
option 'key' 'value'
list 'list_key' 'list_value'

config 'example' 'test'
option 'string' 'some value'
option 'boolean' '1'
list 'collection' 'first item'
list 'collection' 'second item'
 config节点 以关键字config开始的一行用来代表当前节点
 section-type节点类型
 section 节点名称
 option选项 表示节点中的一个元素
 key键
 value值
 list列表选项 表示列表形式的一组参数。
 list_key列表键
 list_value列表值

config节点语法格式

config 'section-type' 'section'

config节点(后文统一称为节点)原则
 UCI允许只有节点类型的匿名节点存在
 节点类型和名字建议使用单引号包含以免引起歧义
 节点中可以包含多个option选项或list列表选项。
 节点遇到文件结束或遇到下一个节点代表完成。

option选项语法格式

option 'key' 'value'

option选项(后文统一称为选项)原则
 选项的键与值建议使用单引号包含
 避免相同的选项键存在于同一个节点，否则只有一个生效

list列表选项语法格式

list 'list_key' 'list_value'

list列表选项(后文统一称为列表)原则
 选项的键与值建议使用单引号包含
 列表键的名字如果相同，则相同键的值将会被当作数组传递给相应软件

UCI的语法容错

option example value
option 'example' value
option example "value"
option "example" 'value'
option 'example' "value"

UCI无法容忍的语法

option 'example" "value'
option example some value with space
尽量使用常规字符去处理器UCI，特殊字符有可能会破坏数据结构的完整性。

UCI命令读写配置

语法格式
uci [] []
读写规则
 UCI读取总是先读取内存中的缓存，然后再读取文件中的
 进行过增加，修改，删除操作后要执行生效指令，否则所做修改只存留在缓存中

读取类语法
取得节点类型
uci get .

取得一个值
uci get .

.

显示全部UCI配置
uci show

显示指定文件配置
uci show

显示指定节点名字配置
uci show .

显示指定选项配置
uci show .

.

显示尚未生效的修改记录
uci changes

匿名节点显示(如果所显示内容有匿名节点，使用-X参数可以显示出匿名节点的ID)
uci show -X .

.

写入类语法

增加一个匿名节点到文件
uci add

增加一个节点到文件中
uci set .

=

增加一个选项和值到节点中
uci set .

.=

增加一个值到列表中
uci add_list .

.=

修改一个节点的类型
uci set .

=

修改一个选项的值
uci set .

.=

删除指定名字的节点
uci delete .

删除指定选项
uci delete .

.

删除列表
uci delete .

.

删除列表中一个值
uci del_list .

.=

生效修改(任何写入类的语法，最终都要执行生效修改，否则所做修改只在缓存中，切记！)
uci commit

综合实例

针对乱七八糟的UCI命令，hoowa写了一篇综合实例，大家多练习下吧，这章挺重要的，系统真的被弄坏了就重刷固件嘛～～

语法测试

准备产生一个用来测试的配置mytest
root@OpenWrt:~# cp /etc/config/system /etc/config/mytest
root@OpenWrt:~# cat /etc/config/system
config system
option hostname OpenWrt
option timezone UTC

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
option enabled 1
option enable_server 0

看看mytest的配置
root@OpenWrt:~# uci show mytest
mytest.@system[0]=system
mytest.@system[0].hostname=OpenWrt
mytest.@system[0].timezone=UTC
mytest.ntp=timeserver
mytest.ntp.server=0.openwrt.pool.ntp.org 1.openwrt.pool.ntp.org 2.openwrt.pool.ntp.org 3.openwrt.pool.ntp.org
mytest.ntp.enabled=1
mytest.ntp.enable_server=0

取得mytest.ntp.server这个选项的值
root@OpenWrt:~# uci get mytest.ntp.server
0.openwrt.pool.ntp.org 1.openwrt.pool.ntp.org 2.openwrt.pool.ntp.org 3.openwrt.pool.ntp.org

增加一个类型为interface名字为hoowa的节点
uci set mytest.hoowa=interface

增加enable选项到hoowa节点
uci set mytest.hoowa.enable=1

修改类型为system的第一个匿名节点下的hostname选项
uci set mytest.@system[0].hostname=smartrouter

删除掉列表mytest.ntp.server的一个值
uci del_list mytest.ntp.server=2.openwrt.pool.ntp.org

查看都修改了啥
root@OpenWrt:~# uci changes mytest
mytest.hoowa=interface
mytest.hoowa.enable=1
mytest.cfg02e48a.hostname=smartrouter
mytest.ntp.server-=2.openwrt.pool.ntp.org

使修改生效
uci commit mytest

看看mytest文件
root@OpenWrt:~# cat /etc/config/mytest

config system
option timezone 'UTC'
option hostname 'smartrouter'

config timeserver 'ntp'
list server '0.openwrt.pool.ntp.org'
list server '1.openwrt.pool.ntp.org'
list server '3.openwrt.pool.ntp.org'
option enabled '1'
option enable_server '0'

config interface 'hoowa'
option enable '1'

举例开启WIFI

默认OpenWrt是不开启WIFI的，这里就根据本章所学一下子打开WIFI吧。

查看WIFI现在的配置
root@OpenWrt:~# uci show wireless
wireless.radio0=wifi-device
wireless.radio0.type=mac80211
wireless.radio0.channel=11
wireless.radio0.hwmode=11g
wireless.radio0.path=10180000.wmac
wireless.radio0.htmode=HT20
wireless.radio0.disabled=1
wireless.@wifi-iface[0]=wifi-iface
wireless.@wifi-iface[0].device=radio0
wireless.@wifi-iface[0].network=lan
wireless.@wifi-iface[0].mode=ap
wireless.@wifi-iface[0].ssid=OpenWrt
wireless.@wifi-iface[0].encryption=none

可以看到的是wireless.radio0.disabled为1表示禁用WIFI，打开方法如下
root@OpenWrt:~# uci set wireless.radio0.disabled=0
root@OpenWrt:~# uci commit wireless
root@OpenWrt:~# uci show wireless.radio0.disabled
wireless.radio0.disabled=0

使用wifi命令启动
root@OpenWrt:~# wifi
root@OpenWrt:~# [ 2976.140000] IPv6: ADDRCONF(NETDEV_UP): wlan0: link is not ready
[ 2976.140000] device wlan0 entered promiscuous mode
[ 2976.180000] br-lan: port 2(wlan0) entered forwarding state
[ 2976.180000] br-lan: port 2(wlan0) entered forwarding state
[ 2976.190000] IPv6: ADDRCONF(NETDEV_CHANGE): wlan0: link becomes ready
[ 2978.180000] br-lan: port 2(wlan0) entered forwarding state
[ 2986.310000] device wlan0 left promiscuous mode
[ 2986.310000] br-lan: port 2(wlan0) entered disabled state
[ 2986.700000] IPv6: ADDRCONF(NETDEV_UP): wlan0: link is not ready
[ 2986.700000] device wlan0 entered promiscuous mode
[ 2986.710000] br-lan: port 2(wlan0) entered forwarding state
[ 2986.710000] br-lan: port 2(wlan0) entered forwarding state
[ 2986.750000] IPv6: ADDRCONF(NETDEV_CHANGE): wlan0: link becomes ready
[ 2988.710000] br-lan: port 2(wlan0) entered forwarding state

扫描下看看是否有一个叫OpenWrt的无线信号。