gdritter repos httputils / efb9214
Wrote README describing basic operation Getty Ritter 9 years ago
1 changed file(s) with 87 addition(s) and 0 deletion(s). Collapse all Expand all
+87
-0
README.md less more
1 # aloysius
2
3 **EARLY AND EXPERIMENTAL**
4
5 Aloysius is the HTTP server interface I want to use. It's very
6 slow at present, and still quite early, but it's at least a
7 proof-of-concept of something I think should exist.
8
9 ## Basic Use
10
11 The Aloysius server does nothing but pass HTTP requests and
12 responses between other servers: it is, in effect, a mechanism
13 for establishing reverse proxies.
14
15 The server is invoked with a single optional argument, and it
16 continues running in the foreground until it is killed with
17 standard Unix signals. The argument is a directory, and if that
18 directory exists, it switches to that directory before
19 continuing. It then reads configuration from that directory and
20 will continuously forward requests based on that configuration.
21
22 The configuration directory contains zero or more
23 subdirectories, each of which describes a given request filter
24 and forwarding mechanism. The subdirectory may contain several
25 specifically named files, whose contents specify a forwarding
26 system:
27
28 ~~~
29 path: which request paths to match; defaults to "*"
30 domain: which request subdomains to match; defaults to "*"
31 mode: how to forward the request; defaults to "http"
32 host: which host to forward to; defaults to "localhost"
33 port: which port to forward to; defaults to "80"
34 path: which path to forward to; defaults to "/dev/null"
35 ~~~
36
37 These are interpreted as follows:
38
39 - The `path` and `domain` fields tell us which requests to forward:
40 both of them default to accepting anything, and both of them
41 allow their values to have the wildcard character `*`.
42
43 - The `mode` field tells us _how_ to forward requests: right now,
44 it can only contain the values `http` or `aloys`. If the mode is
45 `http`, then Aloysius will forward the HTTP request to the server
46 listening on the host `host` and the port `port`. If the mode is
47 `aloys`, then Aloysius will recursively check the configuration
48 directory at `path`.
49
50 ## Example Setups
51
52 Because configuration is specified as a directory, rather than as
53 a single file, we can use properties of the Unix file system as a
54 simple ACL-like mechanism. For example, a system administrator
55 can set up a user-owned configuration directory for each user,
56 and then use a global configuration directory to forward requests
57 to that user on a per-subdomain basis:
58
59 ~~~
60 $ mkdir -p /var/run/aloys
61 $ for U in $USERS
62 > do
63 > # find the user's home directory
64 > HOMEDIR=`cat /etc/passwd | grep ${U} | cut -d ':' -f 6`
65 >
66 > # add a configuration directory to each user
67 > mkdir -p ${HOMEDIR}/aloys
68 > chown ${U} ${HOMEDIR}/aloys
69 >
70 > # add a new forwarding rule for each user
71 > mkdir -p /var/run/aloys/${U}-local
72 > # make ${U}.example.com forward to the user's aloys configuration
73 > echo "${U}.example.com" >/var/run/aloys/user-${U}/domain
74 > echo "aloys" >/var/run/aloys/user-${U}/mode
75 > echo "${HOMEDIR}/aloys" >/var/run/aloys/user-${U}/path
76 > done
77 $ aloysius /var/run/aloys
78 ~~~
79
80 Now, if a given user wants to set up a local HTTP server that
81 produces dynamic content, they can add the appropriate forwarding
82 configuration to their own directory, but they cannot modify
83 other users' configurations or the global configuration.
84
85 Even if you're running a single server, but want to have multiple
86 services on it, this can be a convenient way to set up reverse
87 proxy servers without needing root access.