GNARWL(8)

💖 GNARWL 💖 — the gnarwl(8) page, but make it make sense

okay bestie, welcome to the System Manager's Manual section, because this one is filed under gnarwl(8). it's a system-administrator-flavored page, so grab a lil snack and let's go 🍓

---

✨ NAME ✨

gnarwl — GNU Neat Autoreply With LDAP

---

🌸 SYNOPSIS 🌸

gnarwl [-h] [-c <cfgfile>] [-a <address>] [-s <address>]

---

🦋 DESCRIPTION 🦋

gnarwl is an email autoresponder, and it's literally the glow-up successor to the old vacation(1) program. here's the tea: a modern mailserver is out here serving hundreds (or even thousands) of mailaccounts, so it's just not sensible to hand (untrusted) users shell access just so they can create and maintain the .forward file that vacation(1) needs. like, why.

with gnarwl, all user-supplied data lives inside an LDAP database instead, so there are no per user ".forward" files (or even homedirs, bestie, none) needed. configuration is conveniently done via one systemwide configfile. iconic behavior honestly.

and just like the old vacation(1) program, gnarwl accepts incoming mail through stdin, and will send outgoing mail via an external MTA. it even maintains basic commandline compatibility, so it may be used as a drop in replacement. the range?? unmatched.

several gdbm databases are maintained, and their whole job is to make sure that:

• a) mail does not bounce back and force between gnarwl and another automated MUA,
• b) mailing lists will not be bothered, and
• c) specific local addresses may never produce automatic replies.

all these database files may be managed using the damnit(8) program. 💅

---

🎀 OPTIONS 🎀

• -c <cfgfile> — use a different configfile than the one that's compiled in. go off, custom config.
• -a <alias> — force <address> as receiving address.
• -s <address> — force <address> as sending address.
• -h — print usage information. the classic cry for help, and honestly, same.

---

👑 CONFIGURATION 👑

gnarwl typically uses one global configurationfile, but a per user setup is also possible using the -c commandline switch. the following keywords are recognized in the configfile:

• map_sender <macroname> — binds a macroname (case insensitive), referring to the sender of an incoming email. defaults to "$sender".
• map_receiver <macroname> — binds a macroname (case insensitive), referring to the receiver(s) of an incoming email. defaults to "$receiver".
• map_subject <macroname> — binds a macroname (case insensitive), referring to the subject of an incoming email. defaults to "$subject".
• map_field <ldapattribute> <macroname> — binds a macroname (case insensitive), referring to a field in the resultset, returned by the database. there are no defaults for this directive.
• server_uri <ldap_uri [ldap_uri ...]> — URI of the databaseserver to query. multiple URIs can be specified. no default value.
• starttls <0|1> — enforce StartTLS on connect. defaults to 0.
• ca_cert </path/to/certificate> — use specified CA cert to validate ldap server certificate. no default value.
• server <address> — address of the databaseserver to query. defaults to localhost.
• port <portnumber> — port, the LDAP server listens on. defaults to 389.
• scope <base|one|sub> — the scope used for searching the database. default is "sub".
• login <string> — destinguished name to bind with to the LDAP database. default is to bind anonymously.
• password <string> — password to use for binding to the LDAP database. if a password is required to access the server, then the configfile should belong to the gnarwl user and have file permission 0400.

okay bestie, that 0400 is not a suggestion. it's the whole vibe check. 🔒

