User Tools

Site Tools


doc:howto:luci.essentials

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
doc:howto:luci.essentials [2013/02/22 07:08]
mypopy
doc:howto:luci.essentials [2016/05/22 03:27] (current)
JW0914 [Installing LuCI on uHTTPd] Updated outdated information
Line 1: Line 1:
 +====== LuCI Essentials ======
 +===== Installing LuCI on uHTTPd =====
  
 +  * **<color #​c80000>​DO NOT install //''​luci-ssl''//,​ as it is not secure due to how it employs SSL</​color>​**
 +    * //<color #​4b4b4b>//''​luci-ssl''//​ **does not** need to be installed to enable HTTPS</​color>//​
 +
 +  * <color #​4b4b4b>​**For all available LuCI packages:​**</​color>​
 +    * <color #​646464>​Via WebUI: **System** -> **Software** -> **//​Filter//​** -> //''​ luci-*''//</​color>​
 +    * <color #​646464>​Via CLI: //''​opkg update ; opkg list luci-*''//</​color>​
 +  ​
 +  * **To install LuCI via CLI:​** ​ <​sup><​color #​646464>​[**C**ommand **L**ine **I**nterface]</​color></​sup>​
 +      - //''​opkg update ; opkg install luci openssl-util px5g''//​
 +        - <color #​4b4b4b>​One will need to utilize ''​px5g''</​color>​ //or// <color #​4b4b4b>''​openssl''​ to generate a cert [//​***.crt**//​] and key [//​***.key**//​]</​color>​
 +      - <color #​646464>​**Once done, to configure** ''​uhttpd''​ **to utilize HTTPS, add the following to** //''/​etc/​config/​uhttpd''//:</​color>​
 +        * //''​list ​ listen_https ​ 192.168.1.1:​443''//​
 +          * <color #​646464>​This configures ''​uhttpd''​ to listen for SSL connections on port ''​443''</​color>​
 +            * <color #​646464>​Please note, the default config will have //''​0.0.0.0:​80''/////''​0.0.0.0:​443''//,​ and both IPs need to be changed to your router'​s LAN IP for security.</​color>​
 +        * //''​option ​ cert  '/​etc/​ssl/​certs/​certname.crt'''//​
 +          * <color #​646464>​This tells ''​uhttpd''​ where to look for the public SSL certificate</​color>​
 +        * //''​option ​ key  '/​etc/​ssl/​private/​certname.key'''//​
 +          * <color #​646464>​This tells ''​uhttpd''​ where to look for the private key it uses to encrypt the connection</​color>​
 +          * <color #​646464>​All key files should have permissions set to 400</​color>​ <​sup><​color #​7d7d7d>​[r--------]</​color></​sup>​ <color #​646464>​via:​ //''​chmod 400 *.key''//</​color>​
 +        * //''​option ​ redirect_https ​ 1''//​
 +          * <color #​646464>​This tells ''​uhttpd''​ to automatically redirect HTTP requests to the WebUI to HTTPS instead</​color>​
 +  ​
 +  * <color #​4b4b4b>​The above will result with a ''​uhttpd''​ config that looks like:</​color>​
 +  * <code bash>​list listen_http 192.168.200.1:​80
 +list listen_https 192.168.200.1:​443
 +option redirect_https 1
 +option ​ home '/​www'​
 +option ​ rfc1918_filter 1
 +option ​ max_requests 3
 +option ​ max_connections 100
 +option ​ cert '/​etc/​ssl/​certs/​certname.crt'​
 +option ​ key '/​etc/​ssl/​private/​certname.key'​
 +option ​ cgi_prefix '/​cgi-bin'​
 +option ​ script_timeout 60
 +option ​ network_timeout 30
 +option ​ http_keepalive 20
 +option ​ tcp_keepalive 1
 +option ​ ubus_prefix '/​ubus'​
 +</​code>​
 +
 +
 +| {{:​meta:​icons:​tango:​help-browser.png?​nolink}} | In case you are not familiar with a [[wp>​Command-line interface|CLI]],​ check out [[doc:​howto:​user.beginner.cli|command-line HELP]] and/or [[doc:​techref:​opkg]] |
 +
 +
 +==== Native Language Support ====
 +The basic LuCI web user interface is in English. However, it is being actively translated into many languages by volunteers. See [[http://​i18n.luci.subsignal.org/​pootle/​]] and get involved! For a list of available packages, do
 +<code bash>
 +opkg list | grep luci-i18n-
 +</​code>​
 +
 +You will see a list of the available language packages. To install your native language, do e.g.
 +<code bash>
 +opkg install luci-i18n-hungarian
 +</​code>​
 +
 +You can also install language packs utilizing the WebInterface and you can install multiple LuCI language packs at the same time and switch between them in the LuCI-WebInterface or by editing the file -> ''​[[doc:​uci:​luci|/​etc/​config/​luci]]''​
 +
 +
 +==== Start and Enable the web server (uHTTPd) ====
 +The web server software [[http.uhttpd|uHTTPd]] is a dependency of the LuCI package and is automatically installed when you install LuCI. After installation the web server is **not running!** You need to manually start the web server. You should also //enable// the web server, so that it automatically starts up whenever you reboot the router. The first command below starts the web server, the second enables it across reboots.
 +<code bash>
 +/​etc/​init.d/​uhttpd start
 +/​etc/​init.d/​uhttpd enable
 +</​code>​
 +
 +Now you should be able to connect to the web server serving LuCI at [[http://​192.168.1.1]].
 +
 +
 +==== Details ====
 +LuCI is installed as a 'meta package'​ which installs several other packages by having these defined as a dependency. Notably, it installs the [[doc:​howto:​http.uhttpd|uHTTPd]] web server, configured for use with LuCI. The dependent packages are the following (see [[doc:​techref:​luci|the LuCI technical reference]] for more information):​
 +
 +  *         ​uhttpd
 +  *         ​uhttpd-mod-ubus
 +  *         ​luci-mod-admin-full
 +  *         ​luci-theme-bootstrap
 +  *         ​luci-app-firewall
 +  *         ​luci-proto-core
 +  *         ​luci-proto-ppp
 +  *         ​libiwinfo-lua
 +
 +In case you want to use uHTTPd for the web interface there is little configuration necessary as uHTTPd is configured with CGI to make LuCI work with the Lua interpreter. By default this is organised as follows. By default ''/​www''​ is the standard document root. Thus, by requesting this docroot (by pointing your browser to the devices IP address) an index file such as ''​index.html''​ is searched for (per uHTTPd settings). The file ''/​www/​index.html''​ (installed with LuCI) is prepared such that when requested, it redirects you to ''/​cgi-bin/​luci'',​ which is the default CGI gateway for LuCI. This is just a script, which basically calls Lua at ''/​usr/​bin/​lua''​. uhttpd is configured by default to load pages as CGI in the ''/​cgi-bin''​ path, and thus starts serving these pages with the ''/​cgi-bin/​luci''​ script. ​
 +
 +It is also possible to run LuCI with Lua as an embedded process. uhttpd supports this; see the corresponding section of the [[doc:​uci:​uhttpd#​embedded.lua|uHTTPd Web Server Configuration]] article on the UCI configuration of uhttpd.
 +
 +==== Configuration ====
 +The default web server software uhttpd is configured in the file ''​[[doc:​uci:​uhttpd|/​etc/​config/​uhttpd]]''​.\\
 +The LuCI web interface is configured in the file ''​[[doc:​uci:​luci|/​etc/​config/​luci]]''​.
 +
 +===== LuCI on other web servers =====
 +->​[[doc:​howto:​http.overview]]
 +
 +==== LuCI on lighttpd ====
 +->​[[doc:​howto:​luci.on.lighttpd]]
 +
 +==== LuCI on nginx ====
 +->​[[doc:​howto:​luci.on.nginx]]
 +
 +==== LuCI on ... ====
 +
 +
 +===== Minimalistic offline installation =====
 +Download and transfer (e.g. using SCP) the packages listed below to your OpenWrt router onto the RAM disk in ''/​tmp/​luci-offline-packages''​
 +<​code>​mkdir -p /​tmp/​luci-offline-packages;​ cd /​tmp/​luci-offline-packages</​code>​
 +
 +  * liblua ​
 +  * lua 
 +  * libuci-lua
 +  * libubus ​
 +  * libubus-lua
 +  * uhttpd
 +  * rpcd
 +  * luci-base
 +  * luci-lib-ip
 +  * luci-lib-nixio
 +  * luci-theme-bootstrap
 +  * luci-mod-admin-full
 +  * luci-lib-jsonc
 +
 +and install them with:
 +
 +<code bash>​opkg install /​tmp/​luci-offline-packages/​*.ipk;​ done</​code>​
 +
 +Or use this script bellow. Note, the script assumes you have internet access through the router where you are installing Luci. If you do not, then you will need to either manually download required .ipk packages, or run the script in two parts. First part till the last Done statement to be executed when connected to Internet.:
 +<code bash>#​!/​bin/​sh
 +#assumes the user has egrep, wget, ssh, and scp
 +
 +# Change this to match your router
 +architecture="​brcm63xx"​
 +
 +# These should be fine unless you've changed something
 +user="​root"​
 +ip_address="​192.168.1.1"​
 +
 +url="​https://​downloads.openwrt.org/​snapshots/​trunk/​${architecture}/​generic/​packages/"​
 +tmpdir="/​tmp/​luci-offline"​
 +packages_base="​liblua lua libuci-lua libubus libubus-lua uhttpd rpcd"
 +packages_luci="​luci-base luci-lib-ip luci-lib-nixio luci-theme-bootstrap luci-mod-admin-full luci-lib-jsonc"​
 +
 +mkdir "​$tmpdir"​
 +cd "​$tmpdir"​
 +
 +wget -N --quiet "​${url}base/​Packages"​
 +for pkg in $packages_base;​ do
 +    pkgfile="​$(egrep -oe " ${pkg}_.+"​ Packages | tail -c +2)"
 +    pkgurl="​${url}base/​${pkgfile}"​
 +    wget -N --quiet "​$pkgurl"​
 +done
 +
 +wget -N --quiet "​${url}luci/​Packages"​
 +for pkg in $packages_luci;​ do
 +    pkgfile="​$(egrep -oe " ${pkg}_.+"​ Packages | tail -c +2)"
 +    pkgurl="​${url}luci/​${pkgfile}"​
 +    wget -N --quiet "​$pkgurl"​
 +done
 +
 +wget -N --quiet "​${url}luci"​
 +for pkg in $packages_luci;​ do
 +    pkgfile="​$(egrep -oe " ${pkg}_.+"​ Packages | tail -c +2)"
 +    pkgurl="​${url}luci/​${pkgfile}"​
 +    wget -N --quiet "​$pkgurl"​
 +done
 +
 +ssh "​${user}@${ip_address}"​ mkdir -p /​tmp/​luci-offline-packages
 +scp *.ipk "​${user}@${ip_address}":/​tmp/​luci-offline-packages
 +ssh "​${user}@${ip_address}"​ opkg install /​tmp/​luci-offline-packages/​*.ipk
 +ssh "​${user}@${ip_address}"​ rm -rf /​tmp/​luci-offline-packages/​
 +
 +ssh "​${user}@${ip_address}"​ /​etc/​init.d/​uhttpd start
 +ssh "​${user}@${ip_address}"​ /​etc/​init.d/​uhttpd enable
 +
 +cd
 +rm -rf "​$tmpdir"</​code> ​
 +
 +===== Miscellaneous =====
 +==== Secure acccess to luci webserver ====
 +If you want to configure Luci webserver for secure access, [[doc:​howto:​luci.secure|read the explanation here]].
 +
 +===== Troubleshooting =====
 +  * LuCI is developed at Github: ​ [[https://​github.com/​openwrt/​luci]]
 +  * Please file LuCI specific bugs at the [[https://​github.com/​openwrt/​luci/​issues|LuCI issue tracker]]
 +  * LuCIs old web-presence at [[http://​luci.subsignal.org|LuCI website]]
 +
 +===== Notes =====
 +[[doc:​techref:​luci|LuCI Technical Reference]]