gdritter repos melvil / 84b5130
Including unchanged readme from previous version; may no longer be accurate Getty Ritter 8 years ago
1 changed file(s) with 92 addition(s) and 0 deletion(s). Collapse all Expand all
+92
-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 conf: which path to forward to; defaults to "/dev/null"
35 resp: which HTTP response to issue; defaults to 303
36 ~~~
37
38 These are interpreted as follows:
39
40 - The `path` and `domain` fields tell us which requests to forward:
41 both of them default to accepting anything, and both of them
42 allow their values to have the wildcard character `*`.
43
44 - The `mode` field tells us _how_ to forward requests. There are
45 three possible forwarding modes:
46 - If the mode is `http`, then Aloysius will forward the HTTP
47 request to the server listening on the host `host` and the
48 port `port`.
49 - If the mode is `aloys`, then Aloysius will recursively check
50 the configuration directory at `conf`.
51 - If the mode is `redir`, then Aloysius will respond with an
52 HTTP response code as indicated in `resp` and redirect to
53 the host as indicated in `host`.
54
55 ## Example Setups
56
57 Because configuration is specified as a directory, rather than as
58 a single file, we can use properties of the Unix file system as a
59 simple ACL-like mechanism. For example, a system administrator
60 can set up a user-owned configuration directory for each user,
61 and then use a global configuration directory to forward requests
62 to that user on a per-subdomain basis:
63
64 ~~~
65 $ mkdir -p /var/run/aloys
66 $ for U in $USERS
67 > do
68 > # find the user's home directory
69 > HOMEDIR=`cat /etc/passwd | grep ${U} | cut -d ':' -f 6`
70 >
71 > # add a configuration directory to each user
72 > mkdir -p ${HOMEDIR}/aloys
73 > chown ${U} ${HOMEDIR}/aloys
74 >
75 > # add a new forwarding rule for each user
76 > mkdir -p /var/run/aloys/${U}-local
77 > # make ${U}.example.com forward to the user's aloys configuration
78 > echo "${U}.example.com" >/var/run/aloys/user-${U}/domain
79 > echo "aloys" >/var/run/aloys/user-${U}/mode
80 > echo "${HOMEDIR}/aloys" >/var/run/aloys/user-${U}/conf
81 > done
82 $ aloysius /var/run/aloys
83 ~~~
84
85 Now, if a given user wants to set up a local HTTP server that
86 produces dynamic content, they can add the appropriate forwarding
87 configuration to their own directory, but they cannot modify
88 other users' configurations or the global configuration.
89
90 Even if you're running a single server, but want to have multiple
91 services on it, this can be a convenient way to set up reverse
92 proxy servers without needing root access.