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 [ \-snoop ]
  47 .ad
  48 .SH DESCRIPTION
  49 .B inc
  50 incorporates mail from the user's incoming mail drop into
  51 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 will considered to be a
  60 .B Maildir
  61 format mail drop.
  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.  As the
  76 messages are processed, a
  77 .B scan
  78 listing of the new mail is produced.
  79 .PP
  80 If the user's profile contains a
  81 .RI \*(lq "Msg\-Protect: nnn" \*(rq
  82 entry, it will be used as the protection on the newly created
  83 messages, otherwise the
  84 .B nmh
  85 default of 0600 will be used (on filesystems that support it).  For
  86 all subsequent operations on these messages, this initially assigned
  87 protection will be preserved.
  88 .PP
  89 If the switch
  90 .B \-audit
  91 .I audit\-file
  92 is specified (usually as a default
  93 switch in the profile), then
  94 .B inc
  95 will append a header line and a
  96 line per message to the end of the specified audit\-file with the format:
  97 .PP
  98 .RS 5
  99 .nf
 100 <<inc>> date
 101 <scan line for first message>
 102 <scan line for second message>
 103 <etc.>
 104 .fi
 105 .RE
 106 .PP
 107 This is useful for keeping track of volume and source of incoming mail.
 108 Eventually,
 109 .BR repl ,
 110 .BR forw ,
 111 .BR comp ,
 112 and
 113 .B dist
 114 may also produce audits to this (or another) file, perhaps with
 115 .RI \*(lq Message\-Id \*(rq
 116 information to keep an exact correspondence
 117 history.
 118 .RI \*(lq Audit\-file \*(rq
 119 will be in the user's nmh directory unless a full path is specified.
 120 .PP
 121 .B inc
 122 will incorporate even improperly formatted messages into the
 123 user's nmh folder, inserting a blank line prior to the offending component
 124 and printing a comment identifying the bad message.
 125 .PP
 126 In all cases, 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
 135 each sequence named by 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 .BR scan .
 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 maildrop.
 156 Note that the name 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 use of standard input.  Instead,
 163 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 maildrop instead of the default
 172 (the
 173 .B -file
 174 .I name
 175 switch still overrides this, however).  If this
 176 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
 181 not absolute, then it is 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 maildrop.
 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 .PP
 195 .SS "Using POP"
 196 .B inc
 197 will normally check local mail drops for mail, as covered above.  But
 198 if the option
 199 .RI \*(lq pophost \*(rq
 200 is set in
 201 .RI \*(lq mts.conf \*(rq,
 202 or if the
 203 .B \-host
 204 .I hostname
 205 switch is given, or if the
 206 .B $MAILHOST
 207 environment variable is set, then
 208 .B inc
 209 will query this POP service host for mail to incorporate.  If
 210 .B $MAILHOST
 211 is set and
 212 .B \-host
 213 is specified as well, the commandline switch will override
 214 the environment variable.  The
 215 .B \-port
 216 switch specifies the port name or number used to connect to the POP
 217 server.  If unspecified the default is \*(lqpop3\*(rq.
 218 .PP
 219 To specify a username for authentication with the POP server, use the
 220 .B \-user
 221 .I username
 222 switch.  The credentials profile entry in the mh\-profile(5) man page
 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 .IR %h
 233 in the command will be substituted by the hostname to connect to.
 234 .PP
 235 If
 236 .B inc
 237 uses POP, then the
 238 .B \-pack
 239 .I file
 240 switch is considered.  If given, then
 241 .B inc
 242 simply uses the POP to
 243 .B packf
 244 the user's maildrop 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 watch the POP transaction take place
 249 between you and the POP server.  If
 250 .B \-sasl \-saslmech xoauth2
 251 is used, the HTTP transaction is also shown.
 252 .PP
 253 If
 254 .B nmh
 255 has been compiled with SASL support, the
 256 .B \-sasl
 257 switch will enable
 258 the use of SASL authentication.  Depending on the SASL mechanism used, this
 259 may require an additional password prompt from the user (but the
 260 .I netrc
 261 file can be used to store this password, as described in the
 262 mh-profile(5) man page).  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 grant authorization to that account.  See the
 295 .B mhlogin
 296 man page 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.  The
 304 .B \-initialtls
 305 switch 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)` with 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 .SH FILES
 314 .PD 0
 315 .TP 20
 316 $HOME/.mh_profile
 317 The user's profile.
 318 .TP
 319 %nmhetcdir%/mts.conf
 320 mts configuration file.
 321 .TP
 322 %mailspool%/$USER
 323 Location of the system mail drop.
 324 .PD
 325 .SH "PROFILE COMPONENTS"
 326 .PD 0
 327 .TP 20
 328 Path:
 329 To determine the user's nmh directory.
 330 .TP
 331 Alternate\-Mailboxes:
 332 To determine the user's mailboxes.
 333 .TP
 334 Inbox:
 335 To determine the inbox.
 336 .TP
 337 Folder\-Protect:
 338 To set mode when creating a new folder.
 339 .TP
 340 Msg\-Protect:
 341 To set mode when creating a new message and audit\-file.
 342 .TP
 343 Unseen\-Sequence:
 344 To name sequences denoting unseen messages.
 345 .PD
 346 .SH "SEE ALSO"
 347 .IR mhmail (1),
 348 .IR scan (1),
 349 .IR mh\-mail (5),
 350 .IR mh\-profile (5),
 351 .IR mhlogin (1),
 352 .IR post (8),
 353 .IR rcvstore (1)
 354 .SH DEFAULTS
 355 .PD 0
 356 .TP 20
 357 +folder
 358 defaulted by \*(lqInbox\*(rq above.
 359 .TP
 360 \-noaudit
 361 .TP
 362 \-changecur
 363 .TP
 364 \-format
 365 As described above.
 366 .TP
 367 \-nosilent
 368 .TP
 369 \-nosasl
 370 .TP
 371 \-truncate
 372 If
 373 .B \-file
 374 .I name
 375 not given,
 376 \-notruncate otherwise.
 377 .TP
 378 \-width
 379 The width of the terminal.
 380 .TP
 381 \-nopack
 382 .PD
 383 .SH CONTEXT
 384 The folder into which messages are being incorporated will become the
 385 current folder.  The first message incorporated will become the current
 386 message, unless the
 387 .B \-nochangecur
 388 option is specified.  This leaves the context ready for a
 389 .B show
 390 of the first new message.