Fossil SCM

Enhancements to the copy/paste SVG icon and to the global options help page.

drh 2019-07-29 15:12 trunk merge
Commit 93b0afc889ce44df7162bd8b538fb32a8651ba70ae2ffb0af7bc620dbaab9c24
Parent 8abeb62737c2b52…
4 files changed +1 -1 +4 -2 +22 -250 +22 -250
~ src/default_css.txt ~ www/env-opts.md ~ www/serverext.wiki ~ www/serverext.wiki
M src/default_css.txt
+1 -1
--- src/default_css.txt
+++ src/default_css.txt
@@ -777,11 +777,11 @@
777777
 margin: -2px .24em 0 0;
778778
 padding: 0;
779779
 border: 0;
780780
 vertical-align: middle;
781781
 //Note: the mkcss utility does not support line breaks in data URIs.
782
- background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 14 14'%3E%3Cpath style='fill: black; opacity:0' d='M 14 14 H 0 V 0 h 14 v 14 z'/%3E%3Cpath style='fill:rgb(240,240,240)' d='M 1 0 h 6.6 l 2 2 h 1 l 3.4 3.4 v 8.6 h -10 v -2 h -3 z'/%3E%3Cpath style='fill:rgb(64,64,64)' d='M 2 1 h 5 l 3 3 v 7 h -8 z'/%3E%3Cpath style='fill:rgb(248,248,248)' d='M 3 2 h 3.6 l 2.4 2.4 v 5.6 h -6 z'/%3E%3Cpath style='fill:rgb(80,128,208)' d='M 4 5 h 4 v 1 h -4 z m 0 2 h 4 v 1 h -4 z'/%3E%3Cpath style='fill:rgb(64,64,64)' d='M 5 3 h 5 l 3 3 v 7 h -8 z'/%3E%3Cpath style='fill:rgb(248,248,248)' d='M 10 4.4 v 1.6 h 1.6 z m -4 -0.6 h 3 v 3 h -3 z m 0 3 h 6 v 5.4 h -6 z'/%3E%3Cpath style='fill:rgb(80,128,208)' d='M 7 8 h 4 v 1 h -4 z m 0 2 h 4 v 1 h -4 z'/%3E%3C/svg%3E");
782
+ background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0,0,14,14'%3E%3Cpath style='fill:black;opacity:0' d='M14,14H0V0h14v14z'/%3E%3Cpath style='fill:rgb(240,240,240)' d='M1,0h6.6l2,2h1l3.4,3.4v8.6h-10v-2h-3z'/%3E%3Cpath style='fill:rgb(64,64,64)' d='M2,1h5l3,3v7h-8z'/%3E%3Cpath style='fill:rgb(248,248,248)' d='M3,2h3.6l2.4,2.4v5.6h-6z'/%3E%3Cpath style='fill:rgb(80,128,208)' d='M4,5h4v1h-4zm0,2h4v1h-4z'/%3E%3Cpath style='fill:rgb(64,64,64)' d='M5,3h5l3,3v7h-8z'/%3E%3Cpath style='fill:rgb(248,248,248)' d='M10,4.4v1.6h1.6zm-4,-0.6h3v3h-3zm0,3h6v5.4h-6z'/%3E%3Cpath style='fill:rgb(80,128,208)' d='M7,8h4v1h-4zm0,2h4v1h-4z'/%3E%3C/svg%3E");
783783
 background-repeat: no-repeat;
784784
 background-position: center;
785785
 cursor: pointer;
786786
 }
