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

   1 .TH INC %manext1% "March 23, 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 .RI [ +folder ]
  12 .RB [ \-audit
  13 .IR audit\-file ]
  14 .RB [ \-noaudit ]
  15 .RB [ \-changecur " | " \-nochangecur ]
  16 .RB [ \-form
  17 .IR formfile ]
  18 .RB [ \-format
  19 .IR string ]
  20 .RB [ \-file
  21 .IR name ]
  22 .RB [ \-silent " | " \-nosilent ]
  23 .RB [ \-truncate " | " \-notruncate ]
  24 .RB [ \-width
  25 .IR columns ]
  26 .RB [ \-host
  27 .IR hostname ]
  28 .RB [ \-port
  29 .IR portname/number ]
  30 .RB [ \-user
  31 .IR username ]
  32 .RB [ \-pack
  33 .IR file ]
  34 .RB [ \-nopack ]
  35 .RB [ \-proxy
  36 .IR command ]
  37 .RB [ \-sasl " | " \-nosasl ]
  38 .RB [ \-saslmech
  39 .IR mechanism ]
  40 .RB [ \-authservice
  41 .IR service ]
  42 .RB [ \-snoop ]
  43 .RB [ \-version ]
  44 .RB [ \-help ]
  45 .ad
  46 .SH DESCRIPTION
  47 .B Inc
  48 incorporates mail from the user's incoming mail drop into
  49 an
  50 .B nmh
  51 folder.
  52 If the mail drop is a file, it can be in
  53 .B mbox
  54 or
  55 .B MMDF
  56 format.
  57 If the mail drop is a directory it will considered to be a
  58 .B Maildir
  59 format mail drop.
  60 .PP
  61 You may specify which folder to use with
  62 .IR +folder .
  63 If no folder is specified, then
  64 .B inc
  65 will use either the folder given by a (non\-empty)
  66 .RI \*(lq Inbox \*(rq
  67 entry in the user's profile, or the folder named
  68 .RI \*(lq inbox \*(rq.
  69 If the specified (or default) folder doesn't
  70 exist, the user will be queried prior to its creation.
  71 .PP
  72 When the new messages are incorporated into the folder, they are assigned
  73 numbers starting with the next highest number for the folder.  As the
  74 messages are processed, a
  75 .B scan
  76 listing of the new mail is produced.
  77 .PP
  78 If the user's profile contains a
  79 .RI \*(lq "Msg\-Protect: nnn" \*(rq
  80 entry, it will be used as the protection on the newly created
  81 messages, otherwise the
  82 .B nmh
  83 default of 0600 will be used (on filesystems that support it).  For
  84 all subsequent operations on these messages, this initially assigned
  85 protection will be preserved.
  86 .PP
  87 If the switch
  88 .B \-audit
  89 .I audit\-file
  90 is specified (usually as a default
  91 switch in the profile), then
  92 .B inc
  93 will append a header line and a
  94 line per message to the end of the specified 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 produce audits to this (or another) file, perhaps with
 113 .RI \*(lq Message\-Id \*(rq
 114 information to keep an exact correspondence
 115 history.
 116 .RI \*(lq Audit\-file \*(rq
 117 will be in the user's nmh directory unless a full path is specified.
 118 .PP
 119 .B Inc
 120 will incorporate even improperly formatted messages into the
 121 user's nmh folder, inserting a blank line prior to the offending component
 122 and printing a comment identifying the bad message.
 123 .PP
 124 In all cases, the user's mail drop will be zeroed, unless the
 125 .B \-notruncate
 126 switch is given.
 127 .PP
 128 If the profile entry
 129 .RI \*(lq Unseen\-Sequence \*(rq
 130 is present and non\-empty, then
 131 .B inc
 132 will add each of the newly incorporated messages to
 133 each sequence named by the profile entry.
 134 .B Inc
 135 will not zero each sequence prior to adding messages.
 136 .PP
 137 The interpretation of the
 138 .B \-form
 139 .IR formatfile ,
 140 .B \-format
 141 .IR string ,
 142 and
 143 .B \-width
 144 .I columns
 145 switches is the same as in
 146 .BR scan .
 147 .PP
 148 By using the
 149 .B \-file
 150 .I name
 151 switch, one can direct
 152 .B inc
 153 to incorporate messages from a file other than the user's maildrop.
 154 Note that the name file will NOT be zeroed, unless the
 155 .B \-truncate
 156 switch is given.
 157 .PP
 158 The
 159 .B \-file
 160 switch does not support use of standard input.  Instead,
 161 the
 162 .B rcvstore
 163 command can be used to incorporate mail from the standard input stream.
 164 .PP
 165 If the environment variable
 166 .B $MAILDROP
 167 is set, then
 168 .B inc
 169 uses it as the location of the user's maildrop instead of the default
 170 (the
 171 .B -file
 172 .I name
 173 switch still overrides this, however).  If this
 174 environment variable is not set, then
 175 .B inc
 176 will consult the profile entry
 177 .RI \*(lq MailDrop \*(rq
 178 for this information.  If the value found is
 179 not absolute, then it is interpreted relative to the user's
 180 .B nmh
 181 directory.  If the value is not found, then
 182 .B inc
 183 will look in the standard system location for the user's maildrop.
 184 .PP
 185 The
 186 .B \-silent
 187 switch directs
 188 .B inc
 189 to be quiet and not ask any questions at all.  This is useful for putting
 190 .B inc
 191 in the background and going on to other things.
 192 .PP
 193 .SS "Using POP"
 194 .B inc
 195 will normally check local mail drops for mail, as covered above.  But
 196 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 commandline 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 the mh\-profile(5) man page
 221 describes the ways to supply a username and password.
 222 .PP
 223 If passed the
 224 .B \-proxy
 225 .I command
 226 switch,
 227 .B inc
 228 will use the specified command to establish the connection to the POP
 229 server. The string
 230 .IR %h
 231 in the command will be substituted by the hostname to connect to.
 232 .PP
 233 If
 234 .B inc
 235 uses POP, then the
 236 .B \-pack
 237 .I file
 238 switch is considered. If given, then
 239 .B inc
 240 simply uses the POP to
 241 .B packf
 242 the user's maildrop 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 watch the POP transaction take place
 247 between you and the POP server.  If
 248 .B \-saslmech xoauth2
 249 is used, the HTTP transaction is also shown.
 250 .PP
 251 If
 252 .B nmh
 253 has been compiled with SASL support, the
 254 .B \-sasl
 255 switch will enable
 256 the use of SASL authentication.  Depending on the SASL mechanism used, this
 257 may require an additional password prompt from the user (but the
 258 .I netrc
 259 file can be used to store this password, as described in the
 260 mh-profile(5) man page).  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.
 271 .PP
 272 If
 273 .B nmh
 274 has been compiled with OAuth support, the
 275 .B \-saslmech xoauth2
 276 switch will enable OAuth authentication.  The
 277 .B \-user
 278 switch must be used, and the
 279 .I user-name
 280 must be an email address the user has for the service, which must
 281 be specified with the
 282 .B \-authservice
 283 .I service
 284 switch.  Before using this, the user must authorize nmh by running
 285 .B mhlogin
 286 and grant authorization to that account.  See the
 287 .B mhlogin
 288 man page for more details.
 289 .PP
 290 Gmail only supports POP3 over TLS, but
 291 .B inc
 292 has no TLS support.  To work around this, use something like
 293 .B -proxy 'openssl s_client -connect %h:995 -CAfile /etc/ssl/certs/ca-certificates.crt -quiet'
 294 .SH FILES
 295 .PD 0
 296 .TP 20
 297 $HOME/.mh_profile
 298 The user's profile.
 299 .TP
 300 %nmhetcdir%/mts.conf
 301 mts configuration file.
 302 .TP
 303 %mailspool%/$USER
 304 Location of the system mail drop.
 305 .PD
 306 .SH "PROFILE COMPONENTS"
 307 .PD 0
 308 .TP 20
 309 Path:
 310 To determine the user's nmh directory.
 311 .TP
 312 Alternate\-Mailboxes:
 313 To determine the user's mailboxes.
 314 .TP
 315 Inbox:
 316 To determine the inbox.
 317 .TP
 318 Folder\-Protect:
 319 To set mode when creating a new folder.
 320 .TP
 321 Msg\-Protect:
 322 To set mode when creating a new message and audit\-file.
 323 .TP
 324 Unseen\-Sequence:
 325 To name sequences denoting unseen messages.
 326 .PD
 327 .SH "SEE ALSO"
 328 .IR mhmail (1),
 329 .IR scan (1),
 330 .IR mh\-mail (5),
 331 .IR mh\-profile (5),
 332 .IR mhlogin (1),
 333 .IR post (8),
 334 .IR rcvstore (1)
 335 .SH DEFAULTS
 336 .PD 0
 337 .TP 20
 338 +folder
 339 defaulted by \*(lqInbox\*(rq above.
 340 .TP
 341 \-noaudit
 342 .TP
 343 \-changecur
 344 .TP
 345 \-format
 346 As described above.
 347 .TP
 348 \-nosilent
 349 .TP
 350 \-nosasl
 351 .TP
 352 \-truncate
 353 If
 354 .B \-file
 355 .I name
 356 not given,
 357 \-notruncate otherwise.
 358 .TP
 359 \-width
 360 The width of the terminal.
 361 .TP
 362 \-nopack
 363 .PD
 364 .SH CONTEXT
 365 The folder into which messages are being incorporated will become the
 366 current folder.  The first message incorporated will become the current
 367 message, unless the
 368 .B \-nochangecur
 369 option is specified.  This leaves the context ready for a
 370 .B show
 371 of the first new message.