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

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