generate_dspam_aliases v0.3 README http://www.artsackett.com/freebies/generate_dspam_aliases/ ######################################################################## # Copyright (c) 2004 Art Sackett # # # # This program is free software; you can redistribute it and/or modify # # it under the terms of the GNU General Public License as published by # # the Free Software Foundation; either version 2 of the License, or # # (at your option) any later version. # # # # This program is distributed in the hope that it will be useful, but # # WITHOUT ANY WARRANTY; without even the implied warranty of # # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU # # General Public License for more details. # # # # You should have received a copy of the GNU General Public License # # along with this program; if not, write to the Free Software # # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 # # USA # ######################################################################## TABLE OF CONTENTS 1.0 About 1.1 Overview 1.2 System Requirements 1.3 Installation 1.4 Configuration 1.5 Use 2.0 Release History 1.0 About generate_dspam_aliases is designed to ease the burden of maintaining a mailer daemon aliases file for systems using the DSPAM anti-spam solution. It is more flexible than and intended to replace a similar tool that is part of the DSPAM package, dspam_genaliases. It is intended that in most cases generate_dspam_aliases (the perl script itself) will require no modification for successful integration. This is the first release of generate_dspam_aliases. It seems to work okay for the author's installation, but it could stand improvement. Feedback welcome at asackett at artsackett dot com. 1.1 Overview generate_dspam_aliases reads its configuration at run time from a .ini style configuration file, /etc/generate_dspam_aliases.ini by default. This configuration file contains information about the data source file (/etc/passwd on most systems), the target output file (typically a mail transfer agent's aliases file), formatting of both the data source and target output files, and information about users for which DSPAM aliases should not be generated. In order to support a broad range of operating systems and mail transfer agents (MTA's), generate_dspam_aliases makes few assumptions about the formatting of input or output data. generate_dspam_aliases can be configured to exclude various users who may not need DSPAM aliases. On many systems, system users (i.e. daemon, nobody) are assigned uid's and gid's from a specified range of available numbers, often 0 (zero) through 999. generate_dpam_aliases can be configured to work only with uid's greater than some number and/or lower than some number. The same rules can be applied to gid's. Users can also be excluded by individual uid, gid, or login name. 1.2 System Requirements generate_dspam_aliases should run on any POSIX-like system on which there is a perl interpreter. It depends upon the perl Fcntl module, which is part of the perl core distribution and should be present on any system upon which perl is installed. 1.3 Installation If your perl interpreter isn't at /usr/bin/perl, you'll have to edit the shebang (first) line of generate_dspam_aliases. Just ask your system: which perl and edit accordingly. In most cases, /usr/bin/perl will work. The default limits for least and greatest uid numbers are 0 and 65535, respectively. If your system supports uid's outside of this range, you should edit the lines in generate_dspam_aliases accordingly: my $min_uid = 0; my $max_uid = 65533; Choose a location for the configuration file, which for this discussion will be /etc/. Then, as root: cp generate_dspam_aliases.ini /etc/ If you've chosen to place the configuration file anywhere other than /etc/generate_dspam_aliases.ini, find the line in generate_dspam_aliases that reads: my $inifile = '/etc/generate_dspam_aliases.ini'; and edit the path accordingly. Choose a location for the perl script, which for this discussion will be /usr/local/bin/. Then, as root: cp generate_dspam_aliases /usr/local/bin/ chmod 700 /usr/local/bin/generate_dspam_aliases 1.4 Configuration The configuration file is very much like any other .ini file you may have encountered, but the parser for it uses a limited subset of the features that (some) others offer. The most important of which are: a. It does not support multi-line values. b. It does not support additive values. c. All section names and parameter keys are case-sensitive. d. The comment identifier is # rather than ; Each configuration item must be on one line only, and each key can appear only once. Section names appear within [Square Brackets] and everything from a bracketed section name up to the next bracketed section name is part of the current section. The following parameters are available: [Password File] fields = user password uid gid comment homedir shell file = /etc/passwd The only required parameter in the [Password File] section is 'file'. If 'fields' does not exist, the default will be used. The default is as shown in the example above. The 'fields' parameter indicates the format of the source data file, which is usually /etc/passwd. The values must be space-separated. The source data file record separator is assumed to be the colon (:) character, and is not configurable. The names matter only for 'user', 'uid', and 'gid' (corresponding to login name, user ID, and group ID, respectively), which MUST be present. All other field names can be arbitrary strings, but must contain no whitespace. The 'file' parameter is simply the path to the source data file. It need not actually be the system password file, so long as it conforms to the convention of colon-separated values. Blank lines are ignored. [Alias File] alias-notspam = -notspam alias-spam = -spam args-falsepositive = --falsepositive args-spam = --addspam file = /etc/courier/aliases/dspam format = : | --user program = /usr/local/bin/dspam The required parameters within the [Alias File] section are 'alias-spam', 'format', and 'program'. Within the Alias File section, all parameter values will be subject to variable interpolation. generate_dspam_aliases will provide the values 'user', 'uid', and 'gid' as it finds them in the lines of the source data file, and will then process the above lines in the following sequence: alias-spam args-spam program format alias-notspam args-falsepositive program format Thus, as the program works, the value of 'alias-spam' will be available for replacement within 'args-spam', both of these will be available for replacement within 'program', and all three will be available for use in 'format'. However, the value assigned to 'program' will not be available to 'args-spam' or 'alias-spam'. Any optional parameters that do not exist or contain empty (all whitespace) values will be ignored. The false positive aliases will be generated as described above if 'alias-notspam' exists and contains a non-empty value. The values of this section's parameters are essentially templates that will be populated with the values of their tokens. So, wherever exists, it will be replaced the the value found in the current line of the source data file; the same is true for , , and, as they become available (in the sequence shown above) , , etc. 'format' is the line that will actually be written into the target output file. 'format' is the same for both spam and false positive output lines. If 'args' is not provided, the token will be removed from the output. Be careful about typos here, as anything that is not a known parameter will remain untouched in the output line, so if your format line looks like (note the misspelling of "alias"): format = : | --user Then the line written into the target output file will be something like: : |/usr/local/bin/dspam --user barney --addspam [Users] ignore-gid = 64010 ignore-uid = 65534 ignore-user = nobody fred barney maximum-gid = maximum-uid = minimum-gid = minimum-uid = 1000 All parameters within the [Users] section are optional. 'ignore-gid' should contain the gid's of any groups for whom no aliases should be generated, if they fall within the range of 'minimum-gid' to 'maximum-gid'. Any user whose gid is mentioned in this line will be skipped. 'ignore-uid' should contain the uid's of individual users for whom no aliases should be generated, if they fall within the range of 'minimum-uid' to 'maximum-uid'. 'ignore-user' should contain the login names of users for whom no aliases should be generated. 'maximum-gid' should contain the highest gid for which you wish aliases to be generated. Any user whose gid is higher than 'maximum-gid' will be skipped. 'maximum-uid' should contain the highest uid for which you wish aliases to be generated. Any user whose uid is higher than 'maximum-uid' will be skipped. 'minimum-gid' should contain the lowest gid for which you wish aliases to be generated. Any user whose gid is lower than 'minimum-gid' will be skipped. 'minimum-uid' should contain the lowest uid for which you wish aliases to be generated. Any user whose uid is lower than 'minimum-uid' will be skipped. On most GNU/Linux systems, uid's below 1000 belong to system users, who most often do not intentionally receive email. So, setting 'minimum-uid' to 1000 will ensure that no DSPAM aliases are generated for them. Often, users with uid's above 1000 will have no need of DSPAM aliases, and including them either by name (in 'ignore-user') or by uid (in 'ignore-uid') will ensure that no DSPAM aliases are ever generated for them. 1.5 Use generate_dspam_aliases [options] The available options are: --help (Emits a usage summary, then exits.) --version (Emits version information, then exits.) --inifile=/path/to/inifile --input=/path/to/passwd --output=/path/to/aliases/file --verbose (Useful for configuration troubleshooting.) The options probably do what you'd expect of them. 2.0 Release History: 0.1 2004-01-01: Initial public release. 0.2 2004-01-02: License changed to GPL. 0.3 2004-01-20: Changed blurb to indicate GPL. Oops. 0.4 2004-02-29: Improved parse_argv().