X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/448dd2a7475f0009820f874e8da381cfaee4a679..94187a80bd60baab4b9c4b949ad820d730578123:/man/inc.man diff --git a/man/inc.man b/man/inc.man index 73a5bcd4..56764a31 100644 --- a/man/inc.man +++ b/man/inc.man @@ -1,16 +1,18 @@ -.\" +.TH INC %manext1% 2016-11-02 "%nmhversion%" +. .\" %nmhwarning% -.\" -.TH INC %manext1% "%nmhdate%" MH.6.8 [%nmhversion%] XXX +. .SH NAME -inc \- incorporate new mail +inc \- incorporate new mail to an nmh folder .SH SYNOPSIS .HP 5 .na .B inc +.RB [ \-help ] +.RB [ \-version ] .RI [ +folder ] .RB [ \-audit -.IR audit\-file ] +.IR audit-file ] .RB [ \-noaudit ] .RB [ \-changecur " | " \-nochangecur ] .RB [ \-form @@ -25,24 +27,25 @@ inc \- incorporate new mail .IR columns ] .RB [ \-host .IR hostname ] +.RB [ \-port +.IR portname/number ] .RB [ \-user .IR username ] -.RB [ \-pack -.IR file ] -.RB [ \-nopack ] .RB [ \-proxy .IR command ] -.RB [ \-sasl ] +.RB [ \-sasl " | " \-nosasl ] .RB [ \-saslmech .IR mechanism ] +.RB [ \-authservice +.IR service ] +.RB [ \-initialtls ] +.RB [ \-notls ] +.RB [ \-certverify " | " \-nocertverify ] .RB [ \-snoop ] -.RB [ \-version ] -.RB [ \-help ] .ad .SH DESCRIPTION -.B Inc -incorporates mail from the user's incoming mail drop into -an +.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 @@ -50,15 +53,15 @@ If the mail drop is a file, it can be in or .B MMDF format. -If the mail drop is a directory it will considered to be a +If the mail drop is a directory it is considered to be in .B Maildir -format mail drop. +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) +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. @@ -66,28 +69,26 @@ 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 +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 -If the user's profile contains a +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 -entry, it will be used as the protection on the newly created -messages, otherwise the -.B nmh -default of 0600 will be used (on filesystems that support it). For -all subsequent operations on these messages, this initially assigned -protection will be preserved. +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 profile), then +.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 end of the specified audit\-file with the format: +will append a header line and a line per message to the specified +audit-file with the format: .PP .RS 5 .nf @@ -105,29 +106,31 @@ Eventually, .BR comp , and .B dist -may also produce audits to this (or another) file, perhaps with +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 -will be in the user's nmh directory unless a full path is specified. +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 +.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. .PP -In all cases, the user's mail drop will be zeroed, unless the +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. .PP If the profile entry .RI \*(lq Unseen\-Sequence \*(rq -is present and non\-empty, then +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 add each of the newly incorporated messages to -each sequence named by the profile entry. -.B Inc will not zero each sequence prior to adding messages. .PP The interpretation of the @@ -139,37 +142,46 @@ and .B \-width .I columns switches is the same as in -.BR scan . +.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 maildrop. -Note that the name file will NOT be zeroed, unless the +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 maildrop instead of the default +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 +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 +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 maildrop. +will look in the standard system location for the user's mail drop. .PP The .B \-silent @@ -178,11 +190,10 @@ switch directs 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. -.PP .SS "Using POP" .B inc -will normally check local mail drops for mail, as covered above. But -if the option +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, @@ -197,43 +208,18 @@ will query this POP service host for mail to incorporate. If .B $MAILHOST is set and .B \-host -is specified as well, the commandline switch will override -the environment variable. +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 -The default is for -.B inc -to assume that your account name on -the POP server is the same as your current username. To specify -a different username, use the +To specify a username for authentication with the POP server, use the .B \-user .I username -switch. -.PP -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 -.RI \*(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 -.IR mypopserver , -.IR mylogin , -and -.I mypassword -with your own account information. -.PP -.RS 5 -.B machine -.I mypopserver -.B login -.I mylogin -.B password -.I mypassword -.RE -.PP -This -.RI \*(lq .netrc \*(rq -file should be owned and readable only by you. +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 @@ -241,38 +227,27 @@ If passed the switch, .B inc will use the specified command to establish the connection to the POP -server. The string -.IR %h +server. The string +.I %h in the command will be substituted by the hostname to connect to. .PP -If -.B inc -uses POP, then the -.B \-pack -.I file -switch is considered. If given, then -.B inc -simply uses the POP to -.B packf -the user's maildrop from the POP service host to the named file. This switch -is provided for those users who prefer to use -.B msh -to read their maildrops. -.PP For debugging purposes, you may give the switch .BR \-snoop , -which will allow you to watch the POP transaction take place -between you and the POP server. +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 -.RI \*(lq .netrc \*(rq -file can be used to store this password). The +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 @@ -282,45 +257,123 @@ 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. - +switch; see +.IR post (8)'s +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 -.fc ^ ~ -.nf -.ta \w'%etcdir%/ExtraBigFileName 'u -^$HOME/\&.mh\(ruprofile~^The user profile -^%etcdir%/mts.conf~^nmh mts configuration file -^%mailspool%/$USER~^Location of mail drop -.fi - +.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" -.fc ^ ~ -.nf -.ta 2.4i -.ta \w'ExtraBigProfileName 'u -^Path:~^To determine the user's nmh directory -^Alternate\-Mailboxes:~^To determine the user's mailboxes -^Inbox:~^To determine the inbox, default \*(lqinbox\*(rq -^Folder\-Protect:~^To set mode when creating a new folder -^Msg\-Protect:~^To set mode when creating a new message and audit\-file -^Unseen\-Sequence:~^To name sequences denoting unseen messages -.fi - +.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" -mhmail(1), scan(1), mh\-mail(5), post(8) - +.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 -.nf -.RB ` +folder "' defaulted by \*(lqInbox\*(rq above" -.RB ` \-noaudit ' -.RB ` \-changecur ' -.RB ` \-format "' defaulted as described above" -.RB ` \-nosilent ' -.RB ` \-truncate "' if `" \-file " name' not given, `" \-notruncate "' otherwise" -.RB ` \-width "' defaulted to the width of the terminal" -.RB ` \-nopack ' -.fi - +.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 @@ -329,12 +382,3 @@ message, unless the option is specified. This leaves the context ready for a .B show of the first new message. - -.SH BUGS -The argument to the -.B \-format -switch must be interpreted as a single -token by the shell that invokes -.BR inc . -Therefore, one must usually place the argument to this switch inside -quotes.