diplodocus.org Git - nmh/blob - man/inc.man

   1 .TH INC %manext1% 2016-11-02 "%nmhversion%"
   2 .
   3 .\" %nmhwarning%
   4 .
   5 .SH NAME
   6 inc \- incorporate new mail to an nmh folder
   7 .SH SYNOPSIS
   8 .HP 5
   9 .na
  10 .B inc
  11 .RB [ \-help ]
  12 .RB [ \-version ]
  13 .RI [ +folder ]
  14 .RB [ \-audit
  15 .IR audit-file ]
  16 .RB [ \-noaudit ]
  17 .RB [ \-changecur " | " \-nochangecur ]
  18 .RB [ \-form
  19 .IR formfile ]
  20 .RB [ \-format
  21 .IR string ]
  22 .RB [ \-file
  23 .IR name ]
  24 .RB [ \-silent " | " \-nosilent ]
  25 .RB [ \-truncate " | " \-notruncate ]
  26 .RB [ \-width
  27 .IR columns ]
  28 .RB [ \-host
  29 .IR hostname ]
  30 .RB [ \-port
  31 .IR portname/number ]
  32 .RB [ \-user
  33 .IR username ]
  34 .RB [ \-proxy
  35 .IR command ]
  36 .RB [ \-sasl " | " \-nosasl ]
  37 .RB [ \-saslmech
  38 .IR mechanism ]
  39 .RB [ \-authservice
  40 .IR service ]
  41 .RB [ \-initialtls ]
  42 .RB [ \-notls ]
  43 .RB [ \-certverify " | " \-nocertverify ]
  44 .RB [ \-snoop ]
  45 .ad
  46 .SH DESCRIPTION
  47 .B inc
  48 incorporates mail from the user's incoming mail drop into an
  49 .B nmh
  50 folder.
  51 If the mail drop is a file, it can be in
  52 .B mbox
  53 or
  54 .B MMDF
  55 format.
  56 If the mail drop is a directory it is considered to be in
  57 .B Maildir
  58 format.
  59 .PP
  60 You may specify which folder to use with
  61 .IR +folder .
  62 If no folder is specified, then
  63 .B inc
  64 will use either the folder given by a (non-empty)
  65 .RI \*(lq Inbox \*(rq
  66 entry in the user's profile, or the folder named
  67 .RI \*(lq inbox \*(rq.
  68 If the specified (or default) folder doesn't
  69 exist, the user will be queried prior to its creation.
  70 .PP
  71 When the new messages are incorporated into the folder, they are assigned
  72 numbers starting with the next highest number for the folder.
  73 As the messages are processed, a
  74 .B scan
  75 listing of the new mail is produced.
  76 .PP
  77 The newly created messages will have a mode of 0600, see chmod(1),
  78 on filesystems that support it.
  79 Alternatively, a
  80 .RI \*(lq "Msg\-Protect: nnn" \*(rq
  81 profile entry gives the mode to use, in octal.
  82 For all subsequent operations on these messages, this initially assigned
  83 mode will be preserved.
  84 .PP
  85 If the switch
  86 .B \-audit
  87 .I audit-file
  88 is specified (usually as a default switch in the user's profile), then
  89 .B inc
  90 will append a header line and a line per message to the specified
  91 audit-file with the format:
  92 .PP
  93 .RS 5
  94 .nf
  95 <<inc>> date
  96 <scan line for first message>
  97 <scan line for second message>
  98 <etc.>
  99 .fi
 100 .RE
 101 .PP
 102 This is useful for keeping track of volume and source of incoming mail.
 103 Eventually,
 104 .BR repl ,
 105 .BR forw ,
 106 .BR comp ,
 107 and
 108 .B dist
 109 may also output audit information to this (or another) file, perhaps with
 110 .RI \*(lq Message\-Id \*(rq
 111 information to keep an exact correspondence history.
 112 .RI \*(lq Audit-file \*(rq
 113 is assumed to be in the user's nmh directory unless a full path is specified.
 114 .PP
 115 .B inc
 116 will incorporate even improperly formatted messages into the user's
 117 nmh folder, inserting a blank line prior to the offending component
 118 and printing a comment identifying the bad message.
 119 .PP
 120 In all cases, except the use of
 121 .B \-file
 122 .I name
 123 (see below), the user's mail drop will be zeroed, unless the
 124 .B \-notruncate
 125 switch is given.
 126 .PP
 127 If the profile entry
 128 .RI \*(lq Unseen\-Sequence \*(rq
 129 is present and non-empty, then
 130 .B inc
 131 will add each of the newly incorporated messages to each sequence
 132 named in the profile entry.
 133 .B inc
 134 will not zero each sequence prior to adding messages.
 135 .PP
 136 The interpretation of the
 137 .B \-form
 138 .IR formatfile ,
 139 .B \-format
 140 .IR string ,
 141 and
 142 .B \-width
 143 .I columns
 144 switches is the same as in
 145 .IR scan (1).
 146 .PP
 147 By using the
 148 .B \-file
 149 .I name
 150 switch, one can direct
 151 .B inc
 152 to incorporate messages from a file other than the user's mail drop.
 153 Note that the named file will
 154 .I not
 155 be zeroed, unless the
 156 .B \-truncate
 157 switch is given.
 158 .PP
 159 The
 160 .B \-file
 161 switch does not support the use of standard input.
 162 Instead, the
 163 .B rcvstore
 164 command can be used to incorporate mail from the standard input stream.
 165 .PP
 166 If the environment variable
 167 .B $MAILDROP
 168 is set, then
 169 .B inc
 170 uses it as the location of the user's mail drop instead of the default
 171 (the
 172 .B -file
 173 .I name
 174 switch still overrides this, however).
 175 If this environment variable is not set, then
 176 .B inc
 177 will consult the profile entry
 178 .RI \*(lq MailDrop \*(rq
 179 for this information.  If the value found is not absolute, then it is
 180 interpreted relative to the user's
 181 .B nmh
 182 directory.  If the value is not found, then
 183 .B inc
 184 will look in the standard system location for the user's mail drop.
 185 .PP
 186 The
 187 .B \-silent
 188 switch directs
 189 .B inc
 190 to be quiet and not ask any questions at all.  This is useful for putting
 191 .B inc
 192 in the background and going on to other things.
 193 .SS "Using POP"
 194 .B inc
 195 will normally check local mail drops for mail, as covered above.
 196 But if the option
 197 .RI \*(lq pophost \*(rq
 198 is set in
 199 .RI \*(lq mts.conf \*(rq,
 200 or if the
 201 .B \-host
 202 .I hostname
 203 switch is given, or if the
 204 .B $MAILHOST
 205 environment variable is set, then
 206 .B inc
 207 will query this POP service host for mail to incorporate.  If
 208 .B $MAILHOST
 209 is set and
 210 .B \-host
 211 is specified as well, the command-line switch will override
 212 the environment variable.  The
 213 .B \-port
 214 switch specifies the port name or number used to connect to the POP
 215 server.  If unspecified, the default is \*(lqpop3\*(rq.
 216 .PP
 217 To specify a username for authentication with the POP server, use the
 218 .B \-user
 219 .I username
 220 switch.  The credentials profile entry in
 221 .IR mh\-profile (5)
 222 describes the ways to supply a username and password.
 223 .PP
 224 If passed the
 225 .B \-proxy
 226 .I command
 227 switch,
 228 .B inc
 229 will use the specified command to establish the connection to the POP
 230 server.  The string
 231 .I %h
 232 in the command will be substituted by the hostname to connect to.
 233 .PP
 234 For debugging purposes, you may give the switch
 235 .BR \-snoop ,
 236 which will allow you to monitor the POP transaction.  If
 237 .B \-sasl \-saslmech xoauth2
 238 is used, the HTTP transaction is also shown.
 239 .PP
 240 If
 241 .B nmh
 242 has been compiled with SASL support, the
 243 .B \-sasl
 244 switch will enable the use of SASL authentication.
 245 Depending on the SASL mechanism used, this may require an
 246 additional password prompt from the user (but the
 247 .I netrc
 248 file can be used to store this password, as described in
 249 .IR mh\-profile (5)).
 250 The
 251 .B \-saslmech
 252 switch can be used to select a particular SASL mechanism.
 253 .PP
 254 If SASL authentication is successful,
 255 .B inc
 256 will attempt to negotiate a security layer for session encryption.
 257 Encrypted traffic is labelled with `(encrypted)' and `(decrypted)'
 258 when viewing the POP transaction with the
 259 .B \-snoop
 260 switch; see
 261 .IR post (8)'s
 262 description of
 263 .B \-snoop
 264 for its other features.
 265 .PP
 266 If
 267 .B nmh
 268 has been compiled with OAuth support, the
 269 .B \-sasl
 270 and
 271 .B \-saslmech xoauth2
 272 switches will enable OAuth authentication.  The
 273 .B \-user
 274 switch must be used, and the
 275 .I user-name
 276 must be an email address the user has for the service, which must
 277 be specified with the
 278 .B \-authservice
 279 .I service
 280 switch.  Before using this, the user must authorize nmh by running
 281 .B mhlogin
 282 and granting authorization to that account.  See
 283 .IR mhlogin (1)
 284 for more details.
 285 .PP
 286 If
 287 .B nmh
 288 has been compiled with TLS support, the
 289 .B \-initialtls
 290 switch will require the negotiation of TLS when connecting
 291 to the remote POP server.
 292 .B inc
 293 will negotiate TLS immediately after the connection has taken place,
 294 before any POP commands are sent or received.  Data encrypted by TLS is
 295 labeled `(tls-encrypted)' and `(tls-decrypted)' when viewing the POP
 296 transaction with the
 297 .B \-snoop
 298 switch.  The
 299 .B \-notls
 300 switch will disable all attempts to negotiate TLS.
 301 .PP
 302 When using TLS the default is to verify the remote certificate and SubjectName
 303 against the local trusted certificate store.  This can be controlled by
 304 the
 305 .B \-certverify
 306 and
 307 .B \-nocertverify
 308 switches.  See your OpenSSL documentation for more information on certificate
 309 verification.
 310 .SH FILES
 311 .PD 0
 312 .TP 20
 313 $HOME/.mh_profile
 314 The user's profile.
 315 .TP
 316 %nmhetcdir%/mts.conf
 317 mts configuration file.
 318 .TP
 319 %mailspool%/$USER
 320 Location of the system mail drop.
 321 .PD
 322 .SH "PROFILE COMPONENTS"
 323 .PD 0
 324 .TP 20
 325 Path:
 326 To determine the user's nmh directory.
 327 .TP
 328 Alternate\-Mailboxes:
 329 To determine the user's mailboxes.
 330 .TP
 331 Inbox:
 332 To determine the inbox.
 333 .TP
 334 Folder\-Protect:
 335 To set mode when creating a new folder.
 336 .TP
 337 Msg\-Protect:
 338 To set mode when creating a new message and audit-file.
 339 .TP
 340 Unseen\-Sequence:
 341 To name sequences denoting unseen messages.
 342 .PD
 343 .SH "SEE ALSO"
 344 .IR mhmail (1),
 345 .IR scan (1),
 346 .IR mh\-mail (5),
 347 .IR mh\-profile (5),
 348 .IR mhlogin (1),
 349 .IR post (8),
 350 .IR rcvstore (1)
 351 .SH DEFAULTS
 352 .PD 0
 353 .TP 20
 354 +folder
 355 defaulted by \*(lqInbox\*(rq above.
 356 .TP
 357 \-noaudit
 358 .TP
 359 \-changecur
 360 .TP
 361 \-format
 362 As described above.
 363 .TP
 364 \-nosilent
 365 .TP
 366 \-nosasl
 367 .TP
 368 \-notruncate
 369 Unless
 370 .B \-file
 371 .I name
 372 is given.
 373 .TP
 374 \-width
 375 The width of the terminal.
 376 .PD
 377 .SH CONTEXT
 378 The folder into which messages are being incorporated will become the
 379 current folder.  The first message incorporated will become the current
 380 message, unless the
 381 .B \-nochangecur
 382 option is specified.  This leaves the context ready for a
 383 .B show
 384 of the first new message.