Fossil SCM

Updated server documentation to discuss SCGI.

drh 2013-08-13 18:53 trunk

Commit ce0594c22d1eb34d95b5f43871b92594334b307d

Parent a2e7472d0fa0413…

2 files changed +150 -35 +9 -3

M www/server.wiki

+150 -35

		--- www/server.wiki
		+++ www/server.wiki
		@@ -6,119 +6,234 @@
6	6	The easiest way to set up a Fossil server is to use the <tt>server</tt> or
7	7	<tt>ui</tt> command. Assuming the repository you are interested in serving is
8	8	in the file "<tt>repo.fossil</tt>", you can use either of these commands to
9	9	start Fossil as a server:
10	10	<ul>
11		-<li><tt>fossil server repo.fossil</tt>
12		-<li><tt>fossil ui repo.fossil</tt>
	11	+<li><b>fossil server repo.fossil</b>
	12	+<li><b>fossil ui repo.fossil</b>
13	13	</ul>
14	14
15	15	<p>
16	16	Both of these commands start a Fossil server on port 8080 on the local machine,
17	17	which can be accessed with the URL: <tt>http://localhost:8080/</tt> using any
18	18	handy web browser. The difference between the two commands is that "ui", in
19	19	addition to starting the Fossil server, also starts a web browser and points it
20		-to the URL mentioned above. On the other hand, the "ui" command binds to
	20	+to the URL mentioned above, and the "ui" command binds to
21	21	the loopback IP address only (127.0.0.1) so that the "ui" command cannot be
22	22	used to serve content to a different machine.
23	23	</p>
	24	+
	25	+<p>
	26	+If one of the commands above is run from within an option checkout,
	27	+then the repository name can be omitted and the checkout is used as
	28	+the repository.
	29	+</p>
	30	+
	31	+<p>
	32	+Instead of a single repository, the commands above can specify a
	33	+directory that contains multiple Fossil repositories named with the
	34	+".fossil" suffix. In this case, the request URL should begin with
	35	+the base name of the particular repository that is desired.
	36	+</p>
	37	+
24	38	<p>
25		-NOTES:
	39	+Additional notes:
26	40	<ol>
27		-<li>The option "--port NNN" will start the server on port "NNN" instead of 8080.
	41	+<li>The option "--port NNN" will start the server on port
	42	+"NNN" instead of 8080.
28	43	<li>If port 8080 is already being used (perhaps by another Fossil server), then
29	44	Fossil will use the next available port number.
30		-<li>Starting either command from within an "open" Fossil checkout will start a
31		-server using the repository corresponding to the checkout.
32		-<li>This is an excellent option for quickly sharing with coworkers on a small network.
33		-<li>A huge advantage to this deployment scenario is that no special "root" or "administrator" access is required in order to share the repository.
	45	+<li>The "server" and "ui" commands are an excellent options
	46	+for quickly sharing with coworkers on a small network.
	47	+<li>This deployment scenario does not require special "root" or
	48	+"administrator" access in order to share the repository.
34	49	</ol>
35	50	</p>
36	51	</blockquote>
37	52
38	53	<h2>Fossil as an ''inetd'' service</h2><blockquote>
39	54	<p>
40		-Modify your <tt>/etc/inetd.conf</tt> (on Linux, modify as appropriate for your platform) so it contains a line like this:
	55	+Modify your <tt>/etc/inetd.conf</tt> (on Linux, modify as appropriate for
	56	+your platform) so it contains a line like this:
41	57	<blockquote>
42		-<tt>
	58	+<pre>
43	59	12345 stream tcp nowait.1000 root /path-to/fossil /path-to/fossil http /other-path-to/repository
44		-</tt>
	60	+</pre>
	61	+</blockquote>
	62	+In this example, you are telling "inetd" that when an incoming connection
	63	+on port "12345" happens, it should launch the binary "/path-to/fossil".
	64	+Obviously you will
	65	+need to modify the "path-to" parts as appropriate for your particular setup.
	66	+</p>
	67	+<p>
	68	+If you system is running xinetd, then a typical configuration will be
	69	+held an a separate file (often named "/etc/xinetd.d/http-alt") that might
	70	+look something like this:</p>
	71	+<blockquote>
	72	+<pre>
	73	+service http-alt
	74	+{
	75	+ port = 591
	76	+ socket_type = stream
	77	+ wait = no
	78	+ user = root
	79	+ server = /usr/bin/fossil
	80	+ server_args = http /home/fossil/repos/
	81	+}
	82	+</pre>
