meillo@335: .TH masqmail.route 5 2011-08-27 masqmail-0.3.3 "File Formats" meillo@34: meillo@0: .SH NAME meillo@0: masqmail.route \- masqmail route configuration file meillo@34: meillo@34: meillo@0: .SH DESCRIPTION meillo@0: meillo@34: This man page describes the syntax of the route configuration files of \fBmasqmail (8)\fR. meillo@34: Their usual locations are in \fI/etc/masqmail/\fR. meillo@0: meillo@311: Mail will be sent with the SMTP protocol to its destination, unless meillo@311: `pipe' is given. meillo@311: In this case the message will be piped to the given program. meillo@311: meillo@311: meillo@316: .SH ROUTE CONDITIONS meillo@316: meillo@316: .TP meillo@317: \fBallowed_senders\fR = \fIlist\fR meillo@316: meillo@317: This is a semicolon `;' separated list of envelope sender addresses. meillo@317: Messages which have one of these addresses as the return path (= mail meillo@317: from) are allowed to use this route meillo@317: (if not also in \fBdenied_senders\fR). meillo@317: meillo@317: Glob patterns containing `?' and `*' can be used. meillo@317: The special item "<>" matches the null sender address meillo@317: (eg. failure notices or delivery notifications). meillo@317: If the pattern doesn't contain an `@', it is seen as a pattern for the meillo@317: local part only. meillo@317: meillo@317: Example: \fImeillo;*@*example.org;web*@example.com\fP meillo@317: meillo@317: (``meillo'' equals ``meillo@*'', i.e. the local part.) meillo@316: meillo@316: .TP meillo@317: \fBdenied_senders\fR = \fIlist\fR meillo@316: meillo@317: This is a semicolon `;' separated list of envelope sender addresses. meillo@317: Messages which have one of these addresses as the return path (= meillo@317: mail from) will not meillo@317: be sent using this route (even if also in \fBallowed_senders\fR). meillo@317: meillo@317: Glob patterns containing `?' and `*' can be used. meillo@317: The special item "<>" matches the null sender address meillo@317: (eg. failure notices or delivery notifications). meillo@317: If the pattern doesn't contain an `@', it is seen as a pattern for the meillo@317: local part only. meillo@317: meillo@317: Example: (see \fIallowed_senders\fP) meillo@316: meillo@316: .TP meillo@317: \fBallowed_recipients\fR = \fIlist\fR meillo@316: meillo@317: A list of envelope recipient addresses where mail can be sent to using meillo@317: this route. meillo@317: This is for example useful if you use this route configuration when connected to another LAN via ppp. meillo@317: Glob patterns containing `?' and `*' can be used. meillo@316: meillo@317: Example: \fI*@example.org;*@*foo.bar\fP meillo@317: meillo@317: (See also examples for \fIallowed_senders\fP) meillo@316: meillo@316: .TP meillo@317: \fBdenied_recipients\fR = \fIlist\fR meillo@316: meillo@317: A list of envelope recipient addresses where mail will not be sent to meillo@317: using this route. meillo@316: This is for example useful if you send mail directly (\fBmail_host\fR is not set) meillo@316: and you know of hosts that will not accept mail from you because they use a dialup list meillo@316: (eg. \fBhttp://maps.vix.com/dul/\fR). meillo@317: \fBdenied_recipients\fR overrules \fBallowed_recipients\fR. meillo@317: Glob patterns containing `?' and `*' can be used. meillo@317: meillo@317: Example: \fI*@spamblocker.example.org\fP meillo@317: meillo@317: (See also examples for \fIallowed_senders\fP) meillo@316: meillo@316: .TP meillo@316: \fBlast_route\fR = \fIboolean\fR meillo@316: meillo@316: If this is set, a mail which would have been delivered using this route, meillo@316: but has failed temporarily, will not be tried to be delivered using the next route. meillo@316: meillo@317: If you have set up a special route with filters using the lists meillo@317: `allowed_recipients' and `allowed_senders' or their complements meillo@317: (denied_), meillo@316: and the mail passing these rules should be delivered using this route only, meillo@316: you should set this to `true'. meillo@316: Otherwise the mail would be passed to the next route (if any), meillo@316: unless that route has rules which prevent that. meillo@316: meillo@316: Default is false. meillo@316: meillo@318: .TP meillo@318: \fBconnect_error_fail\fR = \fIboolean\fR meillo@318: meillo@318: If this is set, a connection error (or if a pipe command could not be meillo@318: executed) will cause a mail delivery to fail, ie. it will be bounced. meillo@318: If it is unset, it will just be defered. meillo@318: meillo@318: Default is false. meillo@318: The reason for this is that masqmail is designed for non permanent internet connections, meillo@318: where such errors may occur quite often, and a bounce would be annoying. meillo@318: meillo@318: For the default local_net route it is set to true. meillo@318: meillo@316: meillo@316: .SH SMTP CONFIGURATION meillo@34: meillo@0: .TP meillo@34: \fBmail_host\fR = \fIstring\fR meillo@0: meillo@34: This is preferably the mail server of your ISP. meillo@34: All outgoing messages will be sent to this host which will distribute them to their destinations. meillo@34: If you do not set this mails will be sent directly. meillo@34: Because the mail server is probably `near' to you, mail transfer will be much faster if you use it. meillo@0: meillo@0: You can optionally give a port number following the host name and a colon, eg mail_host="mail.foo.com:25". meillo@34: meillo@0: .TP meillo@34: \fBresolve_list\fR = \fIlist\fR meillo@0: meillo@34: Specify the method how the domain of the server is resolved. meillo@34: Possible values are dns_mx, dns_a, byname. meillo@34: For `dns_mx', the domain is assumed to be an MX pointer to a list of host names, meillo@34: these will be tried each in order (lowest preference value first, equal preference values in random order). meillo@34: For `dns_a', the domain is assumed to be an A pointer. meillo@34: For `byname', the library function \fBgethostbyname(3)\fR will be used. meillo@0: meillo@0: The default is "dns_mx;dns_a;byname". meillo@34: meillo@0: .TP meillo@34: \fBhelo_name\fR = \fIstring\fR meillo@0: meillo@34: Set the name given with the HELO/EHLO command. If this is not set, meillo@34: \fBhost_name\fR from \fImasqmail.conf\fR will be used, meillo@34: if the \fBdo_correct_helo\fR option (see below) is unset. meillo@0: meillo@0: .TP meillo@34: \fBdo_correct_helo\fR = \fIboolean\fR meillo@0: meillo@34: If this is set, masqmail tries to look up your host name as it appears meillo@34: on the internet and sends this in the HELO/EHLO command. meillo@34: Some servers are so picky that they want this. meillo@34: Which is really crazy. meillo@34: It just does not make any sense to lie about ones own identity, meillo@34: because it can always be looked up by the server. meillo@34: Nobody should believe in the name given by HELO/EHLO anyway. meillo@34: If this is not set, \fBhost_name\fR from \fImasqmail.conf\fR or as given with meillo@34: the \fBhelo_name\fR (see above) will be used. meillo@0: meillo@0: .TP meillo@222: \fBinstant_helo\fR = \fIboolean\fR meillo@222: meillo@222: If this is set, masqmail does not wait for the greeting of the SMTP server meillo@222: after opening the connection. meillo@222: Instead it says EHLO right away (ESMTP is assumed). meillo@222: Use this option with wrappers that eat the 220 greeting of the SMTP server. meillo@223: Common examples are STARTTLS wrappers, like `openssl s_client -starttls smtp ...'. meillo@222: meillo@222: If this option is set and a 220 greeting is received though, meillo@222: everything should still work. meillo@222: Please don't rely on that and keep in mind that RFC 2821 says that the client meillo@222: SHOULD wait for the 220 greeting of the server. meillo@222: meillo@222: Default: false meillo@222: meillo@222: .TP meillo@34: \fBdo_pipelining\fR = \fIboolean\fR meillo@0: meillo@34: If this is set to false, masqmail will not use ESMTP PIPELINING, meillo@34: even if the server announces that it is able to cope with it. meillo@34: Default is true. meillo@0: meillo@34: You do not want to set this to false unless the mail setup on the meillo@34: remote server side is really broken. meillo@34: Keywords: wingate. meillo@0: meillo@0: meillo@0: .TP meillo@316: \fBauth_name\fR = \fIstring\fR meillo@0: meillo@316: Set the authentication type for ESMTP AUTH authentication. meillo@316: Currently only `cram-md5' and `login' are supported. meillo@0: meillo@0: .TP meillo@316: \fBauth_login\fR = \fIstring\fR meillo@0: meillo@316: Your account name for ESMTP AUTH authentication. meillo@0: meillo@0: .TP meillo@316: \fBauth_secret\fR = \fIstring\fR meillo@0: meillo@316: Your secret for ESMTP AUTH authentication. meillo@0: meillo@0: .TP meillo@316: \fBwrapper\fR = \fIcommand\fR meillo@0: meillo@316: If set, instead of opening a connection to a remote server, meillo@316: \fIcommand\fR will be called and all traffic will be piped to its stdin and from its stdout. meillo@316: Purpose is to tunnel ip traffic, eg. for ssl. meillo@316: meillo@316: Example for SMTP over SSL tunneling: meillo@316: .nf meillo@316: wrapper="/usr/bin/openssl s_client \-quiet \-connect mail.gmx.net:465 2>/dev/null" meillo@316: .fi meillo@316: meillo@316: SMTP over SSL is supported since masqmail-0.1.8. meillo@316: It is marked obsolete by the IETF but is still in use. meillo@316: meillo@316: meillo@316: Example for encryption with STARTTLS (RFC-3207): meillo@316: .nf meillo@316: # don't forget the instant_helo, otherwise it won't work meillo@316: instant_helo=true meillo@316: wrapper="/usr/bin/openssl s_client \-quiet \-starttls smtp \-connect mail.gmx.net:25 2>/dev/null" meillo@316: .fi meillo@316: meillo@316: This is supported since masqmail-0.2.28. meillo@316: STARTTLS supersedes SMTP over SSL. meillo@316: meillo@316: Note for openssl: meillo@316: Ensure that stderr is redirected. meillo@316: Do *not* use \-crlf in the wrapper command, because masqmail does already insert CRLF. meillo@316: However, you might want to specify \-crlf if you want to test your wrapper command meillo@316: interactively on the command line. meillo@316: meillo@316: meillo@316: .SH PIPE CONFIGURATION meillo@0: meillo@0: .TP meillo@316: \fBpipe\fR = \fIcommand\fR meillo@0: meillo@316: \fIcommand\fR will be called and the message will be piped to its stdin. meillo@316: Purpose is to use gateways to uucp, fax, sms or whatever else. meillo@316: meillo@316: You can use variables to give as arguments to the command, meillo@316: these are the same as for the mda in the main configuration, see \fBmasqmail.conf(5)\fR. meillo@316: meillo@316: .TP meillo@316: \fBpipe_fromline = \fIboolean\fR meillo@316: meillo@316: Only if `pipe' is used. meillo@316: A from line will be prepended to the output stream whenever a pipe command is called. meillo@316: Default is false. meillo@316: meillo@316: .TP meillo@316: \fBpipe_fromhack = \fIboolean\fR meillo@316: meillo@316: Only if `pipe' is used. meillo@316: Each line beginning with `From ' is replaced with `>From ' whenever a pipe command is called. meillo@316: You probably want this if you have set \fBpipe_fromline\fR above. meillo@316: Default is false. meillo@316: meillo@316: meillo@316: .SH ADDRESS REWRITE RULES meillo@0: meillo@0: .TP meillo@34: \fBset_h_from_domain\fR = \fIstring\fR meillo@0: meillo@34: Replace the domain part in `From:' headers with this value. meillo@34: This may be useful if you use a private, outside unknown address on your local LAN meillo@141: and want this to be replaced by the domain of the address of your email address on the internet. meillo@34: Note that this is different to \fBset_return_path_domain\fR, see below. meillo@0: meillo@0: .TP meillo@138: \fBset_h_reply_to_domain\fR = \fIstring\fR meillo@138: meillo@138: Same as \fBset_h_from_domain\fP, but for the `Reply-To' header. meillo@138: meillo@138: .TP meillo@34: \fBset_return_path_domain\fR = \fIstring\fR meillo@0: meillo@34: Sets the domain part of the envelope from address. meillo@34: Some hosts check whether this is the same as the net the connection is coming from. meillo@34: If not, they reject the mail because they suspect spamming. meillo@34: It should be a valid address, because some mail servers also check that. meillo@34: You can also use this to set it to your usual address on the internet meillo@34: and put a local address only known on your LAN in the configuration of your mailer. meillo@34: Only the domain part will be changed, the local part remains unchanged. meillo@34: Use \fBmap_return_path_addresses\fR for rewriting local parts. meillo@0: meillo@0: .TP meillo@34: \fBmap_h_from_addresses\fR = \fIlist\fR meillo@0: meillo@34: This is similar to \fBset_h_from_domain\fR, but more flexible. meillo@34: Set this to a list which maps local parts to a full RFC 822 compliant email address, meillo@34: the local parts (the keys) are separated from the addresses (the values) by colons (`:'). meillo@0: meillo@0: Example: meillo@223: .nf meillo@0: map_h_from_addresses = "john: John Smith ; charlie: Charlie Miller " meillo@223: .fi meillo@0: meillo@0: You can use patterns, eg. * as keys. meillo@34: meillo@0: .TP meillo@34: \fBmap_h_reply_to_addresses\fR = \fIlist\fR meillo@0: meillo@34: Same as \fBmap_h_from_addresses\fR, but for the `Reply-To:' header. meillo@0: meillo@0: .TP meillo@34: \fBmap_h_mail_followup_to_addresses\fR = \fIlist\fR meillo@0: meillo@34: Same as \fBmap_h_from_addresses\fR, but for the `Mail-Followup-To:' header. meillo@34: Useful when replying to mailing lists. meillo@0: meillo@0: .TP meillo@34: \fBmap_return_path_addresses\fR = \fIlist\fR meillo@0: meillo@34: This is similar to \fBset_return_path_domain\fR, but more flexible. meillo@34: Set this to a list which maps local parts to a full RFC 821 compliant email address, meillo@34: the local parts (the keys) are separated from the addresses (the values) by colons (`:'). meillo@34: Note that this option takes RFC 821 addresses while \fBmap_h_from_addresses\fR takes RFC 822 addresses. meillo@34: The most important difference is that RFC 821 addresses have no full name. meillo@0: meillo@0: Example: meillo@223: .nf meillo@0: map_return_path_addresses = "john: ; charlie: " meillo@223: .fi meillo@0: meillo@0: You can use patterns, eg. * as keys. meillo@34: meillo@0: .TP meillo@34: \fBexpand_h_sender_address\fR = \fIboolean\fR meillo@0: meillo@34: This sets the domain of the sender address as given by the Sender: header meillo@34: to the same address as in the envelope return path address meillo@34: (which can be set by either \fBset_return_path_domain\fR or \fBmap_return_path_addresses\fR). meillo@34: This is for mail clients (eg. Microsoft Outlook) which use this address as the sender address. meillo@34: Though they should use the From: address, see RFC 821. meillo@34: If \fBfetchmail(1)\fR encounters an unqualified Sender: address, meillo@34: it will be expanded to the domain of the pop server, which is almost never correct. meillo@34: Default is true. meillo@0: meillo@0: .TP meillo@34: \fBexpand_h_sender_domain\fR = \fIboolean\fR meillo@0: meillo@34: Like \fBexpand_h_sender_address\fR, but sets the domain only. meillo@34: Deprecated, will be removed in a later version. meillo@0: meillo@34: meillo@0: .SH AUTHOR meillo@0: meillo@34: Masqmail was written by Oliver Kurth. meillo@34: It is now maintained by Markus Schnalke . meillo@0: meillo@95: You will find the newest version of masqmail at \fBhttp://marmaro.de/prog/masqmail/\fR. meillo@26: There is also a mailing list, you will find information about it at masqmail's main site. meillo@0: meillo@34: meillo@0: .SH BUGS meillo@0: meillo@34: Please report bugs to the mailing list. meillo@0: meillo@0: .SH SEE ALSO meillo@0: meillo@192: \fBmasqmail(8)\fR, \fBmasqmail.conf(5)\fR