See also: [[docs:guide-developer:uci-defaults|UCI defaults]], [[docs:guide-developer:network-scripting#examples|Network scripting]]
-
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.
+
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.
-
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. Like for example the main network interface configuration, wireless settings, logging functionality and remote access configuration.
+
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.
-
In addition, many packages in the OpenWrt repository have been made compatible with the UCI system.
+
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.
+
This is done upon running the initialization scripts in ''/etc/init.d/''.
+
See [[docs:techref:initscripts|Init scripts]] for more information.
+
Thus, when starting a daemon with such a UCI-compatible initialization script, you should be aware that the program's original configuration file gets overwritten.
+
For example, in the case of [[docs:guide-user:services:nas: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, in [[docs:guide-user:services:nas:cifs.server]] you can see how to disable UCI for samba, for example.
-
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/''. See [[docs:techref:initscripts|Init scripts]] for more information. Thus, when starting a daemon with such a UCI-compatible initialization script, you should be aware that the program's original configuration file gets overwritten. For example, in the case of [[docs:guide-user:services:nas: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, in [[docs:guide-user:services:nas:cifs.server]] you can see how to disable UCI for samba, for example.
+
For those non-UCI compatible programs, there is a convenient [[docs:guide-user:base-system: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.
-
For those non-UCI compatible programs, there is a convenient [[docs:guide-user:base-system: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.
+
===== Common principles =====
+
OpenWrt's central configuration is split into several files located in the ''/etc/config/'' directory.
+
Each file relates roughly to the part of the system it configures.
+
You can edit the configuration files with a text editor or modify them with the command line utility program ''uci''.
+
UCI configuration files are also modifiable through various programming APIs (like Shell, Lua and C), which is also how web interfaces like [[docs:guide-user:luci: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 (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 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.
+
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)]].
-
===== Common Principles =====
+
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''.
-
OpenWrt's central configuration is split into several files located in the ''/etc/config/'' directory. Each file relates roughly to the part of the system it configures. You can edit the configuration files with a text editor or modify them with the command line utility program ''uci''. UCI configuration files are also modifiable through various programming APIs (like Shell, Lua and C), which is also how web interfaces like [[docs:guide-user:luci:luci.essentials|LuCI]] make changes to the UCI files.
+
To do this, using any text editor, such as vi, change the line
-
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. 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.
+
<code bash>
-
+
option ipaddr 192.168.1.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''. To do this, using any text editor, such as vi, change the line
+
</code>
-
+
-
''option ipaddr 192.168.1.1''
+
in the file ''/etc/config/network'' to:
in the file ''/etc/config/network'' to:
-
''option ipaddr 192.168.2.1''
+
<code bash>
+
option ipaddr 192.168.2.1
+
</code>
Next, commit the settings by running
Next, commit the settings by running
-
''/etc/init.d/network restart''
+
<code bash>
+
/etc/init.d/network restart
+
</code>
In this case, remember that you have to login again using SSH as the device is now accessible at its new IP address!
In this case, remember that you have to login again using SSH as the device is now accessible at its new IP address!
| [[docs:guide-user:virtualization:docker_host|/etc/config/dockerd]] | The Docker CE Engine Daemon |
-
| [[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:email:emailrelay|/etc/config/emailrelay]] | E-MailRelay: simple SMTP server and proxy with POP support. Package [[:packages:pkgdata:emailrelay]] |
-
| [[docs:guide-user:storage:fstab|/etc/config/fstab]] | Mount points and swap |
| [[doc:uci:mroute|/etc/config/mroute]] | Configuration files for multiple WAN routes |
-
| [[docs:guide-user:services:ntp:client|/etc/config/ntpclient]] | Getting the correct time |
+
| [[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_server]] | Controlling a UPS (Uninterruptible Power Supply) and/or sharing with other hosts |
+
| [[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_monitor]] | Monitoring a UPS (Uninterruptible Power Supply) from a remote host or local nut-server |
| [[docs:guide-user:services:ups:software.nut|/etc/config/nut_cgi]] | Web UI for NUT (viewing only in UCI) |
+
| [[docs:guide-user:services:ntp:client|/etc/config/ntpclient]] | Getting the correct time |
-
| [[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:ups:software.nut|/etc/config/nut_server]] | Controlling a UPS (Uninterruptible Power Supply) and/or sharing with other hosts |
-
| [[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_monitor]] | Monitoring a UPS (Uninterruptible Power Supply) from a remote host or local nut-server |
-
| [[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_cgi]] | Web UI for NUT (viewing only in UCI) |
The UCI configuration files usually consist of one or more ''config'' statements, so called sections with one or more option statements defining the actual values.
The UCI configuration files usually consist of one or more ''config'' statements, so called sections with one or more option statements defining the actual values.
-
A ''#'' begins comments in the usual way. Specifically, if a line contains a ''#'' outside of a string literal, it and all characters after it in the line are considered a comment and ignored.
+
A ''#'' begins comments in the usual way.
+
Specifically, if a line contains a ''#'' outside of a string literal, it and all characters after it in the line are considered a comment and ignored.
Below is an example of a simple configuration file (see also [[#uci_dataobject_model]]):
Below is an example of a simple configuration file (see also [[#uci_dataobject_model]]):
-
<code>package 'example'
+
<code bash>
+
package 'example'
config 'example' 'test'
config 'example' 'test'
Line 107:
Line 131:
option 'boolean' '1'
option 'boolean' '1'
list 'collection' 'first item'
list 'collection' 'first item'
-
list 'collection' 'second item'</code>
+
list 'collection' 'second item'
+
</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.
Line 125:
Line 150:
All of the examples below are valid UCI syntax:
All of the examples below are valid UCI syntax:
-
* ''option example value''
+
<code bash>
-
* ''option 'example' value''
+
option example value
-
* ''option example "value"''
+
option example "value"
-
* ''option "example" 'value' ''
+
option 'example' value
-
* ''option 'example' "value"''
+
option 'example' "value"
+
option "example" 'value'
+
</code>
In contrast, the following examples are not valid UCI syntax:
In contrast, the following examples are not valid UCI syntax:
-
* ''option 'example" "value' '' (quotes are unbalanced)
+
<code bash>
-
* ''option example some value with space '' (note the missing quotes around the value)
+
# missing quotes around the value
+
option example v_a l u-e
+
# unbalanced quotes
+
option 'example" "value'
+
</code>
-
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. 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 contain only 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).
===== Editor plugins =====
===== Editor plugins =====
-
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.
+
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.
-
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.
-
Below is the usage, as well as some useful examples of how to use this powerful utility.
+
<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>
-
|{{: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.|
+
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.
-
+
You can also use negative indexes, such as ''system.@timeserver[-1]''.
-
When there are multiple rules next to each other, 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. You can also use negative indexes, such as ''system.@timeserver[-1]''. "-1" means the last one, "-2" means the second-to-last one, and so on. This comes in very handy when appending new rules to the end of a list. See the examples below.
+
"-1" means the last one, "-2" means the second-to-last one, and so on.
+
This comes in very handy when appending new rules to the end of a list.
+
See the examples below.
==== Usage ====
==== Usage ====
-
''root@OpenWrt:/lib/config# **uci**''
-
<code>
<code>
+
# uci
Usage: uci [<options>] <command> [<arguments>]
Usage: uci [<options>] <command> [<arguments>]
Line 171:
Line 210:
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>]]
Line 191:
Line 230:
</code>
</code>
-
^ ''Command'' ^ Target ^ Description ^
+
<sortable>
-
| ''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. |
+
^ ''Command'' ^ Target ^ Description ^
-
| ''batch'' | - | Executes a multi-line UCI script which is typically wrapped into a //here// document syntax. |
+
| ''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. |
-
| ''export'' | ''[<config>]'' | Exports the configuration in a machine readable format. It is used internally to evaluate configuration files as shell scripts. |
+
| ''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. |
-
| ''changes'' | ''[<config>]'' | List staged changes to the given configuration file or if none given, all configuration files. |
| ''add'' | ''<config> <section-type>'' | Add an anonymous section of type ''section-type'' to the given configuration. |
+
| ''changes'' | ''[<config>]'' | List staged changes to the given configuration file or if none given, all configuration files. |
+
| ''add'' | ''<config> <section-type>'' | Add an anonymous section of type ''section-type'' to the given configuration. |
| ''add_list'' | ''<config>.<section>.<option>=<string>'' | Add the given string to an existing list option. |
| ''add_list'' | ''<config>.<section>.<option>=<string>'' | Add the given string to an existing list option. |
| ''del_list'' | ''<config>.<section>.<option>=<string>'' | Remove the given string from an existing list option. |
| ''del_list'' | ''<config>.<section>.<option>=<string>'' | Remove the given string from an existing list option. |
-
| ''show'' | ''[<config>[.<section>[.<option>]]]'' | Show the given option, section or configuration in compressed notation. |
+
| ''show'' | ''[<config>[.<section>[.<option>]]]'' | Show the given option, section or configuration in compressed notation. |
-
| ''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>
-
===== UCI data/object model =====
+
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 =====
==== Elements ====
==== Elements ====
The elements in UCI model are:
The elements in UCI model are:
Line 222:
Line 269:
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]")
-
Example of **anonymous-name** (cmd: uci show network):
+
Section names may only contain alphanum and "_" (for shell compatibility). Hyphen '-' is not allowed.
-
<code>
+
+
Example of **anonymous-name**:
+
+
<code bash>
+
# uci show network
...
...
network.@switch[0]=switch
network.@switch[0]=switch
Line 232:
Line 283:
</code>
</code>
-
Example of **autogenerated ID/CFGID** (cmd: "uci show network.@switch[0]):
+
Example of **autogenerated ID/CFGID**:
-
<code>
+
+
<code bash>
+
# uci show network.@switch[0]
network.cfg073777=switch
network.cfg073777=switch
network.cfg073777.name='switch0'
network.cfg073777.name='switch0'
Line 242:
Line 295:
=== Different presentation ===
=== Different presentation ===
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>"
| **Programmable**, named section ("uci show network.wan") | **Programmable**, unnamed section, anonymous name ("uci show network") | **Programmable**, unnamed section, CFGID ("uci show network.@switch[0]") |
| **Programmable**, named section ("uci show network.wan") | **Programmable**, unnamed section, anonymous name ("uci show network") | **Programmable**, unnamed section, CFGID ("uci show network.@switch[0]") |
If we want to change the listening port of the [[docs:guide-user:services:webserver:http.uhttpd|uHTTPd Web Server]] from 80 to 8080 we change the configuration in ''/etc/config/uhttpd'' :
If we want to change the listening port of the [[docs:guide-user:services:webserver:http.uhttpd|uHTTPd Web Server]] from 80 to 8080 we change the configuration in ''/etc/config/uhttpd'' :
-
| ''root@OpenWrt:~# **uci set uhttpd.main.listen_http=8080**
+
<code bash>
-
root@OpenWrt:~# **uci commit uhttpd**
+
uci set uhttpd.main.listen_http='8080'
-
root@OpenWrt:~# **/etc/init.d/uhttpd restart**
+
uci commit uhttpd
-
root@OpenWrt:~#'' |
+
/etc/init.d/uhttpd restart
+
</code>
Done, now the configuration file is updated and uHTTPd listens on port 8080.
Done, now the configuration file is updated and uHTTPd listens on port 8080.
will generate a new section called SECTION_NAME inside the subsystem called SUBSYSTEM_NAME
+
uci add configuration_name section_type
-
afterwards you can add keys to this section as normal.\\
+
</code>
-
It will print an alphanumeric code that you can use as "section" for further adding keys to it.\\
+
-
See this example:\\
+
-
<code>root@LEDE:~# uci add firewall rule
+
-
cfg2092bd
+
-
root@LEDE:~# uci set firewall.cfg2092bd.src='wan'</code>
+
-
=== Showing the not-yet-saved modified values ===
+
It will generate a new unnamed section of type ''section_type'' inside the configuration called ''configuration_name''.
-
<code>root@lede:/# uci changes</code>\\
+
Afterwards you can add keys to this section as normal.
+
The add command will print an auto generated alphanumeric section name that you can use for further adding keys to the newly added section.
-
=== Saving modified values of a single subsystem ===
+
Add a new firewall config section of type ''rule'' and refer to it by index:
-
<code>root@lede:/# uci commit SUBSYSTEM_NAME
+
-
root@lede:/# reload_config </code>\\
+
-
=== Saving all modified values ===
+
<code bash>
-
<code>root@lede:/# uci commit
+
uci add firewall rule
-
root@lede:/# reload_config </code>\\
+
uci set firewall.@rule[-1].src='wan'
+
</code>
+
Add a new firewall config section of type ''rule'' and refer to it by its auto generated name:
-
=== Generating a full uci section with a simple copy-paste ===
+
<code bash>
+
sid=$(uci add firewall rule)
+
uci set firewall.$sid.src='wan'
+
</code>
-
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.
+
=== Adding a named section to configuration ===
-
Generic version:
+
In order to add a named section of a given type, the option-less form of the ''uci set'' command must be used.
uci batch <<EOF set <config>.$rule_name.<option1>='value'
+
-
set <config>.$rule_name.<option2>='value'
+
-
set <config>.$rule_name..<option3>='value'
+
-
#... any number of them
+
-
EOF
+
-
uci commit</code>
+
-
A working example:
+
<code bash>
-
<code>rule_name=$(uci add firewall rule)
+
touch /etc/config/example
-
uci batch <<EOF firewall.$rule_name.enabled='1'
+
uci set example.this_name=blah
-
set firewall.$rule_name.target='ACCEPT'
+
uci set example.this_name.xxx=yyy
-
set firewall.$rule_name.src='wan'
+
uci set example.other_name=blah
-
set firewall.$rule_name.proto='tcp udp'
+
uci set example.other_name.yyy=zzz
-
set firewall.$rule_name.dest_port='111'
+
uci commit example
-
set firewall.$rule_name.name='NFS_share'
+
</code>
-
EOF
+
-
uci commit</code>
+
+
<code bash>
+
uci show example
+
</code>
+
<code>
+
example.this_name=blah
+
example.this_name.xxx=yyy
+
example.other_name=blah
+
example.other_name.yyy=zzz
+
</code>
-
=== Create a new named section of a given type ===
+
<code bash>
+
cat /etc/config/example
+
</code>
+
<code>
+
config blah 'this_name'
+
option xxx 'yyy'
+
+
config blah 'other_name'
+
option xxx 'zzz'
+
</code>
-
"uci add blah" will create a new _anonymous_ section of type blah. ie,
+
=== Showing the not-yet-saved modified values ===
+
<code bash>
+
uci changes
+
</code>
-
| ''#touch /etc/config/playapp
+
=== Saving modified values of a single configuration ===
-
#uci show playapp
+
<code bash>
-
#uci add playapp blah
+
uci commit configuration_name
-
cfg02a4fc
+
reload_config
-
#uci show playapp
+
</code>
-
playapp.@blah[0]=blah
+
-
# uci commit && cat /etc/config/playapp
+
-
config blah
+
=== Saving all modified values ===
+
<code bash>
+
uci commit
+
reload_config
+
</code>
-
#
+
=== 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.
-
If you actually want a named section of that type, for instance,
+
Generic version:
-
|''config blah this_name
+
<code bash>
-
option xxx yyy
+
rule_name=$(uci add <config> <section-type>)
-
config blah other_name
+
uci batch << EOI
-
option xxx zzz
+
set <config>.$rule_name.<option1>='value'
-
''|
+
set <config>.$rule_name.<option2>='value'
+
set <config>.$rule_name.<option3>='value'
+
...
+
EOI
+
uci commit
+
</code>
-
Then "uci add" cannot be used, instead, use this syntax
# uci get foo.second.name won't work; label 'second' undefined.
+
# uci get foo.second.name won't work; label 'second' undefined
# Mr. Third
# Mr. Third
Line 429:
Line 494:
uci get foo.@bar[-1].name
uci get foo.@bar[-1].name
uci get foo.third.name
uci get foo.third.name
-
''|
+
</code>
If you show it, you get :
If you show it, you get :
-
|''# **uci show foo**
+
<code bash>
+
# uci show foo
foo.first=bar
foo.first=bar
-
foo.first.name=Mr. First
+
foo.first.name='Mr. First'
-
//foo.@bar[0]=bar//
+
foo.@bar[0]=bar
-
//foo.@bar[0].name=Mr. Second//
+
foo.@bar[0].name='Mr. Second'
foo.third=bar
foo.third=bar
-
foo.third.name=Mr. Third
+
foo.third.name='Mr. Third'
-
''|
+
</code>
-
But if you used "uci show foo.@bar[0]", you will see:
+
But if you used ''uci show foo.@bar[0]'', you will see:
-
+
-
|''# **uci show foo.@bar[0]**
+
-
//foo.first=bar//
+
-
//foo.first.name=Mr. First// :-(
+
-
''|
+
-
+
-
+
-
=== Query interface state ===
+
-
+
-
| ''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:~#'' |
+
+
<code bash>
+
# uci show foo.@bar[0]
+
foo.first=bar
+
foo.first.name='Mr. First'
+
</code>
=== Add a firewall rule ===
=== 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.
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
+
<code bash>
-
root@OpenWrt:~# uci set firewall.@rule[-1].src=wan
+
uci add firewall rule
-
root@OpenWrt:~# uci set firewall.@rule[-1].target=ACCEPT
+
uci set firewall.@rule[-1].src='wan'
-
root@OpenWrt:~# uci set firewall.@rule[-1].proto=tcp
+
uci set firewall.@rule[-1].target='ACCEPT'
-
root@OpenWrt:~# uci set firewall.@rule[-1].dest_port=22
+
uci set firewall.@rule[-1].proto='tcp'
-
root@OpenWrt:~# uci commit firewall
+
uci set firewall.@rule[-1].dest_port='22'
-
root@OpenWrt:~# /etc/init.d/firewall restart'' |
+
uci commit firewall
-
+
/etc/init.d/firewall restart
-
=== Get WAN IP address ===
+
</code>
-
* Backfire <code bash>uci -P/var/state get network.wan.ipaddr</code>
+
-
* The uci state vars are deprecated and not used anymore for network related information. In Trunk (not really uci) do <code bash>. /lib/functions/network.sh; network_get_ipaddr ip wan; echo $ip</code>
+
-
+
-
=== Get WAN interface ===
+
-
* Backfire <code bash>uci -P/var/state get network.wan.ifname</code>
+
-
* The uci state vars are deprecated and not used anymore for network related information. In Trunk (not really uci) do <code bash>. /lib/functions/network.sh; network_get_device if_wan wan; echo $if_wan</code>
+
-
* Or <code bash>. /lib/functions/network.sh; network_get_physdev if_wan wan; echo $if_wan</code>
+
=== Get SSID ===
=== Get SSID ===
-
<code> uci get wireless.@wifi-iface[-1].ssid</code>
+
<code bash>
+
uci get wireless.@wifi-iface[0].ssid
+
</code>
-
==== uci-defaults ====
+
===== Porting UCI to a different Linux distribution =====
+
See [[docs:techref:uci#usage_outside_of_openwrt|UCI (Unified Configuration Interface) – Technical Reference]]
-
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).
+
If you manually edited the configs in ''/etc/config'', it is possible that some of them are corrupted due to typos.
-
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>#!/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>#!/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 =====
-
See [[docs:techref:uci#usage_outside_of_openwrt|UCI (Unified Configuration Interface) – Technical Reference]]
-
-
===== Finding faulty 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:
<code bash>
<code bash>
-
for i in /etc/config/*; do
+
# uci show fstab
-
if ! uci show ${i##*/} > /dev/null 2>&1; then
+
uci: Parse error (invalid command) at line 20, byte 0