Fossil SCM
More documentation updates.
Commit
52095820d8d629da3ccdd0ede23649075271ea995b86ddd300af6f69acd4a157
Parent
482bd93cf97f652…
2 files changed
+4
-8
+14
-11
+4
-8
| --- www/alerts.md | ||
| +++ www/alerts.md | ||
| @@ -34,15 +34,10 @@ | ||
| 34 | 34 | on the Fossil server that will be sending these email alerts, logged |
| 35 | 35 | in as a user with [**Admin** capability](./caps/ref.html#a). It is not possible to work on a |
| 36 | 36 | clone of the server's repository and push the configuration changes up |
| 37 | 37 | to that repo as an Admin user, [on purpose](#backup). |
| 38 | 38 | |
| 39 | -**Important:** Do not confuse that screen with Admin → Email-Server, | |
| 40 | -which sets up a different subsystem within Fossil. That feature is | |
| 41 | -related to this document's topic, but it is currently incomplete, so we | |
| 42 | -do not cover it at this time. | |
| 43 | - | |
| 44 | 39 | <a id="cd"></a> |
| 45 | 40 | You will also need a CLI window open with its working directory changed |
| 46 | 41 | to a checkout directory of the Fossil repository you are setting up to |
| 47 | 42 | send email. If you don't `cd` to such a checkout directory first, |
| 48 | 43 | you'll need to add `-R /path/to/repo.fossil` to each `fossil` command |
| @@ -55,13 +50,14 @@ | ||
| 55 | 50 | |
| 56 | 51 | |
| 57 | 52 | <a id="quick"></a> |
| 58 | 53 | ## Quick Email Service Setup |
| 59 | 54 | |
| 60 | -If you've already got a working Postfix, Exim, or Sendmail server on the | |
| 61 | -machine running your Fossil instance(s), and you aren't using Fossil's | |
| 62 | -`chroot` feature to wall Fossil off from the rest of the machine, it's | |
| 55 | +If you've already got a working OpenSMTPD, Postfix, Exim, Sendmail, | |
| 56 | +or similar server on the machine running your Fossil instance(s), | |
| 57 | +and you aren't using Fossil's [chroot jail feature](./chroot.md) | |
| 58 | +to wall Fossil off from the rest of the machine, it's | |
| 63 | 59 | fairly simple to set up email alerts. |
| 64 | 60 | |
| 65 | 61 | (Otherwise, skip [ahead](#advanced) to the sections on advanced email |
| 66 | 62 | service setup.) |
| 67 | 63 | |
| 68 | 64 |
| --- www/alerts.md | |
| +++ www/alerts.md | |
| @@ -34,15 +34,10 @@ | |
| 34 | on the Fossil server that will be sending these email alerts, logged |
| 35 | in as a user with [**Admin** capability](./caps/ref.html#a). It is not possible to work on a |
| 36 | clone of the server's repository and push the configuration changes up |
| 37 | to that repo as an Admin user, [on purpose](#backup). |
| 38 | |
| 39 | **Important:** Do not confuse that screen with Admin → Email-Server, |
| 40 | which sets up a different subsystem within Fossil. That feature is |
| 41 | related to this document's topic, but it is currently incomplete, so we |
| 42 | do not cover it at this time. |
| 43 | |
| 44 | <a id="cd"></a> |
| 45 | You will also need a CLI window open with its working directory changed |
| 46 | to a checkout directory of the Fossil repository you are setting up to |
| 47 | send email. If you don't `cd` to such a checkout directory first, |
| 48 | you'll need to add `-R /path/to/repo.fossil` to each `fossil` command |
| @@ -55,13 +50,14 @@ | |
| 55 | |
| 56 | |
| 57 | <a id="quick"></a> |
| 58 | ## Quick Email Service Setup |
| 59 | |
| 60 | If you've already got a working Postfix, Exim, or Sendmail server on the |
| 61 | machine running your Fossil instance(s), and you aren't using Fossil's |
| 62 | `chroot` feature to wall Fossil off from the rest of the machine, it's |
| 63 | fairly simple to set up email alerts. |
| 64 | |
| 65 | (Otherwise, skip [ahead](#advanced) to the sections on advanced email |
| 66 | service setup.) |
| 67 | |
| 68 |
| --- www/alerts.md | |
| +++ www/alerts.md | |
| @@ -34,15 +34,10 @@ | |
| 34 | on the Fossil server that will be sending these email alerts, logged |
| 35 | in as a user with [**Admin** capability](./caps/ref.html#a). It is not possible to work on a |
| 36 | clone of the server's repository and push the configuration changes up |
| 37 | to that repo as an Admin user, [on purpose](#backup). |
| 38 | |
| 39 | <a id="cd"></a> |
| 40 | You will also need a CLI window open with its working directory changed |
| 41 | to a checkout directory of the Fossil repository you are setting up to |
| 42 | send email. If you don't `cd` to such a checkout directory first, |
| 43 | you'll need to add `-R /path/to/repo.fossil` to each `fossil` command |
| @@ -55,13 +50,14 @@ | |
| 50 | |
| 51 | |
| 52 | <a id="quick"></a> |
| 53 | ## Quick Email Service Setup |
| 54 | |
| 55 | If you've already got a working OpenSMTPD, Postfix, Exim, Sendmail, |
| 56 | or similar server on the machine running your Fossil instance(s), |
| 57 | and you aren't using Fossil's [chroot jail feature](./chroot.md) |
| 58 | to wall Fossil off from the rest of the machine, it's |
| 59 | fairly simple to set up email alerts. |
| 60 | |
| 61 | (Otherwise, skip [ahead](#advanced) to the sections on advanced email |
| 62 | service setup.) |
| 63 | |
| 64 |
+14
-11
| --- www/chroot.md | ||
| +++ www/chroot.md | ||
| @@ -1,21 +1,21 @@ | ||
| 1 | 1 | # The Server Chroot Jail |
| 2 | 2 | |
| 3 | 3 | If you run Fossil as root in any mode that [serves data on the |
| 4 | 4 | network][srv], and you're running it on Unix or a compatible OS, Fossil |
| 5 | 5 | will drop itself into a [`chroot(2)` jail][cj] shortly after starting |
| 6 | -up, once it's done everything that requires root access. Most commonly, | |
| 7 | -you run Fossil as root to allow it to bind to TCP port 80 for HTTP | |
| 8 | -service, since normal users are restricted to ports 1024 and up on OSes | |
| 9 | -where this behavior occurs. | |
| 6 | +up. The usual reason for launching Fossil | |
| 7 | +as root to allow it to bind to TCP port 80 for HTTP | |
| 8 | +service, since normal users are restricted to ports 1024 and higher. | |
| 10 | 9 | |
| 11 | 10 | Fossil uses the owner of the Fossil repository file as its new user |
| 12 | -ID when dropping root privileges. | |
| 11 | +ID when it drops root privileges. | |
| 13 | 12 | |
| 14 | -When this happens, Fossil needs to have all of its dependencies inside | |
| 15 | -the chroot jail in order to continue work. There are several things you | |
| 16 | -typically need in order to make things work properly: | |
| 13 | +When Fossil enters a chroot jail, it needs to have all of its dependencies | |
| 14 | +inside the chroot jail in order to continue work. There are several | |
| 15 | +resources that need to be inside the chroot jail with Fossil in order for | |
| 16 | +Fossil to work correctly: | |
| 17 | 17 | |
| 18 | 18 | * the repository file(s) |
| 19 | 19 | |
| 20 | 20 | * `/dev/null` — create it with `mknod(8)` inside the jail directory |
| 21 | 21 | ([Linux example][mnl], [OpenBSD example][obsd]) |
| @@ -27,16 +27,19 @@ | ||
| 27 | 27 | shedding feature][fls] |
| 28 | 28 | |
| 29 | 29 | * any shared libraries your `fossil` binary is linked to, unless you |
| 30 | 30 | [configured Fossil with `--static`][bld] to avoid it |
| 31 | 31 | |
| 32 | -Fossil does all of this in order to protect the host OS. You can make it | |
| 33 | -bypass the jail part of this by passing <tt>--nojail</tt> to <tt>fossil server</tt>, | |
| 34 | -but you cannot make it skip the dropping of root privileges, on purpose. | |
| 32 | +Fossil does all of this as one of many layers of defense against | |
| 33 | +hacks and exploits. You can prevent Fossil from entering the chroot | |
| 34 | +jail using the <tt>--nojail</tt> option to the | |
| 35 | +[fossil server command](/help?cmd=server) | |
| 36 | +but you cannot make Fossil hold onto root privileges. Fossil always drops | |
| 37 | +root privilege before accepting inputs, for security. | |
| 35 | 38 | |
| 36 | 39 | |
| 37 | 40 | [bld]: https://fossil-scm.org/home/doc/trunk/www/build.wiki |
| 38 | 41 | [cj]: https://en.wikipedia.org/wiki/Chroot |
| 39 | 42 | [fls]: ./loadmgmt.md |
| 40 | 43 | [mnl]: https://fossil-scm.org/forum/forumpost/90caff30cb |
| 41 | 44 | [srv]: ./server/ |
| 42 | 45 | [obsd]: ./server/openbsd/fastcgi.md#chroot |
| 43 | 46 |
| --- www/chroot.md | |
| +++ www/chroot.md | |
| @@ -1,21 +1,21 @@ | |
| 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] shortly after starting |
| 6 | up, once it's done everything that requires root access. Most commonly, |
| 7 | you run Fossil as root to allow it to bind to TCP port 80 for HTTP |
| 8 | service, since normal users are restricted to ports 1024 and up on OSes |
| 9 | where this behavior occurs. |
| 10 | |
| 11 | Fossil uses the owner of the Fossil repository file as its new user |
| 12 | ID when dropping root privileges. |
| 13 | |
| 14 | When this happens, Fossil needs to have all of its dependencies inside |
| 15 | the chroot jail in order to continue work. There are several things you |
| 16 | typically need in order to make things work properly: |
| 17 | |
| 18 | * the repository file(s) |
| 19 | |
| 20 | * `/dev/null` — create it with `mknod(8)` inside the jail directory |
| 21 | ([Linux example][mnl], [OpenBSD example][obsd]) |
| @@ -27,16 +27,19 @@ | |
| 27 | shedding feature][fls] |
| 28 | |
| 29 | * any shared libraries your `fossil` binary is linked to, unless you |
| 30 | [configured Fossil with `--static`][bld] to avoid it |
| 31 | |
| 32 | Fossil does all of this in order to protect the host OS. You can make it |
| 33 | bypass the jail part of this by passing <tt>--nojail</tt> to <tt>fossil server</tt>, |
| 34 | but you cannot make it skip the dropping of root privileges, on purpose. |
| 35 | |
| 36 | |
| 37 | [bld]: https://fossil-scm.org/home/doc/trunk/www/build.wiki |
| 38 | [cj]: https://en.wikipedia.org/wiki/Chroot |
| 39 | [fls]: ./loadmgmt.md |
| 40 | [mnl]: https://fossil-scm.org/forum/forumpost/90caff30cb |
| 41 | [srv]: ./server/ |
| 42 | [obsd]: ./server/openbsd/fastcgi.md#chroot |
| 43 |
| --- www/chroot.md | |
| +++ www/chroot.md | |
| @@ -1,21 +1,21 @@ | |
| 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] shortly after starting |
| 6 | up. The usual reason for launching Fossil |
| 7 | as root to allow it to bind to TCP port 80 for HTTP |
| 8 | service, since normal users are restricted to ports 1024 and higher. |
| 9 | |
| 10 | Fossil uses the owner of the Fossil repository file as its new user |
| 11 | ID when it drops root privileges. |
| 12 | |
| 13 | When Fossil enters a chroot jail, it needs to have all of its dependencies |
| 14 | inside the chroot jail in order to continue work. There are several |
| 15 | resources that need to be inside the chroot jail with Fossil in order for |
| 16 | Fossil to work correctly: |
| 17 | |
| 18 | * the repository file(s) |
| 19 | |
| 20 | * `/dev/null` — create it with `mknod(8)` inside the jail directory |
| 21 | ([Linux example][mnl], [OpenBSD example][obsd]) |
| @@ -27,16 +27,19 @@ | |
| 27 | shedding feature][fls] |
| 28 | |
| 29 | * any shared libraries your `fossil` binary is linked to, unless you |
| 30 | [configured Fossil with `--static`][bld] to avoid it |
| 31 | |
| 32 | Fossil does all of this as one of many layers of defense against |
| 33 | hacks and exploits. You can prevent Fossil from entering the chroot |
| 34 | jail using the <tt>--nojail</tt> option to the |
| 35 | [fossil server command](/help?cmd=server) |
| 36 | but you cannot make Fossil hold onto root privileges. Fossil always drops |
| 37 | root privilege before accepting inputs, for security. |
| 38 | |
| 39 | |
| 40 | [bld]: https://fossil-scm.org/home/doc/trunk/www/build.wiki |
| 41 | [cj]: https://en.wikipedia.org/wiki/Chroot |
| 42 | [fls]: ./loadmgmt.md |
| 43 | [mnl]: https://fossil-scm.org/forum/forumpost/90caff30cb |
| 44 | [srv]: ./server/ |
| 45 | [obsd]: ./server/openbsd/fastcgi.md#chroot |
| 46 |