SUBMIT(8)

NAME
submit - MMDF mail enqueuer

SYNOPSIS
submit [-L...*V...*Wbcdf...*g...*hi...*jk...*lmnqrstuvwxyz]

DESCRIPTION

All mail is entered into the MMDF mail transport environment through the submit program. This document is intended to provide the specific information needed to control submit. While it can be called directly from a user's terminal, access to submit is most conveniently done through a program such as v6mail(1) or send(1). The MMDF library also has subroutine package for invoking submit. See the mm_ package, documented in mmdf(3) for more information. It has a set of procedures which make this process much easier. Before proceeding, familiarity with the channels(7) document is recommended, since mm is a member of the family of channel modules. It also will be useful to read replies(5), which describes reply values.

  BASIC MODES

Submit permits considerable flexibility with respect to batching multiple submissions, response and error handling, and address source specification.

  Multiple Submissions

1.  Terminate after one submission, such as is done by the mail command, or

2.  Permit multiple message submissions, as is done by the SMTP channel and the MMDF telephone slave.

The first mode is specified by passing any initialization information in the submit invocation line (i.e., the exec(2) call). In the second mode, the initialization information is given as the first input line, for each submission. The format of this information is the same for both modes.

  Response & Error Handling

1.  Accept input until error or end of message, but terminate on any error, or

2.  Notify result for each segment and continue.

Response mode #1 is mandatory with Multiple mode #1. Response mode #2 is called protocol mode. During it, each address produces a status reply and the message text produces a reply. The domain of the term segment depends on the error. Simple addressing errors cause rejection only of the erroneous address. Other errors may cause rejection of the entire message, but permit submission of following messages.

  Addresses

1.  Extracted from components of the message text,

2.  Explicit list given, ahead of message text, or

3.  Both of the above (extracted and explicit addresses)

The first mode is common when mode #1 (non-protocol) is also in force for the Interaction and the Verification option. The second mode is commonly in force when the second modes apply for the other options (protocol mode). The third mode is of unclear benefit, but was easy to provide and originally looked like a good idea.

  INITIALIZATION

A message's initialization information is specified through a single string, passed either in the process-invocation argument list or in the first line of submit's input. Hence, the string may be terminated either by a null or newline. Spaces and tabs in the line are ignored, unless part of a literal. Specification is only required for non-defaults.

	Option	Value	Literal
1.	Relay source	a. none	(default)
	for the ``Via'' or	b. source channel	i...*
	``Received'' field	c. source host	h...*
2.	From/Sender	a. reject on error	(default)
	authentication	b. trust	t
		c. no trust (disclaim)	u
3.	Source-Info Field	a. not included	(default)
		b. disclaim author	u
		c. user text	f...*
4.	Address list source	a. explicit list	(default)
		b. extract from components	x...*
		c. both (extract and explicit)	g...*
5.	Address verification	a. abort on invalid	(default)
		b. report on each address	v
6.	Delivery destination	a. mailbox	m (default)
		b. user's tty	y
		c. mailbox and tty	b
7.	Delivery attempt	a. leave for daemon	(default)
	(combinable)	b. deliver local now	l
		c. deliver netmail now	n
8.	Observation of	a. none	(default)
	immediate attempts	b. user will watch	w
9.	Return address	a. send to submittor	r
		b. send to ``Sender:''	s
		c. do not return	q
		d. as specified	(next line)
10.	Returned mail	a. entire original	(default)
	contents	b. citation only	c
11.	Warnings	a. send warnings	(default)
		b. do not send warnings	z
12.	Delay channel	a. enable delay channel	(default)
	usage	b. don't use delay	d
13.	Delay channel	a. not delay channel	(default)
	indicator	b. delay channel	j
14.	Nameserver	a. short timeouts	(default)
	timeouts	b. as specified	k...*
15.	Submission	a. not shown	(default)
	tracing	b. watch submission	W
16.	Logging file	a. as per msglog	(default)
		b. as specified	L...*
17.	Logging level	a. as per msglog	(default)
		b. as specified	V...*

  Comments

General
    Literals shown as characters, followed by an ellipsis, followed by an asterisk (e.g. x...*), represent a string. The first character specifies the nature of the setting. The value for the setting is placed between that character and the asterisk. The value may be any string not containing an asterisk, null, or newline. The values for settings x and g are comma-separated lists of strings. These strings may not contain asterisks, nulls, newlines, or commas.

