Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
docs:guide-developer:config-scripting [2018/03/03 20:23] – ↷ Links adapted because of a move operation docs:guide-developer:config-scripting [2024/06/01 08:50] (current) – code bash highlighting stokito
Line 1: Line 1:
 ====== Configuration in scripts ====== ====== Configuration in scripts ======
  
-OpenWrt offers a set of standard shell procedures to interface with UCI in order to efficiently read+{{section>meta:infobox:howto_links#config-network-device&noheader&nofooter&noeditbutton}} 
 + 
 +OpenWrt offers a set of standard shell procedures to interface with [[docs:guide-user:base-system:uci|UCI]] in order to efficiently read
 and process configuration files from within shell scripts.  This is most likely useful for writing startup scripts in ''/etc/init.d/''. and process configuration files from within shell scripts.  This is most likely useful for writing startup scripts in ''/etc/init.d/''.
  
Line 8: Line 10:
 To be able to load UCI configuration files, you need to include the common functions with: To be able to load UCI configuration files, you need to include the common functions with:
  
-| ''. /lib/functions.sh'' |+<code bash> 
 +. /lib/functions.sh 
 +</code> 
 + 
 +(If your startup script starts with: 
 + 
 +<code bash> 
 +#!/bin/sh /etc/rc.common 
 +</code> 
 + 
 +then you do not need to include ''/lib/functions.sh'' directly, because ''/etc/rc.common'' includes ''/lib/functions.sh'' by default.)
  
 Then you can use ''config_load //name//'' to load config files. Then you can use ''config_load //name//'' to load config files.
Line 31: Line 43:
   - Name, the section name, e.g. ''wan'' for ''config interface wan'' or an autogenerated ID like ''cfg13abef'' for anonymous sections like ''config route''   - Name, the section name, e.g. ''wan'' for ''config interface wan'' or an autogenerated ID like ''cfg13abef'' for anonymous sections like ''config route''
  
-| ''config_cb() {+<code bash> 
 +config_cb() {
     local type="$1"     local type="$1"
     local name="$2"     local name="$2"
     # commands to be run for every section     # commands to be run for every section
-}'' |+} 
 +</code>
  
 Also an extra call to ''config_cb'' (without a new section) is generated after config_load is done - Also an extra call to ''config_cb'' (without a new section) is generated after config_load is done -
Line 48: Line 62:
   - Value, the option value, e.g. ''eth0'' for ''option ifname eth0''   - Value, the option value, e.g. ''eth0'' for ''option ifname eth0''
  
-| ''option_cb() {+<code bash> 
 +option_cb() {
     local name="$1"     local name="$1"
     local value="$2"     local value="$2"
     # commands to be run for every option     # commands to be run for every option
-}'' |+} 
 +</code>
  
 Within the callback, the ID of the current section is accessible via the ''$CONFIG_SECTION'' variable. Within the callback, the ID of the current section is accessible via the ''$CONFIG_SECTION'' variable.
Line 67: Line 83:
   - Value, the list value, e.g. ''192.168.42.1'' for ''list server 192.168.42.1''   - Value, the list value, e.g. ''192.168.42.1'' for ''list server 192.168.42.1''
  
-| ''list_cb() {+<code bash> 
 +list_cb() {
     local name="$1"     local name="$1"
     local value="$2"     local value="$2"
     # commands to be run for every list item     # commands to be run for every list item
-}'' |+} 
 +</code>
  
 Each item of a given list generates a new call to ''list_cb''. Each item of a given list generates a new call to ''list_cb''.
Line 88: Line 106:
 in ''/etc/config/network''. The string ''test'' is passed as second argument on each invocation. in ''/etc/config/network''. The string ''test'' is passed as second argument on each invocation.
  
-| ''handle_interface() {+<code bash> 
 +handle_interface() {
     local config="$1"     local config="$1"
     local custom="$2"     local custom="$2"
Line 95: Line 114:
  
 config_load network config_load network
-config_foreach handle_interface interface test'' |+config_foreach handle_interface interface test 
 +</code>
  
-It is possible to abort the iteration from within the callback by returning a non-zero value (''return 1'').+Note that ''config_foreach'' will iterate through all sections without regard to the callback function's return value.
  
 Within the per-section callback, the ''config_get'' or ''config_set'' procedures may be used to read or set Within the per-section callback, the ''config_get'' or ''config_set'' procedures may be used to read or set
Line 110: Line 130:
   - Default (optional), value to return instead if option is unset   - Default (optional), value to return instead if option is unset
  
-| ''    ... +<code bash> 
-    # read the value of "option ifname" into the "iface" variable +#... 
-    # $config contains the ID of the current section +# read the value of "option ifname" into the "iface" variable 
-    local iface +# $config contains the ID of the current section 
-    config_get iface "$config" ifname +local iface 
-    echo "Interface name is $iface" +config_get iface "$config" ifname 
-    ...'' |+echo "Interface name is $iface" 
 +#... 
 +</code>
  
  
Line 126: Line 148:
   - Value to assign   - Value to assign
  
-| ''    ... +<code bash> 
-    # set the value of "option auto" to "0" +... 
-    # $config contains the ID of the current section +# set the value of "option auto" to "0" 
-    config_set "$config" auto 0 +# $config contains the ID of the current section 
-    ...'' | +config_set "$config" auto 0 
- +... 
-Note that values changed with ''config_set'' are only kept in memory. Subsequent calls to ''config_get'' will +</code>
-return the updated values but the underlying configuration files are //not// altered. If you want to alter values, use the uci_* functions from /lib/config/uci.sh which are automatically included by /etc/functions.sh.+
  
 +Note:
 +  * values changed with ''config_set'' are only kept in memory. Subsequent calls to ''config_get'' will return the updated values but the underlying configuration files are //not// altered. If you want to alter values, use the uci_* functions from /lib/config/uci.sh which are automatically included by /etc/functions.sh.
 +  * config_set is arcane and buggy (config_get is fine), use "uci set" instead.
  
 ===== Direct access ===== ===== Direct access =====
Line 143: Line 167:
 The example below reads "option proto" from the "config interface wan" section. The example below reads "option proto" from the "config interface wan" section.
  
-| ''...+<code bash> 
 +...
 local proto local proto
 config_get proto wan proto config_get proto wan proto
 echo "Current WAN protocol is $proto" echo "Current WAN protocol is $proto"
-...'' |+... 
 +</code>
  
  
Line 154: Line 180:
 Some UCI configurations may contain ''list'' options in the form: Some UCI configurations may contain ''list'' options in the form:
  
-| ''...+<code> 
 +...
 list network lan list network lan
 list network wifi list network wifi
-...'' |+... 
 +</code>
  
 Calling ''config_get'' on the ''network'' list will return the list values separated by space, ''lan wifi'' in this example. Calling ''config_get'' on the ''network'' list will return the list values separated by space, ''lan wifi'' in this example.
Line 163: Line 191:
 However, this behaviour might break values if the list items itself contain spaces like illustrated below: However, this behaviour might break values if the list items itself contain spaces like illustrated below:
  
-| ''...+<code> 
 +...
 list animal 'White Elephant' list animal 'White Elephant'
 list animal 'Mighty Unicorn' list animal 'Mighty Unicorn'
-...'' |+... 
 +</code>
  
 The ''config_get'' approach would return the values in the form ''White Elephant Mighty Unicorn'' and the original list items The ''config_get'' approach would return the values in the form ''White Elephant Mighty Unicorn'' and the original list items
Line 180: Line 210:
   - Additional arguments (optional), all following arguments are passed to the callback procedure as-is   - Additional arguments (optional), all following arguments are passed to the callback procedure as-is
  
-| ''# handle list items in a callback+<code bash> 
 +# handle list items in a callback
 # $config contains the ID of the section # $config contains the ID of the section
 handle_animal() { handle_animal() {
Line 187: Line 218:
 } }
  
-config_list_foreach "$config" animal handle_animal'' |+config_list_foreach "$config" animal handle_animal 
 +</code>
  
 Note: for editing value, use the [[docs:guide-user:base-system:uci|uci]] command line tool. Note: for editing value, use the [[docs:guide-user:base-system:uci|uci]] command line tool.
Line 215: Line 247:
 For instance, consider this script: For instance, consider this script:
  
-<code>+<code bash>
 config_cb() { config_cb() {
     local type="$1"     local type="$1"
Line 234: Line 266:
 This would parse a configuration like this one: This would parse a configuration like this one:
  
-| ''config mysection foo+<code> 
 +config mysection foo
     option link_quality auto     option link_quality auto
     option rxcost 256     option rxcost 256
-    option hello_inverval 4'' |+    option hello_inverval 4 
 +</code>
  
 And generate a file containing: And generate a file containing:
  
-| ''link-quality auto+<code> 
 +link-quality auto
 rxcost 256 rxcost 256
-hello-interval 4''|+hello-interval 4 
 +</code>
  
 ==== Use case and example for direct access ==== ==== Use case and example for direct access ====
Line 283: Line 319:
 That is, the type should come first, then selectors (with a special case for ''local'', which doesn't take an argument), and finally the action.  The basic parsing method is the following: That is, the type should come first, then selectors (with a special case for ''local'', which doesn't take an argument), and finally the action.  The basic parsing method is the following:
  
-<code>+<code bash>
 parse_filter() { parse_filter() {
     local section="$1"     local section="$1"
  • Last modified: 2018/03/03 20:23
  • by