| Both sides previous revision Previous revision Next revision | Previous revision Next revisionBoth sides next revision |
| docs:guide-user:base-system:uci [2019/05/15 14:35] – [Examples] syntax unified vgaetera | docs:guide-user:base-system:uci [2023/10/06 04:24] – [Configuration files] update vgaetera |
|---|
| ====== The UCI system ====== | ====== The UCI system ====== |
| The abbreviation [[docs:techref:uci|UCI]] stands for //**__U__**nified **__C__**onfiguration **__I__**nterface// and is a system to centralize the configuration of OpenWrt services. | See also: [[docs:guide-developer:uci-defaults|UCI defaults]], [[docs:guide-developer:network-scripting#examples|Network scripting]] |
| |
| UCI is the successor to the NVRAM-based configuration found in the White Russian series of OpenWrt and is the main configuration user interface for the most important system settings. | The abbreviation [[docs:techref:uci|UCI]] stands for //**__U__**nified **__C__**onfiguration **__I__**nterface//, and is a system to centralize the configuration of OpenWrt services. |
| Like for example the main network interface configuration, wireless settings, logging functionality and remote access configuration. | |
| |
| In addition, many packages in the OpenWrt repository have been made compatible with the UCI system. | UCI is the successor to the NVRAM-based configuration found in the White Russian series of OpenWrt. It is the main configuration user interface for the most important system settings including the main network interface configuration, wireless settings, logging functionality and remote access configuration. |
| |
| | Many packages in the OpenWrt repository have been made compatible with the UCI system. |
| Applications are made UCI-compatible by simply writing the original configuration file (which is read by the program) according to the chosen settings in the corresponding UCI file. | Applications are made UCI-compatible by simply writing the original configuration file (which is read by the program) according to the chosen settings in the corresponding UCI file. |
| This is done upon running the initialization scripts in ''/etc/init.d/''. | This is done upon running the initialization scripts in ''/etc/init.d/''. |
| |
| Upon changing a UCI configuration file, whether through a text editor or the command line, the services or executables that are affected must be (re)started (or, in some cases, simply reloaded) by an [[docs:techref:initscripts|init.d call]], such that the updated UCI configuration is applied to them. | Upon changing a UCI configuration file, whether through a text editor or the command line, the services or executables that are affected must be (re)started (or, in some cases, simply reloaded) by an [[docs:techref:initscripts|init.d call]], such that the updated UCI configuration is applied to them. |
| Many programs are made compatible with UCI in this way by making their init.d script write their standard software specific configuration files. | Many programs are made compatible with UCI by simply making their init.d script first update their standard program-specific configuration files, based on the updated UCI configuration in ''/etc/config'', and then restarting the executable. |
| The init.d script first properly writes such a configuration file to the software's expected location and it is read in again by restarting the executable. | This implies that solely (re)starting the executable directly, without calling the appropriate init.d script, would not behave as expected as it would not yet result in the incorporation of configuration updates into the program's standard [[http://en.wikipedia.org/wiki/Configuration_file|configuration file(s)]]. |
| Note that just (re)starting the executable directly, without init.d calls, will not result in an UCI update to relegate UCI config to the program's expected [[http://en.wikipedia.org/wiki/Configuration_file|configuration file]]. | |
| Changes in files in ''/etc/config/'' then take no effect. | |
| |
| As an example of modifying the UCI configuration, suppose you want to change the device's IP address from the default ''192.168.1.1'' to ''192.168.2.1''. | As an example of modifying the UCI configuration, suppose you want to change the device's IP address from the default ''192.168.1.1'' to ''192.168.2.1''. |
| |
| ===== Configuration files ===== | ===== Configuration files ===== |
| ^ File ^ Description ^ | ^ File ^ Description ^ |
| ^ Basic ^^ | ^ Basic || |
| | [[docs:guide-user:base-system:dhcp|/etc/config/dhcp]] | Dnsmasq configuration and DHCP settings | | | [[docs:guide-user:base-system:dhcp|/etc/config/dhcp]] | [[docs:guide-user:base-system:dhcp.dnsmasq|Dnsmasq]] and [[docs:techref:odhcpd|odhcpd]] settings: DNS, DHCP, DHCPv6 | |
| | [[docs:guide-user:base-system:dropbear|/etc/config/dropbear]] | SSH server options | | | [[docs:guide-user:base-system:dropbear|/etc/config/dropbear]] | SSH server options | |
| | [[docs:guide-user:firewall:firewall_configuration|/etc/config/firewall]] | NAT, packet filter, port forwarding, etc. | | | [[docs:guide-user:firewall:firewall_configuration|/etc/config/firewall]] | NAT, packet filter, port forwarding, etc. | |
| | [[docs:guide-user:network:ucicheatsheet|/etc/config/network]] | Switch, interface and route configuration | | | [[docs:guide-user:network:ucicheatsheet|/etc/config/network]] | Switch, interface and route configuration:\\ [[docs:guide-user:network:network_configuration|General]], [[docs:guide-user:network:ipv4:configuration|IPv4]], [[docs:guide-user:network:ipv6:configuration|IPv6]], [[docs:guide-user:network:routing:routes_configuration|Routes]], [[docs:guide-user:network:routing:ip_rules|Rules]], [[docs:guide-user:network:wan:wan_interface_protocols|WAN]], [[docs:guide-user:network:network_interface_alias|Aliases]], [[docs:guide-user:network:network_configuration|Switches]], [[docs:guide-user:network:vlan:switch_configuration|VLAN]], [[docs:guide-user:network:ipv6_ipv4_transitioning|IPv4/IPv6 transitioning]], [[docs:guide-user:network:tunneling_interface_protocols|Tunneling]] | |
| | [[docs:guide-user:base-system:system_configuration|/etc/config/system]] | Misc. system settings | | | [[docs:guide-user:base-system:system_configuration|/etc/config/system]] | Misc. system settings, [[docs:guide-user:advanced:ntp_configuration|NTP]], [[docs:guide-user:services:rng|RNG]], [[docs:guide-user:advanced:watchcat|Watchcat]] | |
| | [[docs:guide-user:network:wifi:basic|/etc/config/wireless]] | Wireless settings and wifi network definition | | | [[docs:guide-user:network:wifi:basic|/etc/config/wireless]] | Wireless settings and wifi network definition | |
| ^ IPv6 ^^ | ^ IPv6 || |
| | [[doc:uci:ahcpd|/etc/config/ahcpd]] | Ad-Hoc Configuration Protocol (AHCP) server and forwarder configuration | | | [[doc:uci:ahcpd|/etc/config/ahcpd]] | Ad-Hoc Configuration Protocol (AHCP) server and forwarder configuration | |
| | [[docs:guide-user:network:ipv6:dhcp6c|/etc/config/dhcp6c]] | WIDE-DHCPv6 client | | | [[docs:guide-user:network:ipv6:dhcp6c|/etc/config/dhcp6c]] | WIDE-DHCPv6 client | |
| | [[doc:uci:dhcp6s|/etc/config/dhcp6s]] | WIDE-DHCPv6 server | | | [[doc:uci:dhcp6s|/etc/config/dhcp6s]] | WIDE-DHCPv6 server | |
| | [[doc:uci:gw6c|/etc/config/gw6c]] | GW6c client configuration | | | [[doc:uci:gw6c|/etc/config/gw6c]] | GW6c client configuration | |
| ^ Other ^^ | ^ Other || |
| | [[docs:guide-user:services:babeld|/etc/config/babeld]] | babeld configuration | | | [[docs:guide-user:services:babeld|/etc/config/babeld]] | babeld configuration | |
| | [[docs:guide-user:services:bbstored|/etc/config/bbstored]] | BoxBackup server configuration | | | [[docs:guide-user:services:bbstored|/etc/config/bbstored]] | BoxBackup server configuration | |
| | [[docs:guide-user:base-system:ddns|/etc/config/ddns]] | Dynamic DNS configuration (ddns-scripts) | | | [[docs:guide-user:base-system:ddns|/etc/config/ddns]] | Dynamic DNS configuration (ddns-scripts) | |
| | [[docs:guide-user:services:w_o_l:etherwake|/etc/config/etherwake]] | Wake-on-Lan: etherwake | | | [[docs:guide-user:services:dns:dnscrypt-proxy|/etc/config/dnscrypt-proxy]] | DNSCrypt proxy | |
| | [[docs:guide-user:firewall:freifunk_p2pblock|/etc/config/freifunk_p2pblock]] | Uses iptables layer7-, ipp2p- and recent-modules to block p2p/filesharing traffic | | | [[docs:guide-user:virtualization:docker_host|/etc/config/dockerd]] | The Docker CE Engine Daemon | |
| | [[docs:guide-user:storage:fstab|/etc/config/fstab]] | Mount points and swap | | | [[docs:guide-user:services:email:emailrelay|/etc/config/emailrelay]] | E-MailRelay: simple SMTP server and proxy with POP support. Package [[:packages:pkgdata:emailrelay]] | |
| | [[docs:guide-user:storage:hd-idle|/etc/config/hd-idle]] | Another idle-daemon for attached hard drives | | | [[docs:guide-user:services:w_o_l:etherwake|/etc/config/etherwake]] | Wake-on-Lan: etherwake | |
| | [[docs:guide-user:base-system:httpd|/etc/config/httpd]] | Web server options (Busybox httpd, deprecated) | | | [[docs:guide-user:firewall:freifunk_p2pblock|/etc/config/freifunk_p2pblock]] | Uses iptables layer7-, ipp2p- and recent-modules to block p2p/filesharing traffic | |
| | [[docs:guide-user:services:dns:ipset-dns|/etc/config/ipset-dns]] | Configure [[http://git.zx2c4.com/ipset-dns/about/ ipset-dns]] | | | [[docs:guide-user:storage:fstab|/etc/config/fstab]] | Mount points and swap | |
| | [[doc:uci:luci|/etc/config/luci]] | Base LuCI config | | | [[docs:guide-user:storage:hd-idle|/etc/config/hd-idle]] | Another idle-daemon for attached hard drives | |
| | [[doc:uci:luci_statistics|/etc/config/luci_statistics]] | Configuration of Statistics packet| | | [[docs:guide-user:base-system:httpd|/etc/config/httpd]] | Web server options (Busybox httpd, deprecated) | |
| | [[docs:guide-user:services:snmp:mini_snmpd|/etc/config/mini_snmpd]] | mini_snmpd settings | | | [[docs:guide-user:services:dns:ipset-dns|/etc/config/ipset-dns]] | Configure [[https://git.zx2c4.com/ipset-dns/about/|ipset-dns]] | |
| | [[docs:guide-user:services:media_server:minidlna|/etc/config/minidlna]] | MiniDLNA settings | | | [[docs:guide-user:services:dns:kadnode|/etc/config/kadnode]] | KadNode p2p DNS | |
| | [[doc:uci:mjpg-streamer|/etc/config/mjpg-streamer]] | Streaming application for Linux-UVC compatible webcams | | | [[doc:uci:luci|/etc/config/luci]] | Base LuCI config | |
| | [[docs:guide-user:storage:mountd|/etc/config/mountd]] | OpenWrt automount daemon | | | [[doc:uci:luci_statistics|/etc/config/luci_statistics]] | Configuration of Statistics packet | |
| | [[doc:uci:mroute|/etc/config/mroute]] | Configuration files for multiple WAN routes | | | [[docs:guide-user:services:snmp:mini_snmpd|/etc/config/mini_snmpd]] | mini_snmpd settings | |
| | [[docs:guide-user:network:wan:multiwan:multiwan_package|/etc/config/multiwan]] | Simple multi WAN configuration | | | [[docs:guide-user:services:media_server:minidlna|/etc/config/minidlna]] | MiniDLNA settings | |
| | [[docs:guide-user:network:wan:multiwan:mwan3|/etc/config/mwan3]] | Multi-WAN config with load balancing and failover | | | [[doc:uci:mjpg-streamer|/etc/config/mjpg-streamer]] | Streaming application for Linux-UVC compatible webcams | |
| | [[docs:guide-user:services:captive-portal:nodogsplash|/etc/config/nodogsplash]] | nodogsplash configuration | | | [[docs:guide-user:storage:mountd|/etc/config/mountd]] | OpenWrt automount daemon | |
| | [[docs:guide-user:services:ntp:client|/etc/config/ntpclient]] | Getting the correct time | | | [[doc:uci:mroute|/etc/config/mroute]] | Configuration files for multiple WAN routes | |
| | [[docs:guide-user:services:ups:software.nut|/etc/config/nut_server]] | Controlling a UPS (Uninterruptible Power Supply) and/or sharing with other hosts | | | [[docs:guide-user:network:wan:multiwan:multiwan_package|/etc/config/multiwan]] | Simple multi WAN configuration | |
| | [[docs:guide-user:services:ups:software.nut|/etc/config/nut_monitor]] | Monitoring a UPS (Uninterruptible Power Supply) from a remote host or local nut-server | | | [[docs:guide-user:network:wan:multiwan:mwan3|/etc/config/mwan3]] | Multi-WAN config with load balancing and failover | |
| | [[docs:guide-user:services:ups:software.nut|/etc/config/nut_cgi]] | Web UI for NUT (viewing only in UCI) | | | [[docs:guide-user:services:captive-portal:nodogsplash|/etc/config/nodogsplash]] | nodogsplash configuration | |
| | [[docs:guide-user:services:print_server:p910nd|/etc/config/p910nd]] | config for non-spooling Printer daemon [[docs:guide-user:services:print_server:p910nd.server]] | | | [[docs:guide-user:services:ntp:client|/etc/config/ntpclient]] | Getting the correct time | |
| | [[docs:guide-user:services:nas:pure-ftpd|/etc/config/pure-ftpd]] | Pure-FTPd server config | | | [[docs:guide-user:services:ups:software.nut|/etc/config/nut_server]] | Controlling a UPS (Uninterruptible Power Supply) and/or sharing with other hosts | |
| | [[docs:guide-user:network:traffic-shaping:traffic_shaping|/etc/config/qos]] | Implementing Quality of Service for the //upload// | | | [[docs:guide-user:services:ups:software.nut|/etc/config/nut_monitor]] | Monitoring a UPS (Uninterruptible Power Supply) from a remote host or local nut-server | |
| | [[docs:guide-user:services:vpn:ipsec:racoon:basic|/etc/config/racoon]] | racoon IPsec daemon | | | [[docs:guide-user:services:ups:software.nut|/etc/config/nut_cgi]] | Web UI for NUT (viewing only in UCI) | |
| | [[docs:guide-user:services:nas:samba|/etc/config/samba]] | settings for the Microsoft file and print services daemon | | | [[docs:guide-user:services:print_server:p910nd|/etc/config/p910nd]] | config for non-spooling Printer daemon [[docs:guide-user:services:print_server:p910nd.server]] | |
| | [[docs:guide-user:services:snmp:snmpd|/etc/config/snmpd]] | SNMPd settings | | | [[docs:guide-user:services:nas:pure-ftpd|/etc/config/pure-ftpd]] | Pure-FTPd server config | |
| | [[docs:guide-user:network:traffic-shaping:sqm_configuration|/etc/config/sqm]] | SQM settings | | | [[docs:guide-user:network:traffic-shaping:traffic_shaping|/etc/config/qos]] | Implementing Quality of Service for the //upload// | |
| | [[docs:guide-user:services:ssh:sshtunnel|/etc/config/sshtunnel]] | Settings for the package ''sshtunnel'' | | | [[docs:guide-user:services:vpn:ipsec:racoon:basic|/etc/config/racoon]] | racoon IPsec daemon | |
| | [[docs:guide-user:services:voip:stund|/etc/config/stund]] | STUN server configuration | | | [[docs:guide-user:services:nas:samba|/etc/config/samba]] | settings for the Microsoft file and print services daemon | |
| | [[doc:uci:tinc|/etc/config/tinc]] | [[docs:guide-user:services:vpn:tinc|tinc]] package configuration | | | [[docs:guide-user:services:snmp:snmpd|/etc/config/snmpd]] | SNMPd settings | |
| | [[docs:guide-user:services:downloading_and_filesharing:transmission|/etc/config/transmission]] | BitTorrent configuration | | | [[docs:guide-user:network:traffic-shaping:sqm_configuration|/etc/config/sqm]] | SQM settings | |
| | [[docs:guide-user:services:webserver:uhttpd|/etc/config/uhttpd]] | Web server options (uHTTPd) | | | [[docs:guide-user:services:ssh:sshtunnel|/etc/config/sshtunnel]] | Settings for the package ''sshtunnel'' | |
| | [[docs:guide-user:firewall:upnp:miniupnpd|/etc/config/upnpd]] | miniupnpd UPnP server settings | | | [[docs:guide-user:services:voip:stund|/etc/config/stund]] | STUN server configuration | |
| | [[docs:guide-user:base-system:users|/etc/config/users]] | user database for different services | | | [[doc:uci:tinc|/etc/config/tinc]] | [[docs:guide-user:services:vpn:tinc|tinc]] package configuration | |
| | [[docs:guide-user:services:media_server:ushare|/etc/config/ushare]] | uShare UPnP server settings | | | [[docs:guide-user:services:tor:client|/etc/config/tor]] | Tor configuration | |
| | [[docs:guide-user:services:vblade|/etc/config/vblade]] | vblade userspace AOE target | | | [[docs:guide-user:services:tor:hs|/etc/config/tor-hs]] | Tor hidden services configuration | |
| | [[docs:guide-user:services:network_monitoring:vnstat|/etc/config/vnstat]] | vnstat downloader settings | | | [[docs:guide-user:services:downloading_and_filesharing:transmission|/etc/config/transmission]] | BitTorrent configuration | |
| | [[docs:guide-user:network:wifi:wifi_toggle|/etc/config/wifitoggle]] | Toggle WiFi with a button | | | [[docs:guide-user:services:webserver:uhttpd|/etc/config/uhttpd]] | Web server options (uHTTPd) | |
| | [[docs:guide-user:services:w_o_l:wol|/etc/config/wol]] | Wake-on-Lan: wol | | | [[docs:guide-user:firewall:upnp:miniupnpd|/etc/config/upnpd]] | miniupnpd UPnP server settings | |
| | [[docs:guide-user:services:proxy:znc|/etc/config/znc]] | ZNC bouncer configuration | | | [[docs:guide-user:base-system:users|/etc/config/users]] | user database for different services | |
| | | [[docs:guide-user:services:media_server:ushare|/etc/config/ushare]] | uShare UPnP server settings | |
| | | [[docs:guide-user:services:vblade|/etc/config/vblade]] | vblade userspace AOE target | |
| | | [[docs:guide-user:services:network_monitoring:vnstat|/etc/config/vnstat]] | vnstat downloader settings | |
| | | [[docs:guide-user:network:wifi:wifi_toggle|/etc/config/wifitoggle]] | Toggle WiFi with a button | |
| | | [[docs:guide-user:services:w_o_l:wol|/etc/config/wol]] | Wake-on-Lan: wol | |
| | | [[docs:guide-user:services:proxy:znc|/etc/config/znc]] | ZNC bouncer configuration | |
| |
| ===== File syntax ===== | ===== File syntax ===== |
| </code> | </code> |
| |
| * 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 ''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', 'false' or 'disabled' to specify a false value or '1' , 'yes', 'on', 'true' or 'enabled' to specify a true value. | * 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', 'false' or 'disabled' to specify a false value or '1' , 'yes', 'on', 'true' or 'enabled' 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. | * 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. |
| |
| It is important to know that UCI identifiers and config file names may contain only the characters ''a-z'', ''0-9'' and ''_''. | It is important to know that UCI identifiers and config file names may contain only the characters ''a-z'', ''0-9'' and ''_''. |
| E.g. no hyphens (-) are allowed. | E.g. no hyphens (''-'') are allowed. |
| Option values may contain any character (as long they are properly quoted). | Option values may contain any character (as long they are properly quoted). |
| |
| Syntax highlighting and (slightly) more in vim: [[https://github.com/cmcaine/vim-uci |vim-uci]] - works well with sshfs (need openssh-sftp-server). | Syntax highlighting and (slightly) more in vim: [[https://github.com/cmcaine/vim-uci |vim-uci]] - works well with sshfs (need openssh-sftp-server). |
| |
| ===== Command line utility ===== | ===== Command-line utility ===== |
| For adjusting settings, one normally changes the UCI config files directly. | For adjusting settings, one normally changes the UCI config files directly. |
| However, for scripting purposes, all of UCI configuration can also be read and changed using the ''uci'' command line utility. | However, for scripting purposes, all of UCI configuration can also be read and changed using the ''uci'' command line utility. |
| Below is the usage, as well as some useful examples of how to use this powerful utility. | Below is the usage, as well as some useful examples of how to use this powerful utility. |
| |
| | {{:meta:icons:tango:48px-dialog-warning.svg.png?nolink&24}} When using ''uci'' to write configuration files, the files are always rewritten in whole and non-recognised commands are omitted. This means that any extraneous lines in the file are deleted, such as comments. If you have UCI configuration files that you have edited yourself and you want to preserve your own comments and blank lines, you should not use the command line utility but edit the files normally. Note that some files, such as the uHTTPd configuration file, already contain many comments when the application is first installed. Also, note that some applications such as [[docs:techref:luci|LuCI]] also use the ''uci'' utility and thus may rewrite UCI configuration files. | | <WRAP important> |
| | When using ''uci'' to write configuration files, the files are always rewritten in whole and non-recognised commands are omitted. This means that any extraneous lines in the file are deleted, such as comments. If you have UCI configuration files that you have edited yourself and you want to preserve your own comments and blank lines, you should not use the command line utility but edit the files normally. Note that some files, such as the uHTTPd configuration file, already contain many comments when the application is first installed. Also, note that some applications such as [[docs:techref:luci|LuCI]] also use the ''uci'' utility and thus may rewrite UCI configuration files. |
| | </WRAP> |
| |
| When there are multiple rules next to each other, UCI supports array-like references for them. | When there are multiple sections of the same type in a config, UCI supports array-like references for them. |
| If there are 8 NTP servers defined in ''/etc/config/system'', UCI will let you reference their sections as ''system.@timeserver[0]'' for the first or ''system.@timeserver[7]'' for the last one. | If there are 8 NTP servers defined in ''/etc/config/system'', UCI will let you reference their sections as ''system.@timeserver[0]'' for the first or ''system.@timeserver[7]'' for the last one. |
| You can also use negative indexes, such as ''system.@timeserver[-1]''. | You can also use negative indexes, such as ''system.@timeserver[-1]''. |
| get <config>.<section>[.<option>] | get <config>.<section>[.<option>] |
| set <config>.<section>[.<option>]=<value> | set <config>.<section>[.<option>]=<value> |
| delete <config>[.<section[.<option>]] | delete <config>.<section>[.<option>] |
| rename <config>.<section>[.<option>]=<name> | rename <config>.<section>[.<option>]=<name> |
| revert <config>[.<section>[.<option>]] | revert <config>[.<section>[.<option>]] |
| </code> | </code> |
| |
| | <sortable> |
| ^ ''Command'' ^ Target ^ Description ^ | ^ ''Command'' ^ Target ^ Description ^ |
| | ''commit'' | ''[<config>]'' | Writes changes of the given configuration file, or if none is given, all configuration files, to the filesystem. All "uci set", "uci add", "uci rename" and "uci delete" commands are staged into a temporary location and written to flash at once with "uci commit". This is not needed after editing configuration files with a text editor, but for scripts, GUIs and other programs working directly with UCI files. | | | ''commit'' | ''[<config>]'' | Writes changes of the given configuration file, or if none is given, all configuration files, to the filesystem. All "uci set", "uci add", "uci rename" and "uci delete" commands are staged into a temporary location and written to flash at once with "uci commit". This is not needed after editing configuration files with a text editor, but for scripts, GUIs and other programs working directly with UCI files. | |
| | ''get'' | ''<config>.<section>[.<option>]'' | Get the value of the given option or the type of the given section. | | | ''get'' | ''<config>.<section>[.<option>]'' | Get the value of the given option or the type of the given section. | |
| | ''set'' | ''<config>.<section>[.<option>]=<value>'' | Set the value of the given option, or add a new section with the type set to the given value. | | | ''set'' | ''<config>.<section>[.<option>]=<value>'' | Set the value of the given option, or add a new section with the type set to the given value. | |
| | ''delete'' | ''<config>[.<section[.<option>]]'' | Delete the given section or option. | | | ''delete'' | ''<config>.<section>[.<option>]'' | Delete the given section or option. | |
| | ''rename'' | ''<config>.<section>[.<option>]=<name>'' | Rename the given option or section to the given name. | | | ''rename'' | ''<config>.<section>[.<option>]=<name>'' | Rename the given option or section to the given name. | |
| | ''revert'' | ''<config>[.<section>[.<option>]]'' | Revert the given option, section or configuration file. | | | ''revert'' | ''<config>[.<section>[.<option>]]'' | Revert the given option, section or configuration file. | |
| | ''reorder'' | ''<config>.<section>=<position>'' | Move a section to another position. | | | ''reorder'' | ''<config>.<section>=<position>'' | Move a section to another position. | |
| | </sortable> |
| | |
| | Note that you cannot delete an entire config using ''uci delete'' eg. ''uci delete umdns'' will not work. If you are really, truly sure you want to wipe an entire config, this shell code snippet will do it by looping and deleting the first entry in the config until it is empty: |
| | |
| | <code bash> |
| | while uci -q delete umdns.@umdns[0]; do :; done |
| | </code> |
| |
| ===== UCI data/object model ===== | ===== UCI data/object model ===== |
| A section can be //named// or //unnamed//. | A section can be //named// or //unnamed//. |
| Unnamed sections will get an **autogenerated ID/CFGID** (like "cfg073777") and be presented with an **anonymous-name** (like "@switch[0]") | Unnamed sections will get an **autogenerated ID/CFGID** (like "cfg073777") and be presented with an **anonymous-name** (like "@switch[0]") |
| | |
| | Section names may only contain alphanum and "_" (for shell compatibility). Hyphen '-' is not allowed. |
| |
| Example of **anonymous-name**: | Example of **anonymous-name**: |
| The same config section can be presented in different ways: | The same config section can be presented in different ways: |
| * Human-friendly: as presented in the config files or with the command "uci export <config>" | * Human-friendly: as presented in the config files or with the command "uci export <config>" |
| * Programmable: as presented with the command "uci show <config>.." | * Programmable: as presented with the command "uci show <config>" |
| |
| ^ Different model presentations ^^^ | ^ Different model presentations ^^^ |
| Available subsystems are: **defaults**, **dnsmasq**, **dropbear**, **firewall**, **fstab**, **net**, **qos**, **samba**, **system**, **wireless**. | Available subsystems are: **defaults**, **dnsmasq**, **dropbear**, **firewall**, **fstab**, **net**, **qos**, **samba**, **system**, **wireless**. |
| |
| === Show the a subsystem's current configuration === | === Show a subsystem's current configuration === |
| <code bash> | <code bash> |
| uci show SUBSYSTEM_NAME | uci show SUBSYSTEM_NAME |
| </code> | </code> |
| |
| === Generating a full uci section with a simple copy-paste === | === Generating a full UCI section with a simple copy-paste === |
| This block of code catches the code printed by uci when you add a new section (see above) and reuses it in all the new keys you want to add after it. This automates what would be a very fun typing or copy-paste job. You can also do this in your scripts. | This block of code catches the code printed by uci when you add a new section (see above) and reuses it in all the new keys you want to add after it. This automates what would be a very fun typing or copy-paste job. You can also do this in your scripts. |
| |
| <code bash> | <code bash> |
| rule_name=$(uci add <config> <section-type>) | rule_name=$(uci add <config> <section-type>) |
| uci batch << EOF | uci batch << EOI |
| set <config>.$rule_name.<option1>='value' | set <config>.$rule_name.<option1>='value' |
| set <config>.$rule_name.<option2>='value' | set <config>.$rule_name.<option2>='value' |
| set <config>.$rule_name.<option3>='value' | set <config>.$rule_name.<option3>='value' |
| ... | ... |
| EOF | EOI |
| uci commit | uci commit |
| </code> | </code> |
| <code bash> | <code bash> |
| rule_name=$(uci add firewall rule) | rule_name=$(uci add firewall rule) |
| uci batch << EOF | uci batch << EOI |
| set firewall.$rule_name.enabled='1' | set firewall.$rule_name.enabled='1' |
| set firewall.$rule_name.target='ACCEPT' | set firewall.$rule_name.target='ACCEPT' |
| set firewall.$rule_name.dest_port='111' | set firewall.$rule_name.dest_port='111' |
| set firewall.$rule_name.name='NFS_share' | set firewall.$rule_name.name='NFS_share' |
| EOF | EOI |
| uci commit | uci commit |
| </code> | </code> |
| |
| <code bash> | <code bash> |
| # uci import playapp </dev/null | # uci import playapp < /dev/null |
| # uci show playapp | # uci show playapp |
| # uci add playapp blah | # uci add playapp blah |
| |
| <code bash> | <code bash> |
| # uci import playapp </dev/null | # uci import playapp < /dev/null |
| # uci set playapp.myname=mysectiontype | # uci set playapp.myname=mysectiontype |
| # uci set playapp.othername=mysectiontype | # uci set playapp.othername=mysectiontype |
| foo.first=bar | foo.first=bar |
| foo.first.name='Mr. First' | foo.first.name='Mr. First' |
| </code> | |
| |
| === Query interface state === | |
| <code bash> | |
| # 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 | |
| </code> | </code> |
| |
| uci commit firewall | uci commit firewall |
| /etc/init.d/firewall restart | /etc/init.d/firewall restart |
| </code> | |
| |
| === Get WAN IP address === | |
| <code bash> | |
| uci -P/var/state get network.wan.ipaddr | |
| </code> | |
| |
| The uci state vars are deprecated (Backfire) and not used anymore for network related information. | |
| In Trunk (not really uci) do: | |
| |
| <code bash> | |
| source /lib/functions/network.sh | |
| network_get_ipaddr ip wan | |
| echo $ip | |
| </code> | |
| |
| === Get WAN interface === | |
| <code bash> | |
| uci -P/var/state get network.wan.ifname | |
| </code> | |
| |
| The uci state vars are deprecated (Backfire) and not used anymore for network related information. | |
| In Trunk (not really uci) do: | |
| |
| <code bash> | |
| source /lib/functions/network.sh | |
| network_get_device if_wan wan | |
| echo $if_wan | |
| network_get_physdev if_wan wan | |
| echo $if_wan | |
| </code> | </code> |
| |
| === Get SSID === | === Get SSID === |
| <code bash> | <code bash> |
| uci get wireless.@wifi-iface[-1].ssid | uci get wireless.@wifi-iface[0].ssid |
| </code> | </code> |
| |
| ==== UCI defaults ==== | |
| To set some system defaults the first time the device boots, create a script in the folder ''/etc/uci-defaults/''. | |
| |
| All scripts in that folder are automatically executed by ''/etc/init.d/boot'' and if they exited with code 0 __deleted afterwards__ (scripts that did not exit with code 0 are not deleted and will be re-executed during the next boot until they also successfully exit). | |
| |
| In a live router you can see the existing uci-defaults scripts in ''/rom/etc/uci-defaults'' , as ''/etc/uci-defaults'' itself is typically empty (after all scripts have been run ok and have been deleted). | |
| |
| This is a simple example of changing the default ip at first boot. | |
| |
| <code bash> | |
| #!/bin/sh | |
| uci set network.lan.ipaddr='192.168.178.1' | |
| uci commit network | |
| exit 0 | |
| </code> | |
| |
| This is a simple example of changing the default SSID and also turning WiFi on at first boot. | |
| |
| <code bash> | |
| #!/bin/sh | |
| uci set wireless.@wifi-device[0].disabled='0' | |
| uci set wireless.@wifi-iface[0].ssid='OpenWrt0815' | |
| uci commit wireless | |
| exit 0 | |
| </code> | |
| |
| Easiest way to include uci-defaults scripts in your firmware may be as custom files. | |
| See [[docs:guide-developer:build-system:use-buildsystem#custom_files|Buildroot - Custom files]] or [[docs:guide-user:additional-software:imagebuilder#files_variable|Image generator - Custom files]] | |
| |
| ===== Porting UCI to a different Linux distribution ===== | ===== Porting UCI to a different Linux distribution ===== |
| See [[docs:techref:uci#usage_outside_of_openwrt|UCI (Unified Configuration Interface) – Technical Reference]] | See [[docs:techref:uci#usage_outside_of_openwrt|UCI (Unified Configuration Interface) – Technical Reference]] |
| |
| ===== Finding faulty configs ===== | ===== Corrupted configs ===== |
| If you have any errors on generic ''uci'' commands (like ''uci commit'') one of the files in ''/etc/config/'' may be misconfigured/broken. To find the offending file, run: | See also: |
| | [[docs:guide-user:advanced:uci_extras|UCI extras]] |
| | |
| | If you manually edited the configs in ''/etc/config'', it is possible that some of them are corrupted due to typos. |
| |
| <code bash> | <code bash> |
| for i in /etc/config/* | # uci show fstab |
| do | uci: Parse error (invalid command) at line 20, byte 0 |
| if ! uci show ${i##*/} &>/dev/null | |
| then | |
| echo -e -n "$i: " | |
| uci show ${i##*/} >/dev/null | |
| fi | |
| done | |
| </code> | </code> |
| |
| FIXME //Please add example error messages.// | |
| |
| {{tag>UCI}} | |
| |