home *** CD-ROM | disk | FTP | other *** search
/ ftp.uv.es / 2014.11.ftp.uv.es.tar / ftp.uv.es / pub / unix / pine4.10.tar.gz / pine4.10.tar / pine4.10 / imap / docs / imaprc.txt < prev    next >
Text File  |  1997-12-31  |  19KB  |  439 lines
  1.                .imaprc secrets revealed!
  2.             Mark Crispin, December 31, 1997
  3.  
  4. The following information describes the format of the /etc/c-client.cf
  5. and ~/.imaprc file.  The Columbia MM ~/.mminit file is also read by
  6. c-client; however, the only command that ~/.mminit has in common is
  7. set keywords.
  8.  
  9. **********************************************************************
  10. *             DANGER!  BEWARE!  TAKE CARE!             *
  11. **********************************************************************
  12. *                                     *
  13. *  These files, and this documentation, are for internal UW usage    *
  14. * only.  This capability is for UW experimental tinkering, and most  *
  15. * emphatically *not* for sorcerer's apprentices at other sites who   *
  16. * feel that if a config file capability exists, they must write a    *
  17. * config file whether or not there is any need for one.             *
  18. *                                     *
  19. *  This information is subject to change without notice.  Commands   *
  20. * may be added, removed, or altered.  The behavior of comamnds may   *
  21. * change.  Do not use any of this information without consulting me  *
  22. * first.  c-client's defaults have been carefully chosen to be right *
  23. * for general-purpose and most special-purpose configurations.  If   *
  24. * you tinker with these defaults, all hell may break loose.         *
  25. *                                     *
  26. *  This is not an idle threat.  There have been several instances of *
  27. * people who ignored these warnings and have gotten burned.         *
  28. *                                     *
  29. *  Don't even trust this file to work.  Many of the things which can *
  30. * be changed by this file can also be changed by the application,    *
  31. * and it is totally unpredictable which will take precedence.  It    *
  32. * all depends upon how the application is coded.  Not only that, you *
  33. * may cause the application to crash.                                *
  34. *                                     *
  35. *  In other words, keep your cotton-pickin' hands off my defaults.   *
  36. * If it crashes and erases your mail, I don't want to hear about it. *
  37. * Consider 'em ``mandatory defaults''.  Got a nice ring, eh?  :-) If *
  38. * you must tinker with defaults, play with the .pinerc and pine.conf *
  39. * files in Pine.  It's got options galore, all supported for you to  *
  40. * have fun.  They're also documented; so well documented, it takes   *
  41. * two strong men to carry around all the documentation.     ;-) ;-)     *
  42. *                                     *
  43. *  Joking aside, you really shouldn't be fooling around with this    *
  44. * capability.  It's dangerous, and you can shoot yourself in the     *
  45. * foot easily.  If you need custom changes, you are better off with  *
  46. * local source code modifications.  Seriously.                 *
  47. *                                     *
  48. *  One last warning: don't believe anything that you read in this    *
  49. * document.  Every effort has been made to ensure that this document *
  50. * is incomplete and inaccurate, and I take no responsibility for any *
  51. * glimmers of correct information that may, by some fluke, be here.  *
  52. *                                     *
  53. **********************************************************************
  54.  
  55. The files are read in order: /etc/c-client.cf, ~/.mminit, ~/.imaprc,
  56. and an entry in a later file overrides the setting of an earlier file
  57. except as noted below.  This ordering and overriding behavior may
  58. change without notice.
  59.  
  60. Almost all of these facilities can also be set via the mail_parameters()
  61. call in the program.  Whether the file overrides mail_parameters(), or
  62. mail_parameters() overrides the file, is indeterminate.  It will vary
  63. from program to program, and it may be one way in one version and the
  64. other way in the next version.  It's completely unpredictable, and so
  65. anything you do with these files has to be in complete knowledge of what
  66. the version of each program you're running is going to do.  This is
  67. because the files do something for testing, but the real capability for
  68. configurability is put in the program instead.  Are you getting the
  69. feeling that you shouldn't be messing with these files yet?
  70.  
  71. The very first line of the file MUST be the exact string "I accept the
  72. risk for IMAP toolkit 4.1."  This ensures that you have checked the
  73. file for correctness against this version of the IMAP toolkit.  This
  74. enable string will change without notice in future versions, and the
  75. new string may or may not be accurately described in an updated
  76. version of this file.  So any time you install software that uses the
  77. IMAP toolkit, you need to check the new version against these files
  78. (if you have insisted upon creating them in spite of all warnings).
  79. If two pieces of software use different versions of the IMAP toolkit
  80. with incompatible requirements, one of them won't work.  Re-read the
  81. warning above about why you should not use these files.
  82.  
  83. Subsequent lines are read from the file one at a time.  Case does not
  84. matter.  Unrecognized commands are ignored.
  85.  
  86. 1) set new-folder-format
  87.    sets what format new mailboxes are created in.  This also controls
  88.    default delivery via tmail and dmail.
  89.  
  90.    a) set new-folder-format same-as-inbox
  91.       Folder is created using the same mailbox format as INBOX.  If
  92.       INBOX is empty, it defaults to system standard.
  93.  
  94.    b) set new-folder-format system-standard
  95.       This is the default.  Folder is created using the wired-in system
  96.       standard format, which on most UNIX systems is ordinary UNIX
  97.       /bin/mail format.  On SCO systems, this is MMDF.
  98.  
  99.    c) set new-folder-format <driver name>
  100.       Folder is created using the given driver name, e.g. mbx, unix,
  101.       mmdf, etc.
  102.  
  103.    There is no protection against setting this to a silly value (e.g.
  104.    news, nntp, dummy) and doing so is a great way to screw things up.
  105.    Setting this to mh does not do what you think it does.  Setting this
  106.    to tenex or mtx isn't particularly useful.
  107.  
  108. 2) set empty-folder-format
  109.    sets what format data is written into an empty mailbox file using
  110.    mail_copy() or mail_append().  This also controls default delivery
  111.    via tmail.
  112.  
  113.    a) set empty-folder-format same-as-inbox
  114.       Data is written using the same mailbox format as INBOX.  If
  115.       INBOX is empty, it defaults to system standard.
  116.  
  117.    b) set empty-folder-format system-standard
  118.       This is the default.  Data is written using the wired-in system
  119.       standard format, which on most UNIX systems is ordinary UNIX
  120.       /bin/mail format.  On SCO systems, this is MMDF.
  121.  
  122.    c) set-empty-folder-format <driver name>
  123.       Data is written using the given driver name, e.g. tenex, unix,
  124.       mmdf, etc.
  125.  
  126.    There is no protection against setting this to a silly value (e.g.
  127.    news, nntp, dummy) and doing so is a great way to screw things up.
  128.    Setting this to mh, mbx, or mx does not work.
  129.  
  130. 3) set keywords <word1>, <word2>, ... <wordn>
  131.    Sets the list of keyword flags (supported by tenex and mtx) to the
  132.    given list.  Up to 30 flags may be given.  Since these names
  133.    correspond to numeric bits, the order of the keywords can not be
  134.    changed, nor can keywords be removed or inserted (you can append
  135.    new keywords, up to the limit of 30).
  136.  
  137.    Set keywords is a deprecated command.  It may not appear in
  138.    future versions, or it may appear in a changed form.  It exists
  139.    only for compatibility with MM, and should only appear in ~/.mminit
  140.    and not in the other files.  It is likely to disappear entirely in
  141.    IMAP4.
  142.  
  143.    There is no protection against setting these to silly values, and
  144.    doing so is a great way to cause a crash.
  145.  
  146. 4) set from-widget header-only
  147.    Sets smart insertion of the > character in front of lines that
  148.    begin with ``From ''.  Only such lines that are also in UNIX mbox
  149.    header file format will have a > character inserted.  The default
  150.    is to insert the > character in front of all lines which begin with
  151.    ``From '', for the benefit of legacy tools that get confused
  152.    otherwise.
  153.  
  154. 5) set black-box-directory <directory name>
  155.    Sets the directory in which the user's data can be found.  A user's
  156.    folders can be found in a subdirectory of the black box directory
  157.    named with the user's username.  For example, if the blackbox
  158.    directory is /usr/spool/folders/, user jones' data can be found
  159.    in /usr/spool/folders/jones/.  The user's black-box directory is
  160.    the location of folders, .mminit, .imaprc, .newsrc, and all other
  161.    files used by c-client; internally, it sets c-client's idea of the
  162.    user's ``home directory'', overriding /etc/passwd.
  163.  
  164.    This command may not appear in ~/.mminit or ~/.imaprc
  165.  
  166.    In black-box mode, it is not permitted to access any folders
  167.    outside of the user's personal blackbox directory.  The breakouts
  168.    ``/'', ``~'', and ``..'' are not permitted.
  169.  
  170.    There is no protection against setting this to a silly value, and
  171.    doing so is a great way to cause a crash.
  172.  
  173. 6) set local-host <host name>
  174.    Sets c-client's idea of the local host name.
  175.  
  176.    There is no protection against setting this to a silly value, and
  177.    doing so is a great way to cause a crash.
  178.  
  179. 7) set news-active-file <file name>
  180.    Sets the location of the news active file, if it is not in the
  181.    standard place.
  182.  
  183.    It is recommended to use a courtesy symbolic link instead.
  184.  
  185.    There is no protection against setting this to a silly value, and
  186.    doing so is a great way to cause a crash.
  187.  
  188. 8) set news-spool-directory <directory name>
  189.    Sets the location of the news spool, if it is not in the standard
  190.    place.
  191.  
  192.    It is recommended to use a courtesy symbolic link instead.
  193.  
  194.    There is no protection against setting this to a silly value, and
  195.    doing so is a great way to cause a crash.
  196.  
  197. 9) set news-state-file <file name>
  198.    Sets the location of the news state file (normally $(USER)/.newsrc).
  199.  
  200.    This is not very useful in /etc/c-client.cf because it is a file name.
  201.    Setting this in /etc/c-client.cf would set all users to the same file
  202.    as their newsrc, which is probably not what you want.
  203.  
  204.    There is no protection against setting this to a silly value, and
  205.    doing so is a great way to cause a crash.
  206.  
  207. 10) set system-inbox <file name>
  208.    Sets the location of the "system inbox", if it is not in the standard
  209.    place.  This is the default location of INBOX, or the mail drop point
  210.    from which mail is snarfed (e.g. in tenex, mtx, mbox, mh formats).
  211.  
  212.    This is not very useful in /etc/c-client.cf because it is a file name.
  213.    Setting this in /etc/c-client.cf would set all users to the same file
  214.    as their system inbox, which is probably not what you want.
  215.  
  216.    There is no protection against setting this to a silly value, and
  217.    doing so is a great way to cause a crash.
  218.  
  219. 11) set tcp-open-timeout <number>
  220.     Sets the number of seconds that the TCP routines will block on opening
  221.     a TCP connection before timing out.  If a timeout occurs, the connection
  222.     attempt is aborted.
  223.  
  224.     The default is zero, meaning use the operating system default (75
  225.     seconds on most UNIX systems).
  226.  
  227.     There is no protection against setting this to an excessively small
  228.     value, such as 1, and doing so is a great way to cause users extreme
  229.     grief.
  230.  
  231. 12) set tcp-read-timeout <number>
  232.     Sets the number of seconds that the TCP routines will block on reading
  233.     data before calling the timeout routine.  If no timeout routine is set
  234.     by the program, the connection will be aborted on a timeout.
  235.  
  236.     The default is zero, meaning infinite.
  237.  
  238.     There is no protection against setting this to an excessively small
  239.     value, such as 1, and doing so is a great way to cause users extreme
  240.     grief.
  241.  
  242. 13) set tcp-write-timeout <number>
  243.     Sets the number of seconds that the TCP routines will block on sending
  244.     data before calling the timeout routine.  If no timeout routine is set
  245.     by the program, the connection will be aborted on a timeout.
  246.  
  247.     The default is zero, meaning infinite.
  248.  
  249.     There is no protection against setting this to an excessively small
  250.     value, such as 1, and doing so is a great way to cause users extreme
  251.     grief.
  252.  
  253. 14) set rsh-timeout <number>
  254.     Sets the number of seconds that the rsh routines will block on opening
  255.     an rimapd connection before timing out.  If a timeout occurs, the
  256.     rsh connection attempt is aborted.  A zero timeout will disable rsh.
  257.  
  258.     The default is 15 seconds.
  259.  
  260.     There is no protection against setting this to an excessively small
  261.     value, such as 1, and doing so is a great way to cause users extreme
  262.     grief.
  263.  
  264. 15) set maximum-login-trials <number>
  265.     Sets the number of iterations of asking the user, via mm_login(), for
  266.     a user name and password, before cancelling the attempt.
  267.  
  268.     The default is 3.
  269.  
  270.     There is no protection against setting this to zero, and doing so is
  271.     a great way to cause users extreme grief.
  272.  
  273. 16) set lookahead <number>
  274.     Sets the number of envelopes that are looked ahead in IMAP, in
  275.     mail_fetchstructure().  This is based on the guess that in such
  276.     operations as drawing browser lines, if you get data for message n
  277.     you are likely to want it for message n+1, n+2,... in short order.
  278.     Lookahead preloads the c-client  cache and saves unnecessary RTTs.
  279.  
  280.     The default is 20, a good number for a browser on a 24x80 screen, and
  281.     small enough to usually have no significant real-time difference from
  282.     a single message fetch.
  283.  
  284.     Setting it to 0 turns off lookahead.
  285.  
  286.     There is no protection against setting this ridiculously high and
  287.     incurring performance penalties as a result.
  288.  
  289. 17) set prefetch <number>
  290.     Sets the number of envelops which are automatically fetched for the
  291.     messages which match in a search.  This is based on the guess that
  292.     in a browser that is "zoomed" on the results of a search, you are
  293.     likely to want the envelope data for each of those messages in
  294.     short order.  Prefetching reloads the c-client cache, saves
  295.     unnecessary RTTs, and avoids loading undesired envelopes due to
  296.     lookahead (see above).
  297.  
  298.     The default is 20.
  299.  
  300.     Setting it to 0 turns off prefetch.
  301.  
  302.     There is no protection against setting this ridiculously high and
  303.     incurring performance penalties as a result.
  304.  
  305. 18) set close-on-error <number>
  306.     If non-zero, IMAP connections are closed if an EXAMINE or SELECT
  307.     command fails.  Otherwise, they are left half-open, and can be used
  308.     again to select some other mailbox.  The mailbox name in the stream
  309.     is set to {serverhost}<no_mailbox>
  310.  
  311.     The default is zero (do not close on error).
  312.  
  313. 19) set imap-port <number>
  314.     Set the TCP/IP contact port to use for IMAP.  This overrides the
  315.     wired-in setting and the setting from /etc/services, and can in
  316.     turn be overridden by an explicit user specification in the mailbox
  317.     name, e.g. {serverhost:143}foo
  318.  
  319.     The default is zero (use setting from /etc/services or the wired-in
  320.     setting (143).
  321.  
  322.     There is no protection against setting this to a silly value, and
  323.     doing so is a great way to cause users extreme grief.
  324.  
  325. 20) set pop3-port <number>
  326.     Set the TCP/IP contact port to use for POP3.  This overrides the
  327.     wired-in setting and the setting from /etc/services, and can in
  328.     turn be overridden by an explicit user specification in the mailbox
  329.     name, e.g. {serverhost:110/pop3}
  330.  
  331.     The default is zero (use setting from /etc/services or the wired-in
  332.     setting (110).
  333.  
  334.     There is no protection against setting this to a silly value, and
  335.     doing so is a great way to cause users extreme grief.
  336.  
  337. 21) set uid-lookahead <number>
  338.     Sets the number of UIDs that are looked ahead in IMAP in mail_uid().
  339.     Lookahead preloads the c-client cache and saves unnecessary RTTs.
  340.  
  341.     The default is 1000, small enough to usually have no significant
  342.     real-time difference from a single message UID fetch.
  343.  
  344.     Setting it to 0 turns off lookahead.
  345.  
  346.     There is no protection against setting this ridiculously high and
  347.     incurring performance penalties as a result.
  348.  
  349. 22) set mailbox-protection <number>
  350.     Set the default protection for newly-created mailbox files.
  351.  
  352.     The default is 384.
  353.  
  354.     There is no protection against setting this to a silly value, and
  355.     doing so is a great way to screw things up massively.
  356.  
  357. 23) set directory-protection <number>
  358.     Set the default protection for newly-created directories.
  359.  
  360.     The default is 448.
  361.  
  362.     There is no protection against setting this to a silly value, and
  363.     doing so is a great way to screw things up massively.
  364.  
  365. 24) set lock-protection <number>
  366.     Set the default protection for lock files
  367.  
  368.     The default is 438, which is necessary if locks are to be respected
  369.     by processes running as other UIDs.
  370.  
  371.     There is no protection against setting this to a silly value, and
  372.     contrary to what you may think just about any value other than 438
  373.     turns out to be a silly value.
  374.  
  375. 25) set disable-fcntl-locking <number>
  376.     This only applies to SVR4 systems.
  377.  
  378.     If non-zero, fnctl() locking is not attempted.  In the past, this
  379.     was used to avoid locking NFS files.  If NFS is involved, the evil
  380.     lockd/statd daemons get invoked.  These daemons supposedly work over
  381.     NFS, but really don't.
  382.  
  383.     You probably don't really want to do this, though, because now the
  384.     flock() emulator (which calls fcntl()) now checks to see if the file
  385.     is accessed via NFS and no-ops the lock.  This is compatible with
  386.     BSD.
  387.  
  388.     Disabling fcntl() locking loses a great deal of locking protection
  389.     on local files as well as NFS files (which now never have locking
  390.     protection).
  391.  
  392.     The default is zero (fcntl() locking is enabled).
  393.  
  394.     It is HIGHLY RECOMMENDED that you build c-client using the
  395.     -DSVR4_DISABLE_FLOCK build option instead.  You should probably
  396.     also enable EACCES errors (see below).
  397.  
  398. 26) set lock-EACCES-error <number>
  399.     If non-zero, a warning message is given if an attempt to create a
  400.     lock file fails.  Otherwise, EACCES is treated as a "silent failure",
  401.     and it proceeds without trying to use the lock file.  This is for
  402.     the benefit of users on systems with paranoid /usr/spool/mail
  403.     protections which don't let users create /usr/spool/mail/$(USER).lock
  404.     files; these unfortunate users would be harassed with a flood of
  405.     error messages otherwise.  The problem is that on SVR4, if EACCES
  406.     remains disabled and fcntl() locking is also disabled, then there is
  407.     no locking at all which is doubleplus-ungood.
  408.  
  409.     If the site is paranoid on /usr/spool/mail protections AND if there
  410.     is no fcntl() locking (SVR4) or usable flock() locking (e.g. NFS),
  411.     then there is no way to win.  Find a different system to use.
  412.  
  413.     The default is non-zero (report EACCESS as an error).
  414.  
  415.     It is HIGHLY RECOMMENDED that you build c-client using the
  416.     -DIGNORE_LOCK_EACCES_ERRORS build option instead.
  417.  
  418. 27) set list-maximum-level <number>
  419.     Sets the maximum depth of recursion that a * wildcard list will go
  420.     down the directory tree.  0 means that no recursion is permitted,
  421.     and * becomes like %.
  422.  
  423.     The default is 20.
  424.  
  425.     There is no protection against setting this to a ridiculously high
  426.     value.  Since LIST will follow symbolic links, it can effectively
  427.     recurse infinitely, until the name strings get large enough that
  428.     some name limit is exceeded.
  429.  
  430. 28) set anonymous-home-directory <directory name>
  431.    Sets the location of the anonymous home directory, if it is not in
  432.    the standard  place.
  433.  
  434.    It is recommended to use a courtesy symbolic link instead.
  435.  
  436.    There is no protection against setting this to a silly value, and
  437.    doing so is a great way to cause a crash.
  438.  
  439.