Back to index

courier  0.68.2
maildircache.h
Go to the documentation of this file.
00001 /*
00002 ** Copyright 1998 - 2001 Double Precision, Inc.  See COPYING for
00003 ** distribution information.
00004 */
00005 
00006 
00007 
00008 /*
00009 
00010 The login cache is used to try to eliminate a call to getpw for each and
00011 every http request, which can be quite expensive on systems with large number
00012 of users and heave web traffic.  The following information is saved in the
00013 cache:
00014 
00015 userid
00016 groupid
00017 directory (presumably of a maildir)
00018 certain environment variables
00019 
00020 
00021 The interface is abstracted into these functions:
00022 
00023 maildir_cache_init(seconds, cachedir, cacheowner, authvars)
00024 
00025 maildir_cache_start()
00026 maildir_cache_save(userid, login_time, homedir, uid, gid)
00027 maildir_cache_cancel()
00028 
00029 maildir_cache_search(userid, login_time, callback_func, callback_func_arg)
00030 
00031 The prepare, save, and cancel functions are used to cache the login
00032 information.
00033 maildir_cache_start should be called before we attempt to log in, when we're
00034 running as root.  We're about to drop root privileges after a successful
00035 login, but we need to be root in order to update the cache directory, so
00036 maildir_cache_start forks a child process, which will wait patiently in
00037 the background.
00038 
00039 maildir_cache_save will sends the cacheable information to the child process,
00040 over a secured pipe.  maildir_cache_save will be called after a successful
00041 login.
00042 
00043 maildir_cache_cancel shall be called if the login failed.  It will kill the
00044 child process.
00045 
00046 The search function is called to query the cache file.  If it succeeds, it
00047 calls the callback function with the userid, groupid, and homedir.
00048 
00049 There is no need to manually remove an expired cache entry upon logout.
00050 It will be cleaned up by a separate cron job.
00051 
00052 
00053 init_login_cache should be called before any other function.  It's argument
00054 specifies: that hard timeout interval - the fixed amount of time after which
00055 any login becomes invalid; the login cache directory; userid that owns the
00056 login cache directory; the environment variables to save in the login cache
00057 directory.
00058 
00059 The login cache functions receive the saved original login time.  The login
00060 cache information is saved in a directory that should be writable by cache
00061 owner only.  The cache directory contains subdirectories whose name is derived
00062 by dividing the login time by the hard timeout interval.  For example, when
00063 logging on in the afternoon of November 27, 1999, the current time, in seconds,
00064 is 943725152.  With the login interval being the default of 2 hours, 7200
00065 seconds, the top level directory would be 943725152 / 7200 or 131072.
00066 
00067 What this allows us to do is to quickly remove expired login entries, simply
00068 by reading the top level cache directory, and recursively deleting subdirs
00069 whose names are too old to contain any logins that are still active.
00070 
00071 If the login name is 'john', the cached login will be saved in the file
00072 131072/jo/john, creating the subdirectories if necessary.
00073 
00074 Because the login name can contain special characters, the special characters
00075 will be escaped.  See the code for more info.
00076 
00077 */
00078 
00079 #ifndef       logincache_h
00080 #define       logincache_h
00081 
00082 #include      <sys/types.h>
00083 #include      <time.h>
00084 #include      <pwd.h>
00085 
00086 
00087 extern int maildir_cache_init(time_t, const char *, const char *,
00088                            const char * const *);
00089 extern void maildir_cache_start(void);
00090 extern void maildir_cache_save(const char *, time_t, const char *, uid_t,
00091                             gid_t);
00092 extern void maildir_cache_cancel(void);
00093 
00094 extern int maildir_cache_search(const char *, time_t,
00095                             int (*)(uid_t, gid_t, const char *, void *),
00096                             void *);
00097 
00098 extern void maildir_cache_purge();
00099 
00100 #endif