Skip to content

uci.rst

Latest commit

 

History

History
325 lines (221 loc) · 8.42 KB

uci.rst

File metadata and controls

325 lines (221 loc) · 8.42 KB

UCI (Unified Configuration Interface)

UCI (Unified Configuration Interface) is a centralized configuration management system used in NethSecurity. It provides a unified approach to system configuration through a command-line interface and standardized configuration files.

Key Characteristics

  • Centralized Configuration: All system configurations are stored in a single location (/etc/config/)
  • Database-driven: Configurations are stored in structured database files
  • No Built-in Validation: UCI executes commands without safety checks - requires system knowledge
  • Three-phase Workflow: Modify → Commit → Restart/Reload
  • Multi-event Capable: User interfaces can trigger multiple configuration events simultaneously

Configuration Storage

All UCI configurations are stored as database files in /etc/config/. Each file represents a different system component or service, a non-exhaustive example list is provided below.

Configuration Files Structure

/etc/config/
├── acme          # SSL certificate management
├── adblock       # Advertisement blocking
├── banip         # IP banning service
├── chilli        # Captive portal
├── dedalo        # Network access control
├── dhcp          # DHCP server configuration
├── dpi           # Deep packet inspection
├── dropbear      # SSH server
├── firewall      # Firewall rules and zones
├── flashstart    # Web filtering
├── fstab         # Filesystem table
├── ipsec         # IPsec VPN
├── luci          # luci Web interface
├── mwan3         # Multi-WAN configuration
├── network       # Network interfaces and routing
├── nginx         # Web server
├── ns-ui         # NethSecurity user interface
├── objects       # Object definitions
├── openssl       # SSL/TLS configuration
├── openvpn       # OpenVPN configuration
├── qosify        # Quality of Service
├── rpcd          # RPC daemon
├── rsyslog       # System logging
├── socat         # Socket utilities
├── system        # System-wide settings
├── templates     # Configuration templates
├── ucitrack      # UCI change tracking
├── uhttpd        # HTTP server
└── users         # User management

Viewing Configuration

Show all configuration for a specific service

uci show <service>

Example:

uci show network

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 specific configuration option

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

Example:

uci show network.lan.ipaddr

Complete Configuration Workflow

Standard Three-Phase Process

  1. MODIFY - Make configuration changes
  2. COMMIT - Save changes to the configuration database
  3. RELOAD - Apply changes to the running system

Practical Example: Changing LAN IP Address

# Step 1: Modify the configuration
uci set network.lan.ipaddr='192.168.100.151'

# Step 2: Commit the changes
uci commit network

# Step 3: Restart the network service
/etc/init.d/network restart

SET - Modifying Configuration

The uci set command is used to modify configuration values. Changes are stored temporarily and must be committed to become persistent.

Set a configuration value

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

Examples:

# Change IP address
uci set network.lan.ipaddr='192.168.100.151'

# Change netmask
uci set network.lan.netmask='255.255.255.0'

# Change DHCP protocol to static
uci set network.wan.proto='static'

Add a new section

uci add <service> <section_type>

Delete operations

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

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

COMMIT - Saving Changes

Changes made with uci set are not immediately applied to the system. They must be committed first to make them persistent.

Commit specific service

uci commit <service>

Example:

uci commit network

Commit all pending changes

uci commit

Check pending changes

Before committing, you can review what changes will be applied:

uci changes

Revert uncommitted changes

If you want to discard uncommitted changes:

uci revert <service>

RELOAD - Applying Changes

After committing, you can apply the new configuration to the running system with a single command. This will automatically reload the affected services without the need to restart each one manually.

Reload configuration

reload_config

Configuration File Format

UCI configuration files use a structured format with sections and options:

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

Example: Network Configuration File

Network Configuration File (/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

Safety Considerations

  1. Always backup configurations before making changes
  2. Test changes incrementally rather than making multiple changes at once
  3. Understand service dependencies before restarting services
  4. Use uci changes to review pending modifications
  5. Have console access available when making network changes

Common Pitfalls

  • Forgetting to commit: Changes are not persistent until committed
  • Not restarting services: Committed changes may not be active until service restart
  • Breaking network connectivity: Always ensure alternative access methods
  • Syntax errors: Invalid UCI syntax can cause configuration corruption

Troubleshooting

Common Commands for Debugging

View pending changes

uci changes

Revert to last committed state

uci revert <service>

Check UCI syntax

uci show | head -1

Note

Always ensure you have alternative access to the system when making critical configuration changes, especially network-related modifications.

Warning

UCI commands execute without validation. Incorrect configurations can render the system inaccessible.