OpenWRT路由器设置接口中的Lua填坑

刚结束一个急活,主要是整理某个 OpenWRT 路由的设置接口,网页服务主要用的是 Nginx,网页用的是 BackBone 和 jQuery 配合,后端设置服务主要用的是 Lua(由 Nginx 代理)调用 OpenWRT 的 UCI 和 ubus。一开始我以为只需要前端稍微调整下就行了,后来发现后边跟着的 Lua 得一起整,顺带补了不少 OpenWRT 的基础知识,下边简单梳(还)理(债)……

UCI

[](https://marsgt.github.io/#%E5%9F%BA%E7%A1%80%E7%9F%A5%E8%AF%86

“基础知识”)基础知识

UCI 是“Unified Configuration Interface”(统一配置接口)的缩写,是 OpenWrt 系统的核心配置框架,它的主要作用是整合系统里不同的设置项,并提供一个统一的接口。OpenWrt 系统配置文档默认被集中放在了 /etc/config 这里(当然也可以放在其它地方),这些 UCI 文档有自己特殊的语法,比如一个典型的无线配置可能是:

config wifi-device 'radio0'
    option type 'mac80211'
    option channel 'auto'
    option hwmode '11g'
    option path 'platform/qca953x_wmac'
    option htmode 'HT20'
    option disabled '0'

config wifi-iface
    option ifname 'wlan0'
    option device 'radio0'
    option network 'lan'
    option mode 'ap'
    option encryption 'none'
    option ssid 'TestSSID'

这里以 config 开头的行代表了一个 config 节点,其格式为:
config 'section-type' 'section'
section-type 处的值是节点类型,而 section 则是节点名称。另外,config 节点允许匿名节点的存在(意即直接跳过'section',就像第二个的 config 节点那样,wifi- iface只是节点类型而不是节点名,这里要注意),引号在 UCI 文档中也不是必须的,严格来讲只有值里带有空格或制表符时才需要使用,使用时也要注意,其必须成对出现才有效(比如一对单引号或者一对双引号,交叉使用会导致语法错误)。
以 option 开头的是选项,格式为:
option 'key' 'value'
这是比较典型的 key-value 格式,就不再赘述了。除此之外,还有种 list 列表选项,被用来描述形如数组类的设置,格式与 option 非常相似:
list 'list-key' 'list-value'
如果 list-key 相同的话,那么这实际上就是个数组式的设置项,举个栗子,system 设置里的 NTP:

config timeserver 'ntp'
    option enabled '1'
    option enable_server '0'
    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'

这里的 NTP Server 设置实际上就是个数组。

UCI

的调用

在 OpenWRT 系统里调用 UCI 一般有两种方法,通过命令行或者是调用 Lua API。这里首先说命令行。
OpenWRT 官方文档里提到,使用awk、grep等命令来解析Openwrt的配置文档是低效和不明智的做法,并建议在类似的场景下,应该优先使用命令行形式调用。
UCI 命令行语法为(在命令行下直接输入 uci 即可看到):

用法: uci [<options>] <command> [<arguments>]

命令:
    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>]]

参数:
    -c <path>  设置用于存储配置文档的文档夹 (默认位于: /etc/config)
    -d <str>   使用'uci show'命令时,为 list 类型的值设置分隔符
    -f <file>  使用指定的 <file> 作为输入,而不是默认的 stdin
    -m         导入时,合并数据到现有的设置中
    -n         导出时,命名匿名节 (默认)
    -N         不要命名匿名节
    -p <path>  添加一个配置文档的搜索路径
    -P <path>  添加一个配置文档的搜索路径并将其作为默认设置
    -q         安静默认 (不打印错误信息)
    -s         强制使用严格模式 (在解析出现错误时停止,默认)
    -S         关闭严格模式
    -X         在'show'命令上显示匿名节点ID (如果有的话)

