Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
| docs:guide-developer:uci-defaults [2019/09/30 09:53] – changed LEDE to OpenWrt bobafetthotmail | docs:guide-developer:uci-defaults [2023/10/14 09:08] (current) – [UCI defaults] vgaetera | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== UCI defaults ====== | ====== UCI defaults ====== | ||
| + | See also: [[docs: | ||
| - | ===== UCI Defaults ===== | + | //OpenWrt// relies on UCI, the //Unified Configuration Interface//, |
| + | UCI defaults provides a way to preconfigure your images, using UCI. | ||
| - | //OpenWrt// relies on UCI, the //Unified Configuration Interface//, | + | To set some system defaults the first time the device boots, create a script in the directory '' |
| - | To set some system defaults the first time the device boots, create a script in the folder / | + | All scripts in that directory |
| - | + | * If they exit with code 0 they are deleted afterwards. | |
| - | All scripts in that folder | + | |
| - | * 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. | * 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. | ||
| - | In a live router you can see the existing | + | In a live router you can see the existing |
| - | uci-defaults scripts can be created by packages or they can be inserted into the build manually as custom files. | + | UCI defaults scripts can be created by packages or they can be inserted into the build manually as custom files. |
| - | ==== Integrating custom settings ==== | + | ===== Integrating custom settings ===== |
| + | See also: | ||
| + | [[docs: | ||
| + | [[docs: | ||
| - | You can preload custom settings by adding batch scripts containing UCI commands into the ''/ | + | 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 ''/ | ||
| + | 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 ''/ | ||
| + | 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: | ||
| - | < | + | < |
| - | $ cat zzzz_customisations | + | cat << " |
| - | #!/bin/sh | + | uci -q batch << |
| - | + | set network.lan.ipaddr=' | |
| - | uci -q batch <<-EOT | + | set wireless.@wifi-device[0].disabled=' |
| - | add dhcp host | + | set wireless.@wifi-iface[0].ssid=' |
| - | set dhcp.@host[0].name=' | + | add dhcp host |
| - | set network.@host[0].ip=' | + | set dhcp.@host[-1].name=' |
| - | set network.@host[0].mac=' | + | set dhcp.@host[-1].ip=' |
| - | EOT | + | set dhcp.@host[-1].mac=' |
| + | rename firewall.@zone[0]=' | ||
| + | rename firewall.@zone[1]=' | ||
| + | rename firewall.@forwarding[0]=' | ||
| + | EOI | ||
| + | EOF | ||
| </ | </ | ||
| - | Once the script has run successfully and exited cleanly (exit status 0), it will be removed from '' | + | 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 '' | ||
| + | You can still consult the original in ''/ | ||
| - | ==== Ensuring scripts don’t overwrite custom settings: implementing checks ==== | + | ===== Ensuring scripts don’t overwrite custom settings: implementing checks ===== |
| + | Scripts in ''/ | ||
| + | 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: | ||
| - | Scripts in ''/ | + | < |
| - | + | ||
| - | < | + | |
| [ "$(uci -q get system.@system[0].zonename)" | [ "$(uci -q get system.@system[0].zonename)" | ||
| </ | </ | ||
| This will make sure, when the key has the correct value set, that the script exits cleanly and gets removed from ''/ | This will make sure, when the key has the correct value set, that the script exits cleanly and gets removed from ''/ | ||
| + | |||
| + | ===== Examples ===== | ||
| + | * [[docs: | ||
| + | * [[https:// | ||
| + | * [[https:// | ||
| + | * [[https:// | ||
| + | * [[https:// | ||