gdritter repos melvil / 05da4d9
Updated some typos in the README Getty Ritter 3 years ago
2 changed file(s) with 92 addition(s) and 92 deletion(s). Collapse all Expand all
+0
-92
README less more
1 # melvil
2
3 **EARLY AND EXPERIMENTAL**
4
5 Melvil 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 Melvil 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 Melvil will forward the HTTP
47 request to the server listening on the host `host` and the
48 port `port`.
49 - If the mode is `melvil`, then Melvil will recursively check
50 the configuration directory at `conf`.
51 - If the mode is `redir`, then Melvil 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 /etc/melvil
66 $ for U in $USERS; do
67 > # find the user's home directory
68 > HOMEDIR=`cat /etc/passwd | grep ${U} | cut -d ':' -f 6`
69 >
70 > # add a configuration directory to each user
71 > mkdir -p ${HOMEDIR}/melvil
72 > chown ${U} ${HOMEDIR}/melvil
73 >
74 > # add a new forwarding rule for each user
75 > mkdir -p /etc/${U}-local
76 >
77 > # make ${U}.example.com forward to the user's melvil configuration
78 > echo "${U}.example.com" >/melvil/user-${U}/domain
79 > echo "melvil" >/melvil/user-${U}/mode
80 > echo "${HOMEDIR}/melvil" >/melvil/user-${U}/conf
81 > done
82 $ aloysius /etc/melvil
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.
1 # melvil
2
3 **EARLY AND EXPERIMENTAL**
4
5 Melvil 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 Melvil 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 Melvil will forward the HTTP
47 request to the server listening on the host `host` and the
48 port `port`.
49 - If the mode is `melvil`, then Melvil will recursively check
50 the configuration directory at `conf`.
51 - If the mode is `redir`, then Melvil 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 /etc/melvil
66 $ for U in $USERS; do
67 > # find the user's home directory
68 > HOMEDIR=`cat /etc/passwd | grep ${U} | cut -d ':' -f 6`
69 >
70 > # add a configuration directory to each user
71 > mkdir -p ${HOMEDIR}/melvil
72 > chown ${U} ${HOMEDIR}/melvil
73 >
74 > # add a new forwarding rule for each user
75 > mkdir -p /etc/melvil/${U}-local
76 >
77 > # make ${U}.example.com forward to the user's melvil configuration
78 > echo "${U}.example.com" >/melvil/user-${U}/domain
79 > echo "melvil" >/melvil/user-${U}/mode
80 > echo "${HOMEDIR}/melvil" >/melvil/user-${U}/conf
81 > done
82 $ melvil /etc/melvil
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.