45	83	</blockquote>
46		-In this example, you are telling "inetd" that when an incoming connection on port "12345" happens, it should launch the binary "/path-to/fossil". Obviously you will need to modify the "path-to" parts as appropriate for your particular setup.
	84	+<p>
	85	+The xinetd example above has Fossil configured to serve multiple
	86	+repositories, contained under the "/home/fossil/repos/" directory.
	87	+All repositories should be named with a ".fossil" suffix.
	88	+In such a setup, the first element of the request URI should be the
	89	+name of the repository relative to the /home/fossil/repos/ directory
	90	+and without the ".fossil" suffix.
47	91	</p>
48	92	<p>
49		-This is a more complex setup than the "standalone" server, but it has the advantage of only using system resources when an actual connection is attempted. If no-one ever connects to that port, a Fossil server will not (automatically) run. It has the disadvantage of requiring "root" access and therefore may not normally be available to lower-priced "shared" servers on the internet.
	93	+Using inetd or xinetd is a more complex setup
	94	+than the "standalone" server, but it has the
	95	+advantage of only using system resources when an actual connection is
	96	+attempted. If no-one ever connects to that port, a Fossil server will
	97	+not (automatically) run. It has the disadvantage of requiring "root" access
	98	+and therefore may not normally be available to lower-priced "shared" servers
	99	+on the internet.
50	100	</p>
51	101	</blockquote>
52	102
53		-<h2>Fossil as a ''CGI script''</h2><blockquote>
	103	+<h2>Fossil as CGI</h2><blockquote>
54	104	<p>
55		-This is the most flexible and most likely to be widely usable of these deployment scenarios. In order for it to work, you must have the ability to install "CGI scripts" on the server you are interested in using.
	105	+This is the most flexible and most likely to be widely usable of these
	106	+deployment scenarios. In order for it to work, you must have the
	107	+ability to install "CGI scripts" on the server you are interested in using.
