From 9b1ee1b52ff45666da03f6afa1cb90ba02f8149c Mon Sep 17 00:00:00 2001 From: "fox.cpp" Date: Thu, 6 Jan 2022 21:56:08 +0300 Subject: [PATCH] docs: Convert manual pages into per-module Markdown pages --- docs/faq.md | 83 ++++++++----------- .../storage/imap-filters.md} | 81 +++--------------- 2 files changed, 44 insertions(+), 120 deletions(-) rename docs/{man/maddy-imap.5.scd => reference/storage/imap-filters.md} (50%) diff --git a/docs/faq.md b/docs/faq.md index 0aacdc3..a216020 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,16 +1,42 @@ # Frequently Asked Questions -## Why? +## I configured maddy as recommended and gmail still puts my messages in spam -For fun. Turned out to be a rather convenient approach to -self-hosted email. +Unfortunately, GMail policies are opaque so we cannot tell why this happens. -## Is it caddy for email? +Verify that you have a rDNS record set for the IP used +by sender server. Also some IPs may just happen to +have bad reputation - check it with various DNSBLs. In this +case you do not have much of a choice but to replace it. -No. It was intended to be one but developers quickly acknowledged -the fact email cannot be easily abstracted behind some magic. +Additionally, you may try marking multiple messages sent from +your domain as "not spam" in GMail UI. -## How it compares to MailCow or Mail-In-The-Box? +## Message sending fails with `dial tcp X.X.X.X:25: connect: connection timed out` in log + +Your provider is blocking outbound SMTP traffic on port 25. + +You either have to ask them to unblock it or forward +all outbound messages via a "smart-host". + +## What is resource usage of maddy? + +For a small personal server, you do not need much more than a +single 1 GiB of RAM and disk space. + +## How to setup a catchall address? + +https://github.com/foxcpp/maddy/issues/243#issuecomment-655694512 + +## maddyctl prints a "permission denied" error + +Run maddyctl under the same user as maddy itself. +E.g. +``` +sudo -u maddy maddyctl creds ... +``` + +## How maddy compares to MailCow or Mail-In-The-Box? MailCow and MIAB are bundles of well-known email-related software configured to work together. maddy is a single piece of software implementing subset of what @@ -62,13 +88,6 @@ ZoneMTA has a number of features that may make it easier to integrate with HTTP-based services. maddy speaks standard email protocols (SMTP, Submission). -## What is the scope of project? - -1. Implement a usable SMTP + Submission server that can both accept - and send email as secure as possible with todays state of - relevant protocols. -2. Implement a meaningful subset of IMAP for access to local storage. - ## Is there a webmail? No, at least currently. @@ -97,38 +116,4 @@ of bugs in one component. Besides, you are not required to use a single process, it is easy to launch maddy with a non-default configuration path and connect multiple instances -together using off-the-shelf protocols. - -## Can I do X with maddy? - -Ask on #maddy. - -maddy is less feature-packed than other SMTP/IMAP server -implementations but it is not completely useless for anything other than -its default configuration. - -## Can you implement X? - -"Umbrella" projects like maddy are susceptible to scope -creep unless maintainers apply a lot of skepticism to proposed -features. - -If X is essential for providing email security or extends the space of useful -configurations significantly and does not require major design changes - -we can talk, go to #maddy. Otherwise the likely answer is no. - -## Are you breaking things between releases? - -maddy releases follow Semantic Versioning 2.0.0 specification. -It is expected that 0.X releases may not be compatible with each -other. I attempt to minimize such breakage unless there is a significant -benefit. - -## 1.0 when? - -When no more backward-incompatible changes will be needed. maddy releases follow -Semantic Versioning 2.0.0 specification. - -## maddy is bad name, it is almost impossible to Google! - -Call it Maddy Mail Server. +together using off-the-shelf protocols. \ No newline at end of file diff --git a/docs/man/maddy-imap.5.scd b/docs/reference/storage/imap-filters.md similarity index 50% rename from docs/man/maddy-imap.5.scd rename to docs/reference/storage/imap-filters.md index e701a6e..22ce608 100644 --- a/docs/man/maddy-imap.5.scd +++ b/docs/reference/storage/imap-filters.md @@ -1,66 +1,4 @@ -maddy-imap(5) "maddy mail server" "maddy reference documentation" - -; TITLE IMAP endpoint module - -Module 'imap' is a listener that implements IMAP4rev1 protocol and provides -access to local messages storage specified by 'storage' directive. See -*maddy-storage*(5) for support storage backends and corresponding -configuration options. - -``` -imap tcp://0.0.0.0:143 tls://0.0.0.0:993 { - tls /etc/ssl/private/cert.pem /etc/ssl/private/pkey.key - io_debug no - debug no - insecure_auth no - auth pam - storage &local_mailboxes -} -``` - -## Configuration directives - -*Syntax*: tls _certificate_path_ _key_path_ { ... } ++ -*Default*: global directive value - -TLS certificate & key to use. Fine-tuning of other TLS properties is possible -by specifing a configuration block and options inside it: -``` -tls cert.crt key.key { - protocols tls1.2 tls1.3 -} -``` -See section 'TLS configuration' in *maddy*(1) for valid options. - -*Syntax*: io_debug _boolean_ ++ -*Default*: no - -Write all commands and responses to stderr. - -*Syntax*: io_errors _boolean_ ++ -*Default*: no - -Log I/O errors. - -*Syntax*: debug _boolean_ ++ -*Default*: global directive value - -Enable verbose logging. - -*Syntax*: insecure_auth _boolean_ ++ -*Default*: no (yes if TLS is disabled) - -*Syntax*: auth _module_reference_ - -Use the specified module for authentication. -*Required.* - -*Syntax*: storage _module_reference_ - -Use the specified module for message storage. -*Required.* - -## IMAP filters +# IMAP filters Most storage backends support application of custom code late in delivery process. As opposed to using SMTP pipeline modifiers or checks, it allows @@ -72,7 +10,7 @@ eariler in SMTP pipeline logic. Quarantined messages are not processed by IMAP filters and are unconditionally delivered to Junk folder (or other folder with \Junk special-use attribute). -To use an IMAP filter, specify it in the 'imap_filter' directive for the +To use an IMAP filter, specify it in the 'imap\_filter' directive for the used storage backend, like this: ``` storage.imapsql local_mailboxes { @@ -86,8 +24,8 @@ storage.imapsql local_mailboxes { ## System command filter (imap.filter.command) -This filter is similar to check.command module described in *maddy-filters*(5) -and runs system command +This filter is similar to check.command module +and runs a system command to obtain necessary information. Usage: ``` @@ -95,14 +33,14 @@ command executable_name args... { } ``` Same as check.command, following placeholders are supported for command -arguments: {source_ip}, {source_host}, {source_rdns}, {msg_id}, {auth_user}, -{sender}. Note: placeholders in command name are not processed to avoid +arguments: {source\_ip}, {source\_host}, {source\_rdns}, {msg\_id}, {auth\_user}, +{sender}. Note: placeholders in command name are not processed to avoid possible command injection attacks. -Additionally, for imap.filter.command, {account_name} placeholder is replaced +Additionally, for imap.filter.command, {account\_name} placeholder is replaced with effective IMAP account name. -Note that if you use provided systemd units on Linux, maddy executable is +Note that if you use provided systemd units on Linux, maddy executable is sandboxed - all commands will be executed with heavily restricted filesystem acccess and other privileges. Notably, /tmp is isolated and all directories except for /var/lib/maddy and /run/maddy are read-only. You will need to modify @@ -126,5 +64,6 @@ In this case, message will be placed in the Junk folder. $Label1 ``` -In this case, message will be placed in inbox and will have +In this case, message will be placed in inbox and will have '$Label1' added. +