| blob | 82c7daa24ade1dc8ff07721ec999c0332577031e |
1 /* ========================================================================
2 * Copyright 1988-2006 University of Washington
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 *
11 * ========================================================================
12 */
14 .imaprc secrets revealed!
15 Mark Crispin, June 17, 2002
17 The following information describes the format of the /etc/c-client.cf
18 and ~/.imaprc file. The Columbia MM ~/.mminit file is also read by
19 c-client; however, the only command that ~/.mminit has in common is
20 set keywords.
22 **********************************************************************
23 * DANGER! BEWARE! TAKE CARE! *
24 **********************************************************************
25 * *
26 * These files, and this documentation, are for internal UW usage *
27 * only. This capability is for UW experimental tinkering, and most *
28 * emphatically *not* for sorcerer's apprentices at other sites who *
29 * feel that if a config file capability exists, they must write a *
30 * config file whether or not there is any need for one. *
31 * *
32 * This information is subject to change without notice. Commands *
33 * may be added, removed, or altered. The behavior of commands may *
34 * change. Do not use any of this information without consulting me *
35 * first. c-client's defaults have been carefully chosen to be right *
36 * for general-purpose and most special-purpose configurations. If *
37 * you tinker with these defaults, all hell may break loose. *
38 * *
39 * This is not an idle threat. There have been several instances of *
40 * people who ignored these warnings and have gotten burned. *
41 * *
42 * Don't even trust this file to work. Many of the things which can *
43 * be changed by this file can also be changed by the application, *
44 * and it is totally unpredictable which will take precedence. It *
45 * all depends upon how the application is coded. Not only that, you *
46 * may cause the application to crash. *
47 * *
48 * In other words, keep your cotton-pickin' hands off my defaults. *
49 * If it crashes and erases your mail, I don't want to hear about it. *
50 * Consider 'em ``mandatory defaults''. Got a nice ring, eh? :-) If *
51 * you must tinker with defaults, play with the .pinerc and pine.conf *
52 * files in Pine. It's got options galore, all supported for you to *
53 * have fun. They're also documented; so well documented, it takes *
54 * two strong men to carry around all the documentation. ;-) ;-) *
55 * *
56 * Joking aside, you really shouldn't be fooling around with this *
57 * capability. It's dangerous, and you can shoot yourself in the *
58 * foot easily. If you need custom changes, you are better off with *
59 * local source code modifications. Seriously. *
60 * *
61 * One last warning: don't believe anything that you read in this *
62 * document. Every effort has been made to ensure that this document *
63 * is incomplete and inaccurate, and I take no responsibility for any *
64 * glimmers of correct information that may, by some fluke, be here. *
65 * *
66 **********************************************************************
68 The files are read in order: /etc/c-client.cf, ~/.mminit, ~/.imaprc,
69 and an entry in a later file overrides the setting of an earlier file
70 except as noted below. This ordering and overriding behavior may
71 change without notice.
73 Almost all of these facilities can also be set via the mail_parameters()
74 call in the program. Whether the file overrides mail_parameters(), or
75 mail_parameters() overrides the file, is indeterminate. It will vary
76 from program to program, and it may be one way in one version and the
77 other way in the next version. It's completely unpredictable, and so
78 anything you do with these files has to be in complete knowledge of what
79 the version of each program you're running is going to do. This is
80 because the files do something for testing, but the real capability for
81 configurability is put in the program instead. Are you getting the
82 feeling that you shouldn't be messing with these files yet?
84 The very first line of the file MUST start with the exact string "I
85 accept the risk". This ensures that you have checked the file for
86 correctness against this version of the IMAP toolkit. This enable
87 string may change without notice in future versions, and the new
88 string may or may not be accurately described in an updated version of
89 this file. So any time you install software that uses the IMAP
90 toolkit, you need to check the new version against these files (if you
91 have insisted upon creating them in spite of all warnings). If two
92 pieces of software use different versions of the IMAP toolkit with
93 incompatible requirements, one of them won't work. Re-read the
94 warning above about why you should not use these files.
96 Subsequent lines are read from the file one at a time. Case does not
97 matter. Unrecognized commands are ignored.
99 1) set new-folder-format
100 sets what format new mailboxes are created in. This also controls
101 default delivery via tmail and dmail.
103 a) set new-folder-format same-as-inbox
104 Folder is created using the same mailbox format as INBOX. If
105 INBOX is empty, it defaults to system standard.
107 b) set new-folder-format system-standard
108 This is the default. Folder is created using the wired-in system
109 standard format, which on most UNIX systems is ordinary UNIX
110 /bin/mail format. On SCO systems, this is MMDF.
112 c) set new-folder-format <driver name>
113 Folder is created using the given driver name, e.g. mbx, unix,
114 mmdf, etc.
116 There is no protection against setting this to a silly value (e.g.
117 news, nntp, dummy) and doing so is a great way to screw things up.
118 Setting this to mh does not do what you think it does. Setting this
119 to tenex or mtx isn't particularly useful.
121 2) set empty-folder-format
122 sets what format data is written into an empty mailbox file using
123 mail_copy() or mail_append(). This also controls default delivery
124 via tmail.
126 a) set empty-folder-format same-as-inbox
127 Data is written using the same mailbox format as INBOX. If
128 INBOX is empty, it defaults to system standard.
130 b) set empty-folder-format system-standard
131 This is the default. Data is written using the wired-in system
132 standard format, which on most UNIX systems is ordinary UNIX
133 /bin/mail format. On SCO systems, this is MMDF.
135 c) set-empty-folder-format <driver name>
136 Data is written using the given driver name, e.g. tenex, unix,
137 mmdf, etc.
139 There is no protection against setting this to a silly value (e.g.
140 news, nntp, dummy) and doing so is a great way to screw things up.
141 Setting this to mh, mbx, or mx does not work.
143 3) set keywords <word1>, <word2>, ... <wordn>
144 Sets the list of keyword flags (supported by tenex and mtx) to the
145 given list. Up to 30 flags may be given. Since these names
146 correspond to numeric bits, the order of the keywords can not be
147 changed, nor can keywords be removed or inserted (you can append
148 new keywords, up to the limit of 30).
150 Set keywords is a deprecated command. It may not appear in
151 future versions, or it may appear in a changed form. It exists
152 only for compatibility with MM, and should only appear in ~/.mminit
153 and not in the other files. It is likely to disappear entirely in
154 IMAP4.
156 There is no protection against setting these to silly values, and
157 doing so is a great way to cause a crash.
159 4) set from-widget header-only
160 Sets smart insertion of the > character in front of lines that
161 begin with ``From ''. Only such lines that are also in UNIX mbox
162 header file format will have a > character inserted. The default
163 is to insert the > character in front of all lines which begin with
164 ``From '', for the benefit of legacy tools that get confused
165 otherwise.
167 5) set black-box-directory <directory name>
168 Sets the directory in which the user's data can be found. A user's
169 folders can be found in a subdirectory of the black box directory
170 named with the user's username. For example, if the blackbox
171 directory is /usr/spool/folders/, user jones' data can be found
172 in /usr/spool/folders/jones/. The user's black-box directory is
173 the location of folders, .mminit, .imaprc, .newsrc, and all other
174 files used by c-client; internally, it sets c-client's idea of the
175 user's ``home directory'', overriding /etc/passwd.
177 This command may not appear in ~/.mminit or ~/.imaprc
179 In black-box mode, it is not permitted to access any folders
180 outside of the user's personal blackbox directory. The breakouts
181 ``/'', ``~'', and ``..'' are not permitted.
183 In order to make this work without crashing, you must set another
184 option which is not listed in this document.
186 There is no protection against setting this to a silly value, and
187 doing so is a great way to cause a crash.
189 6) set local-host <host name>
190 Sets c-client's idea of the local host name.
192 There is no protection against setting this to a silly value, and
193 doing so is a great way to cause a crash.
195 7) set news-active-file <file name>
196 Sets the location of the news active file, if it is not in the
197 standard place.
199 It is recommended to use a courtesy symbolic link instead.
201 There is no protection against setting this to a silly value, and
202 doing so is a great way to cause a crash.
204 8) set news-spool-directory <directory name>
205 Sets the location of the news spool, if it is not in the standard
206 place.
208 It is recommended to use a courtesy symbolic link instead.
210 There is no protection against setting this to a silly value, and
211 doing so is a great way to cause a crash.
213 9) set news-state-file <file name>
214 Sets the location of the news state file (normally $(USER)/.newsrc).
216 This is not very useful in /etc/c-client.cf because it is a file name.
217 Setting this in /etc/c-client.cf would set all users to the same file
218 as their newsrc, which is probably not what you want.
220 There is no protection against setting this to a silly value, and
221 doing so is a great way to cause a crash.
223 10) set system-inbox <file name>
224 Sets the location of the "system inbox", if it is not in the standard
225 place. This is the default location of INBOX, or the mail drop point
226 from which mail is snarfed (e.g. in tenex, mtx, mbox, mh formats).
228 This is not very useful in /etc/c-client.cf because it is a file name.
229 Setting this in /etc/c-client.cf would set all users to the same file
230 as their system inbox, which is probably not what you want.
232 There is no protection against setting this to a silly value, and
233 doing so is a great way to cause a crash.
235 11) set tcp-open-timeout <number>
236 Sets the number of seconds that the TCP routines will block on opening
237 a TCP connection before timing out. If a timeout occurs, the connection
238 attempt is aborted.
240 The default is zero, meaning use the operating system default (75
241 seconds on most UNIX systems).
243 There is no protection against setting this to an excessively small
244 value, such as 1, and doing so is a great way to cause users extreme
245 grief.
247 12) set tcp-read-timeout <number>
248 Sets the number of seconds that the TCP routines will block on reading
249 data before calling the timeout routine. If no timeout routine is set
250 by the program, the connection will be aborted on a timeout.
252 The default is zero, meaning infinite.
254 There is no protection against setting this to an excessively small
255 value, such as 1, and doing so is a great way to cause users extreme
256 grief.
258 13) set tcp-write-timeout <number>
259 Sets the number of seconds that the TCP routines will block on sending
260 data before calling the timeout routine. If no timeout routine is set
261 by the program, the connection will be aborted on a timeout.
263 The default is zero, meaning infinite.
265 There is no protection against setting this to an excessively small
266 value, such as 1, and doing so is a great way to cause users extreme
267 grief.
269 14) set rsh-timeout <number>
270 Sets the number of seconds that the rsh routines will block on opening
271 an rimapd connection before timing out. If a timeout occurs, the
272 rsh connection attempt is aborted. A zero timeout will disable rsh.
274 The default is 15 seconds.
276 There is no protection against setting this to an excessively small
277 value, such as 1, and doing so is a great way to cause users extreme
278 grief.
280 15) set maximum-login-trials <number>
281 Sets the number of iterations of asking the user, via mm_login(), for
282 a user name and password, before cancelling the attempt.
284 The default is 3.
286 There is no protection against setting this to zero, and doing so is
287 a great way to cause users extreme grief.
289 16) set lookahead <number>
290 Sets the number of envelopes that are looked ahead in IMAP, in
291 mail_fetchstructure(). This is based on the guess that in such
292 operations as drawing browser lines, if you get data for message n
293 you are likely to want it for message n+1, n+2,... in short order.
294 Lookahead preloads the c-client cache and saves unnecessary RTTs.
296 The default is 20, a good number for a browser on a 24x80 screen, and
297 small enough to usually have no significant real-time difference from
298 a single message fetch.
300 Setting it to 0 turns off lookahead.
302 There is no protection against setting this ridiculously high and
303 incurring performance penalties as a result.
305 17) set prefetch <number>
306 Sets the number of envelops which are automatically fetched for the
307 messages which match in a search. This is based on the guess that
308 in a browser that is "zoomed" on the results of a search, you are
309 likely to want the envelope data for each of those messages in
310 short order. Prefetching reloads the c-client cache, saves
311 unnecessary RTTs, and avoids loading undesired envelopes due to
312 lookahead (see above).
314 The default is 20.
316 Setting it to 0 turns off prefetch.
318 There is no protection against setting this ridiculously high and
319 incurring performance penalties as a result.
321 18) set close-on-error <number>
322 If non-zero, IMAP connections are closed if an EXAMINE or SELECT
323 command fails. Otherwise, they are left half-open, and can be used
324 again to select some other mailbox. The mailbox name in the stream
325 is set to {serverhost}<no_mailbox>
327 The default is zero (do not close on error).
329 19) set imap-port <number>
330 Set the TCP/IP contact port to use for IMAP. This overrides the
331 wired-in setting and the setting from /etc/services, and can in
332 turn be overridden by an explicit user specification in the mailbox
333 name, e.g. {serverhost:143}foo
335 The default is zero (use setting from /etc/services or the wired-in
336 setting (143).
338 There is no protection against setting this to a silly value, and
339 doing so is a great way to cause users extreme grief.
341 20) set pop3-port <number>
342 Set the TCP/IP contact port to use for POP3. This overrides the
343 wired-in setting and the setting from /etc/services, and can in
344 turn be overridden by an explicit user specification in the mailbox
345 name, e.g. {serverhost:110/pop3}
347 The default is zero (use setting from /etc/services or the wired-in
348 setting (110).
350 There is no protection against setting this to a silly value, and
351 doing so is a great way to cause users extreme grief.
353 21) set uid-lookahead <number>
354 Sets the number of UIDs that are looked ahead in IMAP in mail_uid().
355 Lookahead preloads the c-client cache and saves unnecessary RTTs.
357 The default is 1000, small enough to usually have no significant
358 real-time difference from a single message UID fetch.
360 Setting it to 0 turns off lookahead.
362 There is no protection against setting this ridiculously high and
363 incurring performance penalties as a result.
365 22) set mailbox-protection <number>
366 Set the default protection for newly-created mailbox files.
368 The default is 384.
370 There is no protection against setting this to a silly value, and
371 doing so is a great way to screw things up massively.
373 23) set directory-protection <number>
374 Set the default protection for newly-created directories.
376 The default is 448.
378 There is no protection against setting this to a silly value, and
379 doing so is a great way to screw things up massively.
381 24) set lock-protection <number>
382 Set the default protection for lock files
384 The default is 438, which is necessary if locks are to be respected
385 by processes running as other UIDs.
387 There is no protection against setting this to a silly value, and
388 contrary to what you may think just about any value other than 438
389 turns out to be a silly value.
391 25) set disable-fcntl-locking <number>
392 This only applies to SVR4 systems.
394 If non-zero, fnctl() locking is not attempted. In the past, this
395 was used to avoid locking NFS files. If NFS is involved, the evil
396 lockd/statd daemons get invoked. These daemons supposedly work over
397 NFS, but really don't.
399 You probably don't really want to do this, though, because now the
400 flock() emulator (which calls fcntl()) now checks to see if the file
401 is accessed via NFS and no-ops the lock. This is compatible with
402 BSD.
404 Disabling fcntl() locking loses a great deal of locking protection
405 on local files as well as NFS files (which now never have locking
406 protection).
408 The default is zero (fcntl() locking is enabled).
410 26) set lock-EACCES-error <number>
411 If non-zero, a warning message is given if an attempt to create a
412 lock file fails. Otherwise, EACCES is treated as a "silent failure",
413 and it proceeds without trying to use the lock file. This is for
414 the benefit of users on systems with paranoid /usr/spool/mail
415 protections which don't let users create /usr/spool/mail/$(USER).lock
416 files; these unfortunate users would be harassed with a flood of
417 error messages otherwise. The problem is that on SVR4, if EACCES
418 remains disabled and fcntl() locking is also disabled, then there is
419 no locking at all which is doubleplus-ungood.
421 If the site is paranoid on /usr/spool/mail protections AND if there
422 is no fcntl() locking (SVR4) or usable flock() locking (e.g. NFS),
423 then there is no way to win. Find a different system to use.
425 The default is non-zero (report EACCESS as an error).
427 27) set list-maximum-level <number>
428 Sets the maximum depth of recursion that a * wildcard list will go
429 down the directory tree. 0 means that no recursion is permitted,
430 and * becomes like %.
432 The default is 20.
434 There is no protection against setting this to a ridiculously high
435 value. Since LIST will follow symbolic links, it can effectively
436 recurse infinitely, until the name strings get large enough that
437 some name limit is exceeded.
439 28) set anonymous-home-directory <directory name>
440 Sets the location of the anonymous home directory, if it is not in
441 the standard place.
443 It is recommended to use a courtesy symbolic link instead.
445 There is no protection against setting this to a silly value, and
446 doing so is a great way to cause a crash.
448 29) set chroot-server <number>
449 This option is for closed server systems only. If defined, a chroot()
450 call to the user's home directory is done as part of the login
451 process. This has the effect of preventing access to any files
452 outside of the user's home directory (including shared mailboxes).
454 Shared mailboxes with other users can't possibly work with this
455 option, because there is no way to export lock information to other
456 users.
458 This should be done ONLY on systems which do not permit users to
459 have shell access
461 This option should NEVER(!!) be set if users are allowed shell access.
462 Doing so actually makes the system *less* secure, since the user could
463 create an etc subdirectory which would be treated as real /etc by such
464 programs as /bin/su.
466 The default is zero (don't do chroot).
468 This option is strongly *NOT* recommended.
470 30) set disable-automatic-shared-namespaces <number>
471 Never look up the "ftp", "imappublic", and "imapshared" users as
472 possible home directories for the #ftp, #public, and #shared
473 namespaces. On some systems (reportedly including AIX 4.3.3)
474 getpwnam() of an unknown user name is horrendously slow.
476 Note that this does not remove the #ftp, #public, and #shared
477 namespaces, and they can still be set up by other means.
479 The default is zero (shared namespaces are automatic).
481 31) set advertise-the-world <number>
482 Include the UNIX root as a shared namespace. This is generally a bad
483 idea, since certain IMAP clients (names withheld to protect the guilty)
484 will take this as license to download the entire filesystem tree.
486 The default is zero (don't advertise the world).
488 32) set mail-subdirectory <subdirectory name>
489 Change the default connected directory from the user's home directory
490 to the named subdirectory of the user's home directory. For example,
491 setting MAILSUBDIR="mail" will cause the POP2 and IMAP servers to
492 connect to the user's ~/mail subdirectory. This is equivalent to
493 the env_unix.c edit described in Example 2 of the CONFIG file.
495 Note that if the subdirectory does not exist, the result is undefined.
496 It is probably an extremely bad idea to set this unless you can
497 guarantee that the subdirectory exists for all users. If you can not
498 guarantee this, then you should leave the default as the user's home
499 directory and allow them to configure a personal default in their IMAP
500 client.
502 The default is not to use any subdirectory.
504 33) set allow-user-config <number>
505 Allow users to use ~/.imaprc and ~/.mminit files.
507 The default is zero (don't allow user config files).
509 34) set allow-reverse-dns <number>
510 By default, the servers (ipop[23]d and imapd) will do gethostbyaddr()
511 on the local and remote sockets so that imapd can identify itself
512 properly (this is important when the same CPU hosts multiple virtual
513 hosts on different IP address) and also includes the client's name
514 when it writes to the syslog. There are also client gethostbyaddr()
515 calls, used primarily by authentication mechanisms.
517 Setting this option to zero disables all gethostbyaddr() calls. The
518 returned "host name" string for the socket is just the bracketed
519 [12.34.56.78] form, as if the reverse DNS lookup failed.
521 WARNING: Some authentication mechanisms, e.g. Kerberos V, depend upon
522 the host names being right, and if you set this option, it won't work.
524 You should only do this if you are encountering server performance
525 problems due to a misconfigured DNS, e.g. long startup delays or
526 client timeouts.
528 The default is non-zero (allow reverse DNS).
530 35) set disable-plaintext <number>
531 Disable plaintext password authentication (LOGIN command, AUTH=LOGIN,
532 and AUTH=PLAIN).
534 The default is zero (allow plaintext authentication).
536 36) set trust-dns <number>
537 By default, host names are canonicalized via gethostbyname() for
538 everything except for SSL certificate validation.
540 This can represent a security bug due to DNS spoofing, but is more
541 likely to deliver results that users expect. It also may be necessary
542 for SASL authentication to work right (e.g. generating a correct name
543 for a Kerberos service principal) if the name entered by the user is a
544 CNAME or not a fully-qualified domain name.
546 If trust-dns is set to zero, no host name canonicalization is done.
547 The user's actual entered name is used for SASL authentication and
548 will appear in the mailbox name of the open stream.
550 The default is non-zero (do DNS canonicalization).
552 37) set sasl-uses-ptr-name <number>
553 By default, if trust-dns is set, the host names used in authentication
554 (e.g. to generate a Kerberos service principal) are canonicalized via
555 gethostbyaddr() instead of by gethostbyname(). If gethostbyaddr()
556 fails the gethostbyname() canonicalization is used.
558 This represents an additional security bug due to DNS spoofing, over and
559 above trust-dns. It also adds an additional DNS query to starting a
560 session.
562 It is necessary for sites which implement a server cluster with multiple
563 A records for a cluster name (instead of a CNAME) but each cluster
564 member has a unique PTR record which it expects for a Kerberos service
565 principal.
567 If sasl-uses-ptr-name is set to zero and trust-dns is set non-zero, the
568 gethostbyname() canonicalized name is used for SASL authentication.
570 The setting of sasl-uses-ptr-name is irrelevant if trust-dns is set to
571 zero.
573 The default is non-zero (use name from PTR record for SASL).
575 38) set network-filesystem-stat-bug <number>
576 By default, traditional UNIX mailbox files are only closed and reopened
577 at checkpoint and expunge time. This ensures that, prior to rewriting
578 the file, that any cached stat() data from a network filesystem is
579 updated with current data.
581 Very old versions of NFS, and reputedly also AFS, can get into a state
582 in which the cached stat() data stays out-of-date, even across a
583 close and reopen of the file.
585 If network-filesystem-stat-bug is set non-zero, then the mailbox file
586 is closed and reopened at ping time as a workaround for this bug in
587 these network filesystems. This means that in imapd, the mailbox
588 file is closed and reopened for every IMAP command. This is obviously
589 something that should be avoided unless absolutely necessary.
591 NFS and AFS are terrible ways to distribute mail. You use use IMAP
592 servers with a local disk instead.
594 The default is zero (only close/reopen at checkpoint and expunge time).
596 Setting this option is a great way to ruin your system's performance.
598 39) set restrict-mailbox-access <option> <option> ... <option>
599 This option is for closed server systems only. It is less extreme
600 than chroot-server, and allows selective restriction of what mailbox
601 named users can use. The existing options are:
602 root access not permitted to names starting with "/"
603 otherusers access not permitted to other users' names; this should
604 normally be used in conjunction with "root", otherwise
605 another user's names can be accessed via a root name.
606 all all of the above
607 Setting any combination of options also disables access to superior
608 directories via "..".
610 This should be done ONLY on systems which do not permit users to
611 have shell access
613 The default is no restrictions.