Description

This is a Sendmail utility milter that can add to the recipient list of any inbound and/or outbound message one or more blind-carbon-copy recipients (Bcc) depending on the MAIL FROM: and/or RCPT TO: addresses for any given message. This is particularly useful for mail hosts that manage several domains, such as an ISP.

For example, an ISP might host the mail for a client's business with several stores. Each store sends it's email via the ISP's SMTP server and the client's head-office would like to maintain a record of all correspondence with suppliers and/or store customers. Ensuring that each store's mail-client is configured to Bcc: head office is not reliable and difficult to alter. By centralising this on the ISP's SMTP server, all mail through the server for the business' domain can be blind-carbon-copy to another email address.

Another example, is an ISP could offer one or more individual client mail accounts the option to have all incoming email to their individual mailboxes blind-carbon-copy to a mailbox corresponding to their cell phone, so that they can be alerted and/or access mail while travelling.

While many of these things can be achieved using /etc/mail/aliases, ~/.forward files, procmail filters, or mailing list managers, there is some advantage to doing this during the SMTP session while the message is in transit.

Usage

milter-bcc [options ...][arguments ...]

Options can be expressed in four different ways. Boolean options are expressed as +option or -option to turn the option on or off respectively. Numeric, string, and list options are expressed as option=value to set the option or option+=value to append to a list. Note that the +option and -option syntax are equivalent to option=1 and option=0 respectively. String values containing white space must be quoted using single (') or double (") quotes. Option names are case insensitive.

Some options, like +help or -help, are treated as immediate actions or commands. Unknown options are ignored and not reported. The first command-line argument is that which does not adhere to the above option syntax. The special command-line argument -- can be used to explicitly signal an end to the list of options.

The default options, as shown below, can be altered by specifying them on the command-line or within an option file, which simply contains command-line options one or more per line and/or on multiple lines. Comments are allowed and are denoted by a line starting with a hash (#) character. If the file option is defined and not empty, then it is parsed first, followed by the command line options.

Note that there may be additional options that are listed in the option summary given by +help or -help that are not described here.

Options

access-db=/etc/mail/access.db

The type and location of the read-only access key-value map. It provides a centralised means to black and white list hosts, domains, mail addresses, etc. The following methods are supported:

text!/path/map.txt	R/O text file, memory hash
/path/map.db	Berkeley DB hash format
db!/path/map.db	Berkeley DB hash format
db!btree!/path/map.db	Berkeley DB btree format
sql!/path/database	An SQLite3 database
socketmap!host:port	Sendmail style socket-map
socketmap!/path/local/socket	Sendmail style socket-map
socketmap!123.45.67.89:port	Sendmail style socket-map
socketmap![2001:0DB8::1234]:port	Sendmail style socket-map

If :port is omitted, the default is 7953.

The access-db contains key-value pairs. Lookups are performed from most to least specific, stopping on the first entry found. Keys are case-insensitive.

An IPv4 lookup is repeated several times reducing the IP address by one octet from right to left until a match is found.

tag:192.0.2.9

tag:192.0.2

tag:192.0

tag:192

An IPv6 lookup is repeated several times reducing the IP address by one 16-bit word from right to left until a match is found.

tag:2001:0DB8:0:0:0:0:1234:5678

tag:2001:0DB8:0:0:0:0:1234

tag:2001:0DB8:0:0:0:0

tag:2001:0DB8:0:0:0

tag:2001:0DB8:0:0

tag:2001:0DB8:0:0

tag:2001:0DB8:0

tag:2001:0DB8

tag:2001

A domain lookup is repeated several times reducing the domain by one label from left to right until a match is found.

tag:[ipv6:2001:0DB8::1234:5678]

tag:[192.0.2.9]

tag:sub.domain.tld

tag:domain.tld

tag:tld

tag:

An email lookup is similar to a domain lookup, the exact address is first tried, then the address's domain, and finally the local part of the address.

tag:account@sub.domain.tld

tag:sub.domain.tld

tag:domain.tld

tag:tld

tag:account@

If a key is found and is a milter specific tag (ie. milter-bcc-Connect:, milter-bcc-From:, milter-bcc-Auth:, milter-bcc-To:), then the value is processed as a pattern list and the result returned. The Sendmail variants cannot have a pattern list. A pattern list is a whitespace separated list of pattern-action pairs followed by an optional default action. The supported patterns are:

[network/cidr]flist	Classless Inter-Domain Routing
!pattern!flist	Simple fast text matching.
/regex/flist	POSIX Extended Regular Expressions

The CIDR will only ever match for IP address related lookups.

A !pattern! uses an astrisk (*) for a wildcard, scanning over zero or more characters; a question-mark (?) matches any single character; a backslash followed by any character treats it as a literal (it loses any special meaning).

!abc!	exact match for 'abc'
!abc*!	match 'abc' at start of string
!*abc!	match 'abc' at the end of string
!abc*def!	match 'abc' at the start and match 'def' at the end, maybe with stuff in between.
!*abc*def*!	find 'abc', then find 'def'

The flist is a comma separated list of zero or more format-path strings described below. The right hand side value list is tested from left to right in order against the original string for which the milter tag applies ie. the full IP address, host name, MAIL FROM: or RCPT TO: arguments respectively.

Note that theflist can be replaced by the SKIP action (equivalent to an empty flist), which stops a lookup prematurely without returning a result. This can be useful to stop a lookup sequence early for special cases before it matches a more generic case later in the lookup sequence.

The flist can also be replaced by the SKIPALL action. This will behave just like SKIP for the current lookup and SKIP all other lookups to follow. An example:

milter-bcc-Connect:192.0.2.200	SKIPALL
milter-bcc-To:domain.com	%T%P@archiving.%D
Do not archive mail from 192.0.2.200, regardless of other rules.

A format-path string comprises of literal characters and percent-sign (%) prefixed format characters:

%%	A literal percent-sign (%)
%A	The original address, equivalent of %T%P@%D.
%D	The domain name portion.
%L	The left-hand-side of a plus-detailed address or the local part.
%P	The local-part. If %R is not empty, then "%L+%R", else "%L".
%R	The right-hand-side of a plus-detailed address or the empty string.
%S	The source-route, ie "@A,@B,@C", or the empty string.
%T	If %S is not empty, then "%S:", else the empty string.

Some format-path examples:

Address		Format	Result
user@example.com		%T%P@%D		user@example.com
user+detail@example.com		%P@%D		user+detail@example.com
user+detail@example.com		%L+bulk@%D		user+bulk@example.com
user+detail@example.com		bulk+%L@%D		bulk+user@example.com
user+detail@example.com		bulk+%R@%D		bulk+detail@example.com
user+detail@example.com		%P@bulk.%D		user+detail@bulk.example.com
@A,@B:user@example.com		%T%P@bulk.%D		@A,@B:user@bulk.example.com

Below is a list of supported tags. Other options may specify additional tags.

milter-bcc-Connect:client-ip	value
milter-bcc-Connect:[client-ip]	value
milter-bcc-Connect:client-domain	value
milter-bcc-Connect:	value
All mail from the client-ip, the unresolved [client-ip] address, or IP addresses that resolve to client-domain is blind-carbon-copied to one or more addresses as given by the value list.
milter-bcc-From:sender-address	value
milter-bcc-From:sender-domain	value
milter-bcc-From:sender@	value
milter-bcc-From:	value
milter-bcc-All:sender-address	value
milter-bcc-All:sender-domain	value
milter-bcc-All:sender@	value
milter-bcc-All:	value
All mail from the sender-address, sender-domain, or that begins with sender@ is blind-carbon-copied to the addresses constructed from the value list explained below. The milter-bcc-From: and/or milter-bcc-All: may be applied. In the case of a +detailed email address, the left hand side of the +detail is used for the sender@ lookup.
milter-bcc-Auth:auth_authen	value
milter-bcc-Auth:	value
All mail from the authenticated sender, as given by sendmail's {auth_authen} macro, is blind-carbon-copied to the addresses constructed from the value list explained above. The string searched by the pattern list will be the sender-address. The empty form of milter-bcc-Auth: allows for a milter specific default only when {auth_authen} is defined.
milter-bcc-To:recipient-address	value
milter-bcc-To:recipient-domain	value
milter-bcc-To:recipient@	value
milter-bcc-To:	value
milter-bcc-All:recipient-address	value
milter-bcc-All:recipient-domain	value
milter-bcc-All:recipient@	value
milter-bcc-All:	value
All mail from the recipient-address, recipient-domain, or that begins with recipient@ is blind-carbon-copied to the addresses constructed from the value list explained below. The milter-bcc-From: and/or milter-bcc-All: may be applied. In the case of a +detailed email address, the left hand side of the +detail is used for the recipient@ lookup.

Below are some examples of what is possible using patterns and format-paths:

milter-bcc-Connect:192.0.2	archive@example.com,archive@offsite.com
All the mail from the network in 192.0.2.0/24 is archived at two locations.
milter-bcc-Connect:192.0.2	/^192\.0\.2\.8[0-9]/bcc@archive.com,manager@archive.com  bcc@archive.com
Mail sent from IP addresses 192.0.2.80 through to 192.0.2.89 is archived and sent to a manager, while the rest of the network in 192.0.2.0/24 is simply archived. This example is rather contrived to show some of what is possible with patterns and is the equivalent of ten simple milter-bcc-connect: entries. When using patterns, weigh the need vs. simplicity, readablity, and administration.
milter-bcc-From:example.com	/^[^+]+@/archive+%L@%D
Mail from within example.com is archived using a plus-detail format if the sender's address does not contain a plus-detail.
milter-bcc-To:example.net	!*+*@*!  /^[0-9].*/  !*smith*@*!managers@%D,archive@%D archive@%D
Mail to addresses within example.net containing a plus-detail or starting with a digit are ignored. Mail to anyone with "smith" as part of their address is archived and sent to a list of managers. Otherwise mail sent to example.net is simply archived by default.
milter-bcc-From:example.com	SKIP
milter-bcc-From:example.net	SKIP
milter-bcc-From:	saveus@archive.com
If example.com and example.net are local domains, then only archive mail sent from outside our domains. milter-bcc-Connect: would work equally well.

+daemon

Start as a background daemon or foreground application.

file=/etc/mail/milter-bcc.cf

Read the option file before command line options. This option is set by default. To disable the use of an option file, simply say file=''

-help or +help

Write the option summary to standard output and exit. The output is suitable for use as an option file.

milter-socket=unix:/var/run/milter/milter-bcc.socket

A socket specifier used to communicate between Sendmail and milter-bcc. Typically a unix named socket or a host:port. This value must match the value specified for the INPUT_MAIL_FILTER() macro in the sendmail.mc file. The accepted syntax is:

{unix|local}:/path/to/file

A named pipe. (default)

inet:port@{hostname|ip-address}

An IPV4 socket.

inet6:port@{hostname|ip-address}

An IPV6 socket.

milter-timeout=7210

The sendmail/milter I/O timeout in seconds.

pid-file=/var/run/milter/milter-bcc.pid

The file path of where to save the process-id.

-quit or +quit

Quit an already running instance of the milter and exit. This is equivalent to: kill -QUIT `cat /var/run/milter/milter-bcc.pid`

-restart or +restart

Terminate an already running instance of the milter before starting.

run-group=milter

The process runtime group name to be used when started by root.

run-user=milter

The process runtime user name to be used when started by root.

verbose=info

A comma separated list of how much detail to write to the mail log. Those mark with § have meaning for this milter.

§	all	All messages
§	0	Log nothing.
§	info	General info messages. (default)
§	trace	Trace progress through the milter.
§	parse	Details from parsing addresses or special strings.
	debug	Lots of debug messages.
	dialog	I/O from Communications dialog
	state	State transitions of message body scanner.
	dns	Trace & debug of DNS operations
	cache	Cache get/put/gc operations.
§	database	Sendmail database lookups.
	socket-fd	Socket open & close calls
	socket-all	All socket operations & I/O
§	libmilter	libmilter engine diagnostics

work-dir=/var/tmp

The working directory of the process. Normally serves no purpose unless the kernel option that permit's daemon process core dumps is set.

SMTP Responses

This is the list of possible SMTP responses generated by milter-bcc.

452 4.3.2 out of memory, cannot add extra recipient to list

milter-bcc appears to be out of memory and cannot add additional recipients.

553 5.1.0 imbalanced angle brackets in path

The path given for a MAIL or RCPT command is missing a closing angle bracket

553 5.1.0 address does not conform to RFC 2821 syntax

The address is missing the angle brackets, < and >, as required by the RFC grammar.

553 5.1.0 local-part too long

The stuff before the @ is too long.

553 5.1.[37] invalid local part

The stuff before the @ sign contains unacceptable characters.

553 5.1.0 domain name too long

The stuff after the @ is too long.

553 5.1.7 address incomplete

Expecting a domain.tld after the @ sign and found none.

553 5.1.[37] invalid domain name

The domain after the @ sign contains unacceptable characters.

Installation

1. Download:

   milter-bcc/1.6	md5sum	Change Log
   LibSnert	md5sum	Change Log
   Sendmail 8.14		http://www.sendmail.org/
   Berkeley DB		http://www.sleepycat.com/

2. In order to support the access database milter-bcc requires Berkeley DB. You should build and install Berkeley DB library first, if you do not already have it. Please read the Berkeley DB documentation on how to build the library. Briefly, it should be something like this:

   cd (path to)/db-4.2.52/build_unix
   ../dist/configure
   make
   make install
   

   If your system is Linux and you install Berkeley DB in the default, non- standard, location then you must remember to update /etc/ld.so.conf and run ldconfig. You can change the default install location by specifying the ../dist/configure option --prefix=/usr/local for example.

3. If you have never built a milter for Sendmail, then please make sure that you build and install libmilter, which is not built by default when you build Sendmail prior to 8.13.0. Please read the libmilter documentation. Briefly, it should be something like this:

   cd (path to)/sendmail-8.12.11/libmilter
   sh Build -c
   sh Build install
   

4. The build process for libsnert and milter-bcc is pretty straight forward once you have libmilter installed:

   cd (path to)/com/snert/src/lib
   ./configure
   make build
   cd ../milter-bcc
   ./configure
   make build
   make install
   

   Both configuration scripts have some options that allow you to override defaults. Those options are listed with:

   ./configure --help
   

5. An example /usr/local/share/examples/milter-bcc/milter-bcc.mc is supplied. This file should be reviewed and the necessary elements inserted into your Sendmail .mc file and sendmail.cf rebuilt. Please note the comments on the general milter flags.

6. Once installed and configured, start milter-bcc and then restart Sendmail. An example startup script is provided in /usr/local/share/examples/milter-bcc/milter-bcc.sh. The default options can be altered by specifying them on the command-line or within a /etc/mail/milter-bcc.cf. The milter-bcc.cf is parsed first followed by the command-line options.

Notes

• Currently tested platforms:

  Cobalt Qube 1 with Linux RH 5.1 (mips 2.0.34 kernel); Linux RH 5.1 (Intel x386 2.2.25 kernel); FreeBSD 4.8, 4.9 (Intel x386); OpenBSD 3.6 (Intel x386)

• The minimum desired file ownership and permissions are as follows for a typical Linux system. For FreeBSD, NetBSD, and OpenBSD the binary and cache locations may differ, but have the same permissions.

  Process user ``milter'' is primary member of group ``milter'' and secondary member of group ``smmsp''. Note that the milter should be started as root, so that it can create a .pid file and .socket file in /var/run; after which it will switch process ownership to milter:milter before starting the accept socket thread.

  /etc/mail/	root:smmsp	0750 drwxr-x---
  /etc/mail/access.db	root:smmsp	0640 -rw-r-----
  /etc/mail/sendmail.cf	root:smmsp	0640 -rw-r-----
  /etc/mail/milter-bcc.cf	root:root	0644 -rw-r--r--
  /var/run/milter/milter-bcc.pid	milter:milter	0644 -rw-r--r--
  /var/run/milter/milter-bcc.socket	milter:milter	0644 srw-r--r--
  /var/db/milter-bcc	milter:milter	0644 -rw-r--r-- (*BSD)
  /var/cache/milter-bcc	milter:milter	0644 -rw-r--r-- (linux)
  /usr/local/libexec/milter-bcc	root:milter	0550 -r-xr-x---

• I would like to express my thanks to Derek Balling for his support at http://www.milter.org/.

License Agreement 1.8

SNERTSOFT & CO. ARE WILLING TO LICENSE THE SOFTWARE IDENTIFIED ABOVE TO YOU ONLY UPON THE CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS LICENSE AGREEMENT. PLEASE READ THE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING THIS SOFTWARE, YOU ACCEPT THE TERMS OF THE AGREEMENT.

1. Definitions

   1. ``Package'' means the identified above in source and/or binary form, any other machine readable materials provided (including, but not limited to documentation, sample files, data files), any updates or error corrections, and its derivative works.

   2. ``Organisation'' means a legal entity or an individual.

   3. ``You'' (or ``Your'') means an Organisation exercising rights under, and complying with all of the terms of, this License or a future version of this License issued under Section 6.1. For legal entities, ``You'' includes any entity which controls, is controlled by, or is under common control with You. For purposes of this definition,``control'' means (a) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (b) ownership of more than fifty percent (50%) of the outstanding shares or beneficial ownership of such entity.

   4. ``SnertSoft'' means Anthony C. Howe situated in Cannes, France (SIRET #489 259 937 00014).

   5. ``SnertSoft & Co.'' means SnertSoft and all authorised & licensed partners, such as value-added resellers or appliance manufacturers.

2. Statement of Original Work

   1. The Package is an original work written by SnertSoft, with exception of following third party code:

      1. MD5 routines written by L. Peter Deutsch, based on RFC 1321;

      2. SQLite3 package is written by D. Richard Hipp of Hwaci and is in the public domain.

      3. strnatcmp.c is written by Martin Pool of sourcefrog.net and has a BSD style license.

      4. Protothreads headers originally written by Adam Dunkels and has a BSD style license.

3. License To Use

   1. You may install and use this Package, without modifications, exclusively on machines for which You have purchased a license, provided You retain this notice, SnertSoft's copyright notice, any and all license control methods (see below), and any links within the Package back to the most current online versions of this License and Disclaimer.

   2. You may copy, share, distribute, modify, and create derivative works from the user manuals and any related documentation solely for Your internal business purposes, such as in-house documentation, training manuals, or reference material.

4. Restrictions

   1. Redistribution, including but not limited to books, CDROMS, download mirrors, floppy diskettes, hard disks, hardcopy print outs, online archives, solid state disks, streaming tapes, or other current or future forms of storage or communication media of the Package, with or without modifications, including any and all derivative works such as source patches, binaries, binary patches, or similar is expressly forbidden without prior written permission in hardcopy (ie. letter or fax) signed and dated by SnertSoft.

   2. It is expressly forbidden for You to use the Package, in whole or in part, in any other software or appliance without prior written permission in hardcopy (ie. letter or fax) signed and dated by SnertSoft.

   3. It is expressly forbidden for You to use the Package to develop any software or other technology having the same primary function as the Package, including but not limited to using the Package in any development or test procedure that seeks to develop like software or other technology, or determine if such software or other technology performs in a similar manner as the Package.

   4. You may not sell, rent, lease, or transfer the Package to third parties without prior written permission in hardcopy (ie. letter or fax) signed and dated by SnertSoft.

5. Termination

   1. This Agreement is effective until terminated. You may terminate this Agreement at any time by destroying all copies of the Package.

   2. This Agreement will terminate immediately without notice from SnertSoft if You fail to comply with any provision of this Agreement.

   3. Either party may terminate this Agreement immediately should any portion of the Package become, or in either party's opinion be likely to become, the subject of a claim of infringement of any intellectual property right. Upon Termination, You must destroy all copies of the Package.

6. Versions Of The License

   1. New Versions. SnertSoft may publish revised and/or new versions of the License from time to time. Each version will be given a distinguishing version number.

   2. Effect of New Versions. Once a version of the Package has been published under a particular version of the License, You may always continue to use it under the terms of that License version. You may also choose to use such Package under the terms of the most current version of the License published by SnertSoft.

   3. No one other than SnertSoft has the right to modify the terms applicable to the Package created under this License.

Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO WAY SHALL SNERTSOFT OR LICENSEE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

License Control

The Package may use one or more license control methods including, but not limited to, license key activation, periodic reporting of Package details and IP address of installation to SnertSoft & Co., or remote license verification by SnertSoft & Co.. Any information reported to or gathered by SnertSoft & Co. shall remain strictly confidential and the private property of SnertSoft & Co.. Under no circumstances will SnertSoft & Co. resell or release this information to third parties, unless demanded by court order.

Support

Support is provided for one year from date of purchase and only for SnertSoft's original Package that was purchased directly from SnertSoft. Additional support beyond the first year can be obtained from SnertSoft on time & materials basis or from one of SnertSoft's authorised partners.

Support for the Package obtained from authorised partners, such as value-added resllers or appliance manufacturers, will be supplied by those partners. SnertSoft will not support the Package without proof of purchase from SnertSoft, such as an Order N° or Invoice N°.

Package enhancements requests and product suggestions are always welcome. A community mailing list is available; please refer to SnertSoft web site Support area for details.

Gifts

Gifts from the author's Amazon US or Amazon UK wishlist (search by mail address <achowe at snert dot com>) are welcomed for the continued encouragement, moral support, and ego pumping needed to work in foreign non-english speaking lands.

Copyright 2004, 2012 by Anthony Howe. All rights reserved.

sex-crimes since 13 June 2004