tcp80 README

tcp80 is an HTTP daemon originally written by cinap_lenrek, and then forked by several people, to include kvik, phil9, and myself. This fork is a combination of kvik and phil9’s ports, which includes phil9’s integration of execfs, and a functional MIME type system to send the correct Content-Type headers that modern browsers insist upon.

Other features in this fork include the ability to redirect error pages so can use your own, usually generated dynamically using the built-in execfs, and the ability to serve different content based on the Host header sent by the client.

This server is also entirely capable of running shithub using the built-in execfs.

Running a basic tcp80 setup is very simple, and requires only one file, and one directory.

First, you must ensure /usr/web exists, and world readable/executable. Once this requirement is met, you need only create the world readable/executable file /rc/bin/service/tcp80 with contents:

#!/bin/rc
exec /bin/tcp80

This is sufficient for serving static files, and uses none of the advanced features available.

Advanced Features

Serving different static content based on request hostname

This feature requires a configuration file containing mappings, the format of which is quite simple. Each line contains a regex to match the hostname against, followed by at least one tab, and a path from which to serve files, as in the following example:

server1.domain.org          /usr/webroot/server1
aardvark.different.org      /usr/webroot/aardvark

Once you have your configuration stored, you must change your /rc/bin/service/tcp80 script. If you use captures in the regular expression, they can be used in the pathname section.

#!/bin/rc
exec /bin/tcp80 -h /sys/lib/hostrules

This currently does not affect the execution of execfs rules, which exist in a single "namespace", however the configuration will likely be expanded to support the use of different execfs rules for each hostname.

Error Page Redirection

It is possible to produce custom error pages. The normal action when tcp80 encounters a situation requiring an error response, such as a 404 Not Found, it produces a very simple HTML snippet. This feature allows you to replace this functionality, however, it does so in a non-standard way.

Instead of allowing for the direct replacement of this snippet, it issues a 303 See Other response. This redirects the browser to a URL containing the error code and the location that generated it. For example, if you were to access http://server.domain.com/nonexistent.html tcp80 would redirect the client to http://server.domain.com/404/nonexistent.html

To use this feature, you pass multiple -e options to tcp80 in your /rc/bin/service/tcp80 script.

#!/bin/rc
exec /bin/tcp80 -e 404 -e 403

Integrated execfs

The integrated execfs functionality is the most advanced and powerful feature available in tcp80. Used correctly, it can provide a powerful tool for dynamic websites. Used incorrectly, it can destroy your server, open security holes, and probably set your house on fire while you’re trying to fix the security.

execfs uses the same configuration format as documented above, consisting of a regex to match the pathname (instead of hostname) against, at least one tab, and a script to run. If the regular expression contains captures, they can be used in the script section as arguments. See the shithub gitrules file for an example.

Common Gateway Interface

The integrated execfs functionality now also supports running applications that rely upon the Common Gateway Interface, CGI/1.1 (RFC 3875).

To use this, you need some bindings, and a rule (or rules) like the following:

/sys/lib/tcp80:
/cgi-bin/.*.cgi            cgi

/rc/bin/service/tcp80:
#!/bin/rc
aux/stub -d /cgi-bin
bind /usr/web/cgi-bin /cgi-bin
exec /bin/tcp80 -r /sys/lib/tcp80 $3 >>[2]/sys/log/httpd/log

Please note the addition of $3 in the exec line. This lets tcp80 find the IP address of the client, which the CGI/1.1 specification requires.

An Example Configuration (for shithub)

/rc/bin/service/tcp80:
#!/bin/auth/box -r/mnt -r/usr/git -r/sys/lib/ -r/usr/web -r/sys/lib/shithub -r/n -r/dev -eMa -s
<[3]/srv/clone{
    d=‘{<[0=3]read}
    bind /srv/$d /srv
    <[3=0]{
        bind /usr/web /mnt/static
        exec /bin/tcp80 -r /sys/lib/tcp80 >>[2]/sys/log/httpd/log
    }
}

/rc/bin/service/tcp443:
#!/bin/auth/box -r/mnt -r/usr/git -r/sys/lib -r/usr/web -r/sys/lib/shithub -r/n -r/dev -eMa -s
<[3]/srv/clone{
    d=‘{<[0=3]read}
    bind /srv/$d /srv
    <[3=0]{
        bind /usr/web /mnt/static
        exec /bin/tlssrv -c/sys/lib/tls/cert.pem -lhttpd -r‘{cat $3/remote} /bin/tcp80 \
                -r /sys/lib/tcp80 >>[2]/sys/log/httpd/log
    }
}

/lib/namespace.httpd:
bind /mnt/static /usr/web/static

Oddities in the Documentation and Implementation

The astute among you may have noticed that we have /lib/namespace.httpd but also seem to ignore it in multiple places in the documentation. This can be found in the examples revolving around /rc/bin/service/tcp80. The reason for this is quite simple; /lib/namespace.httpd is used only in untrusted mode, and only for static files. Anything involving execfs or CGI is expected to handle setting up the namespace for itself. This allows scripts full run of the system, so their first step should always be to isolate themselves as much as possible.

Contact Information

If you find a bug, or have a patch, please feel free to send email to the tcp80 mailing list at tcp80@tcp80.org

To subscribe to the list, send an e-mail to tcp80+subscribe@tcp80.org