mirror of
https://github.com/foxcpp/maddy.git
synced 2025-04-05 14:07:38 +03:00
docs: Convert manual pages into per-module Markdown pages
This commit is contained in:
fox.cpp
parent
a8e0a74be9
commit
9b1ee1b52f
2 changed files with 44 additions and 120 deletions
83
docs/faq.md
83
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.
|
||||
|
|
@ -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.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue