Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openwrt/openwrt/llms.txt

Use this file to discover all available pages before exploring further.

UCI (Unified Configuration Interface) is OpenWrt’s centralized configuration system. Every core OpenWrt package — networking, wireless, firewall, system settings, DHCP, and more — reads its configuration from UCI rather than maintaining its own ad-hoc config file format. This means you have a single, consistent interface for reading and writing configuration across the entire system, both from the command line and programmatically (via libuci in C, Lua, or shell).

​
Configuration Files

UCI configuration files live in /etc/config/. Each subsystem has its own file: 
/etc/config/
├── dhcp          # dnsmasq DHCP and DNS settings
├── dropbear      # SSH server
├── firewall      # nftables/firewall4 rules
├── network       # Network interfaces, routes
├── rpcd          # RPC access control
├── system        # Hostname, timezone, logging
└── wireless      # Wi-Fi radios and SSIDs
/etc/config/ is the canonical UCI configuration directory. Do not edit daemon-specific files like /etc/dnsmasq.conf directly — those are generated from UCI by the respective init scripts.

​
File Format

UCI files use a simple, human-readable format built around sections, options, and lists. 
config <type> ['<name>']
        option <key> '<value>'
        list   <key> '<value>'
  • config — begins a new section. The optional name makes it a named section (addressable as file.name); without a name it is an anonymous section (addressable by index, e.g. file.@type[0]).
  • option — a single key/value pair.
  • list — a multi-value option; multiple list lines with the same key form an array.

​
Example: /etc/config/network

config interface 'loopback'
        option device 'lo'
        option proto 'static'
        option ipaddr '127.0.0.1'
        option netmask '255.0.0.0'

config interface 'lan'
        option device 'br-lan'
        option proto 'static'
        option ipaddr '192.168.1.1'
        option netmask '255.255.255.0'
        option ip6assign '60'

config interface 'wan'
        option device 'eth1'
        option proto 'dhcp'

​
CLI Commands

The uci command-line tool provides full read/write access to all UCI configuration.

​
Read Values

# Get a single option
uci get network.lan.ipaddr

# Show all options in a section
uci show network.lan

# Export an entire config file in batch format
uci export network

​
Write Values

# Set an option
uci set network.lan.ipaddr='10.0.0.1'

# Add a new anonymous section
uci add firewall rule

# Delete an option or section
uci delete network.lan.dns

​
Commit Changes

# Write staged changes to /etc/config/
uci commit network

# Commit all pending changes across all config files
uci commit

​
Transactions: Stage then Commit

UCI uses a transactional model. Changes made with uci set, uci add, or uci delete are staged in /tmp/.uci/ and are not written to /etc/config/ until you run uci commit. This means:
  • You can make multiple related changes atomically
  • You can discard all pending changes by not committing
  • Services are not restarted until you explicitly trigger it (e.g., with reload_config or /etc/init.d/<service> restart)

​
Example: Changing the Hostname

# Stage the change
uci set system.@system[0].hostname='MyRouter'

# Write it to /etc/config/system
uci commit system

# Apply it without a full reboot
/etc/init.d/system restart
Verify the result: 
uci get system.@system[0].hostname
# MyRouter

​
UCI in Shell Scripts

The uci command is available in any shell script. The rc.common framework also provides helper functions via /lib/functions.sh: 
. /lib/functions.sh
config_load network
config_get ipaddr lan ipaddr
echo "LAN IP: $ipaddr"
Use uci show <file> to quickly inspect all values in a config file in dot-notation format — useful for scripting and debugging.