Using the busybox HTTP server

From Chumby Wiki
Jump to: navigation, search

The chumby classic and chumby one devices run a simple HTTP server using the implementation in busybox. If you don't need to do complicated web server processes, you can use that without needing to install additional software or disable the system's server.

Running CGI Scripts

The simplest way to extend the server is to add scripts and content files to /psp/cgi-bin. These will be available via http://<chumby-ip-address>/cgi-bin/custom/<script-name> Scripts need to be marked executable using

 chmod +x /psp/cgi-bin/<script-name>

Scripts can be written in C and compiled to a binary using the scratchbox toolchain or can be interpreted using a language installed on the device. To use the built-in shell, start the first line with "#!/bin/sh"; to use the mini-perl interpreter, start with "#!/usr/bin/perl".

Adding other folders

On the chumby classic, this isn't possible without reflashing the whole root file system. On the chumby one, you can remount the main file system as read/write then create folders in /www for your content. To remount the file system, use the command

 mount -o rw,remount /

Rather than make folders under /www, you may want to instead make symbolic links from /www into /mnt/storage so it's easier to add content without altering the root file system.

Configuring the Server

The busybox httpd is started without a config file. It will try to load one from /etc/httpd.conf, so on the chumby one, you can make a link from /etc/httpd.conf to /psp/httpd.conf to make it easy to adjust the global configuration. The server also reads a config file from the directory where it looks for files before sending them, so you can do local configuration there.

Default MIME Type Mappings

The default MIME mappings provided by httpd are

 text/plain: .txt, .h, .c, .cc, .cpp
 text/html: .htm, .html
 image/jpeg: .jpg, .jpeg
 image/gif: .gif
 image/png: .png
 text/css: .css
 audio/wav: .wav
 video/x-msvideo: .avi
 video/quicktime: .qt, .mov
 video/mpeg: .mpe, .mpeg
 audio/midi: .mid, .midi
 audio/mpeg: .mp3

File extensions not listed in this table or added in a local httpd.conf file will be treated as "application/octet-stream".

Supporting Additional MIME Types

from an extension mapping for a MIME type, just add a line like this to httpd.conf


This will cause any files ending in .xml to be served as text/xml.

https.conf format

This is borrowed from the httpd.c file in the BusyBox source code:

H:/serverroot     # define the server root. It will override -h
A:172.20.         # Allow address from
A:     # Allow any address from
A:  # Allow any address that previous set
A:       # Allow local loopback connections
D:*               # Deny from other IP connections
E404:/path/e404.html # /path/e404.html is the 404 (not found) error page
I:index.html      # Show index.html when a directory is requested

                  # When /urlXXXXXX is requested, reverse proxy
                  # it to http://hostname[:port]/new/pathXXXXXX

/cgi-bin:foo:bar  # Require user foo, pwd bar on urls starting with /cgi-bin/
/adm:admin:setup  # Require user admin, pwd setup on urls starting with /adm/
/adm:toor:PaSsWd  # or user toor, pwd PaSsWd on urls starting with /adm/
.au:audio/basic   # additional mime type for files
*.php:/path/php   # run xxx.php through an interpreter

A/D may be as a/d or allow/deny - only first char matters.

Deny/Allow IP logic:

* Default is to allow all (Allow all (A:*) is a no-op).
* Deny rules take precedence over allow rules.
* "Deny all" rule (D:*) is applied last.

Example 1: Allow only specified addresses

 A:172.20          # Allow any address that begins with 172.20.
 A:10.10.          # Allow any address that begins with 10.10.
 A:       # Allow local loopback connections
 D:*               # Deny from other IP connections

Example 2: Only deny specified addresses

 D:1.2.3.        # deny from -
 D:2.3.4.        # deny from -
 A:*             # (optional line added for clarity)

If a sub directory contains a config file it is parsed and merged with any existing settings as if it was appended to the original configuration.

subdir paths are relative to the containing subdir and thus cannot affect the parent rules.

Note that since the sub dir is parsed in the forked thread servicing the subdir http request, any merge is discarded when the process exits. As a result, the subdir settings only have a lifetime of a single request.

Custom error pages can contain an absolute path or be relative to 'home_httpd'. Error pages are to be static files (no CGI or script). Error page can only be defined in the root configuration file and are not taken into account in local (directories) config files.