Fossil SCM

Added the www/server/any/http-over-ssh.md doc, an elaboration of Andy Bradford's OpenSSH ForceCommand based solution for forcing access via ssh:// URLs to go through a wrapper script that rewrites the command, exchanging "test-http" for "http", causing the Fossil RBAC system to come into play in a secure fashion. Linking to it from the top-level "server/" index and from the #webonly section of the caps/ index where it cites this limitation. Reworked the latter section now that we have a documented alternative.

wyoung 2021-09-18 00:51 trunk

Commit be8ed971f9e640271070f2b936b4043e59f53d48c4ceb5125e020d754e3de9aa

Parent 391bc369872059c…

3 files changed +11 -8 +138 +18 -9

~ www/caps/index.md + www/server/any/http-over-ssh.md ~ www/server/index.html

M www/caps/index.md

+11 -8

		--- www/caps/index.md
		+++ www/caps/index.md
		@@ -288,45 +288,48 @@
288	288	defeated because your user has [Setup][s] capability on both sides
289	289	of the sync. Be aware that those file checks do still matter, however:
290	290	Fossil requires write access to a repo DB while cloning from it, so you
291	291	can’t clone from a read-only repo DB file over a local file path.
292	292
293		-Even more surprising may be the fact that user caps do not affect
294		-cloning and syncing over SSH! When you make a change to such a
295		-repository, the change first goes to the local clone where file system
	293	+Even more surprising to you may be the fact that user caps do not affect
	294	+cloning and syncing over SSH! (Not unless you go [out of your way][sshfc]
	295	+patch around it, at any rate.) When you make a change to such a
	296	+repository, the stock Fossil behavior is that the change first goes to the
	297	+local repo clone where file system
296	298	permissions are all that matter, but then upon sync, the situation is
297	299	effectively the same as when the parent repo is on the local file
298	300	system. The reason behind this is that if you can log into the remote
299	301	system over SSH and that user has the necessary file system permissions
300	302	on that remote repo DB file to allow clone and sync operations, then
301	303	we’re back in the same situation as with local files: there’s no point
302	304	trying to enforce the Fossil user capabilities when you can just modify
303		-the remote DB directly, so the operation proceeds unimpeded.
	305	+the remote DB directly, so the operation proceeds unimpeded by any user
	306	+capability settings on the remote repo.
304	307
305	308	Where this gets confusing is that all Fossil syncs are done over the
306	309	HTTP protocol, including those done over `file://` and `ssh://` URLs,
307	310	not just those done over `http[s]://` URLs:
308	311
309	312	* For `ssh://` URLs, Fossil pipes the HTTP conversation through a
310	313	local SSH client to a remote instance of Fossil running the
311	314	[`test-http`](/help?name=test-http) command to receive the tunneled
312		- HTTP connection. The reason Fossil’s user capability system is
313		- bypassed in this case is that [`test-http` gives full capabilities
314		- to its users][sxycap].
	315	+ HTTP connection. [This interface is intentionally permissionless][sxycap].
315	316
316	317	* For `file://` URLs — as opposed to plain local file paths —
317	318	the “sending” Fossil instance writes its side of
318	319	the HTTP conversation out to a temporary file in the same directory
319	320	as the local repo clone and then calls itself on the “receiving”
320	321	repository to read that same HTTP transcript file back in to apply
321	322	those changes to that repository. Presumably Fossil does this
322	323	instead of using a pipe to ease portability to Windows.
323	324
324		-Checks for capabilities like [Read][o] and [Write][i] within the
	325	+Despite use of HTTP for these URL types, the fact remains that
	326	+checks for capabilities like [Read][o] and [Write][i] within the
325	327	HTTP conversation between two Fossil instances only have a useful effect
326	328	when done over an `http[s]://` URL.
327	329
	330	+[sshfc]: ../server/any/http-over-ssh.md
328	331	[sxycap]: /file?ci=ec5efceb8aac6cb4&name=src/main.c&ln=2748-2752
329	332
330	333
331	334	## <a id="pubpg"></a>Public Pages
332	335
333	336
334	337	ADDED www/server/any/http-over-ssh.md

	--- www/caps/index.md
	+++ www/caps/index.md
	@@ -288,45 +288,48 @@
