Differences

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

--- docs:guide-developer:uci-defaults [2016/11/13 17:59] – [UCI Defaults] bobafetthotmail
+++ docs:guide-developer:uci-defaults [2023/10/14 09:08] (current) – [UCI defaults] vgaetera
@@ Line 1: / Line 1: @@
 ====== UCI defaults ======
+See also: [[docs:guide-user:base-system:uci|The UCI system]]
-===== UCI Defaults =====
+//OpenWrt// relies on UCI, the //Unified Configuration Interface//, to configure its core services.
+UCI defaults provides a way to preconfigure your images, using UCI.
-//LEDE// relies on UCI, the //Unified Configuration Interface//, to configure its core services. UCI Defaults provides a way to preconfigure your images, using UCI.
+To set some system defaults the first time the device boots, create a script in the directory ''/etc/uci-defaults''.
-==== Integrating custom settings ====
+All scripts in that directory are automatically executed by the ''boot'' service:
+  * If they exit with code 0 they are deleted afterwards.
+  * Scripts that exit with non-zero exit code are not deleted and will be re-executed at the next boot until they also successfully exit.
-You can preload custom settings by adding batch scripts containing UCI commands into the ''/files/etc/uci-defaults'' directory. The path is identical for the buildroot and the image generator. The scripts will be run **after** the flashing process - in case of upgrading, that also includes appending the existing configuration to the JFFS2 partition (mounted as ''/overlay'').Scripts should not be executable. To ensure your scripts are not interfering with any other scripts, make sure they get executed last by giving them a high prefix (e.g. //zzzz_customisations//). A basic script could look like this:
+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 successfully and have been deleted).
-<code>
+UCI defaults scripts can be created by packages or they can be inserted into the build manually as custom files.
-$ cat zzzz_customisations
-#!/bin/sh
-uci -q batch <<-EOT
+===== Integrating custom settings =====
-  add dhcp host
+See also:
-  set dhcp.@host[0].name='bellerophon'
+[[docs:guide-developer:toolchain:use-buildsystem#custom_files|Build system - Custom files]],
-  set network.@host[0].ip='192.168.2.100'
+[[docs:guide-user:additional-software:imagebuilder#custom_files|Image builder - Custom files]]
-  set network.@host[0].mac='a1:b2:c3:d4:e5:f6'
-    EOT
-</code>
-Once the script has run successfully and exited cleanly (exit status 0), it will be removed from ''etc/uci-defaults''. You can still consult the original in ''/rom/etc/uci-defaults'' if needed.
+Easiest way to include uci-defaults scripts in your firmware may be as custom files.
+You can preload custom settings by adding batch scripts containing UCI commands into the ''/files/etc/uci-defaults'' directory.
+The path is identical for the buildroot and the image generator.
+The scripts will be run **after** the flashing process - in case of upgrading, that also includes appending the existing configuration to the JFFS2 partition (mounted as ''/overlay'').
+Scripts should not be executable.
+To ensure your scripts are not interfering with any other scripts, make sure they get executed last by giving them a high prefix (e.g. //xx_custom//).
+A basic script could look like this:
-==== Ensuring scripts don’t overwrite custom settings: implementing checks ====
+<code bash>
+cat << "EOF" > /etc/uci-defaults/99-custom
+uci -q batch << EOI
+set network.lan.ipaddr='192.168.178.1'
+set wireless.@wifi-device[0].disabled='0'
+set wireless.@wifi-iface[0].ssid='OpenWrt0815'
+add dhcp host
+set dhcp.@host[-1].name='bellerophon'
+set dhcp.@host[-1].ip='192.168.2.100'
+set dhcp.@host[-1].mac='a1:b2:c3:d4:e5:f6'
+rename firewall.@zone[0]='lan'
+rename firewall.@zone[1]='wan'
+rename firewall.@forwarding[0]='lan_wan'
+EOI
+EOF
+</code>
-Scripts in ''/etc/uci-defaults'' will get executed at every first boot (i.e. after a clean install or an upgrade), possibly overwriting already existing values. If this behaviour is undesired, we recommend you implement a test at the top of your script - e.g. probe for a custom setting your script would normally configure:
+This is a simple example to set up the LAN IP address, SSID, enable Wi-Fi, configure a static DHCP lease, rename firewall zone and forwarding sections.
+Once the script has run successfully and exited cleanly (exit status 0), it will be removed from ''/etc/uci-defaults''.
+You can still consult the original in ''/rom/etc/uci-defaults'' if needed.
-<code>
+===== Ensuring scripts don’t overwrite custom settings: implementing checks =====
+Scripts in ''/etc/uci-defaults'' will get executed at every first boot (i.e. after a clean install or an upgrade), possibly overwriting already existing values.
+If this behaviour is undesired, we recommend you implement a test at the top of your script - e.g. probe for a custom setting your script would normally configure:
+<code bash>
 [ "$(uci -q get system.@system[0].zonename)" = "America/New York" ] && exit 0
 </code>
 This will make sure, when the key has the correct value set, that the script exits cleanly and gets removed from ''/etc/uci-defaults'' as explained above.
+===== Examples =====
+  * [[docs:guide-user:additional-software:imagebuilder#restricting_root_access|Restricting root access]]
+  * [[https://github.com/openwrt/openwrt/tree/master/package/base-files/files/etc/uci-defaults|uci-defaults @ base-files]]
+  * [[https://github.com/freifunk-berlin/firmware-packages/tree/master/defaults|uci-defaults @ Freifunk Berlin]]
+  * [[https://github.com/ffulm/firmware/blob/master/files/etc/uci-defaults/50_freifunk-setup|uci-defaults @ Freifunk Ulm]]
+  * [[https://github.com/richb-hanover/OpenWrtScripts/blob/main/config-openwrt.sh|config-openwrt @ richb-hanover]]