f146e21af9e… — Fossil SCM

M www/aboutcgi.wiki

+1 -1

		--- www/aboutcgi.wiki
		+++ www/aboutcgi.wiki
		@@ -2,11 +2,11 @@
2	2	<h2>Introduction</h2><blockquote>
3	3	<p>CGI or "Common Gateway Interface" is a venerable yet reliable technique for
4	4	generating dynamic web content. This article gives a quick background on how
5	5	CGI works and describes how Fossil can act as a CGI service.
6	6	<p>This is a "how it works" guide. If you just want to set up Fossil
7		-as a CGI server, see the [./server.wiki \| Fossil Server Setup] page.
	7	+as a CGI server, see the [./server/ \| Fossil Server Setup] page.
8	8	</blockquote>
9	9	<h2>A Quick Review Of CGI</h2><blockquote>
10	10	<p>
11	11	An HTTP request is a block of text that is sent by a client application
12	12	(usually a web browser) and arrives at the web server over a network
13	13

	--- www/aboutcgi.wiki
	+++ www/aboutcgi.wiki
	@@ -2,11 +2,11 @@
2	<h2>Introduction</h2><blockquote>
3	<p>CGI or "Common Gateway Interface" is a venerable yet reliable technique for
4	generating dynamic web content. This article gives a quick background on how
5	CGI works and describes how Fossil can act as a CGI service.
6	<p>This is a "how it works" guide. If you just want to set up Fossil
7	as a CGI server, see the [./server.wiki \| Fossil Server Setup] page.
8	</blockquote>
9	<h2>A Quick Review Of CGI</h2><blockquote>
10	<p>
11	An HTTP request is a block of text that is sent by a client application
12	(usually a web browser) and arrives at the web server over a network
13

	--- www/aboutcgi.wiki
	+++ www/aboutcgi.wiki
	@@ -2,11 +2,11 @@
2	<h2>Introduction</h2><blockquote>
3	<p>CGI or "Common Gateway Interface" is a venerable yet reliable technique for
4	generating dynamic web content. This article gives a quick background on how
5	CGI works and describes how Fossil can act as a CGI service.
6	<p>This is a "how it works" guide. If you just want to set up Fossil
7	as a CGI server, see the [./server/ \| Fossil Server Setup] page.
8	</blockquote>
9	<h2>A Quick Review Of CGI</h2><blockquote>
10	<p>
11	An HTTP request is a block of text that is sent by a client application
12	(usually a web browser) and arrives at the web server over a network
13

M www/alerts.md

+1 -1

		--- www/alerts.md
		+++ www/alerts.md
		@@ -12,11 +12,11 @@
12	12	* Announcements
13	13
14	14	Subscribers can elect to receive emails as soon as these events happen,
15	15	or they can receive a daily digest of the events instead.
16	16
17		-Email alerts are sent by a [Fossil server](./server.wiki), which must be
	17	+Email alerts are sent by a [Fossil server](./server/), which must be