288	defeated because your user has [Setup][s] capability on both sides
289	of the sync. Be aware that those file checks do still matter, however:
290	Fossil requires write access to a repo DB while cloning from it, so you
291	can’t clone from a read-only repo DB file over a local file path.
292
293	Even more surprising may be the fact that user caps do not affect
294	cloning and syncing over SSH! When you make a change to such a
295	repository, the change first goes to the local clone where file system


296	permissions are all that matter, but then upon sync, the situation is
297	effectively the same as when the parent repo is on the local file
298	system. The reason behind this is that if you can log into the remote
299	system over SSH and that user has the necessary file system permissions
300	on that remote repo DB file to allow clone and sync operations, then
301	we’re back in the same situation as with local files: there’s no point
302	trying to enforce the Fossil user capabilities when you can just modify
303	the remote DB directly, so the operation proceeds unimpeded.

304
305	Where this gets confusing is that all Fossil syncs are done over the
306	HTTP protocol, including those done over `file://` and `ssh://` URLs,
307	not just those done over `http[s]://` URLs:
308
309	* For `ssh://` URLs, Fossil pipes the HTTP conversation through a
310	local SSH client to a remote instance of Fossil running the
311	[`test-http`](/help?name=test-http) command to receive the tunneled
312	HTTP connection. The reason Fossil’s user capability system is
313	bypassed in this case is that [`test-http` gives full capabilities
314	to its users][sxycap].
315
316	* For `file://` URLs — as opposed to plain local file paths —
317	the “sending” Fossil instance writes its side of
318	the HTTP conversation out to a temporary file in the same directory
319	as the local repo clone and then calls itself on the “receiving”
320	repository to read that same HTTP transcript file back in to apply
321	those changes to that repository. Presumably Fossil does this
322	instead of using a pipe to ease portability to Windows.
323
324	Checks for capabilities like [Read][o] and [Write][i] within the

325	HTTP conversation between two Fossil instances only have a useful effect
326	when done over an `http[s]://` URL.
327

328	[sxycap]: /file?ci=ec5efceb8aac6cb4&name=src/main.c&ln=2748-2752
329
330
331	## <a id="pubpg"></a>Public Pages
332
333
334	DDED www/server/any/http-over-ssh.md

	--- www/caps/index.md
	+++ www/caps/index.md
	@@ -288,45 +288,48 @@
288	defeated because your user has [Setup][s] capability on both sides
289	of the sync. Be aware that those file checks do still matter, however:
290	Fossil requires write access to a repo DB while cloning from it, so you
291	can’t clone from a read-only repo DB file over a local file path.
292
293	Even more surprising to you may be the fact that user caps do not affect
294	cloning and syncing over SSH! (Not unless you go [out of your way][sshfc]
295	patch around it, at any rate.) When you make a change to such a
296	repository, the stock Fossil behavior is that the change first goes to the
297	local repo clone where file system
298	permissions are all that matter, but then upon sync, the situation is
299	effectively the same as when the parent repo is on the local file
300	system. The reason behind this is that if you can log into the remote
301	system over SSH and that user has the necessary file system permissions
302	on that remote repo DB file to allow clone and sync operations, then
303	we’re back in the same situation as with local files: there’s no point
304	trying to enforce the Fossil user capabilities when you can just modify
305	the remote DB directly, so the operation proceeds unimpeded by any user
306	capability settings on the remote repo.
307
308	Where this gets confusing is that all Fossil syncs are done over the
309	HTTP protocol, including those done over `file://` and `ssh://` URLs,
310	not just those done over `http[s]://` URLs:
311
312	* For `ssh://` URLs, Fossil pipes the HTTP conversation through a
313	local SSH client to a remote instance of Fossil running the
314	[`test-http`](/help?name=test-http) command to receive the tunneled
315	HTTP connection. [This interface is intentionally permissionless][sxycap].