56	108	</p>
57	109	</blockquote>
58	110
59	111	<h3>One script per repository</h3><blockquote>
60	112	<p>
61		-Create a script (let's call it 'repo') in your CGI directory which has content like this:
62		-<blockquote><tt>
63		-#!/path-to/fossil<br>
	113	+Create a script (let's call it 'repo') in your CGI directory which has content
	114	+like this:
	115	+<blockquote><pre>
	116	+#!/path-to/fossil
64	117	repository: /path-to-repo/repository
65		-</tt></blockquote>
	118	+</pre></blockquote>
66	119	</p>
67	120	<p>
68		-It may be necessary to set permissions properly, or to modify an ".htaccess" file or other server-specific things like that. Consult with your server provider if you need that sort of assistance.
	121	+It may be necessary to set permissions properly, or to modify an ".htaccess"
	122	+file or other server-specific things like that. Consult with your server
	123	+provider if you need that sort of assistance.
69	124	</p>
70	125	<p>
71		-Once the script is set up correctly, and assuming your server is also set correctly, you should be able to access your repository with a URL like: <tt>http://mydomain.org/cgi-bin/repo</tt> (assuming the "repo" script is accessible under "cgi-bin", which would be a typical deployment on Apache for instance).
	126	+Once the script is set up correctly, and assuming your server is also set
	127	+correctly, you should be able to access your repository with a URL like:
	128	+<tt>http://mydomain.org/cgi-bin/repo</tt> (assuming the "repo" script is
	129	+accessible under "cgi-bin", which would be a typical deployment on Apache
	130	+for instance).
72	131	</p>
73	132	</blockquote>
74	133
75	134	<h3>Serving multiple repositories with one script</h3><blockquote>
76	135	<p>
77		-This scenario is almost identical to the previous one. However, here we will assume you have multiple repositories, in one directory.
	136	+This scenario is almost identical to the previous one. However, here we
	137	+will assume you have multiple repositories, in one directory.
78	138	(Call the directory 'fossils'). All repositories served, in this case, must
79	139	use the ".fossil" filename suffix.
80	140	As before, create a script (again, 'repo'):
81		-<blockquote><tt>
82		-#!/path-to/fossil<br>
83		-directory: /path-to-repo/fossils<br>
	141	+<blockquote><pre>
	142	+#!/path-to/fossil
	143	+directory: /path-to-repo/fossils
84	144	notfound: http://url-to-go-to-if-repo-not-found/
85		-</tt></blockquote>
	145	+</pre></blockquote>
	146	+</p>
	147	+<p>
	148	+Once deployed, a URL like: <tt>http://mydomain.org/cgi-bin/repo/XYZ</tt>
	149	+will serve up the repository "fossils/XYX.fossil" (if it exists). This
	150	+makes serving multiple projects on one server pretty painless.
	151	+</p>
	152	+</blockquote>
	153	+
	154	+<h2>Fossil as SCGI</h2><blockquote>
	155	+
	156	+<p>
	157	+The [/help/server\|fossil server] command, described above as a way of
	158	+starting a stand-alone web server, can be used for SCGI. Simply add
	159	+the --scgi command-line option and the stand-alone server will interpret
	160	+and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can
	161	+be used in combination with a webserver (such as Nginx) that does not
	162	+support CGI. A typical Nginx configuration to support SCGI with Fossil
	163	+would look something like this:
	164	+<blockquote><pre>
	165	+location ~ ^/demo_project/ {
	166	+ include scgi_params;
	167	+ scgi_pass localhost:9000;
	168	+ scgi_param SCRIPT_NAME "/demo_project";
	169	+}
	170	+</pre></blockquote>
	171	+<p>
	172	+Note that Fossil requires either the PATH_INFO or the SCRIPT_NAME variable
	173	+in order to function properly, but Nginx provides neither by default.
	174	+So it is necessary to provide the SCRIPT_NAME parameter in the configuration.
	175	+Failure to do this will cause Fossil to return an error.
86	176	</p>
87	177	<p>
88		-Once deployed, a URL like: <tt>http://mydomain.org/cgi-bin/repo/XYZ</tt> will serve up the repository "fossils/XYX.fossil" (if it exists). This makes serving multiple projects on one server pretty painless.
	178	+All of the features of the stand-alone server mode described above,
	179	+such as the ability to server a directory full of Fossil repositories
	180	+rather than just a single repository, work the same way in SCGI mode.
89	181	</p>
90	182	</blockquote>
91	183
92	184	<h2>Securing a repository with SSL</h2><blockquote>
93	185	<p>
94		-Using either of the CGI script approaches, it is trivial to use SSL to secure the server. Simply set up the Fossil CGI scripts etc. as above, but modify the Apache (or IIS, etc.) server to require SSL (that is, a URL with "https://") in order to access the CGI script directory. This may also be accomplished (on Apache, at least) using appropriate ".htaccess" rules.
	186	+Using either CGI or SCGI, it is trivial to use SSL to
	187	+secure the server. Simply set up the Fossil CGI scripts etc. as above,
	188	+but modify the Apache (or IIS, etc.) server to require SSL (that is, a
	189	+URL with "https://") in order to access the CGI script directory. This
	190	+may also be accomplished (on Apache, at least) using appropriate
	191	+".htaccess" rules.
95	192	</p>
96	193	<p>
97		-If you are using "inetd" to serve your repository, then you simply need to add "/usr/bin/stunnel" (perhaps on a different path, depending on your setup) before the command line to launch Fossil.
	194	+If you are using "inetd" to serve your repository, then you simply need
	195	+to add "/usr/bin/stunnel" (perhaps on a different path, depending on your
	196	+setup) before the command line to launch Fossil.
98	197	</p>
99	198	<p>
100		-At this stage, the standalone server (e.g. "fossil server") does not support SSL.
	199	+At this stage, the standalone server (e.g. "fossil server") does not
	200	+support SSL.
101	201	</p>
102	202	<p>
103	203	For more information, see <a href="./ssl.wiki">Using SSL with Fossil</a>.
104	204	</p>
105	205	</blockquote>
106	206
107	207	<h2>Various security concerns with hosted repositories</h2><blockquote>
108	208	<p>
109		-There are two main concerns relating to usage of Fossil for sharing sensitive information (source or any other data):
	209	+There are two main concerns relating to usage of Fossil for sharing
	210	+sensitive information (source or any other data):
110	211	<ul>
111		-<li>Interception of the Fossil synchronization stream, thereby capturing data, and
	212	+<li>Interception of the Fossil synchronization stream, thereby capturing
	213	+data, and
112	214	<li>Direct access to the Fossil repository on the server
113	215	</ul>
114	216	</p>
115	217	<p>
116		-Regarding the first, it is adequate to secure the server using SSL, and disallowing any non-SSL access. The data stream will be encrypted by the HTTPS protocol, rendering the data reasonably secure. The truly paranoid may wish to deploy <i>ssh</i> encrypted tunnels, but that is quite a bit more difficult and cumbersome to set up (particularly for a larger number of users).
	218	+Regarding the first, it is adequate to secure the server using SSL, and
	219	+disallowing any non-SSL access. The data stream will be encrypted by
	220	+the HTTPS protocol, rendering the data reasonably secure. The truly
	221	+paranoid may wish to deploy <i>ssh</i> encrypted tunnels, but that is
	222	+quite a bit more difficult and cumbersome to set up (particularly for
	223	+a larger number of users).
117	224	</p>
118	225	<p>
119		-As far as direct access to the repository, the same steps must be taken as for any other internet-facing data-store. Access passwords to any disk-accessing accounts should be strong (and preferably changed from time to time). However, the data in the repository itself are <i>not</i> encrypted (unless you save encrypted data yourself), and so the system administrators of your server will be able to access your data (as with any hosting service setup). The only workaround in this case is to host the server yourself, in which case you will need to allocate resources to deal with administration issues.
	226	+As far as direct access to the repository, the same steps must be taken
	227	+as for any other internet-facing data-store. Access passwords to any
	228	+disk-accessing accounts should be strong (and preferably changed from
	229	+time to time). However, the data in the repository itself are <i>not</i>
	230	+encrypted (unless you save encrypted data yourself), and so the system
	231	+administrators of your server will be able to access your data (as with
	232	+any hosting service setup). The only workaround in this case is to
	233	+host the server yourself, in which case you will need to allocate
	234	+resources to deal with administration issues.
120	235	</p>
121	236
122	237	</blockquote>
123	238
124	239	</nowiki>
125	240

	--- www/server.wiki
	+++ www/server.wiki
	@@ -6,119 +6,234 @@
6	The easiest way to set up a Fossil server is to use the <tt>server</tt> or
7	<tt>ui</tt> command. Assuming the repository you are interested in serving is
8	in the file "<tt>repo.fossil</tt>", you can use either of these commands to
9	start Fossil as a server:
10	<ul>
11	<li><tt>fossil server repo.fossil</tt>
12	<li><tt>fossil ui repo.fossil</tt>
13	</ul>
14
15	<p>
16	Both of these commands start a Fossil server on port 8080 on the local machine,
17	which can be accessed with the URL: <tt>http://localhost:8080/</tt> using any
18	handy web browser. The difference between the two commands is that "ui", in
19	addition to starting the Fossil server, also starts a web browser and points it
20	to the URL mentioned above. On the other hand, the "ui" command binds to
21	the loopback IP address only (127.0.0.1) so that the "ui" command cannot be
22	used to serve content to a different machine.
23	</p>














24	<p>
25	NOTES:
26	<ol>
27	<li>The option "--port NNN" will start the server on port "NNN" instead of 8080.

28	<li>If port 8080 is already being used (perhaps by another Fossil server), then
29	Fossil will use the next available port number.
30	<li>Starting either command from within an "open" Fossil checkout will start a
31	server using the repository corresponding to the checkout.
32	<li>This is an excellent option for quickly sharing with coworkers on a small network.
33	<li>A huge advantage to this deployment scenario is that no special "root" or "administrator" access is required in order to share the repository.
34	</ol>
35	</p>
36	</blockquote>
37
38	<h2>Fossil as an ''inetd'' service</h2><blockquote>
39	<p>
40	Modify your <tt>/etc/inetd.conf</tt> (on Linux, modify as appropriate for your platform) so it contains a line like this:

41	<blockquote>
42	<tt>
43	12345 stream tcp nowait.1000 root /path-to/fossil /path-to/fossil http /other-path-to/repository
44	</tt>






















45	</blockquote>
46	In this example, you are telling "inetd" that when an incoming connection on port "12345" happens, it should launch the binary "/path-to/fossil". Obviously you will need to modify the "path-to" parts as appropriate for your particular setup.






47	</p>
48	<p>
49	This is a more complex setup than the "standalone" server, but it has the advantage of only using system resources when an actual connection is attempted. If no-one ever connects to that port, a Fossil server will not (automatically) run. It has the disadvantage of requiring "root" access and therefore may not normally be available to lower-priced "shared" servers on the internet.






50	</p>
51	</blockquote>
52
53	<h2>Fossil as a ''CGI script''</h2><blockquote>
54	<p>
55	This is the most flexible and most likely to be widely usable of these deployment scenarios. In order for it to work, you must have the ability to install "CGI scripts" on the server you are interested in using.


56	</p>
57	</blockquote>
58
59	<h3>One script per repository</h3><blockquote>
60	<p>
61	Create a script (let's call it 'repo') in your CGI directory which has content like this:
62	<blockquote><tt>
63	#!/path-to/fossil<br>

64	repository: /path-to-repo/repository
65	</tt></blockquote>
66	</p>
67	<p>
68	It may be necessary to set permissions properly, or to modify an ".htaccess" file or other server-specific things like that. Consult with your server provider if you need that sort of assistance.


69	</p>
70	<p>
71	Once the script is set up correctly, and assuming your server is also set correctly, you should be able to access your repository with a URL like: <tt>http://mydomain.org/cgi-bin/repo</tt> (assuming the "repo" script is accessible under "cgi-bin", which would be a typical deployment on Apache for instance).




72	</p>
73	</blockquote>
74
75	<h3>Serving multiple repositories with one script</h3><blockquote>
76	<p>
77	This scenario is almost identical to the previous one. However, here we will assume you have multiple repositories, in one directory.

78	(Call the directory 'fossils'). All repositories served, in this case, must
79	use the ".fossil" filename suffix.
80	As before, create a script (again, 'repo'):
81	<blockquote><tt>
82	#!/path-to/fossil<br>
83	directory: /path-to-repo/fossils<br>
84	notfound: http://url-to-go-to-if-repo-not-found/
85	</tt></blockquote>






























86	</p>
87	<p>
88	Once deployed, a URL like: <tt>http://mydomain.org/cgi-bin/repo/XYZ</tt> will serve up the repository "fossils/XYX.fossil" (if it exists). This makes serving multiple projects on one server pretty painless.


89	</p>
90	</blockquote>
91
92	<h2>Securing a repository with SSL</h2><blockquote>
93	<p>
94	Using either of the CGI script approaches, it is trivial to use SSL to secure the server. Simply set up the Fossil CGI scripts etc. as above, but modify the Apache (or IIS, etc.) server to require SSL (that is, a URL with "https://") in order to access the CGI script directory. This may also be accomplished (on Apache, at least) using appropriate ".htaccess" rules.





95	</p>
96	<p>
97	If you are using "inetd" to serve your repository, then you simply need to add "/usr/bin/stunnel" (perhaps on a different path, depending on your setup) before the command line to launch Fossil.


98	</p>
99	<p>
100	At this stage, the standalone server (e.g. "fossil server") does not support SSL.

101	</p>
102	<p>
103	For more information, see <a href="./ssl.wiki">Using SSL with Fossil</a>.
104	</p>
105	</blockquote>
106
107	<h2>Various security concerns with hosted repositories</h2><blockquote>
108	<p>
109	There are two main concerns relating to usage of Fossil for sharing sensitive information (source or any other data):

110	<ul>
111	<li>Interception of the Fossil synchronization stream, thereby capturing data, and

112	<li>Direct access to the Fossil repository on the server
113	</ul>
114	</p>
115	<p>
116	Regarding the first, it is adequate to secure the server using SSL, and disallowing any non-SSL access. The data stream will be encrypted by the HTTPS protocol, rendering the data reasonably secure. The truly paranoid may wish to deploy <i>ssh</i> encrypted tunnels, but that is quite a bit more difficult and cumbersome to set up (particularly for a larger number of users).





117	</p>
118	<p>
119	As far as direct access to the repository, the same steps must be taken as for any other internet-facing data-store. Access passwords to any disk-accessing accounts should be strong (and preferably changed from time to time). However, the data in the repository itself are <i>not</i> encrypted (unless you save encrypted data yourself), and so the system administrators of your server will be able to access your data (as with any hosting service setup). The only workaround in this case is to host the server yourself, in which case you will need to allocate resources to deal with administration issues.








120	</p>
121
122	</blockquote>
123
124	</nowiki>
125

	--- www/server.wiki
	+++ www/server.wiki
	@@ -6,119 +6,234 @@
6	The easiest way to set up a Fossil server is to use the <tt>server</tt> or
7	<tt>ui</tt> command. Assuming the repository you are interested in serving is
8	in the file "<tt>repo.fossil</tt>", you can use either of these commands to
9	start Fossil as a server:
10	<ul>
11	<li><b>fossil server repo.fossil</b>
12	<li><b>fossil ui repo.fossil</b>
13	</ul>
14
15	<p>
16	Both of these commands start a Fossil server on port 8080 on the local machine,
17	which can be accessed with the URL: <tt>http://localhost:8080/</tt> using any
18	handy web browser. The difference between the two commands is that "ui", in
19	addition to starting the Fossil server, also starts a web browser and points it
20	to the URL mentioned above, and the "ui" command binds to
21	the loopback IP address only (127.0.0.1) so that the "ui" command cannot be
22	used to serve content to a different machine.
23	</p>
24
25	<p>
26	If one of the commands above is run from within an option checkout,
27	then the repository name can be omitted and the checkout is used as
28	the repository.
29	</p>
30
31	<p>
32	Instead of a single repository, the commands above can specify a
33	directory that contains multiple Fossil repositories named with the
34	".fossil" suffix. In this case, the request URL should begin with
35	the base name of the particular repository that is desired.
36	</p>
37
38	<p>
39	Additional notes:
40	<ol>
41	<li>The option "--port NNN" will start the server on port
42	"NNN" instead of 8080.
43	<li>If port 8080 is already being used (perhaps by another Fossil server), then
44	Fossil will use the next available port number.
45	<li>The "server" and "ui" commands are an excellent options
46	for quickly sharing with coworkers on a small network.
47	<li>This deployment scenario does not require special "root" or
48	"administrator" access in order to share the repository.
49	</ol>
50	</p>
51	</blockquote>
52
53	<h2>Fossil as an ''inetd'' service</h2><blockquote>
54	<p>
55	Modify your <tt>/etc/inetd.conf</tt> (on Linux, modify as appropriate for
56	your platform) so it contains a line like this:
57	<blockquote>
58	<pre>
59	12345 stream tcp nowait.1000 root /path-to/fossil /path-to/fossil http /other-path-to/repository
60	</pre>
61	</blockquote>
62	In this example, you are telling "inetd" that when an incoming connection
63	on port "12345" happens, it should launch the binary "/path-to/fossil".
64	Obviously you will
65	need to modify the "path-to" parts as appropriate for your particular setup.
66	</p>
67	<p>
68	If you system is running xinetd, then a typical configuration will be
69	held an a separate file (often named "/etc/xinetd.d/http-alt") that might
70	look something like this:</p>
71	<blockquote>
72	<pre>
73	service http-alt
74	{
75	port = 591
76	socket_type = stream
77	wait = no
78	user = root
79	server = /usr/bin/fossil
80	server_args = http /home/fossil/repos/
81	}
82	</pre>
83	</blockquote>
84	<p>
85	The xinetd example above has Fossil configured to serve multiple
86	repositories, contained under the "/home/fossil/repos/" directory.
87	All repositories should be named with a ".fossil" suffix.
88	In such a setup, the first element of the request URI should be the
89	name of the repository relative to the /home/fossil/repos/ directory
90	and without the ".fossil" suffix.
91	</p>
92	<p>
93	Using inetd or xinetd is a more complex setup
94	than the "standalone" server, but it has the
95	advantage of only using system resources when an actual connection is
96	attempted. If no-one ever connects to that port, a Fossil server will
97	not (automatically) run. It has the disadvantage of requiring "root" access
98	and therefore may not normally be available to lower-priced "shared" servers
99	on the internet.
100	</p>
101	</blockquote>
102
103	<h2>Fossil as CGI</h2><blockquote>
104	<p>
105	This is the most flexible and most likely to be widely usable of these
106	deployment scenarios. In order for it to work, you must have the
107	ability to install "CGI scripts" on the server you are interested in using.
108	</p>
109	</blockquote>
110
111	<h3>One script per repository</h3><blockquote>
112	<p>
113	Create a script (let's call it 'repo') in your CGI directory which has content
114	like this:
115	<blockquote><pre>
116	#!/path-to/fossil
117	repository: /path-to-repo/repository
118	</pre></blockquote>
119	</p>
120	<p>
121	It may be necessary to set permissions properly, or to modify an ".htaccess"
122	file or other server-specific things like that. Consult with your server
123	provider if you need that sort of assistance.
124	</p>
125	<p>
126	Once the script is set up correctly, and assuming your server is also set
127	correctly, you should be able to access your repository with a URL like:
128	<tt>http://mydomain.org/cgi-bin/repo</tt> (assuming the "repo" script is
129	accessible under "cgi-bin", which would be a typical deployment on Apache
130	for instance).
131	</p>
132	</blockquote>
133
134	<h3>Serving multiple repositories with one script</h3><blockquote>
135	<p>
136	This scenario is almost identical to the previous one. However, here we
137	will assume you have multiple repositories, in one directory.
138	(Call the directory 'fossils'). All repositories served, in this case, must
139	use the ".fossil" filename suffix.
140	As before, create a script (again, 'repo'):
141	<blockquote><pre>
142	#!/path-to/fossil
143	directory: /path-to-repo/fossils
144	notfound: http://url-to-go-to-if-repo-not-found/
145	</pre></blockquote>
146	</p>
147	<p>
148	Once deployed, a URL like: <tt>http://mydomain.org/cgi-bin/repo/XYZ</tt>
149	will serve up the repository "fossils/XYX.fossil" (if it exists). This
150	makes serving multiple projects on one server pretty painless.
151	</p>
152	</blockquote>
153
154	<h2>Fossil as SCGI</h2><blockquote>
155
156	<p>
157	The [/help/server\|fossil server] command, described above as a way of
158	starting a stand-alone web server, can be used for SCGI. Simply add
159	the --scgi command-line option and the stand-alone server will interpret
160	and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can
161	be used in combination with a webserver (such as Nginx) that does not
162	support CGI. A typical Nginx configuration to support SCGI with Fossil
163	would look something like this:
164	<blockquote><pre>
165	location ~ ^/demo_project/ {
166	include scgi_params;
167	scgi_pass localhost:9000;
168	scgi_param SCRIPT_NAME "/demo_project";
169	}
170	</pre></blockquote>
171	<p>
172	Note that Fossil requires either the PATH_INFO or the SCRIPT_NAME variable
173	in order to function properly, but Nginx provides neither by default.
174	So it is necessary to provide the SCRIPT_NAME parameter in the configuration.
175	Failure to do this will cause Fossil to return an error.
176	</p>
177	<p>
178	All of the features of the stand-alone server mode described above,
179	such as the ability to server a directory full of Fossil repositories
180	rather than just a single repository, work the same way in SCGI mode.
181	</p>
182	</blockquote>
183
184	<h2>Securing a repository with SSL</h2><blockquote>
185	<p>
186	Using either CGI or SCGI, it is trivial to use SSL to
187	secure the server. Simply set up the Fossil CGI scripts etc. as above,
188	but modify the Apache (or IIS, etc.) server to require SSL (that is, a
189	URL with "https://") in order to access the CGI script directory. This
190	may also be accomplished (on Apache, at least) using appropriate
191	".htaccess" rules.
192	</p>
193	<p>
194	If you are using "inetd" to serve your repository, then you simply need
195	to add "/usr/bin/stunnel" (perhaps on a different path, depending on your
196	setup) before the command line to launch Fossil.
197	</p>
198	<p>
199	At this stage, the standalone server (e.g. "fossil server") does not
200	support SSL.
201	</p>
202	<p>
203	For more information, see <a href="./ssl.wiki">Using SSL with Fossil</a>.
204	</p>
205	</blockquote>
206
207	<h2>Various security concerns with hosted repositories</h2><blockquote>
208	<p>
209	There are two main concerns relating to usage of Fossil for sharing
210	sensitive information (source or any other data):
211	<ul>
212	<li>Interception of the Fossil synchronization stream, thereby capturing
213	data, and
214	<li>Direct access to the Fossil repository on the server
215	</ul>
216	</p>
217	<p>
218	Regarding the first, it is adequate to secure the server using SSL, and
219	disallowing any non-SSL access. The data stream will be encrypted by
220	the HTTPS protocol, rendering the data reasonably secure. The truly
221	paranoid may wish to deploy <i>ssh</i> encrypted tunnels, but that is
222	quite a bit more difficult and cumbersome to set up (particularly for
223	a larger number of users).
224	</p>
225	<p>
226	As far as direct access to the repository, the same steps must be taken
227	as for any other internet-facing data-store. Access passwords to any
228	disk-accessing accounts should be strong (and preferably changed from
229	time to time). However, the data in the repository itself are <i>not</i>
230	encrypted (unless you save encrypted data yourself), and so the system
231	administrators of your server will be able to access your data (as with
232	any hosting service setup). The only workaround in this case is to
233	host the server yourself, in which case you will need to allocate
234	resources to deal with administration issues.
235	</p>
236
237	</blockquote>
238
239	</nowiki>
240

M www/webui.wiki

+9 -3

		--- www/webui.wiki
		+++ www/webui.wiki
		@@ -67,11 +67,12 @@
67	67	URL. So there is never any fumbling around trying to find an open
68	68	port or to type arcane strings into your browser URL entry box.
69	69	The interface just pops right up, ready to run.
70	70
71	71	The Fossil web interface is also very easy to setup and run on a
72		-network server, as either a CGI program or from inetd. Details on how
	72	+network server, as either a CGI program or from inetd, or as an
	73	+SCGI server. Details on how
73	74	to do that are described further below.
74	75
75	76	<h2>Things To Do Using The Web Interface</h2>
76	77
77	78	You can view <b>timelines</b> of changes to the project. The default
		@@ -135,11 +136,12 @@
135	136	<h2>Installing On A Network Server</h2>
136	137
137	138	When you create a new Fossil project and after you have configured it
138	139	like you want it using the web interface, you can make the project
139	140	available to a distributed team by simply copying the single
140		-repository file up to a web server that supports CGI. Just put the
	141	+repository file up to a web server that supports CGI or SCGI. To
	142	+run Fossil as CGI, just put the
141	143	<b>sample-project.fossil</b> file in a directory where CGI scripts
142	144	have both read and write permission on the file and the directory that
143	145	contains the file, then add a CGI script that looks something like this:
144	146
145	147	<verbatim>
		@@ -151,11 +153,15 @@
151	153	of course, and also make sure the Fossil binary is installed on the server.
152	154	But that is <u>all</u> you have to do. You now have everything you need to host
153	155	a distributed software development project in less than five minutes using a
154	156	two-line CGI script.
155	157
156		-You don't have a CGI-capable web server running on your server machine?
	158	+Instructions for setting up an SCGI server are
	159	+[./scgi.wiki \| available separately].
	160	+
	161	+You don't have a CGI- or SCGI-capable web server running on your
	162	+server machine?
157	163	Not a problem. The Fossil interface can also be launched via inetd or
158	164	xinetd. An inetd configuration line sufficient to launch the Fossil
159	165	web interface looks like this:
160	166
161	167	<verbatim>
162	168

	--- www/webui.wiki
	+++ www/webui.wiki
	@@ -67,11 +67,12 @@
67	URL. So there is never any fumbling around trying to find an open
68	port or to type arcane strings into your browser URL entry box.
69	The interface just pops right up, ready to run.
70
71	The Fossil web interface is also very easy to setup and run on a
72	network server, as either a CGI program or from inetd. Details on how

73	to do that are described further below.
74
75	<h2>Things To Do Using The Web Interface</h2>
76
77	You can view <b>timelines</b> of changes to the project. The default
	@@ -135,11 +136,12 @@
135	<h2>Installing On A Network Server</h2>
136
137	When you create a new Fossil project and after you have configured it
138	like you want it using the web interface, you can make the project
139	available to a distributed team by simply copying the single
140	repository file up to a web server that supports CGI. Just put the

141	<b>sample-project.fossil</b> file in a directory where CGI scripts
142	have both read and write permission on the file and the directory that
143	contains the file, then add a CGI script that looks something like this:
144
145	<verbatim>
	@@ -151,11 +153,15 @@
151	of course, and also make sure the Fossil binary is installed on the server.
152	But that is <u>all</u> you have to do. You now have everything you need to host
153	a distributed software development project in less than five minutes using a
154	two-line CGI script.
155
156	You don't have a CGI-capable web server running on your server machine?




157	Not a problem. The Fossil interface can also be launched via inetd or
158	xinetd. An inetd configuration line sufficient to launch the Fossil
159	web interface looks like this:
160
161	<verbatim>
162

	--- www/webui.wiki
	+++ www/webui.wiki
	@@ -67,11 +67,12 @@
67	URL. So there is never any fumbling around trying to find an open
68	port or to type arcane strings into your browser URL entry box.
69	The interface just pops right up, ready to run.
70
71	The Fossil web interface is also very easy to setup and run on a
72	network server, as either a CGI program or from inetd, or as an
73	SCGI server. Details on how
74	to do that are described further below.
75
76	<h2>Things To Do Using The Web Interface</h2>
77
78	You can view <b>timelines</b> of changes to the project. The default
	@@ -135,11 +136,12 @@
136	<h2>Installing On A Network Server</h2>
137
138	When you create a new Fossil project and after you have configured it
139	like you want it using the web interface, you can make the project
140	available to a distributed team by simply copying the single
141	repository file up to a web server that supports CGI or SCGI. To
142	run Fossil as CGI, just put the
143	<b>sample-project.fossil</b> file in a directory where CGI scripts
144	have both read and write permission on the file and the directory that
145	contains the file, then add a CGI script that looks something like this:
146
147	<verbatim>
	@@ -151,11 +153,15 @@
153	of course, and also make sure the Fossil binary is installed on the server.
154	But that is <u>all</u> you have to do. You now have everything you need to host
155	a distributed software development project in less than five minutes using a
156	two-line CGI script.
157
158	Instructions for setting up an SCGI server are
159	[./scgi.wiki \| available separately].
160
161	You don't have a CGI- or SCGI-capable web server running on your
162	server machine?
163	Not a problem. The Fossil interface can also be launched via inetd or
164	xinetd. An inetd configuration line sufficient to launch the Fossil
165	web interface looks like this:
166
167	<verbatim>
168

Fossil SCM

Keyboard Shortcuts