• base <destinguished name> — entrypoint of the search. there is no default for this directive, it must be supplied by the administrator.
• protocol <2|3> — select protocol to bind to the ldapserver. the default is 3.
• queryfilter <ldap queryfilter> — search pattern to match against the database. defaults to: "(&(mail=$recepient)(vacationActive=TRUE)".
• result <ldap attribute> — the name of the attribute, that is to be taken as the emailbody. the content of this field will be pasted in between the data found via forceheader and forcefooter directives. afterwards all remaining macros are expanded in the order of declaration, and the result will be piped through to the MTA.
• blockfiles <directory> — the directory, where gnarwl stores it's blockfiles. these files are required to keep track on who was sent an automatic reply. default is: "/var/lib/gnarwl/block/".
• umask <mode> — what permission to give newly generated database files. the default is 0600.
• blockexpire <number> — how long (in hours) to block a certain sender/recepient combo. default is 48 hours. setting <number> to 0 disables the feature (not recommended). no blockfiles are read/written in this case.
• maxreceivers <number> — ignore incoming email, specifying too many receiving addresses. it does not matter, whether these are local or not, as gnarwl doesn't know domains. default is 256.
• maxheader <number> — ignore incoming email with more than this number of header lines. lines are counted before unfolding them, so a folded line really counts as at least two lines. default is 256.
• badheaders <filename> — path to a database file, containing matching patterns for the mailheader. if an entry stored in this file matches a line in the header exactly, then this mail will be ignored by gnarwl. (useful to avoid sending automatic replies to mailing lists). this feature is deactivated by default.
• blacklist <filename> — pointer to a database file, containing emailaddresses, gnarwl is not allowed to generate automatic replies for (useful to prevent automatic replies from addresses, which are shared by several people). this feature is deactivated by default.
• forceheader <filename> — path to a text file, containing a standardized header, that is to be pasted in front of every outgoing mail. this file should end with a single empty line. otherwise it is assumed, that the users are allowed to continue the header and will provide the separating empty line themselves. default is not to force anything (that is: the user has to supply the header in the "result" attribute).
• forcefooter <filename> — path to a text file, containing a standardized footer, that is to be appended at the end of every generated mail. default is to not to force anything.
• mta <prog> [<args>] — specify MTA for sending mail. it must be able to accept mail on STDIN. default is "/usr/sbin/sendmail".
• charset <encoding> — LDAP stores text in unicode, which is ok, as long as outgoing mail doesn't contain any non ASCII characters. however, locale specific characters (like german umlaute) end up as strange glyphs. with the "charset" directive, gnarwl tries to convert these to the correct symbols. the <encoding> argument must contain a string recognized by iconv(3). default is not to try to convert anything (assume US-ASCII charset / MIME encoded mail).
• recvheader <string> — a whitespace separated list of headers (case does not matter), which may contain receiving addresses. defaults to: "To Cc".
• loglevel <0|1|2|3> — specifies what to send to the syslog. a higher loglevel automatically includes all lower loglevels (see section syslog for more information).
• deref <never|search|find|always> — controls what LDAP alias dereferencing will be performed. default is "find".

---

🌈 SYSLOG 🌈

since gnarwl is not meant to be invoked by anything but the mailsystem, it'll never print out messages to the systemconsole, but logs them via syslog(3), using the facility "mail". a log line is always of the following format:

<level>/<origin> <message>

the <level> field indicates the severity of the message, it corresponds to the "loglevel" config directive. possible values are:

• CRIT (loglevel 0) — critical messages. gnarwl cannot continue and will die with a non-zero exit code. this usually causes the mailsystem to bounce mail. 💀

yeah, non-zero exit code, that's a whole situation. the mail gets bounced. no cap.

• WARN (loglevel 1) — a warning. gnarwl can will continue, but not with the full/intended functionality.
• INFO (loglevel 2) — status information. a message in the INFO loglevel indicates normal behaviour.
• DEBUG (loglevel 3) — debugging information. gnarwl will log a lot of information on how mail is processed.

the <origin> field gives a short hint about what caused the log entry in question, while <message> contains a short description of what actually happened. so like, <level> = how bad, <origin> = who did it, <message> = the group chat receipt. 💬

---

🧚 AUTHOR 🧚

Patrick Ahlbrecht <p.ahlbrecht@billiton.de>

---

⭐ SEE ALSO ⭐

vacation(1), postfix(1), iconv(1), damnit(8), rfc822

---

💜 FILES 💜

• /etc/gnarwl.cfg — main configuration file.
• /var/lib/gnarwl/.forward — forward file for the mailsystem.
• /var/lib/gnarwl/blacklist.db — gnarwl won't send an autoreply for anyone whose emailaddress is listed herin.
• /var/lib/gnarwl/badheaders.db — gnarwl will ignore mail, it is able to match a headerline with an entry in this file. case is significant, no wildcards are expanded.
• /var/lib/gnarwl/header.txt — standard header to paste in front of every outgoing mail.
• /var/lib/gnarwl/footer.txt — standard footer to append to every outgoing mail.
• /var/lib/gnarwl/block/* — block files.

---

and that's the whole page, bestie 💅 that was the gnarwl(8) page from the System Manager's Manual, and yeah, the footer is just GNARWL(8) again because the page came from the System Manager's Manual and that's the name we're signing off with. slay, go configure your LDAP, and remember: 0400 on that password file. mwah 🫶✨