From ISPMan

Contents 1 Introduction 2 Using ISPman with FreeBSD 4.9 3 Section 2: ISPman Component Services Setup 3.1 Cyrus IMAPd 2.1 3.2 Postfix 2.0 3.3 Bind 9.2 3.4 Apache 2.0 3.5 Pure-ftpd 3.6 Perdition

[edit] Introduction

There are mailing list archive references to [1]. Unable to find it on that site, it was dug out of archive.org and is pasted here. This is the version from the archive from Apr 21, 2006, although it does not appear to have been updated since Oct 17, 2004. This is still quite out of date (as of now FreeBSD 6.2 is current, and the versions of everything have changed, but it may provide some breadcrumbs for those in need. -NG 2006-04-18

[edit] Using ISPman with FreeBSD 4.9

This installation guide is intended to help the typical administrator install ISPman on a clean FreeBSD 4.9-stable system. It is perfectly possible to add it to a system already handling other tasks, but you must be mindful of the port versions in use. I am making the assumption that the reader is more or less familiar with the FreeBSD operating system in particular, and open source ‘Linux / BSD’ systems in general. Good knowledge of the ports system, and in particular adding/checking/removing ports is also useful. More information can be obtained from the BSD ports handbook, [2].

This document is currently a basic installation guide, and does not cover sysadmin type practices like security, or reboot persistence, or the like. Maybe later. Here is a brief guide to security. Block OpenLDAP ports at your border router. Here is a brief guide to reboot persistence. Line everything up in /etc/rc.local. The needed services are slapd, saslauthd, cyrus-master, apache, bind, and postfix. There are numerous ways for starting each one, the proper way for your particular version can be observed from some testing. Section 1: ISPman Core Setup

1. Install FreeBSD, making sure to include ALL sources and the Ports collection. You should end up with tons of junk in /usr/src and /usr/ports. This will be useful to you later. Finish the setup of the machine by configuring it’s network access in /etc/rc.conf and /etc/resolv.conf.
2. Update the system. Technically, its not necessary at all, since all the ports used here are included in full working version in the base install ports tree. I have a very basic update utility written in bash, available at [3]. If you choose to do it manually, updating the ports tree is probably most important, and can be done several ways, the easiest of which is through CVSUP. Updating the kernel and world can be done at your leisure, but is a good idea to do, to keep ahead of bugs and such.

     Suggested Reading: [4]

1. Install necessary ports. This is a fairly time consuming task, but could be automated with a script calling each port install in succession. Be sure to keep an eye on the make options, sometimes defaults can change, requiring a specific make parameter. If in doubt, tell it to make whatever looks necessary. Rarely will too many make options ever cause a problem. The ports to be installed are

• • Perl-5.8 in the lang section. Be sure to follow its instructions, specifically to run `use.perl port’ after installation.
  • Openldap-client-2.1 and openldap-server-2.1 in the net section

           WITH_SASL=1 is needed for direct SASL compatibility.  If PAM_LDAP is used then it should be safe to ignore.  It does not hurt to use just in case. This port should install berkeley-db 41 with it as well, which is the ideal BDB to be used with later ports.   This port should install cyrus-sasl-21 with it as well.

• • pam_ldap in the security section.
  • Cyrus-sasl-saslauthd21 in the security section.
  • Cyrus-imapd21 in the mail section.
  • Apache2 in the www section. Making with_ldap=1 is useful later.
  • Mod_perl2 in the www section. If this causes an error, be sure to run `use.perl port`
  • Postfix in the mail section. In the menu, check sasl2, db41, and openldap21, corresponding to the other ports you have installed. Respond yes if it asks various questions about mail integration, we want it to be the default mail program on the system. Also take note of its suggestion to disable sendmail; more on this will be covered later.
  • Bind9 in the dns section.
  • PureFTPD in the ftp section. Be sure to specify WITH_LDAP=1.
  • Perdition in the mail section. Be sure to specify WITH_OPENLDAP=1.

1. Install the ISPman system. The best way to do this is with the cvs fetch method suggested at [5].

• • Remember that in FreeBSD, the ports are all preconfigured to run from a base of /usr/local. When choosing your ISPman install path, you may want to put it here as well to keep things orderly. It does not really matter for functionality, however.
  • Run ./configure in the base of the downloaded tree, and then make ISPman. Answer its questions; most options are variable preference, and safe to leave at default. The critical option is the OpenLDAP configuration directory, which in FreeBSD is /usr/local/etc/openldap. Also, the UID/GID ranges should be set to a conservative level, the default is to take any available, but that means new users added unix-style will trample ISPman users. Choosing 1500 for the base of each is a good level, or lower if you anticipate few to no needed unix users and many needed ISPman users.
  • Run make ispman install_ispman_common install_ispman_web to get everything built. Answer its questions naturally. If you change the install home (to something other than opt) you should then re-run ./configure to guarantee the changes take effect. As it suggests, you can then delete or clear the CVS tree you downloaded, and move to the installation directory you chose, for further work.

1. Configure OpenLDAP for ISPman.

• • Copy the temporary ldap configuration files from [ispman]/build/tmp/conf/ldap.conf and [ispman]/build/tmp/conf/slapd.conf to their proper home in /usr/local/etc/openldap/. Also copy [ispman]/build/tmp/conf/schema/* to /usr/local/etc/openldap/schema/.
  • Check the slapd database directory in slapd.conf, to make sure it exists. The default in FreeBSD is /var/db/openldap-data/ but the config will probably want /var/lib/ldap. Either one will work fine, so long as the directory exists.
  • You should then be able to start slapd from /usr/local/libexec/slapd and be ready to go. Note: See the next step before considering this done.

1. This step is a potentially temporary note about OpenLDAP. It has been found that with the basic install of FreeBSD 4.9, the crypt function used by OpenLDAP and that used by ISPman are incompatible. This means that a different password hashing method must be used.

• • For OpenLDAP, the solution is to run `slappasswd –h {md5}’, and at the prompts enter the password that you told ISPman about earlier.
  • Take the hash, which probably looks like {md5}bygv87tyg87gf7v8tf6tf67tfrd, and replace the crypt hash on the rootpw line in /usr/local/etc/openldap/slapd.conf with the md5 hash you just made.
  • This will make the OpenLDAP database useful, but does not complete the changeover from crypt to md5. More will be specified on this later.

1. Install the basic OpenLDAP tree with ISPman. To do this run `make ldif-install’ from the [ISPman]/build directory. This should generate a solid stream of ldap query data. If you see an error anywhere here such as invalid credentials, or unable to contact ldap server, or if the stream of ldap queries includes ‘general errors’ you will need to go back and check your configuration. More info will probably be available in the troubleshooting section of this document.
2. Set up apache to run the ISPman front-end.

• • If the server will have a more generic front-end, then set apache’s default page to whatever is desired there. Then, add a virtualhost or path alias to the [ISPman]/htdocs directory. The path will also need an execCGI option.
  • If you are setting things up from scratch, and are new to apache, here specifically is what needs to be done.

i. Find and remove the following line (it causes trouble in many cases):

 LoadModule unique_id_module libexec/apache2/mod_unique_id.so

ii. Add the following two lines (for organization, putting them after the other loadmodule lines is ideal):

 LoadModule perl_module libexec/apache2/mod_perl.so
 PerlModule Apache2

iii. Set the ServerName line to something appropriate (ip address or ACTUAL hostname is ideal):

 ServerName 10.7.55.54:80

iv. Change the DocumentRoot line to the following:

 DocumentRoot "[ispman]/htdocs"

v. Change the following directory declarations:

 <Directory “[ISPman]/htdocs/">
 Options Indexes FollowSymLinks ExecCGI

vi. Change the DirectoryIndex line like so:

 DirectoryIndex index.html index.html.var index.cgi

vii. Change the scriptalias like so:

 ScriptAlias /cgi-bin/ [ispman]/cgi-bin/"

viii. Uncomment the AddHandler line like so:

 AddHandler cgi-script .cgi

1. Get a administrator login, with the proper hash. In case you’re prone to confusion, here is a shakedown of the login setup. OpenLDAP uses the rootpw specified in the conf file. To ISPMAN, the password for OpenLDAP, and the admin account ispman’s password are the same. This does not mean they are stored in the same place. All administrators connecting via the web interface get their password checked against the hash held INSIDE OpenLDAP. In the case of FreeBSD 4.9, you need to change the scheme used by ISPMAN to hash passwords. This can be done easily in the following way:

• • [ISPman]/bin/ispman.setVar -m sys_vars userPassHashMethod md5
  • [ISPman]/bin/ispman.addAdmin -l 100 -f joe -m joe@not.com -p joespass joe

1. Make sure the web server is started, and then log in to the admin interface. In a browser, connect to the machine in question, select log in as administrator, on the following page enter the newly created admin name, along with his password, the administrator option, and the language you prefer.

• • As a cleanup measure, go to configure, and Administrator accounts, and then change the cyrus and ISPman account passwords by putting the clear text passwords you specified to the ISPman config in, and clicking Update. The password will then be rehashed with the new method, and the system should be ready to run.
  • From this point, the basic control system is in place for ISPman. It is not; however, ready to handle any actual tasks. This document will go on to detail the steps to set up cyrus-imap, postfix, apache, pure-ftpd, and bind. If you are fairly familiar with these, their configuration should not be difficult, as they interface in a fairly straightforward manner. Postfix, cyrus, and pure-ftpd need special configuration options to interface directly with LDAP, and apache and bind need include statements that point them to a prefabricated config file produced by ISPman.
  • You will have to decide, at some point before ISPman starts taking in any useful information, what servers you will be using for this setup. The idea behind ISPman is that it provides the front-end for new information, and stores it for manipulation. When new data is received, ISPman triggers it’s agent to apply the settings to a given number of hosts, who will handle the process from then forward. All of the steps listed here for the ISPman core need to be done on the central server, but the component services can run locally, or on any other server.
  • Another note, to those who may not be familiar with ISPman: ISPman’s OpenLDAP backend is the central repository of information, and all the rest of the parts can be run anywhere else, including the web front-end. This document is targeted at a single-server installation, but is perfectly applicable to a situation of splitting the services up among many servers. More attention must be paid to the requirements of each service, and their configurations, but there is no special information needed to run a distributed system.
  • ISPman host and host-group setup: From within the web front-end, it must be decided what servers will be taking each responsibility. The suggested method is to simply let the local machine take all tasks, since if you are following the rest of this document verbatim that’s where they will be. Setting up a host and adding it to a group is self explanatory, but something to be careful of is the hostname at which each server sees itself. ISPman will be using the hostname function locally on each server to determine its own name, and the [ISPman]/bin/ispman.myhostname function is helpful to check certainly what name ISPman sees. If you notice hosts simply aren’t executing their processes, double check this area and if necessary, edit [ISPman]/conf/ispman.conf to include the following (notice spaces separate multiples):

           $Config->{'hostnames'}="myhostname1 myotherhostname";

[edit] Section 2: ISPman Component Services Setup

This section is intended to cover the popular components tied into ISPman. It is possible to run other versions or different packages entirely, but we will cover the most popular ones bundled with FreeBSD. These packages require a number of configuration changes within ISPman’s web interface, for FreeBSD specific differences. The system in general also requires a number of settings for your domain. Specific details will be stated in their appropriate sections later in this document, but it’s best that (if possible) you update all the information to be as accurate to your situation as possible.

[edit] Cyrus IMAPd 2.1

Cyrus is an all in one ‘Post Office’ solution, comprising intelligent mailbox handling, complete imap and pop3 services, and user account management. I have included a long-winded explanation of how it is intended to work with ISPman, because it’s one of the more intricate processes in the entire installation.

Cyrus is normally intended to run with its cohort Cyrus SASL, which handles user accounts and passwords. In our setup, we want ISPman to coordinate everything, and in order to do so we will keep the users and their related information in OpenLDAP. This means that for Cyrus to do it’s job, it will need a connection to our ldap service. This is one of the trickier tasks to complete. Cyrus works with SASL, the Simple Authentication and Security Layer. SASL is the clearinghouse for Cyrus authentication information, and can tie in to a number of other components to accomplish this. Saslauthd, the daemon run by SASL, is what gets this job done. It is necessary to connect Saslauthd to PAM, the pluggable authentication module that just about all linux/bsd systems use, and then connect PAM to OpenLDAP. To do this, you will use the pam_ldap module installed earlier.

The entire process is as follows: A new imap session (or pop3 hit) is initiated by a remote user, and is caught on the server by cyrus-master. Master then turns it over to an imap or pop3 instance, which then proceeds to gather the credentials (login and pass) from the user. The instance then uses the ‘auth mech’ (specified in imapd.conf) to validate the information. In our case, that will be saslauthd (run in ‘-a pam’ mode). The saslauthd daemon then uses PAM (which in this case is more a library than a process) to process the login. PAM in turn knows to relate the imap/pop3 login to OpenLDAP (detailed in pam.conf and ldap.conf). OpenLDAP then provides the information to pam_ldap, the clear text password is hashed (as specified in ldap.conf) and the results of the login (ok/fail) are relayed back through saslauthd to the imap/pop3 instance.

Once the modules are installed, there are only a few configuration areas to update to tie everything together.

1. Update pam.conf to associate pam_ldap properly by replacing the pop3 and imap lines in /etc/pam.conf with the following:

     imap    auth    required        pam_ldap.so                     try_first_pass
     pop3    auth    required        pam_ldap.so                     try_first_pass
     imap    account required        pam_ldap.so                     try_first_pass
     pop3    account required        pam_ldap.so                     try_first_pass

2. Update the ldap settings that pam_ldap will use. These settings are universal, and pam_ldap comes compiled with the intention of using /usr/local/etc/ldap.conf for its configuration. This file can (but does not have to) be a symlink to the similar file in /usr/local/etc/openldap/ldap.conf. The file needs to contain the following information:

     host 127.0.0.1
     o=ispman
     ldap_version 3
     pam_password md5

3. Update the settings in /usr/local/etc/imapd.conf. There are two areas that need to be updated, the rest can be left in place. Find and check the following settings:

     allowplaintext: yes
     admins: cyrus
     sasl_pwcheck_method: saslauthd

4. Set up the imap spool areas (as set in imapd.conf, the default is OK) by running /usr/local/cyrus/bin/mkimap.

5. Make sure cyrus-master is running (it’s started from /usr/local/cyrus/bin/master). This process does not run as a daemon by default, the easiest way is to simply fork it by using the & operator after the command when run from the prompt. It is recommended to run a wrapper for cyrus-master, but that’s beyond the scope here. At this point, cyrus should be ready to set up new mailboxes and allow authentication. The mail will still need to get there somehow, right?

6. You should be able to add new mailboxes and ‘pop’ them, and this should be tested before continuing. Add a junk domain and user to ispman, wait for the agent to process it, and try popping the mailbox using any email client. If this does not work, the first thing to check is /var/log/messages, where failures from imapd will turn up. If you have problems, recheck your work and if necessary do further debugging by starting saslauthd and slapd with the debug option (-d) to check that the process is flowing from end to end.

[edit] Postfix 2.0

The next natural step is to provide a method for email to get placed into cyrus’ email boxes. Postfix is the email server of choice for this, because it’s easy to configure, has the necessary connections to LDAP and Cyrus, and is bundled with FreeBSD. Sendmail is the default server in FreeBSD, and in fact it comes as part of the ‘world’ meaning it cannot easily be uninstalled. It needs to be disabled, however, for Postfix to run properly.

1. Once postfix is installed, follow it’s advice in disabling sendmail (as detailed in the port installation information) with the following entries in /etc/rc.conf:

     sendmail_enable="YES"
     sendmail_flags="-bd"
     sendmail_pidfile="/var/spool/postfix/pid/master.pid"
     sendmail_outbound_enable="NO"
     sendmail_submit_enable="NO"
     sendmail_msp_queue_enable="NO"

2. Alter the postfix config file held in /usr/local/etc/postfix/main.cf in the following way

     virtual_maps = hash:/usr/local/etc/postfix/virtual ldap:ldapvirtual
     ldapvirtual_server_host = localhost
     ldapvirtual_server_port = 389
     ldapvirtual_bind_dn = o=ispman
     ldapvirtual_bind = no
     ldapvirtual_timeout = 5
     ldapvirtual_search_base = o=ispman
     ldapvirtual_query_filter = (|(mailLocalAddress=%s)(mailAlias=%s))
     ldapvirtual_result_attribute = mailRoutingAddress,mailForwardingAddress
     ldapvirtual_lookup_wildcards = no

     mailbox_transport = cyrus

     mydestination = $myhostname, localhost.$mydomain hash:/usr/local/etc/postfix/destination_domains

     relay_domains = hash:/usr/local/etc/postfix/relay_domains

3. Set the ISPman mail configuration in the web front-end to reflect Postfix as it is installed on your system. The settings are as follows:

     smtpServerReloadCommand  /usr/local/sbin/postfix reload
     makeMapCommand  /usr/local/sbin/postmap
     smtpServerConfDir  /usr/local/etc/postfix

4. Postfix should now be ready to handle incoming mail. Start it using `postfix start’ and check the maillog for errors. This setup did not detail SMTPauth, which is supported in the ISPman system, but currently outside the scope of this document. A standard postfix relay system can easily be added without much trouble, to allow in a set of IPs, hostnames, etc.

5. The mail system should now be checked. This can be tricky, as it requires an actual MX to be directed at your server. Alternatively, you can simply smtp by hand using telnet 25, and put together a piece to test the system. If problems arise, checking /var/log/maillog is the starting place to find possible error messages.

6. There is an alternative delivery method for postfix-cyrus mail, which is LMTP. LMTP is the local mail transport protocol, and like the name says it is intended for local delivery of mail. It is favored over the default, which is cyrus’ deliver program, because of efficiency and universality.

There are two ways of configuring LMTP, the first being localhost-only mail, with no authentication at all. The second, much more complicated way, is to use lmtp-auth between postfix and cyrus. This method has the advantage of being transportable, allowing LMTP to move mail between servers. This scenario has not been explored with relation to ISPman, and is currently not documented. The following instructions are for setting up LMTP transport on a local to local system.

        1. update /etc/services in the following way:
           lmtp             24/tcp    any private mail system
           lmtp             24/udp    any private mail system
        2. update /usr/local/etc/postfix/main.cf in the following way:
           mailbox_transport = lmtp:localhost
        3. update /usr/local/etc/cyrus.conf in the following way:
           lmtp          cmd="lmtpd -a" listen="localhost:lmtp" prefork=0
           lmtpunix      cmd="lmtpd -a" listen="/var/imap/socket/lmtp" prefork=0
        4. restart cyrus and postfix, and test the system.  There will be no apparent change in functionality, but  /var/log/maillog will now show from/to piece handling with a lmtp tag like the following:

         * Feb  2 17:58:17 ns1 postfix/lmtp[94924]: 89BF529F: to=<jeff_meden_org@ns1.meden.org>, orig_to=<jeff@meden.org>, relay=localhost[127.0.0.1], delay=0, status=sent (250 2.1.5 Ok)

        5. You will stop seeing the previous pipe method when cyrus deliver was used:

         * Feb  1 15:01:29 ns1 postfix/pipe[92566]: 168E62E5: to=<jeff_meden_org@ns1.meden.org>, orig_to=<jeff@meden.org>, relay=cyrus, delay=0, status=sent (ns1.meden.org)

[edit] Bind 9.2

FreeBSD’s world in 4.9-stable comes with Bind 8 by default, but you probably want something a little newer, right? Bind 9 can be installed, and the existing Bind 8 installation ignored, with little trouble. Once the package is installed, and you’ve paid attention to the information provided during the port installation (about rndc and random-key generation, among other things) you simply need to update ISPman’s config, apply a generic named.conf, and you are ready to start hosting domains.

1. In ISPman’s web interface, the configuration section for DNS should be changed as follows:

     namedDir  /usr/local/etc
     namedIspmanSubDir  named/
     namedPriDir  pri/
     namedSecDir  sec/
     namedRevDir  rev/
     namedConfFile  named.ispman.conf
     namedUser  bind
     namedStartCommand  /usr/local/sbin/named
     namedStopCommand  /usr/bin/killall named
     namedReloadCommand  /usr/bin/killall –HUP named
     namedBackend  bind9

2. As a note to step #1: yes, named should be run in a proper wrapper, using the killall command is a bit ‘hackish’ but it does the trick. Implementing a wrapper is suggested as a good idea, but not required for this installation.

3. Create/change the /usr/local/etc/named.conf file as follows (if you don’t have an existing file, simply adding these options will get you going. If you want a more complete DNS server, you will have to add more information including localhost and root-hints):

     options {
     port 53;
     pid-file "named.pid";
     listen-on { any; };
     listen-on-v6 { none; };
     yes;
     notify yes;
     };
     include "/usr/local/etc/named.ispman.conf";

4. You can then start up named, after either touching /usr/local/etc/named.ispman.conf or adding a domain to ISPman so it sets up the file. If you take no other steps, it will harp in the log about some missing things, but it will still run normally. It is suggested that you proceed to properly install the necessary features of Bind 9 for the best performance.

[edit] Apache 2.0

Since Apache is more or less set up, there is little to be done further to add support for clients.

1. Edit /usr/local/etc/apache2/httpd.conf to include the statement for ISPman’s vhosts file, as follows, then touch the vhosts.conf file itself to ensure existence for ISPman’s sake:

     NameVirtualHost *
     Include "/usr/local/etc/apache2/vhosts.conf”

2. After that change, Apache will only recognize virtual hosts, requiring you to set a declaration for your ISPman web front-end. Add a vhost as follows:

     <VirtualHost *>
     ServerAdmin webmaster@dummy-host.example.com
     DocumentRoot /usr/ispman/htdocs              
     ServerName ispman.example.com          
     ErrorLog /var/log/ispmanweb-error_log            
     CustomLog /var/log/ispmanweb-access_log common             
     </VirtualHost>

3. ISPman’s apache config must then be updated, in the web front-end. Change the settings as follows:

     apacheVhostsFile  /usr/local/etc/apache2/vhosts.conf
     apacheStopCommand  /usr/local/sbin/apachectl stop
     apacheReloadCommand  /usr/local/sbin/apachectl restart
     apacheStartCommand  /usr/local/sbin/apachectl start
     apacheGracefulCommand /usr/local/sbin/apachectl graceful

4. Apache should now be ready for action. Check this by adding a virt host to a junk domain, and checking to see if it shows up in vhosts and that apache does not error on reload. If you have a domain ready to go, set it up and test the vhost by simply adding it, and waiting for ISPman to process it, then browsing to it with a web browser. It should show a directoryindex containing no files. If problems are experienced, the main-error log for apache should be referenced for details of the problem. Apache will usually detail any critical problems on the command line when manually started or restarted.

[edit] Pure-ftpd

Pure-ftpd is the ftp server of choice for ISPman, since it takes advantage of quota support directly from the LDAP information. Pro-ftpd works as well, but is not the preferred package to use.

1. Edit the sample configuration file in /usr/local/etc/pure-ftpd.conf.sample, and save it without the .sample extension, as follows:

     LDAPConfigFile                /usr/local/etc/pureftpd-ldap.conf

2. There are a number of other configuration directives you may want to change, such as anonymous login, and you should do that before considering the installation complete. The settings here are the basic needed to get things going

3. Create the ldap configuration file detailed above, in /usr/local/etc/pureftpd-ldap.conf, as follows:

     LDAPServer localhost
     LDAPPort   389
     LDAPBaseDN o=ispman
     LDAPVersion 3

4. To start the server, use the following command: /usr/local/sbin/pure-config.pl /usr/local/etc/pure-ftpd.conf

5. The server should be set up. Test it by logging in via ftp to a virt host or user you created. Problems will show up in /var/log/messages, or on the command line when the service is started.

[edit] Perdition

Perdition is a mail proxy, with the added feature of translating addresses in variable ways. This allows the ‘customer_domain_org’ user names that are used in ISPman to become ‘customer@domain.org’ or more simply just ‘customer’, if you are only handling one domain. Perdition is a port in the mail section, but has a number of issues associated with FreeBSD.

1. The port is dependent upon gettext-old, but if you’ve installed certain newer ports that use gettext, you will have a conflict on your hands. Gettext is an internationalization tool, and may or may not be relevant at all to your system. I found that uninstalling it and installing gettext-old to comply with perdition’s needs worked without trouble.

2. ***This has been fixed with the latest FreeBSD port release. Disregard this message, unless you cannot update your ports tree to the newest release.*** There is a known FreeBSD bug relating to file and directory differentiation, that causes the default build to crash mercilessly. The solution is to install it, apply the patch found here http://article.gmane.org/gmane.mail.perdition.user/130 and then move the new ./work/perdition-1.13/perdition/perdition to /usr/local/sbin/. Then, make sure the default PID directory exists, at /usr/local/var/run/perdition/.

3. Setting perdition up on a single server or multi-server setting is simple.

  1. Single server setting:

i. Create the /usr/local/etc/perdition/perdition.conf file with the following information (note the map_library_opt line and the config in quotes following it MUST be all on one line):

 map_library /usr/local/lib/libperditiondb_ldap.so.0
 map_library_opt  "ldap://127.0.0.1/o=ispman?mailroutingaddress?sub?(uid=%25s)"
 server_ok_line
 username_from_database
 bind_address [xx.xx.xx.xx]  (the ip of the local server)
 outgoing_server [xx.xx.xx.xx] (the ip of the local server)
 outgoing_port 10143
 protocol IMAP4

ii. Reconfigure cyrus to use the new port 10143 (or any other port as specified in the perdition.conf) with the following line in /usr/local/etc/cyrus.conf:

 imap          cmd="imapd" listen="10143" prefork=0

iii. Restart cyrus, and start up perdition, and test the system with a mock email address to see if it works. Cyrus will dump errors to /var/log/messages and perdition to /var/log/maillog, for further debugging if needed

2. Multi Server Setting

i. Use the same perdition.conf file as above, and leave the cyrus.conf settings alone. Remove the outgoing_port line, and change outgoing_server to your imap host. If necessary, change the 127.0.0.1 setting for your ldap server to the applicable address.

ii. Start up perdition, and test using the current server as your IMAP host. It should relay all mail from your actual IMAP host.

4. Perdition can also run for pop3, and secure imap/pop3 as well.

1. 1. Change the protocol option in perdition.conf, you can allow the perdition instance to run in any one of these modes.
   2. For multiple protocols, you can create perdition.[protocol].conf files in /usr/local/etc/perdition for each respective protocol, containing all the information, but with different protocol (and possibly outgoing_port) options.
   3. Launch perdition by using one of the symlinks /usr/local/etc/perdition.[protocol] and the instances should coexist nicely.
   4. If you are doing a single server setup, you will need to coordinate the alternate ports in cyrus.conf and perdition.[protocol].conf to get proper forwarding.
   5. Troubleshooting:

1. If perdition starts with an error resembling “dlopen of "/usr/local/lib/libperditiondb_ldap.so.0" failed” this means it did not successfully include the OpenLDAP libraries during its make. Check your make and try again. 2. If you see instant death of the perdition instance and a message similar to “Fatal error listening for connections. Exiting.” Check for whitespace in the config file, perdition is sensitive to newlines and extra spaces in the config lines so be sure to keep it clean.