787787
 .copy-button-flipped {
788788
--- src/default_css.txt
+++ src/default_css.txt
@@ -777,11 +777,11 @@
777 margin: -2px .24em 0 0;
778 padding: 0;
779 border: 0;
780 vertical-align: middle;
781 //Note: the mkcss utility does not support line breaks in data URIs.
782 background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 14 14'%3E%3Cpath style='fill: black; opacity:0' d='M 14 14 H 0 V 0 h 14 v 14 z'/%3E%3Cpath style='fill:rgb(240,240,240)' d='M 1 0 h 6.6 l 2 2 h 1 l 3.4 3.4 v 8.6 h -10 v -2 h -3 z'/%3E%3Cpath style='fill:rgb(64,64,64)' d='M 2 1 h 5 l 3 3 v 7 h -8 z'/%3E%3Cpath style='fill:rgb(248,248,248)' d='M 3 2 h 3.6 l 2.4 2.4 v 5.6 h -6 z'/%3E%3Cpath style='fill:rgb(80,128,208)' d='M 4 5 h 4 v 1 h -4 z m 0 2 h 4 v 1 h -4 z'/%3E%3Cpath style='fill:rgb(64,64,64)' d='M 5 3 h 5 l 3 3 v 7 h -8 z'/%3E%3Cpath style='fill:rgb(248,248,248)' d='M 10 4.4 v 1.6 h 1.6 z m -4 -0.6 h 3 v 3 h -3 z m 0 3 h 6 v 5.4 h -6 z'/%3E%3Cpath style='fill:rgb(80,128,208)' d='M 7 8 h 4 v 1 h -4 z m 0 2 h 4 v 1 h -4 z'/%3E%3C/svg%3E");
783 background-repeat: no-repeat;
784 background-position: center;
785 cursor: pointer;
786 }
787 .copy-button-flipped {
788
--- src/default_css.txt
+++ src/default_css.txt
@@ -777,11 +777,11 @@
777 margin: -2px .24em 0 0;
778 padding: 0;
779 border: 0;
780 vertical-align: middle;
781 //Note: the mkcss utility does not support line breaks in data URIs.
782 background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0,0,14,14'%3E%3Cpath style='fill:black;opacity:0' d='M14,14H0V0h14v14z'/%3E%3Cpath style='fill:rgb(240,240,240)' d='M1,0h6.6l2,2h1l3.4,3.4v8.6h-10v-2h-3z'/%3E%3Cpath style='fill:rgb(64,64,64)' d='M2,1h5l3,3v7h-8z'/%3E%3Cpath style='fill:rgb(248,248,248)' d='M3,2h3.6l2.4,2.4v5.6h-6z'/%3E%3Cpath style='fill:rgb(80,128,208)' d='M4,5h4v1h-4zm0,2h4v1h-4z'/%3E%3Cpath style='fill:rgb(64,64,64)' d='M5,3h5l3,3v7h-8z'/%3E%3Cpath style='fill:rgb(248,248,248)' d='M10,4.4v1.6h1.6zm-4,-0.6h3v3h-3zm0,3h6v5.4h-6z'/%3E%3Cpath style='fill:rgb(80,128,208)' d='M7,8h4v1h-4zm0,2h4v1h-4z'/%3E%3C/svg%3E");
783 background-repeat: no-repeat;
784 background-position: center;
785 cursor: pointer;
786 }
787 .copy-button-flipped {
788
M www/env-opts.md
+4 -2
--- www/env-opts.md
+++ www/env-opts.md
@@ -31,12 +31,11 @@
3131
3232
 `--chdir DIRECTORY`: Change to the named directory before processing
3333
 any commands.
3434
3535
36
-`--comfmtflags NUMBER`
37
-`--comment-format NUMBER`: Specify flags that control how check-in comments
36
+`--comfmtflags NUMBER`: Specify flags that control how check-in comments
3837
 and certain other text outputs are formatted for display. The flags are
3938
 individual bits in `NUMBER`, which must be specified in base 10:
4039
4140
 * _0_ — Uses the revised algorithm with no special handling.
4241
@@ -56,10 +55,13 @@
5655
5756
 * _16_ — Looks for the original comment text within the text being
5857
 printed. Upon matching, a new line will be emitted, thus
5958
 preserving more of the pre-existing formatting.
6059
60
+
61
+`--comment-format NUMBER`: Alias for `--comfmtflags NUMBER`.
62
+
6163
6264
 `--errorlog ERRLOG`: Name a file to which fossil will log panics,
6365
 errors, and warnings.
6466
6567
6668
--- www/env-opts.md
+++ www/env-opts.md
@@ -31,12 +31,11 @@
31
32 `--chdir DIRECTORY`: Change to the named directory before processing
33 any commands.
34
35
36 `--comfmtflags NUMBER`
37 `--comment-format NUMBER`: Specify flags that control how check-in comments
38 and certain other text outputs are formatted for display. The flags are
39 individual bits in `NUMBER`, which must be specified in base 10:
40
41 * _0_ — Uses the revised algorithm with no special handling.
42
@@ -56,10 +55,13 @@
56
57 * _16_ — Looks for the original comment text within the text being
58 printed. Upon matching, a new line will be emitted, thus
59 preserving more of the pre-existing formatting.
60
 
 
 
61
62 `--errorlog ERRLOG`: Name a file to which fossil will log panics,
63 errors, and warnings.
64
65
66
--- www/env-opts.md
+++ www/env-opts.md
@@ -31,12 +31,11 @@
31
32 `--chdir DIRECTORY`: Change to the named directory before processing
33 any commands.
34
35
36 `--comfmtflags NUMBER`: Specify flags that control how check-in comments
 
37 and certain other text outputs are formatted for display. The flags are
38 individual bits in `NUMBER`, which must be specified in base 10:
39
40 * _0_ — Uses the revised algorithm with no special handling.
41
@@ -56,10 +55,13 @@
55
56 * _16_ — Looks for the original comment text within the text being
57 printed. Upon matching, a new line will be emitted, thus
58 preserving more of the pre-existing formatting.
59
60
61 `--comment-format NUMBER`: Alias for `--comfmtflags NUMBER`.
62
63
64 `--errorlog ERRLOG`: Name a file to which fossil will log panics,
65 errors, and warnings.
66
67
68
M www/serverext.wiki
+22 -250
--- www/serverext.wiki
+++ www/serverext.wiki
@@ -1,33 +1,31 @@
11
 <title>CGI Server Extensions</title>
22
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.
3
+If you choose to have a [./server.wiki|central server] for your Fossil-based
4
+project (which is entirely optional - Fossil can be use an a pure peer-to-peer
5
+mode) then you can also add CGI extensions to the Fossil websiteite d. These
6
+extensions work like any other CGI program, except that they also have access
7
+to the Fossil login information, so that they can restrict access based on
8
+the currently logged in user. The CGI output can be a stand-alone webpage,
9
+or it can be incorporated into the Fossil site using the standard Fossil
10
+header and footer.
1111
1212
 An example of where this is useful is the
13
-[https://sqlite.org/src/ext/checklist|checklist application] on
14
-the [https://sqlite.org/|SQLite] project. The checklist
13
+[checklist application](https://sqlite.org/src/ext/checklist) on
14
+the [SQLite](https://sqlite.org/) project. The checklist
1515
 helps the SQLite developers track which release tests have passed,
16
-or failed, or are still to be done. The checklist program began as a
16
+or failed, or are still to be done. The checklist used to be a
1717
 stand-alone CGI which kept its own private user database and implemented
18
-its own permissions and login system and provided its own CSS. By
19
-converting checklist into a Fossil extension, the same login that works
20
-for the [https://sqlite.org/src|main SQLite source repository] also works
21
-for the checklist. Permission to change elements of the checklist
22
-is tied on permission to check-in to the main source repository. And
23
-the standard Fossil header menu and footer appear on each page of
24
-the checklist.
25
-
26
-<h2>2.0 How It Works</h2>
27
-
28
-CGI Extensions are disabled by default.
18
+its on permissions and login system. By converting checklist into
19
+a Fossil extension, the same login that works for the
20
+[main SQLite source repository](https://sqlite.org/src) also works
21
+for the checklist. And permission to change elements of the checklist
22
+is based on permission to check-in to the main source repository.
23
+
24
+<h2>How It Works</h2>
25
+
26
+Extensions are off by default.
2927
 An administrator activates the CGI extension mechanism by specifying
3028
 an "Extension Root Directory" or "extroot" as part of the server setup.
3129
 If the Fossil server is itself run as CGI, then add a line to the CGI
3230
 script file that says:
3331
@@ -37,12 +35,12 @@
3735
3836
 Or, if the Fossil server is begin run as using the "fossil server" or
3937
 "fossil ui" or "fossil http" commands, then add an extra
4038
 "--extroot <i>DIRECTORY</i>" option to that command.
4139
42
-The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI.
43
-Files in the DOCUMENT_ROOT are accessed via URLs like this:
40
+The <i>DIRECTORY</i> thus specified becomes the DOCUMENT_ROOT for the
41
+CGI. Files in the DOCUMENT_ROOT are accessed via URLs like this:
4442
4543
 <blockquote>
4644
 https://example-project.org/ext/<i>FILENAME</i>
4745
 </blockquote>
4846
@@ -49,231 +47,5 @@
4947
 In other words, access files in DOCUMENT_ROOT by appending the filename
5048
 relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext]
5149
 page of the Fossil server.
5250
 Files that are readable but not executable are returned as static
5351
 content. Files that are executable are run as CGI.
54
-
55
-<h3>2.1 Example #1</h3>
56
-
57
-The source code repository for SQLite is a Fossil server that is run
58
-as CGI. The URL for the source code repository is [https://sqlite.org/src].
59
-The CGI script looks like this:
60
-
61
-<blockquote><verbatim>
62
-#!/usr/bin/fossil
63
-repository: /fossil/sqlite.fossil
64
-errorlog: /logs/errors.txt
65
-extroot: /sqlite-src-ext
66
-</verbatim></blockquote>
67
-
68
-The "extroot: /sqlite-src-ext" line tells Fossil that it should look for
69
-extension CGIs in the /sqlite-src-ext directory. (All of this is happening
70
-inside of a chroot jail, so putting the document root in a top-level
71
-directory is a reasonable thing to do.)
72
-
73
-When a URL like "https://sqlite.org/src/ext/checklist" is received by the
74
-main webserver, it figures out that the /src part refers to the main
75
-Fossil CGI script and so it runs that script. Fossil gets the remainder
76
-of the URL to work with: "/ext/checklist". Fossil extracts the "/ext"
77
-prefix and uses that to determine that this a CGI extension request.
78
-Then it takes the leftover "/checklist" part and appends it to the
79
-"extroot" to get the filename "/sqlite-src-ext/checklist". Fossil finds
80
-that file to be executable, so it runs it as CGI and returns the result.
81
-
82
-The /sqlite-src-ext/checklist file is a
83
-[https://wapp.tcl.tk|Wapp program]. The current source code to the
84
-this program can be seen at
85
-[https://www.sqlite.org/src/ext/checklist/self] and
86
-recent historical versions are available at
87
-[https://sqlite.org/docsrc/finfo/misc/checklist.tcl] with
88
-older legacy at [https://sqlite.org/checklistapp/timeline?n=all]
89
-
90
-There is a cascade of CGIs happening here. The webserver that receives
91
-the initial HTTP request runs Fossil as a CGI based on the
92
-"https://sqlite.org/src" portion of the URL. The Fossil instance then
93
-runs the checklist sub-CGI based on the "/ext/checklists" suffix. The
94
-output of the sub-CGI is read by Fossil and then relayed on to the
95
-main webserver which in turn relays the result back to the original client.
96
-
97
-<h3>2.2 Example #2</h3>
98
-
99
-The [https://fossil-scm.org/home|Fossil self-hosting repository] is also
100
-a CGI that looks like this:
101
-
102
-<blockquote><verbatim>
103
-#!/usr/bin/fossil
104
-repository: /fossil/fossil.fossil
105
-errorlog: /logs/errors.txt
106
-extroot: /fossil-extroot
107
-</verbatim></blockquote>
108
-
109
-The extroot for this Fossil server is /fossil-extroot and in that directory
110
-is an executable file named "fileup1" - another [https://wapp.tcl.tk|Wapp]
111
-script. (The extension mechanism does not have to use Wapp. You can use
112
-any kind of program you like. But the creator of SQLite and Fossil is fond
113
-of [https://www.tcl.tk|Tcl/Tk] and so he tends to gravitate toward Tcl-based
114
-technologies like Wapp.) The fileup1 script is a demo program that lets
115
-the user upload a file using a form, and then displays that file in the reply.
116
-There is a link on the page that causes the fileup1 script to return a copy
117
-of its own source-code, so you can see how it works.
118
-
119
-<h2>3.0 CGI Inputs</h2>
120
-
121
-The /ext extension mechanism is an ordinary CGI interface. Parameters
122
-are passed to the CGI program using environment variables. The following
123
-standard CGI environment variables are supported:
124
-
125
- * AUTH_TYPE
126
- * AUTH_CONTENT
127
- * CONTENT_LENGTH
128
- * CONTENT_TYPE
129
- * DOCUMENT_ROOT
130
- * GATEWAY_INTERFACE
131
- * HTTP_ACCEPT
132
- * HTTP_ACCEPT_ENCODING
133
- * HTTP_COOKIE
134
- * HTTP_HOST
135
- * HTTP_IF_MODIFIED_SINCE
136
- * HTTP_IF_NONE_MATCH
137
- * HTTP_REFERER
138
- * HTTP_USER_AGENT
139
- * PATH_INFO
140
- * QUERY_STRING
141
- * REMOTE_ADDR
142
- * REMOTE_USER
143
- * REQUEST_METHOD
144
- * REQUEST_URI
145
- * SCRIPT_DIRECTORY
146
- * SCRIPT_FILENAME
147
- * SCRIPT_NAME
148
- * SERVER_NAME
149
- * SERVER_PORT
150
- * SERVER_PROTOCOL
151
-
152
-Do a web search for
153
-"[https://duckduckgo.com/?q=cgi+environment_variables|cgi environment variables]"
154
-to find more detail about what each of the above variables mean and how
155
-they are used.
156
-Live listings of the values of some or all of these environment variables
157
-can be found at links like these:
158
-
159
- * [https://fossil-scm.org/home/test_env]
160
- * [https://sqlite.org/src/ext/checklist/env]
161
-
162
-In addition to the standard CGI environment variables listed above,
163
-Fossil adds the following:
164
-
165
- * FOSSIL_CAPABILITIES
166
- * FOSSIL_REPOSITORY
167
- * FOSSIL_USER
168
-
169
-The FOSSIL_USER string is the name of the logged-in user. This variable
170
-is missing or is an empty string if the user is not logged in. The
171
-FOSSIL_CAPABILITIES string is a list of
172
-[/setup_ulist_notes|Fossil capability letters] that
173
-indicate what permissions the user has on the Fossil repository.
174
-The FOSSIL_REPOSITORY environment variable gives the filename of the
175
-Fossil repository that is running.
176
-
177
-The [https://sqlite.org/src/ext/checklist|checklist application] uses the
178
-FOSSIL_USER environment variable to determine the name of the user and
179
-the FOSSIL_CAPABILITIES variable to determine if the user is allowed to
180
-mark off changes to the checklist. Only users with check-in permission
181
-to the Fossil repository are allowed to mark off checklist items. That
182
-means that the FOSSIL_CAPABILITIES string must contain the letter "i".
183
-Search for "FOSSIL_CAPABILITIES" in the
184
-[https://sqlite.org/src/ext/checklist/self|source listing] to see how
185
-this happens.
186
-
187
-If the HTTP request includes content (for example if this is a POST request)
188
-then the CONTENT_LENGTH value will be positive and the data for the content
189
-will be readable on standard input.
190
-
191
-<h2>4.0 CGI Outputs</h2>
192
-
193
-CGI programs construct a reply by writing to standard output. The first
194
-few lines of output are parameters intended for the webserver that invoked
195
-the CGI. These are followed by a blank line and then the content.
196
-
197
-Typical parameter output looks like this:
198
-
199
-<blockquote><verbatim>
200
-Status: 200 Ok
201
-Content-Type: text/html
202
-</verbatim></blockquote>
203
-
204
-CGI programs can return any content type they want - they are not restricted
205
-to text replies. It is OK for a CGI program to return (for example)
206
-image/png.
207
-
208
-The fields of the CGI response header can be any valid HTTP header fields.
209
-Those that Fossil does not understand are simply relayed back to up the
210
-line to the requester.
211
-
212
-Fossil takes special action with some content types. If the Content-Type
213
-is "application/x-fossil-wiki" or "application/x-markdown" then Fossil
214
-converts the content from [/wiki_rules|Fossil-Wiki] or
215
-[/md_rules|Markdown] into HTML, adding its
216
-own header and footer text according to the repository skin. Content
217
-of type "text/html" is normally passed straight through
218
-unchanged. However, if the text/html content is of the form:
219
-
220
-<blockquote><verbatim>
221
-<div class='fossil-doc' data-title='DOCUMENT TITLE'>
222
-... HTML content there ...
223
-</div>
224
-</verbatim></blockquote>
225
-
226
-In other words, if the outer-most markup of the HTML is a &lt;div&gt;
227
-element with a single class of "fossil-doc",
228
-then Fossil will adds its own header and footer to the HTML. The
229
-page title contained in the added header will be extracted from the
230
-"data-title" attribute.
231
-
232
-Except for the three cases noted above, Fossil makes no changes or
233
-additions to the CGI-generated content. Fossil just passes the verbatim
234
-content back up the stack towards the requester.
235
-
236
-<h2>5.0 Filename Restrictions</h2>
237
-
238
-For security reasons, Fossil places restrictions on the names of files
239
-in the extroot directory that can participate in the extension CGI
240
-mechanism:
241
-
242
- 1. Filenames must consist of only ASCII alphanumeric characters,
243
- ".", "_", and "-", and of course "/" as the file separator.
244
- Files with names that includes spaces or
245
- other punctuation or special characters are ignored.
246
-
247
- 2. No element of the pathname can begin with "." or "-". Files or
248
- directories whose names begin with "." or "-" are ignored.
249
-
250
-If a CGI program requires separate data files, it is safe to put those
251
-files in the same directory as the CGI program itself as long as the names
252
-of the data files contain special characters that cause them to be ignored
253
-by Fossil.
254
-
255
-<h2>6.0 Trouble-Shooting Hints</h2>
256
-
257
-Remember that the /ext will return any file in the extroot directory
258
-hierarchy as static content if the file is readable but not executable.
259
-When initially setting up the /ext mechanism, it is sometimes helpful
260
-to verify that you are able to receive static content prior to working
261
-on getting your CGIs working. Also remember that CGIs must be
262
-executable files.
263
-
264
-Fossil likes to run inside a chroot jail, and will automatically put
265
-itself inside a chroot jail if it can. The sub-CGI program will also
266
-run inside this same chroot jail. Make sure all embedded pathnames
267
-have been adjusted accordingly and that all resources needed by the
268
-CGI program are available within the chroot jail.
269
-
270
-If anything goes wrong while trying to process an /ext page, Fossil
271
-returns a 404 Not Found error with no details. However, if the requester
272
-is logged in as a user that has Debug privilege (capability letter "D")
273
-then additional diagnostic information may be included in the output.
274
-
275
-If the /ext page has a "fossil-ext-debug=1" query parameter and if
276
-the requester is logged in as a user with Debug privilege, then the
277
-CGI output is returned verbatim, as text/plain and with the original
278
-header intact. This is useful for trying diagnosing problems with the
279
-CGI script.
28052
--- www/serverext.wiki
+++ www/serverext.wiki
@@ -1,33 +1,31 @@
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.
11
12 An example of where this is useful is the
13 [https://sqlite.org/src/ext/checklist|checklist application] on
14 the [https://sqlite.org/|SQLite] project. The checklist
15 helps the SQLite developers track which release tests have passed,
16 or failed, or are still to be done. The checklist program began as a
17 stand-alone CGI which kept its own private user database and implemented
18 its own permissions and login system and provided its own CSS. By
19 converting checklist into a Fossil extension, the same login that works
20 for the [https://sqlite.org/src|main SQLite source repository] also works
21 for the checklist. Permission to change elements of the checklist
22 is tied on permission to check-in to the main source repository. And
23 the standard Fossil header menu and footer appear on each page of
24 the checklist.
25
26 <h2>2.0 How It Works</h2>
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 CGI, then add a line to the CGI
32 script file that says:
33
@@ -37,12 +35,12 @@
37
38 Or, if the Fossil server is begin run as using the "fossil server" or
39 "fossil ui" or "fossil http" commands, then add an extra
40 "--extroot <i>DIRECTORY</i>" option to that command.
41
42 The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI.
43 Files in the DOCUMENT_ROOT are accessed via URLs like this:
44
45 <blockquote>
46 https://example-project.org/ext/<i>FILENAME</i>
47 </blockquote>
48
@@ -49,231 +47,5 @@
49 In other words, access files in DOCUMENT_ROOT by appending the filename
50 relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext]
51 page of the Fossil server.
52 Files that are readable but not executable are returned as static
53 content. Files that are executable are run as CGI.
54
55 <h3>2.1 Example #1</h3>
56
57 The source code repository for SQLite is a Fossil server that is run
58 as CGI. The URL for the source code repository is [https://sqlite.org/src].
59 The CGI script looks like this:
60
61 <blockquote><verbatim>
62 #!/usr/bin/fossil
63 repository: /fossil/sqlite.fossil
64 errorlog: /logs/errors.txt
65 extroot: /sqlite-src-ext
66 </verbatim></blockquote>
67
68 The "extroot: /sqlite-src-ext" line tells Fossil that it should look for
69 extension CGIs in the /sqlite-src-ext directory. (All of this is happening
70 inside of a chroot jail, so putting the document root in a top-level
71 directory is a reasonable thing to do.)
72
73 When a URL like "https://sqlite.org/src/ext/checklist" is received by the
74 main webserver, it figures out that the /src part refers to the main
75 Fossil CGI script and so it runs that script. Fossil gets the remainder
76 of the URL to work with: "/ext/checklist". Fossil extracts the "/ext"
77 prefix and uses that to determine that this a CGI extension request.
78 Then it takes the leftover "/checklist" part and appends it to the
79 "extroot" to get the filename "/sqlite-src-ext/checklist". Fossil finds
80 that file to be executable, so it runs it as CGI and returns the result.
81
82 The /sqlite-src-ext/checklist file is a
83 [https://wapp.tcl.tk|Wapp program]. The current source code to the
84 this program can be seen at
85 [https://www.sqlite.org/src/ext/checklist/self] and
86 recent historical versions are available at
87 [https://sqlite.org/docsrc/finfo/misc/checklist.tcl] with
88 older legacy at [https://sqlite.org/checklistapp/timeline?n=all]
89
90 There is a cascade of CGIs happening here. The webserver that receives
91 the initial HTTP request runs Fossil as a CGI based on the
92 "https://sqlite.org/src" portion of the URL. The Fossil instance then
93 runs the checklist sub-CGI based on the "/ext/checklists" suffix. The
94 output of the sub-CGI is read by Fossil and then relayed on to the
95 main webserver which in turn relays the result back to the original client.
96
97 <h3>2.2 Example #2</h3>
98
99 The [https://fossil-scm.org/home|Fossil self-hosting repository] is also
100 a CGI that looks like this:
101
102 <blockquote><verbatim>
103 #!/usr/bin/fossil
104 repository: /fossil/fossil.fossil
105 errorlog: /logs/errors.txt
106 extroot: /fossil-extroot
107 </verbatim></blockquote>
108
109 The extroot for this Fossil server is /fossil-extroot and in that directory
110 is an executable file named "fileup1" - another [https://wapp.tcl.tk|Wapp]
111 script. (The extension mechanism does not have to use Wapp. You can use
112 any kind of program you like. But the creator of SQLite and Fossil is fond
113 of [https://www.tcl.tk|Tcl/Tk] and so he tends to gravitate toward Tcl-based
114 technologies like Wapp.) The fileup1 script is a demo program that lets
115 the user upload a file using a form, and then displays that file in the reply.
116 There is a link on the page that causes the fileup1 script to return a copy
117 of its own source-code, so you can see how it works.
118
119 <h2>3.0 CGI Inputs</h2>
120
121 The /ext extension mechanism is an ordinary CGI interface. Parameters
122 are passed to the CGI program using environment variables. The following
123 standard CGI environment variables are supported:
124
125 * AUTH_TYPE
126 * AUTH_CONTENT
127 * CONTENT_LENGTH
128 * CONTENT_TYPE
129 * DOCUMENT_ROOT
130 * GATEWAY_INTERFACE
131 * HTTP_ACCEPT
132 * HTTP_ACCEPT_ENCODING
133 * HTTP_COOKIE
134 * HTTP_HOST
135 * HTTP_IF_MODIFIED_SINCE
136 * HTTP_IF_NONE_MATCH
137 * HTTP_REFERER
138 * HTTP_USER_AGENT
139 * PATH_INFO
140 * QUERY_STRING
141 * REMOTE_ADDR
142 * REMOTE_USER
143 * REQUEST_METHOD
144 * REQUEST_URI
145 * SCRIPT_DIRECTORY
146 * SCRIPT_FILENAME
147 * SCRIPT_NAME
148 * SERVER_NAME
149 * SERVER_PORT
150 * SERVER_PROTOCOL
151
152 Do a web search for
153 "[https://duckduckgo.com/?q=cgi+environment_variables|cgi environment variables]"
154 to find more detail about what each of the above variables mean and how
155 they are used.
156 Live listings of the values of some or all of these environment variables
157 can be found at links like these:
158
159 * [https://fossil-scm.org/home/test_env]
160 * [https://sqlite.org/src/ext/checklist/env]
161
162 In addition to the standard CGI environment variables listed above,
163 Fossil adds the following:
164
165 * FOSSIL_CAPABILITIES
166 * FOSSIL_REPOSITORY
167 * FOSSIL_USER
168
169 The FOSSIL_USER string is the name of the logged-in user. This variable
170 is missing or is an empty string if the user is not logged in. The
171 FOSSIL_CAPABILITIES string is a list of
172 [/setup_ulist_notes|Fossil capability letters] that
173 indicate what permissions the user has on the Fossil repository.
174 The FOSSIL_REPOSITORY environment variable gives the filename of the
175 Fossil repository that is running.
176
177 The [https://sqlite.org/src/ext/checklist|checklist application] uses the
178 FOSSIL_USER environment variable to determine the name of the user and
179 the FOSSIL_CAPABILITIES variable to determine if the user is allowed to
180 mark off changes to the checklist. Only users with check-in permission
181 to the Fossil repository are allowed to mark off checklist items. That
182 means that the FOSSIL_CAPABILITIES string must contain the letter "i".
183 Search for "FOSSIL_CAPABILITIES" in the
184 [https://sqlite.org/src/ext/checklist/self|source listing] to see how
185 this happens.
186
187 If the HTTP request includes content (for example if this is a POST request)
188 then the CONTENT_LENGTH value will be positive and the data for the content
189 will be readable on standard input.
190
191 <h2>4.0 CGI Outputs</h2>
192
193 CGI programs construct a reply by writing to standard output. The first
194 few lines of output are parameters intended for the webserver that invoked
195 the CGI. These are followed by a blank line and then the content.
196
197 Typical parameter output looks like this:
198
199 <blockquote><verbatim>
200 Status: 200 Ok
201 Content-Type: text/html
202 </verbatim></blockquote>
203
204 CGI programs can return any content type they want - they are not restricted
205 to text replies. It is OK for a CGI program to return (for example)
206 image/png.
207
208 The fields of the CGI response header can be any valid HTTP header fields.
209 Those that Fossil does not understand are simply relayed back to up the
210 line to the requester.
211
212 Fossil takes special action with some content types. If the Content-Type
213 is "application/x-fossil-wiki" or "application/x-markdown" then Fossil
214 converts the content from [/wiki_rules|Fossil-Wiki] or
215 [/md_rules|Markdown] into HTML, adding its
216 own header and footer text according to the repository skin. Content
217 of type "text/html" is normally passed straight through
218 unchanged. However, if the text/html content is of the form:
219
220 <blockquote><verbatim>
221 <div class='fossil-doc' data-title='DOCUMENT TITLE'>
222 ... HTML content there ...
223 </div>
224 </verbatim></blockquote>
225
226 In other words, if the outer-most markup of the HTML is a &lt;div&gt;
227 element with a single class of "fossil-doc",
228 then Fossil will adds its own header and footer to the HTML. The
229 page title contained in the added header will be extracted from the
230 "data-title" attribute.
231
232 Except for the three cases noted above, Fossil makes no changes or
233 additions to the CGI-generated content. Fossil just passes the verbatim
234 content back up the stack towards the requester.
235
236 <h2>5.0 Filename Restrictions</h2>
237
238 For security reasons, Fossil places restrictions on the names of files
239 in the extroot directory that can participate in the extension CGI
240 mechanism:
241
242 1. Filenames must consist of only ASCII alphanumeric characters,
243 ".", "_", and "-", and of course "/" as the file separator.
244 Files with names that includes spaces or
245 other punctuation or special characters are ignored.
246
247 2. No element of the pathname can begin with "." or "-". Files or
248 directories whose names begin with "." or "-" are ignored.
249
250 If a CGI program requires separate data files, it is safe to put those
251 files in the same directory as the CGI program itself as long as the names
252 of the data files contain special characters that cause them to be ignored
253 by Fossil.
254
255 <h2>6.0 Trouble-Shooting Hints</h2>
256
257 Remember that the /ext will return any file in the extroot directory
258 hierarchy as static content if the file is readable but not executable.
259 When initially setting up the /ext mechanism, it is sometimes helpful
260 to verify that you are able to receive static content prior to working
261 on getting your CGIs working. Also remember that CGIs must be
262 executable files.
263
264 Fossil likes to run inside a chroot jail, and will automatically put
265 itself inside a chroot jail if it can. The sub-CGI program will also
266 run inside this same chroot jail. Make sure all embedded pathnames
267 have been adjusted accordingly and that all resources needed by the
268 CGI program are available within the chroot jail.
269
270 If anything goes wrong while trying to process an /ext page, Fossil
271 returns a 404 Not Found error with no details. However, if the requester
272 is logged in as a user that has Debug privilege (capability letter "D")
273 then additional diagnostic information may be included in the output.
274
275 If the /ext page has a "fossil-ext-debug=1" query parameter and if
276 the requester is logged in as a user with Debug privilege, then the
277 CGI output is returned verbatim, as text/plain and with the original
278 header intact. This is useful for trying diagnosing problems with the
279 CGI script.
280
--- www/serverext.wiki
+++ www/serverext.wiki
@@ -1,33 +1,31 @@
1 <title>CGI Server Extensions</title>
2
3 If you choose to have a [./server.wiki|central server] for your Fossil-based
4 project (which is entirely optional - Fossil can be use an a pure peer-to-peer
5 mode) then you can also add CGI extensions to the Fossil websiteite d. These
6 extensions work like any other CGI program, except that they also have access
7 to the Fossil login information, so that they can restrict access based on
8 the currently logged in user. The CGI output can be a stand-alone webpage,
9 or it can be incorporated into the Fossil site using the standard Fossil
10 header and footer.
11
12 An example of where this is useful is the
13 [checklist application](https://sqlite.org/src/ext/checklist) on
14 the [SQLite](https://sqlite.org/) project. The checklist
15 helps the SQLite developers track which release tests have passed,
16 or failed, or are still to be done. The checklist used to be a
17 stand-alone CGI which kept its own private user database and implemented
18 its on permissions and login system. By converting checklist into
19 a Fossil extension, the same login that works for the
20 [main SQLite source repository](https://sqlite.org/src) also works
21 for the checklist. And permission to change elements of the checklist
22 is based on permission to check-in to the main source repository.
23
24 <h2>How It Works</h2>
25
26 Extensions are off by default.
 
 
27 An administrator activates the CGI extension mechanism by specifying
28 an "Extension Root Directory" or "extroot" as part of the server setup.
29 If the Fossil server is itself run as CGI, then add a line to the CGI
30 script file that says:
31
@@ -37,12 +35,12 @@
35
36 Or, if the Fossil server is begin run as using the "fossil server" or
37 "fossil ui" or "fossil http" commands, then add an extra
38 "--extroot <i>DIRECTORY</i>" option to that command.
39
40 The <i>DIRECTORY</i> thus specified becomes the DOCUMENT_ROOT for the
41 CGI. Files in the DOCUMENT_ROOT are accessed via URLs like this:
42
43 <blockquote>
44 https://example-project.org/ext/<i>FILENAME</i>
45 </blockquote>
46
@@ -49,231 +47,5 @@
47 In other words, access files in DOCUMENT_ROOT by appending the filename
48 relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext]
49 page of the Fossil server.
50 Files that are readable but not executable are returned as static
51 content. Files that are executable are run as CGI.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
52
M www/serverext.wiki
+22 -250
--- www/serverext.wiki
+++ www/serverext.wiki
@@ -1,33 +1,31 @@
11
 <title>CGI Server Extensions</title>
22
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.
3
+If you choose to have a [./server.wiki|central server] for your Fossil-based
4
+project (which is entirely optional - Fossil can be use an a pure peer-to-peer
5
+mode) then you can also add CGI extensions to the Fossil websiteite d. These
6
+extensions work like any other CGI program, except that they also have access
7
+to the Fossil login information, so that they can restrict access based on
8
+the currently logged in user. The CGI output can be a stand-alone webpage,
9
+or it can be incorporated into the Fossil site using the standard Fossil
10
+header and footer.
1111
1212
 An example of where this is useful is the
13
-[https://sqlite.org/src/ext/checklist|checklist application] on
14
-the [https://sqlite.org/|SQLite] project. The checklist
13
+[checklist application](https://sqlite.org/src/ext/checklist) on
14
+the [SQLite](https://sqlite.org/) project. The checklist
1515
 helps the SQLite developers track which release tests have passed,
16
-or failed, or are still to be done. The checklist program began as a
16
+or failed, or are still to be done. The checklist used to be a
1717
 stand-alone CGI which kept its own private user database and implemented
18
-its own permissions and login system and provided its own CSS. By
19
-converting checklist into a Fossil extension, the same login that works
20
-for the [https://sqlite.org/src|main SQLite source repository] also works
21
-for the checklist. Permission to change elements of the checklist
22
-is tied on permission to check-in to the main source repository. And
23
-the standard Fossil header menu and footer appear on each page of
24
-the checklist.
25
-
26
-<h2>2.0 How It Works</h2>
27
-
28
-CGI Extensions are disabled by default.
18
+its on permissions and login system. By converting checklist into
19
+a Fossil extension, the same login that works for the
20
+[main SQLite source repository](https://sqlite.org/src) also works
21
+for the checklist. And permission to change elements of the checklist
22
+is based on permission to check-in to the main source repository.
23
+
24
+<h2>How It Works</h2>
25
+
26
+Extensions are off by default.
2927
 An administrator activates the CGI extension mechanism by specifying
3028
 an "Extension Root Directory" or "extroot" as part of the server setup.
3129
 If the Fossil server is itself run as CGI, then add a line to the CGI
3230
 script file that says:
3331
@@ -37,12 +35,12 @@
3735
3836
 Or, if the Fossil server is begin run as using the "fossil server" or
3937
 "fossil ui" or "fossil http" commands, then add an extra
4038
 "--extroot <i>DIRECTORY</i>" option to that command.
4139
42
-The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI.
43
-Files in the DOCUMENT_ROOT are accessed via URLs like this:
40
+The <i>DIRECTORY</i> thus specified becomes the DOCUMENT_ROOT for the
41
+CGI. Files in the DOCUMENT_ROOT are accessed via URLs like this:
4442
4543
 <blockquote>
4644
 https://example-project.org/ext/<i>FILENAME</i>
4745
 </blockquote>
4846
@@ -49,231 +47,5 @@
4947
 In other words, access files in DOCUMENT_ROOT by appending the filename
5048
 relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext]
5149
 page of the Fossil server.
5250
 Files that are readable but not executable are returned as static
5351
 content. Files that are executable are run as CGI.
54
-
55
-<h3>2.1 Example #1</h3>
56
-
57
-The source code repository for SQLite is a Fossil server that is run
58
-as CGI. The URL for the source code repository is [https://sqlite.org/src].
59
-The CGI script looks like this:
60
-
61
-<blockquote><verbatim>
62
-#!/usr/bin/fossil
63
-repository: /fossil/sqlite.fossil
64
-errorlog: /logs/errors.txt
65
-extroot: /sqlite-src-ext
66
-</verbatim></blockquote>
67
-
68
-The "extroot: /sqlite-src-ext" line tells Fossil that it should look for
69
-extension CGIs in the /sqlite-src-ext directory. (All of this is happening
70
-inside of a chroot jail, so putting the document root in a top-level
71
-directory is a reasonable thing to do.)
72
-
73
-When a URL like "https://sqlite.org/src/ext/checklist" is received by the
74
-main webserver, it figures out that the /src part refers to the main
75
-Fossil CGI script and so it runs that script. Fossil gets the remainder
76
-of the URL to work with: "/ext/checklist". Fossil extracts the "/ext"
77
-prefix and uses that to determine that this a CGI extension request.
78
-Then it takes the leftover "/checklist" part and appends it to the
79
-"extroot" to get the filename "/sqlite-src-ext/checklist". Fossil finds
80
-that file to be executable, so it runs it as CGI and returns the result.
81
-
82
-The /sqlite-src-ext/checklist file is a
83
-[https://wapp.tcl.tk|Wapp program]. The current source code to the
84
-this program can be seen at
85
-[https://www.sqlite.org/src/ext/checklist/self] and
86
-recent historical versions are available at
87
-[https://sqlite.org/docsrc/finfo/misc/checklist.tcl] with
88
-older legacy at [https://sqlite.org/checklistapp/timeline?n=all]
89
-
90
-There is a cascade of CGIs happening here. The webserver that receives
91
-the initial HTTP request runs Fossil as a CGI based on the
92
-"https://sqlite.org/src" portion of the URL. The Fossil instance then
93
-runs the checklist sub-CGI based on the "/ext/checklists" suffix. The
94
-output of the sub-CGI is read by Fossil and then relayed on to the
95
-main webserver which in turn relays the result back to the original client.
96
-
97
-<h3>2.2 Example #2</h3>
98
-
99
-The [https://fossil-scm.org/home|Fossil self-hosting repository] is also
100
-a CGI that looks like this:
101
-
102
-<blockquote><verbatim>
103
-#!/usr/bin/fossil
104
-repository: /fossil/fossil.fossil
105
-errorlog: /logs/errors.txt
106
-extroot: /fossil-extroot
107
-</verbatim></blockquote>
108
-
109
-The extroot for this Fossil server is /fossil-extroot and in that directory
110
-is an executable file named "fileup1" - another [https://wapp.tcl.tk|Wapp]
111
-script. (The extension mechanism does not have to use Wapp. You can use
112
-any kind of program you like. But the creator of SQLite and Fossil is fond
113
-of [https://www.tcl.tk|Tcl/Tk] and so he tends to gravitate toward Tcl-based
114
-technologies like Wapp.) The fileup1 script is a demo program that lets
115
-the user upload a file using a form, and then displays that file in the reply.
116
-There is a link on the page that causes the fileup1 script to return a copy
117
-of its own source-code, so you can see how it works.
118
-
119
-<h2>3.0 CGI Inputs</h2>
120
-
121
-The /ext extension mechanism is an ordinary CGI interface. Parameters
122
-are passed to the CGI program using environment variables. The following
123
-standard CGI environment variables are supported:
124
-
125
- * AUTH_TYPE
126
- * AUTH_CONTENT
127
- * CONTENT_LENGTH
128
- * CONTENT_TYPE
129
- * DOCUMENT_ROOT
130
- * GATEWAY_INTERFACE
131
- * HTTP_ACCEPT
132
- * HTTP_ACCEPT_ENCODING
133
- * HTTP_COOKIE
134
- * HTTP_HOST
135
- * HTTP_IF_MODIFIED_SINCE
136
- * HTTP_IF_NONE_MATCH
137
- * HTTP_REFERER
138
- * HTTP_USER_AGENT
139
- * PATH_INFO
140
- * QUERY_STRING
141
- * REMOTE_ADDR
142
- * REMOTE_USER
143
- * REQUEST_METHOD
144
- * REQUEST_URI
145
- * SCRIPT_DIRECTORY
146
- * SCRIPT_FILENAME
147
- * SCRIPT_NAME
148
- * SERVER_NAME
149
- * SERVER_PORT
150
- * SERVER_PROTOCOL
151
-
152
-Do a web search for
153
-"[https://duckduckgo.com/?q=cgi+environment_variables|cgi environment variables]"
154
-to find more detail about what each of the above variables mean and how
155
-they are used.
156
-Live listings of the values of some or all of these environment variables
157
-can be found at links like these:
158
-
159
- * [https://fossil-scm.org/home/test_env]
160
- * [https://sqlite.org/src/ext/checklist/env]
161
-
162
-In addition to the standard CGI environment variables listed above,
163
-Fossil adds the following:
164
-
165
- * FOSSIL_CAPABILITIES
166
- * FOSSIL_REPOSITORY
167
- * FOSSIL_USER
168
-
169
-The FOSSIL_USER string is the name of the logged-in user. This variable
170
-is missing or is an empty string if the user is not logged in. The
171
-FOSSIL_CAPABILITIES string is a list of
172
-[/setup_ulist_notes|Fossil capability letters] that
173
-indicate what permissions the user has on the Fossil repository.
174
-The FOSSIL_REPOSITORY environment variable gives the filename of the
175
-Fossil repository that is running.
176
-
177
-The [https://sqlite.org/src/ext/checklist|checklist application] uses the
178
-FOSSIL_USER environment variable to determine the name of the user and
179
-the FOSSIL_CAPABILITIES variable to determine if the user is allowed to
180
-mark off changes to the checklist. Only users with check-in permission
181
-to the Fossil repository are allowed to mark off checklist items. That
182
-means that the FOSSIL_CAPABILITIES string must contain the letter "i".
183
-Search for "FOSSIL_CAPABILITIES" in the
184
-[https://sqlite.org/src/ext/checklist/self|source listing] to see how
185
-this happens.
186
-
187
-If the HTTP request includes content (for example if this is a POST request)
188
-then the CONTENT_LENGTH value will be positive and the data for the content
189
-will be readable on standard input.
190
-
191
-<h2>4.0 CGI Outputs</h2>
192
-
193
-CGI programs construct a reply by writing to standard output. The first
194
-few lines of output are parameters intended for the webserver that invoked
195
-the CGI. These are followed by a blank line and then the content.
196
-
197
-Typical parameter output looks like this:
198
-
199
-<blockquote><verbatim>
200
-Status: 200 Ok
201
-Content-Type: text/html
202
-</verbatim></blockquote>
203
-
204
-CGI programs can return any content type they want - they are not restricted
205
-to text replies. It is OK for a CGI program to return (for example)
206
-image/png.
207
-
208
-The fields of the CGI response header can be any valid HTTP header fields.
209
-Those that Fossil does not understand are simply relayed back to up the
210
-line to the requester.
211
-
212
-Fossil takes special action with some content types. If the Content-Type
213
-is "application/x-fossil-wiki" or "application/x-markdown" then Fossil
214
-converts the content from [/wiki_rules|Fossil-Wiki] or
215
-[/md_rules|Markdown] into HTML, adding its
216
-own header and footer text according to the repository skin. Content
217
-of type "text/html" is normally passed straight through
218
-unchanged. However, if the text/html content is of the form:
219
-
220
-<blockquote><verbatim>
221
-<div class='fossil-doc' data-title='DOCUMENT TITLE'>
222
-... HTML content there ...
223
-</div>
224
-</verbatim></blockquote>
225
-
226
-In other words, if the outer-most markup of the HTML is a &lt;div&gt;
227
-element with a single class of "fossil-doc",
228
-then Fossil will adds its own header and footer to the HTML. The
229
-page title contained in the added header will be extracted from the
230
-"data-title" attribute.
231
-
232
-Except for the three cases noted above, Fossil makes no changes or
233
-additions to the CGI-generated content. Fossil just passes the verbatim
234
-content back up the stack towards the requester.
235
-
236
-<h2>5.0 Filename Restrictions</h2>
237
-
238
-For security reasons, Fossil places restrictions on the names of files
239
-in the extroot directory that can participate in the extension CGI
240
-mechanism:
241
-
242
- 1. Filenames must consist of only ASCII alphanumeric characters,
243
- ".", "_", and "-", and of course "/" as the file separator.
244
- Files with names that includes spaces or
245
- other punctuation or special characters are ignored.
246
-
247
- 2. No element of the pathname can begin with "." or "-". Files or
248
- directories whose names begin with "." or "-" are ignored.
249
-
250
-If a CGI program requires separate data files, it is safe to put those
251
-files in the same directory as the CGI program itself as long as the names
252
-of the data files contain special characters that cause them to be ignored
253
-by Fossil.
254
-
255
-<h2>6.0 Trouble-Shooting Hints</h2>
256
-
257
-Remember that the /ext will return any file in the extroot directory
258
-hierarchy as static content if the file is readable but not executable.
259
-When initially setting up the /ext mechanism, it is sometimes helpful
260
-to verify that you are able to receive static content prior to working
261
-on getting your CGIs working. Also remember that CGIs must be
262
-executable files.
263
-
264
-Fossil likes to run inside a chroot jail, and will automatically put
265
-itself inside a chroot jail if it can. The sub-CGI program will also
266
-run inside this same chroot jail. Make sure all embedded pathnames
267
-have been adjusted accordingly and that all resources needed by the
268
-CGI program are available within the chroot jail.
269
-
270
-If anything goes wrong while trying to process an /ext page, Fossil
271
-returns a 404 Not Found error with no details. However, if the requester
272
-is logged in as a user that has Debug privilege (capability letter "D")
273
-then additional diagnostic information may be included in the output.
274
-
275
-If the /ext page has a "fossil-ext-debug=1" query parameter and if
276
-the requester is logged in as a user with Debug privilege, then the
277
-CGI output is returned verbatim, as text/plain and with the original
278
-header intact. This is useful for trying diagnosing problems with the
279
-CGI script.
28052
--- www/serverext.wiki
+++ www/serverext.wiki
@@ -1,33 +1,31 @@
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.
11
12 An example of where this is useful is the
13 [https://sqlite.org/src/ext/checklist|checklist application] on
14 the [https://sqlite.org/|SQLite] project. The checklist
15 helps the SQLite developers track which release tests have passed,
16 or failed, or are still to be done. The checklist program began as a
17 stand-alone CGI which kept its own private user database and implemented
18 its own permissions and login system and provided its own CSS. By
19 converting checklist into a Fossil extension, the same login that works
20 for the [https://sqlite.org/src|main SQLite source repository] also works
21 for the checklist. Permission to change elements of the checklist
22 is tied on permission to check-in to the main source repository. And
23 the standard Fossil header menu and footer appear on each page of
24 the checklist.
25
26 <h2>2.0 How It Works</h2>
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 CGI, then add a line to the CGI
32 script file that says:
33
@@ -37,12 +35,12 @@
37
38 Or, if the Fossil server is begin run as using the "fossil server" or
39 "fossil ui" or "fossil http" commands, then add an extra
40 "--extroot <i>DIRECTORY</i>" option to that command.
41
42 The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI.
43 Files in the DOCUMENT_ROOT are accessed via URLs like this:
44
45 <blockquote>
46 https://example-project.org/ext/<i>FILENAME</i>
47 </blockquote>
48
@@ -49,231 +47,5 @@
49 In other words, access files in DOCUMENT_ROOT by appending the filename
50 relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext]
51 page of the Fossil server.
52 Files that are readable but not executable are returned as static
53 content. Files that are executable are run as CGI.
54
55 <h3>2.1 Example #1</h3>
56
57 The source code repository for SQLite is a Fossil server that is run
58 as CGI. The URL for the source code repository is [https://sqlite.org/src].
59 The CGI script looks like this:
60
61 <blockquote><verbatim>
62 #!/usr/bin/fossil
63 repository: /fossil/sqlite.fossil
64 errorlog: /logs/errors.txt
65 extroot: /sqlite-src-ext
66 </verbatim></blockquote>
67
68 The "extroot: /sqlite-src-ext" line tells Fossil that it should look for
69 extension CGIs in the /sqlite-src-ext directory. (All of this is happening
70 inside of a chroot jail, so putting the document root in a top-level
71 directory is a reasonable thing to do.)
72
73 When a URL like "https://sqlite.org/src/ext/checklist" is received by the
74 main webserver, it figures out that the /src part refers to the main
75 Fossil CGI script and so it runs that script. Fossil gets the remainder
76 of the URL to work with: "/ext/checklist". Fossil extracts the "/ext"
77 prefix and uses that to determine that this a CGI extension request.
78 Then it takes the leftover "/checklist" part and appends it to the
79 "extroot" to get the filename "/sqlite-src-ext/checklist". Fossil finds
80 that file to be executable, so it runs it as CGI and returns the result.
81
82 The /sqlite-src-ext/checklist file is a
83 [https://wapp.tcl.tk|Wapp program]. The current source code to the
84 this program can be seen at
85 [https://www.sqlite.org/src/ext/checklist/self] and
86 recent historical versions are available at
87 [https://sqlite.org/docsrc/finfo/misc/checklist.tcl] with
88 older legacy at [https://sqlite.org/checklistapp/timeline?n=all]
89
90 There is a cascade of CGIs happening here. The webserver that receives
91 the initial HTTP request runs Fossil as a CGI based on the
92 "https://sqlite.org/src" portion of the URL. The Fossil instance then
93 runs the checklist sub-CGI based on the "/ext/checklists" suffix. The
94 output of the sub-CGI is read by Fossil and then relayed on to the
95 main webserver which in turn relays the result back to the original client.
96
97 <h3>2.2 Example #2</h3>
98
99 The [https://fossil-scm.org/home|Fossil self-hosting repository] is also
100 a CGI that looks like this:
101
102 <blockquote><verbatim>
103 #!/usr/bin/fossil
104 repository: /fossil/fossil.fossil
105 errorlog: /logs/errors.txt
106 extroot: /fossil-extroot
107 </verbatim></blockquote>
108
109 The extroot for this Fossil server is /fossil-extroot and in that directory
110 is an executable file named "fileup1" - another [https://wapp.tcl.tk|Wapp]
111 script. (The extension mechanism does not have to use Wapp. You can use
112 any kind of program you like. But the creator of SQLite and Fossil is fond
113 of [https://www.tcl.tk|Tcl/Tk] and so he tends to gravitate toward Tcl-based
114 technologies like Wapp.) The fileup1 script is a demo program that lets
115 the user upload a file using a form, and then displays that file in the reply.
116 There is a link on the page that causes the fileup1 script to return a copy
117 of its own source-code, so you can see how it works.
118
119 <h2>3.0 CGI Inputs</h2>
120
121 The /ext extension mechanism is an ordinary CGI interface. Parameters
122 are passed to the CGI program using environment variables. The following
123 standard CGI environment variables are supported:
124
125 * AUTH_TYPE
126 * AUTH_CONTENT
127 * CONTENT_LENGTH
128 * CONTENT_TYPE
129 * DOCUMENT_ROOT
130 * GATEWAY_INTERFACE
131 * HTTP_ACCEPT
132 * HTTP_ACCEPT_ENCODING
133 * HTTP_COOKIE
134 * HTTP_HOST
135 * HTTP_IF_MODIFIED_SINCE
136 * HTTP_IF_NONE_MATCH
137 * HTTP_REFERER
138 * HTTP_USER_AGENT
139 * PATH_INFO
140 * QUERY_STRING
141 * REMOTE_ADDR
142 * REMOTE_USER
143 * REQUEST_METHOD
144 * REQUEST_URI
145 * SCRIPT_DIRECTORY
146 * SCRIPT_FILENAME
147 * SCRIPT_NAME
148 * SERVER_NAME
149 * SERVER_PORT
150 * SERVER_PROTOCOL
151
152 Do a web search for
153 "[https://duckduckgo.com/?q=cgi+environment_variables|cgi environment variables]"
154 to find more detail about what each of the above variables mean and how
155 they are used.
156 Live listings of the values of some or all of these environment variables
157 can be found at links like these:
158
159 * [https://fossil-scm.org/home/test_env]
160 * [https://sqlite.org/src/ext/checklist/env]
161
162 In addition to the standard CGI environment variables listed above,
163 Fossil adds the following:
164
165 * FOSSIL_CAPABILITIES
166 * FOSSIL_REPOSITORY
167 * FOSSIL_USER
168
169 The FOSSIL_USER string is the name of the logged-in user. This variable
170 is missing or is an empty string if the user is not logged in. The
171 FOSSIL_CAPABILITIES string is a list of
172 [/setup_ulist_notes|Fossil capability letters] that
173 indicate what permissions the user has on the Fossil repository.
174 The FOSSIL_REPOSITORY environment variable gives the filename of the
175 Fossil repository that is running.
176
177 The [https://sqlite.org/src/ext/checklist|checklist application] uses the
178 FOSSIL_USER environment variable to determine the name of the user and
179 the FOSSIL_CAPABILITIES variable to determine if the user is allowed to
180 mark off changes to the checklist. Only users with check-in permission
181 to the Fossil repository are allowed to mark off checklist items. That
182 means that the FOSSIL_CAPABILITIES string must contain the letter "i".
183 Search for "FOSSIL_CAPABILITIES" in the
184 [https://sqlite.org/src/ext/checklist/self|source listing] to see how
185 this happens.
186
187 If the HTTP request includes content (for example if this is a POST request)
188 then the CONTENT_LENGTH value will be positive and the data for the content
189 will be readable on standard input.
190
191 <h2>4.0 CGI Outputs</h2>
192
193 CGI programs construct a reply by writing to standard output. The first
194 few lines of output are parameters intended for the webserver that invoked
195 the CGI. These are followed by a blank line and then the content.
196
197 Typical parameter output looks like this:
198
199 <blockquote><verbatim>
200 Status: 200 Ok
201 Content-Type: text/html
202 </verbatim></blockquote>
203
204 CGI programs can return any content type they want - they are not restricted
205 to text replies. It is OK for a CGI program to return (for example)
206 image/png.
207
208 The fields of the CGI response header can be any valid HTTP header fields.
209 Those that Fossil does not understand are simply relayed back to up the
210 line to the requester.
211
212 Fossil takes special action with some content types. If the Content-Type
213 is "application/x-fossil-wiki" or "application/x-markdown" then Fossil
214 converts the content from [/wiki_rules|Fossil-Wiki] or
215 [/md_rules|Markdown] into HTML, adding its
216 own header and footer text according to the repository skin. Content
217 of type "text/html" is normally passed straight through
218 unchanged. However, if the text/html content is of the form:
219
220 <blockquote><verbatim>
221 <div class='fossil-doc' data-title='DOCUMENT TITLE'>
222 ... HTML content there ...
223 </div>
224 </verbatim></blockquote>
225
226 In other words, if the outer-most markup of the HTML is a &lt;div&gt;
227 element with a single class of "fossil-doc",
228 then Fossil will adds its own header and footer to the HTML. The
229 page title contained in the added header will be extracted from the
230 "data-title" attribute.
231
232 Except for the three cases noted above, Fossil makes no changes or
233 additions to the CGI-generated content. Fossil just passes the verbatim
234 content back up the stack towards the requester.
235
236 <h2>5.0 Filename Restrictions</h2>
237
238 For security reasons, Fossil places restrictions on the names of files
239 in the extroot directory that can participate in the extension CGI
240 mechanism:
241
242 1. Filenames must consist of only ASCII alphanumeric characters,
243 ".", "_", and "-", and of course "/" as the file separator.
244 Files with names that includes spaces or
245 other punctuation or special characters are ignored.
246
247 2. No element of the pathname can begin with "." or "-". Files or
248 directories whose names begin with "." or "-" are ignored.
249
250 If a CGI program requires separate data files, it is safe to put those
251 files in the same directory as the CGI program itself as long as the names
252 of the data files contain special characters that cause them to be ignored
253 by Fossil.
254
255 <h2>6.0 Trouble-Shooting Hints</h2>
256
257 Remember that the /ext will return any file in the extroot directory
258 hierarchy as static content if the file is readable but not executable.
259 When initially setting up the /ext mechanism, it is sometimes helpful
260 to verify that you are able to receive static content prior to working
261 on getting your CGIs working. Also remember that CGIs must be
262 executable files.
263
264 Fossil likes to run inside a chroot jail, and will automatically put
265 itself inside a chroot jail if it can. The sub-CGI program will also
266 run inside this same chroot jail. Make sure all embedded pathnames
267 have been adjusted accordingly and that all resources needed by the
268 CGI program are available within the chroot jail.
269
270 If anything goes wrong while trying to process an /ext page, Fossil
271 returns a 404 Not Found error with no details. However, if the requester
272 is logged in as a user that has Debug privilege (capability letter "D")
273 then additional diagnostic information may be included in the output.
274
275 If the /ext page has a "fossil-ext-debug=1" query parameter and if
276 the requester is logged in as a user with Debug privilege, then the
277 CGI output is returned verbatim, as text/plain and with the original
278 header intact. This is useful for trying diagnosing problems with the
279 CGI script.
280
--- www/serverext.wiki
+++ www/serverext.wiki
@@ -1,33 +1,31 @@
1 <title>CGI Server Extensions</title>
2
3 If you choose to have a [./server.wiki|central server] for your Fossil-based
4 project (which is entirely optional - Fossil can be use an a pure peer-to-peer
5 mode) then you can also add CGI extensions to the Fossil websiteite d. These
6 extensions work like any other CGI program, except that they also have access
7 to the Fossil login information, so that they can restrict access based on
8 the currently logged in user. The CGI output can be a stand-alone webpage,
9 or it can be incorporated into the Fossil site using the standard Fossil
10 header and footer.
11
12 An example of where this is useful is the
13 [checklist application](https://sqlite.org/src/ext/checklist) on
14 the [SQLite](https://sqlite.org/) project. The checklist
15 helps the SQLite developers track which release tests have passed,
16 or failed, or are still to be done. The checklist used to be a
17 stand-alone CGI which kept its own private user database and implemented
18 its on permissions and login system. By converting checklist into
19 a Fossil extension, the same login that works for the
20 [main SQLite source repository](https://sqlite.org/src) also works
21 for the checklist. And permission to change elements of the checklist
22 is based on permission to check-in to the main source repository.
23
24 <h2>How It Works</h2>
25
26 Extensions are off by default.
 
 
27 An administrator activates the CGI extension mechanism by specifying
28 an "Extension Root Directory" or "extroot" as part of the server setup.
29 If the Fossil server is itself run as CGI, then add a line to the CGI
30 script file that says:
31
@@ -37,12 +35,12 @@
35
36 Or, if the Fossil server is begin run as using the "fossil server" or
37 "fossil ui" or "fossil http" commands, then add an extra
38 "--extroot <i>DIRECTORY</i>" option to that command.
39
40 The <i>DIRECTORY</i> thus specified becomes the DOCUMENT_ROOT for the
41 CGI. Files in the DOCUMENT_ROOT are accessed via URLs like this:
42
43 <blockquote>
44 https://example-project.org/ext/<i>FILENAME</i>
45 </blockquote>
46
@@ -49,231 +47,5 @@
47 In other words, access files in DOCUMENT_ROOT by appending the filename
48 relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext]
49 page of the Fossil server.
50 Files that are readable but not executable are returned as static
51 content. Files that are executable are run as CGI.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
52

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button