Name
Availability
FMG, FMG
swiiftefg -a fax-email-address [-c] [-d] -f from-email-address [-h host-name] [-l locale] -t 1 [-v]
The swiiftefg program implements the Email/Fax Gateway (EFG) part of the various Faximum Messaging Software products. This component takes an email message from the sendmail system, extracts the fax number and other cover sheet information, and passes the request on to the specified fax server.
This program is not intended to be called directly (except for the purpose of testing the gateway), rather it is normally called by sendmail to deliver an email message addressed to the email/fax gateway.
The following describes the arguments and parameters expected by the gateway. Please note that the current version of the gateway has been designed to work with sendmail. If you are trying to integrate swiiftefg with other mail systems please contact Faximum Technical Support (support@faximum.com) for assistance as well as modifications (if necessary) to the swiiftefg tool to make it easier to integrate with your system.
-a fax-email-address
This argument provides swiiftefg with the fax number and other information for the cover sheet. The format of the fax-email-address depends on the address type argument (-t), described below.
-c This will cause the copyright information for the program to be displayed. No other parameters will be processed.
-d This will cause detailed debugging information to be written to a file in the /tmp directory with a name starting with efg.dbg.
-f from-email-address
This argument provides the address of the person who sent the email message to the EFG. This address is used both to verify the authority of the sender to access the EFG as well as to provide the address to which the fax server will send confirmation once the fax has been successfully sent.
This address may or may not include a host name component. If the @domain.name component is missing then the EFG takes the host name component from the -h argument (if present).
-h host-name
This argument specifies the default host name to be used if the from-email-address (above) does not include a host name component.
The EFG will delete any trailing periods from the host-name (some sendmail implementations add a period to the host name before passing it to delivery agents).
-l locale-name
This argument specifies the name of the locale to be used when processing messages. This will be used as the second argument to a setlocale(LC_ALL, locale) call (see setlocale(3) in your system documentation) and will also affect the message catalogue used for messages issued by the EFG. Finally, the locale name will be used as the value of the LANG environment variable when conversion program from the mime.types file are run.
-t n This parameter specific the format or type of the email-fax-address parameter. The current version of the WFG only supports one address format type, specified with a value of 1. This argument must appear before the -a argument on the command line.
Type 1 addresses are of the format: name/title/dept/company/fax-number where all of the components except the fax-number are optional. If fewer than five components are provided then the EFG interprets the address parts as follows:
fax-number
name/fax-number
name/company/fax-number
name/title/company/fax-number
Embedded spaces in the various address components can be represented by an underscore ("_") character.
The fax number is passed unchanged to the fax server and ought to be in whatever format your fax server is configured to accept.
Other address format types will be defined and supported as the standards for email-fax addresses evolve. Please contact Faximum Technical Support (support@faximum.com) should you need the EFG extended to handle a different address format.
-v This will cause the version information for the program to be displayed. No further parameters or input will be processed.
The Email/Fax Gateway is usually configured (see below) so that email messages sent to addresses of the form:
name/company/faxnumber%fax@server.company.com
are passed to swiiftefg which examines the message headers (in order to set the appropriate fax transmission parameters), converts any attachments into a format that can be handled by the fax server, and then passes the request to the fax server for conversion into fax format and for transmission.
Note that the standard SWIIFT EFG can handle attachments of text (i.e. ASCII), TIFF-F, and PostScript and/or PCL (depending on the capabilities of your fax server).
Additional software is available from Faximum to extend the capabilities of the EFG to handle attachments from common desktop productivity applications such as Microsoft Word and Excel. Please contact info@Faximum.com for current information on such SWIIFT add-ons.
The EFG examines the mail headers of messages it processes for Faximum-specific headers.
If it finds any of the following headers, it will use the value specified instead of the default value from the /etc/faximum.conf1 file.
X-fxm-account
X-fxm-class
X-fxm-notify
X-fxm-style
If it finds any of the following headers, it will use the value specified instead of the value taken from the email-fax-address (if any).
X-fxm-company
X-fxm-department
X-fxm-name
X-fxm-title
The configuration of the EFG falls into two parts. First you must reconfigure the sendmail program on the system that will be running the EFG (this need not be the same system that is running the Faximum Fax Server) and then you will need to configure the EFG itself (by editing the /etc/faximum.conf or /etc/opt/faximum/config file). Both of these are described in detail below.
BEFORE reconfiguring sendmail on your system please verify that sendmail is working. This can be done by typing the following command:
date | /usr/lib/sendmail root@fax.server.com
where fax.server.com is replaced by the hostname of the system (you may need to change the pathname of the sendmail command depending on where sendmail is located on your system). After running this command, verify that the root account on your system received email containing the output of the date command. DO NOT PROCEED beyond this point until you have verified that sendmail is working properly on your system! If sendmail is not working on your system then please follow the instructions for your system to configure sendmail so that it will work. There is no point in configuring sendmail to work with the SWIIFT EFG if it is not properly configured to handle email in the beginning.
The sendmail configuration file, sendmail.cf, must be edited to tell sendmail that email addressed to something%fax@hostname is special and ought to be passed to swiiftefg for processing. You will need to consult the sendmail documentation for your system to (a) locate the sendmail.cf file (e.g. on most systems this file is in the /etc/mail directory) and (b) determine how to best reconfigure sendmail to work with SWIIFT. Because sendmail can be configured in many different ways, the instructions below on how to add the necessary configuration information for the EFG are, of necessity, general in scope. You will need to examine the sendmail.cf file for your system to determine how to best make the necessary changes. If you prefer, Faximum offers a sendmail.cf configuration service for a modest fee whereby you email support@faximum.com your sendmail.cf file and the engineers at Faximum will make the necessary changes.
If you plan to modify your sendmail.cf file yourself and you find the documentation available for your system's sendmail to be lacking, then consult the highly recommended book sendmail by Costales, Allman, and Rickert; published by O'Reilly & Associates, Inc. (http://www.ora.com/). (The authors of the EFG and this manual page owe a great deal to this book.)
The sendmail.cf changes affect two areas. First, rule set 0, which determines which mail delivery agent will handle delivery for a particular recipient address, must be modified to indicate that email addresses of the form something%fax@domain.name are to be passed to the EFG.
This is done by adding the following line to the beginning of rule set 0 (look for the line in the sendmail.cf file that contains only S0 and add the following immediately after):
R$+%fax<@ $=w . > $#faximum $@node.acme.com$:$1 user%fax@dest
NOTE: (1) replace node.acme.com in the above two lines with the domain name of the fax server machine as used in email addresses, and (2) make sure that the white space separating the three parts of this rule contain only tab characters (not spaces). The only space character is between "faximum" and $@node....
This rule (hence the leading R) matches addresses that start with something (the $+ part of the rule), followed by %fax, followed by the @ symbol and the domain name of the fax server (stored in the w macro which is accessed through the expression $=w).
If this rule matches the address, then sendmail is to use the faximum delivery agent, passing it the hostname (identified by the $@) and the user name (indentified by the $:, with $1 representing the something we matched before the %fax sequence). The user%fax@dest part is merely a comment that is ignored by sendmail.
The second area of the sendmail.cf file that we must modify is the section that defines the delivery agents. We need to add the following lines:
Mfaximum, P=/opt/SWIIFT/lbin/swiiftefg,
F=DFMhuC, M=100000,
A=swiiftefg -t 1 -f $f -a $u -h $h
These lines ought to be added to the sendfax.cf file immediately before the line containing S0.
Let's look at each part of this line in detail.
Mfaximum This identifies the name of the mail delivery agent
P=/opt/SWIIFT/lbin/swiiftefg
This specifies the pathname of the swiiftefg program (your pathname may vary depending on where you installed the SWIIFT software).
F=DFMhuC
These flags tell sendmail to:
D force date information to appear in the message header
F force the from information to appear in the message header
M force the message-id information to appear in the message header
h preserve uppercase in the hostname
u preserve uppercase in the username
C add @domain to the recipient address that lacks one.
M=100000
This specifies the maximum message size (in bytes, including all attachments). If your users are sending only text messages, then 100000 ought to be more than enough. If your users are attaching TIFF files, however, 100000 will only be enough for a couple of pages and will probably need to be increased. This field is optional so if you do not wish to impose any limit on the size of messages passed to the EFG, merely drop this parameter altogether.
A=swiiftefg -t 1 -f $f -a $u -h $h
This specifies the exact command line that is to be run when this delivery agent is to be invoked. $f contains the sender's email address, $u the recipient's email address, and $h the recipient's hostname.
Testing the Sendmail Configuration
To test that these changes to sendmail.cf have been made properly, please run the following command:
/usr/lib/sendmail -bv snort/9999%fax@node.acme.com
(with node.acme.com replaced with the name of the server running the EFG). Note also that on some machines the sendmail executable may be located in a different directory. Consult the documentation for your system in order to locate the sendmail program.
You ought to get a response similar to the following (which will normally appear as a single line but which appears here as several lines):
snort/9999%fax@node.acme.com...
deliverable: mailer faximum, host node.acme.com,
user snort/9999
If the part "mailer faximum" indicates a mailer other than faximum then the reconfiguration of the sendmail.cf file has not be done properly.
If this test is successful, then run sendmail with the -bt flag and type in the following:
/usr/lib/sendmail -bt
sendmail will reply:
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter <ruleset> <address>
Then type:
0 snort/999%fax@engg3.faximum.com
and you ought to see:
rewrite: ruleset 0 input: snort / 999 % fax @ engg3 . faximum . com
rewrite: ruleset 0 returns: $# faximum $@ engg3 . faximum . com $: snort / 999
If you see something like:
rewrite: ruleset 0 returns: $# error $: I don't understand ...
then there is a problem with the changes you have made to the sendmail.cf file.
If you are unable to get these tests to succeed, then please email support@faximum.com and include:
your sendmail.cf file;
the output from the sendmail -bv test; and
the output from the sendmail -bt test.
The parameters in the /etc/faximum.conf that affect the operation of the EFG are described below. (Note that on HP-UX 10.x systems, the Faximum configuration file is named /etc/opt/faximum/config, not /etc/faximum.conf as stated herein).
Note that the examples below are intended to illustrate the form that the values might take on a hypothetical system. You will need to adapt these examples for your particular configuration.
swiift-efg-access
This parameter provides the list of user name patterns (in regcmp(2) regular expression format) that are permitted to access the EFG. Note that since the patterns are not automatically anchored, if the pattern is a substring of the user's name it will match (unless you anchor the pattern using ^ or $). You may optionally precede a pattern with a minus sign (-) to cause the specified users to be denied access to the server. Example:
swiift-efg-access = @faximum.com,
-@sales.faximum.com,jane@acme.co.nz
(This example may appear on two lines because of the limitations of the printed format but ought to appear as a single line in your configuration file.)
swiift-efg-debug
This optional parameter indicates whether a trace log file (useful for testing) is to be created by swiiftefg when it runs. If the parameter value is yes, a files in /tmp with names starting with efg.dbg. will be created and will contain the details of every message processed by swiiftefg. Example:
swiift-efg-debug = yes
When you are first testing the EFG it is recommended that this parameter be set to yes. If you experience problems with the operation of the EFG you can email the /tmp/efg.dbg.* files to Faximum Technical Support for analysis.
swiift-efg-submitfax
This parameter specifies the pathname of the program used to pass the fax request to the fax server. On systems that use Faximum's fax server, this will be the pathname of the submitfax program, for example:
/opt/FAXclient/lib/submitfax.
If you will be using SWIIFT with another type of fax server, please see the appendix on integrating SWIIFT with fax servers. Example:
swiift-efg-submitfax = /opt/SWIIFT/lib/submitfax
swiift-efg-faxhost
This parameter specifies the domain name of the fax server host. It will be passed to submitfax to indicate the fax server that is to be used. Example:
swiift-efg-faxhost = fax.server.faximum.com
swiift-efg-notify
This parameter specified (yes/no) if the fax server ought to send an email message to the sender when the fax is successfully sent (a message is always sent if the fax fails).
swiift-efg-account
swiift-efg-class
swiift-efg-style
These mandatory parameters specify the default values for the account, class, and style to be used by default if no other parameters are provided within the message headers.
The exact meaning of each parameter will depend on the underlying fax server being used with SWIIFT. In the case of the Faximum Software's Fax Server, the account parameter is used to keep track of the project the fax is to be charged to, the class parameter is used to control the priority and scheduling of the fax, and the style parameter controls the appearance (i.e. cover sheet, forms overlay, resolution, and page length) of the fax.
For more information on the Account, Class, and Style databases, please refer to the on-line help or documentation for your Faximum fax server software. If you are using SWIIFT with a fax server from another vendor please contact Faximum Technical Support for assistance.
For information on the available Accounts, Classes, and Styles, please see the configuration of your Faximum fax server.
Example:
swiift-efg-account = Sales-Dept
swiift-efg-class = Panic
swiift-efg-style = Corporate-Coversheet (Fine)
swiift-efg-priority[priority] = class_name
These optional parameters (there can be any number of parameters of this form with different priority names) indicate to swiiftefg how to convert different email priorities into fax priorities.
For each priority name that your email program might generate you can specify a corresponding class (a.k.a. fax priority) for the resulting faxes. In this manner, important (i.e. "first-class") email message will go to the front of the queue while unimportant faxes (i.e. "bulk") could be scheduled to be sent after midnight when phone rates are the lowest.
Names of priorities vary from mailer to mailer but commonly seen priorities include: numbers (i.e. 1 is the highest priority, 5 is the lowest), first-class, normal, special-delivery, urgent (or u), and bulk.
For example:
swiift-efg-priority[first-class] = Rush
swiift-efg-priority[special-delivery]= Panic
The EFG looks first for a Priority: header in the email message and if one is not found, it then looks for an X-Priority: header.
For more information on the Account, Class, and Style databases, please refer to the on-line help or documentation for your Faximum fax server software. If you are using SWIIFT with a fax server from another vendor please contact Faximum Technical Support for assistance.
For information on the available Accounts, Classes, and Styles, please see the configuration of your Faximum fax server.
swiift-efg-mime-types-file
The mime.types file specifies how the swiiftefg tool is to convert MIME attachments into one of the base file types that the underlying fax server knows how to handle. This file is usually shared by the swiiftwfg utility and is documented in a separate mime.types file appendix. Example:
swiift-efg-mime-types-file = /opt/SWIIFT/lib/mime.types
The EFG is capable of fully distributed operation where the person sending the email/fax message is on a different machine (say a.company.com) from the system running the EFG (b.company.com) which is different from the host running the fax server (c.company.com). The following scenario describes how this can be accomplished. (Conversely, of course, the user, the EFG, and the fax server could all reside on the same machine.)
When the user (on machine a.company.com) wishes to send an email/fax message, he uses the host name of the system running the EFG (which also has the modified sendmail.cf file), for example:
mail Jane_Doe/1-604-926-8182%fax@b.company.com
The /etc/faximum.conf file on the system b.company.com will contain a swiift-efg-faxhost parameter specifying the system that is running the fax server, for example:
swiift-efg-faxhost=c.company.com
If your sendmail.cf file passes the -bv and -bt tests outlined above and yet faxes sent through the Email/Fax Gateway are not getting through then please follow the following steps to isolate the cause.
The first step is to try to determine where the failure is occurring. Faxes sent through the EFG are first handled by sendmail, then passed to the SWIIFT EFG, and then passed to the underlying fax server.
The easiest way to see how far the request is getting before it fails is to edit your /etc/faximum.conf file and set the swiift-efg-debug parameter to yes. For example:
swiift-efg-debug = yes
With this parameter set, send an email message to the EFG and then look in the /tmp directory for files with names starting with efg.dbg. These files will contain detailed information on the handling of the request and ought to shed some light on why the request is failing. If the cause is not obvious, then email these files to support@faximum.com for analysis.
If no files are created in /tmp even with the swiift-efg-debug parameter set then this indicates that the problem is with sendmail. Look in the sendmail log file (called syslog and normally found in the /var/log or /usr/adm directories). Again, if the reason is not obvious, then email the last 100 or so lines to support@faximum.com.
NOTE, on SCO systems the sendmail program is, by default, configured not to log much information. In order to obtain the information needed to diagnose sendmail problems on SCO systems you will need to edit the /usr/lib/sendmail.cf file and change the log level to 9. For example:
# log level
OL9
One common cause for email not to be passed to the SWIIFT EFG is because the attachments make the message larger then the limit specified by the M= parameter (see the section on sendmail.cf configuration above). On some systems sendmail will drop oversized messages quietly without any warning or error message.
Since the transmission of faxes through the EFG can incur long-distance charges, it is important for the EFG administrator to realise that the EFG believes the From: information given it by the sendmail (or other mail server) when checking the swiift-efg-access list described above.
Unfortunately the underlying email protocols are not secure and it is not difficult for a malicious user to cause email to be sent that has fictitious From: headers. In this manner an unauthorised user could appear to the email server (and hence to the EFG) as an authorised user and causes faxes to be sent (and phone bills to be incurred) that ought not be permitted.
Until secure email protocols become widely supported, the only method to reduce the likelihood of this problem is to install the EFG on a mail server that is protected from external access (both direct and indirect) by using firewalls and careful configuration of other mail servers behind the same firewall.
Faximum Software is monitoring the progress of the S/MIME secure email proposals and once support for this approach becomes generally available, Faximum will add support for S/MIME to SWIIFT as a means of reliably authenticating the originator of email messages sent to the EFG.
If any customer is running a secure email system with authentication and wishes to have SWIIFT verify the originator of email messages, please contact Faximum Technical Support (support@faximum.com) for more information.
See the documentation for the sendmail utility on your system. Further information on sendmail may also be found at http://www.sendmail.org/
1 On HP-UX 10.x systems the main Faximum configuration file is called /etc/opt/faximum/config
© 2000 Faximum Software Inc.