git » chasquid » commit fcbd20c

docs: Add a section on dovecot auth troubleshooting

author Alberto Bertogli
2020-03-21 16:54:39 UTC
committer Alberto Bertogli
2020-03-21 16:54:39 UTC
parent 65afb02cd53f0c26eb0e54e03d05101e0aad7867

docs: Add a section on dovecot auth troubleshooting

This patch adds a section on dovecot authentication troubleshooting,
with common suggestions that can help identify what is going on when
the chasquid-dovecot interaction isn't working as expected.

docs/dovecot.md +18 -0

diff --git a/docs/dovecot.md b/docs/dovecot.md
index 2eb3024..a40cd77 100644
--- a/docs/dovecot.md
+++ b/docs/dovecot.md
@@ -51,5 +51,23 @@ If chasquid can't find them, the paths can be set with the
 `dovecot_userdb_path` and `dovecot_client_path` options.
 
 
+## Troubleshooting
+
+Dovecot authentication can be tricky to troubleshoot.
+
+If you think it is not working as it should, or chasquid isn't correctly
+talking with it, the easiest way to check is to [increase dovecot auth logging
+verbosity](https://doc.dovecot.org/admin_manual/logging/?highlight=logging#logging-verbosity):
+
+```
+auth_verbose = yes
+auth_debug = yes
+```
+
+One common gotcha is when dovecot is set up to use `user` instead of
+`user@domain`. In that case you can try setting `auth_username_format = %n` to
+make it ignore the domain if present.
+
+
 [dovecot]: https://dovecot.org
 [chasquid]: https://blitiri.com.ar/p/chasquid