316
317	* For `file://` URLs — as opposed to plain local file paths —
318	the “sending” Fossil instance writes its side of
319	the HTTP conversation out to a temporary file in the same directory
320	as the local repo clone and then calls itself on the “receiving”
321	repository to read that same HTTP transcript file back in to apply
322	those changes to that repository. Presumably Fossil does this
323	instead of using a pipe to ease portability to Windows.
324
325	Despite use of HTTP for these URL types, the fact remains that
326	checks for capabilities like [Read][o] and [Write][i] within the
327	HTTP conversation between two Fossil instances only have a useful effect
328	when done over an `http[s]://` URL.
329
330	[sshfc]: ../server/any/http-over-ssh.md
331	[sxycap]: /file?ci=ec5efceb8aac6cb4&name=src/main.c&ln=2748-2752
332
333
334	## <a id="pubpg"></a>Public Pages
335
336
337	DDED www/server/any/http-over-ssh.md

A www/server/any/http-over-ssh.md

+138

		--- a/www/server/any/http-over-ssh.md
		+++ b/www/server/any/http-over-ssh.md
		@@ -0,0 +1,138 @@
	1	+# Forcing Use of Fossil’s RBonceBAC over SSH
	2	+
	3	+Andy Bradford posted a [clever solution][sshfc] to the problem of
	4	+Fossil’s RBAC system [being ignored](../../caps/#webonly) over `ssh://`
	5	+URLs: use OpenSSH’s `ForceCommand` feature to route the sync transfer
	6	+protocol data over `fossil http` rather than `fossil test-http`.
	7	+
	8	+The setup for this is complicated, but it’s a worthy option when you
	9	+need encrypted communications between the client and server, you already
	10	+have SSH set up, and [the HTTPS alternative](../../ssl.wiki) is
	11	+unworkable for some reason.
	12	+
	13	+
	14	+## 1. Force remote Fossil access through a wrapper script <a id="sshd"></a>
	15	+
	16	+Put something like the following into the `sshd_config` file on the
	17	+Fossil reposito ry server:
	18	+
	19	+``` ssh-con-config
	20	+Match Group fossi AllowTcpForwarding no
	21	+
	22	+ AllowTcpForwarding no
	23	+ A ForceCommand /home/fossil/bin/wrapper
	24	+```
	25	+
	26	+This file is usually found in `/etc/ssh`, but some OSes put it
	27	+elsewhere.
	28	+
	29	+The first line presumes that we will put all users who need to use our
	30	+Fossil repositories into the `fossil` group, as we will do
	31	+[below](#perms). You could instead say something like:
	32	+
	33	+``` ssh-config
	34	+ Match User alice,bob,carol,dave
	35	+```
	36	+
	37	+You have to list the users allowed to use Fossil in this case because
	38	+your system likely has a system administrator that uses SSH for remote
	39	+shell access, so you want to exclude that user from the list. For the
	40	+same reason, you don’t want to put the `ForceCommand` directive outside
	41	+a `Match` block of some sort.
	42	+
	43	+You could instead list the exceptions:
	44	+
	45	+``` ssh-config
	46	+ xceptions:
	47	+
	48	+``` ssh-config
	49	+Match User !edie
	50	+```
	51	+
	52	+This would permit only Edi
	53	+## 2. Rewrite the sync command with that wrapper <a id="wrapper"></a>
	54	+
	55	+When Fossil syncs over SSH, it attempts to launch a remote Fossil
	56	+instance with certain parameters in order to set up the HTTP-based sync
	57	+protocol over that SSH tunnel. We need to preserve some of this command
	58	+and rewrite other parts to make this work.
	59	+
	60	+Here is a simpler variant of Andy’s origin #!/bin/bash
	61	+ rwarding no
	62	+ AllowTcpForwa rding no
	63	+ ForceCommand /home/foss ROOT=/home/fossil
	64	+ home/fossil/bin/wrapper
	65	+```
	66	+
	67	+This file is usually found in `/etc/ssh`, but some OSes put it
	68	+elsewhere.
	69	+
	70	+The first line presumes that we will put all users who need to use our
	71	+Fossil repositories into the `fossil` group, as we will do
	72	+[below](#perms). You could instead say something like:
	73	+
	74	+``` ssh-config
	75	+Match User alice,bob,carol,dave
	76	+```
	77	+
	78	+You have to list the users allowed to use Fossil in this case because
	79	+your system likely has a system administrator that uses SSH for remote
	80	+shell access, so you want to exclude that user from the list. For the
	81	+same reason, you don’t want to put the `ForceCommand` directive outside
	82	+a `Match` block of some sort.
	83	+
	84	+You could instead list the exceptions:
	85	+
	86	+``` ssh-config
	87	+Match User !evi
	88	+```
	89	+
	90	+This would permit only [Evi the System Administrator][evi] to bypass this
	91	+mechanism.
	92	+
	93	+[ to bypass this
	94	+mechanism.
	95	+
	96	+[evi]: https://en.wikipedia.org/wiki/Evi_Nemeth
	97	+
	98	+If you have a user that needs both interactive SSH shell access and
	99	+Fossil access, exclude that user from the `Match` rule and use Fossil’s
	100	+normal `ssh://` URL scheme for those cases. This user will bypass the
	101	+Fossil RBAC, but they effectively have Setup capability on those
	102	+repositories anyway by having full read/write access to the DB files via
	103	+the shell.
	104	+
	105	+
	106	+## 2. Rewrite the sync command with that wrapper <a id="HTTP-based sync
	107	+protocol over that SSH tunnel. We need to preserve some of this command
	108	+and rewrite other parts to make this work.
	109	+
	110	+Here is a simpler variant of Andy’s origin #!/bin/bash
	111	+ rwarding no
	112	+ AllowTcpForwa rding no
	113	+ ForceCommand /home/foss ROOT=/home/fossil
	114	+ home/fossil/bin/wrapper
	115	+```
	116	+
	117	+This file is usually found in `/etc/ssh`, but some OSes put it
	118	+elsewhere.
	119	+
	120	+The first line presumes that we will put all users who need to use our
	121	+Fossil rep,itories intything like. wol access through a wrapper script <a id="sshd"></a>
	122	+
	123	+Put something like the e `REMOTE_USER`
	124	+certain conYou have to give
	125	+the following command on each repository where you want to allow this## 4e following into the `sshd_config` file on the
	126	+Fossil repository server:
	127	+
	128	+``` ssh-config
	129	+Match Group fossil
	130	+ X11Forwarsudo adduser fossil
	131	+sudo adduser $u
	132	+done
	133	+sudo -i -u fossil
	134	+chmod 710 .
	135	+mkdir -m 750 bin
	136	+mkdir -m 770 museum
	137	+ and [permit
	138	+`REMOTE_USER`

	--- a/www/server/any/http-over-ssh.md
	+++ b/www/server/any/http-over-ssh.md
	@@ -0,0 +1,138 @@

	--- a/www/server/any/http-over-ssh.md
	+++ b/www/server/any/http-over-ssh.md
	@@ -0,0 +1,138 @@
1	# Forcing Use of Fossil’s RBonceBAC over SSH
2
3	Andy Bradford posted a [clever solution][sshfc] to the problem of
4	Fossil’s RBAC system [being ignored](../../caps/#webonly) over `ssh://`
5	URLs: use OpenSSH’s `ForceCommand` feature to route the sync transfer
6	protocol data over `fossil http` rather than `fossil test-http`.
7
8	The setup for this is complicated, but it’s a worthy option when you
9	need encrypted communications between the client and server, you already
10	have SSH set up, and [the HTTPS alternative](../../ssl.wiki) is
11	unworkable for some reason.
12
13
14	## 1. Force remote Fossil access through a wrapper script <a id="sshd"></a>
15
16	Put something like the following into the `sshd_config` file on the
17	Fossil reposito ry server:
18
19	``` ssh-con-config
20	Match Group fossi AllowTcpForwarding no
21
22	AllowTcpForwarding no
23	A ForceCommand /home/fossil/bin/wrapper
24	```
25
26	This file is usually found in `/etc/ssh`, but some OSes put it
27	elsewhere.
28
29	The first line presumes that we will put all users who need to use our
30	Fossil repositories into the `fossil` group, as we will do
31	[below](#perms). You could instead say something like:
32
33	``` ssh-config
34	Match User alice,bob,carol,dave
35	```
36
37	You have to list the users allowed to use Fossil in this case because
38	your system likely has a system administrator that uses SSH for remote
39	shell access, so you want to exclude that user from the list. For the
40	same reason, you don’t want to put the `ForceCommand` directive outside
41	a `Match` block of some sort.
42
43	You could instead list the exceptions:
44
45	``` ssh-config
46	xceptions:
47
48	``` ssh-config
49	Match User !edie
50	```
51
52	This would permit only Edi
53	## 2. Rewrite the sync command with that wrapper <a id="wrapper"></a>
54
55	When Fossil syncs over SSH, it attempts to launch a remote Fossil
56	instance with certain parameters in order to set up the HTTP-based sync
57	protocol over that SSH tunnel. We need to preserve some of this command
58	and rewrite other parts to make this work.
59
60	Here is a simpler variant of Andy’s origin #!/bin/bash
61	rwarding no
62	AllowTcpForwa rding no
63	ForceCommand /home/foss ROOT=/home/fossil
64	home/fossil/bin/wrapper
65	```
66
67	This file is usually found in `/etc/ssh`, but some OSes put it
68	elsewhere.
69
70	The first line presumes that we will put all users who need to use our
71	Fossil repositories into the `fossil` group, as we will do
72	[below](#perms). You could instead say something like:
73
74	``` ssh-config
75	Match User alice,bob,carol,dave
76	```
77
78	You have to list the users allowed to use Fossil in this case because
79	your system likely has a system administrator that uses SSH for remote
80	shell access, so you want to exclude that user from the list. For the
81	same reason, you don’t want to put the `ForceCommand` directive outside
82	a `Match` block of some sort.
83
84	You could instead list the exceptions:
85
86	``` ssh-config
87	Match User !evi
88	```
89
90	This would permit only [Evi the System Administrator][evi] to bypass this
91	mechanism.
92
93	[ to bypass this
94	mechanism.
95
96	[evi]: https://en.wikipedia.org/wiki/Evi_Nemeth
97
98	If you have a user that needs both interactive SSH shell access and
99	Fossil access, exclude that user from the `Match` rule and use Fossil’s
100	normal `ssh://` URL scheme for those cases. This user will bypass the
101	Fossil RBAC, but they effectively have Setup capability on those
102	repositories anyway by having full read/write access to the DB files via
103	the shell.
104
105
106	## 2. Rewrite the sync command with that wrapper <a id="HTTP-based sync
107	protocol over that SSH tunnel. We need to preserve some of this command
108	and rewrite other parts to make this work.
109
110	Here is a simpler variant of Andy’s origin #!/bin/bash
111	rwarding no
112	AllowTcpForwa rding no
113	ForceCommand /home/foss ROOT=/home/fossil
114	home/fossil/bin/wrapper
115	```
116
117	This file is usually found in `/etc/ssh`, but some OSes put it
118	elsewhere.
119
120	The first line presumes that we will put all users who need to use our
121	Fossil rep,itories intything like. wol access through a wrapper script <a id="sshd"></a>
122
123	Put something like the e `REMOTE_USER`
124	certain conYou have to give
125	the following command on each repository where you want to allow this## 4e following into the `sshd_config` file on the
126	Fossil repository server:
127
128	``` ssh-config
129	Match Group fossil
130	X11Forwarsudo adduser fossil
131	sudo adduser $u
132	done
133	sudo -i -u fossil
134	chmod 710 .
135	mkdir -m 750 bin
136	mkdir -m 770 museum
137	and [permit
138	`REMOTE_USER`

M www/server/index.html

+18 -9

		--- www/server/index.html
		+++ www/server/index.html
		@@ -106,17 +106,18 @@
106	106	the server is running</a>.</p>
107	107
108	108
109	109	<h2 id="methods">Activation Methods</h2>
110	110
111		-<p>There are basically four ways to run a Fossil server:</p>
	111	+<p>There are basically five ways to run a Fossil server:</p>
112	112
113	113	<ol>
114		- <li><a id="cgi" href="any/cgi.md">CGI</a>
115		- <li>Socket listener
116		- <li><a id="standalone" href="any/none.md">Stand-alone HTTP server</a>
117		- <li><a id="scgi" href="any/scgi.md">SCGI</a>
	114	+ <li><a href="any/cgi.md">CGI</a>
	115	+ <li><a href="#slist">Socket listener</a>
	116	+ <li><a href="any/none.md">Stand-alone HTTP server</a>
	117	+ <li><a href="any/scgi.md">SCGI</a>
	118	+ <li><a href="#ssh">SSH</a>
118	119	</ol>
119	120
120	121	<p>All of these methods can serve either a single repository or a
121	122	directory hierarchy containing mulitiple repositories.</p>
122	123
		@@ -125,11 +126,11 @@
125	126	the same time. These methods use clean, well-defined, standard
126	127	interfaces (CGI, SCGI, and HTTP) which allow you to easily migrate from
127	128	one method to another in response to changes in hosting providers or
128	129	administrator preferences.</p>
129	130
130		-<h3>CGI</h3>
	131	+<h3 id="cgi">CGI</h3>
131	132
132	133	<p>Most ordinary web servers can <a href="any/cgi.md">run Fossil as a
133	134	CGI script</a>. This method is known to work with Apache,
134	135	<tt>lighttpd</tt>, and <a
135	136	href="any/althttpd.md"><tt>althttpd</tt></a>. The Fossil server
		@@ -141,11 +142,11 @@
141	142	<p>CGI is a good choice for merging Fossil into an existing web site,
142	143	particularly on hosts that have CGI set up and working.
143	144	The Fossil <a href="../selfhost.wiki">self-hosting repositories</a> are
144	145	implemented with CGI underneath <tt>althttpd</tt>.</p>
145	146
146		-<h3>Socket Listener</h3>
	147	+<h3 id="slist">Socket Listener</h3>
147	148
148	149	<p>Socket listener daemons such as
149	150	<a id="inetd" href="any/inetd.md"><tt>inetd</tt></a>, <a id="xinetd"
150	151	href="any/xinetd.md"><tt>xinetd</tt></a>, <a id="stunnel"
151	152	href="any/stunnel.md"><tt>stunnel</tt></a>, <a
		@@ -159,11 +160,11 @@
159	160	invocation of the "<tt>fossil http</tt>" command for each HTTP request.
160	161	The socket listener daemon takes care of relaying content to and from
161	162	the client, and (in the case of <a href="any/stunnel.md">stunnel</a>)
162	163	handling TLS decryption and encryption.
163	164
164		-<h3>Stand-alone HTTP Server</h3>
	165	+<h3 id="standalone">Stand-alone HTTP Server</h3>
165	166
166	167	<p>This is the <a href="any/none.md">easiest method</a>.
167	168	A stand-alone server uses the
168	169	<a href="$ROOT/help?cmd=server"><tt>fossil server</tt></a> command to run a
169	170	process that listens for incoming HTTP requests on a socket and then
		@@ -170,11 +171,11 @@
170	171	dispatches a copy of itself to deal with each incoming request. You can
171	172	expose Fossil directly to the clients in this way or you can interpose a
172	173	<a href="https://en.wikipedia.org/wiki/Reverse_proxy">reverse proxy</a>
173	174	layer between the clients and Fossil.</p>
174	175
175		-<h3>SCGI</h3>
	176	+<h3 id="scgi"3>SCGI</h3>
176	177
177	178	<p>The Fossil standalone server can also handle <a href="any/scgi.md">SCGI</a>.
178	179	When the <a href="$ROOT/help?cmd=server"><tt>fossil server</tt></a> command is
179	180	run with the extra <tt>--scgi</tt> option, it listens for incoming
180	181	SCGI requests rather than HTTP requests. This allows Fossil to
		@@ -185,10 +186,18 @@
185	186	up because you also have to set up an SCGI-to-HTTP proxy for it. It is
186	187	worth taking on this difficulty only when you need to integrate Fossil
187	188	into an existing web site already being served by an SCGI-capable web
188	189	server.</p>
189	190
	191	+<h3 id="ssh">SSH</h3>
	192	+
	193	+<p>Fossil supports <tt>ssh://</tt> URLs, but there are <a
	194	+href="../caps/#webonly">practical limitations</a> with the default
	195	+behavior. You can get the full power of <a href="../caps/">Fossil's RBAC
	196	+system</a> over SSH <a href="any/http-over-ssh.md">with a bit of clever
	197	+configuration</a>.</p>
	198	+
190	199	<h2 id="matrix">Activation Tutorials</h2>
191	200
192	201	<p>We've broken the configuration for each method out into a series of
193	202	sub-articles. Some of these are generic, while others depend on
194	203	particular operating systems or front-end software:</p>
195	204

	--- www/server/index.html
	+++ www/server/index.html
	@@ -106,17 +106,18 @@
106	the server is running</a>.</p>
107
108
109	<h2 id="methods">Activation Methods</h2>
110
111	<p>There are basically four ways to run a Fossil server:</p>
112
113	<ol>
114	<li><a id="cgi" href="any/cgi.md">CGI</a>
115	<li>Socket listener
116	<li><a id="standalone" href="any/none.md">Stand-alone HTTP server</a>
117	<li><a id="scgi" href="any/scgi.md">SCGI</a>

118	</ol>
119
120	<p>All of these methods can serve either a single repository or a
121	directory hierarchy containing mulitiple repositories.</p>
122
	@@ -125,11 +126,11 @@
125	the same time. These methods use clean, well-defined, standard
126	interfaces (CGI, SCGI, and HTTP) which allow you to easily migrate from
127	one method to another in response to changes in hosting providers or
128	administrator preferences.</p>
129
130	<h3>CGI</h3>
131
132	<p>Most ordinary web servers can <a href="any/cgi.md">run Fossil as a
133	CGI script</a>. This method is known to work with Apache,
134	<tt>lighttpd</tt>, and <a
135	href="any/althttpd.md"><tt>althttpd</tt></a>. The Fossil server
	@@ -141,11 +142,11 @@
141	<p>CGI is a good choice for merging Fossil into an existing web site,
142	particularly on hosts that have CGI set up and working.
143	The Fossil <a href="../selfhost.wiki">self-hosting repositories</a> are
144	implemented with CGI underneath <tt>althttpd</tt>.</p>
145
146	<h3>Socket Listener</h3>
147
148	<p>Socket listener daemons such as
149	<a id="inetd" href="any/inetd.md"><tt>inetd</tt></a>, <a id="xinetd"
150	href="any/xinetd.md"><tt>xinetd</tt></a>, <a id="stunnel"
151	href="any/stunnel.md"><tt>stunnel</tt></a>, <a
	@@ -159,11 +160,11 @@
159	invocation of the "<tt>fossil http</tt>" command for each HTTP request.
160	The socket listener daemon takes care of relaying content to and from
161	the client, and (in the case of <a href="any/stunnel.md">stunnel</a>)
162	handling TLS decryption and encryption.
163
164	<h3>Stand-alone HTTP Server</h3>
165
166	<p>This is the <a href="any/none.md">easiest method</a>.
167	A stand-alone server uses the
168	<a href="$ROOT/help?cmd=server"><tt>fossil server</tt></a> command to run a
169	process that listens for incoming HTTP requests on a socket and then
	@@ -170,11 +171,11 @@
170	dispatches a copy of itself to deal with each incoming request. You can
171	expose Fossil directly to the clients in this way or you can interpose a
172	<a href="https://en.wikipedia.org/wiki/Reverse_proxy">reverse proxy</a>
173	layer between the clients and Fossil.</p>
174
175	<h3>SCGI</h3>
176
177	<p>The Fossil standalone server can also handle <a href="any/scgi.md">SCGI</a>.
178	When the <a href="$ROOT/help?cmd=server"><tt>fossil server</tt></a> command is
179	run with the extra <tt>--scgi</tt> option, it listens for incoming
180	SCGI requests rather than HTTP requests. This allows Fossil to
	@@ -185,10 +186,18 @@
185	up because you also have to set up an SCGI-to-HTTP proxy for it. It is
186	worth taking on this difficulty only when you need to integrate Fossil
187	into an existing web site already being served by an SCGI-capable web
188	server.</p>
189








190	<h2 id="matrix">Activation Tutorials</h2>
191
192	<p>We've broken the configuration for each method out into a series of
193	sub-articles. Some of these are generic, while others depend on
194	particular operating systems or front-end software:</p>
195

	--- www/server/index.html
	+++ www/server/index.html
	@@ -106,17 +106,18 @@
106	the server is running</a>.</p>
107
108
109	<h2 id="methods">Activation Methods</h2>
110
111	<p>There are basically five ways to run a Fossil server:</p>
112
113	<ol>
114	<li><a href="any/cgi.md">CGI</a>
115	<li><a href="#slist">Socket listener</a>
116	<li><a href="any/none.md">Stand-alone HTTP server</a>
117	<li><a href="any/scgi.md">SCGI</a>
118	<li><a href="#ssh">SSH</a>
119	</ol>
120
121	<p>All of these methods can serve either a single repository or a
122	directory hierarchy containing mulitiple repositories.</p>
123
	@@ -125,11 +126,11 @@
126	the same time. These methods use clean, well-defined, standard
127	interfaces (CGI, SCGI, and HTTP) which allow you to easily migrate from
128	one method to another in response to changes in hosting providers or
129	administrator preferences.</p>
130
131	<h3 id="cgi">CGI</h3>
132
133	<p>Most ordinary web servers can <a href="any/cgi.md">run Fossil as a
134	CGI script</a>. This method is known to work with Apache,
135	<tt>lighttpd</tt>, and <a
136	href="any/althttpd.md"><tt>althttpd</tt></a>. The Fossil server
	@@ -141,11 +142,11 @@
142	<p>CGI is a good choice for merging Fossil into an existing web site,
143	particularly on hosts that have CGI set up and working.
144	The Fossil <a href="../selfhost.wiki">self-hosting repositories</a> are
145	implemented with CGI underneath <tt>althttpd</tt>.</p>
146
147	<h3 id="slist">Socket Listener</h3>
148
149	<p>Socket listener daemons such as
150	<a id="inetd" href="any/inetd.md"><tt>inetd</tt></a>, <a id="xinetd"
151	href="any/xinetd.md"><tt>xinetd</tt></a>, <a id="stunnel"
152	href="any/stunnel.md"><tt>stunnel</tt></a>, <a
	@@ -159,11 +160,11 @@
160	invocation of the "<tt>fossil http</tt>" command for each HTTP request.
161	The socket listener daemon takes care of relaying content to and from
162	the client, and (in the case of <a href="any/stunnel.md">stunnel</a>)
163	handling TLS decryption and encryption.
164
165	<h3 id="standalone">Stand-alone HTTP Server</h3>
166
167	<p>This is the <a href="any/none.md">easiest method</a>.
168	A stand-alone server uses the
169	<a href="$ROOT/help?cmd=server"><tt>fossil server</tt></a> command to run a
170	process that listens for incoming HTTP requests on a socket and then
	@@ -170,11 +171,11 @@
171	dispatches a copy of itself to deal with each incoming request. You can
172	expose Fossil directly to the clients in this way or you can interpose a
173	<a href="https://en.wikipedia.org/wiki/Reverse_proxy">reverse proxy</a>
174	layer between the clients and Fossil.</p>
175
176	<h3 id="scgi"3>SCGI</h3>
177
178	<p>The Fossil standalone server can also handle <a href="any/scgi.md">SCGI</a>.
179	When the <a href="$ROOT/help?cmd=server"><tt>fossil server</tt></a> command is
180	run with the extra <tt>--scgi</tt> option, it listens for incoming
181	SCGI requests rather than HTTP requests. This allows Fossil to
	@@ -185,10 +186,18 @@
186	up because you also have to set up an SCGI-to-HTTP proxy for it. It is
187	worth taking on this difficulty only when you need to integrate Fossil
188	into an existing web site already being served by an SCGI-capable web
189	server.</p>
190
191	<h3 id="ssh">SSH</h3>
192
193	<p>Fossil supports <tt>ssh://</tt> URLs, but there are <a
194	href="../caps/#webonly">practical limitations</a> with the default
195	behavior. You can get the full power of <a href="../caps/">Fossil's RBAC
196	system</a> over SSH <a href="any/http-over-ssh.md">with a bit of clever
197	configuration</a>.</p>
198
199	<h2 id="matrix">Activation Tutorials</h2>
200
201	<p>We've broken the configuration for each method out into a series of
202	sub-articles. Some of these are generic, while others depend on
203	particular operating systems or front-end software:</p>
204

Fossil SCM

Keyboard Shortcuts