平时(命令行下)常用的主要是 showgetsetchangescommit 这几个。
使用 UCI 时,需要特别注意下它的读写规则:UCI 在读取时,会首先读取内存中的缓存,而后才是文档;而写入则与此相反,增删改都是在操作缓存,需要手动提交才会将设置项写入到系统中。所以,在编写路由设置系统时,最后的提交操作是切不可忘的一步。
还有一种调用 UCI 的方法,是使用 Lua,文末的参考内容[3]中有详细的 API 列表(记得在开头用 local uci = require "los.uci".cursor() 语句引入)。
在使用 Lua 调用时,有个需要注意的点是匿名节点,比如上文中的无线配置里,有个 wifi-iface 类型的匿名节点,在命令行里使用 uci show wireless 可以看到:

wireless.radio1=wifi-device
wireless.radio1.type='mac80211'
wireless.radio1.channel='auto'
wireless.radio1.hwmode='11g'
wireless.radio1.path='platform/qca953x_wmac'
wireless.radio1.htmode='HT20'
wireless.radio1.disabled='0'
wireless.@wifi-iface[0]=wifi-iface
wireless.@wifi-iface[0].ifname='wlan0'
wireless.@wifi-iface[0].device='mt7620'
wireless.@wifi-iface[0].network='lan'
wireless.@wifi-iface[0].mode='ap'
wireless.@wifi-iface[0].encryption='none'
wireless.@wifi-iface[0].ssid='TestSSID'

这里可以看到很多键名类似 @wifi-iface[0] 的设置项,这就是匿名节点的设置项了。如果在命令行里加入 -X 参数变成 uci -X show wireless,则可以看到:

wireless.radio1=wifi-device
wireless.radio1.type='mac80211'
wireless.radio1.channel='auto'
wireless.radio1.hwmode='11g'
wireless.radio1.path='platform/qca953x_wmac'
wireless.radio1.htmode='HT20'
wireless.radio1.disabled='0'
wireless.cfg043579=wifi-iface
wireless.cfg043579.ifname='wlan1'
wireless.cfg043579.device='radio1'
wireless.cfg043579.network='lan'
wireless.cfg043579.mode='ap'
wireless.cfg043579.encryption='none'
wireless.cfg043579.ssid='TestSSID'

这时 @wifi-iface[0] 变成了 cfg043579,这才是这个匿名节点真实的引用名(系统自动生成的)。
而同样的,在撰写相对应的 Lua 语句时,也不能写成:

uci:get("wireless", "@wifi-iface[0]", "ssid", "NewSSID")

