|
1
|
# Email Alerts |
|
2
|
|
|
3
|
## Overview |
|
4
|
|
|
5
|
Beginning with version 2.7, Fossil can send email messages to |
|
6
|
subscribers to alert them to changes in the repository: |
|
7
|
|
|
8
|
* New [checkins](/help/ci) |
|
9
|
* [Ticket](./tickets.wiki) changes |
|
10
|
* [Wiki](./wikitheory.wiki) page changes |
|
11
|
* New and edited [forum](./forum.wiki) posts |
|
12
|
* Users receiving [new permissions](./caps/index.md) (admins only) |
|
13
|
* Announcements |
|
14
|
|
|
15
|
Subscribers can elect to receive emails as soon as these events happen, |
|
16
|
or they can receive a daily digest of the events instead. |
|
17
|
|
|
18
|
Email alerts are sent by a [Fossil server](./server/), which must be |
|
19
|
[set up](#quick) by the Fossil administrator to send email. |
|
20
|
|
|
21
|
Email alerts do not currently work if you are only using Fossil from the |
|
22
|
command line. |
|
23
|
|
|
24
|
A bit of terminology: Fossil uses the terms "email alerts" and |
|
25
|
"notifications" interchangeably. We stick to the former term in this |
|
26
|
document except when referring to parts of the Fossil UI still using the |
|
27
|
latter term. |
|
28
|
|
|
29
|
|
|
30
|
## Setup Prerequisites |
|
31
|
|
|
32
|
Much of this document describes how to set up Fossil's email alert |
|
33
|
system. To follow this guide, you will need a Fossil UI browser window |
|
34
|
open to the [Admin → Notification](/setup_notification) Fossil UI screen |
|
35
|
on the Fossil server that will be sending these email alerts, logged |
|
36
|
in as a user with [**Admin** capability](./caps/ref.html#a). It is not possible to work on a |
|
37
|
clone of the server's repository and push the configuration changes up |
|
38
|
to that repo as an Admin user, [on purpose](#backup). |
|
39
|
|
|
40
|
<a id="cd"></a> |
|
41
|
You will also need a CLI window open with its working directory changed |
|
42
|
to a checkout directory of the Fossil repository you are setting up to |
|
43
|
send email. If you don't `cd` to such a checkout directory first, |
|
44
|
you'll need to add `-R /path/to/repo.fossil` to each `fossil` command |
|
45
|
below to tell Fossil which repository you mean it to apply the command |
|
46
|
to. |
|
47
|
|
|
48
|
There are other prerequisites for email service, but since they vary |
|
49
|
depending on the configuration you choose, we'll cover these inline |
|
50
|
below. |
|
51
|
|
|
52
|
|
|
53
|
<a id="quick"></a> |
|
54
|
## Quick Email Service Setup |
|
55
|
|
|
56
|
If you've already got a working OpenSMTPD, Postfix, Exim, Sendmail, |
|
57
|
or similar server on the machine running your Fossil instance(s), |
|
58
|
and you aren't using Fossil's [chroot jail feature](./chroot.md) |
|
59
|
to wall Fossil off from the rest of the machine, it's |
|
60
|
fairly simple to set up email alerts. |
|
61
|
|
|
62
|
(Otherwise, skip [ahead](#advanced) to the sections on advanced email |
|
63
|
service setup.) |
|
64
|
|
|
65
|
This is our "quick setup" option even though setting up an SMTP mail |
|
66
|
server is not trivial, because there are many other reasons to have such |
|
67
|
a server set up already: internal project email service, `cron` |
|
68
|
notifications, server status monitoring notifications... |
|
69
|
|
|
70
|
With that out of the way, the Fossil-specific steps are easy: |
|
71
|
|
|
72
|
1. Go to [Admin → Notification](/setup_notification) and fill out all |
|
73
|
of the **Required** fields: |
|
74
|
|
|
75
|
* **Canonical server URL** — Use the suggested URL |
|
76
|
|
|
77
|
* **"From" email address** — `[email protected]` is |
|
78
|
traditional, but suit yourself |
|
79
|
|
|
80
|
* **Repository nickname** — See the suggested examples on the web page. |
|
81
|
|
|
82
|
2. Set "Email Send Method" to "Pipe to a command" |
|
83
|
|
|
84
|
3. Set the "Administrator email address" to a suitable valid email |
|
85
|
address on that machine. It could be the same value you used for |
|
86
|
the "From" address above, or it could be a different value like |
|
87
|
`[email protected]`. |
|
88
|
|
|
89
|
Save your changes. |
|
90
|
|
|
91
|
At the command line, say |
|
92
|
|
|
93
|
$ fossil set email-send-command |
|
94
|
|
|
95
|
If that gives a blank value instead of `sendmail -ti`, say |
|
96
|
|
|
97
|
$ fossil set email-send-command "sendmail -ti" |
|
98
|
|
|
99
|
to force the setting. That works around a [known |
|
100
|
bug](https://fossil-scm.org/forum/forumpost/840b676410) which may be |
|
101
|
squished by the time you read this. |
|
102
|
|
|
103
|
If you're running Postfix or Exim, you might think that command is |
|
104
|
wrong, since you aren't running Sendmail. These mail servers provide a |
|
105
|
`sendmail` command for compatibility with software like Fossil that has |
|
106
|
no good reason to care exactly which SMTP server implementation is |
|
107
|
running at a given site. There may be other SMTP servers that also |
|
108
|
provide a compatible `sendmail` command, in which case they may work |
|
109
|
with Fossil using the same steps as above. |
|
110
|
|
|
111
|
<a id="status"></a> |
|
112
|
If you reload the Admin → Notification page, the Status section at the |
|
113
|
top should show: |
|
114
|
|
|
115
|
Outgoing Email: Piped to command "sendmail -ti" |
|
116
|
Pending Alerts: 0 normal, 0 digest |
|
117
|
Subscribers: 0 active, 0 total |
|
118
|
|
|
119
|
Before you move on to the next section, you might like to read up on |
|
120
|
[some subtleties](#pipe) with the "pipe to a command" method that we did |
|
121
|
not cover above. |
|
122
|
|
|
123
|
|
|
124
|
<a id="usage"></a> |
|
125
|
## Usage and Testing |
|
126
|
|
|
127
|
Now that email service from Fossil is set up, you can test it and begin |
|
128
|
using it. |
|
129
|
|
|
130
|
|
|
131
|
<a id="sub" name="subscribe"></a> |
|
132
|
### Subscribing to Alerts |
|
133
|
|
|
134
|
In the Status output above, we saw that there are no subscribers, so the |
|
135
|
next step is to add the first one. |
|
136
|
|
|
137
|
Go to the `/subscribe` page on your Fossil instance to sign up for email |
|
138
|
alerts. At the very least, you will need to sign up for "Forum Posts" |
|
139
|
and "Announcements" to complete the testing steps below. |
|
140
|
|
|
141
|
If you're logged in with a Fossil repository user account and put the |
|
142
|
same user name and email address into this forum as you used for your |
|
143
|
user information under Admin → Users, Fossil will simply tie your alert |
|
144
|
preferences to your login record, and the email address in your user's |
|
145
|
Contact Info field will be considered already-verified. Otherwise, |
|
146
|
Fossil will create an alert-only record, and you will have to verify the |
|
147
|
email address before Fossil will send alerts to it. |
|
148
|
|
|
149
|
This shows a key aspect of the way Fossil's email alerts system works, |
|
150
|
by the way: a user can be signed up for email alerts without having a |
|
151
|
full-fledged Fossil user account. Only when both user names are the same |
|
152
|
are the two records tied together under the hood. For more on this, see |
|
153
|
[Users vs Subscribers below](#uvs). |
|
154
|
|
|
155
|
If you are seeing the following complaint from Fossil: |
|
156
|
|
|
157
|
> Use a different login with greater privilege than FOO to access /subscribe |
|
158
|
|
|
159
|
...then the repository's administrator forgot to give the |
|
160
|
[**EmailAlert** capability][cap7] |
|
161
|
to that user or to a user category that the user is a member of. |
|
162
|
|
|
163
|
After a subscriber signs up for alerts for the first time, a single |
|
164
|
verification email is sent to that subscriber's given email address. |
|
165
|
The new subscriber must click a link in that email in order to activate |
|
166
|
the subscription. |
|
167
|
|
|
168
|
Subscription verification emails are only sent once. This is a defense |
|
169
|
against malicious robots that try to harass innocent Internet users by |
|
170
|
having subscription pages send multiple verification emails. If the |
|
171
|
initial subscription verification does not go through correctly, an |
|
172
|
administrator must [intervene](#admin) to reset the subscription. |
|
173
|
|
|
174
|
Every subscriber-only email address has a [long random hexadecimal |
|
175
|
security code](#scode) that serves in place of a password. All email |
|
176
|
alerts contain a link in their footer back to the Fossil server, |
|
177
|
incorporating this security code, which allows the subscriber to adjust |
|
178
|
their subscription options. If a user doesn't have any of those emails, |
|
179
|
they can request a link via email by visiting the `/alerts` or |
|
180
|
`/unsubscribe` page on the repository. |
|
181
|
|
|
182
|
Those with Fossil repository logins can adjust their email alert |
|
183
|
settings by visiting the `/alerts` page on the repository. With the |
|
184
|
default skin, you can get there by clicking the "Logout" link in the |
|
185
|
upper right corner of any Fossil UI page then clicking the "Email |
|
186
|
Alerts" link. That link is also available via the Sitemap (`/sitemap`) |
|
187
|
and via the default skin's hamburger menu (☰). |
|
188
|
|
|
189
|
[cap7]: ./caps/ref.html#7 |
|
190
|
|
|
191
|
|
|
192
|
<a id="unsub" name="unsubscribe"></a> |
|
193
|
### Unsubscribing |
|
194
|
|
|
195
|
To unsubscribe from alerts, visit the `/alerts` page on the repository, |
|
196
|
click the "Unsubscribe" button, then check the "Unsubscribe" checkbox to |
|
197
|
verify your action and press the "Unsubscribe" button a second time. |
|
198
|
|
|
199
|
This interlock is intended to prevent accidental unsubscription. |
|
200
|
|
|
201
|
|
|
202
|
<a id="test"></a> |
|
203
|
### Test Email Service |
|
204
|
|
|
205
|
The easiest way to test email sending from Fossil is via the "[Send |
|
206
|
Announcement](/announce)" link at the top of the "Email Notification |
|
207
|
Setup" page. Put your email address in the "To:" line and a test |
|
208
|
message below, then press "Send Message" to verify that outgoing email |
|
209
|
is working. |
|
210
|
|
|
211
|
Another method is from the command line: |
|
212
|
|
|
213
|
$ fossil alerts test-message [email protected] --body README.md --subject Test |
|
214
|
|
|
215
|
That should send you an email with "Test" in the subject line and the |
|
216
|
contents of your project's `README.md` file in the body. |
|
217
|
|
|
218
|
That command assumes that your project contains a "readme" file, but of |
|
219
|
course it does, because you have followed the [Programming Style Guide |
|
220
|
Checklist][cl], right? Right. |
|
221
|
|
|
222
|
[cl]: https://sendgrid.com/blog/programming-style-guide-checklist/ |
|
223
|
|
|
224
|
|
|
225
|
<a id="cap7" name="ucap"></a> |
|
226
|
### User Capabilities |
|
227
|
|
|
228
|
Once email alerts are working, you may need to [adjust the default user |
|
229
|
capabilities](./caps/) to give "[Email Alerts][cap7]" capability to any |
|
230
|
[user category](./caps/#ucat) or [individual user](./caps/#ucap) that |
|
231
|
needs to use the subscription setup pages, `/subscribe` and `/alerts`. |
|
232
|
[**Admin**][capa] and [**Setup**][caps] users always have this |
|
233
|
capability. |
|
234
|
|
|
235
|
To allow any passer-by on the Internet to subscribe, give the "Email |
|
236
|
Alerts" capability to the "nobody" user category. To require that a |
|
237
|
person solve a simple CAPTCHA first, give that capability to the |
|
238
|
"anonymous" user category instead. |
|
239
|
|
|
240
|
[capa]: ./caps/ref.html#a |
|
241
|
[caps]: ./caps/ref.html#s |
|
242
|
|
|
243
|
|
|
244
|
<a id="first" name="frist"></a> |
|
245
|
### First Post |
|
246
|
|
|
247
|
I suggest taking the time to compose a suitable introductory message |
|
248
|
especially for your project's forum, one which a new user would find |
|
249
|
helpful. |
|
250
|
|
|
251
|
Wait a few seconds, and you should receive an email alert with the |
|
252
|
post's subject and body text in the email. |
|
253
|
|
|
254
|
|
|
255
|
<a id="trouble"></a> |
|
256
|
### Troubleshooting |
|
257
|
|
|
258
|
If email alerts aren't working, there are several useful commands you |
|
259
|
can give to figure out why. |
|
260
|
|
|
261
|
(Be sure to [`cd` into a repo checkout directory](#cd) first!) |
|
262
|
|
|
263
|
$ fossil alerts status |
|
264
|
|
|
265
|
This should give much the same information as you saw [above](#status). |
|
266
|
One difference is that, since you've created a forum post, the |
|
267
|
`pending-alerts` value should only be zero if you did in fact get the |
|
268
|
requested email alert. If it's zero, check your mailer's spam folder. If |
|
269
|
it's nonzero, continue with these troubleshooting steps. |
|
270
|
|
|
271
|
$ fossil backoffice |
|
272
|
|
|
273
|
That forces Fossil to run its ["back office" process](./backoffice.md). |
|
274
|
Its only purpose at the time of this writing is to push out alert |
|
275
|
emails, but it might do other things later. Sometimes it can get stuck |
|
276
|
and needs to be kicked. For that reason, you might want to set up a |
|
277
|
crontab entry to make sure it runs occasionally. |
|
278
|
|
|
279
|
$ fossil alerts send |
|
280
|
|
|
281
|
This should also kick off the backoffice processing, if there are any |
|
282
|
pending alerts to send out. |
|
283
|
|
|
284
|
$ fossil alert pending |
|
285
|
|
|
286
|
Show any pending alerts. The number of lines output here should equal |
|
287
|
the [status output above](#status). |
|
288
|
|
|
289
|
$ fossil test-add-alerts f5900 |
|
290
|
$ fossil alert send |
|
291
|
|
|
292
|
Manually create an email alert and push it out immediately. |
|
293
|
|
|
294
|
The `f` in the first command's final parameter means you're scheduling a |
|
295
|
"forum" alert. The integer is the ID of a forum post, which you can find |
|
296
|
by visiting `/timeline?showid` on your Fossil instance. |
|
297
|
|
|
298
|
The second command above is necessary because the `test-add-alerts` |
|
299
|
command doesn't kick off a backoffice run. |
|
300
|
|
|
301
|
$ fossil ale send |
|
302
|
|
|
303
|
This only does the same thing as the final command above, rather than |
|
304
|
send you an ale, as you might be hoping. Sorry. |
|
305
|
|
|
306
|
|
|
307
|
<a id="advanced"></a> |
|
308
|
## Advanced Email Setups |
|
309
|
|
|
310
|
Fossil offers several methods of sending email: |
|
311
|
|
|
312
|
1. Pipe the email message text into a command. |
|
313
|
2. Store email messages as entries in an SQLite database. |
|
314
|
3. Store email messages as individual files in a directory. |
|
315
|
4. Send emails to an SMTP relay. |
|
316
|
5. Send emails directly to the recipients via SMTP. |
|
317
|
|
|
318
|
This wide range of options allows Fossil to talk to pretty much any |
|
319
|
SMTP setup. |
|
320
|
|
|
321
|
The first four options let Fossil delegate email handling to an existing |
|
322
|
[MTA] so that Fossil does not need to implement the [roughly two |
|
323
|
dozen][mprotos] separate [RFCs][rfcs] required in order to properly |
|
324
|
support SMTP email in this complex world we've built. As well, this |
|
325
|
design choice means you do not need to do duplicate configuration, such |
|
326
|
as to point Fossil at your server's TLS certificate in order to support |
|
327
|
users behind mail servers that require STARTTLS encryption. |
|
328
|
|
|
329
|
[mprotos]: http://sqlite.1065341.n5.nabble.com/Many-ML-emails-going-to-GMail-s-SPAM-tp98685p98722.html |
|
330
|
[rfcs]: https://en.wikipedia.org/wiki/Request_for_Comments |
|
331
|
|
|
332
|
|
|
333
|
<a id="pipe"></a> |
|
334
|
### Method 1: Pipe to a Command |
|
335
|
|
|
336
|
This is our ["quick setup" option](#quick) above, but there are some |
|
337
|
details we ignored which we'll cover now. |
|
338
|
|
|
339
|
Fossil pipes the email message in [RFC 822 format][rfc822] to the |
|
340
|
standard input of the command you gave as the "Email Send Method", |
|
341
|
defaulting to `sendmail -ti`. This constitutes a protocol between Fossil |
|
342
|
and the SMTP [message transfer agent (MTA)][MTA]. Any other MTA which |
|
343
|
speaks the same protocol can be used in place of the most common |
|
344
|
options: Sendmail, Exim, and Postfix. |
|
345
|
|
|
346
|
The `-t` option tells the command to expect the list of email recipients |
|
347
|
in a `To` header in the RFC 822 message presented on its standard input. |
|
348
|
Without this option, the `sendmail` command expects to receive the |
|
349
|
recipient list on the command line, but that's not possible with the |
|
350
|
current design of this email sending method. Therefore, if you're |
|
351
|
attempting to use a less common MTA which cannot parse the recipient |
|
352
|
list from the `To` header in the email message, you might need to look |
|
353
|
for a different MTA. |
|
354
|
|
|
355
|
The `-i` option is only needed for MTAs that take a dot/period at the |
|
356
|
beginning of a line of standard input text as "end of message." Fossil |
|
357
|
doesn't attempt to escape such dots, so if the line wrapping happens to |
|
358
|
occur such that a dot or period in an alert message is at the beginning |
|
359
|
of a line, you'll get a truncated email message without this option. |
|
360
|
Statistically, this will happen about once every 70 or so messages, so |
|
361
|
it is important to give this option if your MTA treats leading dots on a |
|
362
|
line this way. |
|
363
|
|
|
364
|
<a id="msmtp"></a> |
|
365
|
The [`msmtp`][msmtp] SMTP client is compatible with this |
|
366
|
protocol if you give it the `-t` option. It’s a useful option on a server |
|
367
|
hosting a Fossil repository which doesn't otherwise require a separate |
|
368
|
SMTP server for other purposes, such as because you’ve got a separate |
|
369
|
provider for your email and merely need a way to let Fossil feed |
|
370
|
messages into it. |
|
371
|
|
|
372
|
It is probably also possible to configure [`procmail`][pmdoc] to work |
|
373
|
with this protocol. If you know how to do it, a patch to this document |
|
374
|
or a how-to on [the Fossil forum][ff] would be appreciated. |
|
375
|
|
|
376
|
[ff]: https://fossil-scm.org/forum/ |
|
377
|
[msmtp]: https://marlam.de/msmtp/ |
|
378
|
[MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent |
|
379
|
[pmdoc]: http://pm-doc.sourceforge.net/doc/ |
|
380
|
[rfc822]: https://www.w3.org/Protocols/rfc822/ |
|
381
|
|
|
382
|
|
|
383
|
<a id="db"></a> |
|
384
|
### Method 2: Store in a Database |
|
385
|
|
|
386
|
The self-hosting Fossil repository at <https://fossil-scm.org/> |
|
387
|
currently uses this method rather than [the pipe method](#pipe) because |
|
388
|
it is running inside of a restrictive [chroot jail][cj] which is unable |
|
389
|
to hand off messages to the local MTA directly. |
|
390
|
|
|
391
|
When you configure a Fossil server this way, it adds outgoing email |
|
392
|
messages to an SQLite database file. A separate daemon process can then |
|
393
|
extract those messages for further disposition. |
|
394
|
|
|
395
|
Fossil uses a short TCL script (seen at [](/file/tools/email-sender.tcl)) |
|
396
|
that continuously monitors this database for new messages and hands any that |
|
397
|
it finds off to a local MTA using the same [pipe to MTA protocol](#pipe) |
|
398
|
as above. |
|
399
|
|
|
400
|
In this way, outbound email alerts escape the chroot jail without |
|
401
|
requiring that we insert a separate MTA configuration inside that jail. |
|
402
|
We only need to arrange that the same SQLite DB file be visible both |
|
403
|
inside and outside the chroot jail, which we do by naming the database |
|
404
|
file in the "Store Emails In This Database" setting under Admin → |
|
405
|
Notification. The Tcl script has this path hard-coded as |
|
406
|
`/home/www/fossil/emailqueue.db`, but you will probably need to adjust |
|
407
|
that for your local purposes. |
|
408
|
|
|
409
|
This method may work with other similar technologies besides `chroot`: |
|
410
|
Docker containers, LXC containers, BSD jails, Solaris zones, etc. |
|
411
|
|
|
412
|
With suitable file share mappings, this method may even work with |
|
413
|
virtual machine or distributed computing setups where the MTA and Fossil |
|
414
|
servers are not on the same machine, though beware the [risk of DB |
|
415
|
corruption][rdbc] if used with a file sharing technology that doesn't |
|
416
|
use proper file locking. |
|
417
|
|
|
418
|
You can start this Tcl script as a daemon automatically on most Unix and |
|
419
|
Unix-like systems by adding the following line to the `/etc/rc.local` |
|
420
|
file of the server that hosts the repository sending email alerts: |
|
421
|
|
|
422
|
/usr/bin/tclsh /home/www/fossil/email-sender.tcl & |
|
423
|
|
|
424
|
[cj]: https://en.wikipedia.org/wiki/Chroot |
|
425
|
[rdbc]: https://www.sqlite.org/howtocorrupt.html#_filesystems_with_broken_or_missing_lock_implementations |
|
426
|
|
|
427
|
|
|
428
|
<a id="dir"></a> |
|
429
|
### Method 3: Store in a Directory |
|
430
|
|
|
431
|
This method is functionally very similar to [the DB method](#db), |
|
432
|
differing only in that messages are written to a directory in the |
|
433
|
filesystem. You should therefore read that section and make the minor |
|
434
|
adjustments required by the storage method. |
|
435
|
|
|
436
|
This method may work over a file sharing mechanism that doesn't do file |
|
437
|
locking properly, as long as the reading process is somehow restricted |
|
438
|
from reading a message file as it's being written. |
|
439
|
|
|
440
|
It might be useful in testing and debugging to temporarily switch to |
|
441
|
this method, since you can easily read the generated email messages |
|
442
|
without needing to involve an [MTA]. |
|
443
|
|
|
444
|
|
|
445
|
<a id="relay"></a> |
|
446
|
### Method 4: SMTP Relay |
|
447
|
|
|
448
|
In this configuration, the Fossil server contacts an open SMTP relay and |
|
449
|
sends the messages to it. This method is only appropriate when: |
|
450
|
|
|
451
|
1. You have a local MTA that doesn't accept [the pipe |
|
452
|
protocol](#pipe). |
|
453
|
|
|
454
|
2. The MTA is willing to accept anonymous submissions, since Fossil |
|
455
|
currently has no way to authenticate itself to the MTA. This is [an |
|
456
|
unsafe configuration][omr] in most cases, but some SMTP servers make |
|
457
|
an exception for connections coming from a `localhost` or LAN |
|
458
|
address, choosing to accept such submissions as inherently safe. |
|
459
|
|
|
460
|
If you have a local MTA meeting criterion #1 but not #2, we'd suggest |
|
461
|
using a more powerful SMTP client such as [msmtp](#msmtp) along with one |
|
462
|
of the other methods above. |
|
463
|
|
|
464
|
[omr]: https://en.wikipedia.org/wiki/Open_mail_relay |
|
465
|
|
|
466
|
|
|
467
|
<a id="direct"></a> |
|
468
|
### Method 5: Direct SMTP Send |
|
469
|
|
|
470
|
As of Fossil 2.7, the code to support this method is incomplete, so you |
|
471
|
cannot currently select it as an option in Admin → Notification. |
|
472
|
|
|
473
|
|
|
474
|
<a id="uvs"></a> |
|
475
|
## Users vs Subscribers |
|
476
|
|
|
477
|
Fossil makes a distinction between "users" and "subscribers". A user is |
|
478
|
someone with a username and password: that is, someone who can log into |
|
479
|
the Fossil repository. A subscriber is someone who receives email |
|
480
|
alerts. Users can also be subscribers and subscribers can be users, but |
|
481
|
that does not have to be the case. It is possible to be a user without |
|
482
|
being a subscriber and to be a subscriber without being a user. |
|
483
|
|
|
484
|
In the repository database file, users are tracked with the `user` table |
|
485
|
and subscribers are tracked via the `subscriber` table. |
|
486
|
|
|
487
|
|
|
488
|
<a id="admin"></a> |
|
489
|
## Administrator Activities |
|
490
|
|
|
491
|
The "[List Subscribers](/subscribers)" button at the top of the Admin → |
|
492
|
Notification screen gives a list of subscribers, which gives a Fossil |
|
493
|
server administrator a lot of power over those subscriptions. |
|
494
|
|
|
495
|
Clicking an email address in this subscriber list opens the same |
|
496
|
`/alerts` page that the user can see for their own subscription, but |
|
497
|
with more information and functionality than normal users get: |
|
498
|
|
|
499
|
* Subscription creation and modification timestamps. |
|
500
|
|
|
501
|
* The IP address the user had when they last made a change via either |
|
502
|
`/subscribe` or `/alert`. |
|
503
|
|
|
504
|
* The user's login name, if they are not [a mere subscriber](#uvs). A |
|
505
|
Fossil Admin user is allowed to modify this, either to tie a |
|
506
|
subscription-only record to an existing Fossil user account or to |
|
507
|
break that tie. |
|
508
|
|
|
509
|
* The "Do not call" checkbox allows a Fossil Admin user to mark a given |
|
510
|
email address so that Fossil never sends email to that address. This |
|
511
|
is distinct from unsubscribing that email address because it prevents |
|
512
|
Fossil from accepting a new subscription for that address. |
|
513
|
|
|
514
|
* The Verified checkbox is initially unchecked for subscriber-only |
|
515
|
email addresses until the user clicks the link in the verification |
|
516
|
email. This checkbox lets the Fossil Admin user manually verify the |
|
517
|
user, such as in the case where the verification email message got |
|
518
|
lost. Unchecking this box does not cause another verification email |
|
519
|
to be sent. |
|
520
|
|
|
521
|
* Admin users (only) may activate the "user elevation" subscription, |
|
522
|
which sends a notification when a user is created or is explicitly |
|
523
|
assigned permission they did not formerly have. |
|
524
|
|
|
525
|
This screen also allows a Fossil Admin user to perform other activities |
|
526
|
on behalf of a subscriber which they could do themselves, such as to |
|
527
|
[unsubscribe](#unsub) them. |
|
528
|
|
|
529
|
|
|
530
|
<a id="backup"></a> |
|
531
|
## Cloning, Syncing, and Backups |
|
532
|
|
|
533
|
That’s [covered elsewhere](./backup.md#alerts). |
|
534
|
|
|
535
|
|
|
536
|
<a id="pages" name="commands"></a> |
|
537
|
## Controlling the Email Alert System |
|
538
|
|
|
539
|
This section collects the list of Fossil UI pages and CLI commands that |
|
540
|
control the email alert system, some of which have not been mentioned so |
|
541
|
far: |
|
542
|
|
|
543
|
Commands: |
|
544
|
|
|
545
|
* The [`alerts`](/help/alerts) command |
|
546
|
* The [`test-alert`](/help/test-alert) command |
|
547
|
* The [`test-add-alerts`](/help/test-add-alerts) command |
|
548
|
|
|
549
|
Web pages available to users and subscribers: |
|
550
|
|
|
551
|
* The [`/subscribe`](/help/www/subscribe) page |
|
552
|
* The [`/alerts`](/help/www/alerts) page |
|
553
|
* The [`/unsubscribe`](/help/www/unsubscribe) page |
|
554
|
* The [`/renew`](/help/www/renew) page |
|
555
|
* The [`/contact_admin`](/help/www/contact_admin) page |
|
556
|
|
|
557
|
Administrator-only web pages: |
|
558
|
|
|
559
|
* The [`/setup_notification`](/help/www/setup_notification) page |
|
560
|
* The [`/subscribers`](/help/www/subscribers) page |
|
561
|
|
|
562
|
|
|
563
|
<a id="design"></a> |
|
564
|
## Design of Email Alerts |
|
565
|
|
|
566
|
This section describes the low-level design of the email alert system in |
|
567
|
Fossil. This expands on the high-level administration focused material |
|
568
|
above with minimal repetition. |
|
569
|
|
|
570
|
This section assumes expert-level systems knowledge. If the material |
|
571
|
above sufficed for your purposes, feel free to skip this section, which |
|
572
|
runs to the end of this document. |
|
573
|
|
|
574
|
|
|
575
|
<a id="datades"></a> |
|
576
|
### Data Design |
|
577
|
|
|
578
|
There are two new tables in the repository database, starting with |
|
579
|
Fossil 2.7. These tables are not created in new repositories by |
|
580
|
default. The tables only come into existence as needed when email |
|
581
|
alerts are configured and used. |
|
582
|
|
|
583
|
* <b>SUBSCRIBER</b> → |
|
584
|
The subscriber table records the email address for people who |
|
585
|
want to receive email notifications. Each subscriber has a |
|
586
|
`subscriberCode` which is a random 32-byte blob that uniquely |
|
587
|
identifies the subscriber. There are also fields to indicate |
|
588
|
what kinds of notifications the subscriber wishes to receive, |
|
589
|
whether or not the email address of the subscriber has been |
|
590
|
verified, etc. |
|
591
|
|
|
592
|
* <b>PENDING\_ALERT</b> → |
|
593
|
The PENDING\_ALERT table contains records that define events |
|
594
|
about which alert emails might need to be sent. |
|
595
|
A pending\_alert always refers to an entry in the |
|
596
|
EVENT table. The EVENT table is part of the standard schema |
|
597
|
and records timeline entries. In other words, there is one |
|
598
|
row in the EVENT table for each possible timeline entry. The |
|
599
|
PENDING\_ALERT table refers to EVENT table entries for which |
|
600
|
we might need to send alert emails. |
|
601
|
|
|
602
|
As pointed out above, ["subscribers" are distinct from "users"](#uvs). |
|
603
|
The SUBSCRIBER.SUNAME field is the optional linkage between users and |
|
604
|
subscribers. |
|
605
|
|
|
606
|
|
|
607
|
<a id="stdout"></a> |
|
608
|
### The "stdout" Method |
|
609
|
|
|
610
|
The [list of mail sending methods](#advanced) above left out an |
|
611
|
internal-only method called "stdout" which simply writes the text of the |
|
612
|
email message on standard output. The "stdout" method is used for |
|
613
|
testing and debugging. If you need something similar and can't modify |
|
614
|
your local Fossil instance to use this method, you might temporarily |
|
615
|
switch to [the "dir" method](#dir) instead. |
|
616
|
|
|
617
|
|
|
618
|
<a id="msgfmt"></a> |
|
619
|
### Message Format |
|
620
|
|
|
621
|
The email messages generated by Fossil have a [well-formed |
|
622
|
header][rfc822]. The downstream processing is expected to extract the |
|
623
|
"To:", "From:", "Subject:" and whatever other attributes it needs from |
|
624
|
the email header text. |
|
625
|
|
|
626
|
These emails use the `text/plain` MIME type with the UTF-8 character |
|
627
|
set. We currently use a transfer encoding of `quoted-printable`, but |
|
628
|
there is commented-out code in Fossil to switch to `base64` encoding, |
|
629
|
which Fossil used in the early days leading up to the 2.7 release. |
|
630
|
|
|
631
|
If you switch Fossil back to `base64` mode, you may want to build a |
|
632
|
utility program that ships in the Fossil source tree named |
|
633
|
["tools/decode-email.c"](/file/tools/decode-email.c) which can decode |
|
634
|
these messages into a human-readable format. |
|
635
|
|
|
636
|
|
|
637
|
<a id="inbound" name="bounces"></a> |
|
638
|
### Dealing with Inbound Email |
|
639
|
|
|
640
|
Inbound email messages — for example, bounces from failed alert emails — |
|
641
|
should be relayed to the `fossil email inbound` command. That command |
|
642
|
is currently a no-op place-holder. At some point, we will need to |
|
643
|
design and write a bounce-message processing system for Fossil. |
|
644
|
|
|
645
|
|
|
646
|
<a id="password" name="scode" name="verification"></a> |
|
647
|
### Passwords vs Subscriber Codes |
|
648
|
|
|
649
|
When anonymous passers-by on the Internet sign up for email alerts, |
|
650
|
their email address must first be verified. An email message is sent to |
|
651
|
the address supplied inviting the user to click on a link. The link |
|
652
|
includes a pseudorandom 128-bit blob encoded as 32 hexadecimal digits, |
|
653
|
which serves in place of a password for that email address. (This is |
|
654
|
stored in the database as `subscriber.subscriberCode`.) If anyone visits |
|
655
|
the link, the email address is verified. |
|
656
|
|
|
657
|
Knowledge of the `subscriberCode` is sufficient to control a |
|
658
|
subscription. |
|
659
|
|
|
660
|
Because this code is included in plain text in email alert messages, it |
|
661
|
is not as secure as a separate password, but it has several virtues: |
|
662
|
|
|
663
|
* It is easier for the average subscriber to deal with in that they |
|
664
|
don't have to come up with yet another password and store it safely. |
|
665
|
|
|
666
|
* If the `subscriberCode` is stolen, the worst that can happen is that |
|
667
|
the thief can change that email address's subscription settings. |
|
668
|
Contrast a password which may be shared with other services, which |
|
669
|
then compromises those other services. |
|
670
|
|
|
671
|
* No PII other than the subscriber's email address is available to an |
|
672
|
attacker with the `subscriberCode`. Nor can knowledge of the |
|
673
|
`subscriberCode` lead to an email flood or other annoyance attack, as |
|
674
|
far as I can see. |
|
675
|
|
|
676
|
If the `subscriberCodes` for a Fossil repository are ever compromised, |
|
677
|
new ones can be generated as follows: |
|
678
|
|
|
679
|
UPDATE subscriber SET subscriberCode=randomblob(32); |
|
680
|
|
|
681
|
Since this then affects all new email alerts going out from Fossil, your |
|
682
|
end users may never even realize that they're getting new codes, as long |
|
683
|
as they don't click on the URLs in the footer of old alert messages. |
|
684
|
|
|
685
|
With that in mind, a Fossil server administrator could choose to |
|
686
|
randomize the `subscriberCodes` periodically, such as just before the |
|
687
|
daily digest emails are sent out each day. |
|
688
|
|
|
689
|
**Important:** All of the above is distinct from the passwords for users |
|
690
|
with a Fossil repository login. Such users also have subscriber codes, |
|
691
|
but those codes can only be used to modify the user's email alert |
|
692
|
settings. That code cannot allow a user to log into the user's Fossil |
|
693
|
repository account. |
|
694
|
|
|
695
|
|
|
696
|
<a id="processing"></a> |
|
697
|
### Internal Processing Flow |
|
698
|
|
|
699
|
Almost all of the email alert code is found in the |
|
700
|
[`src/alerts.c`](/file/src/alerts.c) source file. |
|
701
|
|
|
702
|
When email alerts are enabled, a trigger is created in the schema |
|
703
|
(`email_trigger1`) that adds a new entry to the `PENDING_ALERT` table |
|
704
|
every time a row is added to the `EVENT` table. During a |
|
705
|
`fossil rebuild`, the `EVENT` table is rebuilt from scratch; since we do not |
|
706
|
want users to get alerts for every historical check-in, the trigger is |
|
707
|
disabled during `rebuild`. |
|
708
|
|
|
709
|
Email alerts are sent out by the `alert_send_alerts()` function, which |
|
710
|
is normally called automatically due to the `email-autoexec` setting, |
|
711
|
which defaults to enabled. If that setting is disabled or if the user |
|
712
|
simply wants to force email alerts to be sent immediately, they can give |
|
713
|
a `fossil alert send` command, such as via a `cron` script. Each time |
|
714
|
this function is called, the alert messages are moved further down the |
|
715
|
chain, so you cannot cause duplicate alerts by calling it too often. |
|
716
|
|
|
717
|
Digests are handled by recording the time of the last digest in the |
|
718
|
`email-last-digest` setting, and only sending a new digest if the |
|
719
|
current time is one day or later after the last digest. |
|
720
|
|
|
721
|
Individual emails are sent to each subscriber. I (drh) ran tests and |
|
722
|
found that I could send about 1200 emails/second, which is fast enough |
|
723
|
that I do not need to resort to trying to notify multiple subscribers |
|
724
|
with a single email. Because each subscriber gets a separate email, the |
|
725
|
system can include information in the email that is unique to the |
|
726
|
subscriber, such as a link to the page to edit their subscription. That |
|
727
|
link includes the `subscriberCode`. |
|
728
|
|