Test address rewriting specified by a PMDF configuration.

Syntax

pmdf test -rewrite [test-address]

Command Qualifiers	Defaults
-alias_file=file-spec	-alias_file=PMDF_ALIAS_FILE
-channel	-channel
-check_expansions	-nocheck_expansions
-configuration_file=file-spec	-configuration_file=PMDF_CONFIG_FILE
-database=database-list	See text
-debug	-nodebug
-delivery_receipt	See text
-destination_channel=channel	None
-filter	-nofilter
-from=address	-from=postmaster@localhost
-grey=setting	-grey=0
-image_file	-image_file
-input=input-file-spec	-input=stdin
-local_alias=value	-nolocal_alias
-mapping_file=file-spec	-mapping_file=PMDF_MAPPING_FILE
-option_file=file-spec	-option_file=PMDF_OPTION_FILE
-output=output-file-spec	output=stdout
-read_receipt	See text
-reprocessing	-reprocessing
-restricted=setting	-restricted=0
-source_channel=channel	-source_channel=l

restrictions

None.

prompts

Parameters

test-address

Optional parameter specifying one or more addresses to rewrite.

Description

pmdf test -rewrite provides a straightforward test facility for examining PMDF's address rewriting and channel mapping process without actually sending any message. Various qualifiers can be used to control whether pmdf test -rewrite uses the configuration text files or the compiled configuration (if present), the amount of output produced, and so on.

If a test address is specified on the command line, pmdf test -rewrite applies PMDF address rewriting to that address, reports the results, and exits. If no test address is specified, pmdf test -rewrite will enter a loop, prompting for an address, rewriting it, and prompting again for another address. pmdf test -rewrite will exit when CTRL/D (UNIX) or CTRL/Z (NT) is entered.

When testing an alias corresponding to a mailing list which has an AUTH_ or CANT_ type of named parameter controlling who may post to the list, or when testing rewriting when SEND_ACCESS or related mapping tables are in effect, note that by default pmdf test -rewrite uses as the posting address the return address of the local postmaster as specified by the PMDF option RETURN_ADDRESS. To specify a different posting address for the rewriting process, use the -from qualifier.

Must be run as superuser or by a user in the pmdf_world group.

Command Qualifiers

-alias_file=filename

pmdf test -rewrite normally consults the default alias file named by the PMDF_ALIAS_FILE option of the PMDF tailor file (UNIX) or PMDF Tailor Registry entry (NT) during the rewriting process. The -alias_file qualifier specifies an alternate file for pmdf test -rewrite to use. This qualifier has no effect unless -noimage_file is specified or no compiled configuration exists; use of any compiled configuration precludes reading any sort of alias file.

-channel (default)

-nochannel

This qualifier controls whether the utility outputs detailed information, e.g., channel flags, regarding the channel an address matches.

-check_expansions

-nocheck_expansions (default)

This qualifier controls checking of alias address expansion. Normally PMDF considers the expansion of an alias to have been successful if any of the addresses to which the alias expands are legal. The -check_expansions qualifier causes a much stricter policy to be applied: pmdf test -rewrite -check_expansions checks each expanded address in detail and reports a list of any addresses, expanded or otherwise, that fail to rewrite properly. For addresses that match the L channel, PMDF also performs validity checks.

-configuration_file=filename

pmdf test rewrite normally consults the default configuration file named by the PMDF_CONFIG_FILE option of the PMDF tailor file (UNIX) or PMDF Tailor Registry entry (NT) during the rewriting process. The -configuration_file qualifier specifies an alternate file to use in place of the file named by PMDF_CONFIG_FILE. This qualifier has no effect unless -noimage_file is specified or no compiled configuration exists; use of any compiled configuration will preclude reading any sort of configuration file.

-database=database-list

pmdf test -rewrite normally consults the usual PMDF databases during its operation. This qualifier is used to either disable references to various databases or to redirect the database paths to nonstandard locations. The allowed list items are alias, noalias, personal_alias, nopersonal_alias, domain, nodomain, forward, noforward, general, nogeneral, reverse, and noreverse. The list items beginning with "no" disable use of the corresponding database. The remaining items require an associated value, which is taken to be the name of that database.

-debug

-nodebug (default)

The address rewriting process is capable of producing additional, detailed explanations of what actions are taken and why. The -debug qualifier enables this output; it is disabled by default.

-delivery_receipt

-nodelivery_receipt

The -delivery_receipt and -nodelivery_receipt qualifiers, which explicitly set the corresponding receipt request flags, can be useful when testing the handling of receipt requests when rewriting forwarded addresses or mailing lists.

