Mirrors/go-chasquid-smtp
1
0
Fork 0
mirror of https://blitiri.com.ar/repos/chasquid synced 2025-12-17 14:37:02 +00:00
Code Releases Activity
Files
5c09138db87f10851a5c4b47948fa669b6bf57c3
go-chasquid-smtp/docs/man/chasquid.conf.5
Alberto Bertogli e79586a014 Implement HAProxy protocol support 
This patch implements support for incoming connections wrapped in the
HAProxy protocol v1.

This is useful when running chasquid behind a HAProxy server, as it
needs the original source IP to perform SPF checks.

This patch is a reimplementation of one originally provided by Denys
Vitali in pull request #15, except the logic for the protocol handling
is moved to a new package, and the smtpsrv.Conn handling of the source
IP is simplified.

It is marked as experimental for now, since we want to give it a bit
more exposure just in case the option/api needs adjustment.

Thanks a lot to Denys Vitali (@denysvitali in github) for sending the
original patch for this, and helping test it!
2020-11-13 20:49:42 +00:00

248 lines
9.1 KiB
Groff
Raw Blame History

.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "chasquid.conf 5"
.TH chasquid.conf 5 "2020-11-12" "" ""
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
chasquid.conf(5) \-\- chasquid configuration file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBchasquid.conf\fR\|(5) is \fBchasquid\fR\|(1)'s main configuration file.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The file is in protocol buffers' text format.
.PP
Comments start with \f(CW\*(C`#\*(C'\fR. Empty lines are allowed. Values are of the form
\&\f(CW\*(C`key: value\*(C'\fR. Values can be strings (quoted), integers, or booleans (\f(CW\*(C`true\*(C'\fR or
\&\f(CW\*(C`false\*(C'\fR).
.PP
Some values might be repeated, for example the listening addresses.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fBhostname\fR (string):" 8
.IX Item "hostname (string):"
Default hostname to use when saying hello. This is used to say hello to
clients (for aesthetic purposes), and as the \s-1HELO/EHLO\s0 domain on outgoing \s-1SMTP\s0
connections (so ideally it would resolve back to the server, but it isn't a
big deal if it doesn't). Default: the system's hostname.
.IP "\fBmax_data_size_mb\fR (int):" 8
.IX Item "max_data_size_mb (int):"
Maximum email size, in megabytes. Default: 50.
.IP "\fBsmtp_address\fR (repeated string):" 8
.IX Item "smtp_address (repeated string):"
Addresses to listen on for \s-1SMTP\s0 (usually port 25). Default: \*(L"systemd\*(R", which
means systemd passes sockets to us. systemd sockets must be named with
\&\fBFileDescriptorName=smtp\fR.
.IP "\fBsubmission_address\fR (repeated string):" 8
.IX Item "submission_address (repeated string):"
Addresses to listen on for submission (usually port 587). Default: \*(L"systemd\*(R",
which means systemd passes sockets to us. systemd sockets must be named with
\&\fBFileDescriptorName=submission\fR.
.IP "\fBsubmission_over_tls_address\fR (repeated string):" 8
.IX Item "submission_over_tls_address (repeated string):"
Addresses to listen on for submission-over-TLS (usually port 465). Default:
\&\*(L"systemd\*(R", which means systemd passes sockets to us. systemd sockets must be
named with \fBFileDescriptorName=submission_tls\fR.
.IP "\fBmonitoring_address\fR (string):" 8
.IX Item "monitoring_address (string):"
Address for the monitoring \s-1HTTP\s0 server. Do \s-1NOT\s0 expose this to the public
internet. Default: no monitoring server.
.IP "\fBmail_delivery_agent_bin\fR (string):" 8
.IX Item "mail_delivery_agent_bin (string):"
Mail delivery agent (\s-1MDA,\s0 also known as \s-1LDA\s0) to use. This should point
to the binary to use to deliver email to local users. The content of the
email will be passed via stdin. If it exits unsuccessfully, we assume
the mail was not delivered. Default: \fImaildrop\fR.
.IP "\fBmail_delivery_agent_args\fR (repeated string):" 8
.IX Item "mail_delivery_agent_args (repeated string):"
Command line arguments for the mail delivery agent. One per argument.
Some replacements will be done.
.Sp
On an email sent from marsnik@mars to venera@venus:
.Sp
.Vb 6
\& %from% \-> from address (marsnik@mars)
\& %from_user% \-> from user (marsnik)
\& %from_domain% \-> from domain (mars)
\& %to% \-> to address (venera@venus)
\& %to_user% \-> to user (venera)
\& %to_domain% \-> to domain (venus)
.Ve
.Sp
Default: \f(CW"\-f", "%from%", "\-d", "%to_user%"\fR (adequate for procmail and
maildrop).
.IP "\fBdata_dir\fR (string):" 8
.IX Item "data_dir (string):"
Directory where we store our persistent data. Default:
\&\fI/var/lib/chasquid\fR.
.IP "\fBsuffix_separators\fR (string):" 8
.IX Item "suffix_separators (string):"
Suffix separator, to perform suffix removal of local users. For
example, if you set this to \f(CW\*(C`\-+\*(C'\fR, email to local user \f(CW\*(C`user\-blah\*(C'\fR and
\&\f(CW\*(C`user+blah\*(C'\fR will be delivered to \f(CW\*(C`user\*(C'\fR. Including \f(CW\*(C`+\*(C'\fR is strongly
encouraged, as it is assumed for email forwarding. Default: \f(CW\*(C`+\*(C'\fR.
.IP "\fBdrop_characters\fR (string):" 8
.IX Item "drop_characters (string):"
Characters to drop from the user part on local emails. For example, if
you set this to \f(CW\*(C`._\*(C'\fR, email to local user \f(CW\*(C`u.se_r\*(C'\fR will be delivered to
\&\f(CW\*(C`user\*(C'\fR. Default: \f(CW\*(C`.\*(C'\fR.
.IP "\fBmail_log_path\fR (string):" 8
.IX Item "mail_log_path (string):"
Path where to write the mail log to. If \f(CW\*(C`<syslog>\*(C'\fR, log using the
syslog (at \f(CW\*(C`MAIL|INFO\*(C'\fR priority). If \f(CW\*(C`<stdout>\*(C'\fR, log to stdout; if
\&\f(CW\*(C`<stderr>\*(C'\fR, log to stderr. Default: \f(CW\*(C`<syslog>\*(C'\fR.
.IP "\fBdovecot_auth\fR (bool):" 8
.IX Item "dovecot_auth (bool):"
Enable dovecot authentication. If true, users that are not found in chasquid's
databases will be authenticated via dovecot. Default: \f(CW\*(C`false\*(C'\fR.
.Sp
The path to dovecot's auth sockets is autodetected, but can be manually
overridden using the \f(CW\*(C`dovecot_userdb_path\*(C'\fR and \f(CW\*(C`dovecot_client_path\*(C'\fR if
needed.
.IP "\fBhaproxy_incoming\fR (bool):" 8
.IX Item "haproxy_incoming (bool):"
\&\fB\s-1EXPERIMENTAL\s0\fR, might change in backwards-incompatible ways.
.Sp
If true, expect incoming \s-1SMTP\s0 connections to use the HAProxy protocol.
This allows deploying chasquid behind a HAProxy server, as the address
information is preserved, and \s-1SPF\s0 checks can be performed properly.
Default: \f(CW\*(C`false\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBchasquid\fR\|(1)
View Git Blame Copy Permalink