Das UCI System

Die Abkürzung steht für "Unified Configuration Interface" was sich in etwa mit "Schnittstelle zur vereinheitlichten Konfiguration" übersetzen lässt. Das UCI besteht aus etlichen Skripten, die dazu dienen die UCI-Konfigurationsdateien in die eigentlichen Konfigurationsdateien zu übersetzen bzw. den jeweiligen daemon mit den eingestellten Befehlszeilenparametern zu starten. Der Zweck besteht darin, möglichst die komplette Konfiguration von OpenWrt zu zentralisieren, zu entmystifizieren und zu vereinfachen. Die Konfiguration wird hier erklärt und sollte anschließend gerade heraus und einfach vonstatten gehen.

Viele Programme habe ihre Konfigurationsdateien in /etc/, wie z.B. /etc/network/interfaces oder /etc/exports oder /etc/dnsmasq.conf oder /etc/samba/samba.conf. Sie sind oft zwar ähnlich aufgebaut aber die Syntax unterscheidet sich doch gelegentlich. Unter OpenWrt müssen wir uns damit nicht mehr auseinandersetzen, sondern erledigen möglichst alles im UCI mit Hilfe dieses Wikis.

Hinweis Sie müssen nicht jedes mal, wenn Sie Änderungen vorgenommen haben, Ihren Router rebooten! Lesen Sie mehr dazu weiter unten command.line.utility:.

Allgemeine Prinzipien

Die Konfiguration wird in mehreren Dateien vorgenommen, die sich alle im Verzeichnis /etc/config befinden. Die Dateinamen entsprechen jeweils grob dem System, welches sie konfigurieren. Es handelt sich um ganz gewöhnliche Text-Dateien, die mit jedem Texteditor, mit dem UCI-eigenen utility Programm und natürlich auch mit diversen programmier-APIs (wie Shell, Lua, C) editiert werden können.

Konfigurationsdateien

Datei Beschreibung
Grund-Konfiguration
/etc/config/dhcp Einstellungen von DHCP und DNS
/etc/config/dropbear Einstellungen des SSH-Servers
/etc/config/firewall NAT, Portfilter, Portweiterleitung, usw.
/etc/config/network Einstellung des Switchs, der Interfaces und Routingkonfiguration
/etc/config/system Diverse System Einstellungen
/etc/config/timeserver Konfiguration für rdate (Busybox, veraltetes Protokoll)
/etc/config/wireless Einstellungen für den WLAN-Funk
IPv6
/etc/config/ahcpd Ad-Hoc Configuration Protocol (AHCP) server and forwarder Konfiguration
/etc/config/aiccu AICCU client Konfiguration
/etc/config/dhcp6c WIDE-DHCPv6 client
/etc/config/dhcp6s WIDE-DHCPv6 server
/etc/config/gw6c GW6c client Konfiguration
/etc/config/radvd Router Advertisement (radvd) Konfiguration
Andere
/etc/config/etherwake Einstellungen für (etherwake)-Paket (Wake on Lan)
/etc/config/fstab Einstellungen Mount points and SWAP
/etc/config/hd-idle Einstellungen für idle-daemon für angeschlossene Festplatten
/etc/config/httpd Einstellungen des alten Web-Servers (Busybox httpd, nicht mehr benutzt)
/etc/config/luci Grundkonfiguration von LuCI
/etc/config/luci_statistics Einstellungen für das Statistiken Paket
/etc/config/mini_snmpd Einstellungen für mini_snmpd
/etc/config/mountd OpenWrt automount daemon
/etc/config/multiwan Einfache Konfiguration für multi WAN
/etc/config/ntpclient Einstellungen für den ntpclient
/etc/config/pure-ftpd Pure-FTPd server config
/etc/config/qos Einstellungen für das "Quality of Service"
/etc/config/samba Konfiguration für das Microsoft'sche CIDR-Protokoll (Datei und Druckerfreigabe)
/etc/config/snmpd Einstellungen für den SNMPd
/etc/config/sshtunnel Settings for the package sshtunnel
/etc/config/stund STUN server configuration
/etc/config/transmission Einstellungen des BitTorrent-Programms Transmission
/etc/config/uhttpd Web-Server Einstellungen (uHTTPd)
/etc/config/upnpd Einstellungen für mini-upnpd, ein UPnP-Server
/etc/config/ushare Einstellungen für uShare ein weiter UPnP-Server
/etc/config/vblade vblade userspace AOE target
/etc/config/vnstat vnstat downloader Einstellungen
/etc/config/wifitoogle Script um den WLAN-Funk per Knopf ein- und auszuschlaten
/etc/config/wol Einstellungen für (wol)-Paket (Wake on Lan)
/etc/config/znc ZNC bouncer Konfiguration

Syntax

Die UCI-Konfiguration besteht aus einer oder mehreren Sektionen, die jeweils mehrere Optionen haben.

Hier ein Beispiel:

Paket 'beispiel'

