From 8b056823e6328e2380ef2af1d822faf734afda83 Mon Sep 17 00:00:00 2001
From: Alberto Bertogli <albertito@blitiri.com.ar>
Date: Tue, 6 Feb 2024 00:34:17 +0000
Subject: [PATCH] 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 +
 docs/clients.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 docs/clients.md

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.
+
+