RENATTACH(1)

📦 version 1.2.4, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 RENATTACH 💖 — from the General Commands Manual section, bestie

okay so picture this: you're a mail server, people keep sending each other worms dressed up as invoice.pdf.exe, and you need a bodyguard. that's renattach. it's a renattach (1) page, it lives in the General Commands Manual, and it is lowkey one of the most useful little UNIX tools ever. let's get into it 🦋

✨ NAME ✨

renattach — rename/delete dangerous email attachments 💅

✨ SYNOPSIS ✨

renattach [OPTIONS]

that's it. that's the whole vibe. options only, no positional args, she's clean like that ✨

✨ DESCRIPTION ✨

okay so renattach is a fast and efficient UNIX stream filter that can rename or delete potentially dangerous e-mail attachments. it is a highly effective way of protecting your end-users from harmful mail content (worms/viruses) by disabling or removing attachments that might get accidentally executed by users. no cap. 🛡️

the filter gets invoked as a simple pipe, so it slots into a wide variety of systems. and the kill feature — which eliminates entire messages, like, gone, poof — can also help sites deal with resource strains caused by modern virus floods. 🙈

renattach is written in pure C and can quickly process mail with little overhead. she's fast. 💨

and here's the thing — unlike a conventional virus scanner, there are no specific virus or worm definitions. instead, renattach identifies potentially dangerous attachments based on file extension and executable encoded body content. and the software is even capable of reading filenames from inside ZIP archives on the fly, without requiring any external software. not me being self-contained and iconic 😭

the self-contained MIME code parses, fully interprets, then rewrites the header of every attached file. during this process it checks the file's extension against a list, and further checks to make sure the filename is not on a banned list. only after passing through these steps is the MIME header written fresh using a predetermined, known format. like, she doesn't trust the original header at all, she writes a new one. queen behavior 👑

the program's operation is simple: a single mail message is read from stdin, filtered, then written to stdout (or piped to an external command).

renattach looks for its configuration file (renattach.conf) in the path specified at compile time. alternatively, you can specify the location of renattach.conf by using the -c command-line options. for example:

renattach -c renattach.conf

✨ OPTIONS ✨

🚨 okay bestie, listen. the filter's default behaviour is to rename dangerous attachments that match the badlist — {mode=badlist, action=rename}. BUT. if you're searching inside ZIP archives for filenames (see the search_zip configuration option), the only actions that modify the ZIP files are delete and kill but NOT rename. so the default rename action has no effect on ZIP files. instead, use the --delete or --kill options. or, alternatively, append the /d and /k switches to badlist extensions in the .conf file to selectively delete or kill some file types while just renaming the rest. periodt. 💅
  • -a, --all — Filter mode: match all attachments. every single one. no skipping 🫶
  • -b, --badlist — Filter mode: only match filenames that have extensions listed on the bad-list. this will match only attachments with known dangerous file extensions. this is the default ✨
  • -c, --config filename — use the specified configuration file. run renattach with --settings to verify the current settings. (yes, verify. always verify. trust but check, bestie 🔍)
  • -d, --delete — Filter action: delete attachment body after renaming headers. bye bye 👋
  • -e, --excode — extend exitcodes with a new code, 77=filtering occurred. see below for standard exit codes ⬇️
  • -g, --goodlist — Filter mode: match all attachments except those that have extensions listed on the goodlist. inverse girlie 🌈
  • -h, --help — show help, explain options. the classic 🎀
  • -k, --kill — Filter action: kill (absorb) the entire email. there is null output. nothing survives. 💀
  • -l, --loop — remove Delivered-To headers to prevent malicious mail forwarding loop. this can prevent Postfix from inadvertently relaying spam.
⚠️ careful!! this option must only be used when renattach is a filter service to the outside world, otherwise you will lose loop protection. do not use from procmail. fr fr, this one has consequences 😭
  • -p, --pipe command [args] — instead of writing output to stdout, open pipe to command (with args) and send output there. this program must return with exit code 0. this must be the last option on the command line. see the INSTALL file for instructions on integrating with Postfix as a filter service 🔌
  • -r, --rename — Filter action: rename matching attachments (default). the MIME type is also renamed to new_mime_type from the .conf file ✨
  • -s, --settings — show current settings/configuration and terminate. peek behind the curtain 👀
  • -v, --verbose — write verbose output (including settings) to stderr 📢
  • -V, --version — display software version and terminate. the flex 💅

✨ EXIT CODES ✨

  • 0 — Success (filtered mail and wrote output) ✅
  • 75 — Temporary failure (resource shortage; failed to write to pipe if using --pipe) 😵
  • 255 — Critical failure (improper parameters; bad .conf file) 💀

