Differences

This shows you the differences between two versions of the page.

doc:uci [2013/07/08 15:43]
tmomas spelling correction
doc:uci [2014/09/09 18:33] (current)
gslurp
Line 3: Line 3:
The abbreviation [[doc:techref:uci|UCI]]  stands for //**__U__**nified **__C__**onfiguration **__I__**nterface// and is intended to centralize the configuration of OpenWrt. The abbreviation [[doc:techref:uci|UCI]]  stands for //**__U__**nified **__C__**onfiguration **__I__**nterface// and is intended to centralize the configuration of OpenWrt.
-Configuration should be easy, straightforward and documented here, making life easier! UCI is the successor to the NVRAM-based configuration found in the White Russian series of OpenWrt.+Configuration should be easy and straightforward, making life easier! UCI is all about that. It is the successor to the NVRAM-based configuration found in the White Russian series of OpenWrt. UCI can be seen as OpenWrt's main configuration user interface for the most important system settings. Typically, these are settings that are crucial for the functioning of the device, such as are typically found in the web interface of routers and embedded devices. That is, functionality that is integrated in the system builds. Examples are the main network interface configuration, wireless settings, logging functionality and remote access configuration. 
 + 
 +In addition, selected third party programs have been made compatible with the UCI system, so these can be managed more easily as well. Many programs have their own configuration files lying around somewhere, like ''/etc/network/interfaces'', ''/etc/exports'', ''/etc/dnsmasq.conf'' or ''/etc/samba/samba.conf'' and they often use different syntaxes. With OpenWrt you don't have to bother with any of them and only need to change the UCI configuration files. Of course, most of the software that you would like to install will not have been prepared for UCI configuration. Which is a good thing, because oftentimes you will want the full power of an application's own configuration interface, like it was intended by the developers. Therefore, only a few selected programs which benefit from availability of a centralised configuration have been made UCI-compatible by the OpenWrt package maintainers (see the UCI configuration file list below).  
 + 
 +Most applications (save some that are made in-house) are made UCI compatible by the package maintainer 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 initialisation scripts in ''/etc/init.d/''. See [[doc:techref:initscripts|Init scripts]] for more information. Thus, when starting a daemon with such an UCI compatible initilisation script, you should be aware that the program's original configuration file gets overwritten. For example, in the case of [[doc:howto:cifs.server|Samba/CIFS]], the file ''/etc/samba/smb.conf'' is overwritten with UCI settings from the UCI configuration file ''/etc/config/samba'' when running ''/etc/init.d/samba start''. In addition, the application's configuration file is often stored in RAM instead of in flash, because it does not need to be stored in non-volatile memory and it is rewritten after every change, based on the UCI file. There are ways to disable UCI in case you want to adjust settings in the original configuration file not available through UCI. FIXME add the recommended way please, or link to it. 
 + 
 +For those non-UCI compatible programs, there is a convenient [[doc:howto:notuci.config|list of some non-UCI configuration files]] you may want to tend to. Note that for most third party programs you should consult the program's own documentation. 
 + 
 +/* NOTE THIS IS NOT TRUE AND THEREFORE COMMENTED OUT. UCI IS NOTHING MORE THEN A CENTRAL PLACE FOR YOUR CONFIG. SEE THE EXAMPLE BELOW: YOU STILL HAVE TO RESTART THE uHTTPd SERVER MANUALLY. WITHOUT UCI THIS WOULD WORK THE SAME. THIS COMMENT SECTION CAN BE DELETED AFTER SOME TIME OR AFTER THE ORIGINAL AUTHOR HAS READ IT: You no longer have to reboot your system to make configuration changes. You can use the [[doc:uci#command.line.utility|UCI command line utility]] instead. AGAIN, UCI COMMAND LINE UTILITY HAS NOTHING TO DO WITH THE ABILITY TO COMMIT CHANGES WITHOUT REBOOT */ 
