X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/0d1c5f533f3a6cd1c7f038f59585378f53b666c2..1dd139e04f59bbfa3a310c2776c4bb2e2fdf1fdd:/man/inc.man diff --git a/man/inc.man b/man/inc.man index dda206c6..61624195 100644 --- a/man/inc.man +++ b/man/inc.man @@ -1,199 +1,384 @@ -.\" +.TH INC %manext1% 2016-11-02 "%nmhversion%" +. .\" %nmhwarning% -.\" $Id$ -.\" -.\" include the -mh macro file -.so %etcdir%/tmac.h -.\" -.TH INC %manext1% MH.6.8 [%nmhversion%] +. .SH NAME -inc \- incorporate new mail +inc \- incorporate new mail to an nmh folder .SH SYNOPSIS -.in +.5i -.ti -.5i -inc -\%[+folder] -\%[\-audit\ audit\-file] \%[\-noaudit] -\%[\-changecur] -.br -\%[\-nochangecur] -\%[\-form\ formatfile] -\%[\-format\ string] -.br -\%[\-file\ name] -\%[\-silent] \%[\-nosilent] -\%[\-truncate] -.br -\%[\-notruncate] -\%[\-width\ columns] -%nmhbeginpop% -\%[\-host\ hostname] -.br -\%[\-user\ username] -\%[\-pack\ file] -\%[\-nopack] -\%[\-kpop] -.br -%nmhendpop% -\%[\-version] -\%[\-help] -.in -.5i +.HP 5 +.na +.B inc +.RB [ \-help ] +.RB [ \-version ] +.RI [ +folder ] +.RB [ \-audit +.IR audit-file ] +.RB [ \-noaudit ] +.RB [ \-changecur " | " \-nochangecur ] +.RB [ \-form +.IR formfile ] +.RB [ \-format +.IR string ] +.RB [ \-file +.IR name ] +.RB [ \-silent " | " \-nosilent ] +.RB [ \-truncate " | " \-notruncate ] +.RB [ \-width +.IR columns ] +.RB [ \-host +.IR hostname ] +.RB [ \-port +.IR portname/number ] +.RB [ \-user +.IR username ] +.RB [ \-proxy +.IR command ] +.RB [ \-sasl " | " \-nosasl ] +.RB [ \-saslmech +.IR mechanism ] +.RB [ \-authservice +.IR service ] +.RB [ \-initialtls ] +.RB [ \-notls ] +.RB [ \-certverify " | " \-nocertverify ] +.RB [ \-snoop ] +.ad .SH DESCRIPTION -\fIInc\fR incorporates mail from the user's incoming mail drop into -an \fInmh\fR folder. - -You may specify which folder to use with `+folder'. If no folder -is specified, then \fIinc\fR will use either the folder given by a -(non\-empty) \*(lqInbox:\*(rq entry in the user's profile, or the folder -named \*(lqinbox\*(rq. If the specified (or default) folder doesn't +.B inc +incorporates mail from the user's incoming mail drop into an +.B nmh +folder. +If the mail drop is a file, it can be in +.B mbox +or +.B MMDF +format. +If the mail drop is a directory it is considered to be in +.B Maildir +format. +.PP +You may specify which folder to use with +.IR +folder . +If no folder is specified, then +.B inc +will use either the folder given by a (non-empty) +.RI \*(lq Inbox \*(rq +entry in the user's profile, or the folder named +.RI \*(lq inbox \*(rq. +If the specified (or default) folder doesn't exist, the user will be queried prior to its creation. - +.PP When the new messages are incorporated into the folder, they are assigned -numbers starting with the next highest number for the folder. As the -messages are processed, a \fIscan\fR listing of the new mail is produced. - -If the user's profile contains a \*(lqMsg\-Protect: nnn\*(rq entry, it -will be used as the protection on the newly created messages, otherwise -the \fInmh\fR default of 0644 will be used. For all subsequent operations -on these messages, this initially assigned protection will be preserved. - -If the switch `\-audit\ audit\-file' is specified (usually as a default -switch in the profile), then \fIinc\fR will append a header line and a -line per message to the end of the specified audit\-file with the format: - +numbers starting with the next highest number for the folder. +As the messages are processed, a +.B scan +listing of the new mail is produced. +.PP +The newly created messages will have a mode of 0600, see chmod(1), +on filesystems that support it. +Alternatively, a +.RI \*(lq "Msg\-Protect: nnn" \*(rq +profile entry gives the mode to use, in octal. +For all subsequent operations on these messages, this initially assigned +mode will be preserved. +.PP +If the switch +.B \-audit +.I audit-file +is specified (usually as a default switch in the user's profile), then +.B inc +will append a header line and a line per message to the specified +audit-file with the format: +.PP +.RS 5 .nf -.ti 1i -\*(<> date -.ti 1.5i +<> date -.ti 1.5i -.ti 2.5i .fi - +.RE +.PP This is useful for keeping track of volume and source of incoming mail. -Eventually, \fIrepl\fR, \fIforw\fR, \fIcomp\fR, and \fIdist\fR -may also produce audits to this (or another) file, perhaps with -\*(lqMessage\-Id:\*(rq information to keep an exact correspondence -history. \*(lqAudit\-file\*(rq will be in the user's nmh directory unless -a full path is specified. - -\fIInc\fR will incorporate even improperly formatted messages into the -user's nmh folder, inserting a blank line prior to the offending component +Eventually, +.BR repl , +.BR forw , +.BR comp , +and +.B dist +may also output audit information to this (or another) file, perhaps with +.RI \*(lq Message\-Id \*(rq +information to keep an exact correspondence history. +.RI \*(lq Audit-file \*(rq +is assumed to be in the user's nmh directory unless a full path is specified. +.PP +.B inc +will incorporate even improperly formatted messages into the user's +nmh folder, inserting a blank line prior to the offending component and printing a comment identifying the bad message. - -In all cases, the user's mail drop will be zeroed, unless the -`\-notruncate' switch is given. - -If the profile entry \*(lqUnseen\-Sequence\*(rq is present and non\-empty, -then \fIinc\fR will add each of the newly incorporated messages to -each sequence named by the profile entry. \fIInc\fR will not zero each -sequence prior to adding messages. - -The interpretation of the `\-form\ formatfile', `\-format\ string', and -`\-width\ columns' switches is the same as in \fIscan\fR\0(1). - -By using the `\-file\ name' switch, one can direct \fIinc\fR to -incorporate messages from a file other than the user's maildrop. -Note that the name file will NOT be zeroed, unless the `\-truncate' +.PP +In all cases, except the use of +.B \-file +.I name +(see below), the user's mail drop will be zeroed, unless the +.B \-notruncate switch is given. - -If the environment variable \fB$MAILDROP\fR is set, then \fIinc\fR -uses it as the location of the user's maildrop instead of the default -(the `-file\ name' switch still overrides this, however). If this -environment variable is not set, then \fIinc\fR will consult the profile -entry \*(lqMailDrop\*(rq for this information. If the value found is -not absolute, then it is interpreted relative to the user's \fInmh\fR -directory. If the value is not found, then \fIinc\fR will look in the -standard system location for the user's maildrop. - -The `\-silent' switch directs \fIinc\fR to be quiet and not ask any -questions at all. This is useful for putting \fIinc\fR in the background -and going on to other things. -%nmhbeginpop% - -.Uh "Using POP" -\fIinc\fR will normally check local mail drops for mail, as given -above. But if the option \*(lqpophost:\*(rq is set in the mts -configuration file \*(lqmts.conf\*(rq, or if the `\-host\ hostname' -switch is given, then \fIinc\fR will query this POP service host -for mail to incorporate. - -The default is for \fIinc\fR to assume that your account name on -the POP server is the same as your current username. To specify -a different username, use the `\-user\ username' switch. - -When using POP, you will normally need to type the password for -your account on the POP server, in order to retrieve your messages. -It is possible to automate this process by creating a \*(lq.netrc\*(rq -file containing your login account information for this POP server. -For each POP server, this file should have a line of the following -form. Replace the words mypopserver, mylogin, and mypassword with -your own account information. - -machine mypopserver login mylogin password mypassword - -This \*(lq.netrc\*(rq file should be owned and readable only by -you. - -If \fIinc\fR uses POP, then the `\-pack\ file' switch is considered. -If given, then \fIinc\fR simply uses the POP to \fIpackf\fR\0(1) the -user's maildrop from the POP service host to the named file. This switch -is provided for those users who prefer to use \fImsh\fR to read their -maildrops. - -For debugging purposes, you may give the switch `\-snoop', which will -allow you to watch the POP transaction take place between you and the -POP server. - -If nmh has been compiled with KPOP #defined, but without POPSERVICE being set to -"kpop", the -kpop switch may be specified to cause the use of Kerberized POP -rather than standard POP3 during a given invocation of \fIinc\fR. -%nmhendpop% -.Fi -^$HOME/\&.mh\(ruprofile~^The user profile -^%etcdir%/mts.conf~^nmh mts configuration file -^%mailspool%/$USER~^Location of mail drop -.Pr -^Path:~^To determine the user's nmh directory -.Ps -^Alternate\-Mailboxes:~^To determine the user's mailboxes -.Ps -^Inbox:~^To determine the inbox, default \*(lqinbox\*(rq -.Ps -^Folder\-Protect:~^To set mode when creating a new folder -.Ps -^Msg\-Protect:~^To set mode when creating a new message and audit\-file -.Ps -^Unseen\-Sequence:~^To name sequences denoting unseen messages -.Sa -mhmail(1), scan(1), mh\-mail(5), post(8) -.De -`+folder' defaulted by \*(lqInbox\*(rq above -.Ds -`\-noaudit' -.Ds -`\-changecur' -.Ds -`\-format' defaulted as described above -.Ds -`\-nosilent' -.Ds -`\-truncate' if `\-file\ name' not given, `\-notruncate' otherwise -.Ds -`\-width' defaulted to the width of the terminal -%nmhbeginpop% -.Ds -`\-nopack' -%nmhendpop% -.Co +.PP +If the profile entry +.RI \*(lq Unseen\-Sequence \*(rq +is present and non-empty, then +.B inc +will add each of the newly incorporated messages to each sequence +named in the profile entry. +.B inc +will not zero each sequence prior to adding messages. +.PP +The interpretation of the +.B \-form +.IR formatfile , +.B \-format +.IR string , +and +.B \-width +.I columns +switches is the same as in +.IR scan (1). +.PP +By using the +.B \-file +.I name +switch, one can direct +.B inc +to incorporate messages from a file other than the user's mail drop. +Note that the named file will +.I not +be zeroed, unless the +.B \-truncate +switch is given. +.PP +The +.B \-file +switch does not support the use of standard input. +Instead, the +.B rcvstore +command can be used to incorporate mail from the standard input stream. +.PP +If the environment variable +.B $MAILDROP +is set, then +.B inc +uses it as the location of the user's mail drop instead of the default +(the +.B -file +.I name +switch still overrides this, however). +If this environment variable is not set, then +.B inc +will consult the profile entry +.RI \*(lq MailDrop \*(rq +for this information. If the value found is not absolute, then it is +interpreted relative to the user's +.B nmh +directory. If the value is not found, then +.B inc +will look in the standard system location for the user's mail drop. +.PP +The +.B \-silent +switch directs +.B inc +to be quiet and not ask any questions at all. This is useful for putting +.B inc +in the background and going on to other things. +.SS "Using POP" +.B inc +will normally check local mail drops for mail, as covered above. +But if the option +.RI \*(lq pophost \*(rq +is set in +.RI \*(lq mts.conf \*(rq, +or if the +.B \-host +.I hostname +switch is given, or if the +.B $MAILHOST +environment variable is set, then +.B inc +will query this POP service host for mail to incorporate. If +.B $MAILHOST +is set and +.B \-host +is specified as well, the command-line switch will override +the environment variable. The +.B \-port +switch specifies the port name or number used to connect to the POP +server. If unspecified, the default is \*(lqpop3\*(rq. +.PP +To specify a username for authentication with the POP server, use the +.B \-user +.I username +switch. The credentials profile entry in +.IR mh\-profile (5) +describes the ways to supply a username and password. +.PP +If passed the +.B \-proxy +.I command +switch, +.B inc +will use the specified command to establish the connection to the POP +server. The string +.I %h +in the command will be substituted by the hostname to connect to. +.PP +For debugging purposes, you may give the switch +.BR \-snoop , +which will allow you to monitor the POP transaction. If +.B \-sasl \-saslmech xoauth2 +is used, the HTTP transaction is also shown. +.PP +If +.B nmh +has been compiled with SASL support, the +.B \-sasl +switch will enable the use of SASL authentication. +Depending on the SASL mechanism used, this may require an +additional password prompt from the user (but the +.I netrc +file can be used to store this password, as described in +.IR mh\-profile (5)). +The +.B \-saslmech +switch can be used to select a particular SASL mechanism. +.PP +If SASL authentication is successful, +.B inc +will attempt to negotiate a security layer for session encryption. +Encrypted traffic is labelled with `(encrypted)' and `(decrypted)' +when viewing the POP transaction with the +.B \-snoop +switch; see the +.B post +man page description of +.B \-snoop +for its other features. +.PP +If +.B nmh +has been compiled with OAuth support, the +.B \-sasl +and +.B \-saslmech xoauth2 +switches will enable OAuth authentication. The +.B \-user +switch must be used, and the +.I user-name +must be an email address the user has for the service, which must +be specified with the +.B \-authservice +.I service +switch. Before using this, the user must authorize nmh by running +.B mhlogin +and granting authorization to that account. See +.IR mhlogin (1) +for more details. +.PP +If +.B nmh +has been compiled with TLS support, the +.B \-initialtls +switch will require the negotiation of TLS when connecting +to the remote POP server. +.B inc +will negotiate TLS immediately after the connection has taken place, +before any POP commands are sent or received. Data encrypted by TLS is +labeled `(tls-encrypted)' and `(tls-decrypted)` when viewing the POP +transaction with the +.B \-snoop +switch. The +.B \-notls +switch will disable all attempts to negotiate TLS. +.PP +When using TLS the default is to verify the remote certificate and SubjectName +against the local trusted certificate store. This can be controlled by +the +.B \-certverify +and +.B \-nocertverify +switches. See your OpenSSL documentation for more information on certificate +verification. +.SH FILES +.PD 0 +.TP 20 +$HOME/.mh_profile +The user's profile. +.TP +%nmhetcdir%/mts.conf +mts configuration file. +.TP +%mailspool%/$USER +Location of the system mail drop. +.PD +.SH "PROFILE COMPONENTS" +.PD 0 +.TP 20 +Path: +To determine the user's nmh directory. +.TP +Alternate\-Mailboxes: +To determine the user's mailboxes. +.TP +Inbox: +To determine the inbox. +.TP +Folder\-Protect: +To set mode when creating a new folder. +.TP +Msg\-Protect: +To set mode when creating a new message and audit-file. +.TP +Unseen\-Sequence: +To name sequences denoting unseen messages. +.PD +.SH "SEE ALSO" +.IR mhmail (1), +.IR scan (1), +.IR mh\-mail (5), +.IR mh\-profile (5), +.IR mhlogin (1), +.IR post (8), +.IR rcvstore (1) +.SH DEFAULTS +.PD 0 +.TP 20 ++folder +defaulted by \*(lqInbox\*(rq above. +.TP +\-noaudit +.TP +\-changecur +.TP +\-format +As described above. +.TP +\-nosilent +.TP +\-nosasl +.TP +\-notruncate +Unless +.B \-file +.I name +is given. +.TP +\-width +The width of the terminal. +.PD +.SH CONTEXT The folder into which messages are being incorporated will become the current folder. The first message incorporated will become the current -message, unless the `\-nochangecur' option is specified. This leaves -the context ready for a \fIshow\fR of the first new message. -.Bu -The argument to the `\-format' switch must be interpreted as a single -token by the shell that invokes \fIinc\fR. Therefore, one must usually -place the argument to this switch inside double\-quotes. -.En +message, unless the +.B \-nochangecur +option is specified. This leaves the context ready for a +.B show +of the first new message.