Changes

Page history
start jotting down notes about email services authored by anarcat's avatar anarcat 
Currently only the base template, unchanged, but i want to brain dump
stuff i find along the way in #40986
Show whitespace changes
Inline Side-by-side
service/email.md 0 → 100644
View page @ d4027141
TODO: email service overview
TODO: deduplicate this with howto/submission
[[_TOC_]]
# Tutorial
TODO: import docs from howto/submission.md
# How-to
## Testing outgoing mail
Multiple services exist to see if mail is going out correctly, or if a
given mail is "spammy". Three are recommended by TPA as being easy to
use and giving good technical feedback.
In general, mail can be sent directly from the server using a command
like:
echo "this is a test email" | mail -r postmaster@crm.torproject.org -s 'test email from anarcat' -- target@example.com
### DKIM validator
Visit <https://dkimvalidator.com/> to get a one-time email address,
send a test email there, and check the results on the web site.
Will check SPF, DKIM, and run Spamassassin.
### Mail tester
Visit <https://www.mail-tester.com/> to get a one-time email address,
send a test email there, and check the results on the website.
Will check SPF, DKIM, DMARC, Spamassassin, email formatting, list
unsubscribe, block lists, pretty complete. Has coconut trees.
### verifier.port25.com
Send an email <check-auth@verifier.port25.com>, will check SPF, DKIM,
and reverse IP configuration and reply with a report by email.
Interestingly, ran by [sparkpost](https://www.sparkpost.com/).
## Pager playbook
<!-- information about common errors from the monitoring system and -->
<!-- how to deal with them. this should be easy to follow: think of -->
<!-- your future self, in a stressful situation, tired and hungry. -->
## Disaster recovery
<!-- what to do if all goes to hell. e.g. restore from backups? -->
<!-- rebuild from scratch? not necessarily those procedures (e.g. see -->
<!-- "Installation" below but some pointers. -->
# Reference
<!-- this section is a more in-depth review of how this service works, -->
<!-- how it's setup. day-to-day operation should be covered in -->
<!-- tutorial or how-to, this is more in-depth -->
<!-- a good guide to "audit" an existing project's design: -->
<!-- https://bluesock.org/~willkg/blog/dev/auditing_projects.html -->
<!-- the following sections are partially based on that -->
## Installation
<!-- how to setup the service from scratch -->
### Manual DKIM configuration
TODO: summarize https://gitlab.torproject.org/tpo/tpa/team/-/issues/40981
### SPF records
TODO: summarize https://gitlab.torproject.org/tpo/tpa/team/-/issues/40981
### DMARC records
A good start for a DMARC record is:
_dmarc IN TXT "v=DMARC1;p=none;pct=100;rua=mailto:postmaster@torproject.org"
That is a "soft" policy (`p=` is `none` instead of `quarantine` or
`reject`) that applies to all email (`pct=100`) and sends reports to
the postmaster.
## Upgrades
<!-- how upgrades are performed. preferably automated through Debian -->
<!-- packages, otherwise document how upgrades are performed. see also -->
<!-- the Testing section below -->
## SLA
<!-- this describes an acceptable level of service for this service -->
## Design and architecture
<!-- how this is built -->
<!-- should reuse and expand on the "proposed solution" discussed in -->
<!-- a previous RFC or the Discussion section below. it's a -->
<!-- "as-built" documented, whereas the "Proposed solution" is an -->
<!-- "architectural" document, which the final result might differ -->
<!-- from, sometimes significantly -->
## Services
<!-- open ports, daemons, cron jobs -->
## Storage
<!-- databases? plain text file? the frigging blockchain? memory? -->
## Queues
<!-- email queues, job queues, schedulers -->
## Interfaces
<!-- e.g. web APIs, commandline clients, etc -->
## Authentication
<!-- SSH? LDAP? standalone? -->
## Implementation
<!-- programming languages, frameworks, versions, license -->
## Related services
<!-- dependent services (e.g. authenticates against LDAP, or requires -->
<!-- git pushes) -->
## Issues
<!-- such projects are never over. add a pointer to well-known issues -->
<!-- and show how to report problems. usually a link to the -->
<!-- issue tracker. consider creating a new Label to regroup the -->
<!-- issues if using the general tracker. see also TPA-RFC-19. -->
There is no issue tracker specifically for this project, [File][] or
[search][] for issues in the [team issue tracker][search] with the
label ~Foo.
[File]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/new
[search]: https://gitlab.torproject.org/tpo/tpa/team/-/issues?label_name%5B%5D=Foo
## Maintainer
<!-- document who deployed and operates this service, the team and -->
<!-- ideally the person inside that team -->
## Users
<!-- who the main users are, how they use the service. possibly reuse -->
<!-- the Personas section in the RFC, if available. -->
## Upstream
<!-- who the upstreams are, if they are still active, -->
<!-- collaborative, how do we keep up to date, support channels, see -->
<!-- also the "Issues" section above -->
## Monitoring and metrics
<!-- describe how this service is monitored, how security issues and -->
<!-- upgrades are tracked, see also "Upgrades" above. -->
## Tests
<!-- how the service can be tested, for example after major changes -->
<!-- like IP address changes or upgrades. describe CI, test suites, linting -->
## Logs
<!-- where are the logs? how long are they kept? any PII? -->
<!-- what about performance metrics? same questions -->
## Backups
<!-- does this service need anything special in terms of backups? -->
<!-- e.g. locking a database? special recovery procedures? -->
## Other documentation
<!-- references to upstream documentation, if relevant -->
# Discussion
<!-- the "discussion" section is where you put any longer conversation -->
<!-- about the project that you will not need in a casual -->
<!-- review. history of the project, why it was done the way it was -->
<!-- (as opposed to how), alternatives, and other proposals are -->
<!-- relevant here. -->
<!-- this at least partly overlaps with the TPA-RFC process (see -->
<!-- policy.md), but in general should defer to proposals when -->
<!-- available -->
## Overview
<!-- describe the overall project. should include a link to a ticket -->
<!-- that has a launch checklist -->
<!-- if this is an old project being documented, summarize the known -->
<!-- issues with the project. -->
## Security and risk assessment
<!--
5. When was the last security review done on the project? What was
the outcome? Are there any security issues currently? Should it
have another security review?
6. When was the last risk assessment done? Something that would cover
risks from the data stored, the access required, etc.
-->
## Technical debt and next steps
<!--
7. Are there any in-progress projects? Technical debt cleanup?
Migrations? What state are they in? What's the urgency? What's the
next steps?
8. What urgent things need to be done on this project?
-->
## Proposed Solution
<!-- Link to RFC -->
## Other alternatives
<!-- include benchmarks and procedure if relevant -->