-Many programs have their own configuration files lying around somewhere, like ''/etc/network/interfaces'', ''/etc/exports'', ''/etc/dnsmasq.conf'' or ''/etc/samba/samba.conf'' and they often use different syntaxes. With OpenWrt you don't have to bother with any of them and only need to change the UCI configuration files. 
-You no longer have to reboot your system to make configuration changes. You can use the [[doc:uci#command.line.utility|UCI command line utility]] instead. And please do not forget that quite some daemons are included in the official binaries, but they are not enabled by default! For example the ''cron'' daemon is not activated by default, thus only editing the ''crontab'' won't do anything. You have to either start the daemon with ''/etc/init.d/cron start'' or enable it with ''/etc/init.d/cron enable''. You can ''disable'', ''stop'' and ''restart'' most of those daemons, too. There are some [[doc:howto:notuci.config|not UCI configuration files]] you may want to tend to. 
===== Common Principles ===== ===== Common Principles =====
 +OpenWrt's central configuration is split into several files located in the ''/etc/config/'' directory. Each file roughly relates to the part of the system it configures. You can edit the configuration files with a text editor or with the command line utility program ''uci''. UCI is also editable through various programming APIs (like Shell, Lua and C), which is also how web interfaces like [[doc:howto:luci.essentials‎|LuCI]] make changes to the UCI files.
 +
 +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 by an [[doc/techref/initscripts|init.d call]], such that the 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. 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. 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''. To do this, using any text editor, such as vi, change the line
 +
 +''option ipaddr 192.168.1.1''
 +
 +in the file ''/etc/config/network'' to:
 +
 +''option ipaddr 192.168.2.1''
 +
 +Next, commit the settings by running
 +
 +''/etc/init.d/network restart''
-OpenWrt's central configuration is split into several files located in the ''/etc/config/'' directory. Each file roughly relates to the part of the system it configures. You can edit the configuration files with a text editor or with the command line utility program ''uci'' or through various programming APIs (like Shell, Lua and C).+In this case, remember that you have to login again using SSH as the device is now accessible at its new IP address!
===== Configuration Files ===== ===== Configuration Files =====
Line 39: Line 61:
| [[doc:uci:hd-idle|/etc/config/hd-idle]] | Another idle-daemon for attached hard drives | | [[doc:uci:hd-idle|/etc/config/hd-idle]] | Another idle-daemon for attached hard drives |
| [[doc:uci:httpd|/etc/config/httpd]] | Web server options (Busybox httpd, deprecated) | | [[doc:uci:httpd|/etc/config/httpd]] | Web server options (Busybox httpd, deprecated) |
 +| [[doc:uci:ipset-dns|/etc/config/ipset-dns]] | Configure [[http://git.zx2c4.com/ipset-dns/about/ ipset-dns]] |
| [[doc:uci:luci|/etc/config/luci]] | Base LuCI config | | [[doc:uci:luci|/etc/config/luci]] | Base LuCI config |
| [[doc:uci:luci_statistics|/etc/config/luci_statistics]] | Configuration of Statistics packet| | [[doc:uci:luci_statistics|/etc/config/luci_statistics]] | Configuration of Statistics packet|
Line 56: Line 79:
| [[doc:uci:sshtunnel|/etc/config/sshtunnel]] | Settings for the package ''sshtunnel'' | | [[doc:uci:sshtunnel|/etc/config/sshtunnel]] | Settings for the package ''sshtunnel'' |
| [[doc:uci:stund|/etc/config/stund]] | STUN server configuration | | [[doc:uci:stund|/etc/config/stund]] | STUN server configuration |
 +| [[doc:uci:tinc|/etc/config/tinc]] | [[doc/howto/vpn.tinc|tinc]] package configuration |
| [[doc:uci:transmission|/etc/config/transmission]] | BitTorrent configuration | | [[doc:uci:transmission|/etc/config/transmission]] | BitTorrent configuration |
| [[doc:uci:uhttpd|/etc/config/uhttpd]] | Web server options (uHTTPd) | | [[doc:uci:uhttpd|/etc/config/uhttpd]] | Web server options (uHTTPd) |
Line 89: Line 113:
  * The indentation of the ''option'' and ''list'' statements is a convention to improve the readability of the configuration file but it's not syntactically required.   * The indentation of the ''option'' and ''list'' statements is a convention to improve the readability of the configuration file but it's not syntactically required.
 +
 +  * If an option is absent and not required, the default value is assumed. If it is absent and required, it may trigger an error in the application or other unwanted behaviour.
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. 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.
Line 105: Line 131:
  * ''option example some value with space '' (note the missing quotes around the value)   * ''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).+It is important to know that UCI identifiers and config file names may only contain the characters ''a-z'', ''0-9'' and ''_''. E.g. no hyphens (-) are allowed. Option values may contain any character (as long they are properly quoted).
===== Command Line Utility ===== ===== 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!  +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. For developers requiring automatic parsing of the UCI configuration it is therefore redundant, unwise, and inefficient to use ''awk'' and ''grep'' to parse OpenWrt's config files. The ''uci'' utility offers all functionality with respect to modifying and parsing UCI.
-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!+Below is the usage, as well as some useful examples of how to use this powerful utility.
-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. +|{{: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 blanc 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 [[doc/techref/luci|LuCI]] also use the ''uci'' utility and thus may rewrite UCI configuration files.| 
-====== Usage ======+ 
 +/* Remember, friends don't let friends parse their own config files!  << I fail to see the point ... */ 
 + 
 + 
 +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 the examples below. 
 + 
 +==== Usage ====
''root@OpenWrt:/lib/config# **uci**'' ''root@OpenWrt:/lib/config# **uci**''
Line 151: Line 183:
^ ''Command'' ^ Target ^ Description  ^ ^ ''Command'' ^ Target ^ Description  ^
-| ''commit''  | ''[<config>]'' | Writes changes of the given configuration file, or if none is given, all configration 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. |
| ''batch''    | - | Executes a multi-line UCI script which is typically wrapped into a //here// document syntax. | | ''batch''    | - | Executes a multi-line UCI script which is typically wrapped into a //here// document syntax. |
| ''export''  | ''[<config>]'' | Exports the configuration in a machine readable format. It is used internally to evaluate configuration files as shell scripts. | | ''export''  | ''[<config>]'' | Exports the configuration in a machine readable format. It is used internally to evaluate configuration files as shell scripts. |
Line 167: Line 199:
==== Examples: ==== ==== Examples: ====
-=== No need to reboot ===+=== Setting a value ===
-After changing the port uhttpd listens on from 80 to 8080 in the file /etc/config/uhttpd, save it. Then do+If we want to change the listening port of the [[doc:howto:http.uhttpd|uHTTPd Web Server]] from 80 to 8080 we change the configuration in ''/etc/config/uhttpd'' :
-| ''uci commit uhttpd'' | +| ''root@OpenWrt:~# **uci set uhttpd.main.listen_http=8080** 
- +root@OpenWrt:~# **uci commit uhttpd** 
-And then a +root@OpenWrt:~# **/etc/init.d/uhttpd restart** 
- +root@OpenWrt:~#'' |
-| ''/etc/init.d/uhttpd restart'' |+
-Done. No reboot needed.+Done, now the configuration file is updated and uHTTPd listens on port 8080.
=== Export an entire configuration === === Export an entire configuration ===
Line 215: Line 246:
uci add_list system.ntp.server='2.de.pool.ntp.org' uci add_list system.ntp.server='2.de.pool.ntp.org'
'' | '' |
 +
 +=== Create a new named section of a given type ===
 +
 +"uci add blah" will create a new _anonymous_ section of type blah. ie,
 +
 +| ''#touch /etc/config/playapp
 +#uci show playapp
 +#uci add playapp blah
 +cfg02a4fc
 +#uci show playapp
 +playapp.@blah[0]=blah
 +# uci commit && cat /etc/config/playapp
 +
 +config blah
 +
 +#
 +''|
 +
 +If you actually want a named section of that type, for instance,
 +
 +|''config blah this_name
 +    option xxx yyy
 +config blah other_name
 +    option xxx zzz
 +''|
 +
 +Then "uci add" cannot be used, instead, use this synt
 +
 +|''#rm /etc/config/playapp && touch /etc/config/playapp
 +# uci set playapp.myname=mysectiontype
 +# uci set playapp.othername=mysectiontype
 +# uci commit && uci show playapp
 +playapp.myname=mysectiontype
 +playapp.othername=mysectiontype
 +# cat /etc/config/playapp
 +
 +config mysectiontype 'myname'
 +
 +config mysectiontype 'othername'
 +
 +''|
 +
=== UCI paths === === UCI paths ===
Line 319: Line 392:
To set some system defaults the first time the device boots, create a script in the folder To set some system defaults the first time the device boots, create a script in the folder
<code>/etc/uci-defaults/</code> <code>/etc/uci-defaults/</code>
-All scripts in that folder are automatically executed by ''/etc/init.d/S10boot'' 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).+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).
===== Porting UCI to a different Linux distribution ===== ===== Porting UCI to a different Linux distribution =====
  * [[https://forum.openwrt.org/viewtopic.php?id=15243]]   * [[https://forum.openwrt.org/viewtopic.php?id=15243]]
 +  * http://tabloidharga.com
 +  * http://aurora-ndut.com

Back to top

doc/uci.1373290997.txt.bz2 · Last modified: 2013/07/08 15:43 by tmomas