]> diplodocus.org Git - nmh/blob - man/inc.man
Reorder configure options to be before variables
[nmh] / 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 [ \-proxy
35 .IR command ]
36 .RB [ \-sasl " | " \-nosasl ]
37 .RB [ \-saslmech
38 .IR mechanism ]
39 .RB [ \-authservice
40 .IR service ]
41 .RB [ \-tls ]
42 .RB [ \-initialtls ]
43 .RB [ \-notls ]
44 .RB [ \-certverify " | " \-nocertverify ]
45 .RB [ \-snoop ]
46 .ad
47 .SH DESCRIPTION
48 .B inc
49 incorporates mail from the user's incoming mail drop into 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 is considered to be in
58 .B Maildir
59 format.
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.
74 As the messages are processed, a
75 .B scan
76 listing of the new mail is produced.
77 .PP
78 The newly created messages will have a mode of 0600, see chmod(1),
79 on filesystems that support it.
80 Alternatively, a
81 .RI \*(lq "Msg\-Protect: nnn" \*(rq
82 profile entry gives the mode to use, in octal.
83 For all subsequent operations on these messages, this initially assigned
84 mode will be preserved.
85 .PP
86 If the switch
87 .B \-audit
88 .I audit-file
89 is specified (usually as a default switch in the user's profile), then
90 .B inc
91 will append a header line and a line per message to the specified
92 audit-file with the format:
93 .PP
94 .RS 5
95 .nf
96 <<inc>> date
97 <scan line for first message>
98 <scan line for second message>
99 <etc.>
100 .fi
101 .RE
102 .PP
103 This is useful for keeping track of volume and source of incoming mail.
104 Eventually,
105 .BR repl ,
106 .BR forw ,
107 .BR comp ,
108 and
109 .B dist
110 may also output audit information to this (or another) file, perhaps with
111 .RI \*(lq Message\-Id \*(rq
112 information to keep an exact correspondence history.
113 .RI \*(lq Audit-file \*(rq
114 is assumed to be in the user's nmh directory unless a full path is specified.
115 .PP
116 .B inc
117 will incorporate even improperly formatted messages into the user's
118 nmh folder, inserting a blank line prior to the offending component
119 and printing a comment identifying the bad message.
120 .PP
121 In all cases, except the use of
122 .B \-file
123 .I name
124 (see below), 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 each sequence
133 named in 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 .IR scan (1).
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 mail drop.
154 Note that the named file will
155 .I not
156 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 For debugging purposes, you may give the switch
236 .BR \-snoop ,
237 which will allow you to monitor the POP transaction. If
238 .B \-sasl \-saslmech xoauth2
239 is used, the HTTP transaction is also shown.
240 .PP
241 If
242 .B nmh
243 has been compiled with SASL support, the
244 .B \-sasl
245 switch will enable the use of SASL authentication.
246 Depending on the SASL mechanism used, this may require an
247 additional password prompt from the user (but the
248 .I netrc
249 file can be used to store this password, as described in
250 .IR mh\-profile (5)).
251 The
252 .B \-saslmech
253 switch can be used to select a particular SASL mechanism.
254 .PP
255 If SASL authentication is successful,
256 .B inc
257 will attempt to negotiate a security layer for session encryption.
258 Encrypted traffic is labelled with `(encrypted)' and `(decrypted)'
259 when viewing the POP transaction with the
260 .B \-snoop
261 switch; see
262 .IR post (8)'s
263 description of
264 .B \-snoop
265 for its other features.
266 .PP
267 If
268 .B nmh
269 has been compiled with OAuth support, the
270 .B \-sasl
271 and
272 .B \-saslmech xoauth2
273 switches will enable OAuth authentication. The
274 .B \-user
275 switch must be used, and the
276 .I user-name
277 must be an email address the user has for the service, which must
278 be specified with the
279 .B \-authservice
280 .I service
281 switch. Before using this, the user must authorize nmh by running
282 .B mhlogin
283 and granting authorization to that account. See
284 .IR mhlogin (1)
285 for more details.
286 .PP
287 If
288 .B nmh
289 has been compiled with TLS support, the
290 .B \-tls
291 and
292 .B \-initialtls
293 switches will require the negotiation of TLS when connecting
294 to the remote POP server. The
295 .B \-tls
296 switch will direct
297 .B inc
298 to negotiate TLS as part of the normal POP protocol using
299 the STLS command. The
300 .B \-initialtls
301 switch will direct
302 .B inc
303 to 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 .PD
387 .SH CONTEXT
388 The folder into which messages are being incorporated will become the
389 current folder. The first message incorporated will become the current
390 message, unless the
391 .B \-nochangecur
392 option is specified. This leaves the context ready for a
393 .B show
394 of the first new message.