config 'beispiel' 'grob'
        option   'string'      'Folge von Zeichen'
        option   'boolean'     '1'
        list     'collection'  'erstes item'
        list     'collection'  'zweites item'

  • The config 'example' 'test' statement defines the start of a section with the type example and the name test. There can also be so called anonymous sections with only a type, but no name identifier. The type is important for the processing programs to decide how to treat the enclosed options.
  • The option 'string' 'some value' and option 'boolean' '1' lines define simple values within the section. Note that there are no syntactical differences between text- and boolean options. Per convention, boolean options may have one of the values '0', 'no', 'off' or 'false' to specify a false value or '1' , 'yes', 'on' or 'true' to specify a true value.
  • In the lines starting with a list keyword an option with multiple values is defined. All list statements that share the same name, collection in our example, will be combined into a single list of values with the same order as in the configuration file.
  • The indentination of the option and list statements is a convention to improve the readability of the configuration file but it's not syntactically required.

Usually you do not need to enclose identifiers or values in quotes. Quotes are only required if the enclosed value contains spaces or tabs. Also it's legal to use double- instead of single-quotes when typing configuration options.

All of the examples below are valid uci syntax:

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

In contrast, the following examples are not valid syntax:

  • option 'example" "value' (quotes are unbalanced)
  • option example some value with space (note the missing quotes around the value)

It is important to know that UCI identifiers and config file names may only contain the characters a-z, 0-9 and _. Option values may contain any character (as long they are properly quoted).

Command Line Utility

It is redundant, unwise, and inefficient to use awk and grep to parse OpenWrt's config files. Use the uci utility instead to get what you need!

Below is the usage, as well as some useful examples of how to use this powerful utility. Remember, friends don't let friends parse their own config files!

When there are multiple rules next to each other, uci uses array-like references for them. If there are 8 NTP servers, uci will let you reference their sections as timeserver.@timeserver[0] for the first or timeserver.@timeserver[7] for the last one. You can also use negative indexes, such as timeserver.@timeserver[-1]. "-1" means "the last one, and "-2" means the second-to-last one. This comes in very handy when appending new rules to the end of a list. See examples below.

Usage

root@OpenWrt:/lib/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>
	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>]]

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'

Examples:

No need to reboot

After changing the port uhttpd listens on from 80 to 8080 in the file /etc/config/uhttpd, save it. Then do

uci commit uhttpd

And then a

sh /etc/init.d/uhttpd restart

Done. No reboot needed.

Export an entire configuration

root@OpenWrt:~# uci export httpd package 'httpd' config 'httpd' option 'port' '80' option 'home' '/www' root@OpenWrt:~#

Show the configuration "tree" for a given section

root@OpenWrt:~# uci show httpd httpd.@httpd[0]=httpd httpd.@httpd[0].port=80 httpd.@httpd[0].home=/www root@OpenWrt:~#

Display just the value of the configuration item

root@OpenWrt:~# uci get httpd.@httpd[0].port 80 root@OpenWrt:~#

Query interface state

Notiz: Die UCI-Status-Variablen sind veraltet und werden nicht mehr für Netzwerk-basierte Informationen benutzt. Man nehme stattdessen /lib/functions/network.sh:

. /lib/functions/network.sh; network_get_device if_wan wan; echo $if_wan

In r36817 verfügbar sind:

network_get_ipaddr network_get_ipaddr6 network_get_subnet network_get_subnet6 network_get_prefix6 network_get_gateway network_get_gateway6 network_get_dnsserver network_get_dnssearch
network_get_device network_get_physdev

root@OpenWrt:~# uci -P/var/state show network.wan network.wan=interface network.wan.ifname=eth0.1 network.wan.proto=dhcp network.wan.defaultroute=0 network.wan.peerdns=0 network.wan.device=eth0.1 network.wan.ipaddr=10.11.12.13 network.wan.broadcast=255.255.255.255 network.wan.netmask=255.255.255.0 network.wan.gateway=10.11.12.1 network.wan.dnsdomain= network.wan.dns=10.11.12.100 10.11.12.200 network.wan.up=1 network.wan.lease_gateway=10.11.12.1 network.wan.lease_server=10.11.12.25 network.wan.lease_acquired=1262482940 network.wan.lease_lifetime=5400 network.wan.lease_hostname=x-10-11-12-13 root@OpenWrt:~#

Add a firewall rule

This is a good example of both adding a firewall rule to forward the TCP SSH port, and of the negative (-1) syntax used with uci.

root@OpenWrt:~# uci add firewall rule root@OpenWrt:~# uci set firewall.@rule[-1].src=wan root@OpenWrt:~# uci set firewall.@rule[-1].target=ACCEPT root@OpenWrt:~# uci set firewall.@rule[-1].proto=tcp root@OpenWrt:~# uci set firewall.@rule[-1].dest_port=22 root@OpenWrt:~# uci commit firewall root@OpenWrt:~# /etc/init.d/firewall restart

Back to top

de/doc/uci.txt · Last modified: 2014/10/22 18:05 by owfan