Fossil SCM

Reworked the documentation for email alerts to put all the information in a single document: a) Moved the "quick email setup" material from the forums.wiki document into `alerts.md`; b) linked to that moved material from its original location; c) greatly expanded the material previously present in the `alerts.md` document; c) merged the `emaildesign.md` document into `alerts.md`, so we don't have to link out to two separate documents which previously partially repeated each other. This pass also fixed a number of grammar errors and broken links.

wyoung 2018-09-17 02:57 trunk

Commit 2ef70be2f754941baba5d5dd849528079cd810ebac92817c9a7334f52995c653

Parent 05b40829151aa8a…

4 files changed +721 -139 -215 +57 -218 +1 -1

~ www/alerts.md - www/emaildesign.md ~ www/forum.wiki ~ www/mkindex.tcl

M www/alerts.md

+721 -139

		--- www/alerts.md
		+++ www/alerts.md
		@@ -1,164 +1,740 @@
1		-Email Alerts
2		-============
3		-
4		-Email Alerts And Notifications
		-------------------------------
5		-
6		-Beginning with version 2.7, Fossil supports the ability to send
7		-email messages to subscribers alerting them to changes in the repository.
8		-Subscribers can request an email notification of the following kinds
9		-of changes:
10		-
11		- * New check-ins
12		- * Changes to any ticket
13		- * Changes to any wiki page
14		- * New forum posts
	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?cmd=ci)
	9	+ * [Ticket](./tickets.wiki) changes
	10	+ * [Wiki](./wikitheory.wiki) page changes
	11	+ * New and edited [forum](./forum.wiki) posts
15	12	* Announcements
16	13
17		-Subscribers can either elect to receive emails as soon as these events happen,
	14	+Subscribers can elect to receive emails as soon as these events happen,
