git » chasquid » commit 8b05682

docs: Add a "Clients" document

author Alberto Bertogli
2024-02-06 00:34:17 UTC
committer Alberto Bertogli
2024-02-06 00:50:30 UTC
parent a7342fcb1b044430eca02685c6765dc309d888ac
docs: Add a "Clients" document

We've had a couple of reported issues about the difficulty of setting up
new clients, or confusion due to using broken clients:

- https://github.com/albertito/chasquid/pull/46
- https://github.com/albertito/chasquid/issues/52

This patch adds the first version of a "Clients" document that includes
requirements for all clients, configuration examples, and a list of
known-problematic client software.

The goal is to help reduce friction and confusion when setting up
clients.

The document needs more polishing and examples, which hopefully will be
added later.

Fixes https://github.com/albertito/chasquid/issues/48.
.mkdocs.yml +1 -0
docs/clients.md +54 -0 
diff --git a/.mkdocs.yml b/.mkdocs.yml
index f1e1766..a5700ca 100644
--- a/.mkdocs.yml
+++ b/.mkdocs.yml
@@ -24,6 +24,7 @@ nav:
 - All:
     - aliases.md
     - hooks.md
+    - clients.md
     - dovecot.md
     - dkim.md
     - haproxy.md
diff --git a/docs/clients.md b/docs/clients.md
new file mode 100644
index 0000000..1d7bc2b
--- /dev/null
+++ b/docs/clients.md
@@ -0,0 +1,54 @@
+
+# Clients
+
+chasquid supports most SMTP clients, but requires them to have some features:
+
+- Support TLS (either
+  [STARTTLS](https://datatracker.ietf.org/doc/html/rfc3207) or
+  [implicit TLS](https://datatracker.ietf.org/doc/html/rfc8314#section-3.3))
+- Support the
+  [PLAIN authentication method](https://datatracker.ietf.org/doc/html/rfc4954#section-4).
+
+All modern clients should support both, and thus have no problems talking to
+chasquid.
+
+
+## Configuration examples
+
+### [msmtp](https://marlam.de/msmtp/)
+
+This example is useful as either per-user `~/.msmtprc` or system-wide
+`/etc/msmtprc`:
+
+```
+account default
+tls on
+auth on
+
+# Use the SMTP submission port. Many providers block communications to the
+# default port 25, but the submission port 587 tends to work just fine.
+port 587
+
+# Server hostname.
+host SERVER
+
+# Your username (including the domain).
+user USER@DOMAIN
+
+# Your password.
+password SECRET
+```
+
+Replace the `SERVER`, `USER@DOMAIN` and `SECRET` strings with the appropriate
+values.
+
+
+## Problematic clients
+
+These clients are known to have issues talking to chasquid:
+
+- [ssmtp](https://packages.debian.org/source/unstable/ssmtp): does not
+  support the PLAIN authentication method. It is also unmaintained.  
+  Please use [msmtp](https://marlam.de/msmtp/) instead.
+
+