虽然可以在命令行执行 uci set wireless.@wifi-iface[0].ssid='NewSSID',但是在 Lua 上这么写系统是不会鸟你的(更何况还有个隐性的问题,是设置被改动过后,匿名节点的位置有可能会变,比如会跑到 @wifi-iface[1] 去,这可能会发生在拥有多个匿名节点的配置文档里)。所以这个时候,就需要使用 uci:foreach 去遍历某个设置类型的所有设置节点(注:返回 false 终止遍历),在遍历出的内容里,有几个特殊的、键名以英文字符 . 开头的成员:

  • [.index]: 设置节点的索引
  • [.name]: 设置节点的名称(即真实的引用名,cfg043579 这种)
  • [.type]: 设置节点的类型(如 wifi-iface
  • [.anonymous]: 指示该设置节点是否匿名

这样,通过遍历所有项目并筛选符合条件的配置项,将 [.name] 中的内容缓存下来,就可以用:

uci:get("wireless", "cfg043579", "ssid", "NewSSID")

这种方法去调用了。
这里放个自己写的用于遍历无线设置的函数(双频设备,每个频段只有一个信号,通过设备 ID 来识别):

function getWirelessInfo()
    local wifiConfig = {}
    uci:foreach(
        "wireless",
        "wifi-iface",
        function(s)
            if s.device == "mt7620" then
                if not wifiConfig.mt7620 then
                    wifiConfig["mt7620"] = {}
                end
                local key = ""
                if s.key then
                    key = s.key
                end
                wifiConfig.mt7620 = {
                    name = s[".name"],
                    ssid = s.ssid,
                    ency = s.encryption,
                    pass = key
                }
            elseif s.device == "mt7612" then
                if not wifiConfig.mt7612 then
                    wifiConfig["mt7612"] = {}
                end
                local key = ""
                if s.key then
                    key = s.key
                end
                wifiConfig.mt7612 = {
                    name = s[".name"],
                    ssid = s.ssid,
                    ency = s.encryption,
                    pass = key
                }
            end
        end
    )
    return wifiConfig
end

不过,在实践中,我认为最有效的手段是将匿名节点转化成普通的具名节点,这样 Lua 就可以直接调用,比写挨个遍历内容的逻辑要简单也清晰的多。

下边再说说 ubus。

ubus

ubus 即是 OpenWrt micro bus 架构,是 OpenWrt 为了提供守护进程和应用进程间的通讯而开发的项目。简单来说,想获取系统运行的一些状态,是可以用 ubus 来查看的,而且相比用 UCI 查询,由于 ubus 获取的直接是系统信息而不是设置项,所以可以避免由于错误配置带来的配置项与系统状态不符合的问题。也是因为这个原因,我推荐读取设置(状态)时用 ubus,写入设置时用 UCI。
当然 ubus 也并不是没有问题,目前比较通用的说法是,在数据内容超过 60k 时不建议用,另外如果有多线程、或者逻辑上有递归时也不建议用(命令发出以后,接受到的信息可能是另一条命令的返回内容)。

[](https://marsgt.github.io/#ubus-%E7%9A%84%E8%B0%83%E7%94%A8 “ubus

的调用”)ubus 的调用

同 UCI 类似,调用 ubus 也分为命令行方式与 Lua 调用方式。而与 UCI 将设置文档命名为包(package)不同的是,ubus 将其调度单位称为“命名空间”(namespace),系统后台会默认驻留一个名为 ubusd 的守护进程,使用友好的 JSON 格式进行交互。
在命令行中输入 ubus list 就可以看到所有通过RPC服务器注册的命名空间:

dhcp
hostapd.wlan0
hostapd.wlan1
log
network
network.device
network.interface
network.interface.lan
network.interface.loopback
network.interface.wan
network.interface.wan6
network.wireless
service
session
system
uci

加个参数变成 ubus -v list,就可以详细列出这些命名空间所提供的方法了。调用方法用 call 关键字,比如,查看系统 WiFi 状态就可以用:

ubus call network.wireless status '{}'

(参数一定要带上,即使为空。格式为 JSON)

除此以外,还有:

  • 获取系统信息(上线时间、内存用量、SWAP信息等)

    ubus call system info '{}'
    
  • 获取设备信息(设备型号、固件版本等)

    ubus call system board '{}'
    
  • 获取 WiFi 上已连接的客户端

    ubus call hostapd.wlan0 get_clients '{}'
    
  • 获取路由物理设备信息(如 MAC 型号、工作状态等)

    ubus call network.device status '{"name":"eth0"}'
    

等等。
除了命令行直接调用外,ubus 也可以使用 Lua 调用,由于没有 UCI 那劳什子匿名节点的问题,所以直接用

    local ubus = require "ubus"

引入,在调用前用

    local conn = ubus.connect()

连接服务,在调用后用

    conn:close()

关闭就好。
比如我自己写的一段从 ubus 上拿 WiFi 信息的函数:

    local function getWirelessStatus()
  local conn = ubus.connect()
  if not conn then
      error("Failed to connect to ubusd")
  end
  local info = {}
  local status = conn:call("network.wireless", "status", {})
  for k, v in pairs(status) do
      info[k] = v
  end
  conn:close()    
  return info
end

[](https://marsgt.github.io/#%E5%8F%82%E8%80%83%E5%86%85%E5%AE%B9

“参考内容”)参考内容

  1. OpenWRT官网 - UCI系统
  2. OpenWRT官网 - UCI技术参考资料
  3. LuaDoc - luci.model.uci (英)
  4. OpenWRT官网 - ubus

糖果

糖果
LUA教程

Lapis框架的常用处理方法

Lapis框架的常用处理方法 Continue reading

MoonScript实现选择排序

Published on February 26, 2017

MoonScript与Redis客户端

Published on January 19, 2017