the temporary failure code allows MTAs to re-queue mail for later delivery. these exit codes are compatible with BSD-style mailers, and --excode should not be used without good reason because it returns a non-success code when the filter "catches" something. like, it works, but it's telling the MTA something different than the default behavior does. iykyk 🧚

🎀 CONFIGURATION FILE 🎀

okay so bestie, the .conf file? it's giving plaintext, and the vibe is one configuration directive per line. that's the whole thing. any line that's a comment — anything with a # in front of it — gets ignored, so go ahead and scribble notes to yourself, it's fine 💅

some directives can only appear once (one and done, main character only), but the others are lists, and lists are additive — they stack, they accumulate, they keep showing up 💖

and here's the iconic part: the conf file itself is optional, and so is literally every directive in it, because defaults are compiled straight into the software. so like… you can rawdog it with zero config and renattach will still do its thing 🦋

NOTE: please run renattach --settings to verify your configuration! no cap, do this. fr fr. 🙏

💜 Description of all options 💜

here's the whole menu, bestie. every single one. i'm not skipping a thing 👑

# renattach 1.2.4 recognizes the following configuration directives.

  • delete_exe — deletes executable binary attachments by signature. renattach goes looking for encoded bytes that identify DOS/Windows executables ('MZ'). if an executable is found, the encoded attachment gets removed while the MIME header stays unchanged. this is a feature that works independently of filename-based filtering — it's designed as a backup. net effect: encoded executables are deleted. specify yes or no, or alternatively 1 or 0.
# delete_exe = yes
  • kill_exe — kills executable binary attachments by signature, exactly like the previous directive. ⚠️ note that delete_exe and kill_exe are mutually exclusive — pick one, bestie, you cannot have both.
