uci — Unified Configuration Interface

UCI architecture, file format, full CLI reference, and practical configuration examples.

UCI (Unified Configuration Interface) is OpenWrt’s centralized configuration system. All system configuration is stored in plain-text files under /etc/config/, and the uci command-line tool and libuci library provide a consistent API for reading and modifying these files.

Architecture

Component	Package	Description
libuci	libuci	C library for reading/writing UCI config files
uci	uci	Command-line utility
libuci-lua	libuci-lua	Lua bindings for libuci

Configuration files live in /etc/config/. Each file represents a configuration domain (e.g., network, system, firewall, wireless).

UCI File Format

# /etc/config/system

config system
    option hostname 'OpenWrt'
    option timezone 'UTC'
    option log_size '64'

config timeserver 'ntp'
    option enabled '1'
    list server '0.openwrt.pool.ntp.org'
    list server '1.openwrt.pool.ntp.org'

Key syntax elements:

Keyword	Syntax	Description
config	config <type> [<name>]	Start a new section. <name> is optional (anonymous sections get auto-names like cfg123456).
option	option <name> '<value>'	Set a single string value.
list	list <name> '<value>'	Append a value to a list option. Multiple list lines with the same name create a list.

Full CLI Reference

Reading Configuration

# Show all options in a config file (UCI path format)
uci show system

# Show a specific section
uci show system.ntp

# Get a single option value
uci get system.@system[0].hostname
uci get system.ntp.enabled

# Export config in UCI syntax (machine-readable)
uci export network

# Export all config files
uci export

Writing Configuration

# Set an option (staged, not yet written to disk)
uci set system.@system[0].hostname='MyRouter'

# Add a new unnamed section
uci add firewall rule

# Set an option in a named section
uci set network.loopback.ipaddr='127.0.0.1'

# Append to a list
uci add_list system.ntp.server='2.openwrt.pool.ntp.org'

# Delete an option
uci delete system.@system[0].log_size

# Delete an entire section
uci delete network.wan6

# Rename a section
uci rename firewall.@rule[0]=my_ssh_rule

# Commit staged changes to disk
uci commit

# Commit only one config file
uci commit system

# Discard staged changes
uci revert system

Batch Mode

# Read UCI commands from stdin
uci batch <<EOF
set system.@system[0].hostname='NewHostname'
set system.@system[0].timezone='CET-1CEST,M3.5.0,M10.5.0/3'
commit system
EOF

Import

# Import a UCI-format config file
uci import network < my-network-config.uci

Transaction Model

UCI uses a staged commit model:

1. uci set / uci add / uci delete write changes to a temporary overlay in /tmp/.uci/
2. uci commit atomically writes the changes to /etc/config/
3. uci revert discards the staged changes

This means that changes are not visible to running daemons until after commit and the relevant daemon is reloaded.

Practical Examples

Set the Hostname

uci set system.@system[0].hostname='my-router'
uci commit system
/etc/init.d/system reload

Configure a Static LAN IP

uci set network.lan.ipaddr='10.0.0.1'
uci set network.lan.netmask='255.255.255.0'
uci commit network
/etc/init.d/network restart

Add a Firewall Rule

RULE=$(uci add firewall rule)
uci set firewall.${RULE}.name='Allow-SSH'
uci set firewall.${RULE}.src='wan'
uci set firewall.${RULE}.dest_port='22'
uci set firewall.${RULE}.proto='tcp'
uci set firewall.${RULE}.target='ACCEPT'
uci commit firewall
/etc/init.d/firewall restart

Read Config in a Shell Script

#!/bin/sh
HOSTNAME=$(uci get system.@system[0].hostname 2>/dev/null)
echo "Hostname: ${HOSTNAME:-unknown}"

UCI Path Syntax

UCI addresses follow the format:

<config>.<section>.<option>

Path	Refers to
network	Entire network config file
network.lan	Section named lan in network
network.lan.ipaddr	Option ipaddr inside section lan
network.@interface[0]	First anonymous section of type interface
network.@interface[-1]	Last anonymous section of type interface