--- /dev/null
+/* ========================================================================
+ * 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 <driver name>
+ 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 <driver name>
+ 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 <word1>, <word2>, ... <wordn>
+ 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 <directory name>
+ 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 <host name>
+ 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 <file name>
+ 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 <directory name>
+ 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 <file name>
+ 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 <file name>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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}<no_mailbox>
+
+ The default is zero (do not close on error).
+
+19) set imap-port <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <directory name>
+ 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 <number>
+ 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 <number>
+ 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 <number>
+ 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 <subdirectory name>
+ 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 <number>
+ Allow users to use ~/.imaprc and ~/.mminit files.
+
+ The default is zero (don't allow user config files).
+
+34) set allow-reverse-dns <number>
+ 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 <number>
+ Disable plaintext password authentication (LOGIN command, AUTH=LOGIN,
+ and AUTH=PLAIN).
+
+ The default is zero (allow plaintext authentication).
+
+36) set trust-dns <number>
+ 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 <number>
+ 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 <number>
+ 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 <option> <option> ... <option>
+ This option is for closed server systems only. It is less extreme
+ than chroot-server, and allows selective restriction of what mailbox
+ named users can use. The existing options are:
+ root access not permitted to names starting with "/"
+ otherusers access not permitted to other users' names; this should
+ normally be used in conjunction with "root", otherwise
+ another user's names can be accessed via a root name.
+ all all of the above
+ Setting any combination of options also disables access to superior
+ directories via "..".
+
+ This should be done ONLY on systems which do not permit users to
+ have shell access
+
+ The default is no restrictions.
projects / uw-imap / commitdiff