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
 157 .I not
 158 be zeroed, unless the
 159 .B \-truncate
 160 switch is given.
 161 .PP
 162 The
 163 .B \-file
 164 switch does not support the use of standard input.
 165 Instead, the
 166 .B rcvstore
 167 command can be used to incorporate mail from the standard input stream.
 168 .PP
 169 If the environment variable
 170 .B $MAILDROP
 171 is set, then
 172 .B inc
 173 uses it as the location of the user's mail drop instead of the default
 174 (the
 175 .B -file
 176 .I name
 177 switch still overrides this, however).
 178 If this environment variable is not set, then
 179 .B inc
 180 will consult the profile entry
 181 .RI \*(lq MailDrop \*(rq
 182 for this information.  If the value found is not absolute, then it is
 183 interpreted relative to the user's
 184 .B nmh
 185 directory.  If the value is not found, then
 186 .B inc
 187 will look in the standard system location for the user's mail drop.
 188 .PP
 189 The
 190 .B \-silent
 191 switch directs
 192 .B inc
 193 to be quiet and not ask any questions at all.  This is useful for putting
 194 .B inc
 195 in the background and going on to other things.
 196 .SS "Using POP"
 197 .B inc
 198 will normally check local mail drops for mail, as covered above.
 199 But 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
 224 .IR mh\-profile (5)
 225 describes the ways to supply a username and password.
 226 .PP
 227 If passed the
 228 .B \-proxy
 229 .I command
 230 switch,
 231 .B inc
 232 will use the specified command to establish the connection to the POP
 233 server.  The string
 234 .I %h
 235 in the command will be substituted by the hostname to connect to.
 236 .PP
 237 When using POP, if the
 238 .B \-pack
 239 .I file
 240 switch is given then
 241 .B inc
 242 will
 243 .IR packf (1)
 244 the user's mail drop from the POP service host to the named file.
 245 .PP
 246 For debugging purposes, you may give the switch
 247 .BR \-snoop ,
 248 which will allow you to monitor the POP transaction.  If
 249 .B \-sasl \-saslmech xoauth2
 250 is used, the HTTP transaction is also shown.
 251 .PP
 252 If
 253 .B nmh
 254 has been compiled with SASL support, the
 255 .B \-sasl
 256 switch will enable the use of SASL authentication.
 257 Depending on the SASL mechanism used, this may require an
 258 additional password prompt from the user (but the
 259 .I netrc
 260 file can be used to store this password, as described in
 261 .IR mh\-profile (5)).
 262 The
 263 .B \-saslmech
 264 switch can be used to select a particular SASL mechanism.
 265 .PP
 266 If SASL authentication is successful,
 267 .B inc
 268 will attempt to negotiate a security layer for session encryption.
 269 Encrypted traffic is labelled with `(encrypted)' and `(decrypted)'
 270 when viewing the POP transaction with the
 271 .B \-snoop
 272 switch; see the
 273 .B post
 274 man page description of
 275 .B \-snoop
 276 for its other features.
 277 .PP
 278 If
 279 .B nmh
 280 has been compiled with OAuth support, the
 281 .B \-sasl
 282 and
 283 .B \-saslmech xoauth2
 284 switches will enable OAuth authentication.  The
 285 .B \-user
 286 switch must be used, and the
 287 .I user-name
 288 must be an email address the user has for the service, which must
 289 be specified with the
 290 .B \-authservice
 291 .I service
 292 switch.  Before using this, the user must authorize nmh by running
 293 .B mhlogin
 294 and granting authorization to that account.  See
 295 .IR mhlogin (1)
 296 for more details.
 297 .PP
 298 If
 299 .B nmh
 300 has been compiled with TLS support, the
 301 .B \-initialtls
 302 switch will require the negotiation of TLS when connecting
 303 to the remote POP server.
 304 .B inc
 305 will negotiate TLS immediately after the connection has taken place,
 306 before any POP commands are sent or received.  Data encrypted by TLS is
 307 labeled `(tls-encrypted)' and `(tls-decrypted)` when viewing the POP
 308 transaction with the
 309 .B \-snoop
 310 switch.  The
 311 .B \-notls
 312 switch will disable all attempts to negotiate TLS.
 313 .PP
 314 When using TLS the default is to verify the remote certificate and SubjectName
 315 against the local trusted certificate store.  This can be controlled by
 316 the
 317 .B \-certverify
 318 and
 319 .B \-nocertverify
 320 switches.  See your OpenSSL documentation for more information on certificate
 321 verification.
 322 .SH FILES
 323 .PD 0
 324 .TP 20
 325 $HOME/.mh_profile
 326 The user's profile.
 327 .TP
 328 %nmhetcdir%/mts.conf
 329 mts configuration file.
 330 .TP
 331 %mailspool%/$USER
 332 Location of the system mail drop.
 333 .PD
 334 .SH "PROFILE COMPONENTS"
 335 .PD 0
 336 .TP 20
 337 Path:
 338 To determine the user's nmh directory.
 339 .TP
 340 Alternate\-Mailboxes:
 341 To determine the user's mailboxes.
 342 .TP
 343 Inbox:
 344 To determine the inbox.
 345 .TP
 346 Folder\-Protect:
 347 To set mode when creating a new folder.
 348 .TP
 349 Msg\-Protect:
 350 To set mode when creating a new message and audit-file.
 351 .TP
 352 Unseen\-Sequence:
 353 To name sequences denoting unseen messages.
 354 .PD
 355 .SH "SEE ALSO"
 356 .IR mhmail (1),
 357 .IR scan (1),
 358 .IR mh\-mail (5),
 359 .IR mh\-profile (5),
 360 .IR mhlogin (1),
 361 .IR post (8),
 362 .IR rcvstore (1)
 363 .SH DEFAULTS
 364 .PD 0
 365 .TP 20
 366 +folder
 367 defaulted by \*(lqInbox\*(rq above.
 368 .TP
 369 \-noaudit
 370 .TP
 371 \-changecur
 372 .TP
 373 \-format
 374 As described above.
 375 .TP
 376 \-nosilent
 377 .TP
 378 \-nosasl
 379 .TP
 380 \-notruncate
 381 Unless
 382 .B \-file
 383 .I name
 384 is given.
 385 .TP
 386 \-width
 387 The width of the terminal.
 388 .TP
 389 \-nopack
 390 .PD
 391 .SH CONTEXT
 392 The folder into which messages are being incorporated will become the
 393 current folder.  The first message incorporated will become the current
 394 message, unless the
 395 .B \-nochangecur
 396 option is specified.  This leaves the context ready for a
 397 .B show
 398 of the first new message.