Specific

1. Relaying
    This is used when the calling program is interfacing with another distribution system, effecting relaying. The literal after the i specifies the channel the message is coming from. The h may be used, in conjunction with i, to specify the source host. The literal is the name of the host.

2. Authentication
    Normally, the message must correctly identify its sender. Anyone may send "anonymous" (unsigned) mail, but they must use the u setting which bypasses authentication. However, it also causes MMDF to include, in the Source-Info: component, a statement noting the absence of authentication. Only root or relays may use the t setting, which bypasses authentication and does not add a disclaimer. Others requesting it get u treatment.

3. Source-Info
    In addition to the action explained above, Source-Info: can directly receive text, from the user, through the f setting. The value string is replicated on a separate line in the field.

4. Address lists
    An explicit list has one address per line. When x or g are specified, they list the names of message components, such as ``To:'' and ``CC:'', which are to be searched for addresses.

5. Verification
    Normally, any illegal address will cause the entire message to be rejected. In v (verify) mode, the acceptability of each message is reported and encountering an illegal address does not abort submission.

6. Delivery type
    Mail may be delivered to a recipient's mailbox (file), online terminal (if the recipient is logged in), or a combination of the two. There is no default. For each message, its delivery mode must be specified. (Delivery to online terminals is likely to be removed in the near future.)

7. Attempt
    An immediate attempt causes a special deliver process to be forked and it will attempt to process the indicated mail immediately. (The n setting does not allow more granularity, for historical reasons.) Otherwise, the system's background daemon will get to it eventually. The daemon also handles mail that initially could not be delivered/relayed. A channel's descriptor structure (in chan.c or the runtime tailor file) specifies a channel as being Active, Passive, or Background. Only the first is processed by any request for immediate delivery. The second indicates a Post Office Box-style channel. The third limits the channel to processing by the background deliver daemon, which may be necessary for restricting access to special channels, such as dial-out telephones.

8. Observation
    If an immediate attempt is requested, the user may elect to watch its progress. Deliver and its children will report assorted aspects of their activity. If a quiet attempt is requested, submit returns as soon as submission is completed. That is, a quiet attempt is performed detached.

9. Return address
    If the invoker of submit is not to receive return mail (e.g., notification of delivery failure) then the next input line (the first, if settings are specified in the exec(2) call), contains an address that should receive the notification. It is not validated. If either the r or the s switch is given, submit will not read a line for the return address. If no return mail should be sent, the return address line should be empty (i.e., consist of a newline, only.) If the q switch is given, a return address is read from the next line of input but the local system will not return mail if delivery problems are encountered. The return address given may be used by other systems (if there are mail relays between the local system and the recipient).

10. Return contents
    Normally, a copy of the entire message is sent with a delivery-failure notice. Using the c switch causes a citation, comprising the message header and first three lines of non-blank lines of the body, to be sent. If more than 12 addresses are specified, for a message, citation-only is automatically set. In addition, no warning message will be sent for addresses which take a long time to process (a site dependent value); the final failure notice will always be sent, if there are addresses that are never fully processed.

11. Warnings
    Normally MMDF will send a non-delivery warning if a message has been undelivered after a small period (typically 12 to 72 hours, depending on the site). Deliver attempts continue until a timeout period is reached. This is typically after 3 to 10 days, depending on the site.

12. Disable delay channel
    The delay channel is used to process mail submissions that could not queued because necessary nameserver information was unavailable and therefore an authoritative decision on the validity of the address was not possible. If the d option is specified, use of the delay channel is prohibited. If the nameserver fails, a error is returned, rather than a conditional OK.

13. Delay channel indicator
    This option is intended only to be used by the delay channel itself to indicate to submit that the invoking process IS the delay channel. This option implies the d option above.

14. Nameserver timeouts
    By default, MMDF uses a short timeout algorithm. This is suitable for user interface programs which don't want to wait a long time for dead nameservers. The k option allows a different timeout to be set. The value given is the number of seconds to wait for the nameserver lookup to complete.

15. Submission tracing
    The W option causes submit to print a detailed description of its activities on file descriptor 2. It will indicate, for each addressee, the channel and addresses queued. This can generate a great deal of output if a mailing list is encountered, so it should be used with caution.

