chasquid.conf(5)

💖 chasquid.conf(5) 💖

okay bestie, gather round, because this is the manual page for chasquid.conf(5) — the main configuration file for chasquid(1), and yes it's exactly as iconic as it sounds. 🌸

---

✨ SYNOPSIS ✨

chasquid.conf(5) is chasquid(1)'s main configuration file.

fr fr that's the whole synopsis. short and slay. 💅

---

🌈 DESCRIPTION 🌈

okay so the file is in protocol buffers' text format — that's the vibe, that's the format, no cap. 📝

Comments start with #. Empty lines are allowed, we love a breather. 🫶 Values are of the form key: value. Values can be:

• strings (quoted)
• integers
• booleans ("true" or "false")

Some values might be repeated, for example the listening addresses. the way that some keys just get to appear multiple times… main character energy honestly. 👑

---

💅 OPTIONS 💅

bestie this is the long part, hydrate first. 🍓

• hostname (string) — Default hostname to use when saying hello. This is used to say hello to clients (for aesthetic purposes 💖), and as the HELO/EHLO domain on outgoing SMTP 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.
• max_data_size_mb (int) — Maximum email size, in megabytes. Default: 50.
• smtp_address (repeated string) — Addresses to listen on for SMTP (usually port 25). Default: "systemd", which means systemd passes sockets to us. systemd sockets must be named with FileDescriptorName=smtp.
• submission_address (repeated string) — Addresses to listen on for submission (usually port 587). Default: "systemd", which means systemd passes sockets to us. systemd sockets must be named with FileDescriptorName=submission.
• submission_over_tls_address (repeated string) — Addresses to listen on for submission-over-TLS (usually port 465). Default: "systemd", which means systemd passes sockets to us. systemd sockets must be named with FileDescriptorName=submission_tls.
• monitoring_address (string) — Address for the monitoring HTTP server. Do NOT expose this to the public internet. 😭 Default: no monitoring server.

the way this one is in ALL CAPS in spirit — do NOT expose monitoring_address to the public internet. that's not a vibe, that's a whole incident. 💀

• mail_delivery_agent_bin (string) — Mail delivery agent (MDA, also known as LDA) 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: maildrop.
• mail_delivery_agent_args (repeated string) — Command line arguments for the mail delivery agent. One per argument. Some replacements will be done. 🧚

On an email sent from marsnik@mars to venera@venus:

• %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)

Default: "-f", "%from%", "-d", "%to_user%" (adequate for procmail and maildrop).

• data_dir (string) — Directory where we store our persistent data. Default: /var/lib/chasquid.
• suffix_separators (string) — Suffix separator, to perform suffix removal of local users. For example, if you set this to "-+", email to local user "user-blah" and "user+blah" will be delivered to "user". Including "+" is strongly encouraged, as it is assumed for email forwarding. Default: "+".
• drop_characters (string) — Characters to drop from the user part on local emails. For example, if you set this to "._", email to local user "u.se_r" will be delivered to "user". Default: ".".
• mail_log_path (string) — Path where to write the mail log to. If "<syslog>", log using the syslog (at "MAIL|INFO" priority). If "<stdout>", log to stdout; if "<stderr>", log to stderr. Default: "<syslog>".
• dovecot_auth (bool) — Enable dovecot authentication. If true, users that are not found in chasquid's databases will be authenticated via dovecot. Default: "false".

The path to dovecot's auth sockets is autodetected, but can be manually overridden using the "dovecot_userdb_path" and "dovecot_client_path" if needed.

• haproxy_incoming (bool) — If true, expect incoming SMTP connections to use the HAProxy protocol. This allows deploying chasquid behind a HAProxy server, as the address information is preserved, and SPF checks can be performed properly. Default: "false".
• max_queue_items (int) — EXPERIMENTAL, might change in backwards-incompatible ways. 🚨

Maximum number of items in the queue.

If we have this many items in the queue, we reject new incoming email. Be careful when increasing this, as we keep all items in memory. Default: 200 (but may change in the future).

ngl, max_queue_items is flagged EXPERIMENTAL, so it might change in backwards-incompatible ways, and it holds everything in memory — be careful when increasing it. 💛

• give_up_send_after (string) — EXPERIMENTAL, might change in backwards-incompatible ways. 🚨

How long do we keep retrying sending an email before we give up. Once we give up, a DSN will be sent back to the sender.

The format is a Go duration string (e.g. "48h" or "360m"; note days are not a supported unit). Default: "20h" (but may change in the future).

---

👀 SEE ALSO 👀

• chasquid(1)

---

and that's the whole thing bestie, you ate. 💖✨

this was chasquid.conf(5), dated 2025-06-07 — same manual name, same date, just delivered with ✨aura✨. go configure something gorgeous. 🎀🦋💜