18	18	[set up](#quick) by the Fossil administrator to send email.
19	19
20	20	Email alerts do not currently work if you are only using Fossil from the
21	21	command line.
22	22
23	23

	--- www/alerts.md
	+++ www/alerts.md
	@@ -12,11 +12,11 @@
12	* Announcements
13
14	Subscribers can elect to receive emails as soon as these events happen,
15	or they can receive a daily digest of the events instead.
16
17	Email alerts are sent by a [Fossil server](./server.wiki), which must be
18	[set up](#quick) by the Fossil administrator to send email.
19
20	Email alerts do not currently work if you are only using Fossil from the
21	command line.
22
23

	--- www/alerts.md
	+++ www/alerts.md
	@@ -12,11 +12,11 @@
12	* Announcements
13
14	Subscribers can elect to receive emails as soon as these events happen,
15	or they can receive a daily digest of the events instead.
16
17	Email alerts are sent by a [Fossil server](./server/), which must be
18	[set up](#quick) by the Fossil administrator to send email.
19
20	Email alerts do not currently work if you are only using Fossil from the
21	command line.
22
23

M www/antibot.wiki

+1 -1

		--- www/antibot.wiki
		+++ www/antibot.wiki
		@@ -130,11 +130,11 @@
130	130
131	131	These two sub-settings can be used separately or together. If used together,
132	132	then the delay timer does not start until after the first mouse movement
133	133	is detected.
134	134
135		-See also [./server.wiki#loadmgmt\|Managing Server Load] for a description
	135	+See also [./loadmgmt.md\|Managing Server Load] for a description
136	136	of how expensive pages can be disabled when the server is under heavy
137	137	load.
138	138
139	139	<h2>The ongoing struggle</h2>
140	140
141	141

	--- www/antibot.wiki
	+++ www/antibot.wiki
	@@ -130,11 +130,11 @@
130
131	These two sub-settings can be used separately or together. If used together,
132	then the delay timer does not start until after the first mouse movement
133	is detected.
134
135	See also [./server.wiki#loadmgmt\|Managing Server Load] for a description
136	of how expensive pages can be disabled when the server is under heavy
137	load.
138
139	<h2>The ongoing struggle</h2>
140
141

	--- www/antibot.wiki
	+++ www/antibot.wiki
	@@ -130,11 +130,11 @@
130
131	These two sub-settings can be used separately or together. If used together,
132	then the delay timer does not start until after the first mouse movement
133	is detected.
134
135	See also [./loadmgmt.md\|Managing Server Load] for a description
136	of how expensive pages can be disabled when the server is under heavy
137	load.
138
139	<h2>The ongoing struggle</h2>
140
141

M www/backoffice.md

+3 -3

		--- www/backoffice.md
		+++ www/backoffice.md
		@@ -9,11 +9,11 @@
9	9
10	10	What Is The Backoffice
11	11	----------------------
12	12
13	13	The backoffice is a mechanism used by a
14		-[Fossil server](/doc/trunk/www/server.wiki) to do low-priority
	14	+[Fossil server](./server/) to do low-priority
15	15	background work that is not directly related to the user interface. Here
16	16	are some examples of the kinds of work that backoffice performs:
17	17
18	18	1. Sending email alerts and notifications
19	19	2. Sending out daily digests of email notifications
		@@ -39,12 +39,12 @@
39	39	server for "[fossil sync](/help?cmd=sync)" and
40	40	[fossil clone](/help?cmd=clone)" commands which are implemented as
41	41	web requests - albeit requests that the human user never sees.
42	42	Web requests can arrive at the Fossil server via direct TCP/IP (for example
43	43	when Fossil is started using commands like "[fossil server](/help?cmd=server)")
44		-or via [CGI](/doc/trunk/www/server.wiki) or
45		-[SCGI](/doc/trunk/www/scgi.wiki) or via SSH.
	44	+or via [CGI](./server/any/cgi.md) or
	45	+[SCGI](./server/any/scgi.md) or via SSH.
46	46	A backoffice process might be started regardless of the origin of the
47	47	request.
48	48
49	49	The backoffice is not a daemon. Each backoffice process runs for a short
50	50	while and then exits. This helps keep Fossil easy to manage, since there
51	51

	--- www/backoffice.md
	+++ www/backoffice.md
	@@ -9,11 +9,11 @@
9
10	What Is The Backoffice
11	----------------------
12
13	The backoffice is a mechanism used by a
14	[Fossil server](/doc/trunk/www/server.wiki) to do low-priority
15	background work that is not directly related to the user interface. Here
16	are some examples of the kinds of work that backoffice performs:
17
18	1. Sending email alerts and notifications
19	2. Sending out daily digests of email notifications
	@@ -39,12 +39,12 @@
39	server for "[fossil sync](/help?cmd=sync)" and
40	[fossil clone](/help?cmd=clone)" commands which are implemented as
41	web requests - albeit requests that the human user never sees.
42	Web requests can arrive at the Fossil server via direct TCP/IP (for example
43	when Fossil is started using commands like "[fossil server](/help?cmd=server)")
44	or via [CGI](/doc/trunk/www/server.wiki) or
45	[SCGI](/doc/trunk/www/scgi.wiki) or via SSH.
46	A backoffice process might be started regardless of the origin of the
47	request.
48
49	The backoffice is not a daemon. Each backoffice process runs for a short
50	while and then exits. This helps keep Fossil easy to manage, since there
51

	--- www/backoffice.md
	+++ www/backoffice.md
	@@ -9,11 +9,11 @@
9
10	What Is The Backoffice
11	----------------------
12
13	The backoffice is a mechanism used by a
14	[Fossil server](./server/) to do low-priority
15	background work that is not directly related to the user interface. Here
16	are some examples of the kinds of work that backoffice performs:
17
18	1. Sending email alerts and notifications
19	2. Sending out daily digests of email notifications
	@@ -39,12 +39,12 @@
39	server for "[fossil sync](/help?cmd=sync)" and
40	[fossil clone](/help?cmd=clone)" commands which are implemented as
41	web requests - albeit requests that the human user never sees.
42	Web requests can arrive at the Fossil server via direct TCP/IP (for example
43	when Fossil is started using commands like "[fossil server](/help?cmd=server)")
44	or via [CGI](./server/any/cgi.md) or
45	[SCGI](./server/any/scgi.md) or via SSH.
46	A backoffice process might be started regardless of the origin of the
47	request.
48
49	The backoffice is not a daemon. Each backoffice process runs for a short
50	while and then exits. This helps keep Fossil easy to manage, since there
51

M www/cgi.wiki

+3 -3

		--- www/cgi.wiki
		+++ www/cgi.wiki
		@@ -7,13 +7,13 @@
7	7	a common point of rendezvous for syncing, and by providing a web-based
8	8	portal where developers and non-developers alike can learn about the
9	9	project and its current state.
10	10
11	11	Setting up a server using Fossil is easy.
12		-A [./server.wiki\|separate document] talks about four different methods for
13		-setting up a Fossil server. One of those methods, and perhaps the most
14		-popular is [./server.wiki#cgi\|CGI]. CGI is the technique that the three
	12	+A [./server/\|separate document] talks about all of the many different methods for
	13	+setting up a Fossil server, one of which is [./server/any/cgi.md \| as a CGI
	14	+script]. CGI is the technique that the three
15	15	[./selfhost.wiki\|self-hosting Fossil repositories] all use.
16	16
17	17	Setting up a Fossil server using CGI is mostly about writing a short
18	18	script (usually just 2 lines line) in the cgi-bin folder of an ordinary
19	19	web-browser. But there are a lot of extra options that can be added
20	20

	--- www/cgi.wiki
	+++ www/cgi.wiki
	@@ -7,13 +7,13 @@
7	a common point of rendezvous for syncing, and by providing a web-based
8	portal where developers and non-developers alike can learn about the
9	project and its current state.
10
11	Setting up a server using Fossil is easy.
12	A [./server.wiki\|separate document] talks about four different methods for
13	setting up a Fossil server. One of those methods, and perhaps the most
14	popular is [./server.wiki#cgi\|CGI]. CGI is the technique that the three
15	[./selfhost.wiki\|self-hosting Fossil repositories] all use.
16
17	Setting up a Fossil server using CGI is mostly about writing a short
18	script (usually just 2 lines line) in the cgi-bin folder of an ordinary
19	web-browser. But there are a lot of extra options that can be added
20

	--- www/cgi.wiki
	+++ www/cgi.wiki
	@@ -7,13 +7,13 @@
7	a common point of rendezvous for syncing, and by providing a web-based
8	portal where developers and non-developers alike can learn about the
9	project and its current state.
10
11	Setting up a server using Fossil is easy.
12	A [./server/\|separate document] talks about all of the many different methods for
13	setting up a Fossil server, one of which is [./server/any/cgi.md \| as a CGI
14	script]. CGI is the technique that the three
15	[./selfhost.wiki\|self-hosting Fossil repositories] all use.
16
17	Setting up a Fossil server using CGI is mostly about writing a short
18	script (usually just 2 lines line) in the cgi-bin folder of an ordinary
19	web-browser. But there are a lot of extra options that can be added
20

M www/changes.wiki

+1 -1

		--- www/changes.wiki
		+++ www/changes.wiki
		@@ -13,11 +13,11 @@
13	13	* Add support for fenced code blocks and improved hyperlink
14	14	processing to the [/md_rules\|markdown formatter].
15	15	* Enhance the [/help?cmd=/stat\|/stat] page so that it gives the
16	16	option to show a breakdown of forum posts.
17	17	* Change the default [./hashpolicy.wiki\|hash policy] to SHA3.
18		- * Timeout [./server.wiki#cgi\|CGI requests] after 300 seconds, or
	18	+ * Timeout [./server/any/cgi.md\|CGI requests] after 300 seconds, or
19	19	some other value set by the
20	20	[./cgi.wiki#timeout\|"timeout:" property] in the CGI script.
21	21	* Documentation improvements
22	22
23	23	<a name='v2_9'></a>
24	24
25	25	ADDED www/chroot.md

	--- www/changes.wiki
	+++ www/changes.wiki
	@@ -13,11 +13,11 @@
13	* Add support for fenced code blocks and improved hyperlink
14	processing to the [/md_rules\|markdown formatter].
15	* Enhance the [/help?cmd=/stat\|/stat] page so that it gives the
16	option to show a breakdown of forum posts.
17	* Change the default [./hashpolicy.wiki\|hash policy] to SHA3.
18	* Timeout [./server.wiki#cgi\|CGI requests] after 300 seconds, or
19	some other value set by the
20	[./cgi.wiki#timeout\|"timeout:" property] in the CGI script.
21	* Documentation improvements
22
23	<a name='v2_9'></a>
24
25	DDED www/chroot.md

	--- www/changes.wiki
	+++ www/changes.wiki
	@@ -13,11 +13,11 @@
13	* Add support for fenced code blocks and improved hyperlink
14	processing to the [/md_rules\|markdown formatter].
15	* Enhance the [/help?cmd=/stat\|/stat] page so that it gives the
16	option to show a breakdown of forum posts.
17	* Change the default [./hashpolicy.wiki\|hash policy] to SHA3.
18	* Timeout [./server/any/cgi.md\|CGI requests] after 300 seconds, or
19	some other value set by the
20	[./cgi.wiki#timeout\|"timeout:" property] in the CGI script.
21	* Documentation improvements
22
23	<a name='v2_9'></a>
24
25	DDED www/chroot.md

M www/chroot.md

+38

		--- a/www/chroot.md
		+++ b/www/chroot.md
		@@ -0,0 +1,38 @@
	1	+# The Server Chroot Jail
	2	+
	3	+If you run Fossil as root in any mode that [serves data on the
	4	+network][srv], and you're running it on Unix or a compatible OS, Fossil
	5	+will drop itself into a [`chroot(2)` jail][cj, once it's done everything that requires root access. Most commonly,
	6	+you run Fossil as root to allow it to bind to TCP port 80 for HTTP
	7	+service, since normal users are reup on OSes.
	8	+
	9	+Fossil uses the owner of the Fossil repository file as its new user
	10	+ID when it drops root privileges.
	11	+
	12	+When Fossil enters a chroot jail, it needs to have all of its dependencies
	13	+inside the chroot jail in order to continue work. There are several
	14	+resources that need to be inside the chroot jail with Fossil in order for
	15	+Fossil to work correctly:
	16	+
	17	+* the repository file(s)
	18	+
	19	+* `/dev/null` — create it with `mknod(8)` inside the jail directory
	20	+ ([Linux example][mnl], [OpenBSD example][obsd])
	21	+
	22	+* `/d `/proc` — you might need to mount this virtual filesystem inside the
	23	+ jail on Linux systems that make use of [Fossil’s server load
	24	+ shedding feature][fls]
	25	+
	26	+* any shared libraries your `fossil` binary is linked to, unless you
	27	+ [configured Fossil with `--static`][bld] to avoid it
	28	+
	29	+Fossil does all of this as one of many layers of defense against
	30	+hacks and exploits. You can prevent Fossil from entering the chroot
	31	+jail using the <tt>--nojail</tt> option to the
	32	+[fossil server command](/help?cmd=server)
	33	+but you cannot make Fossil hold onto root privileges. Fossiwww.fossil-scm.org/fossil. Fossil always drops
	34	+root privilege before accepting inputs, for security.
	35	+
	36	+
	37	+[bld]: https://fossil-scm.org/home/doc/trunk/www/build.wiki
	38	+[cj]: https://en.wikipeht

	--- a/www/chroot.md
	+++ b/www/chroot.md
	@@ -0,0 +1,38 @@

	--- a/www/chroot.md
	+++ b/www/chroot.md
	@@ -0,0 +1,38 @@
1	# The Server Chroot Jail
2
3	If you run Fossil as root in any mode that [serves data on the
4	network][srv], and you're running it on Unix or a compatible OS, Fossil
5	will drop itself into a [`chroot(2)` jail][cj, once it's done everything that requires root access. Most commonly,
6	you run Fossil as root to allow it to bind to TCP port 80 for HTTP
7	service, since normal users are reup on OSes.
8
9	Fossil uses the owner of the Fossil repository file as its new user
10	ID when it drops root privileges.
11
12	When Fossil enters a chroot jail, it needs to have all of its dependencies
13	inside the chroot jail in order to continue work. There are several
14	resources that need to be inside the chroot jail with Fossil in order for
15	Fossil to work correctly:
16
17	* the repository file(s)
18
19	* `/dev/null` — create it with `mknod(8)` inside the jail directory
20	([Linux example][mnl], [OpenBSD example][obsd])
21
22	* `/d `/proc` — you might need to mount this virtual filesystem inside the
23	jail on Linux systems that make use of [Fossil’s server load
24	shedding feature][fls]
25
26	* any shared libraries your `fossil` binary is linked to, unless you
27	[configured Fossil with `--static`][bld] to avoid it
28
29	Fossil does all of this as one of many layers of defense against
30	hacks and exploits. You can prevent Fossil from entering the chroot
31	jail using the <tt>--nojail</tt> option to the
32	[fossil server command](/help?cmd=server)
33	but you cannot make Fossil hold onto root privileges. Fossiwww.fossil-scm.org/fossil. Fossil always drops
34	root privilege before accepting inputs, for security.
35
36
37	[bld]: https://fossil-scm.org/home/doc/trunk/www/build.wiki
38	[cj]: https://en.wikipeht

M www/concepts.wiki

+1 -1

		--- www/concepts.wiki
		+++ www/concepts.wiki
		@@ -423,11 +423,11 @@
423	423	<li><p><b>Inetd or Stunnel.</b>
424	424	Configure programs like inetd, xinetd, or stunnel to hand off HTTP requests
425	425	directly to the [/help?cmd=http\|fossil http] command.
426	426	</ol>
427	427
428		-See the [./server.wiki \| How To Configure A Fossil Server] document
	428	+See the [./server/ \| How To Configure A Fossil Server] document
429	429	for details.
430	430
431	431	<h2>6.0 Review Of Key Concepts</h2>
432	432
433	433	<ul>
434	434

	--- www/concepts.wiki
	+++ www/concepts.wiki
	@@ -423,11 +423,11 @@
423	<li><p><b>Inetd or Stunnel.</b>
424	Configure programs like inetd, xinetd, or stunnel to hand off HTTP requests
425	directly to the [/help?cmd=http\|fossil http] command.
426	</ol>
427
428	See the [./server.wiki \| How To Configure A Fossil Server] document
429	for details.
430
431	<h2>6.0 Review Of Key Concepts</h2>
432
433	<ul>
434

	--- www/concepts.wiki
	+++ www/concepts.wiki
	@@ -423,11 +423,11 @@
423	<li><p><b>Inetd or Stunnel.</b>
424	Configure programs like inetd, xinetd, or stunnel to hand off HTTP requests
425	directly to the [/help?cmd=http\|fossil http] command.
426	</ol>
427
428	See the [./server/ \| How To Configure A Fossil Server] document
429	for details.
430
431	<h2>6.0 Review Of Key Concepts</h2>
432
433	<ul>
434

M www/defcsp.md

+1 -1

		--- www/defcsp.md
		+++ www/defcsp.md
		@@ -30,11 +30,11 @@
30	30	* versioned content retrieved via a [`/raw`](/help?cmd=/raw) URL
31	31	* [unversioned content](./unvers.wiki) retrieved
32	32	via a [`/uv`](/help?cmd=/uv) URL
33	33
34	34	Another path around this restriction is to [serve your
35		-repo](./server.wiki) behind an HTTP proxy server, allowing mixed-mode
	35	+repo](./server/) behind an HTTP proxy server, allowing mixed-mode
36	36	content serving, with static images and such served directly by the HTTP
37	37	server and the dynamic content by Fossil. That allows a URI scheme that
38	38	prevents the browser’s CSP enforcement from distinguishing content from
39	39	Fossil proper and that from the front-end proxy.
40	40
41	41

	--- www/defcsp.md
	+++ www/defcsp.md
	@@ -30,11 +30,11 @@
30	* versioned content retrieved via a [`/raw`](/help?cmd=/raw) URL
31	* [unversioned content](./unvers.wiki) retrieved
32	via a [`/uv`](/help?cmd=/uv) URL
33
34	Another path around this restriction is to [serve your
35	repo](./server.wiki) behind an HTTP proxy server, allowing mixed-mode
36	content serving, with static images and such served directly by the HTTP
37	server and the dynamic content by Fossil. That allows a URI scheme that
38	prevents the browser’s CSP enforcement from distinguishing content from
39	Fossil proper and that from the front-end proxy.
40
41

	--- www/defcsp.md
	+++ www/defcsp.md
	@@ -30,11 +30,11 @@
30	* versioned content retrieved via a [`/raw`](/help?cmd=/raw) URL
31	* [unversioned content](./unvers.wiki) retrieved
32	via a [`/uv`](/help?cmd=/uv) URL
33
34	Another path around this restriction is to [serve your
35	repo](./server/) behind an HTTP proxy server, allowing mixed-mode
36	content serving, with static images and such served directly by the HTTP
37	server and the dynamic content by Fossil. That allows a URI scheme that
38	prevents the browser’s CSP enforcement from distinguishing content from
39	Fossil proper and that from the front-end proxy.
40
41

M www/embeddeddoc.wiki

+37 -2

		--- www/embeddeddoc.wiki
		+++ www/embeddeddoc.wiki
		@@ -103,10 +103,45 @@
103	103	[https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP \| Content
104	104	Security Policy] error in your browser with the default CSP as served by
105	105	Fossil. See the documentation on [./customskin.md#headfoot \| Header and
106	106	Footer Processing] and [./defcsp.md \| The Default CSP].
107	107
	108	+
	109	+<h2>Server-Side Text Substitution</h2>
	110	+
	111	+Fossil can do a few types of substitution of server-side information
	112	+into the embedded document.
	113	+
	114	+<h3>1. $ROOT</h3>
	115	+
	116	+To allow for repositories [./server/ \| served deeper than the root of the
	117	+URL hierarchy], Fossil can substitute the repository's root in the URL
	118	+scheme into HTML <tt>href</tt> and <tt>action</tt> attributes. For
	119	+example:
	120	+
	121	+<nowiki><pre>
	122	+ [$ROOT/doc.wiki \| doc at project root]
	123	+</pre></nowiki>
	124	+
	125	+might become this in the rendered HTML:
	126	+
	127	+<nowiki><pre>
	128	+ <a href="/project/root/doc.wiki">doc at project root</a>
	129	+</pre></nowiki>
	130	+
	131	+As you can see, this happens for all source document types that end up
	132	+rendering as HTML, not just source documents in the HTML
	133	+<tt>fossil-doc</tt> format described at the end of the prior section.
	134	+
	135	+
	136	+<h3>2. TH1 Documents</h3>
	137	+
	138	+Fossil will substitute the value of [./th1.md \| TH1 expressions] within
	139	+<tt>{</tt> curly braces <tt>}</tt> into the output HTML if you have
	140	+configured it with the <tt>--with-th1-docs</tt> option, which is
	141	+disabled by default.
	142	+
108	143
109	144	<h2>Examples</h2>
110	145
111	146	This file that you are currently reading is an example of
112	147	embedded documentation. The name of this file in the fossil
		@@ -127,12 +162,12 @@
127	162	<blockquote><pre>
128	163	#!/usr/bin/fossil
129	164	repository: /fossil/fossil.fossil
130	165	</pre></blockquote>
131	166
132		-This is one of four ways to set up a
133		-<a href="./server.wiki">fossil web server</a>.
	167	+This is one of the many ways to set up a
	168	+<a href="./server/">Fossil server</a>.
134	169
135	170	The "<b>/trunk/</b>" part of the URL tells fossil to use
136	171	the documentation files from the most recent trunk check-in.
137	172	If you wanted to see an historical version of this document,
138	173	you could substitute the name of a check-in for "<b>/trunk/</b>".
139	174

	--- www/embeddeddoc.wiki
	+++ www/embeddeddoc.wiki
	@@ -103,10 +103,45 @@
103	[https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP \| Content
104	Security Policy] error in your browser with the default CSP as served by
105	Fossil. See the documentation on [./customskin.md#headfoot \| Header and
106	Footer Processing] and [./defcsp.md \| The Default CSP].
107



































108
109	<h2>Examples</h2>
110
111	This file that you are currently reading is an example of
112	embedded documentation. The name of this file in the fossil
	@@ -127,12 +162,12 @@
127	<blockquote><pre>
128	#!/usr/bin/fossil
129	repository: /fossil/fossil.fossil
130	</pre></blockquote>
131
132	This is one of four ways to set up a
133	<a href="./server.wiki">fossil web server</a>.
134
135	The "<b>/trunk/</b>" part of the URL tells fossil to use
136	the documentation files from the most recent trunk check-in.
137	If you wanted to see an historical version of this document,
138	you could substitute the name of a check-in for "<b>/trunk/</b>".
139

	--- www/embeddeddoc.wiki
	+++ www/embeddeddoc.wiki
	@@ -103,10 +103,45 @@
103	[https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP \| Content
104	Security Policy] error in your browser with the default CSP as served by
105	Fossil. See the documentation on [./customskin.md#headfoot \| Header and
106	Footer Processing] and [./defcsp.md \| The Default CSP].
107
108
109	<h2>Server-Side Text Substitution</h2>
110
111	Fossil can do a few types of substitution of server-side information
112	into the embedded document.
113
114	<h3>1. $ROOT</h3>
115
116	To allow for repositories [./server/ \| served deeper than the root of the
117	URL hierarchy], Fossil can substitute the repository's root in the URL
118	scheme into HTML <tt>href</tt> and <tt>action</tt> attributes. For
119	example:
120
121	<nowiki><pre>
122	[$ROOT/doc.wiki \| doc at project root]
123	</pre></nowiki>
124
125	might become this in the rendered HTML:
126
127	<nowiki><pre>
128	<a href="/project/root/doc.wiki">doc at project root</a>
129	</pre></nowiki>
130
131	As you can see, this happens for all source document types that end up
132	rendering as HTML, not just source documents in the HTML
133	<tt>fossil-doc</tt> format described at the end of the prior section.
134
135
136	<h3>2. TH1 Documents</h3>
137
138	Fossil will substitute the value of [./th1.md \| TH1 expressions] within
139	<tt>{</tt> curly braces <tt>}</tt> into the output HTML if you have
140	configured it with the <tt>--with-th1-docs</tt> option, which is
141	disabled by default.
142
143
144	<h2>Examples</h2>
145
146	This file that you are currently reading is an example of
147	embedded documentation. The name of this file in the fossil
	@@ -127,12 +162,12 @@
162	<blockquote><pre>
163	#!/usr/bin/fossil
164	repository: /fossil/fossil.fossil
165	</pre></blockquote>
166
167	This is one of the many ways to set up a
168	<a href="./server/">Fossil server</a>.
169
170	The "<b>/trunk/</b>" part of the URL tells fossil to use
171	the documentation files from the most recent trunk check-in.
172	If you wanted to see an historical version of this document,
173	you could substitute the name of a check-in for "<b>/trunk/</b>".
174

M www/env-opts.md

+1 -1

		--- www/env-opts.md
		+++ www/env-opts.md
		@@ -432,11 +432,11 @@
432	432	can be selected with either the `--vfs VFSNAME` option or the
433	433	`FOSSIL_VFS` environment variable. The `--vfs` option takes
434	434	precedence.
435	435
436	436
437		-### Temporary File Location
	437	+### <a name="temp"></a>Temporary File Location
438	438
439	439	Fossil places some temporary files in the checkout directory. Most notably,
440	440	supporting files related to merge conflicts are placed in the same
441	441	folder as the merge result.
442	442
443	443

	--- www/env-opts.md
	+++ www/env-opts.md
	@@ -432,11 +432,11 @@
432	can be selected with either the `--vfs VFSNAME` option or the
433	`FOSSIL_VFS` environment variable. The `--vfs` option takes
434	precedence.
435
436
437	### Temporary File Location
438
439	Fossil places some temporary files in the checkout directory. Most notably,
440	supporting files related to merge conflicts are placed in the same
441	folder as the merge result.
442
443

	--- www/env-opts.md
	+++ www/env-opts.md
	@@ -432,11 +432,11 @@
432	can be selected with either the `--vfs VFSNAME` option or the
433	`FOSSIL_VFS` environment variable. The `--vfs` option takes
434	precedence.
435
436
437	### <a name="temp"></a>Temporary File Location
438
439	Fossil places some temporary files in the checkout directory. Most notably,
440	supporting files related to merge conflicts are placed in the same
441	folder as the merge result.
442
443

M www/fossil-v-git.wiki

+1 -1

		--- www/fossil-v-git.wiki
		+++ www/fossil-v-git.wiki
		@@ -75,11 +75,11 @@
75	75	the design. One way to describe Fossil is that it is
76	76	"[https://github.com/ \| GitHub]-in-a-box."
77	77
78	78	For developers who choose to self-host projects (rather than using a
79	79	3rd-party service such as GitHub) Fossil is much easier to set up, since
80		-the stand-alone Fossil executable together with a [./server.wiki#cgi\|2-line CGI script]
	80	+the stand-alone Fossil executable together with a [./server/any/cgi.md\|2-line CGI script]
81	81	suffice to instantiate a full-featured developer website. To accomplish
82	82	the same using Git requires locating, installing, configuring, integrating,
83	83	and managing a wide assortment of separate tools. Standing up a developer
84	84	website using Fossil can be done in minutes, whereas doing the same using
85	85	Git requires hours or days.
86	86

	--- www/fossil-v-git.wiki
	+++ www/fossil-v-git.wiki
	@@ -75,11 +75,11 @@
75	the design. One way to describe Fossil is that it is
76	"[https://github.com/ \| GitHub]-in-a-box."
77
78	For developers who choose to self-host projects (rather than using a
79	3rd-party service such as GitHub) Fossil is much easier to set up, since
80	the stand-alone Fossil executable together with a [./server.wiki#cgi\|2-line CGI script]
81	suffice to instantiate a full-featured developer website. To accomplish
82	the same using Git requires locating, installing, configuring, integrating,
83	and managing a wide assortment of separate tools. Standing up a developer
84	website using Fossil can be done in minutes, whereas doing the same using
85	Git requires hours or days.
86

	--- www/fossil-v-git.wiki
	+++ www/fossil-v-git.wiki
	@@ -75,11 +75,11 @@
75	the design. One way to describe Fossil is that it is
76	"[https://github.com/ \| GitHub]-in-a-box."
77
78	For developers who choose to self-host projects (rather than using a
79	3rd-party service such as GitHub) Fossil is much easier to set up, since
80	the stand-alone Fossil executable together with a [./server/any/cgi.md\|2-line CGI script]
81	suffice to instantiate a full-featured developer website. To accomplish
82	the same using Git requires locating, installing, configuring, integrating,
83	and managing a wide assortment of separate tools. Standing up a developer
84	website using Fossil can be done in minutes, whereas doing the same using
85	Git requires hours or days.
86

M www/index.wiki

+5 -4

		--- www/index.wiki
		+++ www/index.wiki
		@@ -61,13 +61,14 @@
61	61	The protocol is
62	62	[./stats.wiki \| bandwidth efficient] to the point that Fossil can be
63	63	used comfortably over dial-up or over the exceedingly slow Wifi on
64	64	airliners.
65	65
66		- 5. <b>CGI/SCGI Enabled</b> - No server is required, but if you want to
67		- set one up, Fossil supports four easy [./server.wiki \| server configurations].
68		- You can also easily set up your server to automatically
	66	+ 5. <b>Simple Server Setup</b> - No server is required, but if you want to
	67	+ set one up, Fossil supports [./server/ \| several different server
	68	+ configurations] including CGI, SCGI, and direct HTTP.
	69	+ You can also easily set up your Fossil repository to automatically
69	70	[./mirrortogithub.md \| mirror content on GitHub].
70	71
71	72	6. <b>Autosync</b> -
72	73	Fossil supports [./concepts.wiki#workflow \| "autosync" mode]
73	74	which helps to keep projects moving
		@@ -128,11 +129,11 @@
128	129	its key functionality to TH1 scripts.
129	130	* List of [./th1-hooks.md \| TH1 hooks exposed by Fossil] that enable
130	131	customization of commands and web pages.
131	132	* A free hosting server for Fossil repositories is available at
132	133	[http://chiselapp.com/].
133		- * How to [./server.wiki \| set up a server] for your repository.
	134	+ * How to [./server/ \| set up a server] for your repository.
134	135	* Customizing the [./custom_ticket.wiki \| ticket system].
135	136	* Methods to [./checkin_names.wiki \| identify a specific check-in].
136	137	* [./inout.wiki \| Import and export] from and to Git.
137	138	* [./fossil-v-git.wiki \| Fossil versus Git].
138	139	* [./fiveminutes.wiki \| Up and running in 5 minutes as a single user]
139	140
140	141	ADDED www/loadmgmt.md

	--- www/index.wiki
	+++ www/index.wiki
	@@ -61,13 +61,14 @@
61	The protocol is
62	[./stats.wiki \| bandwidth efficient] to the point that Fossil can be
63	used comfortably over dial-up or over the exceedingly slow Wifi on
64	airliners.
65
66	5. <b>CGI/SCGI Enabled</b> - No server is required, but if you want to
67	set one up, Fossil supports four easy [./server.wiki \| server configurations].
68	You can also easily set up your server to automatically

69	[./mirrortogithub.md \| mirror content on GitHub].
70
71	6. <b>Autosync</b> -
72	Fossil supports [./concepts.wiki#workflow \| "autosync" mode]
73	which helps to keep projects moving
	@@ -128,11 +129,11 @@
128	its key functionality to TH1 scripts.
129	* List of [./th1-hooks.md \| TH1 hooks exposed by Fossil] that enable
130	customization of commands and web pages.
131	* A free hosting server for Fossil repositories is available at
132	[http://chiselapp.com/].
133	* How to [./server.wiki \| set up a server] for your repository.
134	* Customizing the [./custom_ticket.wiki \| ticket system].
135	* Methods to [./checkin_names.wiki \| identify a specific check-in].
136	* [./inout.wiki \| Import and export] from and to Git.
137	* [./fossil-v-git.wiki \| Fossil versus Git].
138	* [./fiveminutes.wiki \| Up and running in 5 minutes as a single user]
139
140	DDED www/loadmgmt.md

	--- www/index.wiki
	+++ www/index.wiki
	@@ -61,13 +61,14 @@
61	The protocol is
62	[./stats.wiki \| bandwidth efficient] to the point that Fossil can be
63	used comfortably over dial-up or over the exceedingly slow Wifi on
64	airliners.
65
66	5. <b>Simple Server Setup</b> - No server is required, but if you want to
67	set one up, Fossil supports [./server/ \| several different server
68	configurations] including CGI, SCGI, and direct HTTP.
69	You can also easily set up your Fossil repository to automatically
70	[./mirrortogithub.md \| mirror content on GitHub].
71
72	6. <b>Autosync</b> -
73	Fossil supports [./concepts.wiki#workflow \| "autosync" mode]
74	which helps to keep projects moving
	@@ -128,11 +129,11 @@
129	its key functionality to TH1 scripts.
130	* List of [./th1-hooks.md \| TH1 hooks exposed by Fossil] that enable
131	customization of commands and web pages.
132	* A free hosting server for Fossil repositories is available at
133	[http://chiselapp.com/].
134	* How to [./server/ \| set up a server] for your repository.
135	* Customizing the [./custom_ticket.wiki \| ticket system].
136	* Methods to [./checkin_names.wiki \| identify a specific check-in].
137	* [./inout.wiki \| Import and export] from and to Git.
138	* [./fossil-v-git.wiki \| Fossil versus Git].
139	* [./fiveminutes.wiki \| Up and running in 5 minutes as a single user]
140
141	DDED www/loadmgmt.md

M www/loadmgmt.md

+2

		--- a/www/loadmgmt.md
		+++ b/www/loadmgmt.md
		@@ -0,0 +1,2 @@
	1	+
	2	+

	--- a/www/loadmgmt.md
	+++ b/www/loadmgmt.md
	@@ -0,0 +1,2 @@

	--- a/www/loadmgmt.md
	+++ b/www/loadmgmt.md
	@@ -0,0 +1,2 @@
1
2

M www/mkindex.tcl

+1 -1

		--- www/mkindex.tcl
		+++ www/mkindex.tcl
		@@ -70,11 +70,11 @@
70	70	{Quotes: What People Are Saying About Fossil, Git, and DVCSes in General}
71	71	../test/release-checklist.wiki {Pre-Release Testing Checklist}
72	72	reviews.wiki {Reviews}
73	73	selfcheck.wiki {Fossil Repository Integrity Self Checks}
74	74	selfhost.wiki {Fossil Self Hosting Repositories}
75		- server.wiki {How To Configure A Fossil Server}
	75	+ server/ {How To Configure A Fossil Server}
76	76	serverext.wiki {CGI Server Extensions}
77	77	serverext.wiki {Adding Extensions To A Fossil Server Using CGI Scripts}
78	78	settings.wiki {Fossil Settings}
79	79	/sitemap {Site Map}
80	80	shunning.wiki {Shunning: Deleting Content From Fossil}
81	81

	--- www/mkindex.tcl
	+++ www/mkindex.tcl
	@@ -70,11 +70,11 @@
70	{Quotes: What People Are Saying About Fossil, Git, and DVCSes in General}
71	../test/release-checklist.wiki {Pre-Release Testing Checklist}
72	reviews.wiki {Reviews}
73	selfcheck.wiki {Fossil Repository Integrity Self Checks}
74	selfhost.wiki {Fossil Self Hosting Repositories}
75	server.wiki {How To Configure A Fossil Server}
76	serverext.wiki {CGI Server Extensions}
77	serverext.wiki {Adding Extensions To A Fossil Server Using CGI Scripts}
78	settings.wiki {Fossil Settings}
79	/sitemap {Site Map}
80	shunning.wiki {Shunning: Deleting Content From Fossil}
81

	--- www/mkindex.tcl
	+++ www/mkindex.tcl
	@@ -70,11 +70,11 @@
70	{Quotes: What People Are Saying About Fossil, Git, and DVCSes in General}
71	../test/release-checklist.wiki {Pre-Release Testing Checklist}
72	reviews.wiki {Reviews}
73	selfcheck.wiki {Fossil Repository Integrity Self Checks}
74	selfhost.wiki {Fossil Self Hosting Repositories}
75	server/ {How To Configure A Fossil Server}
76	serverext.wiki {CGI Server Extensions}
77	serverext.wiki {Adding Extensions To A Fossil Server Using CGI Scripts}
78	settings.wiki {Fossil Settings}
79	/sitemap {Site Map}
80	shunning.wiki {Shunning: Deleting Content From Fossil}
81

M www/permutedindex.html

+3 -3

		--- www/permutedindex.html
		+++ www/permutedindex.html
		@@ -63,11 +63,11 @@
63	63	<li><a href="style.wiki">Code Style Guidelines — Source</a></li>
64	64	<li><a href="../../../help">Commands and Webpages — Lists of</a></li>
65	65	<li><a href="build.wiki"><b>Compiling and Installing Fossil</b></a></li>
66	66	<li><a href="concepts.wiki">Concepts — Fossil Core</a></li>
67	67	<li><a href="cgi.wiki">Configuration Options — CGI Script</a></li>
68		-<li><a href="server.wiki">Configure A Fossil Server — How To</a></li>
	68	+<li><a href="server/">Configure A Fossil Server — How To</a></li>
69	69	<li><a href="shunning.wiki">Content From Fossil — Shunning: Deleting</a></li>
70	70	<li><a href="defcsp.md">Content Security Policy — The Default</a></li>
71	71	<li><a href="contribute.wiki"><b>Contributing Code or Documentation To The Fossil Project</b></a></li>
72	72	<li><a href="copyright-release.html"><b>Contributor License Agreement</b></a></li>
73	73	<li><a href="whyusefossil.wiki">Control — Benefits Of Version</a></li>
		@@ -152,11 +152,11 @@
152	152	<li><a href="hints.wiki">Hints — Fossil Tips And Usage</a></li>
153	153	<li><a href="index.wiki"><b>Home Page</b></a></li>
154	154	<li><a href="selfhost.wiki">Hosting Repositories — Fossil Self</a></li>
155	155	<li><a href="aboutcgi.wiki"><b>How CGI Works In Fossil</b></a></li>
156	156	<li><a href="aboutdownload.wiki"><b>How The Download Page Works</b></a></li>
157		-<li><a href="server.wiki"><b>How To Configure A Fossil Server</b></a></li>
	157	+<li><a href="server/"><b>How To Configure A Fossil Server</b></a></li>
158	158	<li><a href="newrepo.wiki"><b>How To Create A New Fossil Repository</b></a></li>
159	159	<li><a href="mirrortogithub.md"><b>How To Mirror A Fossil Repository On GitHub</b></a></li>
160	160	<li><a href="encryptedrepos.wiki"><b>How To Use Encrypted Repositories</b></a></li>
161	161	<li><a href="hacker-howto.wiki">How-To — Hacker</a></li>
162	162	<li><a href="tls-nginx.md">HTTPS with nginx — Proxying Fossil via</a></li>
		@@ -232,11 +232,11 @@
232	232	<li><a href="th1.md">Scripting Language — The TH1</a></li>
233	233	<li><a href="serverext.wiki">Scripts — Adding Extensions To A Fossil Server Using CGI</a></li>
234	234	<li><a href="defcsp.md">Security Policy — The Default Content</a></li>
235	235	<li><a href="selfcheck.wiki">Self Checks — Fossil Repository Integrity</a></li>
236	236	<li><a href="selfhost.wiki">Self Hosting Repositories — Fossil</a></li>
237		-<li><a href="server.wiki">Server — How To Configure A Fossil</a></li>
	237	+<li><a href="server/">Server — How To Configure A Fossil</a></li>
238	238	<li><a href="serverext.wiki">Server Extensions — CGI</a></li>
239	239	<li><a href="serverext.wiki">Server Using CGI Scripts — Adding Extensions To A Fossil</a></li>
240	240	<li><a href="settings.wiki">Settings — Fossil</a></li>
241	241	<li><a href="admin-v-setup.md">Setup and Admin User Capabilities — The Differences Between the</a></li>
242	242	<li><a href="hashpolicy.wiki">SHA1 and SHA3-256 — Hash Policy: Choosing Between</a></li>
243	243

	--- www/permutedindex.html
	+++ www/permutedindex.html
	@@ -63,11 +63,11 @@
63	<li><a href="style.wiki">Code Style Guidelines — Source</a></li>
64	<li><a href="../../../help">Commands and Webpages — Lists of</a></li>
65	<li><a href="build.wiki"><b>Compiling and Installing Fossil</b></a></li>
66	<li><a href="concepts.wiki">Concepts — Fossil Core</a></li>
67	<li><a href="cgi.wiki">Configuration Options — CGI Script</a></li>
68	<li><a href="server.wiki">Configure A Fossil Server — How To</a></li>
69	<li><a href="shunning.wiki">Content From Fossil — Shunning: Deleting</a></li>
70	<li><a href="defcsp.md">Content Security Policy — The Default</a></li>
71	<li><a href="contribute.wiki"><b>Contributing Code or Documentation To The Fossil Project</b></a></li>
72	<li><a href="copyright-release.html"><b>Contributor License Agreement</b></a></li>
73	<li><a href="whyusefossil.wiki">Control — Benefits Of Version</a></li>
	@@ -152,11 +152,11 @@
152	<li><a href="hints.wiki">Hints — Fossil Tips And Usage</a></li>
153	<li><a href="index.wiki"><b>Home Page</b></a></li>
154	<li><a href="selfhost.wiki">Hosting Repositories — Fossil Self</a></li>
155	<li><a href="aboutcgi.wiki"><b>How CGI Works In Fossil</b></a></li>
156	<li><a href="aboutdownload.wiki"><b>How The Download Page Works</b></a></li>
157	<li><a href="server.wiki"><b>How To Configure A Fossil Server</b></a></li>
158	<li><a href="newrepo.wiki"><b>How To Create A New Fossil Repository</b></a></li>
159	<li><a href="mirrortogithub.md"><b>How To Mirror A Fossil Repository On GitHub</b></a></li>
160	<li><a href="encryptedrepos.wiki"><b>How To Use Encrypted Repositories</b></a></li>
161	<li><a href="hacker-howto.wiki">How-To — Hacker</a></li>
162	<li><a href="tls-nginx.md">HTTPS with nginx — Proxying Fossil via</a></li>
	@@ -232,11 +232,11 @@
232	<li><a href="th1.md">Scripting Language — The TH1</a></li>
233	<li><a href="serverext.wiki">Scripts — Adding Extensions To A Fossil Server Using CGI</a></li>
234	<li><a href="defcsp.md">Security Policy — The Default Content</a></li>
235	<li><a href="selfcheck.wiki">Self Checks — Fossil Repository Integrity</a></li>
236	<li><a href="selfhost.wiki">Self Hosting Repositories — Fossil</a></li>
237	<li><a href="server.wiki">Server — How To Configure A Fossil</a></li>
238	<li><a href="serverext.wiki">Server Extensions — CGI</a></li>
239	<li><a href="serverext.wiki">Server Using CGI Scripts — Adding Extensions To A Fossil</a></li>
240	<li><a href="settings.wiki">Settings — Fossil</a></li>
241	<li><a href="admin-v-setup.md">Setup and Admin User Capabilities — The Differences Between the</a></li>
242	<li><a href="hashpolicy.wiki">SHA1 and SHA3-256 — Hash Policy: Choosing Between</a></li>
243

	--- www/permutedindex.html
	+++ www/permutedindex.html
	@@ -63,11 +63,11 @@
63	<li><a href="style.wiki">Code Style Guidelines — Source</a></li>
64	<li><a href="../../../help">Commands and Webpages — Lists of</a></li>
65	<li><a href="build.wiki"><b>Compiling and Installing Fossil</b></a></li>
66	<li><a href="concepts.wiki">Concepts — Fossil Core</a></li>
67	<li><a href="cgi.wiki">Configuration Options — CGI Script</a></li>
68	<li><a href="server/">Configure A Fossil Server — How To</a></li>
69	<li><a href="shunning.wiki">Content From Fossil — Shunning: Deleting</a></li>
70	<li><a href="defcsp.md">Content Security Policy — The Default</a></li>
71	<li><a href="contribute.wiki"><b>Contributing Code or Documentation To The Fossil Project</b></a></li>
72	<li><a href="copyright-release.html"><b>Contributor License Agreement</b></a></li>
73	<li><a href="whyusefossil.wiki">Control — Benefits Of Version</a></li>
	@@ -152,11 +152,11 @@
152	<li><a href="hints.wiki">Hints — Fossil Tips And Usage</a></li>
153	<li><a href="index.wiki"><b>Home Page</b></a></li>
154	<li><a href="selfhost.wiki">Hosting Repositories — Fossil Self</a></li>
155	<li><a href="aboutcgi.wiki"><b>How CGI Works In Fossil</b></a></li>
156	<li><a href="aboutdownload.wiki"><b>How The Download Page Works</b></a></li>
157	<li><a href="server/"><b>How To Configure A Fossil Server</b></a></li>
158	<li><a href="newrepo.wiki"><b>How To Create A New Fossil Repository</b></a></li>
159	<li><a href="mirrortogithub.md"><b>How To Mirror A Fossil Repository On GitHub</b></a></li>
160	<li><a href="encryptedrepos.wiki"><b>How To Use Encrypted Repositories</b></a></li>
161	<li><a href="hacker-howto.wiki">How-To — Hacker</a></li>
162	<li><a href="tls-nginx.md">HTTPS with nginx — Proxying Fossil via</a></li>
	@@ -232,11 +232,11 @@
232	<li><a href="th1.md">Scripting Language — The TH1</a></li>
233	<li><a href="serverext.wiki">Scripts — Adding Extensions To A Fossil Server Using CGI</a></li>
234	<li><a href="defcsp.md">Security Policy — The Default Content</a></li>
235	<li><a href="selfcheck.wiki">Self Checks — Fossil Repository Integrity</a></li>
236	<li><a href="selfhost.wiki">Self Hosting Repositories — Fossil</a></li>
237	<li><a href="server/">Server — How To Configure A Fossil</a></li>
238	<li><a href="serverext.wiki">Server Extensions — CGI</a></li>
239	<li><a href="serverext.wiki">Server Using CGI Scripts — Adding Extensions To A Fossil</a></li>
240	<li><a href="settings.wiki">Settings — Fossil</a></li>
241	<li><a href="admin-v-setup.md">Setup and Admin User Capabilities — The Differences Between the</a></li>
242	<li><a href="hashpolicy.wiki">SHA1 and SHA3-256 — Hash Policy: Choosing Between</a></li>
243

M www/quickstart.wiki

+4 -3

		--- www/quickstart.wiki
		+++ www/quickstart.wiki
		@@ -338,13 +338,14 @@
338	338	server. For cross-machine collaboration, use the <b>server</b> command,
339	339	which binds on all IP addresses and does not try to start a web browser.</p>
340	340
341	341	<p>Servers are also easily configured as:
342	342	<ul>
343		- <li>[./server.wiki#inetd\|inetd/xinetd]
344		- <li>[./server.wiki#cgi\|CGI]
345		- <li>[./server.wiki#scgi\|SCGI]
	343	+ <li>[./server/any/inetd.md\|inetd]
	344	+ <li>[./server/debian/service.md\|systemd]
	345	+ <li>[./server/any/cgi.md\|CGI]
	346	+ <li>[./server/any/scgi.md\|SCGI]
346	347	</ul>
347	348
348	349	<p>The [./selfhost.wiki \| self-hosting fossil repositories] use
349	350	CGI.
350	351
351	352
352	353	DELETED www/server.wiki
353	354	ADDED www/server/any/althttpd.md
354	355	ADDED www/server/any/cgi.md
355	356	ADDED www/server/any/inetd.md
356	357	ADDED www/server/any/none.md
357	358	ADDED www/server/any/scgi.md
358	359	ADDED www/server/any/stunnel.md
359	360	ADDED www/server/any/xinetd.md
360	361	ADDED www/server/debian/nginx.md
361	362	ADDED www/server/debian/service.md
362	363	ADDED www/server/index.html
363	364	ADDED www/server/macos/service.md
364	365	ADDED www/server/whyuseaserver.wiki
365	366	ADDED www/server/windows/cgi-bin-perm.png
366	367	ADDED www/server/windows/cgi-exec-perm.png
367	368	ADDED www/server/windows/cgi-install-iis.png
368	369	ADDED www/server/windows/cgi-script-map.png
369	370	ADDED www/server/windows/cgi.md
370	371	ADDED www/server/windows/iis.md
371	372	ADDED www/server/windows/index.md
372	373	ADDED www/server/windows/none.md
373	374	ADDED www/server/windows/service.md
374	375	ADDED www/server/windows/stunnel.md

	--- www/quickstart.wiki
	+++ www/quickstart.wiki
	@@ -338,13 +338,14 @@
338	server. For cross-machine collaboration, use the <b>server</b> command,
339	which binds on all IP addresses and does not try to start a web browser.</p>
340
341	<p>Servers are also easily configured as:
342	<ul>
343	<li>[./server.wiki#inetd\|inetd/xinetd]
344	<li>[./server.wiki#cgi\|CGI]
345	<li>[./server.wiki#scgi\|SCGI]

346	</ul>
347
348	<p>The [./selfhost.wiki \| self-hosting fossil repositories] use
349	CGI.
350
351
352	ELETED www/server.wiki
353	DDED www/server/any/althttpd.md
354	DDED www/server/any/cgi.md
355	DDED www/server/any/inetd.md
356	DDED www/server/any/none.md
357	DDED www/server/any/scgi.md
358	DDED www/server/any/stunnel.md
359	DDED www/server/any/xinetd.md
360	DDED www/server/debian/nginx.md
361	DDED www/server/debian/service.md
362	DDED www/server/index.html
363	DDED www/server/macos/service.md
364	DDED www/server/whyuseaserver.wiki
365	DDED www/server/windows/cgi-bin-perm.png
366	DDED www/server/windows/cgi-exec-perm.png
367	DDED www/server/windows/cgi-install-iis.png
368	DDED www/server/windows/cgi-script-map.png
369	DDED www/server/windows/cgi.md
370	DDED www/server/windows/iis.md
371	DDED www/server/windows/index.md
372	DDED www/server/windows/none.md
373	DDED www/server/windows/service.md
374	DDED www/server/windows/stunnel.md

	--- www/quickstart.wiki
	+++ www/quickstart.wiki
	@@ -338,13 +338,14 @@
338	server. For cross-machine collaboration, use the <b>server</b> command,
339	which binds on all IP addresses and does not try to start a web browser.</p>
340
341	<p>Servers are also easily configured as:
342	<ul>
343	<li>[./server/any/inetd.md\|inetd]
344	<li>[./server/debian/service.md\|systemd]
345	<li>[./server/any/cgi.md\|CGI]
346	<li>[./server/any/scgi.md\|SCGI]
347	</ul>
348
349	<p>The [./selfhost.wiki \| self-hosting fossil repositories] use
350	CGI.
351
352
353	ELETED www/server.wiki
354	DDED www/server/any/althttpd.md
355	DDED www/server/any/cgi.md
356	DDED www/server/any/inetd.md
357	DDED www/server/any/none.md
358	DDED www/server/any/scgi.md
359	DDED www/server/any/stunnel.md
360	DDED www/server/any/xinetd.md
361	DDED www/server/debian/nginx.md
362	DDED www/server/debian/service.md
363	DDED www/server/index.html
364	DDED www/server/macos/service.md
365	DDED www/server/whyuseaserver.wiki
366	DDED www/server/windows/cgi-bin-perm.png
367	DDED www/server/windows/cgi-exec-perm.png
368	DDED www/server/windows/cgi-install-iis.png
369	DDED www/server/windows/cgi-script-map.png
370	DDED www/server/windows/cgi.md
371	DDED www/server/windows/iis.md
372	DDED www/server/windows/index.md
373	DDED www/server/windows/none.md
374	DDED www/server/windows/service.md
375	DDED www/server/windows/stunnel.md

D www/server.wiki

-291

		--- a/www/server.wiki
		+++ b/www/server.wiki
		@@ -1,291 +0,0 @@
1		-<title>her post-activation steps includher poster post-activation steps is incl:</p>
2		-
3		-<ol>
4		-<li>
5		-Add addieam members have approp.</l].
6		-
7		-by to aData sharing and synchronization can be entirely peer-to-peer.
8		-Fossil uses [https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type\|conflict-free replicated data types]
9		-to ensure that (in the limit) all participating peers see the exact same content.nding in
10		-"<tt>>
11		-sh2>But, A Server Can Be Useful is incl:</p>
12		-
13		-<ol>l>
14		-<li>
15		-Add addnot require a server,
16		-but a server does make collaboration easier.
17		-A Fossil server also works well as a complete website for acompletOverviewMethods is incl:</p>
18		-
19		-<ol>
20		-listener approachactivation: inetd, xinetdA stand-alone server
21		- <li>Using inetd, xinetd, or stunnel
22		- <li>CGI
23		- <li>SCGI (a.k.a. Simp [ \| a separate article].nding in
24		-"<tt>>
25		-
26		-<h2 id="inetd">Serving via inetd is incl:</p>
27		-
28		-<ol>
29		- See [hat all teYou can als \| this article].nding in
30		-"<tt>>
31		-
32		-<h2 id="sl.wiki#stunneleading,
33		-is just a Fossil server displaying the content of the
34		-=> with a also migrate fro
35		- ia-title="Howt This is the easiest wn also migrate fro
36		- ia-title="Howt This is the easieng in
37		-"<tt>>
38		-
39		-<h2 id="inetd">Serving via inetd is incl:</p>
40		-
41		-<ol>
42		- See [hat all teYou can als \| this article].nding in
43		-"<tt>>
44		-
45		-<h2 id="cgi">Serving via CGI is incl:</p>
46		-
47		-<ol>
48		- See [ \| this article].nding in
49		-"<tt>>
50		-
51		-<h2 id="scgi">Serving via SCGI is incl:</p>
52		-
53		-<ol>
54		- See [on standard output w \| this article].nding in
55		-"<tt>>
56		-debian/nginxtext-align:style="text-align: Windows.org/] website, in, or a directory hierarchy
57		-ving via inetd is incl:</p>
58		-
59		-<ol>
60		-serverT is to use either the
61		-[/help/server\|server] or the [/help/ui\|ui] commands:
62		-
63		-<ul>
64		- <li><b>fossil server</b> <i>REPOSITORY</i>
65		- <li><b>fossil ui</b> <i>REPOSITORY</i>
66		-</ul>
67		-
68		-The <i>REPOSITORY</i> argument is either the name of the repository file, or
69		-a directorerving via inetd is incl:</p>
70		-
71		-named <tt>*.fossil</tt>.
72		-Both of these commands start a Fossil server, usually on TCP port 8080, though
73		-a higher numbered port might also be used if 8080 is already occupied. You can
74		-access these using URLs of the form <b>http://localhost:8080/</b>, or if
75		-<i>REPOSITORY</i> is a directory, URLs of the form
76		-<b>http://localhost:8080/</b><i>repo</i><b>/</b> where <i>repo</i> is the base
77		-name of the repository file wkey differences between "ui" and "server":
78		-
79		-<ul>
80		- <li>"ui" always binds the server to the loopback IP address
81		- (127.0.0.1) so that it cannot serve to other machines.
82		- <li>anyone who visits this URL is treated as the all-powerful Setup
83		- user, which is why the first difference exists.
84		- <li>"ui" launches a local web browser pointed at this URL.
85		-</ul>
86		-
87		-You can omit the <i>REPOSITORY</i> argument if you run one of the above
88		-commands from within a Fossil checkout directorE@1II,Av:<pre>
89		-$ fossil ui # or...
90		-$ fossil serve
91		-</pre></blockquote>
92		-
93		-Note that you can abbreviate Fossil sub-commands, as long as they are
94		-unambiguous. "<tt>server</tt>" can currently be as short as
95		-"<tt>ser</tt>".
96		-
97		-As a more complicated example, you can serve a directory containing
98		-multiple <tt>*.fossil</tt> files like so:
99		-
100		-<blockquote><pre>
101		-$ fossil server --port 9000 --repolist /path/to/repo/dir
102		-</pre></blockquote>
103		-
104		-There is an [/file/tools/fslsrv \| example script] in the Fossil
105		-distribution that wraps <tt>fossil server</tt> to produce more
106		-complicated effects. Feel free to take it, study it, and modify it to
107		-suit your local needs.
108		-
109		-See the [/help/server\|online documentation] for moreK@G0,p:options and arguments you can give to these commandsH@6G,m:
110		-<h2 id="inetd">Fossil as an inetd/xinetd serviceK@1vl,Ez:
111		-A Fossil server can be launched on-demand by inetd or xinetd using
112		-the [/help/http\|fossil http] command. To launch Fossil from inetd, modify
113		-your inetd configuration file (typically "/etc/inetd.conf") to contain a
114		-line something like this:
115		-
116		-<blockquote>
117		-<pre>
118		-80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil
119		-</pre>
120		-</blockquote>
121		-
122		-In this example, you are telling "inetd" that when an incoming connection
123		-appears on TCP port "80", that it should launch the binary "/usr/bin/fossil"
124		-program with the arguments shown.
125		-Obviously you will
126		-need to modify the pathnames for your particular setup.
127		-The final argument is either the name of the fossil repository to be served,
128		-or a directory containing multiple repositories.
129		-
130		-
131		-If you use a non-standard TCP port on
132		-systems where the port-specification must be a symbolic name and cannot be
133		-numeric, add the desired name and port to /etc/services. For example, if
134		-you wanL@1Yk,OL:running on TCP port 12345 instead of 80, you
135		-will need to add:
136		-
137		-<blockquote>
138		-<pre>
139		-fossil 12345/tcp #fossil server
140		-</pre>
141		-</blockquote>
142		-
143		-and use the symbolic name ('fossil' in this example) instead of the numeral ('12345')
144		-in inetd.conf. For details, see the relevant section in your system's documentation, e.g.
145		-the [https://www.freebsd.org/doc/en/books/handbook/network-inetd.html\|FreeBSD Handbook] in
146		-case you use FreeBSD.
147		-
148		-If your system is running xinetd, then the configuration is likely to be
149		-in the file "/etc/xinetd.conf" or in a subfile of "/etc/xinetd.d".
150		-An xinetd configuration file will appear like this:
151		-
152		-<blockquote>
153		-<pre>
154		-service http
155		-{
156		- port = 80
157		- socket_type = stream
158		- wait = no
159		- user = root
160		- server = /usr/bin/fossil
161		- server_args = http /home/fossil/repos/
162		-}
163		-</pre>
164		-</blockquote>
165		-
166		-The xinetd example above has Fossil configured to serve multiple
167		-repositories, contained under the "/home/fossil/repos/" directory.
168		-
169		-In both cases notice that Fossil was launched as root. This is not required,
170		-but if it is done, then Fossil will automatically put itself into a chroot
171		-jail for the user who owns the fossil repository before reading any information
172		-off of the wire.
173		-
174		-Inetd or xinetd must be enabled, and must be (re)started whenever their configuration
175		-changes - consult your system's documentation for details.
176		-
177		-Using inetd or xinetd is a more complex setup
178		-than the "standalone" server, but it has the
179		-advantage of only using system resources when an actual connection is
180		-attempted. If no-one ever connects to that port,H@BF,4W:will
181		-not (automatically) run. It has the disadvantage of requiring "root" access
182		-and therefore may not normally be available to lower-priced "shared" servers
183		-on the Internet.
184		-
185		-The configuration for <tt>stunnel</tt> is similar, but it is covered in
186		-[./ssl.wiki#stunnel\|a separate document]K@6G,N: id="cgi">Fossil as CGIK@1vl,2d:
187		-A Fossil server can also be run from an ordinary web server as a CGI program.
188		-This feature allows Fossil to be seamlessly integrated into a larger website.
189		-CGI is how K@2nS,H: \| self-hosting fJ@2n~,eb: are
190		-implemented.
191		-
192		-To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory
193		-of your web server and having content like this:
194		-
195		-<blockquote><pre>
196		-#!/usr/bin/fossil
197		-repository: /home/fossil/repo.fossil
198		-</pre></blockquote>
199		-
200		-As always, adjust your paths appropriately.
201		-It may be necessary to set permissions properly, or to modify an ".htaccess"
202		-file or make other server-specific changes. Consult the documentation
203		-for your particular web server. In particular, the following permissions are
204		-<em>normally</em> required (but, again, may be different for a particular
205		-configuration):
206		-
207		-<ul>
208		- <li>The Fossil binary (/usr/bin/fossil in the example above)
209		- must be readable/executable, and ALL directories leading up to it
210		- must be readable by the process which executes the CGI.</li>
211		- <li>ALL directories leading to the CGI script must also be readable and the CGI
212		- script itself must be executable for the user under which it will run (which often differs
213		- from the one running the web server - consult your site's documentation or administrator).</li>
214		- <li>The repository file AND the directory containing it must be writable by the same account
215		- which executes the Fossil binary (again, this might differ from the WWW user). The directory
216		- needs to be writable so that SQLite can write its journal files.</li>
217		- <li>Fossil must be able to create temporary files, the default directory
218		- for which depends on the OS. When the CGI process is operating within
219		- a chroot, ensure that this directory exists and is readable/writeable
220		- by the user who executes the Fossil binary.</li>
221		-</ul>
222		-
223		-Once the script is set up correctly, and assuming your server is also set
224		-correctly, you should be able to access your repository with a URL like:
225		-<b>http://mydomain.org/cgi-bin/repo</b> (assuming the "repo" script is
226		-accessible under "cgi-bin", which would be a typical deployment on Apache
227		-for instance).
228		-
229		-To serve multiple repositories from a directory using CGI, use the "directory:"
230		-tag in the CGI script rather than "repository:". You might also want to add
231		-a "notfound:" tag to tell where to redirect if the particular repository requested
232		-by the URL is not found:
233		-
234		-<blockquote><pre>
235		-#!/usr/bin/fossil
236		-directory: /home/fossil/repos
237		-notfound: http://url-to-go-to-if-repo-not-found/
238		-</pre></blockquote>
239		-
240		-Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b>
241		-will serve up the repository "/home/fossil/repos/XYZ.fossil" (if it exists).
242		-
243		-Additional options available to the CGI script are
244		-[./cgi.wiki\|documented separately].
245		-
246		-Note that Fossil itself can be launched as CGI, as described here. But
247		-Fossil can also launchI@1R~,C:\|sub-CGIs toS@1Su,3:].
248		-Z@1TN,K: Note also that the
249		-H@1S0,7p:\|sub-CGI mechanism] works regardless of how the main
250		-Fossil server is launched.
251		-
252		-<h2 id="scgi">Fossil as SCGI</h2>
253		-<blockquote>
254		-
255		-The [/help/server\|fossil server] command, described above as a way of
256		-starting a stand-alone web server, can also be used for SCGI. Simply add
257		-the --scgi command-line option and the stand-alone server will interpret
258		-and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can
259		-be used in combination with a web server (such as [http://nginx.org\|Nginx])
260		-M@2~G,Aa:CGI. A typical Nginx configuration to support SCGI
261		-with Fossil would look something like this:
262		-
263		-<blockquote><pre>
264		-location /demo_project/ {
265		- include scgi_params;
266		- scgi_pass localhost:9000;
267		- scgi_param SCRIPT_NAME "/demo_project";
268		- scgi_param HTTPS "on";
269		-}
270		-</pre></blockquote>
271		-
272		-Note that Fossil requires the SCRIPT_NAME variable
273		-in order to function properly, but Nginx does not provide this
274		-variable by default,
275		-so it is necessary to provide the SCRIPT_NAME parameter in the configuration.
276		-Failure to do this will cause Fossil to return an error.
277		-
278		-All of the features of the stand-alone server mode described above,
279		-such as the ability to serve a directory full ofK@2ny,H:
280		-rather than justK@NT,6d:, work the same way in SCGI mode.
281		-
282		-For security, it is probably a good idea to add the --localhost option
283		-to the [/help/server\|fossil server] command to prevent Fossil from accepting
284		-off-site connections. One might also want to specify the listening TCP port
285		-number, rather than letting Fossil choose one for itself, just to avoid
286		-ambiguity. A typical command to start a Fossil SCGI server
287		-would be something like this:
288		-
289		-<B@2qh,15:<pre>
290		-fossil server $REPOSITORY --scgi --localhost --port 9000
291		-</pre>E@1MD,D:</blockquote>5V@1Vv,16j@1vA,1wOnoJ;

	--- a/www/server.wiki
	+++ b/www/server.wiki
	@@ -1,291 +0,0 @@
1	<title>her post-activation steps includher poster post-activation steps is incl:</p>
2
3	<ol>
4	<li>
5	Add addieam members have approp.</l].
6
7	by to aData sharing and synchronization can be entirely peer-to-peer.
8	Fossil uses [https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type\|conflict-free replicated data types]
9	to ensure that (in the limit) all participating peers see the exact same content.nding in
10	"<tt>>
11	sh2>But, A Server Can Be Useful is incl:</p>
12
13	<ol>l>
14	<li>
15	Add addnot require a server,
16	but a server does make collaboration easier.
17	A Fossil server also works well as a complete website for acompletOverviewMethods is incl:</p>
18
19	<ol>
20	listener approachactivation: inetd, xinetdA stand-alone server
21	<li>Using inetd, xinetd, or stunnel
22	<li>CGI
23	<li>SCGI (a.k.a. Simp [ \| a separate article].nding in
24	"<tt>>
25
26	<h2 id="inetd">Serving via inetd is incl:</p>
27
28	<ol>
29	See [hat all teYou can als \| this article].nding in
30	"<tt>>
31
32	<h2 id="sl.wiki#stunneleading,
33	is just a Fossil server displaying the content of the
34	=> with a also migrate fro
35	ia-title="Howt This is the easiest wn also migrate fro
36	ia-title="Howt This is the easieng in
37	"<tt>>
38
39	<h2 id="inetd">Serving via inetd is incl:</p>
40
41	<ol>
42	See [hat all teYou can als \| this article].nding in
43	"<tt>>
44
45	<h2 id="cgi">Serving via CGI is incl:</p>
46
47	<ol>
48	See [ \| this article].nding in
49	"<tt>>
50
51	<h2 id="scgi">Serving via SCGI is incl:</p>
52
53	<ol>
54	See [on standard output w \| this article].nding in
55	"<tt>>
56	debian/nginxtext-align:style="text-align: Windows.org/] website, in, or a directory hierarchy
57	ving via inetd is incl:</p>
58
59	<ol>
60	serverT is to use either the
61	[/help/server\|server] or the [/help/ui\|ui] commands:
62
63	<ul>
64	<li><b>fossil server</b> <i>REPOSITORY</i>
65	<li><b>fossil ui</b> <i>REPOSITORY</i>
66	</ul>
67
68	The <i>REPOSITORY</i> argument is either the name of the repository file, or
69	a directorerving via inetd is incl:</p>
70
71	named <tt>*.fossil</tt>.
72	Both of these commands start a Fossil server, usually on TCP port 8080, though
73	a higher numbered port might also be used if 8080 is already occupied. You can
74	access these using URLs of the form <b>http://localhost:8080/</b>, or if
75	<i>REPOSITORY</i> is a directory, URLs of the form
76	<b>http://localhost:8080/</b><i>repo</i><b>/</b> where <i>repo</i> is the base
77	name of the repository file wkey differences between "ui" and "server":
78
79	<ul>
80	<li>"ui" always binds the server to the loopback IP address
81	(127.0.0.1) so that it cannot serve to other machines.
82	<li>anyone who visits this URL is treated as the all-powerful Setup
83	user, which is why the first difference exists.
84	<li>"ui" launches a local web browser pointed at this URL.
85	</ul>
86
87	You can omit the <i>REPOSITORY</i> argument if you run one of the above
88	commands from within a Fossil checkout directorE@1II,Av:<pre>
89	$ fossil ui # or...
90	$ fossil serve
91	</pre></blockquote>
92
93	Note that you can abbreviate Fossil sub-commands, as long as they are
94	unambiguous. "<tt>server</tt>" can currently be as short as
95	"<tt>ser</tt>".
96
97	As a more complicated example, you can serve a directory containing
98	multiple <tt>*.fossil</tt> files like so:
99
100	<blockquote><pre>
101	$ fossil server --port 9000 --repolist /path/to/repo/dir
102	</pre></blockquote>
103
104	There is an [/file/tools/fslsrv \| example script] in the Fossil
105	distribution that wraps <tt>fossil server</tt> to produce more
106	complicated effects. Feel free to take it, study it, and modify it to
107	suit your local needs.
108
109	See the [/help/server\|online documentation] for moreK@G0,p:options and arguments you can give to these commandsH@6G,m:
110	<h2 id="inetd">Fossil as an inetd/xinetd serviceK@1vl,Ez:
111	A Fossil server can be launched on-demand by inetd or xinetd using
112	the [/help/http\|fossil http] command. To launch Fossil from inetd, modify
113	your inetd configuration file (typically "/etc/inetd.conf") to contain a
114	line something like this:
115
116	<blockquote>
117	<pre>
118	80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil
119	</pre>
120	</blockquote>
121
122	In this example, you are telling "inetd" that when an incoming connection
123	appears on TCP port "80", that it should launch the binary "/usr/bin/fossil"
124	program with the arguments shown.
125	Obviously you will
126	need to modify the pathnames for your particular setup.
127	The final argument is either the name of the fossil repository to be served,
128	or a directory containing multiple repositories.
129
130
131	If you use a non-standard TCP port on
132	systems where the port-specification must be a symbolic name and cannot be
133	numeric, add the desired name and port to /etc/services. For example, if
134	you wanL@1Yk,OL:running on TCP port 12345 instead of 80, you
135	will need to add:
136
137	<blockquote>
138	<pre>
139	fossil 12345/tcp #fossil server
140	</pre>
141	</blockquote>
142
143	and use the symbolic name ('fossil' in this example) instead of the numeral ('12345')
144	in inetd.conf. For details, see the relevant section in your system's documentation, e.g.
145	the [https://www.freebsd.org/doc/en/books/handbook/network-inetd.html\|FreeBSD Handbook] in
146	case you use FreeBSD.
147
148	If your system is running xinetd, then the configuration is likely to be
149	in the file "/etc/xinetd.conf" or in a subfile of "/etc/xinetd.d".
150	An xinetd configuration file will appear like this:
151
152	<blockquote>
153	<pre>
154	service http
155	{
156	port = 80
157	socket_type = stream
158	wait = no
159	user = root
160	server = /usr/bin/fossil
161	server_args = http /home/fossil/repos/
162	}
163	</pre>
164	</blockquote>
165
166	The xinetd example above has Fossil configured to serve multiple
167	repositories, contained under the "/home/fossil/repos/" directory.
168
169	In both cases notice that Fossil was launched as root. This is not required,
170	but if it is done, then Fossil will automatically put itself into a chroot
171	jail for the user who owns the fossil repository before reading any information
172	off of the wire.
173
174	Inetd or xinetd must be enabled, and must be (re)started whenever their configuration
175	changes - consult your system's documentation for details.
176
177	Using inetd or xinetd is a more complex setup
178	than the "standalone" server, but it has the
179	advantage of only using system resources when an actual connection is
180	attempted. If no-one ever connects to that port,H@BF,4W:will
181	not (automatically) run. It has the disadvantage of requiring "root" access
182	and therefore may not normally be available to lower-priced "shared" servers
183	on the Internet.
184
185	The configuration for <tt>stunnel</tt> is similar, but it is covered in
186	[./ssl.wiki#stunnel\|a separate document]K@6G,N: id="cgi">Fossil as CGIK@1vl,2d:
187	A Fossil server can also be run from an ordinary web server as a CGI program.
188	This feature allows Fossil to be seamlessly integrated into a larger website.
189	CGI is how K@2nS,H: \| self-hosting fJ@2n~,eb: are
190	implemented.
191
192	To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory
193	of your web server and having content like this:
194
195	<blockquote><pre>
196	#!/usr/bin/fossil
197	repository: /home/fossil/repo.fossil
198	</pre></blockquote>
199
200	As always, adjust your paths appropriately.
201	It may be necessary to set permissions properly, or to modify an ".htaccess"
202	file or make other server-specific changes. Consult the documentation
203	for your particular web server. In particular, the following permissions are
204	<em>normally</em> required (but, again, may be different for a particular
205	configuration):
206
207	<ul>
208	<li>The Fossil binary (/usr/bin/fossil in the example above)
209	must be readable/executable, and ALL directories leading up to it
210	must be readable by the process which executes the CGI.</li>
211	<li>ALL directories leading to the CGI script must also be readable and the CGI
212	script itself must be executable for the user under which it will run (which often differs
213	from the one running the web server - consult your site's documentation or administrator).</li>
214	<li>The repository file AND the directory containing it must be writable by the same account
215	which executes the Fossil binary (again, this might differ from the WWW user). The directory
216	needs to be writable so that SQLite can write its journal files.</li>
217	<li>Fossil must be able to create temporary files, the default directory
218	for which depends on the OS. When the CGI process is operating within
219	a chroot, ensure that this directory exists and is readable/writeable
220	by the user who executes the Fossil binary.</li>
221	</ul>
222
223	Once the script is set up correctly, and assuming your server is also set
224	correctly, you should be able to access your repository with a URL like:
225	<b>http://mydomain.org/cgi-bin/repo</b> (assuming the "repo" script is
226	accessible under "cgi-bin", which would be a typical deployment on Apache
227	for instance).
228
229	To serve multiple repositories from a directory using CGI, use the "directory:"
230	tag in the CGI script rather than "repository:". You might also want to add
231	a "notfound:" tag to tell where to redirect if the particular repository requested
232	by the URL is not found:
233
234	<blockquote><pre>
235	#!/usr/bin/fossil
236	directory: /home/fossil/repos
237	notfound: http://url-to-go-to-if-repo-not-found/
238	</pre></blockquote>
239
240	Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b>
241	will serve up the repository "/home/fossil/repos/XYZ.fossil" (if it exists).
242
243	Additional options available to the CGI script are
244	[./cgi.wiki\|documented separately].
245
246	Note that Fossil itself can be launched as CGI, as described here. But
247	Fossil can also launchI@1R~,C:\|sub-CGIs toS@1Su,3:].
248	Z@1TN,K: Note also that the
249	H@1S0,7p:\|sub-CGI mechanism] works regardless of how the main
250	Fossil server is launched.
251
252	<h2 id="scgi">Fossil as SCGI</h2>
253	<blockquote>
254
255	The [/help/server\|fossil server] command, described above as a way of
256	starting a stand-alone web server, can also be used for SCGI. Simply add
257	the --scgi command-line option and the stand-alone server will interpret
258	and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can
259	be used in combination with a web server (such as [http://nginx.org\|Nginx])
260	M@2~G,Aa:CGI. A typical Nginx configuration to support SCGI
261	with Fossil would look something like this:
262
263	<blockquote><pre>
264	location /demo_project/ {
265	include scgi_params;
266	scgi_pass localhost:9000;
267	scgi_param SCRIPT_NAME "/demo_project";
268	scgi_param HTTPS "on";
269	}
270	</pre></blockquote>
271
272	Note that Fossil requires the SCRIPT_NAME variable
273	in order to function properly, but Nginx does not provide this
274	variable by default,
275	so it is necessary to provide the SCRIPT_NAME parameter in the configuration.
276	Failure to do this will cause Fossil to return an error.
277
278	All of the features of the stand-alone server mode described above,
279	such as the ability to serve a directory full ofK@2ny,H:
280	rather than justK@NT,6d:, work the same way in SCGI mode.
281
282	For security, it is probably a good idea to add the --localhost option
283	to the [/help/server\|fossil server] command to prevent Fossil from accepting
284	off-site connections. One might also want to specify the listening TCP port
285	number, rather than letting Fossil choose one for itself, just to avoid
286	ambiguity. A typical command to start a Fossil SCGI server
287	would be something like this:
288
289	<B@2qh,15:<pre>
290	fossil server $REPOSITORY --scgi --localhost --port 9000
291	</pre>E@1MD,D:</blockquote>5V@1Vv,16j@1vA,1wOnoJ;

	--- a/www/server.wiki
	+++ b/www/server.wiki
	@@ -1,291 +0,0 @@

M www/server/any/althttpd.md

+37

		--- a/www/server/any/althttpd.md
		+++ b/www/server/any/althttpd.md
		@@ -0,0 +1,37 @@
	1	+# Serving via althttpd
	2	+
	3	+The public SQLite and Fossil web sites are not purely served by Fossil
	4	+for two reasons:
	5	+
	6	+1. We want access to these sites to be secured with TLS, which we do
	7	+ [via `stunnel`](./stunnel.md).
	8	+
	9	+2. Parts of these web sites are static, stored as plain files on disk,
	10	+ not as Fossil artifacts. We serve such files using a separate web
	11	+ server called [`althttpd`][ah], written by the primary author of
	12	+ both SQLite and Fossil, D. Richard Hipp. `althttpd` is a lightweight
	13	+ HTTP-only web server. It handles the static HTTP hits on
	14	+ <tt>sqlite.org</tt> and <tt>fossil-scm.org</tt>, delegating HTTPS
	15	+ hits to `stunnel` and dynamic content hits to Fossil [via
	16	+ CGI][cgi].
	17	+
	18	+The largest single chunk of static content served directly by `althttpd`
	19	+rather than via Fossil is the [SQLite documentation][sd], which is built
	20	+[from source files][ds]. We don’t want those output files stored in
	21	+Fossil; we already keep that process’s input files in Fossil. Thus the
	22	+choice to serve the output statically.
	23	+
	24	+In addition to the [server’s documentation page][ah], there is a large,
	25	+helpful header comment in the server’s [single-file C
	26	+implementation][ac]. Between that and the generic [Serving via CGI][cgi]
	27	+docs, you should be able to figure out how to serve Fossil via
	28	+`althttpd`.
	29	+
	30	+[Return to the top-level Fossil server article.](../)
	31	+
	32	+
	33	+[ac]: https://sqlite.org/docsrc/file/misc/althttpd.c
	34	+[ah]: https://sqlite.org/docsrc/doc/trunk/misc/althttpd.md
	35	+[cgi]: ./cgi.md
	36	+[ds]: https://sqlite.org/docsrc/
	37	+[sd]: https://sqlite.org/docs.html

	--- a/www/server/any/althttpd.md
	+++ b/www/server/any/althttpd.md
	@@ -0,0 +1,37 @@

	--- a/www/server/any/althttpd.md
	+++ b/www/server/any/althttpd.md
	@@ -0,0 +1,37 @@
1	# Serving via althttpd
2
3	The public SQLite and Fossil web sites are not purely served by Fossil
4	for two reasons:
5
6	1. We want access to these sites to be secured with TLS, which we do
7	[via `stunnel`](./stunnel.md).
8
9	2. Parts of these web sites are static, stored as plain files on disk,
10	not as Fossil artifacts. We serve such files using a separate web
11	server called [`althttpd`][ah], written by the primary author of
12	both SQLite and Fossil, D. Richard Hipp. `althttpd` is a lightweight
13	HTTP-only web server. It handles the static HTTP hits on
14	<tt>sqlite.org</tt> and <tt>fossil-scm.org</tt>, delegating HTTPS
15	hits to `stunnel` and dynamic content hits to Fossil [via
16	CGI][cgi].
17
18	The largest single chunk of static content served directly by `althttpd`
19	rather than via Fossil is the [SQLite documentation][sd], which is built
20	[from source files][ds]. We don’t want those output files stored in
21	Fossil; we already keep that process’s input files in Fossil. Thus the
22	choice to serve the output statically.
23
24	In addition to the [server’s documentation page][ah], there is a large,
25	helpful header comment in the server’s [single-file C
26	implementation][ac]. Between that and the generic [Serving via CGI][cgi]
27	docs, you should be able to figure out how to serve Fossil via
28	`althttpd`.
29
30	[Return to the top-level Fossil server article.](../)
31
32
33	[ac]: https://sqlite.org/docsrc/file/misc/althttpd.c
34	[ah]: https://sqlite.org/docsrc/doc/trunk/misc/althttpd.md
35	[cgi]: ./cgi.md
36	[ds]: https://sqlite.org/docsrc/
37	[sd]: https://sqlite.org/docs.html

M www/server/any/cgi.md

+10

		--- a/www/server/any/cgi.md
		+++ b/www/server/any/cgi.md
		@@ -0,0 +1,10 @@
	1	+# Serving via Sometime in# Serving via version 2.4# Serving via In version 2.4.59# Serving Fossil server can be run f
	2	+the Content-Length headeWe use CGI for t in the HTTP reply from CGIs back to client
	3	+```
	4	+<Directory ...>
	5	+<ontent-Length header in the HTTP reply from CGIs back to client
	6	+```
	7	+<Directory ...>
	8	+</Directory>
	9	+```
	10	+# Serving via Sometim

	--- a/www/server/any/cgi.md
	+++ b/www/server/any/cgi.md
	@@ -0,0 +1,10 @@

	--- a/www/server/any/cgi.md
	+++ b/www/server/any/cgi.md
	@@ -0,0 +1,10 @@
1	# Serving via Sometime in# Serving via version 2.4# Serving via In version 2.4.59# Serving Fossil server can be run f
2	the Content-Length headeWe use CGI for t in the HTTP reply from CGIs back to client
3	```
4	<Directory ...>
5	<ontent-Length header in the HTTP reply from CGIs back to client
6	```
7	<Directory ...>
8	</Directory>
9	```
10	# Serving via Sometim

M www/server/any/inetd.md

+16

		--- a/www/server/any/inetd.md
		+++ b/www/server/any/inetd.md
		@@ -0,0 +1,16 @@
	1	+# Serving via inetd
	2	+
	3	+A Fossil server can be launched on-demand by `inetd` by using the
	4	+[`fossil http`](/help/http) command. To do so, add a line like the
	5	+following to its configuration file, typically `/etc/inetd.conf`:
	6	+
	7	+ 80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil
	8	+
	9	+In this example, you are telling `inetd` that when an incoming
	10	+connection appears on TCP port 80 that it should launch the program
	11	+`/usr/bin/fossil` with the arguments shown. Obviously you will need to
	12	+modify the pathnames for your particular setup. The final argument is
	13	+either the name of the fossil repository to be served or a directory
	14	+containing multiple repositories.
	15	+
	16	+If you use a

	--- a/www/server/any/inetd.md
	+++ b/www/server/any/inetd.md
	@@ -0,0 +1,16 @@

	--- a/www/server/any/inetd.md
	+++ b/www/server/any/inetd.md
	@@ -0,0 +1,16 @@
1	# Serving via inetd
2
3	A Fossil server can be launched on-demand by `inetd` by using the
4	[`fossil http`](/help/http) command. To do so, add a line like the
5	following to its configuration file, typically `/etc/inetd.conf`:
6
7	80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil
8
9	In this example, you are telling `inetd` that when an incoming
10	connection appears on TCP port 80 that it should launch the program
11	`/usr/bin/fossil` with the arguments shown. Obviously you will need to
12	modify the pathnames for your particular setup. The final argument is
13	either the name of the fossil repository to be served or a directory
14	containing multiple repositories.
15
16	If you use a

M www/server/any/none.md

+41

		--- a/www/server/any/none.md
		+++ b/www/server/any/none.md
		@@ -0,0 +1,41 @@
	1	+# Standalone HTTP Server
	2	+
	3	+The easiest way to set up a Fossil server is to use either the
	4	+[`server`](/help/server) or [`ui`](/help/ui) command:
	5	+
	6	+* fossil server _REPOSITORY_
	7	+* fossil ui _REPOSITORY_
	8	+
	9	+The _REPOSITORY_ argument is either the name of the repository file or a
	10	+directory containing many repositories named “`*.fossil`”. Both of these
	11	+commands start a Fossil server, usually on TCP port 8080, though a
	12	+higher numbered port will be used instead if 8080 is already occupied.
	13	+
	14	+You can access these using URLs of the form http://localhost:8080/,
	15	+or if _REPOSITORY_ is a directory, URLs of the form
	16	+http://localhost:8080/_repo_/ where _repo_ is the base name of
	17	+the repository file without the “`.fossil`” suffix.
	18	+
	19	+There are several key differences between “`ui`” and “`server`”:
	20	+
	21	+* “`ui`” always binds the server to the loopback IP address (127.0.0.1)
	22	+ so that it cannot serve to other machines.
	23	+
	24	+* Anyone who visits this URL is treated as the all-powerful Setup
	25	+ user, which is why th first difference exists.
	26	+
	27	+* “`ui`” launches a local web browser pointed at this URL.
	28	+
	29	+You can omit the _REPOSITORY_ argument if you run one of the above
	30	+commands from within a Fossil checkout directory to s $ foss# Standalone HTTP Server
	31	+
	32	+The easiest way to set up a Fossil server is to use either the
	33	+[`server`](/help/server) or [`ui`](/help/ui) command:
	34	+
	35	+* fossil server _REPOSITORY_
	36	+* fossil ui _REPOSITORY_
	37	+
	38	+The _REPOSITORY_ argument is either the name of the repository file or a
	39	+directory containing many repositories named “`*.fossil`”. Both of these
	40	+commands start a Fossil server, usually on TCP port 8080, though a
	41	+higher numbered port will be use

	--- a/www/server/any/none.md
	+++ b/www/server/any/none.md
	@@ -0,0 +1,41 @@

	--- a/www/server/any/none.md
	+++ b/www/server/any/none.md
	@@ -0,0 +1,41 @@
1	# Standalone HTTP Server
2
3	The easiest way to set up a Fossil server is to use either the
4	[`server`](/help/server) or [`ui`](/help/ui) command:
5
6	* fossil server _REPOSITORY_
7	* fossil ui _REPOSITORY_
8
9	The _REPOSITORY_ argument is either the name of the repository file or a
10	directory containing many repositories named “`*.fossil`”. Both of these
11	commands start a Fossil server, usually on TCP port 8080, though a
12	higher numbered port will be used instead if 8080 is already occupied.
13
14	You can access these using URLs of the form http://localhost:8080/,
15	or if _REPOSITORY_ is a directory, URLs of the form
16	http://localhost:8080/_repo_/ where _repo_ is the base name of
17	the repository file without the “`.fossil`” suffix.
18
19	There are several key differences between “`ui`” and “`server`”:
20
21	* “`ui`” always binds the server to the loopback IP address (127.0.0.1)
22	so that it cannot serve to other machines.
23
24	* Anyone who visits this URL is treated as the all-powerful Setup
25	user, which is why th first difference exists.
26
27	* “`ui`” launches a local web browser pointed at this URL.
28
29	You can omit the _REPOSITORY_ argument if you run one of the above
30	commands from within a Fossil checkout directory to s $ foss# Standalone HTTP Server
31
32	The easiest way to set up a Fossil server is to use either the
33	[`server`](/help/server) or [`ui`](/help/ui) command:
34
35	* fossil server _REPOSITORY_
36	* fossil ui _REPOSITORY_
37
38	The _REPOSITORY_ argument is either the name of the repository file or a
39	directory containing many repositories named “`*.fossil`”. Both of these
40	commands start a Fossil server, usually on TCP port 8080, though a
41	higher numbered port will be use

M www/server/any/scgi.md

+18

		--- a/www/server/any/scgi.md
		+++ b/www/server/any/scgi.md
		@@ -0,0 +1,18 @@
	1	+# Serving via SCGI
	2	+
	3	+There examplexamplexamplexamplram HTTPS "on";
	4	+ }
	5	+
	6	+Start Fossil so that it will respond to nginx’s SCG
	7	+
	8	+ 12@NB,Bh@OF,8V:Fossil requires the `SCRIPT_NAME` environment variable in order to
	9	+function properly, but nginx does not provide this variable by default,
	10	+so it is necessary to provide it in the configuration. Failure to do
	11	+this will cause Fossil to return an error.
	12	+
	13	+The [example `fslsrv` script](/file/tools/fslsrv) shows off these same
	14	+concepts in a more complicated setting. You might want to mine that
	15	+script for ideas.
	16	+
	17	+You might want to next read one of the platform-specific versions of this
	18	+document, which goes

	--- a/www/server/any/scgi.md
	+++ b/www/server/any/scgi.md
	@@ -0,0 +1,18 @@

	--- a/www/server/any/scgi.md
	+++ b/www/server/any/scgi.md
	@@ -0,0 +1,18 @@
1	# Serving via SCGI
2
3	There examplexamplexamplexamplram HTTPS "on";
4	}
5
6	Start Fossil so that it will respond to nginx’s SCG
7
8	12@NB,Bh@OF,8V:Fossil requires the `SCRIPT_NAME` environment variable in order to
9	function properly, but nginx does not provide this variable by default,
10	so it is necessary to provide it in the configuration. Failure to do
11	this will cause Fossil to return an error.
12
13	The [example `fslsrv` script](/file/tools/fslsrv) shows off these same
14	concepts in a more complicated setting. You might want to mine that
15	script for ideas.
16
17	You might want to next read one of the platform-specific versions of this
18	document, which goes

M www/server/any/stunnel.md

+34

		--- a/www/server/any/stunnel.md
		+++ b/www/server/any/stunnel.md
		@@ -0,0 +1,34 @@
	1	+# Serving via stunnel
	2	+
	3	+[`stunnel`](https://www.stunnel.org/) is a TLS/SSL proxy for programs
	4	+that themselves serve only via HTTP, such as Fossil. (Fossil can speak
	5	+HTTPS, but only as a client.) `stunnel` decodes the HTTPS data from the
	6	+outside world as HTTP before passing it to Fossil, and it encodes the
	7	+HTTP replies from Fossil as HTTPS before sending them to the remote host
	8	+that made the request.
	9	+
	10	+You can run `stunnel` in one of two modes: socket listener — much like
	11	+in our [`inetd` doc](./inetd.md) — and as an HTTP reverse proxy. We’ll
	12	+cover both cases here, separately.
	13	+
	14	+
	15	+## S<a name="sa"></a>ocket Activation
	16	+
	17	+The following `stunnel.conf` configuration configures it to run Fossil
	18	+in socket listener mode, launching Fossil only when an HTTPS hit comes
	19	+in, then shutting it back down as soon as the transaction is complete:
	20	+
	21	+```dosini
	22	+ [fossil]
	23	+ accept = 443
	24	+ TIMEOUTclose = 0
	25	+ exec = /usr/bin/fossil
	26	+ execargs = /usr/bin/fossil http /home/fossil/ubercool.fossil --https
	27	+ cert = /etc/letsencrypt/live/ubercool-project.org/fullchain.pem
	28	+ key = /etc/letsencrypt/live/ubercool-project.org/privkey.pem
	29	+ ciphers = ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES128-SHA:DES-CBC3-SHA
	30	+ options = CIPHER_SERVER_PREFERENCE
	31	+```
	32	+
	33	+This configuration shows the TLS certificate generated by the [Let’s
	34	+Encrypt](https://letsencrypt.org) [Certbot](https://certbot.eff.or

	--- a/www/server/any/stunnel.md
	+++ b/www/server/any/stunnel.md
	@@ -0,0 +1,34 @@

	--- a/www/server/any/stunnel.md
	+++ b/www/server/any/stunnel.md
	@@ -0,0 +1,34 @@
1	# Serving via stunnel
2
3	[`stunnel`](https://www.stunnel.org/) is a TLS/SSL proxy for programs
4	that themselves serve only via HTTP, such as Fossil. (Fossil can speak
5	HTTPS, but only as a client.) `stunnel` decodes the HTTPS data from the
6	outside world as HTTP before passing it to Fossil, and it encodes the
7	HTTP replies from Fossil as HTTPS before sending them to the remote host
8	that made the request.
9
10	You can run `stunnel` in one of two modes: socket listener — much like
11	in our [`inetd` doc](./inetd.md) — and as an HTTP reverse proxy. We’ll
12	cover both cases here, separately.
13
14
15	## S<a name="sa"></a>ocket Activation
16
17	The following `stunnel.conf` configuration configures it to run Fossil
18	in socket listener mode, launching Fossil only when an HTTPS hit comes
19	in, then shutting it back down as soon as the transaction is complete:
20
21	```dosini
22	[fossil]
23	accept = 443
24	TIMEOUTclose = 0
25	exec = /usr/bin/fossil
26	execargs = /usr/bin/fossil http /home/fossil/ubercool.fossil --https
27	cert = /etc/letsencrypt/live/ubercool-project.org/fullchain.pem
28	key = /etc/letsencrypt/live/ubercool-project.org/privkey.pem
29	ciphers = ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES128-SHA:DES-CBC3-SHA
30	options = CIPHER_SERVER_PREFERENCE
31	```
32
33	This configuration shows the TLS certificate generated by the [Let’s
34	Encrypt](https://letsencrypt.org) [Certbot](https://certbot.eff.or

M www/server/any/xinetd.md

+26

		--- a/www/server/any/xinetd.md
		+++ b/www/server/any/xinetd.md
		@@ -0,0 +1,26 @@
	1	+# Serving via xinetd
	2	+
	3	+Some operating systems have replaced the old Unix `inetd` daemon with
	4	+`xinetd`, which has a similar mission but with a very different
	5	+configuration file format.
	6	+
	7	+The typical configuration file is either `/etc/xinetd.conf` or a subfile
	8	+in the `/etc/xinetd.d` directory. You need a configuration something
	9	+like this for Fossil:
	10	+
	11	+ service http
	12	+ {
	13	+ port = 80
	14	+ socket_type = stream
	15	+ wait = no
	16	+ e = stream
	17	+ wait = server = /usr/bin/fossil
	18	+ server_args = ht }
	19	+
	20	+This example configures Fossil to serve multiple repositories under the
	21	+`/home/fossil/repos/` directory.
	22	+
	23	+Beyond this, see the general commentary in our article on [the `inetd`
	24	+method](./inetd.md) as they also apply to service via `xinetd`.
	25	+
	26	+*[Return to the top-level Fos

	--- a/www/server/any/xinetd.md
	+++ b/www/server/any/xinetd.md
	@@ -0,0 +1,26 @@

	--- a/www/server/any/xinetd.md
	+++ b/www/server/any/xinetd.md
	@@ -0,0 +1,26 @@
1	# Serving via xinetd
2
3	Some operating systems have replaced the old Unix `inetd` daemon with
4	`xinetd`, which has a similar mission but with a very different
5	configuration file format.
6
7	The typical configuration file is either `/etc/xinetd.conf` or a subfile
8	in the `/etc/xinetd.d` directory. You need a configuration something
9	like this for Fossil:
10
11	service http
12	{
13	port = 80
14	socket_type = stream
15	wait = no
16	e = stream
17	wait = server = /usr/bin/fossil
18	server_args = ht }
19
20	This example configures Fossil to serve multiple repositories under the
21	`/home/fossil/repos/` directory.
22
23	Beyond this, see the general commentary in our article on [the `inetd`
24	method](./inetd.md) as they also apply to service via `xinetd`.
25
26	*[Return to the top-level Fos

M www/server/debian/nginx.md

+105

		--- a/www/server/debian/nginx.md
		+++ b/www/server/debian/nginx.md
		@@ -0,0 +1,105 @@
	1	+# S generic;
	2	+
	3	+ S# S# S }
	4	+ # Redirect everything els }
	5	+ }T is
	6	+We focus
	7	+Ubuntu 20.04 here, which a
	8	+private servers][vpadding TLS access
	9	+ supports
	10	+TLS. One such option is nginx on Debian, so we show the details of that
	11	+here.
	12	+
	13	+You can extend this guide to other operating systems by following the
	14	+instructions fou18 via [the front Certbot web page][c;
	15	+
	16	+ S# S# S }
	17	+ # Redirect everything els ls }
	18	+ }T is
	19	+# S generic;
	20	+
	21	+ S# S# S }
	22	+ # Redirect everything If you want to add TLS to this configuration, that is covered [in a
	23	+separate document][tls] which was written with the assumption that
	24	+you’ve read this firstnfused Certbot, so we had totls]: ../../tls-nginxs manually](#lehw),
	25	+else the Let’s Encrypt [ACME] exchange failed in thenameecessary domain
	26	+validation steps.
	27	+
	28	+At this point, if# S generic;
	29	+
	30	+ S# S# S }
	31	+ # Redirect everything els }
	32	+ }T is
	33	+
	34	+
	35	+ $ sudo snap install --classic certbot
	36	+ $ sudo systemctl disable certbot.timer
	37	+
	38	+Next, edit `H@3AF,50:renewal/example.com.conf` to disable the
	39	+nginx plugins. You’re looking for two lines setting the “install” and
	40	+“auth” plugins to “nginx”. You can comment them out or remove them
	41	+entirely.
	42	+
	43	+
	44	+#### Step 2: Configuring nginx
	45	+
	46	+This is a straightforward extension to the HTTP/help/serveration
	47	+[above](#config)e@1X4,9:foo.net;
	48	+P@1Y9,_:tls-common;
	49	+
	50	+ charset utf-8c@this
	51	+ option is overkill for our purposes. nginx is itself a fully
	52	+ featured HTTP server, so we will choose in this guide not to make
	53	+ S generic;
	54	+
	55	+ S# S# S }
	56	+ ic;
	57	+
	58	+ S# S# S }
	59	+ #.I run my Fossil SCGI server instances with a variant of [the `fslsrv`
	60	+shell currently hosted in the Fossil source
	61	+code repository. You’ll want to download that and make a copy of it, so
	62	+you can customize it to your particular needSCGI servers, one per
	63	+repository, each bound to a different high-numbered `localhost` port, so
	64	+that only nginx can see and proxy them out to the public. The
	65	+“`example`” repo is on TCP port localhost:12345, and the “`foo`” repo is
	66	+on localhost:12346.
	67	+
	68	+As written, the `fslsrv` script expects repositories to be stored in the
	69	+calling user’s home directory under `~/museum`, because where else do
	70	+you keep Fossils?
	71	+
	72	+That home directory also needs to have a directory to hold log files,
	73	+`~/log/fossil/*.log`. Fossil doesn’t put out much logging, but when it
	74	+does, it’s better to have it captured than to need to re-create the
	75	+problem after the fact.
	76	+
	77	+The use of `--baseurl` in this script lets us have each Fossil
	78	+repository mounted in a different location in the URL scheme. Here, for
	79	+example, we’re saying that the “`example`” repository is hosted under
	80	+the `/code` URI on its domains, but that the “`foo`” repo is hosted at
	81	+the top level of its domain. You’ll want to do something like the
	82	+former for a Fossil repo that’s just one piece of a larger site, but the
	83	+latter for a repo that is basically the whole point of the site.
	84	+
	85	+You might also want another script to automate the update, build, and
	86	+deployment steps for new Fossil versions:
	87	+
	88	+ #!/bin/sh
	89	+ fossil up
	90	+ make -j11
	91	+ killall fossil
	92	+ sudo make install
	93	+ fslsrv
	94	+
	95	+The `killall fossil` step is needed only on OSes that refuse to let you
	96	+replace a running binary on disk.
	97	+
	98	+As written, the `fslsrv` script assumes a Linux environment. It expects
	99	+`/bin/bash` to exist, and it depends on non-POSIX tools like `pgrep`.
	100	+It should not be difficult to port to systems like macOS or the BSDs` contains thfoo.netT is
	101	+We focus
	102	+Ubuntu 20.04 # Sfoo.net;
	103	+foo.netfoo.netDoxygen docsfoo.net scgi_param HTTPS "on"";
	104	+ simpleedirect everything he public. The
	105	+“`example`”

	--- a/www/server/debian/nginx.md
	+++ b/www/server/debian/nginx.md
	@@ -0,0 +1,105 @@

	--- a/www/server/debian/nginx.md
	+++ b/www/server/debian/nginx.md
	@@ -0,0 +1,105 @@
1	# S generic;
2
3	S# S# S }
4	# Redirect everything els }
5	}T is
6	We focus
7	Ubuntu 20.04 here, which a
8	private servers][vpadding TLS access
9	supports
10	TLS. One such option is nginx on Debian, so we show the details of that
11	here.
12
13	You can extend this guide to other operating systems by following the
14	instructions fou18 via [the front Certbot web page][c;
15
16	S# S# S }
17	# Redirect everything els ls }
18	}T is
19	# S generic;
20
21	S# S# S }
22	# Redirect everything If you want to add TLS to this configuration, that is covered [in a
23	separate document][tls] which was written with the assumption that
24	you’ve read this firstnfused Certbot, so we had totls]: ../../tls-nginxs manually](#lehw),
25	else the Let’s Encrypt [ACME] exchange failed in thenameecessary domain
26	validation steps.
27
28	At this point, if# S generic;
29
30	S# S# S }
31	# Redirect everything els }
32	}T is
33
34
35	$ sudo snap install --classic certbot
36	$ sudo systemctl disable certbot.timer
37
38	Next, edit `H@3AF,50:renewal/example.com.conf` to disable the
39	nginx plugins. You’re looking for two lines setting the “install” and
40	“auth” plugins to “nginx”. You can comment them out or remove them
41	entirely.
42
43
44	#### Step 2: Configuring nginx
45
46	This is a straightforward extension to the HTTP/help/serveration
47	[above](#config)e@1X4,9:foo.net;
48	P@1Y9,_:tls-common;
49
50	charset utf-8c@this
51	option is overkill for our purposes. nginx is itself a fully
52	featured HTTP server, so we will choose in this guide not to make
53	S generic;
54
55	S# S# S }
56	ic;
57
58	S# S# S }
59	#.I run my Fossil SCGI server instances with a variant of [the `fslsrv`
60	shell currently hosted in the Fossil source
61	code repository. You’ll want to download that and make a copy of it, so
62	you can customize it to your particular needSCGI servers, one per
63	repository, each bound to a different high-numbered `localhost` port, so
64	that only nginx can see and proxy them out to the public. The
65	“`example`” repo is on TCP port localhost:12345, and the “`foo`” repo is
66	on localhost:12346.
67
68	As written, the `fslsrv` script expects repositories to be stored in the
69	calling user’s home directory under `~/museum`, because where else do
70	you keep Fossils?
71
72	That home directory also needs to have a directory to hold log files,
73	`~/log/fossil/*.log`. Fossil doesn’t put out much logging, but when it
74	does, it’s better to have it captured than to need to re-create the
75	problem after the fact.
76
77	The use of `--baseurl` in this script lets us have each Fossil
78	repository mounted in a different location in the URL scheme. Here, for
79	example, we’re saying that the “`example`” repository is hosted under
80	the `/code` URI on its domains, but that the “`foo`” repo is hosted at
81	the top level of its domain. You’ll want to do something like the
82	former for a Fossil repo that’s just one piece of a larger site, but the
83	latter for a repo that is basically the whole point of the site.
84
85	You might also want another script to automate the update, build, and
86	deployment steps for new Fossil versions:
87
88	#!/bin/sh
89	fossil up
90	make -j11
91	killall fossil
92	sudo make install
93	fslsrv
94
95	The `killall fossil` step is needed only on OSes that refuse to let you
96	replace a running binary on disk.
97
98	As written, the `fslsrv` script assumes a Linux environment. It expects
99	`/bin/bash` to exist, and it depends on non-POSIX tools like `pgrep`.
100	It should not be difficult to port to systems like macOS or the BSDs` contains thfoo.netT is
101	We focus
102	Ubuntu 20.04 # Sfoo.net;
103	foo.netfoo.netDoxygen docsfoo.net scgi_param HTTPS "on"";
104	simpleedirect everything he public. The
105	“`example`”

M www/server/debian/service.md

+14

		--- a/www/server/debian/service.md
		+++ b/www/server/debian/service.md
		@@ -0,0 +1,14 @@
	1	+#A simple and useful modification to the above scheme is to add the
	2	+`--scgi` and `--localhost` flags to the `ExecStart` line to replace the
	3	+use of `fslsrv` in(../any/scgi.md)sockets.target-lAnother workaround for the problem with user services above is to
	4	+install the service as a systeminstead. This , such as
	5	+[nginx](./nginx.md)sockets.targetrably one as a
	6	+user service #A simple and useful modification to the above scheme is to add the
	7	+`--scgi` and `--localhost` flags to the `ExecStart` line to replace the
	8	+use of `fslsrv` in(../any/scgi.md)sockets.target-lAnother workaround for the problem with user services above is to
	9	+install the service as a systeminstead. This , such as
	10	+[nginx](./nginx.md)sockets.targetrably one useful modification to the above scheme is to add the
	11	+`--scgi` and `--localhost` flags to the `ExecStart` line to replace the
	12	+use of `fslsrv` in(../any/scgi.md)sockets.target-lAnother workaround for the problem with user services above is to
	13	+install the service as a systeminstead. This , such as
	14	+[nginx](./nginx.md)sockets.targetrably one

	--- a/www/server/debian/service.md
	+++ b/www/server/debian/service.md
	@@ -0,0 +1,14 @@

	--- a/www/server/debian/service.md
	+++ b/www/server/debian/service.md
	@@ -0,0 +1,14 @@
1	#A simple and useful modification to the above scheme is to add the
2	`--scgi` and `--localhost` flags to the `ExecStart` line to replace the
3	use of `fslsrv` in(../any/scgi.md)sockets.target-lAnother workaround for the problem with user services above is to
4	install the service as a systeminstead. This , such as
5	[nginx](./nginx.md)sockets.targetrably one as a
6	user service #A simple and useful modification to the above scheme is to add the
7	`--scgi` and `--localhost` flags to the `ExecStart` line to replace the
8	use of `fslsrv` in(../any/scgi.md)sockets.target-lAnother workaround for the problem with user services above is to
9	install the service as a systeminstead. This , such as
10	[nginx](./nginx.md)sockets.targetrably one useful modification to the above scheme is to add the
11	`--scgi` and `--localhost` flags to the `ExecStart` line to replace the
12	use of `fslsrv` in(../any/scgi.md)sockets.target-lAnother workaround for the problem with user services above is to
13	install the service as a systeminstead. This , such as
14	[nginx](./nginx.md)sockets.targetrably one

M www/server/index.html

+114 -279

		--- a/www/server/index.html
		+++ b/www/server/index.html
		@@ -1,291 +1,126 @@
1		-<title>her post-activation steps includher poster post-activation steps is incl:</p>
	1	+ia-title="How To Configure A Fossil Server">
	2	+
	3	+<style type="text/css">
	4	+ p {
	5	+ margin-left: 4em;
	6	+ margin-right: 3em;
	7	+ }
	8	+
	9	+ li p {
	10	+ margin-left: 0;h2n evenPI to give it an evenPI
	11	+Prior to launching a server on, it is best to
	12	+prepareto be served. The easiest wacommand
	13	+on a workstation and then visit the "Setup" menu.
	14	+Minimum preparation actions include:</p>
2	15
3	16	<ol>
4	17	<li>
5		-Add addieam members have approp.</l].
	18	+Ensure that you have an administrator user account and password
	19	+configured. Visit the Setup/Users page to accomplish this.</p></li>
	20	+<li>
	21	+Visit the Setup/Security-Audit pageYou might want to configureto be completely private
	22	+for the initial upload and server activatation, then open access up to
	23	+post-activation configuration refinement</a>
	24	+stage.
	25	+</p></li>
	26	+</ol>
6	27
7		-by to aData sharing and synchronization can be entirely peer-to-peer.
8		-Fossil uses [https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type\|conflict-free replicated data types]
9		-to ensure that (in the limit) all participating peers see the exact same content.nding in
10		-"<tt>>
11		-sh2>But, A Server Can Be Useful is incl:</p>
	28	+<p>
	29	+Additional configuration can be accomplished after the server is up
	30	+and running. Once the prvery useful</a>.</p>trator
	31	+and visiting the Setup menu. Pay particular attention to the
	32	+"Setup/Sec
	33	+configured the
	34	+want to keep private. Other post-activation steps include the follodditionalmethods">.
	35	+</p></li>
	36	+</ol>
12	37
13		-<ol>l>
14		-<li>
15		-Add addnot require a server,
16		-but a server does make collaboration easier.
17		-A Fossil server also works well as a complete website for acompletOverviewMethods is incl:</p>
	38	+<p>
	39	+set upe accomplished after the server is up
	40	+and running. Once the preliminary configuration is completed
	41	+uploaddatabaand proceed to
	42	+activate the server using one or more of the techniques dSnext two sectiiques described
	43	+in the next two sections.
	44	+</p>additional configuration
	45	+fine-tuning can be accomplished by logging in as an administrator
	46	+containing repositorieusing a single methodconfigured the
	47	+want to keep private. Other post-activation steps include the following:</p>
18	48
19	49	<ol>
20		-listener approachactivation: inetd, xinetdA stand-alone server
21		- <li>Using inetd, xinetd, or stunnel
22		- <li>CGI
23		- <li>SCGI (a.k.a. Simp [ \| a separate article].nding in
24		-"<tt>>
	50	+<li>
	51	+Add additional users accounts so that all team members have approp.</li>
	52	+<li>
	53	+Modify the look-and-feel of site by to accommodatedocumentation</a> then perhaps activate the s feature so that
	54	+visitors can doin-left: 0;
	55	+ ia-title="Howto an email server so that it can send email
	56	+notifications of new check-ins or other activate.
	57	+<li>
25	58
26		-<h2 id="inetd">Serving via inetd is incl:</p>
	59	+<li>
	60	+If you locked downas completely private prior to
	61	+upload, you might want to open up access to the public once you get
	62	+everything working. Or, keepprivate, according to
	63	+your needs.
	64	+</ol>
	65	+
	66	+<p>
	67	+Afte,t</a>
	68	+stage.
	69	+</p></li>
	70	+</ol>
	71	+
	72	+<p>
	73	+Additional configuration can be accthe script runs Fossil to
	74	+appropriate URL, thatafter the server is up
	75	+and running. w To Configure A Fossil Server">
	76	+
	77	+<style type="text/css">
	78	+ p {
	79	+ margin-left: 4em;
	80	+ margin-right: 3em;
	81	+ }
	82	+
	83	+ li p {
	84	+ margin-left: 0;h2n evenPI to give it an evenPI
	85	+Prior to launching a server on, it is best to
	86	+prepareto be served. The easiest wacommand
	87	+on a workstation and then visit the "Setup" menu.
	88	+Minimum preparation actia-title="How To Configure A Fossil Server">
	89	+
	90	+<style type="text/css">
	91	+ p {
	92	+ margin-left: 4em;
	93	+ margin-right: 3em;
	94	+ }
	95	+
	96	+ li p {
	97	+ margin-left: 0;h2n evenPI to give it an evenPI
	98	+Prior to launching a server on, it is best to
	99	+prepareto be served. The easiest wacommand
	100	+on a workstation and then visit the "Setup" menu.
	101	+Minimum preparation actions include:</p>
27	102
28	103	<ol>
29		- See [hat all teYou can als \| this article].nding in
30		-"<tt>>
	104	+<li>
	105	+Ensure that you have an administrator user account and password
	106	+configured. Visit the Setup/Users page to accomplish this.</p></li>
	107	+<li>
	108	+Vi <a
	109	+documentation</a> then perhaps activate the s feature so that
	110	+visitors can doin-left: 0;
	111	+ ia-title="Howto an email server so that it can send email
	112	+notifications of new check-ins or other activate.
	113	+<li>
31	114
32		-<h2 id="sl.wiki#stunneleading,
33		-is just a Fossil server displaying the content of the
34		-=> with a also migrate fro
35		- ia-title="Howt This is the easiest wn also migrate fro
36		- ia-title="Howt This is the easieng in
37		-"<tt>>
	115	+<li>
	116	+If you locked downas completely private prior to
	117	+upload, you might want to open up access to the public once you get
	118	+everything working. Or, keepprivate, according to
	119	+your needs.
	120	+</ol>
38	121
39		-<h2 id="inetd">Serving via inetd is incl:</p>
40		-
41		-<ol>
42		- See [hat all teYou can als \| this article].nding in
43		-"<tt>>
44		-
45		-<h2 id="cgi">Serving via CGI is incl:</p>
46		-
47		-<ol>
48		- See [ \| this article].nding in
49		-"<tt>>
50		-
51		-<h2 id="scgi">Serving via SCGI is incl:</p>
52		-
53		-<ol>
54		- See [on standard output w \| this article].nding in
55		-"<tt>>
56		-debian/nginxtext-align:style="text-align: Windows.org/] website, in, or a directory hierarchy
57		-ving via inetd is incl:</p>
58		-
59		-<ol>
60		-serverT is to use either the
61		-[/help/server\|server] or the [/help/ui\|ui] commands:
62		-
63		-<ul>
64		- <li><b>fossil server</b> <i>REPOSITORY</i>
65		- <li><b>fossil ui</b> <i>REPOSITORY</i>
66		-</ul>
67		-
68		-The <i>REPOSITORY</i> argument is either the name of the repository file, or
69		-a directorerving via inetd is incl:</p>
70		-
71		-named <tt>*.fossil</tt>.
72		-Both of these commands start a Fossil server, usually on TCP port 8080, though
73		-a higher numbered port might also be used if 8080 is already occupied. You can
74		-access these using URLs of the form <b>http://localhost:8080/</b>, or if
75		-<i>REPOSITORY</i> is a directory, URLs of the form
76		-<b>http://localhost:8080/</b><i>repo</i><b>/</b> where <i>repo</i> is the base
77		-name of the repository file wkey differences between "ui" and "server":
78		-
79		-<ul>
80		- <li>"ui" always binds the server to the loopback IP address
81		- (127.0.0.1) so that it cannot serve to other machines.
82		- <li>anyone who visits this URL is treated as the all-powerful Setup
83		- user, which is why the first difference exists.
84		- <li>"ui" launches a local web browser pointed at this URL.
85		-</ul>
86		-
87		-You can omit the <i>REPOSITORY</i> argument if you run one of the above
88		-commands from within a Fossil checkout directorE@1II,Av:<pre>
89		-$ fossil ui # or...
90		-$ fossil serve
91		-</pre></blockquote>
92		-
93		-Note that you can abbreviate Fossil sub-commands, as long as they are
94		-unambiguous. "<tt>server</tt>" can currently be as short as
95		-"<tt>ser</tt>".
96		-
97		-As a more complicated example, you can serve a directory containing
98		-multiple <tt>*.fossil</tt> files like so:
99		-
100		-<blockquote><pre>
101		-$ fossil server --port 9000 --repolist /path/to/repo/dir
102		-</pre></blockquote>
103		-
104		-There is an [/file/tools/fslsrv \| example script] in the Fossil
105		-distribution that wraps <tt>fossil server</tt> to produce more
106		-complicated effects. Feel free to take it, study it, and modify it to
107		-suit your local needs.
108		-
109		-See the [/help/server\|online documentation] for moreK@G0,p:options and arguments you can give to these commandsH@6G,m:
110		-<h2 id="inetd">Fossil as an inetd/xinetd serviceK@1vl,Ez:
111		-A Fossil server can be launched on-demand by inetd or xinetd using
112		-the [/help/http\|fossil http] command. To launch Fossil from inetd, modify
113		-your inetd configuration file (typically "/etc/inetd.conf") to contain a
114		-line something like this:
115		-
116		-<blockquote>
117		-<pre>
118		-80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil
119		-</pre>
120		-</blockquote>
121		-
122		-In this example, you are telling "inetd" that when an incoming connection
123		-appears on TCP port "80", that it should launch the binary "/usr/bin/fossil"
124		-program with the arguments shown.
125		-Obviously you will
126		-need to modify the pathnames for your particular setup.
127		-The final argument is either the name of the fossil repository to be served,
128		-or a directory containing multiple repositories.
129		-
130		-
131		-If you use a non-standard TCP port on
132		-systems where the port-specification must be a symbolic name and cannot be
133		-numeric, add the desired name and port to /etc/services. For example, if
134		-you wanL@1Yk,OL:running on TCP port 12345 instead of 80, you
135		-will need to add:
136		-
137		-<blockquote>
138		-<pre>
139		-fossil 12345/tcp #fossil server
140		-</pre>
141		-</blockquote>
142		-
143		-and use the symbolic name ('fossil' in this example) instead of the numeral ('12345')
144		-in inetd.conf. For details, see the relevant section in your system's documentation, e.g.
145		-the [https://www.freebsd.org/doc/en/books/handbook/network-inetd.html\|FreeBSD Handbook] in
146		-case you use FreeBSD.
147		-
148		-If your system is running xinetd, then the configuration is likely to be
149		-in the file "/etc/xinetd.conf" or in a subfile of "/etc/xinetd.d".
150		-An xinetd configuration file will appear like this:
151		-
152		-<blockquote>
153		-<pre>
154		-service http
155		-{
156		- port = 80
157		- socket_type = stream
158		- wait = no
159		- user = root
160		- server = /usr/bin/fossil
161		- server_args = http /home/fossil/repos/
162		-}
163		-</pre>
164		-</blockquote>
165		-
166		-The xinetd example above has Fossil configured to serve multiple
167		-repositories, contained under the "/home/fossil/repos/" directory.
168		-
169		-In both cases notice that Fossil was launched as root. This is not required,
170		-but if it is done, then Fossil will automatically put itself into a chroot
171		-jail for the user who owns the fossil repository before reading any information
172		-off of the wire.
173		-
174		-Inetd or xinetd must be enabled, and must be (re)started whenever their configuration
175		-changes - consult your system's documentation for details.
176		-
177		-Using inetd or xinetd is a more complex setup
178		-than the "standalone" server, but it has the
179		-advantage of only using system resources when an actual connection is
180		-attempted. If no-one ever connects to that port,H@BF,4W:will
181		-not (automatically) run. It has the disadvantage of requiring "root" access
182		-and therefore may not normally be available to lower-priced "shared" servers
183		-on the Internet.
184		-
185		-The configuration for <tt>stunnel</tt> is similar, but it is covered in
186		-[./ssl.wiki#stunnel\|a separate document]K@6G,N: id="cgi">Fossil as CGIK@1vl,2d:
187		-A Fossil server can also be run from an ordinary web server as a CGI program.
188		-This feature allows Fossil to be seamlessly integrated into a larger website.
189		-CGI is how K@2nS,H: \| self-hosting fJ@2n~,eb: are
190		-implemented.
191		-
192		-To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory
193		-of your web server and having content like this:
194		-
195		-<blockquote><pre>
196		-#!/usr/bin/fossil
197		-repository: /home/fossil/repo.fossil
198		-</pre></blockquote>
199		-
200		-As always, adjust your paths appropriately.
201		-It may be necessary to set permissions properly, or to modify an ".htaccess"
202		-file or make other server-specific changes. Consult the documentation
203		-for your particular web server. In particular, the following permissions are
204		-<em>normally</em> required (but, again, may be different for a particular
205		-configuration):
206		-
207		-<ul>
208		- <li>The Fossil binary (/usr/bin/fossil in the example above)
209		- must be readable/executable, and ALL directories leading up to it
210		- must be readable by the process which executes the CGI.</li>
211		- <li>ALL directories leading to the CGI script must also be readable and the CGI
212		- script itself must be executable for the user under which it will run (which often differs
213		- from the one running the web server - consult your site's documentation or administrator).</li>
214		- <li>The repository file AND the directory containing it must be writable by the same account
215		- which executes the Fossil binary (again, this might differ from the WWW user). The directory
216		- needs to be writable so that SQLite can write its journal files.</li>
217		- <li>Fossil must be able to create temporary files, the default directory
218		- for which depends on the OS. When the CGI process is operating within
219		- a chroot, ensure that this directory exists and is readable/writeable
220		- by the user who executes the Fossil binary.</li>
221		-</ul>
222		-
223		-Once the script is set up correctly, and assuming your server is also set
224		-correctly, you should be able to access your repository with a URL like:
225		-<b>http://mydomain.org/cgi-bin/repo</b> (assuming the "repo" script is
226		-accessible under "cgi-bin", which would be a typical deployment on Apache
227		-for instance).
228		-
229		-To serve multiple repositories from a directory using CGI, use the "directory:"
230		-tag in the CGI script rather than "repository:". You might also want to add
231		-a "notfound:" tag to tell where to redirect if the particular repository requested
232		-by the URL is not found:
233		-
234		-<blockquote><pre>
235		-#!/usr/bin/fossil
236		-directory: /home/fossil/repos
237		-notfound: http://url-to-go-to-if-repo-not-found/
238		-</pre></blockquote>
239		-
240		-Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b>
241		-will serve up the repository "/home/fossil/repos/XYZ.fossil" (if it exists).
242		-
243		-Additional options available to the CGI script are
244		-[./cgi.wiki\|documented separately].
245		-
246		-Note that Fossil itself can be launched as CGI, as described here. But
247		-Fossil can also launchI@1R~,C:\|sub-CGIs toS@1Su,3:].
248		-Z@1TN,K: Note also that the
249		-H@1S0,7p:\|sub-CGI mechanism] works regardless of how the main
250		-Fossil server is launched.
251		-
252		-<h2 id="scgi">Fossil as SCGI</h2>
253		-<blockquote>
254		-
255		-The [/help/server\|fossil server] command, described above as a way of
256		-starting a stand-alone web server, can also be used for SCGI. Simply add
257		-the --scgi command-line option and the stand-alone server will interpret
258		-and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can
259		-be used in combination with a web server (such as [http://nginx.org\|Nginx])
260		-M@2~G,Aa:CGI. A typical Nginx configuration to support SCGI
261		-with Fossil would look something like this:
262		-
263		-<blockquote><pre>
264		-location /demo_project/ {
265		- include scgi_params;
266		- scgi_pass localhost:9000;
267		- scgi_param SCRIPT_NAME "/demo_project";
268		- scgi_param HTTPS "on";
269		-}
270		-</pre></blockquote>
271		-
272		-Note that Fossil requires the SCRIPT_NAME variable
273		-in order to function properly, but Nginx does not provide this
274		-variable by default,
275		-so it is necessary to provide the SCRIPT_NAME parameter in the configuration.
276		-Failure to do this will cause Fossil to return an error.
277		-
278		-All of the features of the stand-alone server mode described above,
279		-such as the ability to serve a directory full ofK@2ny,H:
280		-rather than justK@NT,6d:, work the same way in SCGI mode.
281		-
282		-For security, it is probably a good idea to add the --localhost option
283		-to the [/help/server\|fossil server] command to prevent Fossil from accepting
284		-off-site connections. One might also want to specify the listening TCP port
285		-number, rather than letting Fossil choose one for itself, just to avoid
286		-ambiguity. A typical command to start a Fossil SCGI server
287		-would be something like this:
288		-
289		-<B@2qh,15:<pre>
290		-fossil server $REPOSITORY --scgi --localhost --port 9000
291		-</pre>E@1MD,D:</blockquote>5V@1Vv,16j@1vA,1wOnoJ;
	122	+<p>
	123	+After any signification configuration change, it is a good idea to
	124	+revisit the Setup/Security-Audit page just to dourun in
	125	+SCGI mode</a> — --scgi</tt></a>
	126	+— instead of HTTP mode</a>, which allows it

	--- a/www/server/index.html
	+++ b/www/server/index.html
	@@ -1,291 +1,126 @@
1	<title>her post-activation steps includher poster post-activation steps is incl:</p>













2
3	<ol>
4	<li>
5	Add addieam members have approp.</l].








6
7	by to aData sharing and synchronization can be entirely peer-to-peer.
8	Fossil uses [https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type\|conflict-free replicated data types]
9	to ensure that (in the limit) all participating peers see the exact same content.nding in
10	"<tt>>
11	sh2>But, A Server Can Be Useful is incl:</p>




12
13	<ol>l>
14	<li>
15	Add addnot require a server,
16	but a server does make collaboration easier.
17	A Fossil server also works well as a complete website for acompletOverviewMethods is incl:</p>





18
19	<ol>
20	listener approachactivation: inetd, xinetdA stand-alone server
21	<li>Using inetd, xinetd, or stunnel
22	<li>CGI
23	<li>SCGI (a.k.a. Simp [ \| a separate article].nding in
24	"<tt>>



25
26	<h2 id="inetd">Serving via inetd is incl:</p>










































27
28	<ol>
29	See [hat all teYou can als \| this article].nding in
30	"<tt>>








31
32	<h2 id="sl.wiki#stunneleading,
33	is just a Fossil server displaying the content of the
34	=> with a also migrate fro
35	ia-title="Howt This is the easiest wn also migrate fro
36	ia-title="Howt This is the easieng in
37	"<tt>>
38
39	<h2 id="inetd">Serving via inetd is incl:</p>
40
41	<ol>
42	See [hat all teYou can als \| this article].nding in
43	"<tt>>
44
45	<h2 id="cgi">Serving via CGI is incl:</p>
46
47	<ol>
48	See [ \| this article].nding in
49	"<tt>>
50
51	<h2 id="scgi">Serving via SCGI is incl:</p>
52
53	<ol>
54	See [on standard output w \| this article].nding in
55	"<tt>>
56	debian/nginxtext-align:style="text-align: Windows.org/] website, in, or a directory hierarchy
57	ving via inetd is incl:</p>
58
59	<ol>
60	serverT is to use either the
61	[/help/server\|server] or the [/help/ui\|ui] commands:
62
63	<ul>
64	<li><b>fossil server</b> <i>REPOSITORY</i>
65	<li><b>fossil ui</b> <i>REPOSITORY</i>
66	</ul>
67
68	The <i>REPOSITORY</i> argument is either the name of the repository file, or
69	a directorerving via inetd is incl:</p>
70
71	named <tt>*.fossil</tt>.
72	Both of these commands start a Fossil server, usually on TCP port 8080, though
73	a higher numbered port might also be used if 8080 is already occupied. You can
74	access these using URLs of the form <b>http://localhost:8080/</b>, or if
75	<i>REPOSITORY</i> is a directory, URLs of the form
76	<b>http://localhost:8080/</b><i>repo</i><b>/</b> where <i>repo</i> is the base
77	name of the repository file wkey differences between "ui" and "server":
78
79	<ul>
80	<li>"ui" always binds the server to the loopback IP address
81	(127.0.0.1) so that it cannot serve to other machines.
82	<li>anyone who visits this URL is treated as the all-powerful Setup
83	user, which is why the first difference exists.
84	<li>"ui" launches a local web browser pointed at this URL.
85	</ul>
86
87	You can omit the <i>REPOSITORY</i> argument if you run one of the above
88	commands from within a Fossil checkout directorE@1II,Av:<pre>
89	$ fossil ui # or...
90	$ fossil serve
91	</pre></blockquote>
92
93	Note that you can abbreviate Fossil sub-commands, as long as they are
94	unambiguous. "<tt>server</tt>" can currently be as short as
95	"<tt>ser</tt>".
96
97	As a more complicated example, you can serve a directory containing
98	multiple <tt>*.fossil</tt> files like so:
99
100	<blockquote><pre>
101	$ fossil server --port 9000 --repolist /path/to/repo/dir
102	</pre></blockquote>
103
104	There is an [/file/tools/fslsrv \| example script] in the Fossil
105	distribution that wraps <tt>fossil server</tt> to produce more
106	complicated effects. Feel free to take it, study it, and modify it to
107	suit your local needs.
108
109	See the [/help/server\|online documentation] for moreK@G0,p:options and arguments you can give to these commandsH@6G,m:
110	<h2 id="inetd">Fossil as an inetd/xinetd serviceK@1vl,Ez:
111	A Fossil server can be launched on-demand by inetd or xinetd using
112	the [/help/http\|fossil http] command. To launch Fossil from inetd, modify
113	your inetd configuration file (typically "/etc/inetd.conf") to contain a
114	line something like this:
115
116	<blockquote>
117	<pre>
118	80 stream tcp nowait.1000 root /usr/bin/fossil /usr/bin/fossil http /home/fossil/repo.fossil
119	</pre>
120	</blockquote>
121
122	In this example, you are telling "inetd" that when an incoming connection
123	appears on TCP port "80", that it should launch the binary "/usr/bin/fossil"
124	program with the arguments shown.
125	Obviously you will
126	need to modify the pathnames for your particular setup.
127	The final argument is either the name of the fossil repository to be served,
128	or a directory containing multiple repositories.
129
130
131	If you use a non-standard TCP port on
132	systems where the port-specification must be a symbolic name and cannot be
133	numeric, add the desired name and port to /etc/services. For example, if
134	you wanL@1Yk,OL:running on TCP port 12345 instead of 80, you
135	will need to add:
136
137	<blockquote>
138	<pre>
139	fossil 12345/tcp #fossil server
140	</pre>
141	</blockquote>
142
143	and use the symbolic name ('fossil' in this example) instead of the numeral ('12345')
144	in inetd.conf. For details, see the relevant section in your system's documentation, e.g.
145	the [https://www.freebsd.org/doc/en/books/handbook/network-inetd.html\|FreeBSD Handbook] in
146	case you use FreeBSD.
147
148	If your system is running xinetd, then the configuration is likely to be
149	in the file "/etc/xinetd.conf" or in a subfile of "/etc/xinetd.d".
150	An xinetd configuration file will appear like this:
151
152	<blockquote>
153	<pre>
154	service http
155	{
156	port = 80
157	socket_type = stream
158	wait = no
159	user = root
160	server = /usr/bin/fossil
161	server_args = http /home/fossil/repos/
162	}
163	</pre>
164	</blockquote>
165
166	The xinetd example above has Fossil configured to serve multiple
167	repositories, contained under the "/home/fossil/repos/" directory.
168
169	In both cases notice that Fossil was launched as root. This is not required,
170	but if it is done, then Fossil will automatically put itself into a chroot
171	jail for the user who owns the fossil repository before reading any information
172	off of the wire.
173
174	Inetd or xinetd must be enabled, and must be (re)started whenever their configuration
175	changes - consult your system's documentation for details.
176
177	Using inetd or xinetd is a more complex setup
178	than the "standalone" server, but it has the
179	advantage of only using system resources when an actual connection is
180	attempted. If no-one ever connects to that port,H@BF,4W:will
181	not (automatically) run. It has the disadvantage of requiring "root" access
182	and therefore may not normally be available to lower-priced "shared" servers
183	on the Internet.
184
185	The configuration for <tt>stunnel</tt> is similar, but it is covered in
186	[./ssl.wiki#stunnel\|a separate document]K@6G,N: id="cgi">Fossil as CGIK@1vl,2d:
187	A Fossil server can also be run from an ordinary web server as a CGI program.
188	This feature allows Fossil to be seamlessly integrated into a larger website.
189	CGI is how K@2nS,H: \| self-hosting fJ@2n~,eb: are
190	implemented.
191
192	To run Fossil as CGI, create a CGI script (here called "repo") in the CGI directory
193	of your web server and having content like this:
194
195	<blockquote><pre>
196	#!/usr/bin/fossil
197	repository: /home/fossil/repo.fossil
198	</pre></blockquote>
199
200	As always, adjust your paths appropriately.
201	It may be necessary to set permissions properly, or to modify an ".htaccess"
202	file or make other server-specific changes. Consult the documentation
203	for your particular web server. In particular, the following permissions are
204	<em>normally</em> required (but, again, may be different for a particular
205	configuration):
206
207	<ul>
208	<li>The Fossil binary (/usr/bin/fossil in the example above)
209	must be readable/executable, and ALL directories leading up to it
210	must be readable by the process which executes the CGI.</li>
211	<li>ALL directories leading to the CGI script must also be readable and the CGI
212	script itself must be executable for the user under which it will run (which often differs
213	from the one running the web server - consult your site's documentation or administrator).</li>
214	<li>The repository file AND the directory containing it must be writable by the same account
215	which executes the Fossil binary (again, this might differ from the WWW user). The directory
216	needs to be writable so that SQLite can write its journal files.</li>
217	<li>Fossil must be able to create temporary files, the default directory
218	for which depends on the OS. When the CGI process is operating within
219	a chroot, ensure that this directory exists and is readable/writeable
220	by the user who executes the Fossil binary.</li>
221	</ul>
222
223	Once the script is set up correctly, and assuming your server is also set
224	correctly, you should be able to access your repository with a URL like:
225	<b>http://mydomain.org/cgi-bin/repo</b> (assuming the "repo" script is
226	accessible under "cgi-bin", which would be a typical deployment on Apache
227	for instance).
228
229	To serve multiple repositories from a directory using CGI, use the "directory:"
230	tag in the CGI script rather than "repository:". You might also want to add
231	a "notfound:" tag to tell where to redirect if the particular repository requested
232	by the URL is not found:
233
234	<blockquote><pre>
235	#!/usr/bin/fossil
236	directory: /home/fossil/repos
237	notfound: http://url-to-go-to-if-repo-not-found/
238	</pre></blockquote>
239
240	Once deployed, a URL like: <b>http://mydomain.org/cgi-bin/repo/XYZ</b>
241	will serve up the repository "/home/fossil/repos/XYZ.fossil" (if it exists).
242
243	Additional options available to the CGI script are
244	[./cgi.wiki\|documented separately].
245
246	Note that Fossil itself can be launched as CGI, as described here. But
247	Fossil can also launchI@1R~,C:\|sub-CGIs toS@1Su,3:].
248	Z@1TN,K: Note also that the
249	H@1S0,7p:\|sub-CGI mechanism] works regardless of how the main
250	Fossil server is launched.
251
252	<h2 id="scgi">Fossil as SCGI</h2>
253	<blockquote>
254
255	The [/help/server\|fossil server] command, described above as a way of
256	starting a stand-alone web server, can also be used for SCGI. Simply add
257	the --scgi command-line option and the stand-alone server will interpret
258	and respond to the SimpleCGI or SCGI protocol rather than raw HTTP. This can
259	be used in combination with a web server (such as [http://nginx.org\|Nginx])
260	M@2~G,Aa:CGI. A typical Nginx configuration to support SCGI
261	with Fossil would look something like this:
262
263	<blockquote><pre>
264	location /demo_project/ {
265	include scgi_params;
266	scgi_pass localhost:9000;
267	scgi_param SCRIPT_NAME "/demo_project";
268	scgi_param HTTPS "on";
269	}
270	</pre></blockquote>
271
272	Note that Fossil requires the SCRIPT_NAME variable
273	in order to function properly, but Nginx does not provide this
274	variable by default,
275	so it is necessary to provide the SCRIPT_NAME parameter in the configuration.
276	Failure to do this will cause Fossil to return an error.
277
278	All of the features of the stand-alone server mode described above,
279	such as the ability to serve a directory full ofK@2ny,H:
280	rather than justK@NT,6d:, work the same way in SCGI mode.
281
282	For security, it is probably a good idea to add the --localhost option
283	to the [/help/server\|fossil server] command to prevent Fossil from accepting
284	off-site connections. One might also want to specify the listening TCP port
285	number, rather than letting Fossil choose one for itself, just to avoid
286	ambiguity. A typical command to start a Fossil SCGI server
287	would be something like this:
288
289	<B@2qh,15:<pre>
290	fossil server $REPOSITORY --scgi --localhost --port 9000
291	</pre>E@1MD,D:</blockquote>5V@1Vv,16j@1vA,1wOnoJ;

	--- a/www/server/index.html
	+++ b/www/server/index.html
	@@ -1,291 +1,126 @@
1	ia-title="How To Configure A Fossil Server">
2
3	<style type="text/css">
4	p {
5	margin-left: 4em;
6	margin-right: 3em;
7	}
8
9	li p {
10	margin-left: 0;h2n evenPI to give it an evenPI
11	Prior to launching a server on, it is best to
12	prepareto be served. The easiest wacommand
13	on a workstation and then visit the "Setup" menu.
14	Minimum preparation actions include:</p>
15
16	<ol>
17	<li>
18	Ensure that you have an administrator user account and password
19	configured. Visit the Setup/Users page to accomplish this.</p></li>
20	<li>
21	Visit the Setup/Security-Audit pageYou might want to configureto be completely private
22	for the initial upload and server activatation, then open access up to
23	post-activation configuration refinement</a>
24	stage.
25	</p></li>
26	</ol>
27
28	<p>
29	Additional configuration can be accomplished after the server is up
30	and running. Once the prvery useful</a>.</p>trator
31	and visiting the Setup menu. Pay particular attention to the
32	"Setup/Sec
33	configured the
34	want to keep private. Other post-activation steps include the follodditionalmethods">.
35	</p></li>
36	</ol>
37
38	<p>
39	set upe accomplished after the server is up
40	and running. Once the preliminary configuration is completed
41	uploaddatabaand proceed to
42	activate the server using one or more of the techniques dSnext two sectiiques described
43	in the next two sections.
44	</p>additional configuration
45	fine-tuning can be accomplished by logging in as an administrator
46	containing repositorieusing a single methodconfigured the
47	want to keep private. Other post-activation steps include the following:</p>
48
49	<ol>
50	<li>
51	Add additional users accounts so that all team members have approp.</li>
52	<li>
53	Modify the look-and-feel of site by to accommodatedocumentation</a> then perhaps activate the s feature so that
54	visitors can doin-left: 0;
55	ia-title="Howto an email server so that it can send email
56	notifications of new check-ins or other activate.
57	<li>
58
59	<li>
60	If you locked downas completely private prior to
61	upload, you might want to open up access to the public once you get
62	everything working. Or, keepprivate, according to
63	your needs.
64	</ol>
65
66	<p>
67	Afte,t</a>
68	stage.
69	</p></li>
70	</ol>
71
72	<p>
73	Additional configuration can be accthe script runs Fossil to
74	appropriate URL, thatafter the server is up
75	and running. w To Configure A Fossil Server">
76
77	<style type="text/css">
78	p {
79	margin-left: 4em;
80	margin-right: 3em;
81	}
82
83	li p {
84	margin-left: 0;h2n evenPI to give it an evenPI
85	Prior to launching a server on, it is best to
86	prepareto be served. The easiest wacommand
87	on a workstation and then visit the "Setup" menu.
88	Minimum preparation actia-title="How To Configure A Fossil Server">
89
90	<style type="text/css">
91	p {
92	margin-left: 4em;
93	margin-right: 3em;
94	}
95
96	li p {
97	margin-left: 0;h2n evenPI to give it an evenPI
98	Prior to launching a server on, it is best to
99	prepareto be served. The easiest wacommand
100	on a workstation and then visit the "Setup" menu.
101	Minimum preparation actions include:</p>
102
103	<ol>
104	<li>
105	Ensure that you have an administrator user account and password
106	configured. Visit the Setup/Users page to accomplish this.</p></li>
107	<li>
108	Vi <a
109	documentation</a> then perhaps activate the s feature so that
110	visitors can doin-left: 0;
111	ia-title="Howto an email server so that it can send email
112	notifications of new check-ins or other activate.
113	<li>
114
115	<li>
116	If you locked downas completely private prior to
117	upload, you might want to open up access to the public once you get
118	everything working. Or, keepprivate, according to
119	your needs.
120	</ol>
121
122	<p>
123	After any signification configuration change, it is a good idea to
124	revisit the Setup/Security-Audit page just to dourun in
125	SCGI mode</a> — --scgi</tt></a>
126	— instead of HTTP mode</a>, which allows it

A www/server/index.html

+126

		--- a/www/server/index.html
		+++ b/www/server/index.html
		@@ -0,0 +1,126 @@
	1	+ia-title="How To Configure A Fossil Server">
	2	+
	3	+<style type="text/css">
	4	+ p {
	5	+ margin-left: 4em;
	6	+ margin-right: 3em;
	7	+ }
	8	+
	9	+ li p {
	10	+ margin-left: 0;h2n evenPI to give it an evenPI
	11	+Prior to launching a server on, it is best to
	12	+prepareto be served. The easiest wacommand
	13	+on a workstation and then visit the "Setup" menu.
	14	+Minimum preparation actions include:</p>
	15	+
	16	+<ol>
	17	+<li>
	18	+Ensure that you have an administrator user account and password
	19	+configured. Visit the Setup/Users page to accomplish this.</p></li>
	20	+<li>
	21	+Visit the Setup/Security-Audit pageYou might want to configureto be completely private
	22	+for the initial upload and server activatation, then open access up to
	23	+post-activation configuration refinement</a>
	24	+stage.
	25	+</p></li>
	26	+</ol>
	27	+
	28	+<p>
	29	+Additional configuration can be accomplished after the server is up
	30	+and running. Once the prvery useful</a>.</p>trator
	31	+and visiting the Setup menu. Pay particular attention to the
	32	+"Setup/Sec
	33	+configured the
	34	+want to keep private. Other post-activation steps include the follodditionalmethods">.
	35	+</p></li>
	36	+</ol>
	37	+
	38	+<p>
	39	+set upe accomplished after the server is up
	40	+and running. Once the preliminary configuration is completed
	41	+uploaddatabaand proceed to
	42	+activate the server using one or more of the techniques dSnext two sectiiques described
	43	+in the next two sections.
	44	+</p>additional configuration
	45	+fine-tuning can be accomplished by logging in as an administrator
	46	+containing repositorieusing a single methodconfigured the
	47	+want to keep private. Other post-activation steps include the following:</p>
	48	+
	49	+<ol>
	50	+<li>
	51	+Add additional users accounts so that all team members have approp.</li>
	52	+<li>
	53	+Modify the look-and-feel of site by to accommodatedocumentation</a> then perhaps activate the s feature so that
	54	+visitors can doin-left: 0;
	55	+ ia-title="Howto an email server so that it can send email
	56	+notifications of new check-ins or other activate.
	57	+<li>
	58	+
	59	+<li>
	60	+If you locked downas completely private prior to
	61	+upload, you might want to open up access to the public once you get
	62	+everything working. Or, keepprivate, according to
	63	+your needs.
	64	+</ol>
	65	+
	66	+<p>
	67	+Afte,t</a>
	68	+stage.
	69	+</p></li>
	70	+</ol>
	71	+
	72	+<p>
	73	+Additional configuration can be accthe script runs Fossil to
	74	+appropriate URL, thatafter the server is up
	75	+and running. w To Configure A Fossil Server">
	76	+
	77	+<style type="text/css">
	78	+ p {
	79	+ margin-left: 4em;
	80	+ margin-right: 3em;
	81	+ }
	82	+
	83	+ li p {
	84	+ margin-left: 0;h2n evenPI to give it an evenPI
	85	+Prior to launching a server on, it is best to
	86	+prepareto be served. The easiest wacommand
	87	+on a workstation and then visit the "Setup" menu.
	88	+Minimum preparation actia-title="How To Configure A Fossil Server">
	89	+
	90	+<style type="text/css">
	91	+ p {
	92	+ margin-left: 4em;
	93	+ margin-right: 3em;
	94	+ }
	95	+
	96	+ li p {
	97	+ margin-left: 0;h2n evenPI to give it an evenPI
	98	+Prior to launching a server on, it is best to
	99	+prepareto be served. The easiest wacommand
	100	+on a workstation and then visit the "Setup" menu.
	101	+Minimum preparation actions include:</p>
	102	+
	103	+<ol>
	104	+<li>
	105	+Ensure that you have an administrator user account and password
	106	+configured. Visit the Setup/Users page to accomplish this.</p></li>
	107	+<li>
	108	+Vi <a
	109	+documentation</a> then perhaps activate the s feature so that
	110	+visitors can doin-left: 0;
	111	+ ia-title="Howto an email server so that it can send email
	112	+notifications of new check-ins or other activate.
	113	+<li>
	114	+
	115	+<li>
	116	+If you locked downas completely private prior to
	117	+upload, you might want to open up access to the public once you get
	118	+everything working. Or, keepprivate, according to
	119	+your needs.
	120	+</ol>
	121	+
	122	+<p>
	123	+After any signification configuration change, it is a good idea to
	124	+revisit the Setup/Security-Audit page just to dourun in
	125	+SCGI mode</a> — --scgi</tt></a>
	126	+— instead of HTTP mode</a>, which allows it

	--- a/www/server/index.html
	+++ b/www/server/index.html
	@@ -0,0 +1,126 @@

	--- a/www/server/index.html
	+++ b/www/server/index.html
	@@ -0,0 +1,126 @@
1	ia-title="How To Configure A Fossil Server">
2
3	<style type="text/css">
4	p {
5	margin-left: 4em;
6	margin-right: 3em;
7	}
8
9	li p {
10	margin-left: 0;h2n evenPI to give it an evenPI
11	Prior to launching a server on, it is best to
12	prepareto be served. The easiest wacommand
13	on a workstation and then visit the "Setup" menu.
14	Minimum preparation actions include:</p>
15
16	<ol>
17	<li>
18	Ensure that you have an administrator user account and password
19	configured. Visit the Setup/Users page to accomplish this.</p></li>
20	<li>
21	Visit the Setup/Security-Audit pageYou might want to configureto be completely private
22	for the initial upload and server activatation, then open access up to
23	post-activation configuration refinement</a>
24	stage.
25	</p></li>
26	</ol>
27
28	<p>
29	Additional configuration can be accomplished after the server is up
30	and running. Once the prvery useful</a>.</p>trator
31	and visiting the Setup menu. Pay particular attention to the
32	"Setup/Sec
33	configured the
34	want to keep private. Other post-activation steps include the follodditionalmethods">.
35	</p></li>
36	</ol>
37
38	<p>
39	set upe accomplished after the server is up
40	and running. Once the preliminary configuration is completed
41	uploaddatabaand proceed to
42	activate the server using one or more of the techniques dSnext two sectiiques described
43	in the next two sections.
44	</p>additional configuration
45	fine-tuning can be accomplished by logging in as an administrator
46	containing repositorieusing a single methodconfigured the
47	want to keep private. Other post-activation steps include the following:</p>
48
49	<ol>
50	<li>
51	Add additional users accounts so that all team members have approp.</li>
52	<li>
53	Modify the look-and-feel of site by to accommodatedocumentation</a> then perhaps activate the s feature so that
54	visitors can doin-left: 0;
55	ia-title="Howto an email server so that it can send email
56	notifications of new check-ins or other activate.
57	<li>
58
59	<li>
60	If you locked downas completely private prior to
61	upload, you might want to open up access to the public once you get
62	everything working. Or, keepprivate, according to
63	your needs.
64	</ol>
65
66	<p>
67	Afte,t</a>
68	stage.
69	</p></li>
70	</ol>
71
72	<p>
73	Additional configuration can be accthe script runs Fossil to
74	appropriate URL, thatafter the server is up
75	and running. w To Configure A Fossil Server">
76
77	<style type="text/css">
78	p {
79	margin-left: 4em;
80	margin-right: 3em;
81	}
82
83	li p {
84	margin-left: 0;h2n evenPI to give it an evenPI
85	Prior to launching a server on, it is best to
86	prepareto be served. The easiest wacommand
87	on a workstation and then visit the "Setup" menu.
88	Minimum preparation actia-title="How To Configure A Fossil Server">
89
90	<style type="text/css">
91	p {
92	margin-left: 4em;
93	margin-right: 3em;
94	}
95
96	li p {
97	margin-left: 0;h2n evenPI to give it an evenPI
98	Prior to launching a server on, it is best to
99	prepareto be served. The easiest wacommand
100	on a workstation and then visit the "Setup" menu.
101	Minimum preparation actions include:</p>
102
103	<ol>
104	<li>
105	Ensure that you have an administrator user account and password
106	configured. Visit the Setup/Users page to accomplish this.</p></li>
107	<li>
108	Vi <a
109	documentation</a> then perhaps activate the s feature so that
110	visitors can doin-left: 0;
111	ia-title="Howto an email server so that it can send email
112	notifications of new check-ins or other activate.
113	<li>
114
115	<li>
116	If you locked downas completely private prior to
117	upload, you might want to open up access to the public once you get
118	everything working. Or, keepprivate, according to
119	your needs.
120	</ol>
121
122	<p>
123	After any signification configuration change, it is a good idea to
124	revisit the Setup/Security-Audit page just to dourun in
125	SCGI mode</a> — --scgi</tt></a>
126	— instead of HTTP mode</a>, which allows it

M www/server/macos/service.md

+122

		--- a/www/server/macos/service.md
		+++ b/www/server/macos/service.md
		@@ -0,0 +1,122 @@
	1	+# Serving via launchd on macOS
	2	+
	3	+[`launchd`][ldhome] is the default service management framework on macOS
	4	+[since the release of Tiger in 2005][wpa]. If you want a Fossil server
	5	+to launch in the background on a Mac, it’s the way Apple wants you to do
	6	+it. `launchd` is to macOS as `systemd` is to most modern Linux desktop
	7	+systems. (Indeed, `systemd` arguably reinvented the perfectly good,
	8	+pre-existing `launchd` wheel.)
	9	+
	10	+Unlike in [our `systemd` article](../debian/service.md), we’re not going
	11	+to show the per-user method here, because those so-called
	12	+[LaunchAgents][la] only start when a user is logged into the GUI, and
	13	+they stop when that user logs out. This does not strike us as proper
	14	+“server” behavior, so we’ll stick to system-level LaunchDaemons instead.
	15	+
	16	+However, we will still give two different configurations, just as in the
	17	+`systemd` article: one for a standalone HTTP server, and one using
	18	+socket activation.
	19	+
	20	+For more information on `launchd`, the single best ](launchd.inf.info). The next best is:
	21	+
	22	+ $ man launchd.plist
	23	+
	24	+[la]: http://www.grivet-tools.com/blog/2014/launchdaemons-vs-launchagents/
	25	+[ldhome]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html
	26	+[wpa]: https://en.wikipedia.org/wiki/Launchd
	27	+
	28	+
	29	+
	30	+## Standalone HTTP Server
	31	+
	32	+To configure `launchd` to start Fossil as a standalone HTTP server,
	33	+write the following as `com.example.dev. >WorkingDire
	34	+[`launchd`][ldhome] is t# Serving via launchd on /key>
	35	+ <true/>
	36	+ <dict>
	37	+ <key>Labe <key>log</string>
	38	+ <key>StandardHTTP</string>
	39	+ ev.FossilHTTP</string>
	40	+ <key>ring>/tmp/fossil-inf-info.log</string>
	41	+ <# Serving via launchd on macOS
	42	+
	43	+[` <strin </array>
	44	+ key>WorkingDirec <key>KeepAlive</key>
	45	+ >
	46	+ <key>KeepAeepAlive</key>
	47	+ <true/>
	48	+ >
	49	+ <key>KeepA <key>S <string>/tmp/fossil-error.log</string>
	50	+ /fossil-error.log</string>
	51	+ <key <string>/tmp/fop/fossil-info.log</string>
	52	+ # Serving via launchd on macOlaunchd on macOS
	53	+
	54	+[`launchd`]a launchd on macOS
	55	+
	56	+[`launchd`]es not strike us as proper
	57	+“>
	58	+ <key>KeepAl/dict>
	59	+ or, so we’ll stick to system-level LaunchDaemons instead.
	60	+
	61	+However, we will still give two different configurations, just as in the
	62	+`systemd` article: one for a standalone HTTP server, and one using
	63	+socket activation.
	64	+
	65	+For more information on `launchd`, the single best resource we’ve found
	66	+is [launchd.info](https://launchd.info). The next best is:
	67	+
	68	+ $ man launchd.plist
	69	+
	70	+[la]: http://www.grivet-tools.com/blog/2014/launchdaemons-vs-launchagents/
	71	+[ldhome]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html
	72	+[wpa]: https://en.wikipedia.org/wiki/Launchd
	73	+
	74	+
	75	+
	76	+## Standalone HTTP Server
	77	+
	78	+To configure `launchd` to start Fossil as a standalone HTTP server,
	79	+write the following as `com.example.dev.FossilHTTP.plist`:n macOS
	80	+
	81	+[`launchd`][ldhome] is the default service management framework on macOS
	82	+[s# S"http://www.apple.com/DT
	83	+ "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
	84	+<plist version="1.0">
	85	+<dict>
	86	+ <key>Label</key>
	87	+ <string>com.example.dev.FossilHTTP</string>
	88	+ <key "http://www.apple.co<string>/usr/local/bin/fossil</string>
	89	+ <string>server</string>
	90	+ <string>--port</string>
	91	+ <string>9000</string>
	92	+ <string>repo.fossil</string>
	93	+ </array>
	94	+ <key>WorkingDirectory</key>
	95	+ <string>/Users/you/museum</string>
	96	+ <key>KeepAlive</key>
	97	+ "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
	98	+<plist version="1.0">
	99	+<dict>
	100	+ <key>Label</key>
	101	+ <string>com.example.dev.Fossil</string>
	102	+ <key>StandardOutPath</key>
	103	+ <string>/tmp/fossil-info.log</string>
	104	+ <key>UserName</key>
	105	+ <string>you</string>
	106	+ <key>GroupName</key>
	107	+ <string>staff</string>
	108	+ <key>InitGroups</key>
	109	+ <true/>
	110	+</dict>
	111	+</plist>
	112	+```
	113	+
	114	+In this example, we’re assuming your development organization uses the
	115	+domain name “`dev.example.org`”, that your short macOS login name is
	116	+“`you`”, and that you store your Fossils in “`~/museum`”. Adjust these
	117	+elements of the plist file to suit your local situation.
	118	+
	119	+You might be wondering about the use of `UserName`: isn’t Fossil
	120	+supposed to drop privileges and enter [a `chroot(2)`
	121	+jail](../../chroot.md) when it’s started as root like this? Why do we
	122	+need

	--- a/www/server/macos/service.md
	+++ b/www/server/macos/service.md
	@@ -0,0 +1,122 @@

	--- a/www/server/macos/service.md
	+++ b/www/server/macos/service.md
	@@ -0,0 +1,122 @@
1	# Serving via launchd on macOS
2
3	[`launchd`][ldhome] is the default service management framework on macOS
4	[since the release of Tiger in 2005][wpa]. If you want a Fossil server
5	to launch in the background on a Mac, it’s the way Apple wants you to do
6	it. `launchd` is to macOS as `systemd` is to most modern Linux desktop
7	systems. (Indeed, `systemd` arguably reinvented the perfectly good,
8	pre-existing `launchd` wheel.)
9
10	Unlike in [our `systemd` article](../debian/service.md), we’re not going
11	to show the per-user method here, because those so-called
12	[LaunchAgents][la] only start when a user is logged into the GUI, and
13	they stop when that user logs out. This does not strike us as proper
14	“server” behavior, so we’ll stick to system-level LaunchDaemons instead.
15
16	However, we will still give two different configurations, just as in the
17	`systemd` article: one for a standalone HTTP server, and one using
18	socket activation.
19
20	For more information on `launchd`, the single best ](launchd.inf.info). The next best is:
21
22	$ man launchd.plist
23
24	[la]: http://www.grivet-tools.com/blog/2014/launchdaemons-vs-launchagents/
25	[ldhome]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html
26	[wpa]: https://en.wikipedia.org/wiki/Launchd
27
28
29
30	## Standalone HTTP Server
31
32	To configure `launchd` to start Fossil as a standalone HTTP server,
33	write the following as `com.example.dev. >WorkingDire
34	[`launchd`][ldhome] is t# Serving via launchd on /key>
35	<true/>
36	<dict>
37	<key>Labe <key>log</string>
38	<key>StandardHTTP</string>
39	ev.FossilHTTP</string>
40	<key>ring>/tmp/fossil-inf-info.log</string>
41	<# Serving via launchd on macOS
42
43	[` <strin </array>
44	key>WorkingDirec <key>KeepAlive</key>
45	>
46	<key>KeepAeepAlive</key>
47	<true/>
48	>
49	<key>KeepA <key>S <string>/tmp/fossil-error.log</string>
50	/fossil-error.log</string>
51	<key <string>/tmp/fop/fossil-info.log</string>
52	# Serving via launchd on macOlaunchd on macOS
53
54	[`launchd`]a launchd on macOS
55
56	[`launchd`]es not strike us as proper
57	“>
58	<key>KeepAl/dict>
59	or, so we’ll stick to system-level LaunchDaemons instead.
60
61	However, we will still give two different configurations, just as in the
62	`systemd` article: one for a standalone HTTP server, and one using
63	socket activation.
64
65	For more information on `launchd`, the single best resource we’ve found
66	is [launchd.info](https://launchd.info). The next best is:
67
68	$ man launchd.plist
69
70	[la]: http://www.grivet-tools.com/blog/2014/launchdaemons-vs-launchagents/
71	[ldhome]: https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html
72	[wpa]: https://en.wikipedia.org/wiki/Launchd
73
74
75
76	## Standalone HTTP Server
77
78	To configure `launchd` to start Fossil as a standalone HTTP server,
79	write the following as `com.example.dev.FossilHTTP.plist`:n macOS
80
81	[`launchd`][ldhome] is the default service management framework on macOS
82	[s# S"http://www.apple.com/DT
83	"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
84	<plist version="1.0">
85	<dict>
86	<key>Label</key>
87	<string>com.example.dev.FossilHTTP</string>
88	<key "http://www.apple.co<string>/usr/local/bin/fossil</string>
89	<string>server</string>
90	<string>--port</string>
91	<string>9000</string>
92	<string>repo.fossil</string>
93	</array>
94	<key>WorkingDirectory</key>
95	<string>/Users/you/museum</string>
96	<key>KeepAlive</key>
97	"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
98	<plist version="1.0">
99	<dict>
100	<key>Label</key>
101	<string>com.example.dev.Fossil</string>
102	<key>StandardOutPath</key>
103	<string>/tmp/fossil-info.log</string>
104	<key>UserName</key>
105	<string>you</string>
106	<key>GroupName</key>
107	<string>staff</string>
108	<key>InitGroups</key>
109	<true/>
110	</dict>
111	</plist>
112	```
113
114	In this example, we’re assuming your development organization uses the
115	domain name “`dev.example.org`”, that your short macOS login name is
116	“`you`”, and that you store your Fossils in “`~/museum`”. Adjust these
117	elements of the plist file to suit your local situation.
118
119	You might be wondering about the use of `UserName`: isn’t Fossil
120	supposed to drop privileges and enter [a `chroot(2)`
121	jail](../../chroot.md) when it’s started as root like this? Why do we
122	need

M www/server/whyuseaserver.wiki

+20

		--- a/www/server/whyuseaserver.wiki
		+++ b/www/server/whyuseaserver.wiki
		@@ -0,0 +1,20 @@
	1	+<title>Benefits Of A Fossil Server</title>
	2	+
	3	+<h2>No Server Required</h2>
	4	+
	5	+Fossil does <em>not</em> require a central server.
	6	+Data sharing and synchronization can be entirel peer-to-peer.
	7	+Fossil uses
	8	+[https://en.wikipedia.org/wiki/Conflic\|conflict-free replicated data types]
	9	+to ensure that (in the limit) all participating peers see tAe>Benefits of a Fossil Server</title>
	10	+
	11	+<h2>No Server Required</h2>
	12	+
	13	+Fossil does not require a central server.
	14	+Data sharing and synchronization can be entirely peer-to-peer.
	15	+Fossil uses
	16	+[https://en.wikipedia.org/wiki/Conflict-free_replous2. <b>A server works as a projectplicated data types]
	17	+to ensure that (in the limit) all participating peer
	18	+trouble-tickets, and wiki, and a forum. It shows the status
	19	+ of the project. And the embedded documentation feature provides
	20	+ only instructionse.

	--- a/www/server/whyuseaserver.wiki
	+++ b/www/server/whyuseaserver.wiki
	@@ -0,0 +1,20 @@

	--- a/www/server/whyuseaserver.wiki
	+++ b/www/server/whyuseaserver.wiki
	@@ -0,0 +1,20 @@
1	<title>Benefits Of A Fossil Server</title>
2
3	<h2>No Server Required</h2>
4
5	Fossil does <em>not</em> require a central server.
6	Data sharing and synchronization can be entirel peer-to-peer.
7	Fossil uses
8	[https://en.wikipedia.org/wiki/Conflic\|conflict-free replicated data types]
9	to ensure that (in the limit) all participating peers see tAe>Benefits of a Fossil Server</title>
10
11	<h2>No Server Required</h2>
12
13	Fossil does not require a central server.
14	Data sharing and synchronization can be entirely peer-to-peer.
15	Fossil uses
16	[https://en.wikipedia.org/wiki/Conflict-free_replous2. <b>A server works as a projectplicated data types]
17	to ensure that (in the limit) all participating peer
18	trouble-tickets, and wiki, and a forum. It shows the status
19	of the project. And the embedded documentation feature provides
20	only instructionse.

M www/server/windows/cgi-bin-perm.png

Binary file

M www/server/windows/cgi-exec-perm.png

Binary file

M www/server/windows/cgi-install-iis.png

Binary file

M www/server/windows/cgi-script-map.png

Binary file

M www/server/windows/cgi.md

+115

		--- a/www/server/windows/cgi.md
		+++ b/www/server/windows/cgi.md
		@@ -0,0 +1,115 @@
	1	+# Serving via IIS + CGI
	2	+
	3	+## This Is Not the Method You Are Looking For
	4	+
	5	+Setting up CGI service under IIS is surprisingly complicated compared to
	6	+running Fossil as a CGI under most other operating systems. We recommend
	7	+that you use the simpler [reverse proxying method](./iis.md) instead
	8	+unless there is some compelling reason why that method cannot work for
	9	+you, such as its dependence on non-stock IIS extensions. (Keep in mind
	10	+that both extensions it requires are by Microsoft, not third parties!)
	11	+
	12	+Once you’ve got this scheme working, it gives the same benefits as those
	13	+listed at the top of the linked-to document.
	14	+
	15	+There is a small benefit you get from using CGI over reverse proxying on
	16	+other OSes, which is that the Fossil program only runs briefly in order
	17	+to serve each HTTP hit. Once the request is done, that Fossil instance
	18	+shuts back down, releasing all of its resources. You don’t need to keep
	19	+a background Fossil HTTP server running full-time to provide CGI-based
	20	+Fossil service.
	21	+
	22	+You lose a lot of that benefit on Windows:
	23	+
	24	+1. It only matters to start with on servers that are highly RAM
	25	+ constrained. (Roughly ≤ 128 MiB.) Our configuration steps below
	26	+ assume you’re using the Windows and IIS GUIs, which have RAM
	27	+ requirements well in excess of this, making Fossil’s resource
	28	+ requirements a drop in the bucket next to them. On the [Azure
	29	+ B1s][b1s] virtual machine I used to prepare these instructions, the
	30	+ Windows Server Manager GUI kept filling the VM’s 1 GiB of RAM
	31	+ during feature installation and crashing. I had to upgrade the VM’s
	32	+ RAM to 2 GiB just to get useful work done!
	33	+
	34	+2. Process creation on Windows is [much more expensive][cp] than on the
	35	+ other OSes Fossil runs on, so the benefits of firing up a Fossil
	36	+ executable to process each HTTP request are partially swamped by the
	37	+ overhead of doing so.
	38	+
	39	+Therefore, unless you’re willing to replace all of the GUI configuration
	40	+steps below with command line equivalents, or shut the GUI down entirely
	41	+after configuring IIS, CGI is a much less compelling option on Windows.
	42	+
	43	+WARNING: The following tutorial appears to fail with the current
	44	+(2019-08-17) version of Fossil, [apparently][fbug] due to an inability
	45	+of Fossil to detect that it’s being run in CGI mode.
	46	+
	47	+[b1s]: https://azure.microsoft.com/en-us/blog/introducing-b-series-our-new-burstable-vm-size/
	48	+[cp]: https://stackoverflow.com/a/48244/142454
	49	+[fbug]: https://fossil-scm.org/forum/forumpost/de18dc32c0
	50	+
	51	+
	52	+## Install IIS with CGI Support
	53	+
	54	+The steps for this are identical to those for the [reverse proxying IIS
	55	+setup](./iis.md#install) except that you need to enable CGI in the last
	56	+step, since it isn’t installed by default. For Windows Server, the path
	57	+is:
	58	+
	59	+![Install CGI in IIS](./cgi-install-iis.png)
	60	+
	61	+The path is similar on the consumer-focused versions of Windows, once
	62	+you get to that last step.
	63	+
	64	+
	65	+## Setup
	66	+
	67	+1. Install the Fossil executable to `c:\inetpub\wwwroot\bin` on the web
	68	+ server. We can’t use an executable you might already have because IIS
	69	+ runs under a separate user account, so we need to give that
	70	+ executable special permissions, and that’s easiest to do under the
	71	+ IIS tree:
	72	+
	73	+ ![IIS fossil.exe execute permission](./cgi-bin-perm.png)
	74	+
	75	+2. In IIS Manager (a.k.a. `INETMGR`) drill down into the Sites folder
	76	+ in the left-side pane and right-click your web site’s
	77	+ configuration. (e.g. “Default Web Site”)
	78	+
	79	+3. On that menu say “Add Virtual Directory.” Give it the alias “`cgi`”
	80	+ and point it at a suitable directory, such as
	81	+ “`c:\inetpub\wwwroot\cgi`”.
	82	+
	83	+4. Double-click the “Handler Mappings” icon, then in the right-side
	84	+ pane, click “Add Script Map...” Apply the following settings:
	85	+
	86	+ ![IIS script map dialog](./cgi-script-map.png)
	87	+
	88	+ The Executable path must point to the path we set up in step 1, not
	89	+ to some other `fossil.exe` you may have elsewhere on your system.
	90	+ You will need to change the default “`*.dll`” filter in the Open
	91	+ dialog to “`*.exe`” in order to see it when browsing via the “`...`”
	92	+ button.
	93	+
	94	+5. Create a file called `repo.fslcgi` within the CGI directory you
	95	+ chose in step 3, with a single line like this:
	96	+
	97	+ repository: c:\Users\SOMEONE\museum\repo.fossil
	98	+
	99	+ Give the actual path to the repository, of course.
	100	+
	101	+6. Up at the top level of IIS Manager, double-click the “ISAPI and CGI
	102	+ Restrictions” icon, then click “Add...” in the right-side pane.
	103	+ Give the script you just created permission to execute:
	104	+
	105	+ ![IIS CGI execute permission](./cgi-exec-perm.png)
	106	+
	107	+7. In the right-side pane, click “Restart” to apply this configuration,
	108	+ then test it by visiting the newly-available URL in a browser:
	109	+
	110	+ http://localhost/cgi/repo.fslcgi
	111	+
	112	+For more complicated setups such as “directory” mode, see [the generic
	113	+CGI instructions](../any/cgi.md).
	114	+
	115	+[Return to the top-level Fossil server article.](../)

	--- a/www/server/windows/cgi.md
	+++ b/www/server/windows/cgi.md
	@@ -0,0 +1,115 @@

	--- a/www/server/windows/cgi.md
	+++ b/www/server/windows/cgi.md
	@@ -0,0 +1,115 @@
1	# Serving via IIS + CGI
2
3	## This Is Not the Method You Are Looking For
4
5	Setting up CGI service under IIS is surprisingly complicated compared to
6	running Fossil as a CGI under most other operating systems. We recommend
7	that you use the simpler [reverse proxying method](./iis.md) instead
8	unless there is some compelling reason why that method cannot work for
9	you, such as its dependence on non-stock IIS extensions. (Keep in mind
10	that both extensions it requires are by Microsoft, not third parties!)
11
12	Once you’ve got this scheme working, it gives the same benefits as those
13	listed at the top of the linked-to document.
14
15	There is a small benefit you get from using CGI over reverse proxying on
16	other OSes, which is that the Fossil program only runs briefly in order
17	to serve each HTTP hit. Once the request is done, that Fossil instance
18	shuts back down, releasing all of its resources. You don’t need to keep
19	a background Fossil HTTP server running full-time to provide CGI-based
20	Fossil service.
21
22	You lose a lot of that benefit on Windows:
23
24	1. It only matters to start with on servers that are highly RAM
25	constrained. (Roughly ≤ 128 MiB.) Our configuration steps below
26	assume you’re using the Windows and IIS GUIs, which have RAM
27	requirements well in excess of this, making Fossil’s resource
28	requirements a drop in the bucket next to them. On the [Azure
29	B1s][b1s] virtual machine I used to prepare these instructions, the
30	Windows Server Manager GUI kept filling the VM’s 1 GiB of RAM
31	during feature installation and crashing. I had to upgrade the VM’s
32	RAM to 2 GiB just to get useful work done!
33
34	2. Process creation on Windows is [much more expensive][cp] than on the
35	other OSes Fossil runs on, so the benefits of firing up a Fossil
36	executable to process each HTTP request are partially swamped by the
37	overhead of doing so.
38
39	Therefore, unless you’re willing to replace all of the GUI configuration
40	steps below with command line equivalents, or shut the GUI down entirely
41	after configuring IIS, CGI is a much less compelling option on Windows.
42
43	WARNING: The following tutorial appears to fail with the current
44	(2019-08-17) version of Fossil, [apparently][fbug] due to an inability
45	of Fossil to detect that it’s being run in CGI mode.
46
47	[b1s]: https://azure.microsoft.com/en-us/blog/introducing-b-series-our-new-burstable-vm-size/
48	[cp]: https://stackoverflow.com/a/48244/142454
49	[fbug]: https://fossil-scm.org/forum/forumpost/de18dc32c0
50
51
52	## Install IIS with CGI Support
53
54	The steps for this are identical to those for the [reverse proxying IIS
55	setup](./iis.md#install) except that you need to enable CGI in the last
56	step, since it isn’t installed by default. For Windows Server, the path
57	is:
58
59	![Install CGI in IIS](./cgi-install-iis.png)
60
61	The path is similar on the consumer-focused versions of Windows, once
62	you get to that last step.
63
64
65	## Setup
66
67	1. Install the Fossil executable to `c:\inetpub\wwwroot\bin` on the web
68	server. We can’t use an executable you might already have because IIS
69	runs under a separate user account, so we need to give that
70	executable special permissions, and that’s easiest to do under the
71	IIS tree:
72
73	![IIS fossil.exe execute permission](./cgi-bin-perm.png)
74
75	2. In IIS Manager (a.k.a. `INETMGR`) drill down into the Sites folder
76	in the left-side pane and right-click your web site’s
77	configuration. (e.g. “Default Web Site”)
78
79	3. On that menu say “Add Virtual Directory.” Give it the alias “`cgi`”
80	and point it at a suitable directory, such as
81	“`c:\inetpub\wwwroot\cgi`”.
82
83	4. Double-click the “Handler Mappings” icon, then in the right-side
84	pane, click “Add Script Map...” Apply the following settings:
85
86	![IIS script map dialog](./cgi-script-map.png)
87
88	The Executable path must point to the path we set up in step 1, not
89	to some other `fossil.exe` you may have elsewhere on your system.
90	You will need to change the default “`*.dll`” filter in the Open
91	dialog to “`*.exe`” in order to see it when browsing via the “`...`”
92	button.
93
94	5. Create a file called `repo.fslcgi` within the CGI directory you
95	chose in step 3, with a single line like this:
96
97	repository: c:\Users\SOMEONE\museum\repo.fossil
98
99	Give the actual path to the repository, of course.
100
101	6. Up at the top level of IIS Manager, double-click the “ISAPI and CGI
102	Restrictions” icon, then click “Add...” in the right-side pane.
103	Give the script you just created permission to execute:
104
105	![IIS CGI execute permission](./cgi-exec-perm.png)
106
107	7. In the right-side pane, click “Restart” to apply this configuration,
108	then test it by visiting the newly-available URL in a browser:
109
110	http://localhost/cgi/repo.fslcgi
111
112	For more complicated setups such as “directory” mode, see [the generic
113	CGI instructions](../any/cgi.md).
114
115	[Return to the top-level Fossil server article.](../)

M www/server/windows/iis.md

+52

		--- a/www/server/windows/iis.md
		+++ b/www/server/windows/iis.md
		@@ -0,0 +1,52 @@
	1	+# Serving via IIS
	2	+
	3	+## Why Bother?
	4	+
	5	+The first part of the scheme below sets Fossil up as an HTTP server, so
	6	+you might be wondering why you wouldn’t just modify that to make it
	7	+listen on all network interfaces on TCP port 80, so you can avoid the
	8	+need for IIS entirely. For simple use cases, you can indeed do without
	9	+IIS, but there are several use cases where adding it is helpful:
	10	+
	11	+1. Proxying Fossil with IIS lets you [add TLS encryption][tls], which
	12	+ [Fossil does not currently speak](../../ssl.wiki) in its server role.
	13	+
	14	+2. The URL rewriting we do below allows Fossil to be part of a larger
	15	+ site already being served with IIS.
	16	+
	17	+3. You ca n have a mixed-mode site, with Fossil acting as a powerful
	18	+ dynamic content management service and IIS as a fast static content
	19	+ server. The pure-Fossil alternative requires that you check all of
	20	+ your static content into Fossil as versioned or unversioned
	21	+ artifacts.
	22	+
	23	+This article shows how you can get any combination of those benefits by
	24	+using IIS as a reverse proxy for `fossil server`.
	25	+
	26	+There are other ways to use IIS to serve Fossil, such as [via
	27	+CGI](./cgi.md).
	28	+
	29	+
	30	+## Background Fossil Service Setup
	31	+
	32	+You will need to have the Fossil HTTP server running in the background,
	33	+serving some local repository, bound to localhost on a fixed
	34	+high-numbered TCP port. For the purposes of testing, simply start it by
	35	+hand in your command shell of choice:
	36	+
	37	+ fossil serve --port 9000 --localhost repo.fossil
	38	+
	39	+That command assumes you’ve got `fossil.exe` in your `%PATH%` and you’re
	40	+in a directory holding `repo.fossil`. See [the platform-independent
	41	+instructions](../any/none.md) for further details.
	42	+
	43	+For a more robust setup, we recommend that you [install Fossil as a
	44	+Windows service](./service.md), which will allow Fossil to start at
	45	+system boot, before anyone has logged in interactively.
	46	+
	47	+
	48	+## <a name="install"></a>Install IIS
	49	+
	50	+IIS might not be installed in your system yet, so follow the path
	51	+appropriate to your host OS. We’ve tested only the latest Microsoft
	52	+OSes as of the time of this wri

	--- a/www/server/windows/iis.md
	+++ b/www/server/windows/iis.md
	@@ -0,0 +1,52 @@

	--- a/www/server/windows/iis.md
	+++ b/www/server/windows/iis.md
	@@ -0,0 +1,52 @@
1	# Serving via IIS
2
3	## Why Bother?
4
5	The first part of the scheme below sets Fossil up as an HTTP server, so
6	you might be wondering why you wouldn’t just modify that to make it
7	listen on all network interfaces on TCP port 80, so you can avoid the
8	need for IIS entirely. For simple use cases, you can indeed do without
9	IIS, but there are several use cases where adding it is helpful:
10
11	1. Proxying Fossil with IIS lets you [add TLS encryption][tls], which
12	[Fossil does not currently speak](../../ssl.wiki) in its server role.
13
14	2. The URL rewriting we do below allows Fossil to be part of a larger
15	site already being served with IIS.
16
17	3. You ca n have a mixed-mode site, with Fossil acting as a powerful
18	dynamic content management service and IIS as a fast static content
19	server. The pure-Fossil alternative requires that you check all of
20	your static content into Fossil as versioned or unversioned
21	artifacts.
22
23	This article shows how you can get any combination of those benefits by
24	using IIS as a reverse proxy for `fossil server`.
25
26	There are other ways to use IIS to serve Fossil, such as [via
27	CGI](./cgi.md).
28
29
30	## Background Fossil Service Setup
31
32	You will need to have the Fossil HTTP server running in the background,
33	serving some local repository, bound to localhost on a fixed
34	high-numbered TCP port. For the purposes of testing, simply start it by
35	hand in your command shell of choice:
36
37	fossil serve --port 9000 --localhost repo.fossil
38
39	That command assumes you’ve got `fossil.exe` in your `%PATH%` and you’re
40	in a directory holding `repo.fossil`. See [the platform-independent
41	instructions](../any/none.md) for further details.
42
43	For a more robust setup, we recommend that you [install Fossil as a
44	Windows service](./service.md), which will allow Fossil to start at
45	system boot, before anyone has logged in interactively.
46
47
48	## <a name="install"></a>Install IIS
49
50	IIS might not be installed in your system yet, so follow the path
51	appropriate to your host OS. We’ve tested only the latest Microsoft
52	OSes as of the time of this wri

M www/server/windows/index.md

+4

		--- a/www/server/windows/index.md
		+++ b/www/server/windows/index.md
		@@ -0,0 +1,4 @@
	1	+# Using Windows as as a Service](service.md)
	2	+- [Using stunn with Fossil on Windows](./stunnel.md)
	3	+
	4	+*[Return to the top-level Fos

	--- a/www/server/windows/index.md
	+++ b/www/server/windows/index.md
	@@ -0,0 +1,4 @@

	--- a/www/server/windows/index.md
	+++ b/www/server/windows/index.md
	@@ -0,0 +1,4 @@
1	# Using Windows as as a Service](service.md)
2	- [Using stunn with Fossil on Windows](./stunnel.md)
3
4	*[Return to the top-level Fos

M www/server/windows/none.md

+69

		--- a/www/server/windows/none.md
		+++ b/www/server/windows/none.md
		@@ -0,0 +1,69 @@
	1	+# Serving as a Standalone Server on Windows
	2	+
	3	+On Windows, this method works more or less identically to how it’s
	4	+documented in [the generic instructions](../any/none.md).
	5	+
	6	+...but only while `fossil.exe` is actually running, which is the source
	7	+of much trouble on Windows. This problem has two halves:
	8	+
	9	+
	10	+## No App Startup Without Desktop
	11	+
	12	+The easy methods for starting a program in Windows at system start all
	13	+require an interactive desktop. There is no easy way to start an arbitrary
	14	+program on Windows at boot before anyone has logged in. In Unix
	15	+terms, Windows has no simple equivalent to [the `/etc/rc.local` file][rcl].
	16	+
	17	+You can partially get around the first problem by setting your `fossil
	18	+server` call up as one of the user’s interactive startup items. Windows
	19	+10 has its own [idiosyncratic way of doing this][si10], and in older
	20	+systems you have [several alternatives to this][si7]. Regardless of the
	21	+actual mechanism, these will cause the Fossil standalone HTTP server to
	22	+start on an interactive desktop login only. While you’re sitting at
	23	+the Windows login screen, the Fossil server is down.
	24	+
	25	+[rcl]: http://nixdoc.net/man-pages/FreeBSD/man8/rc.local.8.html
	26	+[si10]: https://www.tenforums.com/tutorials/2944-add-delete-enable-disable-startup-items-windows-10-a.html
	27	+[si7]: https://www.wikihow.com/Change-Startup-Programs-in-Windows-7
	28	+
	29	+
	30	+
	31	+## No Simple Background Mode
	32	+
	33	+Windows also lacks a direct equivalent of the Bourne shell’s “`&`” control operator to
	34	+run a program in the background, which you can give in Unix’s `rc.local`
	35	+file, which is just a normal Bourne shell script.
	36	+
	37	+By “background,” I mean
	38	+“not attached to any interactive user’s login session.” When the
	39	+`rc.local` script exits in Unix, any program it backgrounded *stays
	40	+running*. There is no simple and direct equivalent to this mechanism in
	41	+Windows.
	42	+
	43	+If you set `fossil server` to run on interactive login, as above, it
	44	+will shut right back down again when that user logs back out.
	45	+
	46	+With Windows 10, it’s especially problematic because you can no longer
	47	+make the OS put off updates arbitrarily: your Fossil server will go down
	48	+every time Windows Update decides it needs to reboot your computer, and
	49	+then Fossil service will stay down until someone logs back into that
	50	+machine interactively.
	51	+
	52	+
	53	+## Better Solutions
	54	+
	55	+Because of these problems, we only recommend setting `fossil server` up
	56	+on Windows this way when
	57	+you’re a solo developer or you work in a small office where everyone
	58	+arrives more or less at the same time each day, and everyone goes home
	59	+about the same time each day, so that one user can keep the Fossil
	60	+server up through the working day.
	61	+
	62	+If your needs go at all beyond this, you should expect proper “server”
	63	+behavior, which you can get on Windows by [registering Fossil as a
	64	+Windows service](./service.md), which solves the interactive startup and
	65	+shutdown problems above, at a bit of complexity over the Startup Items
	66	+method. You may also want to consider putting that service behind [an
	67	+IIS front-end proxy](./iis.md) to add additional web serving features.
	68	+
	69	+[Return to the top-level Fossil server article.](../)

	--- a/www/server/windows/none.md
	+++ b/www/server/windows/none.md
	@@ -0,0 +1,69 @@

	--- a/www/server/windows/none.md
	+++ b/www/server/windows/none.md
	@@ -0,0 +1,69 @@
1	# Serving as a Standalone Server on Windows
2
3	On Windows, this method works more or less identically to how it’s
4	documented in [the generic instructions](../any/none.md).
5
6	...but only while `fossil.exe` is actually running, which is the source
7	of much trouble on Windows. This problem has two halves:
8
9
10	## No App Startup Without Desktop
11
12	The easy methods for starting a program in Windows at system start all
13	require an interactive desktop. There is no easy way to start an arbitrary
14	program on Windows at boot before anyone has logged in. In Unix
15	terms, Windows has no simple equivalent to [the `/etc/rc.local` file][rcl].
16
17	You can partially get around the first problem by setting your `fossil
18	server` call up as one of the user’s interactive startup items. Windows
19	10 has its own [idiosyncratic way of doing this][si10], and in older
20	systems you have [several alternatives to this][si7]. Regardless of the
21	actual mechanism, these will cause the Fossil standalone HTTP server to
22	start on an interactive desktop login only. While you’re sitting at
23	the Windows login screen, the Fossil server is down.
24
25	[rcl]: http://nixdoc.net/man-pages/FreeBSD/man8/rc.local.8.html
26	[si10]: https://www.tenforums.com/tutorials/2944-add-delete-enable-disable-startup-items-windows-10-a.html
27	[si7]: https://www.wikihow.com/Change-Startup-Programs-in-Windows-7
28
29
30
31	## No Simple Background Mode
32
33	Windows also lacks a direct equivalent of the Bourne shell’s “`&`” control operator to
34	run a program in the background, which you can give in Unix’s `rc.local`
35	file, which is just a normal Bourne shell script.
36
37	By “background,” I mean
38	“not attached to any interactive user’s login session.” When the
39	`rc.local` script exits in Unix, any program it backgrounded *stays
40	running*. There is no simple and direct equivalent to this mechanism in
41	Windows.
42
43	If you set `fossil server` to run on interactive login, as above, it
44	will shut right back down again when that user logs back out.
45
46	With Windows 10, it’s especially problematic because you can no longer
47	make the OS put off updates arbitrarily: your Fossil server will go down
48	every time Windows Update decides it needs to reboot your computer, and
49	then Fossil service will stay down until someone logs back into that
50	machine interactively.
51
52
53	## Better Solutions
54
55	Because of these problems, we only recommend setting `fossil server` up
56	on Windows this way when
57	you’re a solo developer or you work in a small office where everyone
58	arrives more or less at the same time each day, and everyone goes home
59	about the same time each day, so that one user can keep the Fossil
60	server up through the working day.
61
62	If your needs go at all beyond this, you should expect proper “server”
63	behavior, which you can get on Windows by [registering Fossil as a
64	Windows service](./service.md), which solves the interactive startup and
65	shutdown problems above, at a bit of complexity over the Startup Items
66	method. You may also want to consider putting that service behind [an
67	IIS front-end proxy](./iis.md) to add additional web serving features.
68
69	[Return to the top-level Fossil server article.](../)

M www/server/windows/service.md

+15

		--- a/www/server/windows/service.md
		+++ b/www/server/windows/service.md
		@@ -0,0 +1,15 @@
	1	+# Fossil as a WiDir(...) API. -DSCM' running under the local
	2	+s
	3	+ running u 80 by default. `fossil winsrv`
	4	+ default. `fossil winsrv` car<a name='PowerShell'></a>
	5	+### (x86)\Fossil This
	6	+way Fossil is inYou do NOT
	7	+ Make Fossil a WindowsAs of Fossil 2.9 the built in API. -DSCM' runni# Fossil as a WiDir(...) API. -DSCM' running under the local
	8	+s
	9	+ running u (x86)\FossilSCM\fossil.exe"
	10	+paths passed to Fossil. Windows
	11	+has
	12	+...) API. -DSCM' running under the local
	13	+s
	14	+ running u 80 by default.# Fossil repository,
	15	+ to the

	--- a/www/server/windows/service.md
	+++ b/www/server/windows/service.md
	@@ -0,0 +1,15 @@

	--- a/www/server/windows/service.md
	+++ b/www/server/windows/service.md
	@@ -0,0 +1,15 @@
1	# Fossil as a WiDir(...) API. -DSCM' running under the local
2	s
3	running u 80 by default. `fossil winsrv`
4	default. `fossil winsrv` car<a name='PowerShell'></a>
5	### (x86)\Fossil This
6	way Fossil is inYou do NOT
7	Make Fossil a WindowsAs of Fossil 2.9 the built in API. -DSCM' runni# Fossil as a WiDir(...) API. -DSCM' running under the local
8	s
9	running u (x86)\FossilSCM\fossil.exe"
10	paths passed to Fossil. Windows
11	has
12	...) API. -DSCM' running under the local
13	s
14	running u 80 by default.# Fossil repository,
15	to the

M www/server/windows/stunnel.md

+129

		--- a/www/server/windows/stunnel.md
		+++ b/www/server/windows/stunnel.md
		@@ -0,0 +1,129 @@
	1	+Following most of [Fossil as a Windows Service](./service.md), you will need
	2	+to change the command to install the Fossil Service to configure it properly for
	3	+ configure
	4	+it properly for instead:
	5	+
	6	+```PowerShell
	7	+ following:
	8	+
	9	+```PowerShell
	10	+New-Service -Name fossil-secure -DisplayName fossil-secure -Binary (x86)\FossilSCM\fossil.exe"
	11	+iles\FossilSCM\fossil.exe" server --localhost --port 9000 --https --repolist "D:/Path/to/Repo
	12	+```
	13	+
	14	+The use of `--localhost` means Fossil will only listen for traffic on the local
	15	+host on the designated port - 9000 in this case - and will not respond to
	16	+network traffic. Using `--https` will tell Fossil to generate HTTPS URLs rather
	17	+than HTTP ones.
	18	+
	19	+`New-Service` does not automatically start a service on install, so you will
	20	+need to enter the following to avoid rebooting the server:
	21	+
	22	+```PowerShell
	23	+Start-Service -Name fossil-secure
	24	+```
	25	+
	26	+wershell is 6.0 or above.
	27	+
	28	+## Install stunnel 5.55
	29	+
	30	+Download stunnel from the [downloads](https://www.stunnel.org/downloads.html)
	31	+page. Select the latest stunnel windows package (at the time of writing this is
	32	+`stunnel-5.55-win64-installer.exe`). Execute the installer and make sure you
	33	+install openSSL tools when you install stunnel. You will need this to convert
	34	+your certificate from PFX to PEM format.
	35	+
	36	+Even though the installer says it is for win64, it installs stunnel by default
	37	+to `\Program Files (x86)\stunnel`.
	38	+
	39	+## Get your certificate ready for Stunnel
	40	+
	41	+Whether you use a Public Certificate Authority or Internal Certificate
	42	+Authority, the next step is exporting the certificate from Windows into a format
	43	+useable by Stunnel.
	44	+
	45	+### Export Certificate from Windows
	46	+
	47	+If your certificate is installed via Windows Certificate Management, you will
	48	+need to export the certificate into a usable format. You can do this either
	49	+using the Windows Certificate Management Console, or PowerShell.
	50	+
	51	+#### Certificate Management Console
	52	+
	53	+Start `mmc.exe` as an Administrator. Select 'File>Add/Remove Snapin', select
	54	+'Certificates' from the list, and click 'Add'. Select 'Computer Account',
	55	+'Next', 'Local Computer', and then 'Finish'. In the Console Root, expand
	56	+'Certificates', then 'Personal', and select 'Certificates'. In the middle pane
	57	+find and select your certificate. Right click the certificate and select
	58	+'All Tasks>Export'. You want to export as PFX the Private Key, include all
	59	+certificates in the certification path, and use a password only to secure the
	60	+file. Enter a path and file name to a working directory and complete the
	61	+export.
	62	+
	63	+Continue with [Convert Certificate from PFX to PEM](#convert).
	64	+
	65	+#### PowerShell
	66	+
	67	+If you know the Friendly
	68	+Name of the Certificate this is relatively easy. Since you need to export
	69	+the private key as well, you must run the following from an Administrative
	70	+PowerShell console.
	71	+
	72	+```PowerShell
	73	+$passwd = ConvertTo-SecureString -string "yourpassword" -Force -AsPlainText
	74	+
	75	+Get-ChildItem Cert:\LocalMachine\My \| Where{$_.FriendlyName -eq "FriendlyName"} \|
	76	+Export-PfxCertificate -FilePath fossil-scm.pfx -Password $passwd
	77	+```
	78	+
	79	+You will now have your certificatename="convert"></a>
	80	+### Convert Certificate from PFX to PEM
	81	+
	82	+For this step you will need the openssl tools that were installed with stunnel.
	83	+
	84	+```PowerShell
	85	+# Add stunnel\bin directory to path for this session.
	86	+$env:PATH += ";${env:ProgramFiles(x86)}\stunnel\bin"
	87	+# Export Private Key
	88	+openssl.exe pkcs12 -in fossil-scm.pfx -out fossil-scm.key -nocerts -nodes
	89	+# Export the Certificate
	90	+openssl.exe pkcs12 -in fossil-scm.pfx -out fossil-scm.pem -nokeys
	91	+```
	92	+
	93	+Now move `fossil-scm.key` and `fossil-scm.pem` to your stunnel config directory
	94	+(by default this should be located at `\Program Files (x86)\stunne\config`).
	95	+
	96	+## stunnel Configuration
	97	+
	98	+Use the reverse proxy configuration given in the generic [Serving via
	99	+stunnel document](../any/stunnel.md#proxy). On Windows, the
	100	+`stunnel.conf` file is located at `\Program Files (x86)\stunnel\config`.
	101	+
	102	+You will need to modify it to point at the PEM and key files generated
	103	+above.
	104	+
	105	+After completing the above configuration restart the stunnel service in Windows
	106	+with the following:
	107	+
	108	+```PowerShell
	109	+Restart-Service -Name stunnel
	110	+```
	111	+
	112	+## Open up port 443 in the Windows Firewall
	113	+
	114	+The following instructions are for the [Windows Advanced
	115	+Firewall](https://docs.microsoft.com/en-us/windows/security/threat-protection/windows-firewall/windows-firewall-with-advanced-security).
	116	+If you are using a different Firewall, please consult your Firewall
	117	+documentation for how to open port 443 for inbound traffic.
	118	+
	119	+The following command should be entered all on one line.
	120	+
	121	+```PowerShell
	122	+New-NetFirewallRule -DisplayName "Allow Fossil Inbound" -Description "Allow Fossil inbound on port 443 using Stunnel as TLS Proxy."
	123	+ -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow -Program "C:\Program Files (x86)\Stunnel\bin\stunnel.exe"
	124	+```
	125	+
	126	+You should now be able to access your new Fossil Server via HTTPS.
	127	+
	128	+
	129	+*[

	--- a/www/server/windows/stunnel.md
	+++ b/www/server/windows/stunnel.md
	@@ -0,0 +1,129 @@

	--- a/www/server/windows/stunnel.md
	+++ b/www/server/windows/stunnel.md
	@@ -0,0 +1,129 @@
1	Following most of [Fossil as a Windows Service](./service.md), you will need
2	to change the command to install the Fossil Service to configure it properly for
3	configure
4	it properly for instead:
5
6	```PowerShell
7	following:
8
9	```PowerShell
10	New-Service -Name fossil-secure -DisplayName fossil-secure -Binary (x86)\FossilSCM\fossil.exe"
11	iles\FossilSCM\fossil.exe" server --localhost --port 9000 --https --repolist "D:/Path/to/Repo
12	```
13
14	The use of `--localhost` means Fossil will only listen for traffic on the local
15	host on the designated port - 9000 in this case - and will not respond to
16	network traffic. Using `--https` will tell Fossil to generate HTTPS URLs rather
17	than HTTP ones.
18
19	`New-Service` does not automatically start a service on install, so you will
20	need to enter the following to avoid rebooting the server:
21
22	```PowerShell
23	Start-Service -Name fossil-secure
24	```
25
26	wershell is 6.0 or above.
27
28	## Install stunnel 5.55
29
30	Download stunnel from the [downloads](https://www.stunnel.org/downloads.html)
31	page. Select the latest stunnel windows package (at the time of writing this is
32	`stunnel-5.55-win64-installer.exe`). Execute the installer and make sure you
33	install openSSL tools when you install stunnel. You will need this to convert
34	your certificate from PFX to PEM format.
35
36	Even though the installer says it is for win64, it installs stunnel by default
37	to `\Program Files (x86)\stunnel`.
38
39	## Get your certificate ready for Stunnel
40
41	Whether you use a Public Certificate Authority or Internal Certificate
42	Authority, the next step is exporting the certificate from Windows into a format
43	useable by Stunnel.
44
45	### Export Certificate from Windows
46
47	If your certificate is installed via Windows Certificate Management, you will
48	need to export the certificate into a usable format. You can do this either
49	using the Windows Certificate Management Console, or PowerShell.
50
51	#### Certificate Management Console
52
53	Start `mmc.exe` as an Administrator. Select 'File>Add/Remove Snapin', select
54	'Certificates' from the list, and click 'Add'. Select 'Computer Account',
55	'Next', 'Local Computer', and then 'Finish'. In the Console Root, expand
56	'Certificates', then 'Personal', and select 'Certificates'. In the middle pane
57	find and select your certificate. Right click the certificate and select
58	'All Tasks>Export'. You want to export as PFX the Private Key, include all
59	certificates in the certification path, and use a password only to secure the
60	file. Enter a path and file name to a working directory and complete the
61	export.
62
63	Continue with [Convert Certificate from PFX to PEM](#convert).
64
65	#### PowerShell
66
67	If you know the Friendly
68	Name of the Certificate this is relatively easy. Since you need to export
69	the private key as well, you must run the following from an Administrative
70	PowerShell console.
71
72	```PowerShell
73	$passwd = ConvertTo-SecureString -string "yourpassword" -Force -AsPlainText
74
75	Get-ChildItem Cert:\LocalMachine\My \| Where{$_.FriendlyName -eq "FriendlyName"} \|
76	Export-PfxCertificate -FilePath fossil-scm.pfx -Password $passwd
77	```
78
79	You will now have your certificatename="convert"></a>
80	### Convert Certificate from PFX to PEM
81
82	For this step you will need the openssl tools that were installed with stunnel.
83
84	```PowerShell
85	# Add stunnel\bin directory to path for this session.
86	$env:PATH += ";${env:ProgramFiles(x86)}\stunnel\bin"
87	# Export Private Key
88	openssl.exe pkcs12 -in fossil-scm.pfx -out fossil-scm.key -nocerts -nodes
89	# Export the Certificate
90	openssl.exe pkcs12 -in fossil-scm.pfx -out fossil-scm.pem -nokeys
91	```
92
93	Now move `fossil-scm.key` and `fossil-scm.pem` to your stunnel config directory
94	(by default this should be located at `\Program Files (x86)\stunne\config`).
95
96	## stunnel Configuration
97
98	Use the reverse proxy configuration given in the generic [Serving via
99	stunnel document](../any/stunnel.md#proxy). On Windows, the
100	`stunnel.conf` file is located at `\Program Files (x86)\stunnel\config`.
101
102	You will need to modify it to point at the PEM and key files generated
103	above.
104
105	After completing the above configuration restart the stunnel service in Windows
106	with the following:
107
108	```PowerShell
109	Restart-Service -Name stunnel
110	```
111
112	## Open up port 443 in the Windows Firewall
113
114	The following instructions are for the [Windows Advanced
115	Firewall](https://docs.microsoft.com/en-us/windows/security/threat-protection/windows-firewall/windows-firewall-with-advanced-security).
116	If you are using a different Firewall, please consult your Firewall
117	documentation for how to open port 443 for inbound traffic.
118
119	The following command should be entered all on one line.
120
121	```PowerShell
122	New-NetFirewallRule -DisplayName "Allow Fossil Inbound" -Description "Allow Fossil inbound on port 443 using Stunnel as TLS Proxy."
123	-Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow -Program "C:\Program Files (x86)\Stunnel\bin\stunnel.exe"
124	```
125
126	You should now be able to access your new Fossil Server via HTTPS.
127
128
129	*[

M www/serverext.wiki

+5 -5

		--- www/serverext.wiki
		+++ www/serverext.wiki
		@@ -1,10 +1,10 @@
1	1	<title>CGI Server Extensions</title>
2	2
3	3	<h2>1.0 Introduction</h2>
4	4
5		-If you have a [./server.wiki\|Fossil server] for your project,
	5	+If you have a [./server/\|Fossil server] for your project,
6	6	you can add [https://en.wikipedia.org/wiki/Common_Gateway_Interface\|CGI]
7	7	extensions to that server. These extensions work like
8	8	any other CGI program, except that they also have access to the Fossil
9	9	login information and can (optionally) leverage the "skins" of Fossil
10	10	so that they appear to be more tightly integrated into the project.
		@@ -27,21 +27,21 @@
27	27
28	28	CGI Extensions are disabled by default.
29	29	An administrator activates the CGI extension mechanism by specifying
30	30	an "Extension Root Directory" or "extroot" as part of the server setup.
31	31	If the Fossil server is itself run as
32		-[./server.wiki#cgi\|CGI], then add a line to the
	32	+[./server/any/cgi.md\|CGI], then add a line to the
33	33	[./cgi.wiki#extroot\|CGI script file] that says:
34	34
35	35	<blockquote><pre>
36	36	extroot: <i>DIRECTORY</i>
37	37	</pre></blockquote>
38	38
39	39	Or, if the Fossil server is begin run as using the
40		-"[./server.wiki#standalone\|fossil server]" or
41		-"[./server.wiki#standalone\|fossil ui]" or
42		-"[./server.wiki#inetd\|fossil http]" commands, then add an extra
	40	+"[./server/any/none.md\|fossil server]" or
	41	+"[./server/any/none.md\|fossil ui]" or
	42	+"[./server/any/inetd.md\|fossil http]" commands, then add an extra
43	43	"--extroot <i>DIRECTORY</i>" option to that command.
44	44
45	45	The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI.
46	46	Files in the DOCUMENT_ROOT are accessed via URLs like this:
47	47
48	48

	--- www/serverext.wiki
	+++ www/serverext.wiki
	@@ -1,10 +1,10 @@
1	<title>CGI Server Extensions</title>
2
3	<h2>1.0 Introduction</h2>
4
5	If you have a [./server.wiki\|Fossil server] for your project,
6	you can add [https://en.wikipedia.org/wiki/Common_Gateway_Interface\|CGI]
7	extensions to that server. These extensions work like
8	any other CGI program, except that they also have access to the Fossil
9	login information and can (optionally) leverage the "skins" of Fossil
10	so that they appear to be more tightly integrated into the project.
	@@ -27,21 +27,21 @@
27
28	CGI Extensions are disabled by default.
29	An administrator activates the CGI extension mechanism by specifying
30	an "Extension Root Directory" or "extroot" as part of the server setup.
31	If the Fossil server is itself run as
32	[./server.wiki#cgi\|CGI], then add a line to the
33	[./cgi.wiki#extroot\|CGI script file] that says:
34
35	<blockquote><pre>
36	extroot: <i>DIRECTORY</i>
37	</pre></blockquote>
38
39	Or, if the Fossil server is begin run as using the
40	"[./server.wiki#standalone\|fossil server]" or
41	"[./server.wiki#standalone\|fossil ui]" or
42	"[./server.wiki#inetd\|fossil http]" commands, then add an extra
43	"--extroot <i>DIRECTORY</i>" option to that command.
44
45	The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI.
46	Files in the DOCUMENT_ROOT are accessed via URLs like this:
47
48

	--- www/serverext.wiki
	+++ www/serverext.wiki
	@@ -1,10 +1,10 @@
1	<title>CGI Server Extensions</title>
2
3	<h2>1.0 Introduction</h2>
4
5	If you have a [./server/\|Fossil server] for your project,
6	you can add [https://en.wikipedia.org/wiki/Common_Gateway_Interface\|CGI]
7	extensions to that server. These extensions work like
8	any other CGI program, except that they also have access to the Fossil
9	login information and can (optionally) leverage the "skins" of Fossil
10	so that they appear to be more tightly integrated into the project.
	@@ -27,21 +27,21 @@
27
28	CGI Extensions are disabled by default.
29	An administrator activates the CGI extension mechanism by specifying
30	an "Extension Root Directory" or "extroot" as part of the server setup.
31	If the Fossil server is itself run as
32	[./server/any/cgi.md\|CGI], then add a line to the
33	[./cgi.wiki#extroot\|CGI script file] that says:
34
35	<blockquote><pre>
36	extroot: <i>DIRECTORY</i>
37	</pre></blockquote>
38
39	Or, if the Fossil server is begin run as using the
40	"[./server/any/none.md\|fossil server]" or
41	"[./server/any/none.md\|fossil ui]" or
42	"[./server/any/inetd.md\|fossil http]" commands, then add an extra
43	"--extroot <i>DIRECTORY</i>" option to that command.
44
45	The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI.
46	Files in the DOCUMENT_ROOT are accessed via URLs like this:
47
48

M www/ssl.wiki

+8 -63

		--- www/ssl.wiki
		+++ www/ssl.wiki
		@@ -1,6 +1,6 @@
1		-<title>TLS and Fossil</title>
	1	+<title>Securing a Repository with TLS</title>
2	2
3	3	<h2>Using TLS-Encrypted Communications with Fossil</h2>
4	4
5	5	If you are storing sensitive information in a repository accessible over
6	6	a network whose integrity you do not fully trust, you should use TLS to
		@@ -206,72 +206,17 @@
206	206	<h2 id="server">Fossil TLS Configuration: Server Side</h2>
207	207
208	208	Fossil's built-in HTTP server feature does not currently have a built-in
209	209	way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked
210	210	Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put
211		-it behind some kind of HTTPS proxy.
212		-
213		-
214		-<h3 id="stunnel">stunnel Alone</h3>
215		-
216		-[https://www.stunnel.org/ \| <tt>stunnel</tt>] is an
217		-[https://en.wikipedia.org/wiki/Inetd \| <tt>inetd</tt>]-like process that
218		-accepts and decodes TLS-encrypted connections. It can directly proxy
219		-Fossil communications, allowing secure TLS-encrypted communications to a
220		-Fossil repository server. You simply need to install <tt>stunnel</tt>
221		-and then place something like this in its main configuration file,
222		-<tt>stunnel.conf</tt>:
223		-
224		-<nowiki><pre>
225		- [https]
226		- accept = www.ubercool-project.org:443
227		- TIMEOUTclose = 0
228		- exec = /usr/bin/fossil
229		- execargs = /usr/bin/fossil http /home/fossil/ubercool.fossil --https
230		-</pre></nowiki>
231		-
232		-The directory where that file goes varies between OSes, so check the man
233		-pages on your system to find out where it should be locally.
234		-
235		-See the <tt>stunnel</tt> documentation for further details about this
236		-configuration file.
237		-
238		-It is important that the [/help/http \| <tt>fossil http</tt>] command in
239		-that configuration include the <tt>--https</tt> option to let Fossil
240		-know to use "<tt>https</tt>" instead of "<tt>http</tt>" as the URL
241		-scheme on generated hyperlinks.
242		-
243		-
244		-<h3 id="althttpd">stunnel + althttpd</h3>
245		-
246		-The public SQLite and Fossil web sites can't just use stunnel + Fossil
247		-because parts of the web site are static, served by
248		-[https://sqlite.org/docsrc/doc/trunk/misc/althttpd.md\|a separate web
249		-server called <tt>althttpd</tt>], written by the primary author of both
250		-SQLite and Fossil. <tt>althttpd</tt> is a lightweight HTTP-only web
251		-server. It handles the static HTTP hits on <tt>sqlite.org</tt> and
252		-<tt>fossil-scm.org</tt>, delegating HTTPS hits to stunnel and dynamic
253		-content hits to Fossil.
254		-
255		-(The largest single chunk of static content served directly by
256		-<tt>althttpd</tt> rather than via Fossil is the
257		-[https://sqlite.org/docs.html \| SQLite documentation], which is built
258		-[https://sqlite.org/docsrc/ \| from source files] and then served
259		-statically.)
260		-
261		-In addition to the documentation linked above, there is a large header
262		-comment in the [https://sqlite.org/docsrc/file/misc/althttpd.c\|single C
263		-file] of <tt>althttpd</tt> which is most helpful.
264		-
265		-
266		-<h3 id="nginx">nginx</h3>
267		-
268		-If your needs are more complex than althttpd can handle or you'd prefer
269		-to use only software available in your server operating system's package
270		-repository, we recommend that you step up to [http://nginx.org/\|nginx].
271		-Setting this up is complex enough that we cover it [./tls-nginx.md\|in a
272		-separate document].
	211	+it behind some kind of HTTPS proxy. We have a number of documents
	212	+elsewhere in this repository that cover your options for [./server/
	213	+\| serving Fossil repositories]. A few of the most useful of these are:
	214	+
	215	+ * <a id="stunnel" href="./server/any/stunnel.md">Serving via stunnel</a>
	216	+ * <a id="althttpd" href="./server/any/althttpd.md">Serving via stunnel + althttpd</a>
	217	+ * <a id="nginx" href="./server/any/scgi.md">Serving via SCGI (nginx)</a>
273	218
274	219
275	220	<h2 id="enforcing">Enforcing TLS Access</h2>
276	221
277	222	To use TLS encryption in cloning and syncing to a remote Fossil
278	223

	--- www/ssl.wiki
	+++ www/ssl.wiki
	@@ -1,6 +1,6 @@
1	<title>TLS and Fossil</title>
2
3	<h2>Using TLS-Encrypted Communications with Fossil</h2>
4
5	If you are storing sensitive information in a repository accessible over
6	a network whose integrity you do not fully trust, you should use TLS to
	@@ -206,72 +206,17 @@
206	<h2 id="server">Fossil TLS Configuration: Server Side</h2>
207
208	Fossil's built-in HTTP server feature does not currently have a built-in
209	way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked
210	Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put
211	it behind some kind of HTTPS proxy.
212
213
214	<h3 id="stunnel">stunnel Alone</h3>
215
216	[https://www.stunnel.org/ \| <tt>stunnel</tt>] is an
217	[https://en.wikipedia.org/wiki/Inetd \| <tt>inetd</tt>]-like process that
218	accepts and decodes TLS-encrypted connections. It can directly proxy
219	Fossil communications, allowing secure TLS-encrypted communications to a
220	Fossil repository server. You simply need to install <tt>stunnel</tt>
221	and then place something like this in its main configuration file,
222	<tt>stunnel.conf</tt>:
223
224	<nowiki><pre>
225	[https]
226	accept = www.ubercool-project.org:443
227	TIMEOUTclose = 0
228	exec = /usr/bin/fossil
229	execargs = /usr/bin/fossil http /home/fossil/ubercool.fossil --https
230	</pre></nowiki>
231
232	The directory where that file goes varies between OSes, so check the man
233	pages on your system to find out where it should be locally.
234
235	See the <tt>stunnel</tt> documentation for further details about this
236	configuration file.
237
238	It is important that the [/help/http \| <tt>fossil http</tt>] command in
239	that configuration include the <tt>--https</tt> option to let Fossil
240	know to use "<tt>https</tt>" instead of "<tt>http</tt>" as the URL
241	scheme on generated hyperlinks.
242
243
244	<h3 id="althttpd">stunnel + althttpd</h3>
245
246	The public SQLite and Fossil web sites can't just use stunnel + Fossil
247	because parts of the web site are static, served by
248	[https://sqlite.org/docsrc/doc/trunk/misc/althttpd.md\|a separate web
249	server called <tt>althttpd</tt>], written by the primary author of both
250	SQLite and Fossil. <tt>althttpd</tt> is a lightweight HTTP-only web
251	server. It handles the static HTTP hits on <tt>sqlite.org</tt> and
252	<tt>fossil-scm.org</tt>, delegating HTTPS hits to stunnel and dynamic
253	content hits to Fossil.
254
255	(The largest single chunk of static content served directly by
256	<tt>althttpd</tt> rather than via Fossil is the
257	[https://sqlite.org/docs.html \| SQLite documentation], which is built
258	[https://sqlite.org/docsrc/ \| from source files] and then served
259	statically.)
260
261	In addition to the documentation linked above, there is a large header
262	comment in the [https://sqlite.org/docsrc/file/misc/althttpd.c\|single C
263	file] of <tt>althttpd</tt> which is most helpful.
264
265
266	<h3 id="nginx">nginx</h3>
267
268	If your needs are more complex than althttpd can handle or you'd prefer
269	to use only software available in your server operating system's package
270	repository, we recommend that you step up to [http://nginx.org/\|nginx].
271	Setting this up is complex enough that we cover it [./tls-nginx.md\|in a
272	separate document].
273
274
275	<h2 id="enforcing">Enforcing TLS Access</h2>
276
277	To use TLS encryption in cloning and syncing to a remote Fossil
278

	--- www/ssl.wiki
	+++ www/ssl.wiki
	@@ -1,6 +1,6 @@
1	<title>Securing a Repository with TLS</title>
2
3	<h2>Using TLS-Encrypted Communications with Fossil</h2>
4
5	If you are storing sensitive information in a repository accessible over
6	a network whose integrity you do not fully trust, you should use TLS to
	@@ -206,72 +206,17 @@
206	<h2 id="server">Fossil TLS Configuration: Server Side</h2>
207
208	Fossil's built-in HTTP server feature does not currently have a built-in
209	way to serve via HTTP over TLS, a.k.a. HTTPS, even when you've linked
210	Fossil to OpenSSL. To serve a Fossil repository via HTTPS, you must put
211	it behind some kind of HTTPS proxy. We have a number of documents
212	elsewhere in this repository that cover your options for [./server/
213	\| serving Fossil repositories]. A few of the most useful of these are:
214
215	* <a id="stunnel" href="./server/any/stunnel.md">Serving via stunnel</a>
216	* <a id="althttpd" href="./server/any/althttpd.md">Serving via stunnel + althttpd</a>
217	* <a id="nginx" href="./server/any/scgi.md">Serving via SCGI (nginx)</a>























































218
219
220	<h2 id="enforcing">Enforcing TLS Access</h2>
221
222	To use TLS encryption in cloning and syncing to a remote Fossil
223

M www/sync.wiki

+1 -1

		--- www/sync.wiki
		+++ www/sync.wiki
		@@ -59,11 +59,11 @@
59	59
60	60	<p>The server might be running as an independent server
61	61	using the <b>server</b> command, or it might be launched from
62	62	inetd or xinetd using the <b>http</b> command. Or the server might
63	63	be launched from CGI.
64		-(See "[./server.wiki\|How To Configure A Fossil Server]" for details.)
	64	+(See "[./server/\|How To Configure A Fossil Server]" for details.)
65	65	The specifics of how the server listens
66	66	for incoming HTTP requests is immaterial to this protocol.
67	67	The important point is that the server is listening for requests and
68	68	the client is the issuer of the requests.</p>
69	69
70	70

	--- www/sync.wiki
	+++ www/sync.wiki
	@@ -59,11 +59,11 @@
59
60	<p>The server might be running as an independent server
61	using the <b>server</b> command, or it might be launched from
62	inetd or xinetd using the <b>http</b> command. Or the server might
63	be launched from CGI.
64	(See "[./server.wiki\|How To Configure A Fossil Server]" for details.)
65	The specifics of how the server listens
66	for incoming HTTP requests is immaterial to this protocol.
67	The important point is that the server is listening for requests and
68	the client is the issuer of the requests.</p>
69
70

	--- www/sync.wiki
	+++ www/sync.wiki
	@@ -59,11 +59,11 @@
59
60	<p>The server might be running as an independent server
61	using the <b>server</b> command, or it might be launched from
62	inetd or xinetd using the <b>http</b> command. Or the server might
63	be launched from CGI.
64	(See "[./server/\|How To Configure A Fossil Server]" for details.)
65	The specifics of how the server listens
66	for incoming HTTP requests is immaterial to this protocol.
67	The important point is that the server is listening for requests and
68	the client is the issuer of the requests.</p>
69
70

M www/tls-nginx.md

+50 -242

		--- www/tls-nginx.md
		+++ www/tls-nginx.md
		@@ -3,183 +3,45 @@
3	3	One of the [many ways](./ssl.wiki) to provide TLS-encrypted HTTP access
4	4	(a.k.a. HTTPS) to Fossil is to run it behind a web proxy that supports
5	5	TLS. This document explains how to use the powerful [nginx web
6	6	server](http://nginx.org/) to do that.
7	7
8		-
9		-## Benefits
10		-
11		-This scheme is complicated, even with the benefit of this guide and
12		-pre-built binary packages. Why should you put up with this complexity?
13		-Because it gives many benefits that are difficult or impossible to get
14		-with the less complicated options:
15		-
16		-* Power — nginx is one of the most powerful web servers in the
17		- world. The chance that you will run into a web serving wall that you
18		- can’t scale with nginx is very low.
19		-
20		- To give you some idea of the sort of thing you can readily
21		- accomplish with nginx, your author runs a single public web server
22		- that provides transparent name-based virtual hosting for four
23		- separate domains:
24		-
25		- * One is entirely static, not involving any dynamic content or
26		- Fossil integration at all.
27		-
28		- * Another is served almost entirely by Fossil, with a few select
29		- static content exceptions punched past Fossil, which are handled
30		- entirely via nginx.
31		-
32		- * The other two domains are aliases for one another — e.g.
33		- `example.com` and `example.net` — with most of the content being
34		- static. This pair of domains has three different Fossil repo
35		- proxies attached to various sections of the URI hierarchy.
36		-
37		- All of this is done with minimal configuration repetition between
38		- the site configurations.
39		-
40		-* Integration — Because nginx is so popular, it integrates with
41		-many different technologies, and many other systems integrate with it in
42		-turn. This makes it great middleware, sitting between the outer web
43		-world and interior site services like Fossil. It allows Fossil to
44		-participate seamlessly as part of a larger web stack.
45		-
46		-* Availability — nginx is already in most operating system binary
47		-package repositories, so you don’t need to go out of your way to get it.
48		-
49		-
50		-## Fossil Remote Access Methods
51		-
52		-Fossil provides four major ways to access a repository it’s serving
53		-remotely, three of which are straightforward to use with nginx:
54		-
55		-* HTTP — Fossil has a built-in HTTP server: `fossil server`.
56		- While this method is efficient and it’s possible to use nginx to
57		- proxy access to another HTTP server, this option is overkill for our
58		- purposes. nginx is itself a fully featured HTTP server, so we will
59		- choose in this guide not to make nginx reinterpret Fossil’s
60		- implementation of HTTP.
61		-
62		-* CGI — This method is simple but inefficient, because it launches
63		- a separate Fossil instance on every HTTP hit.
64		-
65		- Since Fossil is a relatively small self-contained program, and it’s
66		- designed to start up quickly, this method can work well in a
67		- surprisingly large number of cases.
68		-
69		- Nevertheless, we will avoid this option in this document because
70		- we’re already buying into a certain amount of complexity here in
71		- order to gain power. There’s no sense in throwing away any of that
72		- hard-won performance on CGI overhead.
73		-
74		-* SCGI — The [SCGI protocol][scgi] provides the simplicity of CGI
75		- without its performance problems.
76		-
77		-* SSH — This method exists primarily to avoid the need for HTTPS
78		- in the first place. There is probably a way to get nginx to proxy
79		- Fossil to HTTPS via SSH, but it would be pointlessly complicated.
80		-
81		-SCGI it is, then.
82		-
83		-
84		-# Installing
85		-
86		-The first step is to install the pieces we’ll be working with. This
87		-varies on different operating systems, so to avoid overcomplicating this
88		-guide, we’re going to assume you’re using Ubuntu Server 18.04 LTS, a
89		-common Tier 1 offering for [virtual private servers][vps].
90		-
91		-SSH into your server, then say:
92		-
93		- $ sudo apt install certbot fossil nginx
94		-
95		-For other operating systems, simply visit [the front Certbot web
96		-page][cb] and tell it what OS and web stack you’re using. Chances are
97		-good that they’ve got a good guide for you already.
98		-
99		-
100		-# Running Fossil in SCGI Mode
101		-
102		-You presumably already have a working Fossil configuration on the public
103		-server you’re trying to set up and are just following this guide to
104		-replace HTTP service with HTTPS.
105		-
106		-(You can adjust the advice in this guide to get both HTTP and HTTPS
107		-service on the same site, but I strongly recommend that you do not do
108		-that: the good excuses remaining for continuing to allow HTTP on public
109		-web servers are running thin these days.)
110		-
111		-I run my Fossil SCGI server instances with a variant of [the `fslsrv`
112		-shell script](/file/tools/fslsrv) currently hosted in the Fossil source
113		-code repository. You’ll want to download that and make a copy of it, so
114		-you can customize it to your particular needs.
115		-
116		-This script allows running multiple Fossil SCGI servers, one per
117		-repository, each bound to a different high-numbered `localhost` port, so
118		-that only nginx can see and proxy them out to the public. The
119		-“`example`” repo is on TCP port localhost:12345, and the “`foo`” repo is
120		-on localhost:12346.
121		-
122		-As written, the `fslsrv` script expects repositories to be stored in the
123		-calling user’s home directory under `~/museum`, because where else do
124		-you keep Fossils?
125		-
126		-That home directory also needs to have a directory to hold log files,
127		-`~/log/fossil/*.log`. Fossil doesn’t put out much logging, but when it
128		-does, it’s better to have it captured than to need to re-create the
129		-problem after the fact.
130		-
131		-The use of `--baseurl` in this script lets us have each Fossil
132		-repository mounted in a different location in the URL scheme. Here, for
133		-example, we’re saying that the “`example`” repository is hosted under
134		-the `/code` URI on its domains, but that the “`foo`” repo is hosted at
135		-the top level of its domain. You’ll want to do something like the
136		-former for a Fossil repo that’s just one piece of a larger site, but the
137		-latter for a repo that is basically the whole point of the site.
138		-
139		-You might also want another script to automate the update, build, and
140		-deployment steps for new Fossil versions:
141		-
142		- #!/bin/sh
143		- cd $HOME/src/fossil/trunk
144		- fossil up
145		- make -j11
146		- killall fossil
147		- sudo make install
148		- fslsrv
149		-
150		-The `killall fossil` step is needed only on OSes that refuse to let you
151		-replace a running binary on disk.
152		-
153		-As written, the `fslsrv` script assumes a Linux environment. It expects
154		-`/bin/bash` to exist, and it depends on non-POSIX tools like `pgrep`.
155		-It should not be difficult to port to systems like macOS or the BSDs.
	8	+This document is an extension of the [Serving via nginx on Debian][nod]
	9	+document. Please read that first, then come back here to extend its
	10	+configuration with TLS.
	11	+
	12	+[nod]: ./server/debian/nginx.md
	13	+
	14	+
	15	+## Install Certbot
	16	+
	17	+The [nginx-on-Debian document][nod] had you install a few non-default
	18	+packages to the system, but there’s one more you need for this guide:
	19	+
	20	+ $ sudo apt install certbot
	21	+
	22	+You can extend this guide to other operating systems by following the
	23	+instructions found via [the front Certbot web page][cb] instead, telling
	24	+it what OS and web stack you’re using. Chances are good that they’ve got
	25	+a good guide for you already.
156	26
157	27
158	28	# Configuring Let’s Encrypt, the Easy Way
159	29
160	30	If your web serving needs are simple, [Certbot][cb] can configure nginx
161		-for you and keep its certificates up to date. You can follow the Certbot
162		-documentation for [nginx on Ubuntu 18.04 LTS guide][cbnu] as-is, though
163		-we’d recommend one small change: to use the version of Certbot in the
164		-Ubuntu package repository rather than the first-party Certbot package
165		-that the guide recommends.
166		-
167		-The primary local configuration you need is to tell nginx how to proxy
168		-certain URLs down to the Fossil instance you started above with the
169		-`fslsrv` script:
170		-
171		- location / {
172		- include scgi_params;
173		- scgi_pass 127.0.0.1:12345;
174		- scgi_param HTTPS "on";
175		- scgi_param SCRIPT_NAME "";
176		- }
177		-
178		-The TCP port number in that snippet is the key: it has to match the port
179		-number generated by `fslsrv` from the base port number passed to the
180		-`start_one` function.
	31	+for you and keep its certificates up to date. Simply follow Certbot’s
	32	+[nginx on Ubuntu 18.04 LTS guide][cbnu]. We’d recommend one small
	33	+change: to use the version of Certbot in the Ubuntu package repository
	34	+rather than download it from the Certbot site.
	35	+
	36	+You should be able to use the nginx configuration given in our [Serving
	37	+via nginx on Debian][nod] guide with little to no change. The main thing
	38	+to watch out for is that the TCP port number in the nginx configuration
	39	+needs to match the value you gave when starting Fossil. If you followed
	40	+that guide’s advice, it will be 9000. Another option is to use [the
	41	+`fslsrv` script](/file/tools/fslsrv), in which case the TCP port number
	42	+will be 12345 or higher.
181	43
182	44
183	45	# Configuring Let’s Encrypt, the Hard Way
184	46
185	47	If you’re finding that you can’t get certificates to be issued or
		@@ -193,11 +55,12 @@
193	55	Environment][acme] protocol (ACME) to determine whether a given client
194	56	actually has control over the domain(s) for which it wants a certificate
195	57	minted. Let’s Encrypt will not blithely let you mint certificates for
196	58	`google.com` and `paypal.com` just because you ask for it!
197	59
198		-Your author’s configuration, glossed above, is complicated enough that
	60	+Your author’s configuration, glossed [in the HTTP-only guide][nod],
	61	+is complicated enough that
199	62	the current version of Certbot (0.28 at the time of this writing) can’t
200	63	cope with it. That’s the primary motivation for me to write this guide:
201	64	I’m addressing the “me” years hence who needs to upgrade to Ubuntu 20.04
202	65	or 22.04 LTS and has forgotten all of this stuff. 😉
203	66
		@@ -216,24 +79,12 @@
216	79	entirely.
217	80
218	81
219	82	## Step 2: Configuring nginx
220	83
221		-On Ubuntu systems, at least, the primary user-level configuration file
222		-is `/etc/nginx/sites-enabled/default`. For a configuration like I
223		-described at the top of this article, I recommend that this file contain
224		-only a list of include statements, one for each site that server hosts:
225		-
226		- include local/example
227		- include local/foo
228		-
229		-Those files then each define one domain’s configuration. Here,
230		-`/etc/nginx/local/example` contains the configuration for
231		-`.example.com` and `.example.net`; and `local/foo` contains the
232		-configuration for `*.foo.net`.
233		-
234		-Here’s an example configuration:
	84	+This is a straightforward extension to [the HTTP-only
	85	+configuration](./server/debian/nginx.md#config):
235	86
236	87	server {
237	88	server_name .foo.net;
238	89
239	90	include local/tls-common;
		@@ -268,12 +119,13 @@
268	119	include local/http-certbot-only;
269	120	access_log /var/log/nginx/foo.net-http-access.log;
270	121	error_log /var/log/nginx/foo.net-http-error.log;
271	122	}
272	123
273		-Notice that we need two `server { }` blocks: one for HTTPS service, and
274		-one for HTTP-only service:
	124	+One big difference between this and the HTTP-only case is
	125	+that we need two `server { }` blocks: one for HTTPS service, and
	126	+one for HTTP-only service.
275	127
276	128
277	129	### HTTP over TLS (HTTPS) Service
278	130
279	131	The first `server { }` block includes this file, `local/tls-common`:
		@@ -385,43 +237,17 @@
385	237	# Force everything else to HTTPS with a permanent redirect.
386	238	#return 301 https://$host$request_uri;
387	239
388	240	As written above, this configuration does nothing other than to tell
389	241	nginx that it’s allowed to serve content via HTTP on port 80 as well.
390		-
391	242	We’ll uncomment the `rewrite` and `return` directives below, when we’re
392	243	ready to begin testing.
393	244
394		-
395		-#### Why the Repetition?
396		-
397		-These `server { }` blocks contain several directives that have to be
398		-either completely repeated or copied with only trivial changes when
399		-you’re hosting multiple domains from a single server.
400		-
401		-You might then wonder, why haven’t I factored some of those directives
402		-into the included files `local/tls-common` and
403		-`local/http-certbot-only`? Why can’t the HTTP-only `server { }` block
404		-above be just two lines? That is, why can I not say:
405		-
406		- server_name .foo.net;
407		- include local/http-certbot-only;
408		-
409		-Then in `local/http-certbot-only` say:
410		-
411		- root /var/www/$host;
412		- access_log /var/log/nginx/$host-http-access.log;
413		- error_log /var/log/nginx/$host-http-error.log;
414		-
415		-Sadly, nginx doesn’t allow variable substitution into these particular
416		-directives. As I understand it, allowing that would make nginx slower,
417		-so we must largely repeat these directives in each HTTP `server { }`
418		-block.
419		-
420		-These configurations are, as shown, as small as I know how to get them.
421		-If you know of a way to reduce some of this repetition, [I solicit your
422		-advice][fd].
	245	+Notice that this configuration is very different from that in the
	246	+[HTTP-only nginx on Debian][nod] guide. Most of that guide’s nginx
	247	+directives moved up into the TLS `server { }` block, because we
	248	+eventually want this site to be as close to HTTPS-only as we can get it.
423	249
424	250
425	251	## Step 3: Dry Run
426	252
427	253	We want to first request a dry run, because Let’s Encrypt puts some
		@@ -541,29 +367,19 @@
541	367	it would actually [cause an infinite redirect loop if
542	368	enabled](./ssl.wiki#rloop).
543	369
544	370
545	371
546		-## Step 6: Re-Sync Your Repositories
	372	+## Step 6: Re-Point Fossil at Your Repositories
547	373
548		-Now that the repositories hosted by this server are available via HTTPS,
549		-you need to tell Fossil about it:
	374	+As of Fossil 2.9, the permanent HTTP-to-HTTPS redirect we enabled above
	375	+causes Fossil to remember the new URL automatically the first time it’s
	376	+redirected to it. All you need to do to switch your syncs to HTTPS is:
550	377
551	378	$ cd ~/path/to/checkout
552		- $ fossil sync https://example.com/code
553		-
554		-Once that’s done per repository file, all checkouts of that repo will
555		-from that point on use the HTTPS URI to sync.
556		-
557		-You might wonder if that’s necessary, since we have the automatic
558		-HTTP-to-HTTPS redirect on this site now. If you clone or sync one of
559		-these nginx-hosted Fossil repositories over an untrustworthy network
560		-that allows [MITM attacks][mitm], that redirect won’t protect you from a
561		-sufficiently capable and motivated attacker unless you’ve also gone
562		-ahead and [enabled HSTS](#hsts). You can put off the need to enable
563		-HSTS by explicitly using HTTPS URIs.
564		-
	379	+ $ fossil sync
	380	+
565	381
566	382	## Step 7: Renewing Automatically
567	383
568	384	Now that the configuration is solid, you can renew the LE cert with the
569	385	`certbot` command from above without the `--dry-run` flag plus a restart
		@@ -588,27 +404,21 @@
588	404	-----------
589	405
590	406	<a id=”evolution”></a>
591	407	Document Evolution
592	408
593		-TLS and web proxying are a constantly evolving technology. This article
594		-replaces my [earlier effort][2016], which had whole sections that were
595		-basically obsolete within about a year of posting it. Two years on, and
596		-I was encouraging readers to ignore about half of that HOWTO. I am now
597		-writing this document about 3 years later because Let’s Encrypt
598		-deprecated key technology that HOWTO depended on, to the point that
599		-following that old HOWTO is more likely to confuse than enlighten.
	409	+Large parts of this article have been rewritten several times now due to
	410	+shifting technology in the TLS and proxying spheres.
600	411
601	412	There is no particularly good reason to expect that this sort of thing
602		-will not continue to happen, so this effort is expected to be a living
	413	+will not continue to happen, so we consider this to be a living
603	414	document. If you do not have commit access on the `fossil-scm.org`
604	415	repository to update this document as the world changes around it, you
605	416	can discuss this document [on the forum][fd]. This document’s author
606	417	keeps an eye on the forum and expects to keep this document updated with
607	418	ideas that appear in that thread.
608	419
609		-[2016]: https://www.mail-archive.com/[email protected]/msg22907.html
610	420	[acme]: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment
611	421	[cb]: https://certbot.eff.org/
612	422	[cbnu]: https://certbot.eff.org/lets-encrypt/ubuntubionic-nginx
613	423	[fd]: https://fossil-scm.org/forum/forumpost/ae6a4ee157
614	424	[hsts]: https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
		@@ -616,7 +426,5 @@
616	426	[mitm]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
617	427	[nest]: https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/
618	428	[ocsp]: https://en.wikipedia.org/wiki/OCSP_stapling
619	429	[qslc]: https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices
620	430	[qslt]: https://www.ssllabs.com/ssltest/
621		-[scgi]: https://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface
622		-[vps]: https://en.wikipedia.org/wiki/Virtual_private_server
623	431

	--- www/tls-nginx.md
	+++ www/tls-nginx.md
	@@ -3,183 +3,45 @@
3	One of the [many ways](./ssl.wiki) to provide TLS-encrypted HTTP access
4	(a.k.a. HTTPS) to Fossil is to run it behind a web proxy that supports
5	TLS. This document explains how to use the powerful [nginx web
6	server](http://nginx.org/) to do that.
7
8
9	## Benefits
10
11	This scheme is complicated, even with the benefit of this guide and
12	pre-built binary packages. Why should you put up with this complexity?
13	Because it gives many benefits that are difficult or impossible to get
14	with the less complicated options:
15
16	* Power — nginx is one of the most powerful web servers in the
17	world. The chance that you will run into a web serving wall that you
18	can’t scale with nginx is very low.
19
20	To give you some idea of the sort of thing you can readily
21	accomplish with nginx, your author runs a single public web server
22	that provides transparent name-based virtual hosting for four
23	separate domains:
24
25	* One is entirely static, not involving any dynamic content or
26	Fossil integration at all.
27
28	* Another is served almost entirely by Fossil, with a few select
29	static content exceptions punched past Fossil, which are handled
30	entirely via nginx.
31
32	* The other two domains are aliases for one another — e.g.
33	`example.com` and `example.net` — with most of the content being
34	static. This pair of domains has three different Fossil repo
35	proxies attached to various sections of the URI hierarchy.
36
37	All of this is done with minimal configuration repetition between
38	the site configurations.
39
40	* Integration — Because nginx is so popular, it integrates with
41	many different technologies, and many other systems integrate with it in
42	turn. This makes it great middleware, sitting between the outer web
43	world and interior site services like Fossil. It allows Fossil to
44	participate seamlessly as part of a larger web stack.
45
46	* Availability — nginx is already in most operating system binary
47	package repositories, so you don’t need to go out of your way to get it.
48
49
50	## Fossil Remote Access Methods
51
52	Fossil provides four major ways to access a repository it’s serving
53	remotely, three of which are straightforward to use with nginx:
54
55	* HTTP — Fossil has a built-in HTTP server: `fossil server`.
56	While this method is efficient and it’s possible to use nginx to
57	proxy access to another HTTP server, this option is overkill for our
58	purposes. nginx is itself a fully featured HTTP server, so we will
59	choose in this guide not to make nginx reinterpret Fossil’s
60	implementation of HTTP.
61
62	* CGI — This method is simple but inefficient, because it launches
63	a separate Fossil instance on every HTTP hit.
64
65	Since Fossil is a relatively small self-contained program, and it’s
66	designed to start up quickly, this method can work well in a
67	surprisingly large number of cases.
68
69	Nevertheless, we will avoid this option in this document because
70	we’re already buying into a certain amount of complexity here in
71	order to gain power. There’s no sense in throwing away any of that
72	hard-won performance on CGI overhead.
73
74	* SCGI — The [SCGI protocol][scgi] provides the simplicity of CGI
75	without its performance problems.
76
77	* SSH — This method exists primarily to avoid the need for HTTPS
78	in the first place. There is probably a way to get nginx to proxy
79	Fossil to HTTPS via SSH, but it would be pointlessly complicated.
80
81	SCGI it is, then.
82
83
84	# Installing
85
86	The first step is to install the pieces we’ll be working with. This
87	varies on different operating systems, so to avoid overcomplicating this
88	guide, we’re going to assume you’re using Ubuntu Server 18.04 LTS, a
89	common Tier 1 offering for [virtual private servers][vps].
90
91	SSH into your server, then say:
92
93	$ sudo apt install certbot fossil nginx
94
95	For other operating systems, simply visit [the front Certbot web
96	page][cb] and tell it what OS and web stack you’re using. Chances are
97	good that they’ve got a good guide for you already.
98
99
100	# Running Fossil in SCGI Mode
101
102	You presumably already have a working Fossil configuration on the public
103	server you’re trying to set up and are just following this guide to
104	replace HTTP service with HTTPS.
105
106	(You can adjust the advice in this guide to get both HTTP and HTTPS
107	service on the same site, but I strongly recommend that you do not do
108	that: the good excuses remaining for continuing to allow HTTP on public
109	web servers are running thin these days.)
110
111	I run my Fossil SCGI server instances with a variant of [the `fslsrv`
112	shell script](/file/tools/fslsrv) currently hosted in the Fossil source
113	code repository. You’ll want to download that and make a copy of it, so
114	you can customize it to your particular needs.
115
116	This script allows running multiple Fossil SCGI servers, one per
117	repository, each bound to a different high-numbered `localhost` port, so
118	that only nginx can see and proxy them out to the public. The
119	“`example`” repo is on TCP port localhost:12345, and the “`foo`” repo is
120	on localhost:12346.
121
122	As written, the `fslsrv` script expects repositories to be stored in the
123	calling user’s home directory under `~/museum`, because where else do
124	you keep Fossils?
125
126	That home directory also needs to have a directory to hold log files,
127	`~/log/fossil/*.log`. Fossil doesn’t put out much logging, but when it
128	does, it’s better to have it captured than to need to re-create the
129	problem after the fact.
130
131	The use of `--baseurl` in this script lets us have each Fossil
132	repository mounted in a different location in the URL scheme. Here, for
133	example, we’re saying that the “`example`” repository is hosted under
134	the `/code` URI on its domains, but that the “`foo`” repo is hosted at
135	the top level of its domain. You’ll want to do something like the
136	former for a Fossil repo that’s just one piece of a larger site, but the
137	latter for a repo that is basically the whole point of the site.
138
139	You might also want another script to automate the update, build, and
140	deployment steps for new Fossil versions:
141
142	#!/bin/sh
143	cd $HOME/src/fossil/trunk
144	fossil up
145	make -j11
146	killall fossil
147	sudo make install
148	fslsrv
149
150	The `killall fossil` step is needed only on OSes that refuse to let you
151	replace a running binary on disk.
152
153	As written, the `fslsrv` script assumes a Linux environment. It expects
154	`/bin/bash` to exist, and it depends on non-POSIX tools like `pgrep`.
155	It should not be difficult to port to systems like macOS or the BSDs.
156
157
158	# Configuring Let’s Encrypt, the Easy Way
159
160	If your web serving needs are simple, [Certbot][cb] can configure nginx
161	for you and keep its certificates up to date. You can follow the Certbot
162	documentation for [nginx on Ubuntu 18.04 LTS guide][cbnu] as-is, though
163	we’d recommend one small change: to use the version of Certbot in the
164	Ubuntu package repository rather than the first-party Certbot package
165	that the guide recommends.
166
167	The primary local configuration you need is to tell nginx how to proxy
168	certain URLs down to the Fossil instance you started above with the
169	`fslsrv` script:
170
171	location / {
172	include scgi_params;
173	scgi_pass 127.0.0.1:12345;
174	scgi_param HTTPS "on";
175	scgi_param SCRIPT_NAME "";
176	}
177
178	The TCP port number in that snippet is the key: it has to match the port
179	number generated by `fslsrv` from the base port number passed to the
180	`start_one` function.
181
182
183	# Configuring Let’s Encrypt, the Hard Way
184
185	If you’re finding that you can’t get certificates to be issued or
	@@ -193,11 +55,12 @@
193	Environment][acme] protocol (ACME) to determine whether a given client
194	actually has control over the domain(s) for which it wants a certificate
195	minted. Let’s Encrypt will not blithely let you mint certificates for
196	`google.com` and `paypal.com` just because you ask for it!
197
198	Your author’s configuration, glossed above, is complicated enough that

199	the current version of Certbot (0.28 at the time of this writing) can’t
200	cope with it. That’s the primary motivation for me to write this guide:
201	I’m addressing the “me” years hence who needs to upgrade to Ubuntu 20.04
202	or 22.04 LTS and has forgotten all of this stuff. 😉
203
	@@ -216,24 +79,12 @@
216	entirely.
217
218
219	## Step 2: Configuring nginx
220
221	On Ubuntu systems, at least, the primary user-level configuration file
222	is `/etc/nginx/sites-enabled/default`. For a configuration like I
223	described at the top of this article, I recommend that this file contain
224	only a list of include statements, one for each site that server hosts:
225
226	include local/example
227	include local/foo
228
229	Those files then each define one domain’s configuration. Here,
230	`/etc/nginx/local/example` contains the configuration for
231	`.example.com` and `.example.net`; and `local/foo` contains the
232	configuration for `*.foo.net`.
233
234	Here’s an example configuration:
235
236	server {
237	server_name .foo.net;
238
239	include local/tls-common;
	@@ -268,12 +119,13 @@
268	include local/http-certbot-only;
269	access_log /var/log/nginx/foo.net-http-access.log;
270	error_log /var/log/nginx/foo.net-http-error.log;
271	}
272
273	Notice that we need two `server { }` blocks: one for HTTPS service, and
274	one for HTTP-only service:

275
276
277	### HTTP over TLS (HTTPS) Service
278
279	The first `server { }` block includes this file, `local/tls-common`:
	@@ -385,43 +237,17 @@
385	# Force everything else to HTTPS with a permanent redirect.
386	#return 301 https://$host$request_uri;
387
388	As written above, this configuration does nothing other than to tell
389	nginx that it’s allowed to serve content via HTTP on port 80 as well.
390
391	We’ll uncomment the `rewrite` and `return` directives below, when we’re
392	ready to begin testing.
393
394
395	#### Why the Repetition?
396
397	These `server { }` blocks contain several directives that have to be
398	either completely repeated or copied with only trivial changes when
399	you’re hosting multiple domains from a single server.
400
401	You might then wonder, why haven’t I factored some of those directives
402	into the included files `local/tls-common` and
403	`local/http-certbot-only`? Why can’t the HTTP-only `server { }` block
404	above be just two lines? That is, why can I not say:
405
406	server_name .foo.net;
407	include local/http-certbot-only;
408
409	Then in `local/http-certbot-only` say:
410
411	root /var/www/$host;
412	access_log /var/log/nginx/$host-http-access.log;
413	error_log /var/log/nginx/$host-http-error.log;
414
415	Sadly, nginx doesn’t allow variable substitution into these particular
416	directives. As I understand it, allowing that would make nginx slower,
417	so we must largely repeat these directives in each HTTP `server { }`
418	block.
419
420	These configurations are, as shown, as small as I know how to get them.
421	If you know of a way to reduce some of this repetition, [I solicit your
422	advice][fd].
423
424
425	## Step 3: Dry Run
426
427	We want to first request a dry run, because Let’s Encrypt puts some
	@@ -541,29 +367,19 @@
541	it would actually [cause an infinite redirect loop if
542	enabled](./ssl.wiki#rloop).
543
544
545
546	## Step 6: Re-Sync Your Repositories
547
548	Now that the repositories hosted by this server are available via HTTPS,
549	you need to tell Fossil about it:

550
551	$ cd ~/path/to/checkout
552	$ fossil sync https://example.com/code
553
554	Once that’s done per repository file, all checkouts of that repo will
555	from that point on use the HTTPS URI to sync.
556
557	You might wonder if that’s necessary, since we have the automatic
558	HTTP-to-HTTPS redirect on this site now. If you clone or sync one of
559	these nginx-hosted Fossil repositories over an untrustworthy network
560	that allows [MITM attacks][mitm], that redirect won’t protect you from a
561	sufficiently capable and motivated attacker unless you’ve also gone
562	ahead and [enabled HSTS](#hsts). You can put off the need to enable
563	HSTS by explicitly using HTTPS URIs.
564
565
566	## Step 7: Renewing Automatically
567
568	Now that the configuration is solid, you can renew the LE cert with the
569	`certbot` command from above without the `--dry-run` flag plus a restart
	@@ -588,27 +404,21 @@
588	-----------
589
590	<a id=”evolution”></a>
591	Document Evolution
592
593	TLS and web proxying are a constantly evolving technology. This article
594	replaces my [earlier effort][2016], which had whole sections that were
595	basically obsolete within about a year of posting it. Two years on, and
596	I was encouraging readers to ignore about half of that HOWTO. I am now
597	writing this document about 3 years later because Let’s Encrypt
598	deprecated key technology that HOWTO depended on, to the point that
599	following that old HOWTO is more likely to confuse than enlighten.
600
601	There is no particularly good reason to expect that this sort of thing
602	will not continue to happen, so this effort is expected to be a living
603	document. If you do not have commit access on the `fossil-scm.org`
604	repository to update this document as the world changes around it, you
605	can discuss this document [on the forum][fd]. This document’s author
606	keeps an eye on the forum and expects to keep this document updated with
607	ideas that appear in that thread.
608
609	[2016]: https://www.mail-archive.com/[email protected]/msg22907.html
610	[acme]: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment
611	[cb]: https://certbot.eff.org/
612	[cbnu]: https://certbot.eff.org/lets-encrypt/ubuntubionic-nginx
613	[fd]: https://fossil-scm.org/forum/forumpost/ae6a4ee157
614	[hsts]: https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
	@@ -616,7 +426,5 @@
616	[mitm]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
617	[nest]: https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/
618	[ocsp]: https://en.wikipedia.org/wiki/OCSP_stapling
619	[qslc]: https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices
620	[qslt]: https://www.ssllabs.com/ssltest/
621	[scgi]: https://en.wikipedia.org/wiki/Simple_Common_Gateway_Interface
622	[vps]: https://en.wikipedia.org/wiki/Virtual_private_server
623

	--- www/tls-nginx.md
	+++ www/tls-nginx.md
	@@ -3,183 +3,45 @@
3	One of the [many ways](./ssl.wiki) to provide TLS-encrypted HTTP access
4	(a.k.a. HTTPS) to Fossil is to run it behind a web proxy that supports
5	TLS. This document explains how to use the powerful [nginx web
6	server](http://nginx.org/) to do that.
7
8	This document is an extension of the [Serving via nginx on Debian][nod]
9	document. Please read that first, then come back here to extend its
10	configuration with TLS.
11
12	[nod]: ./server/debian/nginx.md
13
14
15	## Install Certbot
16
17	The [nginx-on-Debian document][nod] had you install a few non-default
18	packages to the system, but there’s one more you need for this guide:
19
20	$ sudo apt install certbot
21
22	You can extend this guide to other operating systems by following the
23	instructions found via [the front Certbot web page][cb] instead, telling
24	it what OS and web stack you’re using. Chances are good that they’ve got
25	a good guide for you already.


































































































































26
27
28	# Configuring Let’s Encrypt, the Easy Way
29
30	If your web serving needs are simple, [Certbot][cb] can configure nginx
31	for you and keep its certificates up to date. Simply follow Certbot’s
32	[nginx on Ubuntu 18.04 LTS guide][cbnu]. We’d recommend one small
33	change: to use the version of Certbot in the Ubuntu package repository
34	rather than download it from the Certbot site.
35
36	You should be able to use the nginx configuration given in our [Serving
37	via nginx on Debian][nod] guide with little to no change. The main thing
38	to watch out for is that the TCP port number in the nginx configuration
39	needs to match the value you gave when starting Fossil. If you followed
40	that guide’s advice, it will be 9000. Another option is to use [the
41	`fslsrv` script](/file/tools/fslsrv), in which case the TCP port number
42	will be 12345 or higher.








43
44
45	# Configuring Let’s Encrypt, the Hard Way
46
47	If you’re finding that you can’t get certificates to be issued or
	@@ -193,11 +55,12 @@
55	Environment][acme] protocol (ACME) to determine whether a given client
56	actually has control over the domain(s) for which it wants a certificate
57	minted. Let’s Encrypt will not blithely let you mint certificates for
58	`google.com` and `paypal.com` just because you ask for it!
59
60	Your author’s configuration, glossed [in the HTTP-only guide][nod],
61	is complicated enough that
62	the current version of Certbot (0.28 at the time of this writing) can’t
63	cope with it. That’s the primary motivation for me to write this guide:
64	I’m addressing the “me” years hence who needs to upgrade to Ubuntu 20.04
65	or 22.04 LTS and has forgotten all of this stuff. 😉
66
	@@ -216,24 +79,12 @@
79	entirely.
80
81
82	## Step 2: Configuring nginx
83
84	This is a straightforward extension to [the HTTP-only
85	configuration](./server/debian/nginx.md#config):












86
87	server {
88	server_name .foo.net;
89
90	include local/tls-common;
	@@ -268,12 +119,13 @@
119	include local/http-certbot-only;
120	access_log /var/log/nginx/foo.net-http-access.log;
121	error_log /var/log/nginx/foo.net-http-error.log;
122	}
123
124	One big difference between this and the HTTP-only case is
125	that we need two `server { }` blocks: one for HTTPS service, and
126	one for HTTP-only service.
127
128
129	### HTTP over TLS (HTTPS) Service
130
131	The first `server { }` block includes this file, `local/tls-common`:
	@@ -385,43 +237,17 @@
237	# Force everything else to HTTPS with a permanent redirect.
238	#return 301 https://$host$request_uri;
239
240	As written above, this configuration does nothing other than to tell
241	nginx that it’s allowed to serve content via HTTP on port 80 as well.

242	We’ll uncomment the `rewrite` and `return` directives below, when we’re
243	ready to begin testing.
244
245	Notice that this configuration is very different from that in the
246	[HTTP-only nginx on Debian][nod] guide. Most of that guide’s nginx
247	directives moved up into the TLS `server { }` block, because we
248	eventually want this site to be as close to HTTPS-only as we can get it.

























249
250
251	## Step 3: Dry Run
252
253	We want to first request a dry run, because Let’s Encrypt puts some
	@@ -541,29 +367,19 @@
367	it would actually [cause an infinite redirect loop if
368	enabled](./ssl.wiki#rloop).
369
370
371
372	## Step 6: Re-Point Fossil at Your Repositories
373
374	As of Fossil 2.9, the permanent HTTP-to-HTTPS redirect we enabled above
375	causes Fossil to remember the new URL automatically the first time it’s
376	redirected to it. All you need to do to switch your syncs to HTTPS is:
377
378	$ cd ~/path/to/checkout
379	$ fossil sync
380











381
382	## Step 7: Renewing Automatically
383
384	Now that the configuration is solid, you can renew the LE cert with the
385	`certbot` command from above without the `--dry-run` flag plus a restart
	@@ -588,27 +404,21 @@
404	-----------
405
406	<a id=”evolution”></a>
407	Document Evolution
408
409	Large parts of this article have been rewritten several times now due to
410	shifting technology in the TLS and proxying spheres.





411
412	There is no particularly good reason to expect that this sort of thing
413	will not continue to happen, so we consider this to be a living
414	document. If you do not have commit access on the `fossil-scm.org`
415	repository to update this document as the world changes around it, you
416	can discuss this document [on the forum][fd]. This document’s author
417	keeps an eye on the forum and expects to keep this document updated with
418	ideas that appear in that thread.
419

420	[acme]: https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment
421	[cb]: https://certbot.eff.org/
422	[cbnu]: https://certbot.eff.org/lets-encrypt/ubuntubionic-nginx
423	[fd]: https://fossil-scm.org/forum/forumpost/ae6a4ee157
424	[hsts]: https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
	@@ -616,7 +426,5 @@
426	[mitm]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
427	[nest]: https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/
428	[ocsp]: https://en.wikipedia.org/wiki/OCSP_stapling
429	[qslc]: https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices
430	[qslt]: https://www.ssllabs.com/ssltest/


431

Fossil SCM

Keyboard Shortcuts