submit(ADM) 06 January 1993 submit(ADM) Name submit - MMDF mail queue manager Syntax /usr/mmdf/bin/submit [ -L...*V...*Wbcdf...*g...*hi...*jk...*lmnqrstuvwx...*yz ] Description All mail is entered into the MMDF mail transport environment through the submit program. This document is intended to provide the specific infor- mation needed to control submit. While it can be called directly from a user's terminal, access to submit is most conveniently performed through a program such as mail(C). Basic modes submit permits considerable flexibility with respect to batching multiple submissions, response and error handling, and address source specifica- tion. Multiple submissions 1. Terminate after one submission, such as is carried out by the mail command, or 2. permit multiple message submissions, as is done by the SMTP channel. The first mode is specified by passing any initialization information in the submit invocation line (that is, the exec(S) 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 seg- ment 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). 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 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 g...* explicit) 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 b. user will watch w attempts 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 (for example 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. From/Sender 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 field 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 list source An explicit list has one address per line. When x or g are speci- fied, they list the names of message components, such as To: and CC:, which are to be searched for addresses. 5. Address 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 submis- sion. 6. Delivery destination Mail may be delivered to a recipient's mailbox (file), online termi- nal (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. 7. Delivery 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, Pas- sive, 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 back- ground 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 per- formed detached. 9. Return address If the invoker of submit is not to receive return mail (e.g., notifi- cation of delivery failure) then the next input line (the first, if settings are specified in the exec(S) 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 reci- pient). 10. Returned mail 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. Delay channel usage The delay channel is used to process mail submissions that could not be 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, an 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 do not 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 addres- see, 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 log- file to be used. It can be terminated by a ``*'' or the end of the arguments. This option is only available to the super user 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 super user 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 Interna- tional. 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 delimiters are recognized within the local part of addresses (in order of precedence): @ % ! The ``!'' delimiter 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 recogni- tion of the ``.'' delimiter is a site-selectable option. Also, addresses may be indirectly referenced, through a file specifica- tion 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 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), indicating submis- sion status. 2. Standard, multi-message protocol: a. Invoke: No parameters b. To: Initialization information line. A typical user pro- gram 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 verif- ication 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 chan- nels 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 (unavaila- bility). 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 configu- ration 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 deliver(ADM) and mmdf(S). Return codes The following, excerpted from MMDF source, lists the return codes. /* Reply Codes for MMDF * Based on: "Revised FTP Reply Codes", by Jon Postel&Nancy Neigus Arpanet * RFC 640 / NIC 30843, in the "Arpanet Protocol Handbook", E. Feinler * and J. Postel (eds.), NIC 7104, Network Information Center, SRI * International: Menlo Park, CA. (NTIS AD-A0038901) * * Actual values are different, but scheme is same. Codes must fit into * 8-bits (to pass on exit() calls); fields are packed 2-3-3 and * interpreted as octal numbers. * * Basic format: * * 0yz: positive completion; entire action done * 1yz: positive intermediate; only part done * 2yz: Transient negative completion; may work later * 3yz: Permanent negative completion; you lose forever * * x0z: syntax * x1z: general; doesn't fit any other category * x2z: connections; truly transfer-related * x3z: user/authentication/account * x4x: mail * x5z: file system * * 3-bit z field is unique to the reply. In the following, * the RP_xVAL defines are available for masking to obtain a field. */ /* ************** FIELD DEFINITIONS & BASIC VALUES ****************** */ /* Field 1: Basic degree of success (2-bits) */ #define RP_BTYP '200' /* good vs. bad; on => bad */ #define RP_BVAL '300' /* basic degree of success */ #define RP_BOK ' 00' /* went fine; all done */ #define RP_BPOK '100' /* only the first part got done */ #define RP_BTNO '200' /* temporary failure; try later */ #define RP_BNO '300' /* not now, nor never; you lose */ /* Field 2: Basic domain of discourse (3-bits) */ #define RP_CVAL ' 70' /* basic category (domain) of reply */ #define RP_CSYN '\000' /* purely a matter of form */ #define RP_CGEN '\010' /* couldn't find anywhere else for it */ #define RP_CCON '\020' /* data-transfer-related issue */ #define RP_CUSR '\030' /* pertaining to the user */ #define RP_CMAI '\040' /* specific to mail semantics */ #define RP_CFIL '\050' /* file system */ #define RP_CLIO '\060' /* local i/o system */ /* Field 3: Specific value for this reply (3-bits) */ #define RP_SVAL '\007' /* specific value of reply */ /* ******************** SPECIFIC SUCCESS VALUES ******************** */ /* Complete Success */ #define RP_DONE (RP_BOK | RP_CGEN | '\000') /* done (e.g., w/trans.) */ #define RP_OK (RP_BOK | RP_CGEN | '\001') /* general-purpose OK */ #define RP_MOK (RP_BOK | RP_CMAI | '\000') /* message is accepted (w/text) */ #define RP_DOK (RP_BOK | RP_CGEN | '\003') /* accepted for the delayed submission channel */ /* Partial Success */ #define RP_MAST (RP_BPOK| RP_CGEN | '\000') /* you are the requestor */ #define RP_SLAV (RP_BPOK| RP_CGEN | '\001') /* you are the requestee */ #define RP_AOK (RP_BPOK| RP_CMAI | '\000') /* message address accepted */ #define RP_HOK (RP_BPOK| RP_CMAI | '\001') /* host processing complete */ /* ******************** SPECIFIC FALURE VALUES ********************* */ /* Partial Failure */ #define RP_AGN (RP_BTNO | RP_CGEN | '\000') /* not now; maybe later */ #define RP_TIME (RP_BTNO | RP_CGEN | '\001') /* timeout */ #define RP_NOOP (RP_BTNO | RP_CGEN | '\002') /* no-op; nothing done */ #define RP_EOF (RP_BTNO | RP_CGEN | '\003') /* encountered an EOF */ #define RP_NET (RP_BTNO | RP_CCON | '\000') /* channel went bad */ #define RP_BHST (RP_BTNO | RP_CCON | '\001') /* foreign host screwed up */ #define RP_DHST (RP_BTNO | RP_CCON | '\002') /* host went away */ #define RP_NIO (RP_BTNO | RP_CCON | '\004') /* general net i/o problem */ #define RP_NS (RP_BTNO | RP_CCON | '\005') /* temp nameserver failure */ #define RP_FIO (RP_BTNO | RP_CFIL | '\000') /* err reading/writing file */ #define RP_FCRT (RP_BTNO | RP_CFIL | '\001') /* unable to create file */ #define RP_FOPN (RP_BTNO | RP_CFIL | '\002') /* unable to open file */ #define RP_LIO (RP_BTNO | RP_CLIO | '\000') /* general local i/o problem */ #define RP_LOCK (RP_BTNO | RP_CLIO | '\001') /* resource currently locked */ /* Complete Failure */ #define RP_MECH (RP_BNO | RP_CGEN | '\000') /* bad mechanism/path; try alternate? */ #define RP_NO (RP_BNO | RP_CGEN | '\001') /* general-purpose NO */ #define RP_PROT (RP_BNO | RP_CCON | '\000') /* general prototocol error */ #define RP_RPLY (RP_BNO | RP_CCON | '\001') /* bad reply code (PERMANENT ERROR) */ #define RP_NAUTH (RP_BNO | RP_CUSR | '\001') /* bad authorisation */ /* SEK this will be used for user checks */ #define RP_NDEL (RP_BNO | RP_CMAI | '\000') /* couldn't deliver */ #define RP_HUH (RP_BNO | RP_CSYN | '\000') /* couldn't parse request */ #define RP_NCMD (RP_BNO | RP_CSYN | '\001') /* no such command defined */ #define RP_PARM (RP_BNO | RP_CSYN | '\002') /* bad parameter */ #define RP_UCMD (RP_BNO | RP_CSYN | '\003') /* command not implemented */ #define RP_USER (RP_BNO | RP_CUSR | '\000') /* unknown user */ /* STRUCTURE OF A REPLY STRING */ struct rp_construct /* for constant reply conditions */ { char rp_cval; char rp_cline[50]; }; #define RP_LINEBUF_MAX 256 struct rp_bufstruct /* for reading reply strings */ { char rp_val; char rp_line[RP_LINEBUF_MAX]; }; typedef struct rp_bufstruct RP_Buf; #define rp_conlen(bufnam) (strlen(bufnam.rp_cline) + sizeof(bufnam.rp_cval)) /* PSEUDO-FUNCTIONS TO ACCESS REPLY INFO */ #define rp_gval(val) ((char) (val)) /* get the entire return value */ /* The next three give the field's bits, within the whole value */ #define rp_gbval(val) (rp_gval (val) & RP_BVAL) /* get the basic part of return value */ #define rp_gcval(val) (rp_gval (val) & RP_CVAL) /* get the domain part of value */ #define rp_gsval(val) (rp_gval (val) & RP_SVAL) /* get the specific part of value */ /* The next three give the numeric value withing the field */ #define rp_gbbit(val) ((rp_gval (val) >> 6) & 03) /* get the basic part right-shifted */ #define rp_gcbit(val) ((rp_gval (val) >> 3 ) & 07) /* get the domain part right-shifted */ #define rp_gsbit(val) (rp_gval (val) & 07) /* get the specific part right-shifted */ /* The following works with SIGNED or UNSIGNED chars! */ #define rp_isgood(val) (! rp_isbad(val)) /* is return value positive? */ #define rp_isbad(val) (rp_gval(val) & 0200) /* is return value negative? */ extern char *rp_valstr (); Credit MMDF was developed at the University of Delaware and is used with permission.