DOCSEARCHbyAlgolia
Submit Docs

LuCI for OpenWrt

repository·master·Indexed 27 days ago

https://github.com/openwrt/luci

The web-based configuration interface for OpenWrt devices. This repository contains the LuCI feed and various applications, including luci-app-adblock-fast for DNS-based ad-blocking, luci-app-advanced-reboot for dual-partition firmware management, luci-app-attendedsysupgrade for automated firmware updates, luci-app-dockerman for Docker API management, luci-app-https-dns-proxy for DNS-over-HTTPS, and luci-app-pbr for policy-based routing.

Tokens
15.8K
Snippets
38
Records
83
Agent score
93%

What's inside LuCI

  1. Overview of luci-app-adblock-fast

    master

    luci-app-adblock-fast is a WebUI for the adblock-fast DNS-based ad-blocker on OpenWrt. It is designed to be lightweight by running once to process and install blocklists and then exiting, which minimizes runtime memory usage.

    It is compatible with the following DNS services:

    • dnsmasq
    • smartdns
    • unbound

    Key features include:

    • Parallel blocklist download and processing.
    • Persistent cache support.
    • Optional Web UI for managing custom block/allow lists.
    • Automatic reversion if DNS resolution fails after a restart.

  2. Overview of luci-app-advanced-reboot features

    master

    The luci-app-advanced-reboot LuCI application provides the following capabilities for dual-partition devices:

    • Partition Detection: Automatically detects supported dual-partition hardware.
    • Firmware Information: Displays details regarding both the current and alternative firmware partitions.
    • Partition Switching: Enables rebooting into the alternative partition directly from the web UI, removing the need for SSH.
    • Vendor Firmware Support: Supports switching between OpenWrt and vendor firmware if a vendor partition is present.

  3. Overview of luci-app-https-dns-proxy

    master

    luci-app-https-dns-proxy is a LuCI Web UI for a lightweight, RFC8484-compliant DNS-over-HTTPS (DoH) proxy service designed for OpenWrt. It provides a user-friendly interface to manage DoH settings and includes the following features:

    • Small footprint: Approximately 40KB installed.
    • dnsmasq integration: Seamless integration with dnsmasq and automatic fallback capabilities.
    • Built-in resolvers: Includes over 40 built-in DoH resolvers.
    • Canary domain support: Supports canary domain configurations for privacy.

    For detailed technical documentation, refer to the official https-dns-proxy documentation.

  4. Overview of LuCI App for pbr

    master

    The luci-app-pbr package provides a LuCI Web UI for managing the pbr (policy-based routing) package on OpenWrt. It allows users to visually define and manage traffic policies that route network traffic over specific WAN or VPN interfaces based on various criteria.

    Key capabilities include:

    • Managing routing rules via a policy table.
    • Creating rules based on IP addresses, ports, MAC addresses, or domains.
    • Monitoring interface-specific status and logs.
    • Toggling services and resolver settings via the UI.
    • Integration with OpenWrt's native service management.

  5. Understand Dockerman JS Architecture

    master

    Dockerman JS uses two primary backend mechanisms to interact with the Docker socket:

    1. rpcd/CGI: All API calls are sent via rpcd and appear as POST calls to the LuCI CGI (e.g., http://192.168.1.1/cgi-bin/luci). These are authenticated with your LuCI session login.
    2. ucode Controller: A ucode-based controller that forwards requests more directly to the Docker API socket to reduce RPC overhead and support streaming file uploads/downloads. The controller exposes a limited subset of the Docker API and is also authenticated via your session login.

  7. Understand the Dockerman JS socket connection architecture

    master

    Dockerman JS communicates with the Docker Daemon using a multi-layered connection flow:

    1. Web Server to Controller: The uhttpd web server communicates with the Controller Process via an AF_UNIX socket (named pipe).
    2. Controller to Docker Daemon: The Controller process connects to the Docker Daemon via the /var/run/docker.sock socket.
    3. Docker API Engine: Communication over the socket uses the HTTP protocol. The engine handles tasks such as creating export tar files and sending them as chunked streams.
    ┌──────────────────────────────────────┐
│     UHTTPd (Web Server)              │
│  [Controller Process]                │
└─────────────┬────────────────────────┘
              │
              │ AF_UNIX socket
              │ (named pipe)
              V
┌──────────────────────────────────────┐
│     Docker Daemon                    │
│  /var/run/docker.sock                │
└─────────────┬────────────────────────┘
              │
              │ HTTP Protocol
              │ (over socket)
              V
      Docker API Engine
      - Creates export tar
      - Sends as chunked stream

  8. Make a LuCI theme selectable in settings

    master

    To register your theme so it appears in the OpenWrt settings page, you must provide two files:

    1. UCI Default Configuration: Create root/etc/uci-defaults/luci-theme-mytheme. This script sets the theme path and the media URL base.
    2. Post-installation Script: Create ipkg/postinst. This ensures the UCI defaults are applied immediately upon installation.

    Note: Replace mytheme with your theme name in the filenames and the UCI paths below.

    # File: root/etc/uci-defaults/luci-theme-mytheme
#!/bin/sh
uci batch <<-EOF
	set luci.themes.MyTheme=/luci-static/mytheme
  set luci.main.mediaurlbase=/luci-static/mytheme
	commit luci
EOF
exit 0

# File: ipkg/postinst
#!/bin/sh
[ -n "${IPKG_INSTROOT}" ] || {
	( . /etc/uci-defaults/luci-theme-mytheme ) && rm -f /etc/uci-defaults/luci-theme-mytheme
}

  9. Compile a LuCI package and locate the IPK file

    master

    To compile a specific LuCI application and its dependencies (such as ubus, libjson-c, and rpcd), use the make package/.../compile command.

    After the build completes, the resulting .ipk file is located in: bin/packages/<architecture>/luci/.

    You can install this file on your target hardware or QEMU environment using opkg.

    make package/luci-app-example/compile

  10. Authenticate with the LuCI JSON-RPC API

    master

    Most exported libraries require authentication. If you receive an HTTP 403 Forbidden error, you must provide a valid authentication token.

    1. Obtain a token: Call the login method on the auth library at /cgi-bin/luci/rpc/auth. This method accepts a username and password (of a valid host system user).
    2. Use the token: Append the token to your RPC requests as a URL parameter named auth. For example: /cgi-bin/luci/rpc/LIBRARY?auth=TOKEN.

    Note: Cookie-aware clients (like web browsers) may automatically handle the session cookie, potentially removing the need to append the auth parameter manually.

    # Step 1: Login to get a token
curl http://<hostname>/cgi-bin/luci/rpc/auth --data '
{
  "id": 1,
  "method": "login",
  "params": [
    "youruser",
    "somepassword"
  ]
}'

# Step 2: Use the returned token in subsequent calls
curl http://<hostname>/cgi-bin/luci/rpc/LIBRARY?auth=65e60c5a93b2f2c05e61681bf5e94b49 --data '...'

  12. Install LuCI package definitions

    master

    After ensuring the feed is configured in your feeds configuration file, use the OpenWrt feed scripts to update the definitions and install all packages within the luci feed.

    #!/bin/sh
./scripts/feeds update luci
./scripts/feeds install -a -p luci