Fossil SCM
Enhancements to the CGI extension documentation. Update the 2.10 change log to mention this enhancement and other changes.
Commit
dfa5d50971c757a027917495de12e49a329efb3311770f6e50e6203ce000ddb2
Parent
12c8cc709d3376b…
2 files changed
+6
+29
-13
+6
| --- www/changes.wiki | ||
| +++ www/changes.wiki | ||
| @@ -1,11 +1,17 @@ | ||
| 1 | 1 | <title>Change Log</title> |
| 2 | 2 | |
| 3 | 3 | <a name='v2_10'></a> |
| 4 | 4 | <h2>Changes for Version 2.10 (pending)</h2> |
| 5 | 5 | |
| 6 | + * Added support for [./serverext.wiki|CGI-based Server Extensions]. | |
| 7 | + * Enhance the hierarchical display of Forum threads to do less | |
| 8 | + indentation and to provide links back to the previous message | |
| 9 | + in the thread. Provide sequential numbers for all messages in | |
| 10 | + a forum thread. | |
| 6 | 11 | * Change the default [./hashpolicy.wiki|hash policy] to SHA3. |
| 12 | + * Documentation improvements | |
| 7 | 13 | |
| 8 | 14 | <a name='v2_9'></a> |
| 9 | 15 | <h2>Changes for Version 2.9 (2019-07-13)</h2> |
| 10 | 16 | |
| 11 | 17 | * Added the [/help?cmd=git|fossil git export] command and instructions |
| 12 | 18 |
| --- www/changes.wiki | |
| +++ www/changes.wiki | |
| @@ -1,11 +1,17 @@ | |
| 1 | <title>Change Log</title> |
| 2 | |
| 3 | <a name='v2_10'></a> |
| 4 | <h2>Changes for Version 2.10 (pending)</h2> |
| 5 | |
| 6 | * Change the default [./hashpolicy.wiki|hash policy] to SHA3. |
| 7 | |
| 8 | <a name='v2_9'></a> |
| 9 | <h2>Changes for Version 2.9 (2019-07-13)</h2> |
| 10 | |
| 11 | * Added the [/help?cmd=git|fossil git export] command and instructions |
| 12 |
| --- www/changes.wiki | |
| +++ www/changes.wiki | |
| @@ -1,11 +1,17 @@ | |
| 1 | <title>Change Log</title> |
| 2 | |
| 3 | <a name='v2_10'></a> |
| 4 | <h2>Changes for Version 2.10 (pending)</h2> |
| 5 | |
| 6 | * Added support for [./serverext.wiki|CGI-based Server Extensions]. |
| 7 | * Enhance the hierarchical display of Forum threads to do less |
| 8 | indentation and to provide links back to the previous message |
| 9 | in the thread. Provide sequential numbers for all messages in |
| 10 | a forum thread. |
| 11 | * Change the default [./hashpolicy.wiki|hash policy] to SHA3. |
| 12 | * Documentation improvements |
| 13 | |
| 14 | <a name='v2_9'></a> |
| 15 | <h2>Changes for Version 2.9 (2019-07-13)</h2> |
| 16 | |
| 17 | * Added the [/help?cmd=git|fossil git export] command and instructions |
| 18 |
+29
-13
| --- www/serverext.wiki | ||
| +++ www/serverext.wiki | ||
| @@ -15,19 +15,19 @@ | ||
| 15 | 15 | [https://sqlite.org/src/ext/checklist|checklist application] on |
| 16 | 16 | the [https://sqlite.org/|SQLite] project. The checklist |
| 17 | 17 | helps the SQLite developers track which release tests have passed, |
| 18 | 18 | or failed, or are still to be done. The checklist program began as a |
| 19 | 19 | stand-alone CGI which kept its own private user database and implemented |
| 20 | -its on permissions and login system. By converting checklist into | |
| 20 | +its own permissions and login system. By converting checklist into | |
| 21 | 21 | a Fossil extension, the same login that works for the |
| 22 | 22 | [https://sqlite.org/src|main SQLite source repository] also works |
| 23 | 23 | for the checklist. And permission to change elements of the checklist |
| 24 | 24 | is based on permission to check-in to the main source repository. |
| 25 | 25 | |
| 26 | 26 | <h2>2.0 How It Works</h2> |
| 27 | 27 | |
| 28 | -Extensions are disabled by default. | |
| 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 CGI, then add a line to the CGI |
| 32 | 32 | script file that says: |
| 33 | 33 | |
| @@ -78,13 +78,15 @@ | ||
| 78 | 78 | Then it takes the leftover "/checklist" part and appends it to the |
| 79 | 79 | "extroot" to get the filename "/sqlite-src-ext/checklist". Fossil finds |
| 80 | 80 | that file to be executable, so it runs it as CGI and returns the result. |
| 81 | 81 | |
| 82 | 82 | The /sqlite-src-ext/checklist file is a |
| 83 | -[https://wapp.tcl.tk|Wapp program]. The complete source code to the | |
| 83 | +[https://wapp.tcl.tk|Wapp program]. The current source code to the | |
| 84 | 84 | this program can be seen at |
| 85 | -[https://www.sqlite.org/src/ext/checklist/self]. | |
| 85 | +[https://www.sqlite.org/src/ext/checklist/self] and | |
| 86 | +historical versions are available at | |
| 87 | +[https://sqlite.org/docsrc/finfo/misc/checklist.tcl]. | |
| 86 | 88 | |
| 87 | 89 | There is a cascade of CGIs happening here. The webserver that receives |
| 88 | 90 | the initial HTTP request runs Fossil as a CGI based on the |
| 89 | 91 | "https://sqlite.org/src" portion of the URL. The Fossil instance then |
| 90 | 92 | runs the checklist sub-CGI based on the "/ext/checklists" suffix. The |
| @@ -144,11 +146,22 @@ | ||
| 144 | 146 | * SCRIPT_NAME |
| 145 | 147 | * SERVER_NAME |
| 146 | 148 | * SERVER_PORT |
| 147 | 149 | * SERVER_PROTOCOL |
| 148 | 150 | |
| 149 | -In addition, Fossil adds the following environment variables: | |
| 151 | +Do a web search for | |
| 152 | +"[https://duckduckgo.com/?q=cgi+environment_variables|cgi environment variables]" | |
| 153 | +to find more detail about what each of the above variables mean and how | |
| 154 | +they are used. | |
| 155 | +Live listings of the values of some or all of these environment variables | |
| 156 | +can be found at links like these: | |
| 157 | + | |
| 158 | + * [https://fossil-scm.org/home/test_env] | |
| 159 | + * [https://sqlite.org/src/ext/checklist/env] | |
| 160 | + | |
| 161 | +In addition to the standard CGI environment variables listed above, | |
| 162 | +Fossil adds the following: | |
| 150 | 163 | |
| 151 | 164 | * FOSSIL_CAPABILITIES |
| 152 | 165 | * FOSSIL_REPOSITORY |
| 153 | 166 | * FOSSIL_USER |
| 154 | 167 | |
| @@ -158,16 +171,19 @@ | ||
| 158 | 171 | [/setup_ulist_notes|Fossil capability letters] that |
| 159 | 172 | indicate what permissions the user has on the Fossil repository. |
| 160 | 173 | The FOSSIL_REPOSITORY environment variable gives the filename of the |
| 161 | 174 | Fossil repository that is running. |
| 162 | 175 | |
| 163 | -The [https://sqlite.org/ext/checklist|checklist application] uses the | |
| 176 | +The [https://sqlite.org/src/ext/checklist|checklist application] uses the | |
| 164 | 177 | FOSSIL_USER environment variable to determine the name of the user and |
| 165 | 178 | the FOSSIL_CAPABILITIES variable to determine if the user is allowed to |
| 166 | 179 | mark off changes to the checklist. Only users with check-in permission |
| 167 | 180 | to the Fossil repository are allowed to mark off checklist items. That |
| 168 | 181 | means that the FOSSIL_CAPABILITIES string must contain the letter "i". |
| 182 | +Search for "FOSSIL_CAPABILITIES" in the | |
| 183 | +[https://sqlite.org/src/ext/checklist/self|source listing] to see how | |
| 184 | +this happens. | |
| 169 | 185 | |
| 170 | 186 | If the HTTP request includes content (for example if this is a POST request) |
| 171 | 187 | then the CONTENT_LENGTH value will be positive and the data for the content |
| 172 | 188 | will be readable on standard input. |
| 173 | 189 | |
| @@ -192,14 +208,15 @@ | ||
| 192 | 208 | Those that Fossil does not understand are simply relayed back to up the |
| 193 | 209 | line to the requester. |
| 194 | 210 | |
| 195 | 211 | Fossil takes special action with some content types. If the Content-Type |
| 196 | 212 | is "application/x-fossil-wiki" or "application/x-markdown" then Fossil |
| 197 | -converts the content from Fossil-wiki or Markdown into HTML, adding its | |
| 198 | -own header and footer text according to the repository skin. If the | |
| 199 | -content-type is "text/html", that is normally passed straight through | |
| 200 | -unchanged. However, if the HTML content is of the form: | |
| 213 | +converts the content from [/wiki_rules|Fossil-Wiki] or | |
| 214 | +[/md_rules|Markdown] into HTML, adding its | |
| 215 | +own header and footer text according to the repository skin. Content | |
| 216 | +of type "text/html" is normally passed straight through | |
| 217 | +unchanged. However, if the text/html content is of the form: | |
| 201 | 218 | |
| 202 | 219 | <blockquote><verbatim> |
| 203 | 220 | <div class='fossil-doc' data-title='DOCUMENT TITLE'> |
| 204 | 221 | ... HTML content there ... |
| 205 | 222 | </div> |
| @@ -210,11 +227,11 @@ | ||
| 210 | 227 | then Fossil will adds its own header and footer to the HTML. The |
| 211 | 228 | page title contained in the added header will be extracted from the |
| 212 | 229 | "data-title" attribute. |
| 213 | 230 | |
| 214 | 231 | Except for the three cases noted above, Fossil makes no changes or |
| 215 | -additions to the CGI-generated content, but simply passes the verbatim | |
| 232 | +additions to the CGI-generated content. Fossil just passes the verbatim | |
| 216 | 233 | content back up the stack towards the requester. |
| 217 | 234 | |
| 218 | 235 | <h2>5.0 Filename Restrictions</h2> |
| 219 | 236 | |
| 220 | 237 | For security reasons, Fossil places restrictions on the names of files |
| @@ -230,12 +247,11 @@ | ||
| 230 | 247 | directories whose names begin with "." or "-" are ignored. |
| 231 | 248 | |
| 232 | 249 | If a CGI program requires separate data files, it is safe to put those |
| 233 | 250 | files in the same directory as the CGI program itself as long as the names |
| 234 | 251 | of the data files contain special characters that cause them to be ignored |
| 235 | -by Fossil. For example, ensure that all datafile begin with "-" or | |
| 236 | -end with ",data" or "~data". | |
| 252 | +by Fossil. | |
| 237 | 253 | |
| 238 | 254 | <h2>6.0 Trouble-Shooting Hints</h2> |
| 239 | 255 | |
| 240 | 256 | Remember that the /ext will return any file in the extroot directory |
| 241 | 257 | hierarchy as static content if the file is readable but not executable. |
| 242 | 258 |
| --- www/serverext.wiki | |
| +++ www/serverext.wiki | |
| @@ -15,19 +15,19 @@ | |
| 15 | [https://sqlite.org/src/ext/checklist|checklist application] on |
| 16 | the [https://sqlite.org/|SQLite] project. The checklist |
| 17 | helps the SQLite developers track which release tests have passed, |
| 18 | or failed, or are still to be done. The checklist program began as a |
| 19 | stand-alone CGI which kept its own private user database and implemented |
| 20 | its on permissions and login system. By converting checklist into |
| 21 | a Fossil extension, the same login that works for the |
| 22 | [https://sqlite.org/src|main SQLite source repository] also works |
| 23 | for the checklist. And permission to change elements of the checklist |
| 24 | is based on permission to check-in to the main source repository. |
| 25 | |
| 26 | <h2>2.0 How It Works</h2> |
| 27 | |
| 28 | 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 | |
| @@ -78,13 +78,15 @@ | |
| 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 complete source code to the |
| 84 | this program can be seen at |
| 85 | [https://www.sqlite.org/src/ext/checklist/self]. |
| 86 | |
| 87 | There is a cascade of CGIs happening here. The webserver that receives |
| 88 | the initial HTTP request runs Fossil as a CGI based on the |
| 89 | "https://sqlite.org/src" portion of the URL. The Fossil instance then |
| 90 | runs the checklist sub-CGI based on the "/ext/checklists" suffix. The |
| @@ -144,11 +146,22 @@ | |
| 144 | * SCRIPT_NAME |
| 145 | * SERVER_NAME |
| 146 | * SERVER_PORT |
| 147 | * SERVER_PROTOCOL |
| 148 | |
| 149 | In addition, Fossil adds the following environment variables: |
| 150 | |
| 151 | * FOSSIL_CAPABILITIES |
| 152 | * FOSSIL_REPOSITORY |
| 153 | * FOSSIL_USER |
| 154 | |
| @@ -158,16 +171,19 @@ | |
| 158 | [/setup_ulist_notes|Fossil capability letters] that |
| 159 | indicate what permissions the user has on the Fossil repository. |
| 160 | The FOSSIL_REPOSITORY environment variable gives the filename of the |
| 161 | Fossil repository that is running. |
| 162 | |
| 163 | The [https://sqlite.org/ext/checklist|checklist application] uses the |
| 164 | FOSSIL_USER environment variable to determine the name of the user and |
| 165 | the FOSSIL_CAPABILITIES variable to determine if the user is allowed to |
| 166 | mark off changes to the checklist. Only users with check-in permission |
| 167 | to the Fossil repository are allowed to mark off checklist items. That |
| 168 | means that the FOSSIL_CAPABILITIES string must contain the letter "i". |
| 169 | |
| 170 | If the HTTP request includes content (for example if this is a POST request) |
| 171 | then the CONTENT_LENGTH value will be positive and the data for the content |
| 172 | will be readable on standard input. |
| 173 | |
| @@ -192,14 +208,15 @@ | |
| 192 | Those that Fossil does not understand are simply relayed back to up the |
| 193 | line to the requester. |
| 194 | |
| 195 | Fossil takes special action with some content types. If the Content-Type |
| 196 | is "application/x-fossil-wiki" or "application/x-markdown" then Fossil |
| 197 | converts the content from Fossil-wiki or Markdown into HTML, adding its |
| 198 | own header and footer text according to the repository skin. If the |
| 199 | content-type is "text/html", that is normally passed straight through |
| 200 | unchanged. However, if the HTML content is of the form: |
| 201 | |
| 202 | <blockquote><verbatim> |
| 203 | <div class='fossil-doc' data-title='DOCUMENT TITLE'> |
| 204 | ... HTML content there ... |
| 205 | </div> |
| @@ -210,11 +227,11 @@ | |
| 210 | then Fossil will adds its own header and footer to the HTML. The |
| 211 | page title contained in the added header will be extracted from the |
| 212 | "data-title" attribute. |
| 213 | |
| 214 | Except for the three cases noted above, Fossil makes no changes or |
| 215 | additions to the CGI-generated content, but simply passes the verbatim |
| 216 | content back up the stack towards the requester. |
| 217 | |
| 218 | <h2>5.0 Filename Restrictions</h2> |
| 219 | |
| 220 | For security reasons, Fossil places restrictions on the names of files |
| @@ -230,12 +247,11 @@ | |
| 230 | directories whose names begin with "." or "-" are ignored. |
| 231 | |
| 232 | If a CGI program requires separate data files, it is safe to put those |
| 233 | files in the same directory as the CGI program itself as long as the names |
| 234 | of the data files contain special characters that cause them to be ignored |
| 235 | by Fossil. For example, ensure that all datafile begin with "-" or |
| 236 | end with ",data" or "~data". |
| 237 | |
| 238 | <h2>6.0 Trouble-Shooting Hints</h2> |
| 239 | |
| 240 | Remember that the /ext will return any file in the extroot directory |
| 241 | hierarchy as static content if the file is readable but not executable. |
| 242 |
| --- www/serverext.wiki | |
| +++ www/serverext.wiki | |
| @@ -15,19 +15,19 @@ | |
| 15 | [https://sqlite.org/src/ext/checklist|checklist application] on |
| 16 | the [https://sqlite.org/|SQLite] project. The checklist |
| 17 | helps the SQLite developers track which release tests have passed, |
| 18 | or failed, or are still to be done. The checklist program began as a |
| 19 | stand-alone CGI which kept its own private user database and implemented |
| 20 | its own permissions and login system. By converting checklist into |
| 21 | a Fossil extension, the same login that works for the |
| 22 | [https://sqlite.org/src|main SQLite source repository] also works |
| 23 | for the checklist. And permission to change elements of the checklist |
| 24 | is based on permission to check-in to the main source repository. |
| 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 | |
| @@ -78,13 +78,15 @@ | |
| 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 | historical versions are available at |
| 87 | [https://sqlite.org/docsrc/finfo/misc/checklist.tcl]. |
| 88 | |
| 89 | There is a cascade of CGIs happening here. The webserver that receives |
| 90 | the initial HTTP request runs Fossil as a CGI based on the |
| 91 | "https://sqlite.org/src" portion of the URL. The Fossil instance then |
| 92 | runs the checklist sub-CGI based on the "/ext/checklists" suffix. The |
| @@ -144,11 +146,22 @@ | |
| 146 | * SCRIPT_NAME |
| 147 | * SERVER_NAME |
| 148 | * SERVER_PORT |
| 149 | * SERVER_PROTOCOL |
| 150 | |
| 151 | Do a web search for |
| 152 | "[https://duckduckgo.com/?q=cgi+environment_variables|cgi environment variables]" |
| 153 | to find more detail about what each of the above variables mean and how |
| 154 | they are used. |
| 155 | Live listings of the values of some or all of these environment variables |
| 156 | can be found at links like these: |
| 157 | |
| 158 | * [https://fossil-scm.org/home/test_env] |
| 159 | * [https://sqlite.org/src/ext/checklist/env] |
| 160 | |
| 161 | In addition to the standard CGI environment variables listed above, |
| 162 | Fossil adds the following: |
| 163 | |
| 164 | * FOSSIL_CAPABILITIES |
| 165 | * FOSSIL_REPOSITORY |
| 166 | * FOSSIL_USER |
| 167 | |
| @@ -158,16 +171,19 @@ | |
| 171 | [/setup_ulist_notes|Fossil capability letters] that |
| 172 | indicate what permissions the user has on the Fossil repository. |
| 173 | The FOSSIL_REPOSITORY environment variable gives the filename of the |
| 174 | Fossil repository that is running. |
| 175 | |
| 176 | The [https://sqlite.org/src/ext/checklist|checklist application] uses the |
| 177 | FOSSIL_USER environment variable to determine the name of the user and |
| 178 | the FOSSIL_CAPABILITIES variable to determine if the user is allowed to |
| 179 | mark off changes to the checklist. Only users with check-in permission |
| 180 | to the Fossil repository are allowed to mark off checklist items. That |
| 181 | means that the FOSSIL_CAPABILITIES string must contain the letter "i". |
| 182 | Search for "FOSSIL_CAPABILITIES" in the |
| 183 | [https://sqlite.org/src/ext/checklist/self|source listing] to see how |
| 184 | this happens. |
| 185 | |
| 186 | If the HTTP request includes content (for example if this is a POST request) |
| 187 | then the CONTENT_LENGTH value will be positive and the data for the content |
| 188 | will be readable on standard input. |
| 189 | |
| @@ -192,14 +208,15 @@ | |
| 208 | Those that Fossil does not understand are simply relayed back to up the |
| 209 | line to the requester. |
| 210 | |
| 211 | Fossil takes special action with some content types. If the Content-Type |
| 212 | is "application/x-fossil-wiki" or "application/x-markdown" then Fossil |
| 213 | converts the content from [/wiki_rules|Fossil-Wiki] or |
| 214 | [/md_rules|Markdown] into HTML, adding its |
| 215 | own header and footer text according to the repository skin. Content |
| 216 | of type "text/html" is normally passed straight through |
| 217 | unchanged. However, if the text/html content is of the form: |
| 218 | |
| 219 | <blockquote><verbatim> |
| 220 | <div class='fossil-doc' data-title='DOCUMENT TITLE'> |
| 221 | ... HTML content there ... |
| 222 | </div> |
| @@ -210,11 +227,11 @@ | |
| 227 | then Fossil will adds its own header and footer to the HTML. The |
| 228 | page title contained in the added header will be extracted from the |
| 229 | "data-title" attribute. |
| 230 | |
| 231 | Except for the three cases noted above, Fossil makes no changes or |
| 232 | additions to the CGI-generated content. Fossil just passes the verbatim |
| 233 | content back up the stack towards the requester. |
| 234 | |
| 235 | <h2>5.0 Filename Restrictions</h2> |
| 236 | |
| 237 | For security reasons, Fossil places restrictions on the names of files |
| @@ -230,12 +247,11 @@ | |
| 247 | directories whose names begin with "." or "-" are ignored. |
| 248 | |
| 249 | If a CGI program requires separate data files, it is safe to put those |
| 250 | files in the same directory as the CGI program itself as long as the names |
| 251 | of the data files contain special characters that cause them to be ignored |
| 252 | by Fossil. |
| 253 | |
| 254 | <h2>6.0 Trouble-Shooting Hints</h2> |
| 255 | |
| 256 | Remember that the /ext will return any file in the extroot directory |
| 257 | hierarchy as static content if the file is readable but not executable. |
| 258 |