OpenWRT LuCI Documentation¶

LuCI (Lua Configuration Interface) is the web-based administration interface for OpenWRT. It provides a comprehensive GUI for router configuration while maintaining the ability to drop down to UCI (Unified Configuration Interface) commands or raw configuration files when needed. This page documents LuCI's architecture, key modules, and advanced configuration workflows.

Overview¶

Architecture¶

LuCI uses a Model-View-Controller architecture built on Lua and the Nginx/uHTTPd web server:

flowchart TD
    B["Browser"] -->|"HTTP/HTTPS"| W["uHTTPd / Nginx"]
    W -->|"Lua dispatch"| D["LuCI Dispatcher"]
    D --> A["Authentication<br/>luci.sysauth"]
    D --> C["CSRF Protection"]
    D --> M["Menu Tree"]
    D --> CTL["Controller<br/>lua/luci/controller/"]
    CTL --> CBI["CBI Model<br/>lua/luci/model/cbi/"]
    CBI --> U["UCI Config<br/>/etc/config/"]
    CBI --> V["View<br/>lua/luci/view/"]
    V --> H["HTML Templates"]
    V --> J["JavaScript<br/>/luci-static/resources/"]
    V --> S["CSS<br/>/luci-static/bootstrap/"]

    style B fill:#333,color:#fff
    style U fill:#4a7c59,color:#fff
    style D fill:#5a3a2d,color:#fff

LuCI Modules¶

Status¶

System¶

Network¶

CBI (Configuration Binding Interface)¶

CBI is LuCI's framework for automatically generating configuration forms from UCI schemas:

-- Example CBI model for a simple configuration page
local m = Map("system", "System Configuration")
local s = m:section(TypedSection, "system", "General Settings")
s.anonymous = true

-- Hostname field
local hostname = s:option(Value, "hostname", "Hostname")
hostname.datatype = "hostname"
hostname.default = "OpenWrt"

-- Timezone field
local timezone = s:option(ListValue, "timezone", "Timezone")
timezone:value("UTC", "UTC")
timezone:value("EST5EDT", "Eastern Time")
timezone:value("CST6CDT", "Central Time")
timezone:value("MST7MDT", "Mountain Time")
timezone:value("PST8PDT", "Pacific Time")

-- Boolean field
local logging = s:option(Flag, "logging", "Enable Logging")
logging.default = logging.enabled

return m

CBI Field Types¶

Advanced Configuration Workflows¶

VLAN Configuration via LuCI¶

Network > Interfaces > Devices tab
  |
  +-- Add device configuration
  |     Type: 802.1q VLAN
  |     Base device: eth0
  |     VLAN ID: 10
  |
  +-- Add device configuration
  |     Type: Bridge device
  |     Bridge ports: eth0.10
  |
  +-- Add new interface
        Protocol: Static address
        Device: br-vlan10
        IP: 192.168.10.1/24

Wi-Fi Configuration via LuCI¶

Network > Wireless
  |
  +-- Edit radio0 (2.4 GHz)
  |     Channel: auto / specific
  |     Width: 20 MHz / 40 MHz
  |     Power: transmission power dBm
  |
  +-- Add new network
        ESSID: network-name
        Mode: Access Point
        Network: lan / guest / iot
        Encryption: WPA2-PSK / WPA3-SAE
        Key: passphrase

Firewall Configuration via LuCI¶

Network > Firewall
  |
  +-- General Settings
  |     Input: Accept / Reject / Drop
  |     Output: Accept / Reject / Drop
  |     Forward: Accept / Reject / Drop
  |
  +-- Zones
  |     lan -> wan: Allow
  |     guest -> wan: Allow
  |     iot -> wan: Allow
  |     iot -> lan: Reject
  |
  +-- Traffic Rules
  |     Name: Allow-SSH-WAN
  |     Source: wan
  |     Destination port: 22
  |     Action: Accept
  |
  +-- Port Forwards
        Name: HTTP-Server
        External port: 80
        Internal IP: 192.168.1.100
        Internal port: 80

Custom LuCI Pages¶

Creating a custom LuCI page involves three files:

1. Controller (/usr/lib/lua/luci/controller/myapp.lua)¶

module("luci.controller.myapp", package.seeall)

function index()
    entry({"admin", "services", "myapp"}, 
          cbi("myapp/config"), 
          "My Application", 
          60).dependent = false
end

2. Model (/usr/lib/lua/luci/model/cbi/myapp/config.lua)¶

local m = Map("myapp", "My Application Configuration")
local s = m:section(TypedSection, "settings", "Settings")
s.anonymous = true

local enabled = s:option(Flag, "enabled", "Enable")
local port = s:option(Value, "port", "Port")
port.datatype = "port"
port.default = "8080"

return m

3. UCI Configuration (/etc/config/myapp)¶

config settings 'main'
    option enabled '1'
    option port '8080'

LuCI Themes¶

# Install theme
opkg update
opkg install luci-theme-material

# Set theme
uci set luci.main.mediaurlbase='/luci-static/material'
uci commit luci

LuCI API (RPC)¶

LuCI provides a JSON-RPC API for programmatic access:

# Authenticate
curl -d '{"id":1,"method":"call","params":["","session","login",["root","password"]]}' \
     http://192.168.1.1/cgi-bin/luci/rpc/auth

# Response: {"id":1,"result":"auth_token","error":null}

# Call UCI methods
curl -d '{"id":1,"method":"call","params":["auth_token","uci","get",["network","lan","ipaddr"]]}' \
     http://192.168.1.1/cgi-bin/luci/rpc/uci

# Response: {"id":1,"result":"192.168.1.1","error":null}

RPC Modules¶

Related Deep Hole¶

• OpenWRT LuCI Documentation — Official LuCI guide
• LuCI API Documentation — Technical reference
• OpenWRT Forum — Community support
• OpenWrt Wiki: Writing LuCI Modules — Developer guide
• UCI Documentation — Configuration system