path: root/imap/docs/imaprc.txt

/* ========================================================================
 * 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.