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