uci: Manage OpenWrt configuration files

What is UCI?

UCI (Unified Configuration Interface) is the OpenWrt tool for reading and modifying configuration files. It provides a consistent command-line API to manage settings across different services.

Quickstart: common operations

  • Fetch a value
uci get {{network.lan.ipaddr}}
  • Show all options in a config
uci show {{network}}
  • Set a value (staged for commit)
uci set {{config}}.{{section}}.{{option}}={{value}}
  • Add a new section
uci add {{config}} {{section}}
  • Delete a section or an option
uci delete {{config}}.{{section}}.{{option}}
  • Commit changes to disk
uci commit {{config}}
  • Discard uncommitted changes
uci revert {{config}}
  • Display help
uci

Tip: You can omit {{config}} for global operations, but many commands target a specific config like network or wireless.

Typical workflows

  1. View current LAN IP address and set a new one
uci get network.lan.ipaddr
uci set network.lan.ipaddr='192.168.2.1'
uci commit network
  1. Add a new bridge and a member interface (example)
uci add network
uci set network.@bridge[0].name='br0'
uci set network.lan='bridge'
uci commit network
  1. Remove an unused option
uci delete network.lan.macaddr
uci commit network

Common pitfalls

  • Forgetting to commit: changes stay in memory and appear missing to rebooted systems.
  • Editing the wrong config: network vs wireless is a common mix-up.
  • Missing root privileges: some systems require sudo or root to modify configs.
  • Quoting values: when setting strings with spaces, quote them properly as shown above.

Best practices

  • Always back up before large changes:
cp /etc/config/network /etc/config/network.bak
  • Use uci show to verify the exact path you’ll modify.
  • Prefer uci commit <config> over global commits to minimize risk.

Troubleshooting and help

  • If a change disappears after reboot, you likely didn’t commit the config or there’s another process rewriting it.
  • Use uci show to inspect the live configuration and confirm what will be applied.
  • For advanced help, read the official OpenWrt docs: https://openwrt.org/docs/techref/uci

Quick reference

  • Get a value: uci get {{path}}
  • Show: uci show {{config}}
  • Set: uci set {{config}}.{{section}}.{{option}}={{value}}
  • Add: uci add {{config}} {{section}}
  • Delete: uci delete {{config}}.{{section}}.{{option}}
  • Commit: uci commit {{config}}
  • Revert: uci revert {{config}}
  • Help: uci

See Also