service/email.md

@@ -70,7 +70,101 @@ Interestingly, ran by [sparkpost](https://www.sparkpost.com/).
 
 ### Manual DKIM configuration
 
-TODO: summarize https://gitlab.torproject.org/tpo/tpa/team/-/issues/40981
+This is a rushed OpenDKIM deployment procedure that was used in
+[tpo/tpa/team#40981][] and [tpo/tpa/team#40988][]. It will be added
+to Puppet in [tpo/tpa/team#40989][].
+
+ 1. install OpenDKIM:
+
+        apt install opendkim opendkim-tools
+
+ 2. ensure you have those lines in `/etc/opendkim.conf`:
+
+        LogWhy          yes
+        Mode            s # sign only, use sv to also check incoming
+        Domain          torproject.org
+        Selector        2022-submit-01 # 2022-submit-01._domainkey.torproject.org
+        Keyfile         /etc/opendkim/keys/2022-submit-01.private
+        Socket          local:/var/spool/postfix/opendkim/opendkim.sock
+
+    Note that the `Selector` and `Domain` fields are prone to change
+    if the server is sending mail from more than one domain. For
+    example, on `crm-int-01`, we also put `crm-int-01.torproject.org`
+    and `crm.torproject.org` in there. The selector is also based on
+    the year of creation (`2022` in this case) and the short hostname
+    of the server the key belongs to (`submit-01`) so that we don't
+    have to copy that private key around.
+
+ 3. generate the keys and directories:
+
+        mkdir -p /etc/opendkim/keys &&
+        mkdir /var/spool/postfix/opendkim &&
+        chown opendkim /var/spool/postfix/opendkim &&
+        opendkim-genkey --directory=/etc/opendkim/keys/ --selector=2022-submit-01 --domain=torproject.org --verbose
+
+ 4. grant Postfix access to the OpenDKIM socket:
+
+        adduser postfix opendkim
+
+ 5. restart the server:
+
+        service opendkim restart
+
+ 6. add the keys from `/etc/opendkim/keys/2022-submit-01.txt` into
+    DNS, e.g.:
+
+        2022-submit-01._domainkey       IN      TXT     ( "v=DKIM1; h=sha256; k=rsa; "
+                  "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6iJa25pvx5qatYV4u44zolHLMiqkWZBvF6UJcX8hrSNES/aw/k4zXiliChs3eUtGHjf5aSNC6TrOndfQqRxMxNn+XhSEsUa6zFhZeeAOIi0A3TPRd5qL8aWfHH2NtHZAnZ5lodkA6HjJ/HpyrJvFuyuJ94yNL/bjvRWu+bMwixBIYr6znDoJYGTPC5YHZt48bJgvg3lAb3vIwD"
+                  "bkBw+bMkZCbRjSQuOM52pg6uQLSBiBeQHqWkSd03vp4A906jWaMLDHMfVZDDrXLg+QG2nAOoJmZ0l5argoIRiEG/8GO72FI2dEKJaXgXYqpSXGCtzZJNIr8schHFZBirZBLljbEwIDAQAB" )  ; ----- DKIM key 2022-submit-01 for torproject.org
+
+    if you had a subdomain prefix (e.g. in [tpo/tpa/team#40981][] we
+    used `crm.tpo`), make sure the `_domainkey` is under that prefix:
+
+        2022._domainkey.crm IN      TXT     ( "v=DKIM1; h=sha256; k=rsa; "
+                  "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtSNGCjHmZnGrnBb9nCsPUc6MjZd5QueGKV+iXwcRNfU0LapFZMi5t7WE/kTPJsRWIF8AMHymNqLA5835m5LwaBBXZdu1utNARKSXDzGsEjxuDiAnSqD0Rb1px1JA+Eex0RC3thYZuyIIAxK31pXxJt2mowXtrhIkuKFB2YpE0yUudKuDZIZZ3YNH025czK/jFLD6TH+5xD9Cej"
+                  "H0MB6tE4O41rCjZUjSZ7Ar7BjVID6foCmlbr/3EG7dbzQv6YqH19OX6YgL0UMfG2RhvhWEUNYghS6K88vTelnHx/ShUzIeu05jd6mi9OLCA/Hl2bFRsa0f1ttHKpnzuC+ecn0sWwIDAQAB" )  ; ----- DKIM key 2022 for crm.torproject.org
+
+ 7. then test the key with:
+
+        opendkim-testkey -d torproject.org -s 2022-submit-01 -vv
+
+    ... which should show, once DNS propagated:
+
+        root@submit-01:/etc/opendkim/keys# opendkim-testkey -d torproject.org -s 2022-submit-01 -vv
+        opendkim-testkey: using default configfile /etc/opendkim.conf
+        opendkim-testkey: key loaded from /etc/opendkim/keys/2022-submit-01.private
+        opendkim-testkey: checking key '2022-submit-01._domainkey.torproject.org'
+        opendkim-testkey: key secure
+
+    If you see `record not found`, it's because the DNS record wasn't
+    found. See if DNS has propagated properly, maybe flush negative
+    responses with `unbound-control flush-negative`.
+
+    The `keys not secure` message means you are not using DNSSEC,
+    which should *not* happen in our configuration. Investigate if you
+    do see the warning.
+
+ 8. stop puppet to keep it from messing with the Puppet config
+
+        puppet agent --disable 'rush opendkim deployment by hand, tpo/tpa/team#40988'
+
+ 8. hook into postfix:
+
+        postconf -e milter_default_action=accept &&
+        postconf -e smtpd_milters=local:opendkim/opendkim.sock &&
+        postconf -e non_smtpd_milters=local:opendkim/opendkim.sock
+
+ 9. reload postfix (warning: this will retry the queue)
+
+        service postfix reload
+
+ 10. [test outgoing mail](#testing-outgoing-mail):
+
+        echo "this is a test email" | mail -r postmaster@torproject.org -s 'test email from anarcat' -- check-auth@verifier.port25.com
+
+[tpo/tpa/team#40981]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/40981
+[tpo/tpa/team#40988]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/40988
+[tpo/tpa/team#40989]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/40989
 
 ### SPF records