/etc/config/uhttpd configuration is provided by the uhttpd web server package used since OpenWrt 10.03 (Backfire).
This file defines the behaviour of the server and default values for certificates generated for SSL operation. uhttpd supports multiple instances (i.e. multiple listen ports, each with its own document root and other features) as well as cgi, php5, perl and lua.
There are two sections defined, the section of type uhttpd contains general server settings while the cert one defines the default values for SSL certificates.
uhttpd config section must consist of at least the document root and HTTP listen options:
The options defined for this section are outlined below.
| ||list of port numbers or address:port pairs|| yes, if ||(none)|| Specifies the ports and addresses to listen on for plain HTTP access. If only a port number is given, the server will attempt to serve both IPv4 and IPv6 requests. Use
| ||list of port numbers or address:port pairs|| yes, if ||(none)|| Specifies the ports and addresses to listen on for encrypted HTTPS access. The format is the same as for
| ||directory path||yes|| ||Defines the server document root|
| ||file path|| yes if || ||ASN.1/DER certificate used to serve HTTPS connections|
| ||file path|| yes if || ||ASN.1/DER private key used to serve HTTPS connections|
| ||string||no|| ||Defines the prefix for CGI scripts, relative to the document root. CGI support is disabled if this option is missing|
| ||string||no||(none)||Defines the prefix for dispatching requests to the embedded Lua interpreter, relative to the document root. Lua support is disabled if this option is missing|
| ||file path|| yes if ||(none)||Lua handler script used to initialize the Lua runtime on server start|
| ||integer||no|| ||Maximum wait time for CGI or Lua requests in seconds. Requested executables are terminated if no output was generated until the timeout expired|
| ||integer||no|| ||Maximum wait time for network activity. Requested executables are terminated and connection is shut down if no network activity occured for the specified number of seconds|
| ||string||no||local hostname||Basic authentication realm when prompting the client for credentials (HTTP 400)|
| ||file path||no|| ||Config file in Busybox httpd format for additional settings (currently only used to specify Basic Auth areas)|
| ||file name||no|| ||Index file to use for directories, e.g. add index.php when using php|
| ||file name||no|| ||Index file to use for directories, e.g. add index.php when using php (last, 20131015, replace index_file ?) should be noted: list index_page "index.html"|
| ||string||no||(none)||Virtual URL of file or CGI script to handle 404 request. Must begin with '/'|
| ||boolean||no|| ||Do not follow symbolic links if enabled|
| ||boolean||no|| ||Do not generate directory listings if enabled|
| ||integer||no|| || connection reuse. Some bugs have been seen, you may wish to disable this by setting to
Multiple sections if the type uhttpd may exist - the init script will launch one webserver instance per section.
First of all, you need to install the
uhttpd-mod-tls package in order to pull into the system the 'TLS plugin which adds HTTPS support to uHTTPd'.
listen_https is defined in the server configuration, the certificate and private key is missing. In this case (as of 10.03.1) you'll need to install the
luci-ssl meta-package which in turn will pull also the
px5g script. With this utility the init script will generate the appropriate certifcate and key files when the server is started for the first time, either by reboot or by manual restart.
/etc/config/uhttpd file contains in the end a section detailing the certificate and key files creation parameters:
| ||integer||no|| ||Validity time of the generated certificates in days|
| ||integer||no|| ||Size of the generated RSA key in bits|
| ||string||no|| ||ISO country code of the certificate issuer|
| ||string||no|| ||State of the certificate issuer|
| ||string||no|| ||Location/city of the certificate issuer|
| ||string||no|| ||Common name covered by the certificate|
Those will be needed only once, at the next restart.
For backward compatibility reasons, uhttpd uses the old Busybox httpd config file
/etc/httpd.conf to define authentication areas and the associated usernames and passwords.
This configuration file is not in UCI format and usually shipped or generated by external packages like
Authentication realms are defined in the format
prefix:username:password with one entry per line followed by a newline.
prefixis the URL part covered by the realm, e.g.
/cgi-binto request basic auth for any CGI program
usernamespecifies the username a client has to login with
passworddefines the secret password required to authenticate
The password can be either in plain text format, MD5 encoded or in the form
user refers to an account in
A plain text password can be converted to MD5 encoding by using the
-m switch of the uhttpd executable:
root@OpenWrt:~# uhttpd -m secret $1$$ysVNzQc4CTMkp5daOdZ.3/
$p$… format is used, uhttpd will compare the client provided password against the one stored in the
Like Busybox HTTPd, the URL decoding of strings on the command line is supported through the
root@OpenWrt:/# uhttpd -d "An%20URL%20encoded%20String%21%0a" An URL encoded String!
A minimal php5 installation includes
In /etc/php.ini ensure that the doc_root is empty if you are using multiple uhttpd instances (each on its own port). This enables the uhttpd 'home' variable to work for you.
Ensure that you uncomment the extension interpreter line for PHP in the main section of the uHTTPd config file:
By default, uHTTPd is bind to 0.0.0.0 which also includes the WAN port of your router. To bind uHTTPd to the LAN port only you have to change the listen_http and listen_https options to your LAN IP address.
To get your current LAN IP address run this command:
uci get network.lan.ipaddr
uHTTPd supports running Lua in-process, which can speed up Lua CGI scripts.
It is unclear whether LuCI supports running in this embedded interpreter. LuCI seems to work fine (if not better) with the embedded Lua interpreter. See the next subsection for instructions on how to set it up.
Here is an example using a test file test.lua to show it works:
root@OpenWrt:~# opkg install uhttpd-mod-lua Installing uhttpd-mod-lua (18) to root... Downloading http://downloads.openwrt.org/snapshots/trunk/ar71xx/packages/uhttpd-mod-lua_18_ar71xx.ipk. Configuring uhttpd-mod-lua. root@OpenWrt:~# uci set uhttpd.main.lua_prefix=/lua root@OpenWrt:~# uci set uhttpd.main.lua_handler=/root/test.lua root@OpenWrt:~# cat /root/test.lua function handle_request(env) uhttpd.send("Status: 200 OK\r\n") uhttpd.send("Content-Type: text/plain\r\n\r\n") uhttpd.send("Hello world.\n") end root@OpenWrt:~# /etc/init.d/uhttpd restart root@OpenWrt:~# wget -qO- http://127.0.0.1/lua/ Hello world. root@OpenWrt:~#
Taken from http://pastebin.com/8H9eqiJ3. Tested on Backfire 10.03.1 with uHTTPd 28.
Taken from http://pastebin.com/8H9eqiJ3 with minor fix to make it pass on Barrier Breaker. Tested on Barrier Breaker 14.07 with uHTTPd 2014-08-25.
You need to install
luci-sgi-uhttpd to get it to work:
root@OpenWrt:~# opkg install uhttpd-mod-lua luci-sgi-uhttpd
Then uncomment the following lines in
/etc/config/uhttpd (or add them if you don't have them):
option lua_prefix /luci option lua_handler /usr/lib/lua/luci/sgi/uhttpd.lua
Then restart the server:
root@OpenWrt:~# /etc/init.d/uhttpd restart
One thing remains to be done. By default
/www/index.html redirects you to
/cgi-bin/luci which is the default CGI gateway for LuCI. The config above puts LuCI through embedded interpreter under
lua_prefix is what causes it) so you have to change that in
/www/index.html. The path appears there twice (one for the
meta tag which does the redirect and one for the anchor). You can also copy/paste the code below if you don't want to meddle with it on your own.
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="refresh" content="0; URL=/luci" /> </head> <body style="background-color: black"> <a style="color: white; text-decoration: none" href="/luci">LuCI - Lua Configuration Interface</a> </body> </html>
Also remember to flush the browser's cache if you relied on the redirection because otherwise it will probably keep redirecting you to
/cgi-bin/luci until the cache expires by itself.