Nexapp - UCI (Unified Configuration Interface)

UCI (Unified Configuration Interface)

UCI (Unified Configuration Interface) is the centralized configuration system used in NexappOS. It stores system settings in structured files and provides a consistent command-line method to read and change them.

UCI is powerful and flexible, but it does not validate what you write. That means it’s fast for advanced admins, but mistakes can break services or connectivity.

---

Key characteristics

• Centralized configuration All system configuration files are stored in: /etc/config/

• Database-driven format Each file is a structured configuration database for one service.

• No built-in validation UCI accepts commands as written. Incorrect values can make the system unstable or unreachable.

• Three-phase workflow UCI changes follow a standard flow: Modify → Commit → Restart/Reload

• Multi-event capable The NexappOS UI can trigger multiple UCI changes and service reloads at once.

---

Where configuration lives

Each service has its own file under /etc/config/. Example directory (non-exhaustive):

/etc/config/
├── acme          # SSL certificate management
├── adblock       # DNS/domain blocking
├── banip         # IP blocking service
├── chilli        # Captive portal
├── dedalo        # Hotspot access control
├── dhcp          # DHCP server
├── dpi           # Deep Packet Inspection
├── dropbear      # SSH server
├── firewall      # Firewall rules and zones
├── fstab         # Filesystem mounts
├── ipsec         # IPsec VPN
├── mwan3         # MultiWAN configuration
├── network       # Interfaces and routing
├── nginx         # Reverse proxy / web server
├── openvpn       # OpenVPN configuration
├── qosify        # QoS
├── rpcd          # RPC daemon
├── rsyslog       # System logging
├── system        # Global system settings
└── users         # Users and objects

---

Viewing configuration

Show all configuration for a service

uci show <service>

Example:

uci show network

Example output:

network.loopback=interface
network.loopback.device='lo'
network.loopback.proto='static'
network.loopback.ipaddr='127.0.0.1'
network.loopback.netmask='255.0.0.0'

network.@device[0]=device
network.@device[0].name='br-lan'
network.@device[0].type='bridge'
network.@device[0].ports='eth0'

network.lan=interface
network.lan.device='br-lan'
network.lan.proto='static'
network.lan.ipaddr='192.168.100.101'
network.lan.netmask='255.255.255.0'

network.wan=interface
network.wan.device='eth1'
network.wan.proto='dhcp'

Show a specific option

uci show <service>.<section>.<option>

Example:

uci show network.lan.ipaddr

---

Standard UCI workflow

UCI always follows three steps:

1. MODIFY Change values in memory.

2. COMMIT Save them permanently into /etc/config/<service>.

3. RELOAD / RESTART Apply changes to running services.

---

Practical example: change LAN IP

# 1. Modify
uci set network.lan.ipaddr='192.168.100.151'

# 2. Commit
uci commit network

# 3. Apply
/etc/init.d/network restart

---

MODIFY: editing configuration

Set a value

uci set <service>.<section>.<option>='<value>'

Examples:

uci set network.lan.ipaddr='192.168.100.151'
uci set network.lan.netmask='255.255.255.0'
uci set network.wan.proto='static'

Add a new section

uci add <service> <section_type>

Delete items

# Delete a single option
uci delete <service>.<section>.<option>

# Delete an entire section
uci delete <service>.<section>

---

COMMIT: saving changes

Changes only become persistent after commit.

Commit one service

uci commit <service>

Example:

uci commit network

Commit everything pending

uci commit

Review pending changes

uci changes

Revert uncommitted changes

uci revert <service>

---

RELOAD: applying changes

After commit, apply settings to the running system:

reload_config

Sometimes a specific service restart is required instead (example: network, firewall, openvpn).

---

UCI file format

UCI files are structured into sections with options and optional lists:

config <section_type> '<section_name>'
    option <option_name> '<value>'
    list <list_name> '<value1>'
    list <list_name> '<value2>'

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 device
    option name 'br-lan'
    option type 'bridge'
    list ports 'eth0'

config interface 'lan'
    option device 'br-lan'
    option proto 'static'
    option ipaddr '192.168.100.101'
    option netmask '255.255.255.0'

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

---

Best practices

• Backup before editing critical services, especially networking.
• Change one thing at a time, test, then proceed.
• Use uci changes before committing to confirm what will be applied.
• For network edits, keep console/physical access available in case you lock yourself out.

---

Common pitfalls

• Forgetting commit → changes vanish after reboot.
• Forgetting to restart/reload services → changes don’t take effect.
• Making multiple risky edits at once → hard to recover.
• Typos or invalid values → UCI won’t stop you.

---

Troubleshooting quick commands

# Show pending edits
uci changes

# Discard pending edits
uci revert <service>

# Quick sanity check
uci show | head -1

Warning: UCI doesn’t validate input. Incorrect commands can break services or make the firewall unreachable. Always ensure you have a recovery path before changing network settings.