ref: f423629013854dfd09b37ce2f1c7ba637df8a541
dir: /README.ms/
.br
..
.po 1i
.fp 1 R LucidaSans
.fp 2 I LucidaSansI
.fp 3 B LucidaSansB
.fp 4 BI LucidaSansBI
.fp 5 CW LucidaCW
.paragraph 0
.margin 0
.HTML "tcp80 README
.\".html - <link rel="stylesheet" href="index.css"/>
.html - <style type="text/css">body{width: 50rem; max-width: 96%; margin: 0 auto;}pre{border: 1px solid;}</style>
.SH
.LG
.ihtml header <header>
.ihtml h1 <h1>
tcp80 README
.ihtml h1
.NL
.R
.SH
What is tcp80?
.R
.ihtml header
.\".html nav <nav data-sblg-nav="1" data-sblg-navcontent="1">
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
.ihtml a <a href="https://shithub.us/garden/shithub/HEAD/info.html">
shithub
.ihtml a
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
.CW /usr/web
exists, and world readable/executable. Once this requirement is met, you need
only create the world readable/executable file
.CW /rc/bin/service/tcp80
with contents:
.ihtml pre <pre>
.ihtml code <code>
#!/bin/rc
exec /bin/tcp80
.ihtml code
.ihtml pre
This is sufficient for serving static files, and uses none of the advanced
features available.
.ihtml h2 <h2>
.NL
.R
.SH
Advanced Features
.R
.ihtml h2
.ihtml h3 <h3>
.NL
.R
.SH
Serving different static content based on request hostname
.R
.ihtml h3
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:
.ihtml pre <pre>
.ithml code <code>
server1.domain.org /usr/webroot/server1
aardvark.different.org /usr/webroot/aardvark
.ihtml code
.ihtml pre
Once you have your configuration stored, you must change your
.CW /rc/bin/service/tcp80
script. If you use captures in the regular expression, they can be used in the
pathname section.
.ihtml pre <pre>
.ihtml code <code>
#!/bin/rc
exec /bin/tcp80 -h /sys/lib/hostrules
.ihtml code
.ihtml pre
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.
.ihtml h3 <h3>
.NL
.R
.SH
Error Page Redirection
.R
.ihtml h3
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
.CW "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
.CW http://server.domain.com/nonexistent.html
tcp80 would redirect the client to
.CW http://server.domain.com/404/nonexistent.html
To use this feature, you pass multiple
.CW -e
options to tcp80 in your
.CW /rc/bin/service/tcp80
script.
.ihtml pre <pre>
.ihtml code <code>
#!/bin/rc
exec /bin/tcp80 -e 404 -e 403
.ihtml code
.ihtml pre
.ihtml h3 <h3>
.NL
.R
.SH
Integrated execfs
.R
.ihtml h3
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
.ihtml a <a href="https://shithub.us/garden/shithub/HEAD/gitrules/f.html">
gitrules
.ihtml a
file for an example.
.ihtml h3 <h3>
.NL
.R
.SH
Common Gateway Interface
.R
.ihtml h3
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:
.ihtml pre <pre>
.ihtml code <code>
/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
.ihtml code
.ihtml pre
Please note the addition of
.CW "$3
in the
.CW "exec
line. This lets tcp80 find the IP address of the client, which the CGI/1.1
specification requires.
.ihtml h2 <h2>
.NL
.R
.SH
An Example Configuration (for shithub)
.R
.ihtml h2
.ihtml pre <pre>
.ihtml code <code>
/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
.ihtml code
.ihtml pre
.ihtml h2 <h2>
.NL
.R
.SH
Oddities in the Documentation and Implementation
.R
.ihtml h2
The astute among you may have noticed that we have
.CW "/lib/namespace.httpd
but also seem to ignore it in multiple places in the documentation. This can be found in the
examples revolving around
.CW "/rc/bin/service/tcp80".
The reason for this is quite simple;
.CW /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.
.ihtml h2 <h2>
.NL
.R
.SH
Contact Information
.R
.ihtml h2
If you find a bug, or have a patch, please feel free to send email to the tcp80
mailing list at
.ihtml a <a href="mailto:[email protected]">
[email protected]
.ihtml a
To subscribe to the list, send an e-mail to
.ihtml a <a href="mailto:[email protected]">
[email protected]
.ihtml a