Fossil SCM
Assorted minor improvements to the www/alerts.md document. The major one is re-emphasizing the need to give capability 7 to some user or user category. Ask me how I came to think this necessary. :)
Commit
3e75a683efb801f73c3d14cbd3cdac7b478ed867bf416a578e34707dc50a1018
Parent
c3d9c8e082d2bd3…
1 file changed
+34
-18
+34
-18
| --- www/alerts.md | ||
| +++ www/alerts.md | ||
| @@ -1,10 +1,10 @@ | ||
| 1 | 1 | Email Alerts |
| 2 | 2 | ============ |
| 3 | 3 | |
| 4 | 4 | The email alert system is a work-in-progress. |
| 5 | -This documentation was last updated on 2018-08-08. | |
| 5 | +This documentation was last updated on 2018-08-12. | |
| 6 | 6 | Check back later for updates. |
| 7 | 7 | |
| 8 | 8 | Email Alerts And Notifications |
| 9 | 9 | ------------------------------ |
| 10 | 10 | |
| @@ -17,37 +17,39 @@ | ||
| 17 | 17 | * Changes to any ticket |
| 18 | 18 | * Changes to any wiki page |
| 19 | 19 | * New forum posts |
| 20 | 20 | * Announcements |
| 21 | 21 | |
| 22 | -Subscribers can elect to receive emails as soon as these events happen, | |
| 23 | -or to receive a daily digest of the events. | |
| 22 | +Subscribers can either elect to receive emails as soon as these events happen, | |
| 23 | +or they can receive a daily digest of the events instead. | |
| 24 | 24 | |
| 25 | 25 | Email alerts are sent by a [Fossil server](./server.wiki). You must |
| 26 | -have a server setup to make use of email alerts. Email alerts do not | |
| 27 | -(currently) work if you are only using Fossil from the command-line. | |
| 26 | +have a server [set up to make use of email alerts](#setup). Email | |
| 27 | +alerts do not currently work if you are only using Fossil from the | |
| 28 | +command line. | |
| 28 | 29 | |
| 29 | 30 | Users and Subscribers |
| 30 | 31 | --------------------- |
| 31 | 32 | |
| 32 | 33 | Fossil makes a distinction between "users" and "subscribers". A |
| 33 | -"user" is someone with a username and password - someone who can | |
| 34 | -log in. A "subscriber" is someone who receives email alerts. Users | |
| 34 | +user is someone with a username and password — someone who can | |
| 35 | +log in. A subscriber is someone who receives email alerts. Users | |
| 35 | 36 | can also be subscribers and subscribers can be users, but that does |
| 36 | 37 | not have to be the case. It is possible to be a user without being |
| 37 | 38 | a subscriber and to be a subscriber without being a user. |
| 38 | 39 | |
| 39 | 40 | In the repository database file, users are tracked with the USER table |
| 40 | 41 | and subscribers are tracked via the SUBSCRIBER table. |
| 41 | 42 | |
| 43 | +<a id="setup"></a> | |
| 42 | 44 | Activating Email Alerts |
| 43 | 45 | ----------------------- |
| 44 | 46 | |
| 45 | 47 | Email alerts are turned off by default. To activate them, log into |
| 46 | 48 | the Fossil server as an administrator and visit the |
| 47 | 49 | [Admin/Notification](/setup_notification) |
| 48 | -setup page ([/setup_notification](/setup_notification)). | |
| 50 | +setup page. ([`/setup_notification`](/setup_notification)) | |
| 49 | 51 | |
| 50 | 52 | Important: Email alerts are configured using Admin/Notification, not |
| 51 | 53 | Admin/Email-Server. The Email-Server setup screen is used to configure |
| 52 | 54 | a different subsystem within Fossil. |
| 53 | 55 | |
| @@ -58,11 +60,11 @@ | ||
| 58 | 60 | will appear in the "Subject:" line of outgoing emails. But the key |
| 59 | 61 | setup parameter is the "Email Send Method". |
| 60 | 62 | |
| 61 | 63 | Fossil supports multiple methods for sending email alerts: |
| 62 | 64 | |
| 63 | - 1. Pipe the email message text into a command, such as "sendmail". | |
| 65 | + 1. Pipe the email message text into a command, such as `sendmail`. | |
| 64 | 66 | 2. Store email messages as individual files in a directory and let |
| 65 | 67 | some other process set up by the administrator take care of |
| 66 | 68 | reading and forwarding those files. |
| 67 | 69 | 3. Store email messages as entries in an SQLite database where |
| 68 | 70 | some external process and read and forward the emails. |
| @@ -81,36 +83,50 @@ | ||
| 81 | 83 | it is running inside of a restrictive chroot jail which is unable to |
| 82 | 84 | hand off messages to "procmail" directly. The daemon that monitors the |
| 83 | 85 | email database is a [short TCL script](/file/tools/email-sender.tcl). |
| 84 | 86 | That daemon is started automatically by adding this line: |
| 85 | 87 | |
| 86 | -> /usr/bin/tclsh /home/www/fossil/email-sender.tcl & | |
| 88 | + /usr/bin/tclsh /home/www/fossil/email-sender.tcl & | |
| 87 | 89 | |
| 88 | -To the "/etc/rc.local" file of the Ubuntu server that hosts the | |
| 90 | +To the `/etc/rc.local` file of the Ubuntu server that hosts the | |
| 89 | 91 | repository. |
| 90 | 92 | |
| 91 | 93 | After making necessary changes to the Admin/Notification page, test |
| 92 | 94 | those changes by clicking the "[Send Announcement](/announce)" link |
| 93 | 95 | at the top of the page. Fill in your email address in the "To:" |
| 94 | 96 | line and a test message below, and press "Send Message" to verify that |
| 95 | 97 | outgoing email is working. |
| 96 | 98 | |
| 99 | +<a id="cap7"></a> | |
| 97 | 100 | Once email notification is working, one must also adjust user permissions |
| 98 | 101 | to allow users to subscribe to email notification. On the |
| 99 | 102 | Setup/User page, under the permissions for each user, is a new capability |
| 100 | 103 | called "Email Alerts". The corresponding capability letter is "7". |
| 101 | 104 | That new "7" capability must be enabled in order for |
| 102 | 105 | users to be able to become subscribers. To allow anonymous passers-by |
| 103 | 106 | on the internet to subscribe, simply enable "Email Alerts" for the |
| 104 | -special "nobody" user. | |
| 107 | +"nobody" user category. To require that the user solve a simple CAPTCHA | |
| 108 | +first, add it to the "anonymous" user category instead. | |
| 105 | 109 | |
| 106 | 110 | Signing Up For Email Notification |
| 107 | 111 | --------------------------------- |
| 108 | 112 | |
| 109 | 113 | Users and/or anonymous passers-by can visit the |
| 110 | -[/subscribe](/subscribe) page to sign | |
| 111 | -up for email notification. After signing up, a single verification email | |
| 114 | +[`/subscribe`](/subscribe) page to sign | |
| 115 | +up for email notification. | |
| 116 | + | |
| 117 | +If your users are getting the following complaint from Fossil: | |
| 118 | + | |
| 119 | +<blockquote> | |
| 120 | + Use a different login with greater privilege than FOO to access | |
| 121 | + /subscribe | |
| 122 | +</blockquote> | |
| 123 | + | |
| 124 | +...then you forgot to [give capability 7](#cap7) to that user or to a | |
| 125 | +user category that the user is a member of. | |
| 126 | + | |
| 127 | +After signing up, a single verification email | |
| 112 | 128 | is sent. The new subscriber must click a link on that email in order to |
| 113 | 129 | activate the subscription. |
| 114 | 130 | |
| 115 | 131 | Subscription verification emails are only sent once. This is a defense |
| 116 | 132 | against malicious robots that try to harass innocent internet users |
| @@ -118,11 +134,11 @@ | ||
| 118 | 134 | If the initial subscription verification does not go through correctly, |
| 119 | 135 | an administrator must intervene to reset the subscription. |
| 120 | 136 | |
| 121 | 137 | Every subscriber has a long random hexadecimal security code that serves |
| 122 | 138 | as their password. All email notifications contain a link back to the |
| 123 | -Fossil server, incorporating this security code, that allows the | |
| 139 | +Fossil server, incorporating this security code, which allows the | |
| 124 | 140 | subscriber to adjust their subscription options. |
| 125 | 141 | |
| 126 | 142 | Administrator Activities |
| 127 | 143 | ------------------------ |
| 128 | 144 | |
| @@ -145,8 +161,8 @@ | ||
| 145 | 161 | In a network of peer repositories, you only want one repository sending |
| 146 | 162 | email notifications. If you were to replicate the email notification |
| 147 | 163 | settings to a separate repository, then subscribers would get multiple |
| 148 | 164 | notifications for each event, which would be bad. |
| 149 | 165 | |
| 150 | -However, the subscriber list can be synced for backup purposes. | |
| 151 | -Use the "[fossil config pull subscriber](/help?cmd=configuration)" command | |
| 152 | -to pull the latest subscriber list from a server into a backup repository. | |
| 166 | +However, the subscriber list can be synced for backup purposes. Use the | |
| 167 | +[`fossil config pull subscriber`](/help?cmd=configuration) command to | |
| 168 | +pull the latest subscriber list from a server into a backup repository. | |
| 153 | 169 |
| --- www/alerts.md | |
| +++ www/alerts.md | |
| @@ -1,10 +1,10 @@ | |
| 1 | Email Alerts |
| 2 | ============ |
| 3 | |
| 4 | The email alert system is a work-in-progress. |
| 5 | This documentation was last updated on 2018-08-08. |
| 6 | Check back later for updates. |
| 7 | |
| 8 | Email Alerts And Notifications |
| 9 | ------------------------------ |
| 10 | |
| @@ -17,37 +17,39 @@ | |
| 17 | * Changes to any ticket |
| 18 | * Changes to any wiki page |
| 19 | * New forum posts |
| 20 | * Announcements |
| 21 | |
| 22 | Subscribers can elect to receive emails as soon as these events happen, |
| 23 | or to receive a daily digest of the events. |
| 24 | |
| 25 | Email alerts are sent by a [Fossil server](./server.wiki). You must |
| 26 | have a server setup to make use of email alerts. Email alerts do not |
| 27 | (currently) work if you are only using Fossil from the command-line. |
| 28 | |
| 29 | Users and Subscribers |
| 30 | --------------------- |
| 31 | |
| 32 | Fossil makes a distinction between "users" and "subscribers". A |
| 33 | "user" is someone with a username and password - someone who can |
| 34 | log in. A "subscriber" is someone who receives email alerts. Users |
| 35 | can also be subscribers and subscribers can be users, but that does |
| 36 | not have to be the case. It is possible to be a user without being |
| 37 | a subscriber and to be a subscriber without being a user. |
| 38 | |
| 39 | In the repository database file, users are tracked with the USER table |
| 40 | and subscribers are tracked via the SUBSCRIBER table. |
| 41 | |
| 42 | Activating Email Alerts |
| 43 | ----------------------- |
| 44 | |
| 45 | Email alerts are turned off by default. To activate them, log into |
| 46 | the Fossil server as an administrator and visit the |
| 47 | [Admin/Notification](/setup_notification) |
| 48 | setup page ([/setup_notification](/setup_notification)). |
| 49 | |
| 50 | Important: Email alerts are configured using Admin/Notification, not |
| 51 | Admin/Email-Server. The Email-Server setup screen is used to configure |
| 52 | a different subsystem within Fossil. |
| 53 | |
| @@ -58,11 +60,11 @@ | |
| 58 | will appear in the "Subject:" line of outgoing emails. But the key |
| 59 | setup parameter is the "Email Send Method". |
| 60 | |
| 61 | Fossil supports multiple methods for sending email alerts: |
| 62 | |
| 63 | 1. Pipe the email message text into a command, such as "sendmail". |
| 64 | 2. Store email messages as individual files in a directory and let |
| 65 | some other process set up by the administrator take care of |
| 66 | reading and forwarding those files. |
| 67 | 3. Store email messages as entries in an SQLite database where |
| 68 | some external process and read and forward the emails. |
| @@ -81,36 +83,50 @@ | |
| 81 | it is running inside of a restrictive chroot jail which is unable to |
| 82 | hand off messages to "procmail" directly. The daemon that monitors the |
| 83 | email database is a [short TCL script](/file/tools/email-sender.tcl). |
| 84 | That daemon is started automatically by adding this line: |
| 85 | |
| 86 | > /usr/bin/tclsh /home/www/fossil/email-sender.tcl & |
| 87 | |
| 88 | To the "/etc/rc.local" file of the Ubuntu server that hosts the |
| 89 | repository. |
| 90 | |
| 91 | After making necessary changes to the Admin/Notification page, test |
| 92 | those changes by clicking the "[Send Announcement](/announce)" link |
| 93 | at the top of the page. Fill in your email address in the "To:" |
| 94 | line and a test message below, and press "Send Message" to verify that |
| 95 | outgoing email is working. |
| 96 | |
| 97 | Once email notification is working, one must also adjust user permissions |
| 98 | to allow users to subscribe to email notification. On the |
| 99 | Setup/User page, under the permissions for each user, is a new capability |
| 100 | called "Email Alerts". The corresponding capability letter is "7". |
| 101 | That new "7" capability must be enabled in order for |
| 102 | users to be able to become subscribers. To allow anonymous passers-by |
| 103 | on the internet to subscribe, simply enable "Email Alerts" for the |
| 104 | special "nobody" user. |
| 105 | |
| 106 | Signing Up For Email Notification |
| 107 | --------------------------------- |
| 108 | |
| 109 | Users and/or anonymous passers-by can visit the |
| 110 | [/subscribe](/subscribe) page to sign |
| 111 | up for email notification. After signing up, a single verification email |
| 112 | is sent. The new subscriber must click a link on that email in order to |
| 113 | activate the subscription. |
| 114 | |
| 115 | Subscription verification emails are only sent once. This is a defense |
| 116 | against malicious robots that try to harass innocent internet users |
| @@ -118,11 +134,11 @@ | |
| 118 | If the initial subscription verification does not go through correctly, |
| 119 | an administrator must intervene to reset the subscription. |
| 120 | |
| 121 | Every subscriber has a long random hexadecimal security code that serves |
| 122 | as their password. All email notifications contain a link back to the |
| 123 | Fossil server, incorporating this security code, that allows the |
| 124 | subscriber to adjust their subscription options. |
| 125 | |
| 126 | Administrator Activities |
| 127 | ------------------------ |
| 128 | |
| @@ -145,8 +161,8 @@ | |
| 145 | In a network of peer repositories, you only want one repository sending |
| 146 | email notifications. If you were to replicate the email notification |
| 147 | settings to a separate repository, then subscribers would get multiple |
| 148 | notifications for each event, which would be bad. |
| 149 | |
| 150 | However, the subscriber list can be synced for backup purposes. |
| 151 | Use the "[fossil config pull subscriber](/help?cmd=configuration)" command |
| 152 | to pull the latest subscriber list from a server into a backup repository. |
| 153 |
| --- www/alerts.md | |
| +++ www/alerts.md | |
| @@ -1,10 +1,10 @@ | |
| 1 | Email Alerts |
| 2 | ============ |
| 3 | |
| 4 | The email alert system is a work-in-progress. |
| 5 | This documentation was last updated on 2018-08-12. |
| 6 | Check back later for updates. |
| 7 | |
| 8 | Email Alerts And Notifications |
| 9 | ------------------------------ |
| 10 | |
| @@ -17,37 +17,39 @@ | |
| 17 | * Changes to any ticket |
| 18 | * Changes to any wiki page |
| 19 | * New forum posts |
| 20 | * Announcements |
| 21 | |
| 22 | Subscribers can either elect to receive emails as soon as these events happen, |
| 23 | or they can receive a daily digest of the events instead. |
| 24 | |
| 25 | Email alerts are sent by a [Fossil server](./server.wiki). You must |
| 26 | have a server [set up to make use of email alerts](#setup). Email |
| 27 | alerts do not currently work if you are only using Fossil from the |
| 28 | command line. |
| 29 | |
| 30 | Users and Subscribers |
| 31 | --------------------- |
| 32 | |
| 33 | Fossil makes a distinction between "users" and "subscribers". A |
| 34 | user is someone with a username and password — someone who can |
| 35 | log in. A subscriber is someone who receives email alerts. Users |
| 36 | can also be subscribers and subscribers can be users, but that does |
| 37 | not have to be the case. It is possible to be a user without being |
| 38 | a subscriber and to be a subscriber without being a user. |
| 39 | |
| 40 | In the repository database file, users are tracked with the USER table |
| 41 | and subscribers are tracked via the SUBSCRIBER table. |
| 42 | |
| 43 | <a id="setup"></a> |
| 44 | Activating Email Alerts |
| 45 | ----------------------- |
| 46 | |
| 47 | Email alerts are turned off by default. To activate them, log into |
| 48 | the Fossil server as an administrator and visit the |
| 49 | [Admin/Notification](/setup_notification) |
| 50 | setup page. ([`/setup_notification`](/setup_notification)) |
| 51 | |
| 52 | Important: Email alerts are configured using Admin/Notification, not |
| 53 | Admin/Email-Server. The Email-Server setup screen is used to configure |
| 54 | a different subsystem within Fossil. |
| 55 | |
| @@ -58,11 +60,11 @@ | |
| 60 | will appear in the "Subject:" line of outgoing emails. But the key |
| 61 | setup parameter is the "Email Send Method". |
| 62 | |
| 63 | Fossil supports multiple methods for sending email alerts: |
| 64 | |
| 65 | 1. Pipe the email message text into a command, such as `sendmail`. |
| 66 | 2. Store email messages as individual files in a directory and let |
| 67 | some other process set up by the administrator take care of |
| 68 | reading and forwarding those files. |
| 69 | 3. Store email messages as entries in an SQLite database where |
| 70 | some external process and read and forward the emails. |
| @@ -81,36 +83,50 @@ | |
| 83 | it is running inside of a restrictive chroot jail which is unable to |
| 84 | hand off messages to "procmail" directly. The daemon that monitors the |
| 85 | email database is a [short TCL script](/file/tools/email-sender.tcl). |
| 86 | That daemon is started automatically by adding this line: |
| 87 | |
| 88 | /usr/bin/tclsh /home/www/fossil/email-sender.tcl & |
| 89 | |
| 90 | To the `/etc/rc.local` file of the Ubuntu server that hosts the |
| 91 | repository. |
| 92 | |
| 93 | After making necessary changes to the Admin/Notification page, test |
| 94 | those changes by clicking the "[Send Announcement](/announce)" link |
| 95 | at the top of the page. Fill in your email address in the "To:" |
| 96 | line and a test message below, and press "Send Message" to verify that |
| 97 | outgoing email is working. |
| 98 | |
| 99 | <a id="cap7"></a> |
| 100 | Once email notification is working, one must also adjust user permissions |
| 101 | to allow users to subscribe to email notification. On the |
| 102 | Setup/User page, under the permissions for each user, is a new capability |
| 103 | called "Email Alerts". The corresponding capability letter is "7". |
| 104 | That new "7" capability must be enabled in order for |
| 105 | users to be able to become subscribers. To allow anonymous passers-by |
| 106 | on the internet to subscribe, simply enable "Email Alerts" for the |
| 107 | "nobody" user category. To require that the user solve a simple CAPTCHA |
| 108 | first, add it to the "anonymous" user category instead. |
| 109 | |
| 110 | Signing Up For Email Notification |
| 111 | --------------------------------- |
| 112 | |
| 113 | Users and/or anonymous passers-by can visit the |
| 114 | [`/subscribe`](/subscribe) page to sign |
| 115 | up for email notification. |
| 116 | |
| 117 | If your users are getting the following complaint from Fossil: |
| 118 | |
| 119 | <blockquote> |
| 120 | Use a different login with greater privilege than FOO to access |
| 121 | /subscribe |
| 122 | </blockquote> |
| 123 | |
| 124 | ...then you forgot to [give capability 7](#cap7) to that user or to a |
| 125 | user category that the user is a member of. |
| 126 | |
| 127 | After signing up, a single verification email |
| 128 | is sent. The new subscriber must click a link on that email in order to |
| 129 | activate the subscription. |
| 130 | |
| 131 | Subscription verification emails are only sent once. This is a defense |
| 132 | against malicious robots that try to harass innocent internet users |
| @@ -118,11 +134,11 @@ | |
| 134 | If the initial subscription verification does not go through correctly, |
| 135 | an administrator must intervene to reset the subscription. |
| 136 | |
| 137 | Every subscriber has a long random hexadecimal security code that serves |
| 138 | as their password. All email notifications contain a link back to the |
| 139 | Fossil server, incorporating this security code, which allows the |
| 140 | subscriber to adjust their subscription options. |
| 141 | |
| 142 | Administrator Activities |
| 143 | ------------------------ |
| 144 | |
| @@ -145,8 +161,8 @@ | |
| 161 | In a network of peer repositories, you only want one repository sending |
| 162 | email notifications. If you were to replicate the email notification |
| 163 | settings to a separate repository, then subscribers would get multiple |
| 164 | notifications for each event, which would be bad. |
| 165 | |
| 166 | However, the subscriber list can be synced for backup purposes. Use the |
| 167 | [`fossil config pull subscriber`](/help?cmd=configuration) command to |
| 168 | pull the latest subscriber list from a server into a backup repository. |
| 169 |