16. Logging file
    The L option allows the specification of an alternate logging file at runtime. The string following the L should be the name of the logfile to be used. It can be terminated by a * or the end of the arguments. This option is only available to the Superuser or MMDF.

17. Logging level
    The V option allows the setting of the logging level at runtime. The string following the V should be one of the valid MMDF logging level strings such as FTR or BST. It can be terminated by a * or the end of the arguments. This option is only available to the Superuser or MMDF.

  INPUT STREAM

The following augmented BNF characterizes submit's input (file descriptor zero) format:

    stream:
        *(init-seq '\n' msg-info null) [null]

    init-seq:
        *{ switches listed above }

    msg-info:
        [ret-addr] '\n'
        [addr-seq '!' '\n']
        { rfc822-format message }

    ret-addr:
        { rfc822-format (return) address }

    addr-seq:
        *{ rfc822-address }

  ADDRESS FORMAT

Addresses are expected to conform to the ARPANET mail standard known as RFC-822, available from the Network Information Center at SRI International. Submit (and MMDF in general) also continues to support RFC-733 style mail for compatibility with earlier mail systems.

In addition to those in RFC-822, the following address delimeters are recognized within the local part of addresses (in order of precedence):

    @
    %
    !
    .

The "!" delimeter is interpreted as "host!user" while the others are interpreted as "user?host". For example, the address "a.b!user%c@localhost" would be queued for "a.b!user@c". The address "a.b!user@localhost" would be queued for "user@a.b". The address "user.a@localhost" would be queued for "user@a". Note that recognition of the "." delimeter is a site-selectable option. The LEFTDOTS option is discussed in Installing and Operating MMDF II.

Also, addresses may be indirectly referenced, through a file specification of the form:

  ``<filename'' or ``:include:filename''

where the angle-bracket must be the first non-blank character of the specification (to distinguish it from the ``<...>'' usage, above). Addresses in the file may be separated by commas or newlines.

  EXAMPLE INTERACTIONS

Phases involve Invocation (Invoke), data sent into submit via its file descriptor zero (To), data returned from submit via its file descriptor one (From), iteration back to the specified phase (Loop), and process exit value (Exit).

1.  Simple, single-message, as with the v6mail command:

    a. Invoke:
        Parameters, ``-mlrxto,cc*'', indicate that the message is to be sent to recipients' mailboxes, local mail should be sent immediately, return mail goes to the submittor, and addresses are to be extracted from the ``To:'' and ``cc:`` components.

    b. To:
        The entire message

    c. From:
        Error messages

    d. Exit:
        Process return value, in wait(&val), taken from mmdf.h, indicating submission status.

2.  Standard, multi-message protocol:

    a. Invoke:
        No parameters

    b. To:
        Initialization information line. A typical user program might have "mlrv", indicating the message is to be sent to mailboxes, local mail sent immediately, return mail goes to the sender, and each address verification is to be reported. A relay program might have "mlntviVGR.BRL.MIL*", with "mlv" as above and the other settings indicating that mail for non-local channels is to be sent immediately, the author information is to be trusted, and the "Received: " component should cite the mail as being relayed via Internet host VGR.BRL.MIL.

    c. To:
        One address, terminated by a newline ('\n').

    d. From:
        Status character, from mmdf.h, plus human-oriented text plus newline.

    e. Loop:
        Back to (c). Terminate with address line having only an exclamation mark (!), with newline.

    f. To:
        Message text, in Internet RFC #822 format. Multi-line, terminated by null ('\0').

    g. From:
        Status character, text, newline.

    h. Loop:
        Back to (b). Terminate with initialization line having only a null, without newline.

CHANNELS

When MMDF is used in conjunction with the DARPA domain nameserver system, a ``delay'' channel should be configured to allow queuing of addresses that fail verification temporarily due to nameserver failures (unavailability). Two other special channels that can be configured are the ``badusers'' and ``badhosts'' channels. Mail to unknown users or unknown hosts will be queued to these channels if they are configured. The bad channels have no special code associated with them. The channel configuration should reference whatever table and program is necessary to reach a smarter host which can deliver or forward the mail. The channel should have the ``host='' parameter set to this host name. The channel names given above are reserved.

FILES
Numerous. Generally under the MMDF login directory.

SEE ALSO
send(1), mmdf(3), deliver(8)