Commit 05da4d9d81b1d71445a8bb631c5d04bd47a3045b - melvil

Updated some typos in the README Getty Ritter 8 years ago

2 changed file(s) with 92 addition(s) and 92 deletion(s). Collapse all Expand all

-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.

+92

-0

README.md 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/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.