-filter

-nofilter (default)

The -filter qualifier may be used to have pmdf test -rewrite output any filters (personal mailbox, channel, or system) applying for the address in question.

-destination_channel= channel

The -destination_channel qualifier controls for which destination or target channel pmdf test -rewrite rewrites addresses. Some address rewriting is destination channel specific; this qualifier allows control of the assumed destination channel.

-from=address

-nofrom

The -from qualifier controls what envelope From: address is used for access control probes and mailing list access probes. If this qualifier is omitted, the postmaster return address is used for such probes. Specifying -nofrom tells PMDF to use an empty envelope From: address for access probes.

-grey=setting

This qualifier controls the setting of the Grey Book flag. By default, this flag has value 0. When set to 1, -grey=1, the Grey Book flag will be set on and addresses will be rewritten using the Grey Book format. This flag is used to force rewriting of address in accordance with the JANET (Grey Book) specifications. The most significant effect is that domain specifications appear in reverse order, e.g., edu.claremont.ymir and not ymir.claremont.edu. See Section 2.3.4.84 for further details. Grey Book address formats are not currently used in PMDF, so this qualifier's usefulness is problematic at best.

-image_file (default)

-noimage_file

When the -image_file qualifier is specified (the default), pmdf test -rewrite will load the compiled configuration from the file named by the PMDF_CONFIG_DATA option in the PMDF tailor file (UNIX) or PMDF Tailor Registry entry (NT). PMDF_CONFIG_DATA is usually /pmdf/lib/config_data on UNIX, and usually C:\pmdf\lib\config_data on NT. When -noimage_file is specified, pmdf test -rewrite unconditionally ignores any previously compiled configuration and instead reads configuration information from the various text files.

-input=input-file-spec

By default, pmdf test -rewrite takes input from stdin. The -input qualifier may be used to specify a different source for input.

-local_alias=value

-nolocal_alias (default)

This qualifier controls the setting of an alias for the local host. PMDF supports multiple "identities" for the local host; the local host may have a different identity on each channel. This qualifier may be used to set the local host alias to the specified value; appearances of the local host in rewritten addresses will be replaced by this value.

-mapping_file [ =file-spec]

-nomapping_file

This qualifier instructs pmdf test -rewrite to use the specified mapping file rather than the default mapping file named by the PMDF_MAPPING_FILE option in the PMDF tailor file (UNIX) or PMDF Tailor Registry entry (NT). PMDF_MAPPING_FILE usually points to the file /pmdf/table/mappings (UNIX) or C:\pmdf\table\mappings (NT). This qualifier has no effect unless -noimage_file was specified or no compiled configuration exists; use of any compiled configuration will preclude reading the mappings file. Use of the -nomapping_file qualifier will prevent the PMDF_MAPPING_FILE file from being read in when there is no compiled configuration.

-option_file [ = filename]

-nooption_file

This qualifier instructs pmdf test -rewrite to use the specified option file rather than the default option file named by the PMDF_OPTION_FILE option in the PMDF tailor file (UNIX) or PMDF Tailor Registry entry (NT). PMDF_OPTION_FILE usually points to the file /pmdf/table/options (UNIX) or C:\pmdf\table\options (NT). This qualifier has no effect unless -noimage_file is specified or no compiled configuration exists; use of any compiled configuration will preclude reading any sort of option file. Use of the -nooption_file qualifier will prevent the PMDF_OPTION_FILE file from being read in when there is no compiled configuration.

-output=output_file_spec

By default, pmdf test -rewrite writes output to stdout. The -output qualifier may be used to direct the output of pmdf test -rewrite elsewhere.

-read_receipt

-noread_receipt

The -read_receipt and -noread_receipt qualifiers, which explicitly set the corresponding receipt request flags, can be useful when testing the handling of receipt requests when rewriting forwarded addresses or mailing lists.

-reprocessing (default)

-noreprocessing

This flag allows the utility to display the contents of a mailing list which uses the [REPROCESS] named parameter in its alias definition.

-restricted=setting

This qualifier controls the setting of the restricted flag. By default, this flag has value 0. When set to 1, -restricted=1, the restricted flag will be set on and addresses will be rewritten using the restricted mailbox encoding format recommended by RFC 1137. This flag is used to force rewriting of address mailbox names in accordance with the RFC 1137 specifications; see Section 2.3.4.57 for further details.

-source_channel=channel

