masqmail.route(5)

📦 version 0.3.4, in ubuntu jammy

💖 NAME 💖

masqmail.route — masqmail route configuration file

okay so this is masqmail.route(5), filed under File Formats in section 5, and it's literally the whole vibe guide for masqmail's route config files 🎀

✨ DESCRIPTION ✨

bestie, this page spills all the tea on the syntax of the route configuration files for masqmail(8). Their usual hangout spots are in /etc/masqmail/ 📁

Mail gets sent with the SMTP protocol to its destination, unless pipe is given. In that case, the message gets piped straight to the given program instead 🚰

🎀 ROUTE CONDITIONS 🎀

  • allowed_senders = list — this is a semicolon ; separated list of envelope sender addresses. Messages that have one of these addresses as the return path (= mail from) are allowed to use this route — as long as they're not also in denied_senders. Glob patterns containing ? and * can be used. The special item <> matches the null sender address (eg. failure notices or delivery notifications). If the pattern doesn't contain an @, it's seen as a pattern for the local part only.

Example: meillo;*@*example.org;web*@example.com

(meillo equals meillo@*, i.e. the local part.)

  • denied_senders = list — this is a semicolon ; separated list of envelope sender addresses. Messages that have one of these addresses as the return path (= mail from) will not be sent using this route (even if they're also in allowed_senders). Glob patterns containing ? and * can be used. The special item <> matches the null sender address (eg. failure notices or delivery notifications). If the pattern doesn't contain an @, it's seen as a pattern for the local part only.

Example: (see allowed_senders)

  • allowed_recipients = list — a list of envelope recipient addresses where mail can be sent to using this route. This is, for example, useful if you use this route configuration when connected to another LAN via ppp 🖇️ Glob patterns containing ? and * can be used.

Example: *@example.org;*@*foo.bar

(See also examples for allowed_senders)

  • denied_recipients = list — a list of envelope recipient addresses where mail will not be sent to using this route. This is, for example, useful if you send mail directly (mail_host is not set) and you know of hosts that won't accept mail from you because they use a dialup list (eg. http://maps.vix.com/dul/). denied_recipients overrules allowed_recipients. Glob patterns containing ? and * can be used.

Example: *@spamblocker.example.org

(See also examples for allowed_senders)

  • last_route = boolean — if this is set, a mail which would have been delivered using this route, but has failed temporarily, will not be tried to be delivered using the next route. If you've set up a special route with filters using the lists allowed_recipients and allowed_senders or their complements (denied_), and the mail passing these rules should be delivered using this route only, you should set this to true. Otherwise the mail would be passed to the next route (if any), unless that route has rules which prevent that.

Default is false.

  • connect_error_fail = boolean — if this is set, a connection error (or if a pipe command could not be executed) will cause a mail delivery to fail, ie. it will be bounced. If it's unset, it will just be defered.

Default is false. The reason for this is that masqmail is designed for non permanent internet connections, where such errors may occur quite often, and a bounce would be annoying 😭

You probably want to set this to true for permanent routes.

💅 SMTP CONFIGURATION 💅

  • mail_host = string — this is preferably the mail server of your ISP. All outgoing messages will be sent to this host which will distribute them to their destinations. If you do not set this, mails will be sent directly. Because the mail server is probably near to you, mail transfer will be much faster if you use it ⚡

You can optionally give a port number following the host name and a colon, eg mail_host="mail.foo.com:25".

  • resolve_list = list — specify the method how the domain of the server is resolved. Possible values are dns_mx, dns_a, byname. For dns_mx, the domain is assumed to be an MX pointer to a list of host names, these will be tried each in order (lowest preference value first, equal preference values in random order). For dns_a, the domain is assumed to be an A pointer. For byname, the library function gethostbyname(3) will be used.

For routes to a local network, where you likely don't have a DNS service, use only byname.

The default is "dns_mx;dns_a;byname".

  • helo_name = string — set the name given with the HELO/EHLO command. If this is not set, host_name from masqmail.conf will be used, if the do_correct_helo option (see below) is unset.
  • do_correct_helo = boolean — if this is set, masqmail tries to look up your host name as it appears on the internet and sends this in the HELO/EHLO command. Some servers are so picky that they want this. Which is really crazy 💀 It just does not make any sense to lie about ones own identity, because it can always be looked up by the server. Nobody should believe in the name given by HELO/EHLO anyway. If this is not set, host_name from masqmail.conf or as given with the helo_name (see above) will be used.
  • instant_helo = boolean — if this is set, masqmail does not wait for the greeting of the SMTP server after opening the connection. Instead it says EHLO right away (ESMTP is assumed). Use this option with wrappers that eat the 220 greeting of the SMTP server. Common examples are STARTTLS wrappers, like openssl s_client -starttls smtp ....

If this option is set and a 220 greeting is received though, everything should still work. Please don't rely on that and keep in mind that RFC 2821 says that the client SHOULD wait for the 220 greeting of the server.

Default: false

  • do_pipelining = boolean — if this is set to false, masqmail will not use ESMTP PIPELINING, even if the server announces that it is able to cope with it. Default is true.

You do not want to set this to false unless the mail setup on the remote server side is really broken. Keywords: wingate.

  • auth_name = string — set the authentication type for ESMTP AUTH authentication. Currently only cram-md5 and login are supported.
  • auth_login = string — your account name for ESMTP AUTH authentication.
  • auth_secret = string — your secret for ESMTP AUTH authentication.
  • wrapper = command — if set, instead of opening a connection to a remote server, command will be called and all traffic will be piped to its stdin and from its stdout. Purpose is to tunnel ip traffic, eg. for ssl 🛡️

Example for SMTP over SSL tunneling:

wrapper="/usr/bin/openssl s_client -quiet -connect mail.gmx.net:465 2>/dev/null"

SMTP over SSL is supported since masqmail-0.1.8. It is marked obsolete by the IETF but is still in use.

Example for encryption with STARTTLS (RFC-3207):

# don't forget the instant_helo, otherwise it won't work
instant_helo=true
wrapper="/usr/bin/openssl s_client -quiet -starttls smtp -connect mail.gmx.net:25 2>/dev/null"

This is supported since masqmail-0.2.28. STARTTLS supersedes SMTP over SSL.

Note for openssl: Ensure that stderr is redirected. Do not use -crlf in the wrapper command, because masqmail does already insert CRLF. However, you might want to specify -crlf if you want to test your wrapper command interactively on the command line.

🧚 PIPE CONFIGURATION 🧚

  • pipe = command — command will be called and the message will be piped to its stdin. Purpose is to use gateways to uucp, fax, sms or whatever else 📠

You can use variables to give as arguments to the command, these are the same as for the mda in the main configuration, see masqmail.conf(5).

  • pipe_fromline = boolean — only if pipe is used. A from line will be prepended to the output stream whenever a pipe command is called. Default is false.
  • pipe_fromhack = boolean — only if pipe is used. Each line beginning with From is replaced with >From whenever a pipe command is called. You probably want this if you have set pipe_fromline above. Default is false.

✨ ADDRESS REWRITE RULES ✨

okay bestie this is the section where we make your addresses cute AND correct 💅 because sometimes the address you send from on your LAN is NOT the address the internet needs to see, and mail servers will absolutely side-eye you for it 🫶

💌 the options, one by one, no skips

  • set_h_from_domain = string — swaps out the domain part inside your From: headers for this value. super handy if you're rocking a private address on your local LAN that the outside world has never heard of, and you want it replaced by the domain of your real internet email address. ⚠️ heads up: this is not the same thing as set_return_path_domain, which is a whole separate option further down, okay?
  • set_h_reply_to_domain = string — literally the exact same idea as set_h_from_domain, but it does its thing on the Reply-To header instead. 🎀
  • set_return_path_domain = string — sets the domain part of the envelope from address. here's the tea: some hosts check whether this matches the net the connection is coming from, and if it doesn't, they just reject your mail because they think you're spamming 😭. it should also be a valid address, because some mail servers check that too. you can also use this to set your usual internet address while keeping a local-only LAN address in your mailer's config. only the domain part gets changed — the local part stays exactly as it is. use map_return_path_addresses if you need to rewrite local parts instead. ✨
  • map_h_from_addresses = list — like set_h_from_domain but way more flexible. set it to a list that maps local parts to full RFC 822 compliant email addresses. the local parts (the keys) and the addresses (the values) are separated by colons (:).

Example:

map_h_from_addresses = "john: John Smith <jsmith@mail.academic.edu>; charlie: Charlie Miller <cmiller@mx.commercial.com>"

you can use patterns as keys too, eg. *. 🌸

  • map_h_reply_to_addresses = list — same as map_h_from_addresses, but for the Reply-To: header. 💖
  • map_h_mail_followup_to_addresses = list — same as map_h_from_addresses, but for the Mail-Followup-To: header. obsessed with this one if you reply to mailing lists a lot. 🧚
  • map_return_path_addresses = list — the flexible sibling of set_return_path_domain. set it to a list mapping local parts to full RFC 821 compliant email addresses, keys and values split by colons (:). ⚠️ important detail bestie: this one takes RFC 821 addresses while map_h_from_addresses takes RFC 822 addresses. the biggest diff is that RFC 821 addresses have no full name. periodt.

Example:

map_return_path_addresses = "john: <jsmith@mail.academic.edu>; charlie: <cmiller@mx.commercial.com>"

patterns as keys work here too, eg. *. 🌈

  • expand_h_sender_address = boolean — this sets the domain of the sender address (the one from the Sender: header) to match the envelope return path address — which can come from either set_return_path_domain or map_return_path_addresses. it exists for mail clients (eg. Microsoft Outlook 👀) that use this address as the sender address, even though they should be using the From: address, see RFC 821. also: if fetchmail(1) runs into an unqualified Sender: address, it expands it to the domain of the pop server — which is almost never correct 💀. Default is true.
  • expand_h_sender_domain = boolean — like expand_h_sender_address, but it only sets the domain. 🚨 Deprecated — it will be removed in a later version, so don't get attached.

👑 AUTHOR

Masqmail was written by Oliver Kurth. It is now maintained by Markus Schnalke <meillo@marmaro.de>. 🫶

the newest version of masqmail lives at http://marmaro.de/prog/masqmail/. there's also a mailing list, and you'll find all the info about it on masqmail's main site. ✨

🐛 BUGS

please report bugs to the mailing list! fr fr, they wanna hear about it 🙈

🔍 SEE ALSO

and that's a wrap bestie 💖 this whole page is from masqmail-0.3.4, dated 2012-01-18 — go forth and rewrite those addresses, you absolute icon 👑✨

📦 where this page comes from