# kill_exe = no
  • search_zip — searches for filenames within ZIP archives using the internal ZIP parsing engine (no external software required, we're self-sufficient 💅). any filenames found are subject to the same checks, for instance badlist or goodlist, with the notable difference that the RENAME ACTION HAS NO EFFECT on ZIP files. only the delete or kill actions will modify ZIP files.
# search_zip = no
  • pass_contentid — normally, MIME Content-ID fields are dropped during filtering due to their application-specific use and security risk (recently used by worms to link malicious code to embedded images 😭). if you are sure you want to pass Content-ID fields unfiltered, enable this option.
# pass_contentid = no
  • full_rename — normally, all periods in filenames are replaced with underscores during renaming. although this is the recommended mode, you can also disable full renaming if you only want the last period to be changed to an underscore.
# full_rename = yes
  • use_syslog — if enabled, all filtering actions will be logged via syslog. renattach logs with priority 'warning' to facility 'mail'.
# use_syslog = no
  • generic_name — a generic filename to use when parsing fails. since renattach rewrites all attachment headers, it's possible that corruption, lack of buffer space, or some other problem will prevent filenames from being recreated. in such a case, this generic name is used. (a little fallback bestie, a safety net 🫶)
# generic_name = filename
  • new_extension — a replacement file extension to use when changing dangerous attachment filenames. this extension is appended to the previous one. for instance virus.pif becomes virus_pif.bad. specify just # to leave the extension as is, and not rename it.
# new_extension = bad
  • new_mime_type — when attachments are renamed, the MIME type is also changed to this new_mime_type for safety.
# new_mime_type = application/unknown

the following directives control how the message Subject is modified to inform the user that filtering has occurred. they have the following ORDER OF PRIORITY (starting with highest): subj_banned, subj_exec, subj_deleted, subj_renamed, add_subject.

by default, only add_subject is defined, so any condition (whether it's a ban, executable match, delete, or rename) results in the same Subject addition. if you also define subj_exec then there could be a different Subject if an executable was caught (since it has higher priority than add_subject). another alternative for these options is to specify the single character # to suppress Subject modification for that condition. you could use this to be quiet in case a banned attachment is caught. you can also use # to turn off add_subject, hence NEVER modify the message Subject. silence, iconic, mysterious 😌

  • subj_banned — add text to Subject if an attachment is caught by banned_files, shown here in suppression mode to NOT inform user on file ban.
# subj_banned = #
  • subj_exec — add text to Subject if an attachment is caught by delete_exe.
# subj_exec = [removed executable]
  • subj_deleted — add text to Subject if an attachment is deleted for any reason.
# subj_deleted = [deleted attachment]
  • subj_renamed — add text to Subject if an attachment is renamed for any reason.
# subj_renamed = [renamed attachment]
  • add_subject — add text to Subject if an attachment is filtered in any way. this has the lowest priority, and is only used if the previous ones are undefined. use the single character # to suppress addition to Subject.
# add_subject = [filtered]
  • htmlwarn_pos — when inserting a warning into HTML parts of messages (warning_html), this tag defines the preferred position to insert the new HTML. if the first tag in the list is found, the warning position is placed just after this tag. as subsequent tags are found, the position advances after each.
# htmlwarn_pos = html, body
  • warning_text — if an attachment is filtered, this lets you specify some warning text that will be inserted into any plain text portion(s) of the email. this is effective for informing users of filtered files, but the act of inserting arbitrary text into an email can cause new problems. use with caution. ⚠️
# warning_text =    *******************
# warning_text =    MAIL SYSTEM WARNING
# warning_text =    Attachments removed
# warning_text =    *******************
  • warning_html — inserts a warning message into HTML portions of the email when filtering occurs. the HTML is inserted at a position determined by htmlwarn_pos (see above) which provides a good hope for adding a visible warning. unfortunately, inserting arbitrary HTML is tricky due to the complexity of markup interactions. inserting warnings in HTML may thoroughly disrupt the original message, so use with caution. 😬
# warning_html =    <h1>Mail system warning<h1>
# warning_html =    <h2>Attachments removed</h2>
  • add_header — when enabled, these new headers will be added to the message to inform the user about filtering that occurred.
# add_header = X-Filtered-0:  *** PLEASE NOTE ***
# add_header = X-Filtered-1:  Potentially dangerous attachments have been
# add_header = X-Filtered-2:  found in this e-mail, and have either been
# add_header = X-Filtered-3:  renamed or deleted for your safety.
  • banned_files — catches specifically named, banned attachment filenames and optionally takes an action (r=rename, d=delete, k=kill). this is an additive option so there is no limit to how many names can be specified. if the name begins with a forward slash ('/'), this substring has to be found; '/foo' matches 'foobar' and 'eatfoo'. otherwise, the whole name has to match. specify case-insensitive filenames separated by commas. to specify an action on a matching filename, append /r (rename), /d (delete), or /k (kill) to the filename as illustrated in the example.
# banned_files = your_details.zip/r, your_details.pif/k
# banned_files = movie.pif/d, movie.zip, /winmail/d
  • goodlist — a list of good (known-safe) attachment file extensions to use in goodlist filtering mode. this is an additive option, so there is no limit to how many filenames can be specified. specify case-insensitive extensions separated by commas.
# goodlist = DOC, PDF, RTF, SXC, SXW, TXT, ZIP
  • badlist — a list of bad (known-dangerous) attachment file extensions to use in badlist filtering mode. this is an additive option, so there is no limit to how many filenames can be specified. specify case-insensitive extensions separated by commas. to specify an action for an extension, append /r (rename), /d (delete), or /k (kill) to the filename. this overrides the default action for the filter and can be used to provide special handling for some extensions. an additional switch can be used to specify an action only for files found within ZIP archives. for instance, EXE/k/d tells the filter to kill emails containing EXE attachments, but if the EXE was found inside a ZIP then the attachment is deleted, not killed. (so specific. so precise. we love a nuanced queen 👑)
# badlist = ADE, ADP, BAS, BAT, CHM, CMD, COM, CPL, CRT, EML, EXE
# badlist = HLP, HTA, HTM, HTML, INF, INS, ISP, JS, JSE, LNK, MDB
# badlist = MDE, MSC, MSH, MSI, MSP, MST, NWS, OCX, PCD, PIF, REG
# badlist = SCR, SCT, SHB, SHS, URL, VB, VBE, VBS, WSC, WSF, WSH

🌸 FILES 🌸

  • renattach.conf — yeah that's the one, bestie 💖

🦋 SEE ALSO 🦋

💀 WARRANTY 💀

okay so legally speaking, bestie, we gotta be real with you:

as per the GNU GPL, there is no warranty for this software. the author makes no guarantees as to software performance or effectiveness. 😭

renattach is NOT a virus scanner. read that again. it is not a virus scanner, no cap.

filtering is based on MIME headers and detectable filenames; as such, the software tries to handle both correct structures and incorrectly formatted messages. this filter will not catch all dangerous emails, particularly attachments embedded inside attachments. so like… stay alert, diva. it's a filter, not a bodyguard 💅

🎀 AUTHOR 🎀

Copyright (C) 2003-2006 Jem E. Berkes <jberkes@pc-tools.net>

http://www.pc-tools.net/unix/renattach/

http://www.sysdesign.ca/

and that's a wrap on renattach, bestie — page RENATTACH(1), dated October 2006, the era of the original 📅. you read the whole thing, you understood the whole thing, and honestly? that's giving scholar energy. slay, go filter something responsibly 🫶✨💖

📦 where this page comes from