From 094ca96844842928810f14844413109fc6cdd890 Mon Sep 17 00:00:00 2001 From: Eduardo Chappa Date: Sun, 3 Feb 2013 00:59:38 -0700 Subject: Initial Alpine Version --- imap/docs/imaprc.txt | 613 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 613 insertions(+) create mode 100644 imap/docs/imaprc.txt (limited to 'imap/docs/imaprc.txt') diff --git a/imap/docs/imaprc.txt b/imap/docs/imaprc.txt new file mode 100644 index 00000000..cda153a6 --- /dev/null +++ b/imap/docs/imaprc.txt @@ -0,0 +1,613 @@ +/* ======================================================================== + * Copyright 1988-2006 University of Washington + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * + * ======================================================================== + */ + + .imaprc secrets revealed! + Mark Crispin, June 17, 2002 + +The following information describes the format of the /etc/c-client.cf +and ~/.imaprc file. The Columbia MM ~/.mminit file is also read by +c-client; however, the only command that ~/.mminit has in common is +set keywords. + +********************************************************************** +* DANGER! BEWARE! TAKE CARE! * +********************************************************************** +* * +* These files, and this documentation, are for internal UW usage * +* only. This capability is for UW experimental tinkering, and most * +* emphatically *not* for sorcerer's apprentices at other sites who * +* feel that if a config file capability exists, they must write a * +* config file whether or not there is any need for one. * +* * +* This information is subject to change without notice. Commands * +* may be added, removed, or altered. The behavior of comamnds may * +* change. Do not use any of this information without consulting me * +* first. c-client's defaults have been carefully chosen to be right * +* for general-purpose and most special-purpose configurations. If * +* you tinker with these defaults, all hell may break loose. * +* * +* This is not an idle threat. There have been several instances of * +* people who ignored these warnings and have gotten burned. * +* * +* Don't even trust this file to work. Many of the things which can * +* be changed by this file can also be changed by the application, * +* and it is totally unpredictable which will take precedence. It * +* all depends upon how the application is coded. Not only that, you * +* may cause the application to crash. * +* * +* In other words, keep your cotton-pickin' hands off my defaults. * +* If it crashes and erases your mail, I don't want to hear about it. * +* Consider 'em ``mandatory defaults''. Got a nice ring, eh? :-) If * +* you must tinker with defaults, play with the .pinerc and pine.conf * +* files in Pine. It's got options galore, all supported for you to * +* have fun. They're also documented; so well documented, it takes * +* two strong men to carry around all the documentation. ;-) ;-) * +* * +* Joking aside, you really shouldn't be fooling around with this * +* capability. It's dangerous, and you can shoot yourself in the * +* foot easily. If you need custom changes, you are better off with * +* local source code modifications. Seriously. * +* * +* One last warning: don't believe anything that you read in this * +* document. Every effort has been made to ensure that this document * +* is incomplete and inaccurate, and I take no responsibility for any * +* glimmers of correct information that may, by some fluke, be here. * +* * +********************************************************************** + +The files are read in order: /etc/c-client.cf, ~/.mminit, ~/.imaprc, +and an entry in a later file overrides the setting of an earlier file +except as noted below. This ordering and overriding behavior may +change without notice. + +Almost all of these facilities can also be set via the mail_parameters() +call in the program. Whether the file overrides mail_parameters(), or +mail_parameters() overrides the file, is indeterminate. It will vary +from program to program, and it may be one way in one version and the +other way in the next version. It's completely unpredictable, and so +anything you do with these files has to be in complete knowledge of what +the version of each program you're running is going to do. This is +because the files do something for testing, but the real capability for +configurability is put in the program instead. Are you getting the +feeling that you shouldn't be messing with these files yet? + +The very first line of the file MUST start with the exact string "I +accept the risk". This ensures that you have checked the file for +correctness against this version of the IMAP toolkit. This enable +string may change without notice in future versions, and the new +string may or may not be accurately described in an updated version of +this file. So any time you install software that uses the IMAP +toolkit, you need to check the new version against these files (if you +have insisted upon creating them in spite of all warnings). If two +pieces of software use different versions of the IMAP toolkit with +incompatible requirements, one of them won't work. Re-read the +warning above about why you should not use these files. + +Subsequent lines are read from the file one at a time. Case does not +matter. Unrecognized commands are ignored. + +1) set new-folder-format + sets what format new mailboxes are created in. This also controls + default delivery via tmail and dmail. + + a) set new-folder-format same-as-inbox + Folder is created using the same mailbox format as INBOX. If + INBOX is empty, it defaults to system standard. + + b) set new-folder-format system-standard + This is the default. Folder is created using the wired-in system + standard format, which on most UNIX systems is ordinary UNIX + /bin/mail format. On SCO systems, this is MMDF. + + c) set new-folder-format + Folder is created using the given driver name, e.g. mbx, unix, + mmdf, etc. + + There is no protection against setting this to a silly value (e.g. + news, nntp, dummy) and doing so is a great way to screw things up. + Setting this to mh does not do what you think it does. Setting this + to tenex or mtx isn't particularly useful. + +2) set empty-folder-format + sets what format data is written into an empty mailbox file using + mail_copy() or mail_append(). This also controls default delivery + via tmail. + + a) set empty-folder-format same-as-inbox + Data is written using the same mailbox format as INBOX. If + INBOX is empty, it defaults to system standard. + + b) set empty-folder-format system-standard + This is the default. Data is written using the wired-in system + standard format, which on most UNIX systems is ordinary UNIX + /bin/mail format. On SCO systems, this is MMDF. + + c) set-empty-folder-format + Data is written using the given driver name, e.g. tenex, unix, + mmdf, etc. + + There is no protection against setting this to a silly value (e.g. + news, nntp, dummy) and doing so is a great way to screw things up. + Setting this to mh, mbx, or mx does not work. + +3) set keywords , , ... + Sets the list of keyword flags (supported by tenex and mtx) to the + given list. Up to 30 flags may be given. Since these names + correspond to numeric bits, the order of the keywords can not be + changed, nor can keywords be removed or inserted (you can append + new keywords, up to the limit of 30). + + Set keywords is a deprecated command. It may not appear in + future versions, or it may appear in a changed form. It exists + only for compatibility with MM, and should only appear in ~/.mminit + and not in the other files. It is likely to disappear entirely in + IMAP4. + + There is no protection against setting these to silly values, and + doing so is a great way to cause a crash. + +4) set from-widget header-only + Sets smart insertion of the > character in front of lines that + begin with ``From ''. Only such lines that are also in UNIX mbox + header file format will have a > character inserted. The default + is to insert the > character in front of all lines which begin with + ``From '', for the benefit of legacy tools that get confused + otherwise. + +5) set black-box-directory + Sets the directory in which the user's data can be found. A user's + folders can be found in a subdirectory of the black box directory + named with the user's username. For example, if the blackbox + directory is /usr/spool/folders/, user jones' data can be found + in /usr/spool/folders/jones/. The user's black-box directory is + the location of folders, .mminit, .imaprc, .newsrc, and all other + files used by c-client; internally, it sets c-client's idea of the + user's ``home directory'', overriding /etc/passwd. + + This command may not appear in ~/.mminit or ~/.imaprc + + In black-box mode, it is not permitted to access any folders + outside of the user's personal blackbox directory. The breakouts + ``/'', ``~'', and ``..'' are not permitted. + + In order to make this work without crashing, you must set another + option which is not listed in this document. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +6) set local-host + Sets c-client's idea of the local host name. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +7) set news-active-file + Sets the location of the news active file, if it is not in the + standard place. + + It is recommended to use a courtesy symbolic link instead. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +8) set news-spool-directory + Sets the location of the news spool, if it is not in the standard + place. + + It is recommended to use a courtesy symbolic link instead. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +9) set news-state-file + Sets the location of the news state file (normally $(USER)/.newsrc). + + This is not very useful in /etc/c-client.cf because it is a file name. + Setting this in /etc/c-client.cf would set all users to the same file + as their newsrc, which is probably not what you want. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +10) set system-inbox + Sets the location of the "system inbox", if it is not in the standard + place. This is the default location of INBOX, or the mail drop point + from which mail is snarfed (e.g. in tenex, mtx, mbox, mh formats). + + This is not very useful in /etc/c-client.cf because it is a file name. + Setting this in /etc/c-client.cf would set all users to the same file + as their system inbox, which is probably not what you want. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +11) set tcp-open-timeout + Sets the number of seconds that the TCP routines will block on opening + a TCP connection before timing out. If a timeout occurs, the connection + attempt is aborted. + + The default is zero, meaning use the operating system default (75 + seconds on most UNIX systems). + + There is no protection against setting this to an excessively small + value, such as 1, and doing so is a great way to cause users extreme + grief. + +12) set tcp-read-timeout + Sets the number of seconds that the TCP routines will block on reading + data before calling the timeout routine. If no timeout routine is set + by the program, the connection will be aborted on a timeout. + + The default is zero, meaning infinite. + + There is no protection against setting this to an excessively small + value, such as 1, and doing so is a great way to cause users extreme + grief. + +13) set tcp-write-timeout + Sets the number of seconds that the TCP routines will block on sending + data before calling the timeout routine. If no timeout routine is set + by the program, the connection will be aborted on a timeout. + + The default is zero, meaning infinite. + + There is no protection against setting this to an excessively small + value, such as 1, and doing so is a great way to cause users extreme + grief. + +14) set rsh-timeout + Sets the number of seconds that the rsh routines will block on opening + an rimapd connection before timing out. If a timeout occurs, the + rsh connection attempt is aborted. A zero timeout will disable rsh. + + The default is 15 seconds. + + There is no protection against setting this to an excessively small + value, such as 1, and doing so is a great way to cause users extreme + grief. + +15) set maximum-login-trials + Sets the number of iterations of asking the user, via mm_login(), for + a user name and password, before cancelling the attempt. + + The default is 3. + + There is no protection against setting this to zero, and doing so is + a great way to cause users extreme grief. + +16) set lookahead + Sets the number of envelopes that are looked ahead in IMAP, in + mail_fetchstructure(). This is based on the guess that in such + operations as drawing browser lines, if you get data for message n + you are likely to want it for message n+1, n+2,... in short order. + Lookahead preloads the c-client cache and saves unnecessary RTTs. + + The default is 20, a good number for a browser on a 24x80 screen, and + small enough to usually have no significant real-time difference from + a single message fetch. + + Setting it to 0 turns off lookahead. + + There is no protection against setting this ridiculously high and + incurring performance penalties as a result. + +17) set prefetch + Sets the number of envelops which are automatically fetched for the + messages which match in a search. This is based on the guess that + in a browser that is "zoomed" on the results of a search, you are + likely to want the envelope data for each of those messages in + short order. Prefetching reloads the c-client cache, saves + unnecessary RTTs, and avoids loading undesired envelopes due to + lookahead (see above). + + The default is 20. + + Setting it to 0 turns off prefetch. + + There is no protection against setting this ridiculously high and + incurring performance penalties as a result. + +18) set close-on-error + If non-zero, IMAP connections are closed if an EXAMINE or SELECT + command fails. Otherwise, they are left half-open, and can be used + again to select some other mailbox. The mailbox name in the stream + is set to {serverhost} + + The default is zero (do not close on error). + +19) set imap-port + Set the TCP/IP contact port to use for IMAP. This overrides the + wired-in setting and the setting from /etc/services, and can in + turn be overridden by an explicit user specification in the mailbox + name, e.g. {serverhost:143}foo + + The default is zero (use setting from /etc/services or the wired-in + setting (143). + + There is no protection against setting this to a silly value, and + doing so is a great way to cause users extreme grief. + +20) set pop3-port + Set the TCP/IP contact port to use for POP3. This overrides the + wired-in setting and the setting from /etc/services, and can in + turn be overridden by an explicit user specification in the mailbox + name, e.g. {serverhost:110/pop3} + + The default is zero (use setting from /etc/services or the wired-in + setting (110). + + There is no protection against setting this to a silly value, and + doing so is a great way to cause users extreme grief. + +21) set uid-lookahead + Sets the number of UIDs that are looked ahead in IMAP in mail_uid(). + Lookahead preloads the c-client cache and saves unnecessary RTTs. + + The default is 1000, small enough to usually have no significant + real-time difference from a single message UID fetch. + + Setting it to 0 turns off lookahead. + + There is no protection against setting this ridiculously high and + incurring performance penalties as a result. + +22) set mailbox-protection + Set the default protection for newly-created mailbox files. + + The default is 384. + + There is no protection against setting this to a silly value, and + doing so is a great way to screw things up massively. + +23) set directory-protection + Set the default protection for newly-created directories. + + The default is 448. + + There is no protection against setting this to a silly value, and + doing so is a great way to screw things up massively. + +24) set lock-protection + Set the default protection for lock files + + The default is 438, which is necessary if locks are to be respected + by processes running as other UIDs. + + There is no protection against setting this to a silly value, and + contrary to what you may think just about any value other than 438 + turns out to be a silly value. + +25) set disable-fcntl-locking + This only applies to SVR4 systems. + + If non-zero, fnctl() locking is not attempted. In the past, this + was used to avoid locking NFS files. If NFS is involved, the evil + lockd/statd daemons get invoked. These daemons supposedly work over + NFS, but really don't. + + You probably don't really want to do this, though, because now the + flock() emulator (which calls fcntl()) now checks to see if the file + is accessed via NFS and no-ops the lock. This is compatible with + BSD. + + Disabling fcntl() locking loses a great deal of locking protection + on local files as well as NFS files (which now never have locking + protection). + + The default is zero (fcntl() locking is enabled). + +26) set lock-EACCES-error + If non-zero, a warning message is given if an attempt to create a + lock file fails. Otherwise, EACCES is treated as a "silent failure", + and it proceeds without trying to use the lock file. This is for + the benefit of users on systems with paranoid /usr/spool/mail + protections which don't let users create /usr/spool/mail/$(USER).lock + files; these unfortunate users would be harassed with a flood of + error messages otherwise. The problem is that on SVR4, if EACCES + remains disabled and fcntl() locking is also disabled, then there is + no locking at all which is doubleplus-ungood. + + If the site is paranoid on /usr/spool/mail protections AND if there + is no fcntl() locking (SVR4) or usable flock() locking (e.g. NFS), + then there is no way to win. Find a different system to use. + + The default is non-zero (report EACCESS as an error). + +27) set list-maximum-level + Sets the maximum depth of recursion that a * wildcard list will go + down the directory tree. 0 means that no recursion is permitted, + and * becomes like %. + + The default is 20. + + There is no protection against setting this to a ridiculously high + value. Since LIST will follow symbolic links, it can effectively + recurse infinitely, until the name strings get large enough that + some name limit is exceeded. + +28) set anonymous-home-directory + Sets the location of the anonymous home directory, if it is not in + the standard place. + + It is recommended to use a courtesy symbolic link instead. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +29) set chroot-server + This option is for closed server systems only. If defined, a chroot() + call to the user's home directory is done as part of the login + process. This has the effect of preventing access to any files + outside of the user's home directory (including shared mailboxes). + + Shared mailboxes with other users can't possibly work with this + option, because there is no way to export lock information to other + users. + + This should be done ONLY on systems which do not permit users to + have shell access + + This option should NEVER(!!) be set if users are allowed shell access. + Doing so actually makes the system *less* secure, since the user could + create an etc subdirectory which would be treated as real /etc by such + programs as /bin/su. + + The default is zero (don't do chroot). + + This option is strongly *NOT* recommended. + +30) set disable-automatic-shared-namespaces + Never look up the "ftp", "imappublic", and "imapshared" users as + posssible home directories for the #ftp, #public, and #shared + namespaces. On some systems (reportedly including AIX 4.3.3) + getpwnam() of an unknown user name is horrendously slow. + + Note that this does not remove the #ftp, #public, and #shared + namespaces, and they can still be set up by other means. + + The default is zero (shared namespaces are automatic). + +31) set advertise-the-world + Include the UNIX root as a shared namespace. This is generally a bad + idea, since certain IMAP clients (names withheld to protect the guilty) + will take this as license to download the entire filesystem tree. + + The default is zero (don't advertise the world). + +32) set mail-subdirectory + Change the default connected directory from the user's home directory + to the named subdirectory of the user's home directory. For example, + setting MAILSUBDIR="mail" will cause the POP2 and IMAP servers to + connect to the user's ~/mail subdirectory. This is equivalent to + the env_unix.c edit described in Example 2 of the CONFIG file. + + Note that if the subdirectory does not exist, the result is undefined. + It is probably an extremely bad idea to set this unless you can + guarantee that the subdirectory exists for all users. If you can not + guarantee this, then you should leave the default as the user's home + directory and allow them to configure a personal default in their IMAP + client. + + The default is not to use any subdirectory. + +33) set allow-user-config + Allow users to use ~/.imaprc and ~/.mminit files. + + The default is zero (don't allow user config files). + +34) set allow-reverse-dns + By default, the servers (ipop[23]d and imapd) will do gethostbyaddr() + on the local and remote sockets so that imapd can identify itself + properly (this is important when the same CPU hosts multiple virtual + hosts on different IP addresss) and also includes the client's name + when it writes to the syslog. There are also client gethostbyaddr() + calls, used primarily by authentication mechanisms. + + Setting this option to zero disables all gethostbyaddr() calls. The + returned "host name" string for the socket is just the bracketed + [12.34.56.78] form, as if the reverse DNS lookup failed. + + WARNING: Some authentication mechanisms, e.g. Kerberos V, depend upon + the host names being right, and if you set this option, it won't work. + + You should only do this if you are encountering server performance + problems due to a misconfigured DNS, e.g. long startup delays or + client timeouts. + + The default is non-zero (allow reverse DNS). + +35) set disable-plaintext + Disable plaintext password authentication (LOGIN command, AUTH=LOGIN, + and AUTH=PLAIN). + + The default is zero (allow plaintext authentication). + +36) set trust-dns + By default, host names are canonicalized via gethostbyname() for + everything except for SSL certificate validation. + + This can represent a security bug due to DNS spoofing, but is more + likely to deliver results that users expect. It also may be necessary + for SASL authentication to work right (e.g. generating a correct name + for a Kerberos service principal) if the name entered by the user is a + CNAME or not a fully-qualified domain name. + + If trust-dns is set to zero, no host name canonicalization is done. + The user's actual entered name is used for SASL authentication and + will appear in the mailbox name of the open stream. + + The default is non-zero (do DNS canonicalization). + +37) set sasl-uses-ptr-name + By default, if trust-dns is set, the host names used in authentication + (e.g. to generate a Kerberos service principal) are canonicalized via + gethostbyaddr() instead of by gethostbyname(). If gethostbyaddr() + fails the gethostbyname() canonicalization is used. + + This represents an additional security bug due to DNS spoofing, over and + above trust-dns. It also adds an additional DNS query to starting a + session. + + It is necessary for sites which implement a server cluster with multiple + A records for a cluster name (instead of a CNAME) but each cluster + member has a unique PTR record which it expects for a Kerberos service + principal. + + If sasl-uses-ptr-name is set to zero and trust-dns is set non-zero, the + gethostbyname() canonicalized name is used for SASL authentication. + + The setting of sasl-uses-ptr-name is irrelevant if trust-dns is set to + zero. + + The default is non-zero (use name from PTR record for SASL). + +38) set network-filesystem-stat-bug + By default, traditional UNIX mailbox files are only closed and reopened + at checkpoint and expunge time. This ensures that, prior to rewriting + the file, that any cached stat() data from a network filesystem is + updated with current data. + + Very old versions of NFS, and reputedly also AFS, can get into a state + in which the cached stat() data stays out-of-date, even across a + close and reopen of the file. + + If network-filesystem-stat-bug is set non-zero, then the mailbox file + is closed and reopened at ping time as a workaround for this bug in + these network filesystems. This means that in imapd, the mailbox + file is closed and reopened for every IMAP command. This is obviously + something that should be avoided unless absolutely necessary. + + NFS and AFS are terrible ways to distribute mail. You use use IMAP + servers with a local disk instead. + + The default is zero (only close/reopen at checkpoint and expunge time). + + Setting this option is a great way to ruin your system's performance. + +39) set restrict-mailbox-access