IMSP Version 1.7 ---------------- Here's a crude set of directions for setting up the IMSP server. There are several sections in this document: - Setting it up - Setting up LDAP address books - Testing it - Telemetry (logging user activity) - Predefined options SETTING IT UP ------------- You have to create the directory /var/imsp, or change the "PREFIX" definition in the syncdb.c file to an appropriate existing directory. The cyrus-imspd must be run as root to use port 406. (But I think it could be run out of inetd, so maybe that's no longer a true statement.) You should copy the "options.sample" file to /var/imsp/options after changing the site-specific lines as needed. The parenthesized lists in the options file are space separated. Binary options are set to "+" for true and "-" for false. See the "Predefined options" section for a list of options that control the IMSP server. If you want new users to be able to LOGIN to the server, be sure the "imsp.create.new.users" option is set to true (+). Without it, no one can login until a directory and options file are created for them. The AUTHENTICATE and LOGIN commands are implemented using SASL, so you need to configure it as instructed by the directions that came with the SASL libraries. That primarily involves putting SASL plug-ins into the /usr/lib/sasl/ directory. Also check the "imsp.sasl.*" options that are documented in "Predefined options" section below. If you're using Kerberos you need to create an "imap." Kerberos instance where is the first element of the fully qualified domain name (ex: imap.cyrus for cyrus.andrew.cmu.edu). Note that we use "imap", not "imsp", as the service name. The IMAP proxy features of the IMSP server were never completed and never used at any site that I'm aware of. Therefore, I decided to remove those features rather than port them to the SASL environment. The following paragraphs are kept around for history's sake. The CREATE/DELETE/RENAME and new user LOGIN commands do proxy connections to an IMAP server. You need to make sure the "imap.new.mailbox.servers" option is correct for new user LOGIN to find a server to get a list of mailboxes from. In addition, if your IMSP clients are using Kerberos tickets rather than plaintext passwords, you need to modify your IMAP server to accept the imap. ticket as valid for any user. AFS sites may need to start imspd after running pagsh to prevent ticket confusion, and other sites may need to modify the ticket file environment variable. If you are running a cyrus imap server, you can remove the file /var/imsp/mailboxes to cause an automatic re-sync of the mailbox list with the IMAP server the next time IMSP is restarted. The mailbox commands will not work with a c-client IMAP server. SETTING UP LDAP ADDRESS BOOKS ----------------------------- The IMSP server now supports a special kind of read-only address book that's implemented via LDAP lookups rather than the built-in syncdb database. The "imsp.implementation.updates" file has more details on our motivations for adding this ability to the server, so this document will just talk about setting it up. In the initial implementation, the IMSP server can only perform lookups through one LDAP server using one set of search options. The server name and other LDAP settings are retrieved from the IMSP global options file whenever they are first needed. (You don't need to provide any settings if you're not going to use the LDAP feature.) The LDAP server name and search base settings are defined in the following global options. In /var/imsp/options, replace the values as appropriate for your site. Omit the "ldapport" setting to have it default to the standard LDAP port number. The "scope" setting must be one of "subtree", "base", or "onelevel"; see the LDAP documentation on ldap_search() for more info. imsp.ldap.searchbase N o=Carnegie Mellon University imsp.ldap.scope N subtree imsp.ldap.host N ldap.andrew.cmu.edu imsp.ldap.port N 389 Next, fill in the name of the LDAP attribute that contains the full name of the entry. This is normally "cn", short for common name. The server also needs the name of an attribute which is sure to be unique for each entry. At Carnegie Mellon, more than one user can have the same common name but we know that no two entries will have the same "uid" user-id field. In the worst case, you could always use "dn", the distinguished name of the entry. Try to pick something shorter, though. imsp.ldap.fullnameattr N cn imsp.ldap.uniqueattr N uid Now define a default filter for the search operations. Generally, this should help narrow the search down to entries which correspond to people or at least entries which have e-mail addresses. The value you see below is specific to Carnegie Mellon, so make sure you change it. Something like "mail=*" would limit the search to those entries that have an e-mail attribute. If you don't want to restrict the search at all, use "(objectclass=*)", the LDAP equivalent of an unqualified wildcard search. imsp.ldap.defaultfilter N (objectclass=cmuwhitepages) Finally, you must provide a mapping table to translate between IMSP field names and LDAP attribute names. They are entered as a simple list but are interpreted as (field-name, ldap-attribute-name) pairs. Obviously, there must be an even number of items in the list. If an IMSP field name has no corresponding LDAP attribute, use NULL as the corresponding attribute name. The values suggested below are tuned to Cyrusoft's Mulberry e-mail client. The IMSP fields you see listed are exactly what Mulberry uses when storing its address books. Pay particular attention to the "alias" field since that is the one used when Mulberry 1.4 or later does nickname resolution on addresses entered in the "To" header of outgoing message drafts. We use "uid" so Andrew user-ids are automatically expanded to the full name and preferred e-mail address of the user. This should appear as one long line in your options file, but has been broken up here for readability: imsp.ldap.attrmap N (name cn address postaladdress alias uid company ou email mail fax telephonenumber notes NULL phone-home telephonenumber phone-work telephonenumber urls labeleduri) When compiling the server for your site, make sure that the configure script finds your LDAP library. Use the --with-ldap= argument if you need to help it out. For example, "--with-ldap=superldap" results in "-lsuperldap" at link time. If configure doesn't find an LDAP library or you use "--without-ldap", all the LDAP lookup features are omitted. (abook_ldap.c is not even compiled.) The remaining set up steps are done by sending commands to the running IMSP server. The "imtest" program is a simple way of interacting with your IMSP server. See below for more information. You might find that "telnet imsp.company.com 406" will also do the job if you're comfortable authenticating with the 'A LOGIN user "password"' command first. Decide which address books should use LDAP lookups. If necessary, create the address book first with the protocol: A0 CREATEADDRESSBOOK "All Users" If the address book already exists and isn't empty, that's okay. Once the LDAP feature is enabled, the old contents of the address book are ignored. Turn on the LDAP feature for the address book by setting the USER1 access control list (ACL) bit for all users. By setting the USER1 bit, the server will automatically remove all normal access bits other than READ and LOOKUP, making this a read-only address book. If you don't want users to be able to open the address book, also set the USER0 bit. This is strongly recommended as producing a list of each user in the address book can be an expensive operation when the list of users ranges in the tens of thousands. When USER0 is set, users can still search for specific entries -- they're just restricted from doing an unqualified search. The protocol for this is ('0' stands for USER0 and '1' stands for USER1): A1 SETACL ADDRESSBOOK "All Users" anyone lr01 As a quick test of your LDAP-based address book, try a simple search: A2 SEARCHADDRESS "All Users" name "*jackson*" If you don't get the results you expected, check the syslog log file for error messages. TESTING IT ---------- The test program "imtest" included with the Cyrus IMAP release is a simple protocol tester. It connects to the IMSP or IMAP server specified on the command line, line-buffers user input and sends it to the server as well as displaying server responses locally. It will convert all newlines to CRLF pairs. It also has SASL integration, so it can let you test authenticated server logins. See the documentation that comes with "imtest" for more details on using the tool. TELEMETRY (LOGGING USER ACTIVITY) --------------------------------- If you wish to save session telemetry on the server, create the directory "/var/imsp/log/". All connections by will store a telemetry log in that directory. PREDEFINED OPTIONS ------------------ The following option names are reserved in this implementation. Some of the options have been deprecated by the removal of the IMAP integration (mailbox and bboard) features or by the conversion to the SASL authentication infrastructure. Those options are prefixed with the word "OLD" in the list below. imsp.sasl.allowplaintext [NON-VISIBLE] Binary option to decide whether users are allowed to AUTHENTICATE with the plaintext mechanism. Even if this option is turned off, the LOGIN command will accept the equivalent of plain text authentications. (Should that be changed?) imsp.sasl.minimum_ssf [NON-VISIBLE] Determines the minimum security strength factor required before the server will advertise and accept a given mechanism. Measured in bits. If the client doesn't support a mechanism with at least this many bits of "strength", authentication will fail. imsp.sasl.maximum_ssf [NON-VISIBLE] Determines the maximum security strength factor allowed for the server will advertise and accept a given mechanism. See above. imsp.sasl..* Each SASL plug-in may choose to support optional or required mechanism settings. When the mechanism requests an option lookup, the IMSP server prepends the string "imsp.sasl." and the lowercased name of the mechanism to the name of the option being sought. Example: imsp.sasl.kerberos_v4.srvtab common.date [READ-ONLY] (magic) When a user asks for the value of the date option, an RFC-822 date string should be returned with the current time. This is provided to assist small clients with unreliable clocks. common.delivery.hosts [READ-ONLY] This contains the list of recommended SMTP hosts for mail delivery. common.domain [READ-ONLY] When a user asks for the domain option, the local mail domain is returned. common.from [READ-ONLY] (magic) When a user asks for the value of the from option, an RFC-822 address for that user is returned. common.sent.mailbox [READ-WRITE] The name of a mailbox to APPEND blind carbon copies. imsp.admin.all [NON-VISIBLE] This is a list of users that may use any implemented IMSP features. OLD imsp.admin.bboards [NON-VISIBLE] This is a list of users that may create, rename, delete and replace any mailbox. OLD imsp.admin.subs [NON-VISIBLE] This is a list of users allowed to view (but not change) other user's subscriptions and mailboxes. imsp.create.new.users [NON-VISIBLE] If this global option is on, the directory for a new user will be created automatically. Otherwise the system administrator must create a directory for each authorized user. imsp.create.policy [NON-VISIBLE] This is specifies the creation policy for new mailboxes. The option is specified as a site-defined string. OLD imsp.default.subs [NON-VISIBLE] A list of the default subscriptions given to a new user. OLD imsp.external.subs [NON-VISIBLE] If this is set, subscriptions to external mailboxes and mailboxes are allowed by using the {hostname}folder notation. OLD imsp.imap.servers [READ-ONLY] This global option contains a list of all IMAP servers managed by IMSP. An implementation specifier may be appended to the end of a server name with a `/' separator. imsp.ldap.* [NON-VISIBLE] See the section above for more information on all the LDAP settings. imsp.log.level [NON-VISIBLE] This integer specifies the amount of logging to be done. imsp.login.realms [NON-VISIBLE] This specifies a list of realms which are permitted to do cross-realm Kerberos authentication. imsp.login.srvtab [NON-VISIBLE] This specifies the filename of the Kerberos srvtab file. Still supported for backward compatibility, but you should probably use imsp.sasl.kerberos_v4.srvtab instead. OLD imsp.new.mailbox.servers [NON-VISIBLE] This specifies a list of IMAP servers to search for or create the INBOX for a new user, or new non-personal mailboxes. OLD imsp.proxy.authlevel [NON-VISIBLE] This is an integer bitmask of the authentication levels supported for proxy login to IMAP servers. Add 1 if cleartext permitted, add 2 if integrity permitted, add 4 if privacy permitted. Defaults to 7. The highest permitted mechanism available will be used. OLD imsp.proxy.authtype [NON-VISIBLE] This is the authentication type used for proxy login to IMAP servers. If this is not set, the best authentication available will be used. Only KERBEROS_V4 and PLAINTEXT supported at present. OLD imsp.required.subs [NON-VISIBLE] Users will not be allowed to unsubscribe to mailboxes in this list. OLD imsp.share.mailboxes [NON-VISIBLE] If this global option is on, then mailbox names beginning with the prefix "user.." are reserved as mappings of individual user's MAILBOXES into the MAILBOXES namespace. In addition, it permits users to allow other users to read their mailboxes if ACLs permit. OLD imsp.user.inbox [READ-ONLY] This is the name of a mailbox which will appear as "INBOX" on any mailbox list. The phrase "$USER" will be replaced with the login name of the current user. imsp.user.quota [READ-ONLY] This is an integer specifying the maximum number of kilobytes in the user's options & address books (doesn't include subscriptions or address book ACLs). imsp.user.quota.usage [READ-ONLY] This is an integer specifying the number of bytes used by options and address book entries (see "QUOTA" above for full details). Its value is translated to kilobytes for user requests.