18	15	or they can receive a daily digest of the events instead.
19	16
20		-Email alerts are sent by a [Fossil server](./server.wiki). You must
21		-have a server [set up to make use of email alerts](#setup). Email
22		-alerts do not currently work if you are only using Fossil from the
	17	+Email alerts are sent by a [Fossil server](./server.wiki), which must be
	18	+[set up](#quick) by the Fossil administrator to send email.
	19	+
	20	+Email alerts do not currently work if you are only using Fossil from the
23	21	command line.
24	22
25		-Users and Subscribers
		----------------------
26		-
27		-Fossil makes a distinction between "users" and "subscribers". A
28		-user is someone with a username and password — someone who can
29		-log in. A subscriber is someone who receives email alerts. Users
30		-can also be subscribers and subscribers can be users, but that does
31		-not have to be the case. It is possible to be a user without being
32		-a subscriber and to be a subscriber without being a user.
33		-
34		-In the repository database file, users are tracked with the USER table
35		-and subscribers are tracked via the SUBSCRIBER table.
36		-
37		-<a id="setup"></a>
38		-Activating Email Alerts
		------------------------
39		-
40		-Email alerts are turned off by default. To activate them, log into
41		-the Fossil server as an administrator and visit the
42		-[Admin/Notification](/setup_notification)
43		-setup page. ([`/setup_notification`](/setup_notification))
44		-
45		-Important: Email alerts are configured using Admin/Notification, not
46		-Admin/Email-Server. The Email-Server setup screen is used to configure
47		-a different subsystem within Fossil.
48		-
49		-The Admin/Notification setup screen lets you configure how Fossil should
50		-send email for alerts. There are some required fields at the top of the
51		-screen for elements such as the "From:" address for outgoing emails,
52		-the URL for the Fossil server, and a nickname for the repository that
53		-will appear in the "Subject:" line of outgoing emails. But the key
54		-setup parameter is the "Email Send Method".
55		-
56		-Fossil supports multiple methods for sending email alerts:
57		-
58		- 1. Pipe the email message text into a command, such as `sendmail`.
59		- 2. Store email messages as individual files in a directory and let
60		- some other process set up by the administrator take care of
61		- reading and forwarding those files.
62		- 3. Store email messages as entries in an SQLite database where
63		- some external process and read and forward the emails.
64		- 4. Send emails to an SMTP Relay.
65		- 5. Send emails directly to the recipients via SMTP.
66		-
67		-Fossil 2.7 does not support method (5). Work on supporting that method
68		-is still in progress.
69		-
70		-The self-hosting Fossil repository at <https://www.fossil-scm.org/> currently
71		-uses method (3). Outgoing email messages are added to an SQLite database
72		-file. A separate daemon process continously monitors that database file,
73		-extracts email messages as they are added, and hands them off to
74		-"procmail" to be sent on to the final recipient. The self-hosting
75		-Fossil repository uses this technique rather than method (1) because
76		-it is running inside of a restrictive chroot jail which is unable to
77		-hand off messages to "procmail" directly. The daemon that monitors the
78		-email database is a [short TCL script](/file/tools/email-sender.tcl).
79		-That daemon is started automatically by adding this line:
80		-
81		- /usr/bin/tclsh /home/www/fossil/email-sender.tcl &
82		-
83		-To the `/etc/rc.local` file of the Ubuntu server that hosts the
84		-repository.
85		-
86		-After making necessary changes to the Admin/Notification page, test
87		-those changes by clicking the "[Send Announcement](/announce)" link
88		-at the top of the page. Fill in your email address in the "To:"
89		-line and a test message below, and press "Send Message" to verify that
90		-outgoing email is working.
91		-
92		-<a id="cap7"></a>
93		-Once email notification is working, one must also adjust user permissions
94		-to allow users to subscribe to email notification. On the
95		-Setup/User page, under the permissions for each user, is a new capability
96		-called "Email Alerts". The corresponding capability letter is "7".
97		-That new "7" capability must be enabled in order for
98		-users to be able to become subscribers. To allow anonymous passers-by
99		-on the internet to subscribe, simply enable "Email Alerts" for the
100		-"nobody" user category. To require that the user solve a simple CAPTCHA
101		-first, add it to the "anonymous" user category instead.
102		-
103		-Signing Up For Email Notification
		----------------------------------
104		-
105		-Users and/or anonymous passers-by can visit the
106		-[`/subscribe`](/subscribe) page to sign
107		-up for email notification.
108		-
109		-If your users are getting the following complaint from Fossil:
	23	+A bit of terminology: Fossil uses the terms "email alerts" and
	24	+"notifications" interchangeably. We stick to the former term in this
	25	+document except when referring to parts of the Fossil UI still using the
	26	+latter term.
	27	+
	28	+
	29	+## Setup Prerequisites
	30	+
	31	+Much of this document describes how to set up Fossil's email alert
	32	+system. To follow this guide, you will need a Fossil UI browser window
	33	+open to the [Admin → Notification](/setup_notification) Fossil UI screen
	34	+on the the Fossil server that will be sending these email alerts, logged
	35	+in as a user with Admin capability. 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
	49	+below to tell Fossil which repository you mean it to apply the command
	50	+to.
	51	+
	52	+There are other prerequisites for email service, but since they vary
	53	+depending on the configuration you choose, we'll cover these inline
	54	+below.
	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	+This is our "quick setup" option even though setting up an SMTP mail
	69	+server is not trival, because there are many other reasons to have such
	70	+a server set up already: internal project email service, `cron`
	71	+notifications, server status monitoring notifications...
	72	+
	73	+With that out of the way, the Fossil-specific steps are easy:
	74	+
	75	+1. Go to [Admin → Notification](/setup_notification) and fill out all
	76	+ of the Required fields:
	77	+
	78	+ * Canonical server URL — Use the suggested URL
	79	+
	80	+ * "From" email address — `[email protected]` is
	81	+ traditional, but suit yourself
	82	+
	83	+ * Repository nickname — See the suggested examples on the web page.
	84	+
	85	+2. Set "Email Send Method" to "Pipe to a command"
	86	+
	87	+3. Set the "Administrator email address" to a suitable valid email
	88	+ address on that machine. It could be the same value you used for
	89	+ the "From" address above, or it could be a different value like
	90	+ `[email protected]`.
	91	+
	92	+Save your changes.
	93	+
	94	+At the command line, say
	95	+
	96	+ $ fossil set email-send-command
	97	+
	98	+If that gives a blank value instead of `sendmail -ti`, say
	99	+
	100	+ $ fossil set email-send-command "sendmail -ti"
	101	+
	102	+to force the setting. That works around a [known
	103	+bug](https://fossil-scm.org/forum/forumpost/840b676410) which may be
	104	+squished by the time you read this.
	105	+
	106	+If you're running Postfix or Exim, you might think that command is
	107	+wrong, since you aren't running Sendmail. These mail servers provide a
	108	+`sendmail` command for compatibility with software like Fossil that has
	109	+no good reason to care exactly which SMTP server implementation is
	110	+running at a given site. There may be other SMTP servers that also
	111	+provide a compatible `sendmail` command, in which case they may work
	112	+with Fossil using the same steps as above.
	113	+
	114	+<a id="status"></a>
	115	+If you reload the Admin → Notification page, the Status section at the
	116	+top should show:
	117	+
	118	+ Outgoing Email: Piped to command "sendmail -ti"
	119	+ Pending Alerts: 0 normal, 0 digest
	120	+ Subscribers: 0 active, 0 total
	121	+
	122	+Before you move on to the next section, you might like to read up on
	123	+[some subtleties](#pipe) with the "pipe to a command" method that we did
	124	+not cover above.
	125	+
	126	+
	127	+<a id="usage"></a>
	128	+## Usage and Testing
	129	+
	130	+Now that email service from Fossil is set up, you can test it and begin
	131	+using it.
	132	+
	133	+
	134	+<a id="sub" name="subscribe"></a>
	135	+### Subscribing to Alerts
	136	+
	137	+In the Status output above, we saw that there are no subscribers, so the
	138	+next step is to add the first one.
	139	+
	140	+Go to the `/subscribe` page on your Fossil instance to sign up for email
	141	+alerts. At the very least, you will need to sign up for "Forum Posts"
	142	+and "Announcements" to complete the testing steps below.
	143	+
	144	+If you're logged in with a Fossil repository user account and put the
	145	+same user name and email address into this forum as you used for your
	146	+user information under Admin → Users, Fossil will simply tie your alert
	147	+preferences to your login record, and the email address in your user's
	148	+Contact Info field will be considered already-verified. Otherwise,
	149	+Fossil will create an alert-only record, and you will have to verify the
	150	+email address before Fossil will send alerts to it.
	151	+
	152	+This shows a key aspect of the way Fossil's email alerts system works,
	153	+by the way: a user can be signed up for email alerts without having a
	154	+full-fledged Fossil user account. Only when both user names are the same
	155	+are the two records tied together under the hood. For more on this, see
	156	+[Users vs Subscribers below](#uvs).
	157	+
	158	+If you are seeing the following complaint from Fossil:
110	159
111	160	<blockquote>
112	161	Use a different login with greater privilege than FOO to access
113	162	/subscribe
114	163	</blockquote>
115	164
116		-...then you forgot to [give capability 7](#cap7) to that user or to a
117		-user category that the user is a member of.
	165	+...then the repository's administrator forgot to [give the Alerts capability](#cap7)
	166	+to that user or to a user category that the user is a member of.
118	167
119		-After signing up, a single verification email
120		-is sent. The new subscriber must click a link on that email in order to
121		-activate the subscription.
	168	+After a subscriber signs up for alerts for the first time, a single
	169	+verification email is sent to that subscriber's given email address.
	170	+The new subscriber must click a link in that email in order to activate
	171	+the subscription.
122	172
123	173	Subscription verification emails are only sent once. This is a defense
124		-against malicious robots that try to harass innocent internet users
125		-by having subscription pages send multiple verification emails.
126		-If the initial subscription verification does not go through correctly,
127		-an administrator must intervene to reset the subscription.
128		-
129		-Every subscriber has a long random hexadecimal security code that serves
130		-as their password. All email notifications contain a link back to the
131		-Fossil server, incorporating this security code, which allows the
132		-subscriber to adjust their subscription options.
133		-
134		-Administrator Activities
		-------------------------
135		-
136		-The repository administrator has unlimited control over individual
137		-subscriptions. The "[List Subscribers](/subscribers)" button at the top
138		-of the Setup/Notification screen gives a list of subscribers. Clicking on
139		-any subscriber link allows the administrator to adjust the subscription.
140		-
141		-To unsubscribe, first select the "unsubscribe" checkbox, then press the
142		-"Unsubscribe" button.
143		-
144		-The "verified" checkbox determines whether or not an email address has
145		-been verified. This can be enabled or disabled manually by the
146		-administrator.
147		-
148		-Cloning, Syncing, and Backups
		------------------------------
149		-
150		-The Setup/Notification settings are not replicated using clone or sync.
151		-In a network of peer repositories, you only want one repository sending
152		-email notifications. If you were to replicate the email notification
153		-settings to a separate repository, then subscribers would get multiple
154		-notifications for each event, which would be bad.
	174	+against malicious robots that try to harass innocent Internet users by
	175	+having subscription pages send multiple verification emails. If the
	176	+initial subscription verification does not go through correctly, an
	177	+administrator must [intervene](#admin) to reset the subscription.
	178	+
	179	+Every subscriber-only email address has a [long random hexadecimal
	180	+security code](#scode) that serves in place of a password. All email
	181	+alerts contain a link in their footer back to the Fossil server,
	182	+incorporating this security code, which allows the subscriber to adjust
	183	+their subscription options. If a user doesn't have any of those emails,
	184	+they can request a link via email by visiting the `/alerts` or
	185	+`/unsubscribe` page on the repository.
	186	+
	187	+Those with Fossil repository logins can adjust their email alert
	188	+settings by visiting the `/alerts` page on the repository. With the
	189	+default skin, you can get there by clicking the "Logout" link in the
	190	+upper right corner of any Fossil UI page then clicking the "Email
	191	+Alerts" link. That link is also available via the Sitemap (`/sitemap`)
	192	+and via the default skin's hamburger menu (☰).
	193	+
	194	+
	195	+<a id="unsub" name="unsubscribe"></a>
	196	+### Unsubscribing
	197	+
	198	+To unsubscribe from alerts, visit the `/alerts` page on the repository,
	199	+click the "Unsubscribe" button, then check the "Unsbuscribe" checkbox to
	200	+verify your action and press the "Unsubscribe" button a second time.
	201	+
	202	+This interlock is intended to prevent accidental unsubscription.
	203	+
	204	+
	205	+<a id="test"></a>
	206	+### Test Email Service
	207	+
	208	+The easiest way to test email sending from Fossil is via the "[Send
	209	+Announcement](/announce)" link at the top of the "Email Notification
	210	+Setup" page. Put your email address in the "To:" line and a test
	211	+message below, then press "Send Message" to verify that outgoing email
	212	+is working.
	213	+
	214	+Another method is from the command line:
	215	+
	216	+ $ fossil alerts test-message [email protected] --body README.md --subject Test
	217	+
	218	+That should send you an email with "Test" in the subject line and the
	219	+contents of your project's `README.md` file in the body.
	220	+
	221	+That command assumes that your project contains a "readme" file, but of
	222	+course it does, because you have followed the [Programming Style Guide
	223	+Checklist][cl], right? Right.
	224	+
	225	+[cl]: https://sendgrid.com/blog/programming-style-guide-checklist/
	226	+
	227	+
	228	+<a id="cap7"></a>
	229	+### User Capabilities
	230	+
	231	+Once email alerts are working, one must also adjust user permissions to
	232	+allow users to subscribe to email alerts. In the capability list for
	233	+each user on the Admin → Users page is a new capability called "Email
	234	+Alerts". The corresponding capability letter is "7", which you must
	235	+give to any user that needs to use the subscription setup pages,
	236	+`/subscribe` and `/alerts`.
	237	+
	238	+To allow any passer-by on the Internet to subscribe, give the "Email
	239	+Alerts" capability to the "nobody" user category. To require that a
	240	+person solve a simple CAPTCHA first, give that capability to the
	241	+"anonymous" user category instead.
	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 a 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][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	+We believe the [`msmtp`][msmtp] SMTP client is compatible with this
	366	+protocol if you give it the `-t` option. To our knowledge, this remains
	367	+untested, but if it works, this would be a useful option on a server
	368	+hosting a Fossil repository which doesn't otherwise require a separate
	369	+SMTP server for other purposes.
	370	+
	371	+It is probably also possible to configure [`procmail`][pmdoc] to work
	372	+with this protocol. If you know how to do it, a patch to this document
	373	+or a how-to on [the Fossil forum][ff] would be appreciated.
	374	+
	375	+[ff]: https://fossil-scm.org/forum/
	376	+[msmtp]: https://marlam.de/msmtp/
	377	+[mta]: https://en.wikipedia.org/wiki/Message_transfer_agent
	378	+[pmdoc]: http://pm-doc.sourceforge.net/doc/
	379	+[rfc822]: https://www.w3.org/Protocols/rfc822/
	380	+
	381	+
	382	+<a id="db"></a>
	383	+### Method 2: Store in a Database
	384	+
	385	+The self-hosting Fossil repository at <https://www.fossil-scm.org/>
	386	+currently uses this method rather than [the pipe method](#pipe) because
	387	+it is running inside of a restrictive [chroot jail][cj] which is unable
	388	+to hand off messages to the local MTA directly.
	389	+
	390	+When you configure a Fossil server this way, it adds outgoing email
	391	+messages to a SQLite database file. A separate daemon process can then
	392	+extract those messages for further disposition.
	393	+
	394	+Fossil includes a copy of [the daemon](/file/tools/email-sender.tcl)
	395	+used on `fossil-scm.org`: it is just a short Tcl script that
	396	+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][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 Fossi 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	+This screen also allows a Fossil Admin user to perform other activities
	522	+on behalf of a subscriber which they could do themselves, such as to
	523	+[unsubscribe](#unsub) them.
	524	+
	525	+
	526	+<a id="backup"></a>
	527	+## Cloning, Syncing, and Backups
	528	+
	529	+The Admin → Notification settings are not replicated using clone or
	530	+sync, and it is not possible to push such settings from one repository
	531	+to another. In a network of peer repositories, you only want one
	532	+repository sending email alerts. If you were to replicate the email
	533	+alert settings to a separate repository, then subscribers would get
	534	+multiple alerts for each event, which would be bad.
155	535
156	536	However, the subscriber list can be synced for backup purposes. Use the
157	537	[`fossil config pull subscriber`](/help?cmd=configuration) command to
158	538	pull the latest subscriber list from a server into a backup repository.
	539	+
	540	+The `push`, `export`, and `import` commands all work similarly.
	541	+
	542	+
	543	+<a id="pages" name="commands"></a>
	544	+## Controlling the Email Alert System
	545	+
	546	+This section collects the list of Fossil UI pages and CLI commands that
	547	+control the email alert system, some of which have not been mentioned so
	548	+far:
	549	+
	550	+Commands:
	551	+
	552	+ * The [`alerts`](/help?cmd=alerts) command
	553	+ * The [`test-alert`](/help?cmd=test-alert) command
	554	+ * The [`test-add-alerts`](/help?cmd=test-add-alerts) command
	555	+
	556	+Web pages available to users and subscribers:
	557	+
	558	+ * The [`/subscribe`](/help?cmd=/subscribe) page
	559	+ * The [`/alerts`](/help?cmd=/alerts) page
	560	+ * The [`/unsubscribe`](/help?cmd=/unsubscribe) page
	561	+ * The [`/contact_admin`](/help?cmd=/contact_admin) page
	562	+
	563	+Administrator-only web pages:
	564	+
	565	+ * The [`/setup_notification`](/help?cmd=/setup_notification) page
	566	+ * The [`/subscribers`](/help?cmd=/subscribers) page
	567	+
	568	+
	569	+<a id="design"></a>
	570	+## Design of Email Alerts
	571	+
	572	+This section describes the low-level design of the email alert system in
	573	+Fossil. This expands on the high-level administion focused material
	574	+above with minimal repetition.
	575	+
	576	+This section assumes expert-level systems knowledge. If the material
	577	+above sufficed for your purposes, feel free to skip this section, which
	578	+runs to the end of this document.
	579	+
	580	+
	581	+<a id="datades"></a>
	582	+### Data Design
	583	+
	584	+There are three new tables in the repository database, starting with
	585	+Fossil 2.7. These tables are not created in new repositories by
	586	+default. The tables only come into existence as needed when email
	587	+alerts are configured and used.
	588	+
	589	+
	590	+ * <b>SUBSCRIBER</b> →
	591	+ The subscriber table records the email address for people who
	592	+ want to receive email notifications. Each subscriber has a
	593	+ `subscriberCode` which is a random 32-byte blob that uniquely
	594	+ identifies the subscriber. There are also fields to indicate
	595	+ what kinds of notifications the subscriber wishes to receive,
	596	+ whether or not the email address of the subscriber has been
	597	+ verified, etc.
	598	+
	599	+ * <b>PENDING\_ALERT</b> →
	600	+ The PENDING\_ALERT table contains records that define events
	601	+ about which alert emails might need to be sent.
	602	+ A pending\_alert always refers to an entry in the
	603	+ EVENT table. The EVENT table is part of the standard schema
	604	+ and records timeline entries. In other words, there is one
	605	+ row in the EVENT table for each possible timeline entry. The
	606	+ PENDING\_ALERT table refers to EVENT table entries for which
	607	+ we might need to send alert emails.
	608	+
	609	+ * <b>EMAIL\_BOUNCE</b> →
	610	+ This table is intended to record email bounce history so that
	611	+ subscribers with excessive bounces can be turned off. That
	612	+ logic has not yet been implemented so the EMAIL\_BOUNCE table
	613	+ is currently unused.
	614	+
	615	+As pointed out above, ["subscribers" are distinct from "users"](#uvs).
	616	+The SUBSCRIBER.SUNAME field is the optional linkage between users and
	617	+subscribers.
	618	+
	619	+
	620	+<a id="stdout"></a>
	621	+### The "stdout" Method
	622	+
	623	+The [list of mail sending methods](#advanced) above left out an
	624	+internal-only method called "stdout" which simply writes the text of the
	625	+email message on standard output. The "stdout" method is used for
	626	+testing and debugging. If you need something similar and can't modify
	627	+your local Fossil instance to use this method, you might temporarily
	628	+switch to [the "dir" method](#dir) instead.
	629	+
	630	+
	631	+<a id="msgfmt"></a>
	632	+### Message Format
	633	+
	634	+The email messages generated by Fossil have a [well-formed
	635	+header][rfc822]. The downstream processing is expected to extract the
	636	+"To:", "From:", "Subject:" and whatever other attributes it needs from
	637	+the email header text.
	638	+
	639	+These emails use the `text/plain` MIME type with the UTF-8 character
	640	+set. We currently use a transfer encoding of `quoted-printable`, but
	641	+there is commented-out code in Fossil to switch to `base64` encoding,
	642	+which Fossil used in the early days leading up to the 2.7 release.
	643	+
	644	+If you switch Fossil back to `base64` mode, you may want to build a
	645	+utility program that ships in the Fossil source tree named
	646	+["tools/decode-email.c"](/file/tools/decode-email.c) which can decode
	647	+these messages into a human-readable format.
	648	+
	649	+
	650	+<a id="inbound" name="bounces"></a>
	651	+### Dealing with Inbound Email
	652	+
	653	+Inbound email messages — for example, bounces from failed alert emails —
	654	+should be relayed to the `fossil email inbound` command. That command
	655	+is currently a no-op place-holder. At some point, we will need to
	656	+design and write a bounce-message processing system for Fossil.
	657	+
	658	+
	659	+<a id="password" name="scode" name="verification"></a>
	660	+### Passwords vs Subscriber Codes
	661	+
	662	+When anonymous passers-by on the Internet sign up for email alerts,
	663	+their email address must first be verified. An email message is sent to
	664	+the address supplied inviting the user to click on a link. The link
	665	+includes a pseudorandom 128-bit blob encoded as 32 hexadecimal digits,
	666	+which serves in place of a password for that email address. (This is
	667	+stored in the database as `subscriber.subscriberCode`.) If anyone visits
	668	+the link, the email address is verified.
	669	+
	670	+Knowledge of the `subscriberCode` is sufficient to control a
	671	+subscription.
	672	+
	673	+Because this code is included in plain text in email alert messages, it
	674	+is not as secure as a separate password, but it has several virtues:
	675	+
	676	+* It is easier for the average subscriber to deal with in that they
	677	+ don't have to come up with yet another password and store it safely.
	678	+
	679	+* If the `subscriberCode` is stolen, the worst that can happen is that
	680	+ the thief can change that email address's subscription settings.
	681	+ Contrast a password which may be shared with other services, which
	682	+ then compromises those other services.
	683	+
	684	+* No PII other than the subscriber's email address is available to an
	685	+ attacker with the `subscriberCode`. Nor can knowledge of the
	686	+ `subscriberCode` lead to a email flood or other annoyance attack, as
	687	+ far as I can see.
	688	+
	689	+If the `subscriberCodes` for a Fossil repository are ever compromised,
	690	+new ones can be generated as follows:
	691	+
	692	+ UPDATE subscriber SET subscriberCode=randomblob(32);
	693	+
	694	+Since this then affects all new email alerts going out from Fossil, your
	695	+end users may never even realize that they're getting new codes, as long
	696	+as they don't click on the URLs in the footer of old alert messages.
	697	+
	698	+With that in mind, a Fossil server administrator could choose to
	699	+randomize the `subscriberCodes` periodically, such as just before the
	700	+daily digest emails are sent out each day.
	701	+
	702	+Important: All of the above is distinct from the passwords for users
	703	+with a Fossil repository login. Such users also have subscriber codes,
	704	+but those codes can only be used to modify the user's email alert
	705	+settings. That code cannot allow a user to log into the user's Fossil
	706	+repository account.
	707	+
	708	+
	709	+<a id="processing"></a>
	710	+### Internal Processing Flow
	711	+
	712	+Almost all of the email alert code is found in the
	713	+[`src/alerts.c`](/file/src/alerts.c) source file.
	714	+
	715	+When email alerts are enabled, a trigger is created in the schema
	716	+(`email_trigger1`) that adds a new entry to the `PENDING_ALERT` table
	717	+every time a row is added to the `EVENT` table. During a `fossil
	718	+rebuild`, the `EVENT` table is rebuilt from scratch; since we do not
	719	+want users to get alerts for every historical check-in, the trigger is
	720	+disabled during `rebuild`.
	721	+
	722	+Email alerts are sent out by the `alert_send_alerts()` function, which
	723	+is normally called automatically due to the `email-autoexec` setting,
	724	+which defaults to enabled. If that setting is disabled or if the user
	725	+simply wants to force email alerts to be sent immediately, they can give
	726	+a `fossil alert send` command, such as via a `cron` script. Each time
	727	+this function is called, the alert messages are moved further down the
	728	+chain, so you cannot cause duplicate alerts by calling it too often.
	729	+
	730	+Digests are handled by recording the time of the last digest in the
	731	+`email-last-digest` setting, and only sending a new digest if the
	732	+current time is one day or later after the last digest.
	733	+
	734	+Individual emails are sent to each subscriber. I (drh) ran tests and
	735	+found that I could send about 1200 emails/second, which is fast enough
	736	+that I do not need to resort to trying to notify multiple subscribers
	737	+with a single email. Because each subscriber gets a separate email, the
	738	+system can include information in the email that is unique to the
	739	+subscriber, such as a link to the page to edit their subscription. That
	740	+link includes the `subscriberCode`.
159	741
160	742	DELETED www/emaildesign.md

	--- www/alerts.md
	+++ www/alerts.md
	@@ -1,164 +1,740 @@
1	Email Alerts
2	============
3
4	Email Alerts And Notifications
	-------------------------------
5
6	Beginning with version 2.7, Fossil supports the ability to send
7	email messages to subscribers alerting them to changes in the repository.
8	Subscribers can request an email notification of the following kinds
9	of changes:
10
11	* New check-ins
12	* Changes to any ticket
13	* Changes to any wiki page
14	* New forum posts

15	* Announcements
16
17	Subscribers can either elect to receive emails as soon as these events happen,
18	or they can receive a daily digest of the events instead.
19
20	Email alerts are sent by a [Fossil server](./server.wiki). You must
21	have a server [set up to make use of email alerts](#setup). Email
22	alerts do not currently work if you are only using Fossil from the

23	command line.
24
25	Users and Subscribers
	----------------------
26
27	Fossil makes a distinction between "users" and "subscribers". A
28	user is someone with a username and password — someone who can
29	log in. A subscriber is someone who receives email alerts. Users
30	can also be subscribers and subscribers can be users, but that does
31	not have to be the case. It is possible to be a user without being
32	a subscriber and to be a subscriber without being a user.
33
34	In the repository database file, users are tracked with the USER table
35	and subscribers are tracked via the SUBSCRIBER table.
36
37	<a id="setup"></a>
38	Activating Email Alerts
	------------------------
39
40	Email alerts are turned off by default. To activate them, log into
41	the Fossil server as an administrator and visit the
42	[Admin/Notification](/setup_notification)
43	setup page. ([`/setup_notification`](/setup_notification))
44
45	Important: Email alerts are configured using Admin/Notification, not
46	Admin/Email-Server. The Email-Server setup screen is used to configure
47	a different subsystem within Fossil.
48
49	The Admin/Notification setup screen lets you configure how Fossil should
50	send email for alerts. There are some required fields at the top of the
51	screen for elements such as the "From:" address for outgoing emails,
52	the URL for the Fossil server, and a nickname for the repository that
53	will appear in the "Subject:" line of outgoing emails. But the key
54	setup parameter is the "Email Send Method".
55
56	Fossil supports multiple methods for sending email alerts:
57
58	1. Pipe the email message text into a command, such as `sendmail`.
59	2. Store email messages as individual files in a directory and let
60	some other process set up by the administrator take care of
61	reading and forwarding those files.
62	3. Store email messages as entries in an SQLite database where
63	some external process and read and forward the emails.
64	4. Send emails to an SMTP Relay.
65	5. Send emails directly to the recipients via SMTP.
66
67	Fossil 2.7 does not support method (5). Work on supporting that method
68	is still in progress.
69
70	The self-hosting Fossil repository at <https://www.fossil-scm.org/> currently
71	uses method (3). Outgoing email messages are added to an SQLite database
72	file. A separate daemon process continously monitors that database file,
73	extracts email messages as they are added, and hands them off to
74	"procmail" to be sent on to the final recipient. The self-hosting
75	Fossil repository uses this technique rather than method (1) because
76	it is running inside of a restrictive chroot jail which is unable to
77	hand off messages to "procmail" directly. The daemon that monitors the
78	email database is a [short TCL script](/file/tools/email-sender.tcl).
79	That daemon is started automatically by adding this line:
80
81	/usr/bin/tclsh /home/www/fossil/email-sender.tcl &
82
83	To the `/etc/rc.local` file of the Ubuntu server that hosts the
84	repository.
85
86	After making necessary changes to the Admin/Notification page, test
87	those changes by clicking the "[Send Announcement](/announce)" link
88	at the top of the page. Fill in your email address in the "To:"
89	line and a test message below, and press "Send Message" to verify that
90	outgoing email is working.
91
92	<a id="cap7"></a>
93	Once email notification is working, one must also adjust user permissions
94	to allow users to subscribe to email notification. On the
95	Setup/User page, under the permissions for each user, is a new capability
96	called "Email Alerts". The corresponding capability letter is "7".
97	That new "7" capability must be enabled in order for
98	users to be able to become subscribers. To allow anonymous passers-by
99	on the internet to subscribe, simply enable "Email Alerts" for the
100	"nobody" user category. To require that the user solve a simple CAPTCHA
101	first, add it to the "anonymous" user category instead.
102
103	Signing Up For Email Notification
	----------------------------------
104
105	Users and/or anonymous passers-by can visit the
106	[`/subscribe`](/subscribe) page to sign
107	up for email notification.
108
109	If your users are getting the following complaint from Fossil:


































































































































110
111	<blockquote>
112	Use a different login with greater privilege than FOO to access
113	/subscribe
114	</blockquote>
115
116	...then you forgot to [give capability 7](#cap7) to that user or to a
117	user category that the user is a member of.
118
119	After signing up, a single verification email
120	is sent. The new subscriber must click a link on that email in order to
121	activate the subscription.

122
123	Subscription verification emails are only sent once. This is a defense
124	against malicious robots that try to harass innocent internet users
125	by having subscription pages send multiple verification emails.
126	If the initial subscription verification does not go through correctly,
127	an administrator must intervene to reset the subscription.
128
129	Every subscriber has a long random hexadecimal security code that serves
130	as their password. All email notifications contain a link back to the
131	Fossil server, incorporating this security code, which allows the
132	subscriber to adjust their subscription options.
133
134	Administrator Activities
	-------------------------
135
136	The repository administrator has unlimited control over individual
137	subscriptions. The "[List Subscribers](/subscribers)" button at the top
138	of the Setup/Notification screen gives a list of subscribers. Clicking on
139	any subscriber link allows the administrator to adjust the subscription.
140
141	To unsubscribe, first select the "unsubscribe" checkbox, then press the
142	"Unsubscribe" button.
143
144	The "verified" checkbox determines whether or not an email address has
145	been verified. This can be enabled or disabled manually by the
146	administrator.
147
148	Cloning, Syncing, and Backups
	------------------------------
149
150	The Setup/Notification settings are not replicated using clone or sync.
151	In a network of peer repositories, you only want one repository sending
152	email notifications. If you were to replicate the email notification
153	settings to a separate repository, then subscribers would get multiple
154	notifications for each event, which would be bad.



































































































































































































































































































































































155
156	However, the subscriber list can be synced for backup purposes. Use the
157	[`fossil config pull subscriber`](/help?cmd=configuration) command to
158	pull the latest subscriber list from a server into a backup repository.










































































































































































































159
160	ELETED www/emaildesign.md

	--- www/alerts.md
	+++ www/alerts.md
	@@ -1,164 +1,740 @@




	-------------------------------
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?cmd=ci)
9	* [Ticket](./tickets.wiki) changes
10	* [Wiki](./wikitheory.wiki) page changes
11	* New and edited [forum](./forum.wiki) posts
12	* Announcements
13
14	Subscribers can elect to receive emails as soon as these events happen,
15	or they can receive a daily digest of the events instead.
16
17	Email alerts are sent by a [Fossil server](./server.wiki), which must be
18	[set up](#quick) by the Fossil administrator to send email.
19
20	Email alerts do not currently work if you are only using Fossil from the
21	command line.
22

	----------------------













	------------------------

































































	----------------------------------
23	A bit of terminology: Fossil uses the terms "email alerts" and
24	"notifications" interchangeably. We stick to the former term in this
25	document except when referring to parts of the Fossil UI still using the
26	latter term.
27
28
29	## Setup Prerequisites
30
31	Much of this document describes how to set up Fossil's email alert
32	system. To follow this guide, you will need a Fossil UI browser window
33	open to the [Admin → Notification](/setup_notification) Fossil UI screen
34	on the the Fossil server that will be sending these email alerts, logged
35	in as a user with Admin capability. 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
49	below to tell Fossil which repository you mean it to apply the command
50	to.
51
52	There are other prerequisites for email service, but since they vary
53	depending on the configuration you choose, we'll cover these inline
54	below.
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	This is our "quick setup" option even though setting up an SMTP mail
69	server is not trival, because there are many other reasons to have such
70	a server set up already: internal project email service, `cron`
71	notifications, server status monitoring notifications...
72
73	With that out of the way, the Fossil-specific steps are easy:
74
75	1. Go to [Admin → Notification](/setup_notification) and fill out all
76	of the Required fields:
77
78	* Canonical server URL — Use the suggested URL
79
80	* "From" email address — `[email protected]` is
81	traditional, but suit yourself
82
83	* Repository nickname — See the suggested examples on the web page.
84
85	2. Set "Email Send Method" to "Pipe to a command"
86
87	3. Set the "Administrator email address" to a suitable valid email
88	address on that machine. It could be the same value you used for
89	the "From" address above, or it could be a different value like
90	`[email protected]`.
91
92	Save your changes.
93
94	At the command line, say
95
96	$ fossil set email-send-command
97
98	If that gives a blank value instead of `sendmail -ti`, say
99
100	$ fossil set email-send-command "sendmail -ti"
101
102	to force the setting. That works around a [known
103	bug](https://fossil-scm.org/forum/forumpost/840b676410) which may be
104	squished by the time you read this.
105
106	If you're running Postfix or Exim, you might think that command is
107	wrong, since you aren't running Sendmail. These mail servers provide a
108	`sendmail` command for compatibility with software like Fossil that has
109	no good reason to care exactly which SMTP server implementation is
110	running at a given site. There may be other SMTP servers that also
111	provide a compatible `sendmail` command, in which case they may work
112	with Fossil using the same steps as above.
113
114	<a id="status"></a>
115	If you reload the Admin → Notification page, the Status section at the
116	top should show:
117
118	Outgoing Email: Piped to command "sendmail -ti"
119	Pending Alerts: 0 normal, 0 digest
120	Subscribers: 0 active, 0 total
121
122	Before you move on to the next section, you might like to read up on
123	[some subtleties](#pipe) with the "pipe to a command" method that we did
124	not cover above.
125
126
127	<a id="usage"></a>
128	## Usage and Testing
129
130	Now that email service from Fossil is set up, you can test it and begin
131	using it.
132
133
134	<a id="sub" name="subscribe"></a>
135	### Subscribing to Alerts
136
137	In the Status output above, we saw that there are no subscribers, so the
138	next step is to add the first one.
139
140	Go to the `/subscribe` page on your Fossil instance to sign up for email
141	alerts. At the very least, you will need to sign up for "Forum Posts"
142	and "Announcements" to complete the testing steps below.
143
144	If you're logged in with a Fossil repository user account and put the
145	same user name and email address into this forum as you used for your
146	user information under Admin → Users, Fossil will simply tie your alert
147	preferences to your login record, and the email address in your user's
148	Contact Info field will be considered already-verified. Otherwise,
149	Fossil will create an alert-only record, and you will have to verify the
150	email address before Fossil will send alerts to it.
151
152	This shows a key aspect of the way Fossil's email alerts system works,
153	by the way: a user can be signed up for email alerts without having a
154	full-fledged Fossil user account. Only when both user names are the same
155	are the two records tied together under the hood. For more on this, see
156	[Users vs Subscribers below](#uvs).
157
158	If you are seeing the following complaint from Fossil:
159
160	<blockquote>
161	Use a different login with greater privilege than FOO to access
162	/subscribe
163	</blockquote>
164
165	...then the repository's administrator forgot to [give the Alerts capability](#cap7)
166	to that user or to a user category that the user is a member of.
167
168	After a subscriber signs up for alerts for the first time, a single
169	verification email is sent to that subscriber's given email address.
170	The new subscriber must click a link in that email in order to activate
171	the subscription.
172
173	Subscription verification emails are only sent once. This is a defense











	-------------------------














	------------------------------
174	against malicious robots that try to harass innocent Internet users by
175	having subscription pages send multiple verification emails. If the
176	initial subscription verification does not go through correctly, an
177	administrator must [intervene](#admin) to reset the subscription.
178
179	Every subscriber-only email address has a [long random hexadecimal
180	security code](#scode) that serves in place of a password. All email
181	alerts contain a link in their footer back to the Fossil server,
182	incorporating this security code, which allows the subscriber to adjust
183	their subscription options. If a user doesn't have any of those emails,
184	they can request a link via email by visiting the `/alerts` or
185	`/unsubscribe` page on the repository.
186
187	Those with Fossil repository logins can adjust their email alert
188	settings by visiting the `/alerts` page on the repository. With the
189	default skin, you can get there by clicking the "Logout" link in the
190	upper right corner of any Fossil UI page then clicking the "Email
191	Alerts" link. That link is also available via the Sitemap (`/sitemap`)
192	and via the default skin's hamburger menu (☰).
193
194
195	<a id="unsub" name="unsubscribe"></a>
196	### Unsubscribing
197
198	To unsubscribe from alerts, visit the `/alerts` page on the repository,
199	click the "Unsubscribe" button, then check the "Unsbuscribe" checkbox to
200	verify your action and press the "Unsubscribe" button a second time.
201
202	This interlock is intended to prevent accidental unsubscription.
203
204
205	<a id="test"></a>
206	### Test Email Service
207
208	The easiest way to test email sending from Fossil is via the "[Send
209	Announcement](/announce)" link at the top of the "Email Notification
210	Setup" page. Put your email address in the "To:" line and a test
211	message below, then press "Send Message" to verify that outgoing email
212	is working.
213
214	Another method is from the command line:
215
216	$ fossil alerts test-message [email protected] --body README.md --subject Test
217
218	That should send you an email with "Test" in the subject line and the
219	contents of your project's `README.md` file in the body.
220
221	That command assumes that your project contains a "readme" file, but of
222	course it does, because you have followed the [Programming Style Guide
223	Checklist][cl], right? Right.
224
225	[cl]: https://sendgrid.com/blog/programming-style-guide-checklist/
226
227
228	<a id="cap7"></a>
229	### User Capabilities
230
231	Once email alerts are working, one must also adjust user permissions to
232	allow users to subscribe to email alerts. In the capability list for
233	each user on the Admin → Users page is a new capability called "Email
234	Alerts". The corresponding capability letter is "7", which you must
235	give to any user that needs to use the subscription setup pages,
236	`/subscribe` and `/alerts`.
237
238	To allow any passer-by on the Internet to subscribe, give the "Email
239	Alerts" capability to the "nobody" user category. To require that a
240	person solve a simple CAPTCHA first, give that capability to the
241	"anonymous" user category instead.
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 a 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][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	We believe the [`msmtp`][msmtp] SMTP client is compatible with this
366	protocol if you give it the `-t` option. To our knowledge, this remains
367	untested, but if it works, this would be a useful option on a server
368	hosting a Fossil repository which doesn't otherwise require a separate
369	SMTP server for other purposes.
370
371	It is probably also possible to configure [`procmail`][pmdoc] to work
372	with this protocol. If you know how to do it, a patch to this document
373	or a how-to on [the Fossil forum][ff] would be appreciated.
374
375	[ff]: https://fossil-scm.org/forum/
376	[msmtp]: https://marlam.de/msmtp/
377	[mta]: https://en.wikipedia.org/wiki/Message_transfer_agent
378	[pmdoc]: http://pm-doc.sourceforge.net/doc/
379	[rfc822]: https://www.w3.org/Protocols/rfc822/
380
381
382	<a id="db"></a>
383	### Method 2: Store in a Database
384
385	The self-hosting Fossil repository at <https://www.fossil-scm.org/>
386	currently uses this method rather than [the pipe method](#pipe) because
387	it is running inside of a restrictive [chroot jail][cj] which is unable
388	to hand off messages to the local MTA directly.
389
390	When you configure a Fossil server this way, it adds outgoing email
391	messages to a SQLite database file. A separate daemon process can then
392	extract those messages for further disposition.
393
394	Fossil includes a copy of [the daemon](/file/tools/email-sender.tcl)
395	used on `fossil-scm.org`: it is just a short Tcl script that
396	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][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 Fossi 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	This screen also allows a Fossil Admin user to perform other activities
522	on behalf of a subscriber which they could do themselves, such as to
523	[unsubscribe](#unsub) them.
524
525
526	<a id="backup"></a>
527	## Cloning, Syncing, and Backups
528
529	The Admin → Notification settings are not replicated using clone or
530	sync, and it is not possible to push such settings from one repository
531	to another. In a network of peer repositories, you only want one
532	repository sending email alerts. If you were to replicate the email
533	alert settings to a separate repository, then subscribers would get
534	multiple alerts for each event, which would be bad.
535
536	However, the subscriber list can be synced for backup purposes. Use the
537	[`fossil config pull subscriber`](/help?cmd=configuration) command to
538	pull the latest subscriber list from a server into a backup repository.
539
540	The `push`, `export`, and `import` commands all work similarly.
541
542
543	<a id="pages" name="commands"></a>
544	## Controlling the Email Alert System
545
546	This section collects the list of Fossil UI pages and CLI commands that
547	control the email alert system, some of which have not been mentioned so
548	far:
549
550	Commands:
551
552	* The [`alerts`](/help?cmd=alerts) command
553	* The [`test-alert`](/help?cmd=test-alert) command
554	* The [`test-add-alerts`](/help?cmd=test-add-alerts) command
555
556	Web pages available to users and subscribers:
557
558	* The [`/subscribe`](/help?cmd=/subscribe) page
559	* The [`/alerts`](/help?cmd=/alerts) page
560	* The [`/unsubscribe`](/help?cmd=/unsubscribe) page
561	* The [`/contact_admin`](/help?cmd=/contact_admin) page
562
563	Administrator-only web pages:
564
565	* The [`/setup_notification`](/help?cmd=/setup_notification) page
566	* The [`/subscribers`](/help?cmd=/subscribers) page
567
568
569	<a id="design"></a>
570	## Design of Email Alerts
571
572	This section describes the low-level design of the email alert system in
573	Fossil. This expands on the high-level administion focused material
574	above with minimal repetition.
575
576	This section assumes expert-level systems knowledge. If the material
577	above sufficed for your purposes, feel free to skip this section, which
578	runs to the end of this document.
579
580
581	<a id="datades"></a>
582	### Data Design
583
584	There are three new tables in the repository database, starting with
585	Fossil 2.7. These tables are not created in new repositories by
586	default. The tables only come into existence as needed when email
587	alerts are configured and used.
588
589
590	* <b>SUBSCRIBER</b> →
591	The subscriber table records the email address for people who
592	want to receive email notifications. Each subscriber has a
593	`subscriberCode` which is a random 32-byte blob that uniquely
594	identifies the subscriber. There are also fields to indicate
595	what kinds of notifications the subscriber wishes to receive,
596	whether or not the email address of the subscriber has been
597	verified, etc.
598
599	* <b>PENDING\_ALERT</b> →
600	The PENDING\_ALERT table contains records that define events
601	about which alert emails might need to be sent.
602	A pending\_alert always refers to an entry in the
603	EVENT table. The EVENT table is part of the standard schema
604	and records timeline entries. In other words, there is one
605	row in the EVENT table for each possible timeline entry. The
606	PENDING\_ALERT table refers to EVENT table entries for which
607	we might need to send alert emails.
608
609	* <b>EMAIL\_BOUNCE</b> →
610	This table is intended to record email bounce history so that
611	subscribers with excessive bounces can be turned off. That
612	logic has not yet been implemented so the EMAIL\_BOUNCE table
613	is currently unused.
614
615	As pointed out above, ["subscribers" are distinct from "users"](#uvs).
616	The SUBSCRIBER.SUNAME field is the optional linkage between users and
617	subscribers.
618
619
620	<a id="stdout"></a>
621	### The "stdout" Method
622
623	The [list of mail sending methods](#advanced) above left out an
624	internal-only method called "stdout" which simply writes the text of the
625	email message on standard output. The "stdout" method is used for
626	testing and debugging. If you need something similar and can't modify
627	your local Fossil instance to use this method, you might temporarily
628	switch to [the "dir" method](#dir) instead.
629
630
631	<a id="msgfmt"></a>
632	### Message Format
633
634	The email messages generated by Fossil have a [well-formed
635	header][rfc822]. The downstream processing is expected to extract the
636	"To:", "From:", "Subject:" and whatever other attributes it needs from
637	the email header text.
638
639	These emails use the `text/plain` MIME type with the UTF-8 character
640	set. We currently use a transfer encoding of `quoted-printable`, but
641	there is commented-out code in Fossil to switch to `base64` encoding,
642	which Fossil used in the early days leading up to the 2.7 release.
643
644	If you switch Fossil back to `base64` mode, you may want to build a
645	utility program that ships in the Fossil source tree named
646	["tools/decode-email.c"](/file/tools/decode-email.c) which can decode
647	these messages into a human-readable format.
648
649
650	<a id="inbound" name="bounces"></a>
651	### Dealing with Inbound Email
652
653	Inbound email messages — for example, bounces from failed alert emails —
654	should be relayed to the `fossil email inbound` command. That command
655	is currently a no-op place-holder. At some point, we will need to
656	design and write a bounce-message processing system for Fossil.
657
658
659	<a id="password" name="scode" name="verification"></a>
660	### Passwords vs Subscriber Codes
661
662	When anonymous passers-by on the Internet sign up for email alerts,
663	their email address must first be verified. An email message is sent to
664	the address supplied inviting the user to click on a link. The link
665	includes a pseudorandom 128-bit blob encoded as 32 hexadecimal digits,
666	which serves in place of a password for that email address. (This is
667	stored in the database as `subscriber.subscriberCode`.) If anyone visits
668	the link, the email address is verified.
669
670	Knowledge of the `subscriberCode` is sufficient to control a
671	subscription.
672
673	Because this code is included in plain text in email alert messages, it
674	is not as secure as a separate password, but it has several virtues:
675
676	* It is easier for the average subscriber to deal with in that they
677	don't have to come up with yet another password and store it safely.
678
679	* If the `subscriberCode` is stolen, the worst that can happen is that
680	the thief can change that email address's subscription settings.
681	Contrast a password which may be shared with other services, which
682	then compromises those other services.
683
684	* No PII other than the subscriber's email address is available to an
685	attacker with the `subscriberCode`. Nor can knowledge of the
686	`subscriberCode` lead to a email flood or other annoyance attack, as
687	far as I can see.
688
689	If the `subscriberCodes` for a Fossil repository are ever compromised,
690	new ones can be generated as follows:
691
692	UPDATE subscriber SET subscriberCode=randomblob(32);
693
694	Since this then affects all new email alerts going out from Fossil, your
695	end users may never even realize that they're getting new codes, as long
696	as they don't click on the URLs in the footer of old alert messages.
697
698	With that in mind, a Fossil server administrator could choose to
699	randomize the `subscriberCodes` periodically, such as just before the
700	daily digest emails are sent out each day.
701
702	Important: All of the above is distinct from the passwords for users
703	with a Fossil repository login. Such users also have subscriber codes,
704	but those codes can only be used to modify the user's email alert
705	settings. That code cannot allow a user to log into the user's Fossil
706	repository account.
707
708
709	<a id="processing"></a>
710	### Internal Processing Flow
711
712	Almost all of the email alert code is found in the
713	[`src/alerts.c`](/file/src/alerts.c) source file.
714
715	When email alerts are enabled, a trigger is created in the schema
716	(`email_trigger1`) that adds a new entry to the `PENDING_ALERT` table
717	every time a row is added to the `EVENT` table. During a `fossil
718	rebuild`, the `EVENT` table is rebuilt from scratch; since we do not
719	want users to get alerts for every historical check-in, the trigger is
720	disabled during `rebuild`.
721
722	Email alerts are sent out by the `alert_send_alerts()` function, which
723	is normally called automatically due to the `email-autoexec` setting,
724	which defaults to enabled. If that setting is disabled or if the user
725	simply wants to force email alerts to be sent immediately, they can give
726	a `fossil alert send` command, such as via a `cron` script. Each time
727	this function is called, the alert messages are moved further down the
728	chain, so you cannot cause duplicate alerts by calling it too often.
729
730	Digests are handled by recording the time of the last digest in the
731	`email-last-digest` setting, and only sending a new digest if the
732	current time is one day or later after the last digest.
733
734	Individual emails are sent to each subscriber. I (drh) ran tests and
735	found that I could send about 1200 emails/second, which is fast enough
736	that I do not need to resort to trying to notify multiple subscribers
737	with a single email. Because each subscriber gets a separate email, the
738	system can include information in the email that is unique to the
739	subscriber, such as a link to the page to edit their subscription. That
740	link includes the `subscriberCode`.
741
742	ELETED www/emaildesign.md

D www/emaildesign.md

-215

		--- a/www/emaildesign.md
		+++ b/www/emaildesign.md
		@@ -1,223 +0,0 @@
1		-Design of Email Notification
2		-============================
3		-
4		-This document contains high-level design notes for the email
5		-notification system in Fossil. Use this document to get a better
6		-understanding of how Fossil handles email notification, to help
7		-with doing custom configurations, or to help contribute features.
8		-
9		-This document assumes expert-level systems knowledge. A separate
10		-tutorial for setting up email notification by non-experts will be
11		-generated once the email notification system stabilizes.
12		-
13		-Email notification is under active development as of this writing
14		-(2018-06-25). Check back frequently for updates.
15		-
16		-Data Design
		------------
17		-
18		-There are three new tables in the repository database. These tables
19		-are not created in new repositories by default. The tables only
20		-come into existance if email notification is configured and used.
21		-
22		-
23		- * <b>SUBSCRIBER</b> →
24		- The subscriber table records the email address for people who
25		- want to receive email notifications. Each subscriber has a
26		- `subscriberCode` which is a random 32-byte blob that uniquely
27		- identifies the subscriber. There are also fields to indicate
28		- what kinds of notifications the subscriber wishes to receive,
29		- whether or not the email address of the subscriber has been
30		- verified, etc.
31		-
32		- * <b>PENDING\_ALERT</b> →
33		- The PENDING\_ALERT table contains records that define events
34		- about which notification emails might need to be sent.
35		- A pending\_alert always refers to an entry in the
36		- EVENT table. The EVENT table is part of the standard schema
37		- and records timeline entries. In other words, there is one
38		- row in the EVENT table for each possible timeline entry. The
39		- PENDING\_ALERT table refers to EVENT table entries for which
40		- we might need to send notification emails.
41		-
42		- * <b>EMAIL\_BOUNCE</b> →
43		- This table is intended to record email bounce history so that
44		- subscribers with excessive bounces can be turned off. That
45		- logic has not yet been implemented so the EMAIL\_BOUNCE table
46		- is currently unused.
47		-
48		-Note that "subscribers" are distinct from "users" in the USER table.
49		-A "user" is someone who has a login and password. A "subscriber" is
50		-an email address that receives notification events. Users can be
51		-subscribers, and there is a SUBSCRIBER.SUNAME field that records
52		-the linkage between users and subscribers. But it is also possible
53		-to be a user without being a subscriber, or to be a subscriber without
54		-being a user.
55		-
56		-Sending Email Messages
		-----------------------
57		-
58		-Fossil expects to interact with an external [mail transfer agent][MTA].
59		-There are currently three different methods for sending outbound
60		-email messages from Fossil to the external mail agent:
61		-
62		- 1. <b>"pipe"</b> → Invoke an external command that accepts
63		- the email message on standard input. This is useful if the
64		- host computer has a command like /usr/sbin/sendmail that will
65		- accept well-formed email messages from standard input and forward
66		- them to the appropriate destination.
67		-
68		- 2. <b>"db"</b> → Write outgoing email messages into an
69		- SQLite database file. The self-hosting Fossil website uses
70		- this technique because Fossil runs inside a reduced-privilege
71		- chroot jail and cannot invoke commands like /usr/sbin/sendmail.
72		- A separate TCL script running outside of the jail monitors
73		- the email queue database and forwards email messages to the
74		- Postfix mail transfer agent. There is an example TCL script in the
75		- [tools/email-sender.tcl](/file/tools/email-sender.tcl) file
76		- of the source tree that shows how this is done.
77		-
78		- 3. <b>"dir"</b> → Write outgoing email messages as individual
79		- files in a designated directory. This might be useful for
80		- testing and debugging.
81		-
82		-Internally, there is a fourth email sending method named "stdout"
83		-which simply writes the text of the email message on standard output.
84		-The "stdout" method is used for testing and debugging.
85		-
86		-Perhaps we will add an "smtp" sending method in the future. The
87		-main problem with an "smtp" delivery method is that front-line Fossil
88		-running inside the privilege jail would need to deal with all kinds
89		-of errors from SMTP, such as unable to connect, or connection resets,
90		-etc. SMTP expects the sender to have the ability to retry, does it
91		-not?
92		-
93		-The emails transmitted have a well-formed header. The downstream
94		-processing is expected to extract the "To:", "From:", "Subject:" and
95		-whatever other attributes it needs from the email header text.
96		-
97		-All emails are text/plain and use a transfer-encoding of base64.
98		-
99		-There is a utility command-line program named
100		-["tools/decode-email.c"](/file/tools/decode-email.c) in
101		-the Fossil source tree. If you compile this program, you can use it
102		-to convert the base64 transfer-encoding into human-readable output for
103		-testing and debugging.
104		-
105		-[MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent
106		-
107		-
108		-Receiving Email Messages
		-------------------------
109		-
110		-Inbound email messages (for example bounces from failed notification
111		-emails) should be relayed to the "fossil email inbound" command. That
112		-command is currently a no-op place-holder. At some point, we will need
113		-to design and write a bounce-message processing system for Fossil.
114		-
115		-Controlling The Setup
		----------------------
116		-
117		-Commands:
118		-
119		- * The [email](/help?cmd=email) command
120		-
121		-Web pages:
122		-
123		- * The [/subscribe](/help?cmd=/subscribe) page
124		- * The [/alerts](/help?cmd=/alerts) page
125		- * The [/unsubscribe](/help?cmd=/unsubscribe) page
126		- * The [/msgtoadmin](/help?cmd=/msgtoadmin) page
127		-
128		-Web pages for administrators only:
129		-
130		- * The [/setup_email](/help?cmd=/setup_email) page
131		- * The [/subscribers](/help?cmd=/subscribers) page
132		-
133		-Test command:
134		-
135		- * The [test-alert](/help?cmd=test-alert) command
136		- * The [test-add-alerts](/help?cmd=test-add-alerts) command
137		-
138		-Email Address Verification
		---------------------------
139		-
140		-When anonymous passers-by on the internet sign up for email notifications,
141		-their email address must first be verified. An email message is sent to
142		-the address supplied inviting the user to click on a link. The link includes
143		-the random 32-byte `subscriberCode` in hex. If anyone visits the link, the
144		-email address is verified.
145		-
146		-There is no password. Knowledge of the `subscriberCode` is sufficient to
147		-control the subscription. This is not a secure as a separate password,
148		-but on the other hand it is easier for the average subscriber to deal
149		-with in that they don't have to come up with yet another password. Also,
150		-even if the `subscriberCode` is stolen, the worst that can happens is that
151		-the thief can change your subscription settings. No PII (other than
152		-the subscriber's email address) is available to an attacker with the
153		-`subscriberCode`. Nor can knowledge of the `subscriberCode` lead to a
154		-email flood or other annoyance attack, as far as I can see.
155		-
156		-If subscriberCodes are ever compromised, new ones can be generated
157		-as follows:
158		-
159		- UPDATE subscriber SET subscriberCode=randomblob(32);
160		-
161		-Perhaps the system be enhanced to randomize the
162		-`subscriberCodes` periodically - say just before each daily digest
163		-is sent out?
164		-
165		-User Control Of Their Subscription
		-----------------------------------
166		-
167		-If a user has a separate account with a login and password for
168		-the repository, then their subscription is linked to their account.
169		-On the /login page is a link to a page to control their subscription.
170		-
171		-For users without logins, they can request a link to a page for
172		-controling their subscription on the `/alerts` or `/unsubscribe` page.
173		-The link is sent via email, and includes the `subscriberCode`.
174		-
175		-Internal Processing Flow
		-------------------------
176		-
177		-Almost all of the email notification code is found in the `src/email.c`
178		-source file.
179		-
180		-When email notifications are enabled, a trigger is created in the schema
181		-(the `email_trigger1` trigger) that adds a new entry to the
182		-`PENDING_ALERT` table every time a row is added to the `EVENT` table.
183		-During a `fossil rebuild`, the `EVENT` table is rebuilt from scratch; since we
184		-do not want users to get notifications for every historical check-in,
185		-the trigger is disabled during `rebuild`.
186		-
187		-Email notifications are sent out by the `email_send_alerts()` function.
188		-This function is can be called by having a cron job invoke the
189		-`fossil email exec` command. Or, if the email-autoexec setting is
190		-enabled, then `email_send_alerts()` is invoked automatically after each
191		-successful webpage is generated. The latter approach is used on the
192		-Fossil self-hosting repository. The `email_send_alerts()` function is
193		-a no-op (obviously) if there are no pending events to be sent.
194		-
195		-Digests are handled by recording the time of the last digest in the
196		-`email-last-digest` setting, and only sending a new digest if the
197		-current time is one day or later after the last digest.
198		-
199		-Individual emails are sent to each subscriber. I ran tests and found
200		-that I could send about 1200 emails/second, which is fast enough that
201		-I do not need to resort to trying to notify multiple subscribers with
202		-a single email. Because each subscriber gets a separate email, the
203		-system can include information in the email that is unique to the
204		-subscriber, such as a link to the page to edit their subscription. That
205		-link includes the `subscriberCode`.,
206		-
207		-Other Notes
		------------
208		-
209		-The `fossil configuration pull subscriber` command pulls down the content
210		-of the `SUBSCRIBER` table. This is intended to as a backup-only. It
211		-is not desirable to have two or more systems sending emails to the
212		-same people for the same repository, as that would mean users would
213		-receive duplicate emails. Hence, the settings that control email
214		-notifications are not transmitted with the pull. The `push`, `export`,
215		-and `import` commands all work similarly.

	--- a/www/emaildesign.md
	+++ b/www/emaildesign.md
	@@ -1,223 +0,0 @@
1	Design of Email Notification
2	============================
3
4	This document contains high-level design notes for the email
5	notification system in Fossil. Use this document to get a better
6	understanding of how Fossil handles email notification, to help
7	with doing custom configurations, or to help contribute features.
8
9	This document assumes expert-level systems knowledge. A separate
10	tutorial for setting up email notification by non-experts will be
11	generated once the email notification system stabilizes.
12
13	Email notification is under active development as of this writing
14	(2018-06-25). Check back frequently for updates.
15
16	Data Design
	------------
17
18	There are three new tables in the repository database. These tables
19	are not created in new repositories by default. The tables only
20	come into existance if email notification is configured and used.
21
22
23	* <b>SUBSCRIBER</b> →
24	The subscriber table records the email address for people who
25	want to receive email notifications. Each subscriber has a
26	`subscriberCode` which is a random 32-byte blob that uniquely
27	identifies the subscriber. There are also fields to indicate
28	what kinds of notifications the subscriber wishes to receive,
29	whether or not the email address of the subscriber has been
30	verified, etc.
31
32	* <b>PENDING\_ALERT</b> →
33	The PENDING\_ALERT table contains records that define events
34	about which notification emails might need to be sent.
35	A pending\_alert always refers to an entry in the
36	EVENT table. The EVENT table is part of the standard schema
37	and records timeline entries. In other words, there is one
38	row in the EVENT table for each possible timeline entry. The
39	PENDING\_ALERT table refers to EVENT table entries for which
40	we might need to send notification emails.
41
42	* <b>EMAIL\_BOUNCE</b> →
43	This table is intended to record email bounce history so that
44	subscribers with excessive bounces can be turned off. That
45	logic has not yet been implemented so the EMAIL\_BOUNCE table
46	is currently unused.
47
48	Note that "subscribers" are distinct from "users" in the USER table.
49	A "user" is someone who has a login and password. A "subscriber" is
50	an email address that receives notification events. Users can be
51	subscribers, and there is a SUBSCRIBER.SUNAME field that records
52	the linkage between users and subscribers. But it is also possible
53	to be a user without being a subscriber, or to be a subscriber without
54	being a user.
55
56	Sending Email Messages
	-----------------------
57
58	Fossil expects to interact with an external [mail transfer agent][MTA].
59	There are currently three different methods for sending outbound
60	email messages from Fossil to the external mail agent:
61
62	1. <b>"pipe"</b> → Invoke an external command that accepts
63	the email message on standard input. This is useful if the
64	host computer has a command like /usr/sbin/sendmail that will
65	accept well-formed email messages from standard input and forward
66	them to the appropriate destination.
67
68	2. <b>"db"</b> → Write outgoing email messages into an
69	SQLite database file. The self-hosting Fossil website uses
70	this technique because Fossil runs inside a reduced-privilege
71	chroot jail and cannot invoke commands like /usr/sbin/sendmail.
72	A separate TCL script running outside of the jail monitors
73	the email queue database and forwards email messages to the
74	Postfix mail transfer agent. There is an example TCL script in the
75	[tools/email-sender.tcl](/file/tools/email-sender.tcl) file
76	of the source tree that shows how this is done.
77
78	3. <b>"dir"</b> → Write outgoing email messages as individual
79	files in a designated directory. This might be useful for
80	testing and debugging.
81
82	Internally, there is a fourth email sending method named "stdout"
83	which simply writes the text of the email message on standard output.
84	The "stdout" method is used for testing and debugging.
85
86	Perhaps we will add an "smtp" sending method in the future. The
87	main problem with an "smtp" delivery method is that front-line Fossil
88	running inside the privilege jail would need to deal with all kinds
89	of errors from SMTP, such as unable to connect, or connection resets,
90	etc. SMTP expects the sender to have the ability to retry, does it
91	not?
92
93	The emails transmitted have a well-formed header. The downstream
94	processing is expected to extract the "To:", "From:", "Subject:" and
95	whatever other attributes it needs from the email header text.
96
97	All emails are text/plain and use a transfer-encoding of base64.
98
99	There is a utility command-line program named
100	["tools/decode-email.c"](/file/tools/decode-email.c) in
101	the Fossil source tree. If you compile this program, you can use it
102	to convert the base64 transfer-encoding into human-readable output for
103	testing and debugging.
104
105	[MTA]: https://en.wikipedia.org/wiki/Message_transfer_agent
106
107
108	Receiving Email Messages
	-------------------------
109
110	Inbound email messages (for example bounces from failed notification
111	emails) should be relayed to the "fossil email inbound" command. That
112	command is currently a no-op place-holder. At some point, we will need
113	to design and write a bounce-message processing system for Fossil.
114
115	Controlling The Setup
	----------------------
116
117	Commands:
118
119	* The [email](/help?cmd=email) command
120
121	Web pages:
122
123	* The [/subscribe](/help?cmd=/subscribe) page
124	* The [/alerts](/help?cmd=/alerts) page
125	* The [/unsubscribe](/help?cmd=/unsubscribe) page
126	* The [/msgtoadmin](/help?cmd=/msgtoadmin) page
127
128	Web pages for administrators only:
129
130	* The [/setup_email](/help?cmd=/setup_email) page
131	* The [/subscribers](/help?cmd=/subscribers) page
132
133	Test command:
134
135	* The [test-alert](/help?cmd=test-alert) command
136	* The [test-add-alerts](/help?cmd=test-add-alerts) command
137
138	Email Address Verification
	---------------------------
139
140	When anonymous passers-by on the internet sign up for email notifications,
141	their email address must first be verified. An email message is sent to
142	the address supplied inviting the user to click on a link. The link includes
143	the random 32-byte `subscriberCode` in hex. If anyone visits the link, the
144	email address is verified.
145
146	There is no password. Knowledge of the `subscriberCode` is sufficient to
147	control the subscription. This is not a secure as a separate password,
148	but on the other hand it is easier for the average subscriber to deal
149	with in that they don't have to come up with yet another password. Also,
150	even if the `subscriberCode` is stolen, the worst that can happens is that
151	the thief can change your subscription settings. No PII (other than
152	the subscriber's email address) is available to an attacker with the
153	`subscriberCode`. Nor can knowledge of the `subscriberCode` lead to a
154	email flood or other annoyance attack, as far as I can see.
155
156	If subscriberCodes are ever compromised, new ones can be generated
157	as follows:
158
159	UPDATE subscriber SET subscriberCode=randomblob(32);
160
161	Perhaps the system be enhanced to randomize the
162	`subscriberCodes` periodically - say just before each daily digest
163	is sent out?
164
165	User Control Of Their Subscription
	-----------------------------------
166
167	If a user has a separate account with a login and password for
168	the repository, then their subscription is linked to their account.
169	On the /login page is a link to a page to control their subscription.
170
171	For users without logins, they can request a link to a page for
172	controling their subscription on the `/alerts` or `/unsubscribe` page.
173	The link is sent via email, and includes the `subscriberCode`.
174
175	Internal Processing Flow
	-------------------------
176
177	Almost all of the email notification code is found in the `src/email.c`
178	source file.
179
180	When email notifications are enabled, a trigger is created in the schema
181	(the `email_trigger1` trigger) that adds a new entry to the
182	`PENDING_ALERT` table every time a row is added to the `EVENT` table.
183	During a `fossil rebuild`, the `EVENT` table is rebuilt from scratch; since we
184	do not want users to get notifications for every historical check-in,
185	the trigger is disabled during `rebuild`.
186
187	Email notifications are sent out by the `email_send_alerts()` function.
188	This function is can be called by having a cron job invoke the
189	`fossil email exec` command. Or, if the email-autoexec setting is
190	enabled, then `email_send_alerts()` is invoked automatically after each
191	successful webpage is generated. The latter approach is used on the
192	Fossil self-hosting repository. The `email_send_alerts()` function is
193	a no-op (obviously) if there are no pending events to be sent.
194
195	Digests are handled by recording the time of the last digest in the
196	`email-last-digest` setting, and only sending a new digest if the
197	current time is one day or later after the last digest.
198
199	Individual emails are sent to each subscriber. I ran tests and found
200	that I could send about 1200 emails/second, which is fast enough that
201	I do not need to resort to trying to notify multiple subscribers with
202	a single email. Because each subscriber gets a separate email, the
203	system can include information in the email that is unique to the
204	subscriber, such as a link to the page to edit their subscription. That
205	link includes the `subscriberCode`.,
206
207	Other Notes
	------------
208
209	The `fossil configuration pull subscriber` command pulls down the content
210	of the `SUBSCRIBER` table. This is intended to as a backup-only. It
211	is not desirable to have two or more systems sending emails to the
212	same people for the same repository, as that would mean users would
213	receive duplicate emails. Hence, the settings that control email
214	notifications are not transmitted with the pull. The `push`, `export`,
215	and `import` commands all work similarly.

	--- a/www/emaildesign.md
	+++ b/www/emaildesign.md
	@@ -1,223 +0,0 @@
















	------------








































	-----------------------




















































	-------------------------







	----------------------























	---------------------------



























	-----------------------------------










	-------------------------
































	------------

M www/forum.wiki

+57 -218

		--- www/forum.wiki
		+++ www/forum.wiki
		@@ -97,30 +97,16 @@
97	97	formatting features give you a middle path, providing your users
98	98	enough formatting power to communicate complex ideas well without
99	99	providing so much power as to risk
100	100	[https://wonko.com/post/html-escaping \| security problems].
101	101
102		- * <b>Easy Notification Emails:</b> It is easy to configure Fossil to
103		- send email notifications of new posts to interested forum users via
104		- your Fossil server's existing
105		- [https://en.wikipedia.org/wiki/Message_transfer_agent \| message
106		- transfer agent] (MTA): Postfix, Exim, Sendmail... Notification
107		- emails include the complete message content for the benefit of
108		- those that prefer to visit the forum only when they need to post
109		- something. Notifications are optional, and each user gets the
110		- choice of immediate or daily digest delivery.
111		-
112		- * <b>Talks to Everyone:</b> Because Fossil delegates email handling
113		- to your existing MTA, it does not need to implement the
114		- [http://sqlite.1065341.n5.nabble.com/Many-ML-emails-going-to-GMail-s-SPAM-tp98685p98722.html
115		- \| roughly two dozen]
116		- [https://en.wikipedia.org/wiki/Request_for_Comments \| RFCs]
117		- required in order to properly support SMTP email in this complex
118		- world we've built. As well, this design choice means you do not
119		- need to do duplicate configuration, such as to point Fossil at your
120		- server's TLS certificate private key in order to support users
121		- behind mail servers that require STARTTLS encryption.
	102	+ * <b>Easy Email Alerts:</b> You can configure Fossil to
	103	+ [./alerts.md \| send email alerts]. Forum post emails include the
	104	+ complete message content for the benefit of those that prefer to
	105	+ visit the forum only when they need to post something. Alerts are
	106	+ optional, and each user gets the choice of immediate or daily
	107	+ digest delivery.
122	108
123	109
124	110	<h2 id="setup">Setting up a Fossil Forum</h2>
125	111
126	112	<h3 id="caps">Capabilities</h3>
		@@ -150,11 +136,11 @@
150	136	* <b>Supervise Forum</b> (<tt>6</tt>): User can grant or revoke
151	137	<b>WriteTrusted</b> capability for other users. (Currently
152	138	unimplemented.)
153	139
154	140	* <b>Email Alerts</b> (<tt>7</tt>): User can sign themselves up for
155		- email notifications, a.k.a. alerts.
	141	+ email alerts, a.k.a. notifications.
156	142
157	143	By default, no Fossil user has permission to use the forums except for
158	144	users with Setup and Admin capabilities, which get these as part of the
159	145	large package of other capabilities they get.
160	146
		@@ -173,14 +159,14 @@
173	159	the WriteTrusted capability (4) to users in the <tt>developer</tt>
174	160	category. If you did not give the Read Forum capability (2) to
175	161	<tt>anonymous</tt> above, you should give <tt>developer</tt> that
176	162	capability here if you choose to give it capability 3 or 4.
177	163
178		-If you want to use the email notification feature, by default only those
	164	+If you want to use the email alert feature, by default only those
179	165	users in the Setup and Admin user categories can make use of it. Grant
180	166	the Email Alerts capability (7) to give others access to this feature.
181		-Alternately, you can handle notification signups outside of Fossil, with
	167	+Alternately, you can handle alert signups outside of Fossil, with
182	168	a Setup or Admin users manually signing users up via Admin →
183	169	Notification. You'll want to grant this capability to the
184	170	<tt>nobody</tt> user category if you want anyone to sign up without any
185	171	restrictions. Give it to <tt>anonymous</tt> instead if you want the
186	172	user to solve a simple CAPTCHA before signing up. Or, give it to
		@@ -219,17 +205,17 @@
219	205
220	206	The first thing is that you'll need to add something like the following
221	207	to the Header part of the skin to create the navbar link:
222	208
223	209	<verbatim>
224		- if {[anycap 234567] \|\| [anoncap 2] \|\| [anoncap 3]} {
	210	+ if {[anycap 23456] \|\| [anoncap 2] \|\| [anoncap 3]} {,
225	211	menulink /forum Forum
226	212	}
227	213	</verbatim>
228	214
229	215	These rules say that any logged-in user with any forum-related
230		-capability (2-7 inclusive, as of this writing) or an anonymous user with
	216	+capability (2-6 inclusive, as of this writing) or an anonymous user with
231	217	read or write capability on the forum (2, 3) will see the "Forum" navbar
232	218	link, which just takes you to <tt>/forum</tt>.
233	219
234	220	The exact code you need here varies depending on which skin you're
235	221	using. Follow the style you see for the other navbar links.
		@@ -323,207 +309,60 @@
323	309	has been a feature of Fossil since April of 2011: Admin →
324	310	Login-Group. This allows one Fossil repository to recognize users
325	311	authorized on a different Fossil repository.
326	312
327	313
328		-<h3 id="alerts">Email Notifications (Alerts)</h3>
	314	+<h3 id="alerts">Email Alerts (a.k.a. Notifications)</h3>
329	315
330		-The detailed information for this feature of Fossil is in two other
331		-documents:
332		-
333		- * [./alerts.md \| Email Alerts]
334		- * [./emaildesign.md \| Email Notification Design]
	316	+Internet email service has become rather complicated since its initial
	317	+simple and insecure implementation decades ago. Fossil's role in all of
	318	+this is rather small at the moment, but the details of the integration
	319	+are complex enough to justify [./alerts.md \| a separate document].
	320	+(Fossil's email alerts system also gets used by subsystems other than
	321	+the Fossil forum feature.)
335	322
336	323	You may want to study those in detail, since email is complicated. Some
337	324	of that complexity necessarily leaks out to the configuration of email
338		-notification in Fossil.
339		-
340		-
341		-<h4 id="quick">Quick Setup</h4>
342		-
343		-However, if you've already got a working Postfix, Exim, or Sendmail
344		-server on the machine running your Fossil instance(s), and you aren't
345		-using Fossil's <tt>chroot</tt> feature to wall it off from the rest of
346		-the machine, it's fairly simple to set up email notifications:
347		-
348		-<ol>
349		- <li>Go to Admin → Notification and fill out all of the
350		- <b>Required</b> fields:</li>
351		-
352		- <ul>
353		- <li><b>Canonical server URL</b> — Use the suggested URL</li>
354		- <li><b>"From" email address</b> — <tt>[email protected]</tt>
355		- is traditional, but do what you like</li>
356		- <li><b>Repository nickname</b> — See the suggested examples on
357		- the web page.</li>
358		- </ul>
359		-
360		- <li>Set "Email Send Method" to "Pipe to a command"</li>
361		-
362		- <li>Set the "Administrator email address" to a suitable email address.
363		- It could be the same value you used for the "From" address above,
364		- or it could be a different value like
365		- <tt>[email protected]</tt>.</li>
366		-</ol>
367		-
368		-Save your changes.
369		-
370		-<a id="cd"></a>For all of the following <tt>fossil</tt> CLI commands,
371		-we're going to assume that you've <tt>cd</tt>'d into a checkout
372		-directory for your repository on the central server. Otherwise, we'd
373		-need to add <tt>-R /path/to/repo.fossil</tt> to each of them.
374		-
375		-Give this command:
376		-
377		-<verbatim>
378		- $ fossil set email-send-command
379		-</verbatim>
380		-
381		-If that gives a blank value instead of <tt>sendmail -ti</tt>, say
382		-
383		-<verbatim>
384		- $ fossil set email-send-command "sendmail -ti"
385		-</verbatim>
386		-
387		-to force the setting. That's a
388		-[https://fossil-scm.org/forum/forumpost/840b676410 \| known bug] which
389		-should be squished soon.
390		-
391		-This is the correct command even if you're running Postfix or Exim
392		-rather than Sendmail. These mail servers (and perhaps others) provide a
393		-<tt>sendmail</tt> command for this very sort of reason: it lets programs
394		-send email without having to care exactly which server implementation is
395		-running at a given site.
396		-
397		-<a id="status"></a>If you reload the Email Notification Setup page, the
398		-Status section at the top should show:
399		-
400		-<verbatim>
401		- Outgoing Email: Piped to command "sendmail -ti"
402		- Pending Alerts: 0 normal, 0 digest
403		- Subscribers: 0 active, 0 total
404		-</verbatim>
405		-
406		-
407		-<h4 id="subscribe">Subscribe to Alerts</h4>
408		-
409		-Above, we see that there are no subscribers, so the next step is to add
410		-one.
411		-
412		-Go to the <tt>/alerts</tt> page on your Fossil instance and sign your
413		-regular Fossil user up for email alerts. (Alternate path: click the user
414		-name or login/logout link in the upper right corner, depending on the
415		-skin you're using, then go to "Email Alerts".) You will need "Forum
416		-Posts" checked at the least for the testing steps below.
417		-
418		-If you use the same user name and email address as you used for your
419		-normal user login, Fossil will simply tie your alert preferences to your
420		-login record, and the email address in your user's Contact Info field
421		-will be considered already-verified. Otherwise, Fossil will create an
422		-alert-only record, and you will have to verify the email address before
423		-Fossil will send notifications to it.
424		-
425		-This shows a key aspect of the way Fossil's email alerts system works,
426		-by the way: a user can be signed up for email alerts without having a
427		-full-fledged Fossil user account. Only when both user names are the same
428		-are the two records tied together under the hood.
429		-
430		-
431		-<h4 id="alert-test">Test the Email Subsystem</h4>
432		-
433		-If you'd rather not create an inane "testing" post in your Fossil
434		-instance just to force out an email alert, you can test the email
435		-subsystem separately from the rest of the Fossil email alerts system
436		-with the following command:
437		-
438		-<verbatim>
439		- $ fossil alerts test-message [email protected] --body README.md --subject Test
440		-</verbatim>
441		-
442		-That should send you an email with "Test" in the subject line and the
443		-contents of your project's <tt>README.md</tt> file in the body. If it
444		-works, the file's contents may be truncated. I'm uncertain whether
445		-that's due to an intentionally-small buffer size or if it's a bug.
446		-
447		-That command assumes that your project [./foss-cklist.wiki \| contains a
448		-readme file]. Of course it does. Why would it not?
449		-
450		-
451		-<h4 id="frist" name="first">First Post</h4>
452		-
453		-Since you've already edited the skin per [#skin \| the instructions
454		-above], you can click the "Forum" link in the navbar and create a new
455		-post. I suggest taking the time to compose a suitable introductory
456		-message especially for your project's forum, one which a new user would
457		-find helpful.
458		-
459		-Wait a few seconds, and you should receive a notification email with the
460		-post's subject and body text in the email.
461		-
462		-
463		-<h4 id="trouble">Troubleshooting</h4>
464		-
465		-If email alerts aren't working, there are several useful commands you
466		-can give to figure out why.
467		-
468		-(Be sure to [#cd \| <tt>cd</tt> into a repo checkout directory] first!)
469		-
470		-<verbatim>
471		- $ fossil alerts status
472		-</verbatim>
473		-
474		-This should give much the same information as you saw [#status \| above].
475		-One difference is that, since you've created a forum post, the
476		-<tt>pending-alerts</tt> value should only be zero if you did in fact get
477		-the requested email alert. If it's zero, check your mailer's spam
478		-folder. If it's nonzero, continue with these troubleshooting steps.
479		-
480		-<verbatim>
481		- $ fossil backoffice
482		-</verbatim>
483		-
484		-That forces Fossil to run its [./backoffice.md \| "back office" process].
485		-Its only purpose at the time of this writing is to push out alert
486		-emails, but it might do other things later. Sometimes it can get stuck
487		-and needs to be kicked. For that reason, you might want to set up a
488		-crontab entry to make sure it runs occasionally.
489		-
490		-<verbatim>
491		- $ fossil alerts send
492		-</verbatim>
493		-
494		-This should also kick off the backoffice processing, if there are any
495		-pending alerts to send out.
496		-
497		-<verbatim>
498		- $ fossil alert pending
499		-</verbatim>
500		-
501		-Show any pending alerts. The number of lines output here should equal
502		-the [#status \| status output above].
503		-
504		-<verbatim>
505		- $ fossil test-add-alerts f5900
506		- $ fossil alert send
507		-</verbatim>
508		-
509		-Manually create an email alert and push it out immediately.
510		-
511		-The <tt>f</tt> in the first command's final parameter means you're
512		-scheduling a "forum" alert. The integer is the ID of a forum post, which
513		-you can find by visiting <tt>/timeline?showid</tt> on your Fossil
514		-instance.
515		-
516		-The second command above is necessary because the
517		-<tt>test-add-alerts</tt> command doesn't kick off a backoffice run.
518		-
519		-<verbatim>
520		- $ fossil ale send
521		-</verbatim>
522		-
523		-This only does the same thing as the final command above, rather than
524		-send you an ale, as you might be hoping. Sorry.
	325	+alerts in Fossil.
	326	+
	327	+
	328	+<h2 id="access">Accessing the Forum</h2>
	329	+
	330	+There are many paths to a repository's Fossil forum:
	331	+
	332	+<ul>
	333	+ <li>
	334	+ <p>If you're using the default Fossil skin as shipped with Fossil
	335	+ 2.7 or one updated to include the changes since 2.6 or prior, there
	336	+ is a Forum button in the navbar which appears for users with any of
	337	+ the forum-related user capabilities: 2 through 6 inclusive for those
	338	+ with repository logins, or caps 2 and 3 for users without a user
	339	+ account but who have solved the Anonymous user CAPTCHA.</p>
	340	+
	341	+ <p>This button will not appear in the default skin for such users if
	342	+ their browser window is not greater than 1200 pixels wide. The
	343	+ Fossil admin can adjust this limit in the skin's CSS section, down
	344	+ near the bottom in the definition of the `wideonly` style.</p>
	345	+ </li>
	346	+
	347	+ <li>The other stock skins have this button in them as of 2.7 as well,
	348	+ without the screen width restriction, since the navbar in those skins
	349	+ wraps on narrow screens more gracefully than the default skin
	350	+ does.</li>
	351	+
	352	+ <li>Users who set up their Fossil repository under prior versions and
	353	+ who now have local skin changes they don't want to overwrite by
	354	+ reverting to the stock 2.7 version of the skin they chose to start
	355	+ with can easily [#skin \| edit their skin] to include these links.</li>
	356	+
	357	+ <li>A "Forum" link appears in the drop-down panel when you click the
	358	+ default skin's hamburger menu (☰) for any user with one or more
	359	+ of the capabilities listed above.</li>
	360	+
	361	+ <li>That same link also appears on the repository's `/sitemap` page,
	362	+ since it provides the content for the hamburger menu's panel.</li>
	363	+</ul>
525	364
526	365
527	366	<h2 id="moderation">How Moderation Works</h2>
528	367
529	368	In this section, we're going to call all of the following a "forum
530	369

	--- www/forum.wiki
	+++ www/forum.wiki
	@@ -97,30 +97,16 @@
97	formatting features give you a middle path, providing your users
98	enough formatting power to communicate complex ideas well without
99	providing so much power as to risk
100	[https://wonko.com/post/html-escaping \| security problems].
101
102	* <b>Easy Notification Emails:</b> It is easy to configure Fossil to
103	send email notifications of new posts to interested forum users via
104	your Fossil server's existing
105	[https://en.wikipedia.org/wiki/Message_transfer_agent \| message
106	transfer agent] (MTA): Postfix, Exim, Sendmail... Notification
107	emails include the complete message content for the benefit of
108	those that prefer to visit the forum only when they need to post
109	something. Notifications are optional, and each user gets the
110	choice of immediate or daily digest delivery.
111
112	* <b>Talks to Everyone:</b> Because Fossil delegates email handling
113	to your existing MTA, it does not need to implement the
114	[http://sqlite.1065341.n5.nabble.com/Many-ML-emails-going-to-GMail-s-SPAM-tp98685p98722.html
115	\| roughly two dozen]
116	[https://en.wikipedia.org/wiki/Request_for_Comments \| RFCs]
117	required in order to properly support SMTP email in this complex
118	world we've built. As well, this design choice means you do not
119	need to do duplicate configuration, such as to point Fossil at your
120	server's TLS certificate private key in order to support users
121	behind mail servers that require STARTTLS encryption.
122
123
124	<h2 id="setup">Setting up a Fossil Forum</h2>
125
126	<h3 id="caps">Capabilities</h3>
	@@ -150,11 +136,11 @@
150	* <b>Supervise Forum</b> (<tt>6</tt>): User can grant or revoke
151	<b>WriteTrusted</b> capability for other users. (Currently
152	unimplemented.)
153
154	* <b>Email Alerts</b> (<tt>7</tt>): User can sign themselves up for
155	email notifications, a.k.a. alerts.
156
157	By default, no Fossil user has permission to use the forums except for
158	users with Setup and Admin capabilities, which get these as part of the
159	large package of other capabilities they get.
160
	@@ -173,14 +159,14 @@
173	the WriteTrusted capability (4) to users in the <tt>developer</tt>
174	category. If you did not give the Read Forum capability (2) to
175	<tt>anonymous</tt> above, you should give <tt>developer</tt> that
176	capability here if you choose to give it capability 3 or 4.
177
178	If you want to use the email notification feature, by default only those
179	users in the Setup and Admin user categories can make use of it. Grant
180	the Email Alerts capability (7) to give others access to this feature.
181	Alternately, you can handle notification signups outside of Fossil, with
182	a Setup or Admin users manually signing users up via Admin →
183	Notification. You'll want to grant this capability to the
184	<tt>nobody</tt> user category if you want anyone to sign up without any
185	restrictions. Give it to <tt>anonymous</tt> instead if you want the
186	user to solve a simple CAPTCHA before signing up. Or, give it to
	@@ -219,17 +205,17 @@
219
220	The first thing is that you'll need to add something like the following
221	to the Header part of the skin to create the navbar link:
222
223	<verbatim>
224	if {[anycap 234567] \|\| [anoncap 2] \|\| [anoncap 3]} {
225	menulink /forum Forum
226	}
227	</verbatim>
228
229	These rules say that any logged-in user with any forum-related
230	capability (2-7 inclusive, as of this writing) or an anonymous user with
231	read or write capability on the forum (2, 3) will see the "Forum" navbar
232	link, which just takes you to <tt>/forum</tt>.
233
234	The exact code you need here varies depending on which skin you're
235	using. Follow the style you see for the other navbar links.
	@@ -323,207 +309,60 @@
323	has been a feature of Fossil since April of 2011: Admin →
324	Login-Group. This allows one Fossil repository to recognize users
325	authorized on a different Fossil repository.
326
327
328	<h3 id="alerts">Email Notifications (Alerts)</h3>
329
330	The detailed information for this feature of Fossil is in two other
331	documents:
332
333	* [./alerts.md \| Email Alerts]
334	* [./emaildesign.md \| Email Notification Design]

335
336	You may want to study those in detail, since email is complicated. Some
337	of that complexity necessarily leaks out to the configuration of email
338	notification in Fossil.
339
340
341	<h4 id="quick">Quick Setup</h4>
342
343	However, if you've already got a working Postfix, Exim, or Sendmail
344	server on the machine running your Fossil instance(s), and you aren't
345	using Fossil's <tt>chroot</tt> feature to wall it off from the rest of
346	the machine, it's fairly simple to set up email notifications:
347
348	<ol>
349	<li>Go to Admin → Notification and fill out all of the
350	<b>Required</b> fields:</li>
351
352	<ul>
353	<li><b>Canonical server URL</b> — Use the suggested URL</li>
354	<li><b>"From" email address</b> — <tt>[email protected]</tt>
355	is traditional, but do what you like</li>
356	<li><b>Repository nickname</b> — See the suggested examples on
357	the web page.</li>
358	</ul>
359
360	<li>Set "Email Send Method" to "Pipe to a command"</li>
361
362	<li>Set the "Administrator email address" to a suitable email address.
363	It could be the same value you used for the "From" address above,
364	or it could be a different value like
365	<tt>[email protected]</tt>.</li>
366	</ol>
367
368	Save your changes.
369
370	<a id="cd"></a>For all of the following <tt>fossil</tt> CLI commands,
371	we're going to assume that you've <tt>cd</tt>'d into a checkout
372	directory for your repository on the central server. Otherwise, we'd
373	need to add <tt>-R /path/to/repo.fossil</tt> to each of them.
374
375	Give this command:
376
377	<verbatim>
378	$ fossil set email-send-command
379	</verbatim>
380
381	If that gives a blank value instead of <tt>sendmail -ti</tt>, say
382
383	<verbatim>
384	$ fossil set email-send-command "sendmail -ti"
385	</verbatim>
386
387	to force the setting. That's a
388	[https://fossil-scm.org/forum/forumpost/840b676410 \| known bug] which
389	should be squished soon.
390
391	This is the correct command even if you're running Postfix or Exim
392	rather than Sendmail. These mail servers (and perhaps others) provide a
393	<tt>sendmail</tt> command for this very sort of reason: it lets programs
394	send email without having to care exactly which server implementation is
395	running at a given site.
396
397	<a id="status"></a>If you reload the Email Notification Setup page, the
398	Status section at the top should show:
399
400	<verbatim>
401	Outgoing Email: Piped to command "sendmail -ti"
402	Pending Alerts: 0 normal, 0 digest
403	Subscribers: 0 active, 0 total
404	</verbatim>
405
406
407	<h4 id="subscribe">Subscribe to Alerts</h4>
408
409	Above, we see that there are no subscribers, so the next step is to add
410	one.
411
412	Go to the <tt>/alerts</tt> page on your Fossil instance and sign your
413	regular Fossil user up for email alerts. (Alternate path: click the user
414	name or login/logout link in the upper right corner, depending on the
415	skin you're using, then go to "Email Alerts".) You will need "Forum
416	Posts" checked at the least for the testing steps below.
417
418	If you use the same user name and email address as you used for your
419	normal user login, Fossil will simply tie your alert preferences to your
420	login record, and the email address in your user's Contact Info field
421	will be considered already-verified. Otherwise, Fossil will create an
422	alert-only record, and you will have to verify the email address before
423	Fossil will send notifications to it.
424
425	This shows a key aspect of the way Fossil's email alerts system works,
426	by the way: a user can be signed up for email alerts without having a
427	full-fledged Fossil user account. Only when both user names are the same
428	are the two records tied together under the hood.
429
430
431	<h4 id="alert-test">Test the Email Subsystem</h4>
432
433	If you'd rather not create an inane "testing" post in your Fossil
434	instance just to force out an email alert, you can test the email
435	subsystem separately from the rest of the Fossil email alerts system
436	with the following command:
437
438	<verbatim>
439	$ fossil alerts test-message [email protected] --body README.md --subject Test
440	</verbatim>
441
442	That should send you an email with "Test" in the subject line and the
443	contents of your project's <tt>README.md</tt> file in the body. If it
444	works, the file's contents may be truncated. I'm uncertain whether
445	that's due to an intentionally-small buffer size or if it's a bug.
446
447	That command assumes that your project [./foss-cklist.wiki \| contains a
448	readme file]. Of course it does. Why would it not?
449
450
451	<h4 id="frist" name="first">First Post</h4>
452
453	Since you've already edited the skin per [#skin \| the instructions
454	above], you can click the "Forum" link in the navbar and create a new
455	post. I suggest taking the time to compose a suitable introductory
456	message especially for your project's forum, one which a new user would
457	find helpful.
458
459	Wait a few seconds, and you should receive a notification email with the
460	post's subject and body text in the email.
461
462
463	<h4 id="trouble">Troubleshooting</h4>
464
465	If email alerts aren't working, there are several useful commands you
466	can give to figure out why.
467
468	(Be sure to [#cd \| <tt>cd</tt> into a repo checkout directory] first!)
469
470	<verbatim>
471	$ fossil alerts status
472	</verbatim>
473
474	This should give much the same information as you saw [#status \| above].
475	One difference is that, since you've created a forum post, the
476	<tt>pending-alerts</tt> value should only be zero if you did in fact get
477	the requested email alert. If it's zero, check your mailer's spam
478	folder. If it's nonzero, continue with these troubleshooting steps.
479
480	<verbatim>
481	$ fossil backoffice
482	</verbatim>
483
484	That forces Fossil to run its [./backoffice.md \| "back office" process].
485	Its only purpose at the time of this writing is to push out alert
486	emails, but it might do other things later. Sometimes it can get stuck
487	and needs to be kicked. For that reason, you might want to set up a
488	crontab entry to make sure it runs occasionally.
489
490	<verbatim>
491	$ fossil alerts send
492	</verbatim>
493
494	This should also kick off the backoffice processing, if there are any
495	pending alerts to send out.
496
497	<verbatim>
498	$ fossil alert pending
499	</verbatim>
500
501	Show any pending alerts. The number of lines output here should equal
502	the [#status \| status output above].
503
504	<verbatim>
505	$ fossil test-add-alerts f5900
506	$ fossil alert send
507	</verbatim>
508
509	Manually create an email alert and push it out immediately.
510
511	The <tt>f</tt> in the first command's final parameter means you're
512	scheduling a "forum" alert. The integer is the ID of a forum post, which
513	you can find by visiting <tt>/timeline?showid</tt> on your Fossil
514	instance.
515
516	The second command above is necessary because the
517	<tt>test-add-alerts</tt> command doesn't kick off a backoffice run.
518
519	<verbatim>
520	$ fossil ale send
521	</verbatim>
522
523	This only does the same thing as the final command above, rather than
524	send you an ale, as you might be hoping. Sorry.
525
526
527	<h2 id="moderation">How Moderation Works</h2>
528
529	In this section, we're going to call all of the following a "forum
530

	--- www/forum.wiki
	+++ www/forum.wiki
	@@ -97,30 +97,16 @@
97	formatting features give you a middle path, providing your users
98	enough formatting power to communicate complex ideas well without
99	providing so much power as to risk
100	[https://wonko.com/post/html-escaping \| security problems].
101
102	* <b>Easy Email Alerts:</b> You can configure Fossil to
103	[./alerts.md \| send email alerts]. Forum post emails include the
104	complete message content for the benefit of those that prefer to
105	visit the forum only when they need to post something. Alerts are
106	optional, and each user gets the choice of immediate or daily
107	digest delivery.














108
109
110	<h2 id="setup">Setting up a Fossil Forum</h2>
111
112	<h3 id="caps">Capabilities</h3>
	@@ -150,11 +136,11 @@
136	* <b>Supervise Forum</b> (<tt>6</tt>): User can grant or revoke
137	<b>WriteTrusted</b> capability for other users. (Currently
138	unimplemented.)
139
140	* <b>Email Alerts</b> (<tt>7</tt>): User can sign themselves up for
141	email alerts, a.k.a. notifications.
142
143	By default, no Fossil user has permission to use the forums except for
144	users with Setup and Admin capabilities, which get these as part of the
145	large package of other capabilities they get.
146
	@@ -173,14 +159,14 @@
159	the WriteTrusted capability (4) to users in the <tt>developer</tt>
160	category. If you did not give the Read Forum capability (2) to
161	<tt>anonymous</tt> above, you should give <tt>developer</tt> that
162	capability here if you choose to give it capability 3 or 4.
163
164	If you want to use the email alert feature, by default only those
165	users in the Setup and Admin user categories can make use of it. Grant
166	the Email Alerts capability (7) to give others access to this feature.
167	Alternately, you can handle alert signups outside of Fossil, with
168	a Setup or Admin users manually signing users up via Admin →
169	Notification. You'll want to grant this capability to the
170	<tt>nobody</tt> user category if you want anyone to sign up without any
171	restrictions. Give it to <tt>anonymous</tt> instead if you want the
172	user to solve a simple CAPTCHA before signing up. Or, give it to
	@@ -219,17 +205,17 @@
205
206	The first thing is that you'll need to add something like the following
207	to the Header part of the skin to create the navbar link:
208
209	<verbatim>
210	if {[anycap 23456] \|\| [anoncap 2] \|\| [anoncap 3]} {,
211	menulink /forum Forum
212	}
213	</verbatim>
214
215	These rules say that any logged-in user with any forum-related
216	capability (2-6 inclusive, as of this writing) or an anonymous user with
217	read or write capability on the forum (2, 3) will see the "Forum" navbar
218	link, which just takes you to <tt>/forum</tt>.
219
220	The exact code you need here varies depending on which skin you're
221	using. Follow the style you see for the other navbar links.
	@@ -323,207 +309,60 @@
309	has been a feature of Fossil since April of 2011: Admin →
310	Login-Group. This allows one Fossil repository to recognize users
311	authorized on a different Fossil repository.
312
313
314	<h3 id="alerts">Email Alerts (a.k.a. Notifications)</h3>
315
316	Internet email service has become rather complicated since its initial
317	simple and insecure implementation decades ago. Fossil's role in all of
318	this is rather small at the moment, but the details of the integration
319	are complex enough to justify [./alerts.md \| a separate document].
320	(Fossil's email alerts system also gets used by subsystems other than
321	the Fossil forum feature.)
322
323	You may want to study those in detail, since email is complicated. Some
324	of that complexity necessarily leaks out to the configuration of email
325	alerts in Fossil.
326
327
328	<h2 id="access">Accessing the Forum</h2>
329
330	There are many paths to a repository's Fossil forum:
331
332	<ul>
333	<li>
334	<p>If you're using the default Fossil skin as shipped with Fossil
335	2.7 or one updated to include the changes since 2.6 or prior, there
336	is a Forum button in the navbar which appears for users with any of
337	the forum-related user capabilities: 2 through 6 inclusive for those
338	with repository logins, or caps 2 and 3 for users without a user
339	account but who have solved the Anonymous user CAPTCHA.</p>
340
341	<p>This button will not appear in the default skin for such users if
342	their browser window is not greater than 1200 pixels wide. The
343	Fossil admin can adjust this limit in the skin's CSS section, down
344	near the bottom in the definition of the `wideonly` style.</p>
345	</li>
346
347	<li>The other stock skins have this button in them as of 2.7 as well,
348	without the screen width restriction, since the navbar in those skins
349	wraps on narrow screens more gracefully than the default skin
350	does.</li>
351
352	<li>Users who set up their Fossil repository under prior versions and
353	who now have local skin changes they don't want to overwrite by
354	reverting to the stock 2.7 version of the skin they chose to start
355	with can easily [#skin \| edit their skin] to include these links.</li>
356
357	<li>A "Forum" link appears in the drop-down panel when you click the
358	default skin's hamburger menu (☰) for any user with one or more
359	of the capabilities listed above.</li>
360
361	<li>That same link also appears on the repository's `/sitemap` page,
362	since it provides the content for the hamburger menu's panel.</li>
363	</ul>




















































































































































364
365
366	<h2 id="moderation">How Moderation Works</h2>
367
368	In this section, we're going to call all of the following a "forum
369

M www/mkindex.tcl

+1 -1

		--- www/mkindex.tcl
		+++ www/mkindex.tcl
		@@ -9,11 +9,11 @@
9	9	set doclist {
10	10	aboutcgi.wiki {How CGI Works In Fossil}
11	11	aboutdownload.wiki {How The Download Page Works}
12	12	adding_code.wiki {Adding New Features To Fossil}
13	13	adding_code.wiki {Hacking Fossil}
14		- alerts.md {Email Alerts And Notification}
	14	+ alerts.md {Email Alerts And Notifications}
15	15	antibot.wiki {Defense against Spiders and Bots}
16	16	backoffice.md {The "Backoffice" mechanism of Fossil}
17	17	blame.wiki {The Annotate/Blame Algorithm Of Fossil}
18	18	branching.wiki {Branching, Forking, Merging, and Tagging}
19	19	bugtheory.wiki {Bug Tracking In Fossil}
20	20

	--- www/mkindex.tcl
	+++ www/mkindex.tcl
	@@ -9,11 +9,11 @@
9	set doclist {
10	aboutcgi.wiki {How CGI Works In Fossil}
11	aboutdownload.wiki {How The Download Page Works}
12	adding_code.wiki {Adding New Features To Fossil}
13	adding_code.wiki {Hacking Fossil}
14	alerts.md {Email Alerts And Notification}
15	antibot.wiki {Defense against Spiders and Bots}
16	backoffice.md {The "Backoffice" mechanism of Fossil}
17	blame.wiki {The Annotate/Blame Algorithm Of Fossil}
18	branching.wiki {Branching, Forking, Merging, and Tagging}
19	bugtheory.wiki {Bug Tracking In Fossil}
20

	--- www/mkindex.tcl
	+++ www/mkindex.tcl
	@@ -9,11 +9,11 @@
9	set doclist {
10	aboutcgi.wiki {How CGI Works In Fossil}
11	aboutdownload.wiki {How The Download Page Works}
12	adding_code.wiki {Adding New Features To Fossil}
13	adding_code.wiki {Hacking Fossil}
14	alerts.md {Email Alerts And Notifications}
15	antibot.wiki {Defense against Spiders and Bots}
16	backoffice.md {The "Backoffice" mechanism of Fossil}
17	blame.wiki {The Annotate/Blame Algorithm Of Fossil}
18	branching.wiki {Branching, Forking, Merging, and Tagging}
19	bugtheory.wiki {Bug Tracking In Fossil}
20

Fossil SCM

Keyboard Shortcuts