Using Pegasus Mail and Mercury in NDS Mode under NetWare 4.1 ------------------------------------------------------------------ Introduction This document covers the operating theory of Pegasus Mail in the NetWare 4.1 environment using Novell's NDS user database structure. The target audience for this file is system administrators and those who are charged with maintaining the mail system. Because of the complexity of the NetWare 4.1 environment, we strongly recommend that you take some time to read this document thoroughly. We do, however, realise that many sites would prefer to get straight into things, so if you wish, you can bypass the theory and go straight to a step-by-step setup procedure by reading the file QSETUP.TXT supplied in this archive. Contents: 1: Summary 2: Overview and operating requirements 3: Contexts and operation 4: Addresses 5: Synonyms (alternative addressing formats) 6: Installing Pegasus Mail for Windows in NDS Mode 7: Installing Mercury in NDS Mode 7.1: Modifying MERCURY.INI for NDS use. 8: Allowing Local User Lookup 9: Extended Features 10: Security Considerations 11: POP3 server considerations 12: Troubleshooting 1: Summary This document provides information on running NDS-aware versions of Pegasus Mail for Windows and the Mercury MTS on NetWare 4.1 systems. Because NetWare 4.1 does not have some of the features of NetWare 3.x that made it possible to create a maintenance-free mail system, some extra work is required to set it up for optimum use, so you should take the time to familiarise yourself with this document thoroughly before attempting the installation. In brief, installing Pegasus Mail for Windows entails following these steps: * Install WPNNW4.DLL into the same directory as WINPMAIL.EXE * Make sure current versions of the Novell API DLLs are installed on your system * Run the NDS-Aware version of PCONFIG to configure WinPMail for each context on your server that needs its own configuration. * Run the Pegasus Mail MAKEMBOX utility to create user mail directories as required in each configured context. * [Optional] Run the PMIGRATE utility to copy the mailbox contents of any user who has previously run Pegasus Mail in Bindery Emulation mode on your server to the new mailbox location. * Install PMUSER.NLM, the mailbox maintenance utility, on your file server. * [Optional] Make a small change to NDS to allow local user lookup (see section 7 in this file). Installing the NDS-Aware version of Mercury on your file server is a simpler process requiring these steps: * If you have never installed Mercury before, run SETUP.EXE -- or -- * Install MERCNDS.NLM and MERCNDSS.NLM in SYS:SYSTEM * Add a couple of new sections to your MERCURY.INI file * [Optional] Install MERCNDSP.NLM in SYS:SYSTEM for POP3 support. Installing Pegasus Mail and Mercury in NDS mode is slightly more complex than it is in Bindery Mode, but the ultimate aim is to produce a system with little or no ongoing maintenance or management requirement at the expense of a small amount of relatively simple extra initial setup and configuration. 2: Overview and operating requirements In NDS mode, Pegasus Mail no longer uses the old NetWare 3.x SYS:MAIL directory structure to deliver and store mail: instead, it expects to deliver mail to a directory called PMAIL in each user's home directory on the file server. The MAKEMBOX utility creates the necessary directories for existing users, while the PMUSER NLM creates them automatically for each user that is created in future. The aim is to produce a system that is as nearly maintenance-free as possible, and to isolate Pegasus Mail from further disastrous changes in Novell system policy in future. Clearly, though, there are a couple of specific requirements that must be met in order to make this work: * All mail users must have a writable home directory in which they have full rights. * PMUSER.NLM must be run on every file server containing a partition where Pegasus Mail users could be created. PMUSER.NLM uses one service connection and about 10KB of server RAM in normal use, and introduces almost no load on your server when it is idle. PMUSER.NLM is not required if you use the NDS-Aware version of Mercury to handle all of your mail delivery, since Mercury can duplicate the functionality of PMUSER. Running PMUSER, however, allows Pegasus Mail's local delivery agent to function normally, just as it always has under NetWare 3.x and earlier. 3: Contexts and operation NDS provides a tree structure which can contain many organizational units. Pegasus Mail's NDS-awareness supports the full idea of NDS, allowing different configurations for specific organizational units within your NDS tree. You can also create configurations that apply to a particular subtree of the NDS hierarchy, or even to the whole NDS tree by choosing where you place the configuration information. To find its configuration information, Pegasus Mail starts in the user's "Home context" - the organizational unit in the tree where the user was created, and looks for a "Profile" object called "Pegasus Mail". If it finds it, it parses the object's "Login script" attribute for its configuration information. If it does not find the object, it changes up one level in the NDS tree and repeats the search. The search continues until either a configuration object is found, or else the root of the tree is reached without finding a record. The NDS-aware version of PCONFIG creates and maintains the "Pegasus Mail" profile object for you, ensuring that all users have the rights necessary to be able to read its login script. The Profile Object Pegasus Mail uses is, however, a standard NDS data type, and can be easily manipulated using standard Novell tools such as NWADMIN or NETADMIN, provided the user doing so has sufficient rights. Unlike running in NetWare 3.x mode, Pegasus Mail MUST find at least one configuration record somewhere in the tree or it will refuse to run. The context where Pegasus Mail finds its configuration record is known as the "Configuration context" and is important for other reasons: Pegasus Mail's control groups, such as GROUPMAIL, MAILUSERS and NOMAIL must all be located in the configuration context in order to operate. Similarly, a simple mail address, such as "Peter" is presumed to be relative to the configuration context. This brings us to the next topic... 4: Addresses Just as it does under NetWare 3.x, Pegasus Mail uses the native NetWare user naming structure when running in NDS mode. So, you can enter addresses like "Admin.pmail", or "CN=Admin.O=PMAIL" and Pegasus Mail will accept these as normal addresses, routing the mail as required. You can also use "relative addresses" - so if there is an organizational unit called "Dev" in the configuration context and it contains a user called "David", you can use "David.Dev" as an address as well. Provided you install Pegasus Mail correctly in NDS mode, it can easily act as a low-maintenance enterprise-wide mail system providing mail services to all users throughout your NDS hierarchy. 5: Synonyms (alternative addressing formats) Many sites have policies mandating that particular addressing formats should be used in their outgoing Internet mail - for example, a site may want its users' Internet addresses to consist of their initials and surname, like this: D.L.Harris@pmail.gen.nz. Basic address changes like this are beyond the scope of simple aliasing - they require the co-operation of both the mail program (Pegasus Mail) to ensure that the "from" field of the message is written properly in outgoing mail, and also of the Mail Transport System (Mercury) to ensure that incoming mail using the alternative address format is routed to the proper user. In the Pegasus Mail and Mercury systems, an address of this kind, which is completely different from the user's actual login name, is called a Synonym. Creating synonyms in NDS mode is an easy two-stage process. The first stage involves using standard NetWare tools to give users their synonyms, while the second stage involves running a utility supplied with this archive to build a reverse lookup database allowing Mercury to match synonyms to their users. Note that using synonyms is NOT an all-or-nothing process - you can define synonyms for only some of your users if you wish. To create synonyms under NDS mode simply follow these steps: 1: Run the NetWare NWADMIN utility. Open the details screen for the user whose synonym you wish to set. 2: Select the Foreign Email Address button at the right of the dialog 3: Click the Set button beneath the Foreign Email Address field 4: Type in the address you want the user to have - the address can contain a domain if you wish, but if you do not add a domain, Pegasus Mail will add the proper domain for you. 5: Set the Type field to SMTP. 6: Save the entry. Repeat steps 1 to 6 for as many users as need synonyms. Once you have finished adding synonyms, start a DOS shell and run the NSYNONYM.EXE utility supplied with this archive. This utility processes the information in the NDS tree and builds a reverse synonym database Mercury can use to match incoming synonyms to the proper users. NSYNONYM has the following syntax: NSYNONYM [SUB] "Starting_domain" is the point in your NDS tree at which NSYNONYM should start looking for users with synonyms defined. You can enter [Root] here if you want NSYNONYM to process the whole NDS tree. "Synonym_file" is the name of the database file NSYNONYM should create: this will be the same file you have defined in the Synfile entry of the [Mercury] Section of your MERCURY.INI file. You should always delete the existing file before running NSYNONYM. "Sub" If you add the word "sub" at the end of the NSYNONYM command line, it will search in all contexts below the starting context for users with synonyms. Example: to have NSYNONYM create a synonym database for all users in the context Dev.PMail and in all contexts below that and write the results to the default synonym database file, you would use the commandline: NSYNONYM Dev.PMail \\SERVER\SYS\SYSTEM\MERCURY\SYNONYM.MER sub 6: Installing Pegasus Mail for Windows in NDS Mode Complete the normal installation process for Pegasus Mail, then follow these additional steps: a) Install WPNNW4.DLL into the same directory as WINPMAIL.EXE. Note that if any of your users have "-P " commandlines in use for WinPMail under Bindery Emulation mode, these options must be removed because the -P option forces Pegasus Mail to run in Bindery mode. b) Pegasus Mail is supplied with three Novell DLL files that provide the Interface into NetWare for NDS-aware utilities. These files are: NWCALLS.DLL, NWNET.DLL and NWLOCALE.DLL. You should ensure that you have exactly one copy of each of these files loadable on your system. The safest approach is to make sure that they appear in your \WINDOWS\SYSTEM directory and that all other copies on your system are deleted or removed. If you have more recent versions of these files than the ones supplied with Pegasus Mail, always use the newer versions and discard the Pegasus Mail versions. c) Run the NDS-aware version of PCONFIG to configure Pegasus Mail for the specific contexts in which it is to run. The only difference between running the NDS version of PCONFIG and the standard Bindery version is that it will ask you at startup for the name of the context in which you want the configuration Profile Object to be placed. Provided you have the necessary privileges, you can create or edit configuration objects in any context in your NDS tree. Apart from this, the screens and general operation of PCONFIG are identical to the way they operate under Bindery mode. d) Run MAKEMBOX to create user mail directories. MAKEMBOX performs the following tasks: * It ensures that the target user has a "Home Directory" attribute and issues an error if not. * It creates a directory called PMAIL in the user's home directory * It grants [C] (File create) rights to mail users in that directory: by default, the grant of rights is to [Root] (any logged-in user), but you can if you wish specify a NetWare group to which the grant of rights should be made instead. * It adds an ACL entry (ACLs are "Access Control Lists", and are the equivalent of Trustee Rights for NDS itself, controlling who can see or change what in the NDS database) that allows either [Root] or your designated mail group to read the specified user's NDS "Home Directory" attribute. * It creates an empty extended features file (PMXF.INI) in each user's new mailbox and grants [RF] rights to all mail users for it. It also grants the owning user only [RF] rights, preventing the user from modifying his/her extended features without permission. MAKEMBOX can be run in a number of ways: * MAKEMBOX - simply creates the mailbox for the single specified user * MAKEMBOX -s - creates mailboxes for every user in the context specified in the parameter. Example: "MAKEMBOX -s dev.pmail" creates mailboxes for all user objects in the context "dev.pmail". * MAKEMBOX -r -s - creates mailboxes for every user in the specified context and in every organizational unit below it in the NDS tree. In order to run MAKEMBOX you must be logged in as a user with full administrative privilege over every organizational unit in which you run the program. e) [Optional] Run PMIGRATE: if you have previously run Pegasus Mail in Bindery Emulation mode under NetWare 4.1, you can run PMIGRATE to transfer the mailbox information from the old SYS:MAIL directories to the new mailboxes for affected users. The PMIGRATE commandline syntax is simply * PMIGRATE - where "search mask" is a pattern matching the names of bindery-based users you want to migrate. Example: to migrate all users, use the commandline "PMIGRATE *"; to migrate all Bindery Users whose bindery username starts with "JOHN", use the commandline "PMIGRATE JOHN*". f) Install PMUSER.NLM on your file server. PMUSER is a very small NLM which asks NDS to notify it every time a user is created on the file server. When a user is created, PMUSER attempts to create the necessary mailbox directory for that user via the same method as MAKEMBOX. PMUSER logs into your file server using a privileged account name and uses one licensed connection on your server while it runs. If your user creation process is automated, you can duplicate the functionality of PMUSER by running MAKEMBOX for each user as you create it - the advantage of PMUSER is that if you use utilities such as NWADMIN or NETADMIN to create your users, it will automatically ensure that the necessary mailbox information is created for them without further intervention from you. PMUSER can be loaded using the following syntax * LOAD PMUSER [-u username] [-p password] [-g group] - where "username" is the NDS username PMUSER should use when logging in to NDS, "password" is the password for the account and "group" is the name of the user group PMUSER should give access to the mail properties of new user mailboxes. "group" defaults to "[Root]" (that is, all users logged-in to the file server); "username" and "password" can be omitted, in which case PMUSER will prompt you for them. 7: Installing Mercury in NDS Mode Installing Mercury for operation in NDS mode is only slightly different from installing it for normal Bindery-mode operation. Complete all the steps in the normal installation process, then do the following: a) If there are copies of MERCURY.NLM, MERCURYP.NLM or MERCURYS.NLM in SYS:SYSTEM, remove them; they are not used in NDS mode. b) Make sure MERCNDS.NLM and MERCNDSS.NLM have been installed in SYS:SYSTEM on your file server. c) Edit your MERCURY.INI: add the [NDS] section and modify the [Domains] section as described below. d) Load MERCNDS.NLM, MERCNDSS.NLM and MERCURYC.NLM on your server. Optionally, load MERCNDSP.NLM if you want to make POP3 services available for your server. 7.1: Modifying MERCURY.INI for NDS use. At startup, Mercury parses your MERCURY.INI file as it has always done, except that it expects to find a new section, [NDS], and to find different entries in the [Domains] section. a) The [NDS] section. Mercury uses this section to work out who it should log in as. In order to operate in NDS mode, Mercury needs to login to Directory Services using a privileged user account. See the section entitled "Security considerations" at the end of this document for discussion of the type of usercode Mercury should be given. The NDS section can contain four entries: USERID - the NDS "Distinguished Name" of the user identity Mercury should use to login to NDS. Example "USERID : Admin.pmail". There is no default for this section - it must be provided. The name you use should be expressed relative to the root of the NDS tree. PASSWORD - the password for the account given in "USERID". If you omit this field, or leave it blank, Mercury will prompt you for a password when it loads and will not process any mail until you respond. MAILBOX_MODE - should be either 0 or 1. If 0 (the default), Mercury will use the mailbox methods described in section 5d above. If 1, Mercury will assume that you have installed the Novell MHS Services product on your server and will use the mailboxes created by that system instead. AUTOMAINTENANCE - should be either 0 or 1. If 0 (the default), Mercury will NOT attempt to create mailboxes for users that do not have them already. If 1, Mercury will use the same creation method as MAKEMBOX and PMUSER to create mailboxes for users when it detects a user without a mailbox. If "Automaintenance" is set to 0 and mail is sent to a user without a mailbox, a delivery error occurs. It is legal to omit the [NDS] section; if you do so, Mercury will prompt you to enter a username and password when it starts up. b) The [Domains] Section. In NDS mode, Mercury uses the [Domains] section to associate an NDS organizational unit with an Internet domain. The syntax of the section is basically the same as under Bindery mode, but with one or two extra capabilities. Each entry in the [Domains] section must have an NDS context on the left and an Internet domain name on the right. The NDS context name must be expressed relative to the root of the NDS tree. If you wish to apply an entry to an entire subtree rather than to a single specific context, add a '/' character at the start of the NDS context name. Example: The Organization "Acme Inc", has two separate divisions in the same NDS tree, "Sales" and "Manufacturing". The "Manufacturing" division contains three more organizational units, "Development", "Futures" and "Production". The Sales division has only one organizational unit, "Marketing". The NDS tree for Acme Inc looks like this: Acme Inc --+-- Sales ----------+-- Marketing | +-- Manufacturing --+-- Development | +-- Futures | +-- Production The Internet domain name for Acme Inc is "acme.com". Because the Sales and Manufacturing Divisions are administratively separate, they want to have the domain names "sales.acme.com" and "mfg.acme.com" respectively. Because of political divisions within the Sales group, the Marketing division also wants to have its own domain name, "mktg.acme.com". The Manufacturing Division, however, is happy to have "mfg.acme.com" apply to all its sub-divisions. The [Domains] section that achieves this organizational structure would be as follows: [Domains] Marketing.Sales.Acme Inc : mktg.acme.com Sales.Acme Inc : sales.acme.com /Manufacturing.Acme Inc : mfg.acme.com Note the use of the '/' in the last entry to indicate that "mfg.acme.com" should apply to all the organizational units beneath "Manufacturing" in the NDS tree. c) Restrictions There are certain restrictions you must observe when running Mercury in NDS mode: i: Your users' names must only contain standard ASCII characters. If you have usernames that contain special or extended ASCII characters, then you must create ASCII-only synonyms for those users. ii: If you use the '/' character to apply an Internet domain name to an NDS subtree then your users' names must be unique throughout that subtree. If you have two users with the same names in different organizational units of a subtree served by Mercury, then one of the users must be given a synonym that distinguishes him or her from the other user. iii: Usernames may contain spaces; Mercury and Pegasus Mail will convert the space characters to underscores when writing the user's address into Internet mail. NDS regards spaces and underscores as exactly equivalent - if this condition ever changes in future versions of NetWare, then users whose names contain spaces must be given synonyms. iv: You may have more than one Internet domain name mapped to a single NDS context, but you may not have multiple NDS contexts mapped to a single Internet domain name except by using the '/' operator. 8: Local User Lookup WinPMail supports local user lookup directly from the NDS database (via the "Local users" option on the "Addresses" menu). Unfortunately, Novell made some curious design decisions about default access rights when they implemented NDS - most notably that users cannot by default access any information about other users other than their surnames and their default servers. By default, the PMUSER.NLM and MAKEMBOX utilities will add an ACL (ACLs are the same as trustee rights except they apply to the NDS database and control who can see what information) allowing all users to see other users' full names, but this grant of rights can be suppressed on the commandline if you wish. An alternative way of allowing all users to see other users' full names involves making a small global change to the NDS database one time. If you would prefer to use this option to enable local user lookup within Pegasus Mail, follow these steps: 1: Login as ADMIN 2: Run the NetWare NWADMIN administrator tool. 3: Highlight the first context below the root context (i.e, the highest level context other than "Root"). 4: Choose "Trustees of this object" from the "Object" menu. 5: Click on "Add trustee" 6: Change your context to "[Root]" and double-click "[Root]" in the "Objects" list. 7: Click OK to save the trustee assignment. 8: Highlight "[Root]" in the "Trustees" list, then check the controls labelled "Browse" (on the left) and "Read" and "Compare" (on the right). The effect of this change is to permit all users the default right to browse information about other users. 9: Extended Features Pegasus Mail has a number of specialised features that are not normally enabled for every user. In NetWare 3.x mode, these features were stored in the NetWare Bindery, where they were readable by all users. Under NetWare 4.1, the only equivalent way of doing this involves modifying the base NDS schema to add a new object type: unfortunately, at the time of writing, modifying the base schema has far-reaching consequences (most specifically that it is impossible to merge two NDS trees where either has a modified schema) and hence we have had to rule out this approach. Instead, WinPMail and Mercury look for a file called PMXF.INI in each user's new mail directory. This file must be world-readable to be effective. PMUSER and MAKEMBOX will automatically create a zero-length version of this file when creating a new mail directory for a user, and will grant [RF] rights to all users, as well as making an explicit grant of [RF] to the user himself; this latter grant prevents the user from modifying the file, thus keeping compatibility with Pegasus Mail under NetWare 3.x (where by default users are not permitted to modify their extended feature sets). To allow a user to modify his/her extended features, grant all rights to PMXF.INI. Note that if you manually edit a PMXF.INI file, you will probably alter the rights grants to the file. Make sure you grant [RF] to [Root] (all logged-in users) each time you modify the file manually. PMXF.INI is a simple text file that contains statements, one per line. The following statements are recognized: "Local autoforward =
" - Sets a forwarding address for mail delivered by Pegasus Mail itself. "
" can be any valid address to which you could normally send mail using Pegasus Mail. "Internet autoforward = " - Sets a forwarding address for mail delivered by Mercury. The address can only be a local NDS address or an Internet address. "Deliver even when forwarding = " - Determines whether or not a copy of mail that is automatically forwarded by Mercury or Pegasus Mail should be left in the recipient's new mailfolder as well. "Allow confirmation of reading = " - If 'N', then Pegasus Mail will not honour requests for confirm- ation that a message has been read. "Disable mail delivery = " - If 'Y', then no mail can be delivered to this account. "Send delivery broadcasts = " - If 'Y', then NetWare broadcast messages will be sent to the recipient when new mail arrives. Lines beginning with '#', ';' or '*' in PMXF.INI are regarded as comments and are ignored. 10: Security Considerations Running Pegasus Mail in NDS mode does not compromise the security of your server, but it does create some conditions of which you should be aware. Firstly, Mercury and PMUSER must login to Directory Services using privileged usercodes. The most expedient approach is to have them login using the ADMIN account: this creates a security issue in that the passwords for these accounts must be given to the programs in some way. Mercury will prompt for a password if none is provided in MERCURY.INI and PMUSER will also prompt for the password if it is not passed on the commandline; you may want to consider carefully how these applications are loaded in this light. Another alternative is to create a user account that can be used by PMUSER and Mercury but which is more limited in privilege than the ADMIN account. If you do this, the account you create must be able to do the following things: * Read and set the Home Directory attribute for any mail user * Create directories in any user's home directory * Grant trustee rights in any user's home directory * Browse the entire NDS tree without restriction * Grant ACLs covering any mail user's "Home Directory" attribute * Create, rename, delete, read and write files in any mail user's home directory. * Change the ownership of any file on the system * Read SYS:SYSTEM/MERCURY.INI * Verify any user's NDS password Pegasus Mail and Mercury require grants of rights to all mail users, but only at the smallest possible rights levels. The only viable security consideration that can arise from these extra grants of rights is a fairly standard service denial attack - because all mail users have [C] rights in all other mail users' new mail directories, it is possible for someone to exhaust a user's disk space allocation by repeatedly creating files in that user's new mail directory. This is not much of an attack, though, because you can always see the owner of the files that are created in the process and trace back to the culprit that way. The only other security consideration arising from the use of Pegasus Mail and Mercury in NDS mode is a provision of information consideration: by default, NetWare NDS permits users to read their own home directory information from the Directory Services database, but not to read the location of other users' home directories. MAKEMBOX, Mercury and PMUSER can all alter this so that all mail users can see all other mail users' home directory locations in the database. While it is unlikely that this information could really have much consequence, some sites may prefer not to make it available for some reason. In cases like this, you should consider using Mercury to handle all your mail. 11: POP3 server considerations Under NDS, it is possible to have exactly the same username defined in multiple contexts in your NDS tree. This can pose a problem for MERCNDSP, the POP3 server, in that when presented with a name like "david", it may be unable to tell which of several possible "david"s in your NDS tree is the proper user. To get around this, you can take one of two approaches: * Require your users to give a full NDS distinguished name when logging in to the server (for example, "david.dev.pmail"). * Create a POP3 alias file, POPALIAS.MER, in SYS:SYSTEM. This file simply equates a simple username (like "david") to the full NDS format used for logging in (like "david.dev.pmail"). POPALIAS.MER is a simple text file where each line has the form: = As an example, using the names above, you would have the line david = david.dev.pmail NDS usernames must be expressed as full paths relative to the root of your NDS tree. Each line must begin hard against the left margin. Lines beginning with #, * or ; are regarded as comments and are ignored. 12: Troubleshooting "When I run MAKEMBOX or the other commandline utilities, they complain about failing to initialize unicode tables." This is a problem with the NetWare API library. Novell provide a suite of files to handle the conversion from unicode to local character sets and back - these files are the ones in SYS:PUBLIC/NLS on your NetWare 4.1 file server, and have names like 1250_UNI.042 or UNI_MON.061. These files MUST be on your DOS PATH before you run any of the Pegasus Mail support utilities, and when running Pegasus Mail itself. "WinPMail complains about a Locale Failure at startup" "WinPMail appears to start up, but when I look in the 'Info' screen in the 'About Pegasus Mail' dialog it hasn't picked up any of my NDS information." This problem can be caused by unicode table failure - see above for more information on this. There is also a more subtle cause for this problem: if you are running Windows 95, it is possible for you to select a country setting (using the "Regional Settings" control panel) for which Novell have not provided Locale support. An example of this is New Zealand, which Microsoft supports as a separate country, but which Novell seems to regard as part of Australia. Unfortunately, the ONLY known solution for this at this stage is to change your regional setting to one for which Novell DO offer support. "I've granted extended features to a user and can see the PMXF.INI file in his new mail directory, but none of the settings are being used." Have you edited the file manually? If so, the rights settings for the file have probably been disturbed. Make sure that [Root] (all logged-in users) has [RF] rights to the file - you can do this using the command: RIGHTS PMXF.INI RF /name=[Root]