The -source_channel qualifier controls for which source channel to rewrite addresses. Some address rewriting is source channel specific; pmdf test -rewrite normally pretends that the channel source for which it is rewriting is the local channel, l on UNIX or usually msgstore on NT.

EXAMPLES

This UNIX example shows typical output generated by pmdf test -rewrite Perhaps the single most important piece of information generated by pmdf test -rewrite is displayed on the last few lines of the output, (6), which shows the channel to which pmdf test -rewrite would submit a message with the specified test address and the form in which the test address would be rewritten for that channel. This output is invaluable when debugging configuration problems.

% pmdf test -rewrite DAN@EXAMPLE.COM (1) channel = tcp_local channel description = channel filter = (2) channel flags #0 = BIDIRECTIONAL SINGLE_SYSTEM IMMNORMAL NOSERVICEALL channel flags #1 = SMTP_LF MX channel flags #2 = POSTHEADBODY HEADERINC NOEXPROUTE channel flags #3 = LOGGING NOGREY RESTRICTED channel flags #4 = EIGHTNEGOTIATE NOHEADERTRIM NOHEADERREAD RULES channel flags #5 = channel flags #6 = LOCALUSER REPORTHEADER channel flags #7 = ALLOWSWITCHCHANNEL NOREMOTEHOST DATEFOUR DAYOFWEEK channel flags #8 = NODEFRAGMENT EXQUOTA REVERSE NOCONVERT_OCTET_STREAM channel flags #9 = NOTHURMAN INTERPRETENCODING INCLUDEFINAL RECEIVEDFROM linelength = 998 ddrsperfile = 127 channel envelope address type = SOURCEROUTE channel header address type = SOURCEROUTE (3) channel official host = TCP-DAEMON channel local alias = channel queue name = channel daemon name = channel user name = urgentnotices = normalnotices = nonurgentnotices = (4) channel group ids = (5) backward channel = tcp_local header To: address = DAN@EXAMPLE.COM header From: address = DAN@EXAMPLE.COM envelope To: address = DAN@EXAMPLE.COM (route (TCP-DAEMON,TCP-DAEMON)) envelope From: address = DAN@EXAMPLE.COM name = mbox = DAN Extracted address action list: DAN@EXAMPLE.COM Extracted 733 address action list: DAN@EXAMPLE.COM Address list expansion: 0 expansion total. Expanded address: DAN@EXAMPLE.COM (6)Submitted address list: tcp_local DAN@EXAMPLE.COM (EXAMPLE.COM) *NOTIFY FAILURES* *NOTIFY DELAYS* (7)Submitted notifications list:

1. The channel to which, after rewriting as an envelope To: address, the address is mapped.
2. The flags set for the channel indicated in . These flags are controlled by the channel keywords on the first line of the channel control block for the specified channel. Any unknown keywords---keywords which may have been mistyped---will be interpreted as group ids and will appear on the line .
3. The channel's official host name as specified on the second line of the channel control block for the channel indicated in .
4. Any items appearing on the first line of the channel block which were not channel keywords are interpreted as group ids. Any group ids so specified for the channel are listed on this line.
5. The channel which the address would match if rewritten as an envelope From: address.
6. The channel to which a message with the address DAN@EXAMPLE.COM would be queued and the envelope To: address which would be used. Here, the message would be submitted to the TCP/IP channel, tcp_local, using the address DAN@EXAMPLE.COM. Other information appearing here might include an explicit Errors-to: address, which, if present, appears enclosed in square brackets; or notations such as *RR* or *NRR*, indicating whether or not the message is flagged for read receipts, or notations such as *NOTIFY FAILURES*, *NOTIFY DELAYS*, *NOTIFY SUCCESSES*, etc., indicating the message's delivery receipt mechanism and flagging.
7. Notification addresses (reserved for future use).

Error messages

Usually errors reported by pmdf test -rewrite are not actually errors regarding pmdf test -rewrite in particular, but rather are the utility warning of an underlying configuration problem. For instance, "Error in mm_init: ..." sorts of errors; see Section 36.3 for a discussion of many such general error messages.

Insufficient privileges to run test -rewrite 
      

Must be run as superuser or by a user in the pmdf_world group.

Address list error -- unknown host or domain: 
      

The domain name in the specified address did not rewrite to any PMDF channel. Check that the domain name was correctly spelled. If the domain name was correct, then most likely you need a new (or changed) rewrite rule in the PMDF configuration file to handle that domain name; see Section 2.2.

Unknown group identifier ... found on channel ... 
      

You do not have the specified group identifier. Check that it is truly intended to be present as a group identifier, rather than simply being a misspelled channel keyword.