Updated January 19,2004
Suggestions to: wasson@azxws.com,
Tony Wasson
DISCLAIMER: This worked for me, your mileage may vary.
Standard disclaimers apply.
This document explains how to setup and use ISPMan to manage virtual domain and virtual email hosting on a Debian 3.0 GNU/Linux server. ISPMan is available at http://www.ispman.org
Changelog: 1/19/2004 – Cleaned up pureftpd section and some misspellings. 10/21/2003 – Updated /etc/ispman/apache.conf and Perdition steps.
Table of Contents
Running ISPMAN on Debian 3.0 Full Install Guide 1
Overview and pre-installation checklist 1
Configuring and Compiling ISPMAN 2
Overview of Cyrus Mail Server Setup 7
Overview of the process:
A) Download, configure and install ISPMan then populate LDAP.
B) Log into the ISPMan web interface and finish configuration
C) Setup ISPMan-agent with a startup script
D) Configure daemons/services to use LDAP
Choose an LDAP password. This will be needed three times, when you run “make ispman” and when you first login to your ISPMan management website.
Choose a password for the Cyrus mail system. You'll need this when you run “make ispman” and when you test Cyrus using cyradm.
If you don't have LDAP installed, install it. Don't worry about the configuration, since ISPMan will create an example config file for you to copy over later.
apt-get install libdigest-md5-perl slapd
1. Create a user called ispman and assign ownership of the /opt directory. If you have other stuff in the /opt directory, make your permissions more granular.
adduser –system ispman chown ispman /opt -R
2. Login as ispman and download the latest ispman.tar.gz to /opt. Check the home page and install the current version.
su – ispman wget http://twtelecom.dl.sourceforge.net/sourceforge/ispman/ispman-1.1.tar.gz tar zxf ispman-1.1.tar.gz
3. Go into the unpacked ispman-1.1 direcory and do a cvs update. This applies the latest bug fixes and patches.
cd ispman-1.1 apt-get install cvs cvs -z3 update -dP
4. Configure and make ISPMan.
./configure make
5. To run the web administration interface on this machine, do this:
make ispman install_ispman_common install_ispman_web
6. For a new installation ONLY, initialize LDAP.
cp /opt/ispman-someversion/tmp/conf/slapd.conf /etc/ldap/slapd.conf cp /opt/ispman-someversion/tmp/conf/schema/* /etc/ldap/schema/ /etc/init.d/slapd restart make ldif-install
7. For an existing installation, don't initialize LDAP, just copy the latest schema files over.
cp /opt/ispman-someversion/tmp/conf/schema/* /etc/ldap/schema/ /etc/init.d/slapd restart
1. Install apache-ssl
apt-get install apache apache-ssl
2. Modify /etc/apache-ssl/httpd.conf, customizing it for your domain. I prefer to access ISPMan by typing “https://ispman.yourdomain.tld”. I also like to restrict access only to certain IPs.
<VirtualHost *>
SSLEnable
ServerName ispman.yourdomain.tld
DocumentRoot /opt/ispman/htdocs
Options FollowSymlinks ExecCGI
<Directory /opt/ispman/htdocs>
Options ExecCGI
AddHandler cgi-script .cgi
DirectoryIndex index.html index.cgi
AllowOverride None
</Directory>
</VirtualHost>
3. Restart apache-ssl
/etc/init.d/apache-ssl restart
4. Modify your local hosts file or existing DNS to access the server. At ispman.yourdomain.tld. You should now be able to access ISPMAN at
https://ispman.yourdomain.tld/
If unable to access the website, check /var/log/apache_ssl/error_log and fix any wrong lines and try again.
5. From your ISPMan Management Page, click Admin, and login as an Administrator. The default username is ispman, the password is the LDAP password.
Click Configuration, make sure to setup hosts and host groups.
ISPMAN - Apache Configuration Apache stop command - /etc/init.d/apache stop Webalizer command - /usr/bin/webalizer Apache vhost file - /etc/apache/vhosts.conf Apache start command - /etc/init.d/apache start Apache graceful reload command - /etc/init.d/apache reload Default vhost IP -- * (Allows it to work on any machine) Apache reload command - /etc/init.d/apache reload ISPMAN - Mail Configuration IMAP server - cyrus Server Maps command - /usr/sbin/postmap SMTP reload command - /etc/init.d/postfix reload Map files directory - /etc/postfix Mailbox Prefix - user. DNS Config: Named Start Command - /etc/init.d/bind start Primary DNS (name) - ns1.yourdomain.tld ISPMan's DNS data directory - ispman/ Primary Mail Server (name) - mail.yourdomain.tld Named data directory - /var/named Secondary Mail Server (IP) - xxx.xxx.xxx DNS Backend - bind8 Secondary DNS (IP) - xxx.xxx.xxx.xxx Reverse Zone directory - rev/ Header file for named.conf - /opt/ispman/templates/named.conf.header Named Reload Command - /etc/init.d/bind reload Footer file for named.conf -/opt/ispman/templates/named.conf.footer Named Stop Command - /etc/init.d/bind stop Secondary Zone directory - sec/ Named Config File -/etc/named.ispman.conf Primary DNS (IP) - xxx.xxx.xxx.xxx Secondary Mail Server (name) - mail2.yourdomain.tld Secondary DNS (name) - ns2.yourdomain.tld Primary Mail Server (IP) - xxx.xxx.xxx.xxx Catch all CNAME - none Primary Zone directory - pri/ Hostmaster's email address - hostmaster.yourdomain.tld Named User - root
Set up additional ISPMan users if desired.
1. Install daemontools
apt-get install daemontools-installer
when asked DO make the /service directory
2. Create /etc/ispman directory
mkdir /etc/ispman
3. Create a run script for daemontools called /etc/ispman/run:
#!/bin/sh echo Starting ispman agent exec /opt/ispman/bin/ispman-agent nodetach
4. Make the run script executable and link /etc/ispman to the /service directory. This allows daemontools to “watch” the process. If it ever dies, daemontools will execute the run script.
chmod +x /etc/ispman/run ln -s /etc/ispman /service/
5. I prefer my logs to all be accessible from /var/log so I did this:
ln -s /opt/ispman/var/ /var/log/ispman/
6. I also prefer all my processes to be controlled by /etc/init.d/ scripts, so I made a script called /etc/init.d/ispman-agent like so:
#!/bin/sh
# * svc -h /service/yourdaemon: sends HUP
# * svc -t /service/yourdaemon: sends TERM and restarts
# * svc -d /service/yourdaemon: sends TERM and leaves it down
# * svc -u /service/yourdaemon: brings the service back up
# * svc -o /service/yourdaemon: runs the service once
daemon="/service/ispman"
process="ispman"
name="ispman-agent"
case "$1" in
start)
echo -n "Starting $name:"
svc -u $daemon
echo " started"
ps aux | grep $process
;;
stop)
echo -n "Stopping $name:"
svc -d /service/ispman
echo " stopped"
ps aux | grep $process
;;
restart|force-reload)
echo -n "Restarting $name:"
svc -t $daemon
echo " restarted"
;;
reload)
echo -n "Reloading $name:"
svc -h $daemon
echo " reloaded"
;;
status)
echo -"Getting Status... Jobs in queue: "
/opt/ispman/bin/ispman.processes -h $HOSTNAME
;;
*)
echo 'Usage: /etc/init.d/ispman {start|stop|restart|force-reload|reload|status}'
exit 1
esac
exit 0
NOTE: I had to edit /opt/ispman/bin/ispman.processes and tell it the
ispman/lib path. That was probably just my own problem, several other people said 0.9.7 worked fine for them. MORAL: Don't touch it is it ain't broke.
7. Make /etc/init.d/ispman-agent executable, and start ispman-agent.
chmod +x /etc/init.d/ispman-agent /etc/init.d/ispman-agent start
Next, check the logs in /var/log/ispman/ to see whats happening.
The biggest problem with agents not completing tasks is a non-matching hostname.
8. Set the script to autostart, in case the machine is ever rebooted. This adds ispman-agent to Debian's startup scripts.
update-rc.d ispman-agent defaults 98
NOTE: Each machine in a hostgroup should have “ispman-agent” installed. You can follow the above steps, skipping the ISPMan Web steps.
This provides basic security for LDAP using tcpwrappers. You can supplement this with LDAP ACLs and iptable rules.
1. You should limit access to your LDAP directory atleast to the IP level. Edit /etc/hosts.allow and add IP addresses of the servers that need remote LDAP access.
slapd: XXX.XXX.XXX.XXX 127.0.0.1 : ALLOW
NOTE: YOU MUST HAVE A NEWLINE AFTER YOUR ENTRIES OR THEY WON'T WORK.
2. Deny all other machines access by making /etc/hosts.deny look like so:
slapd: ALL : DENY
3. Verify this works by using ldapsearch locally and from a remote machine not in the allowed file. (requires ldap-utils package)
ldapsearch -xvu -LLL -b "o=ispman" ispmanVar=*
This basically allows any daemon using PAM for authentication to use LDAP. Some programs like Cyrus don't authenticate directly from LDAP without patches. This lets them 'ask' PAM for authentication. PAM then queries LDAP and returns the answer in an understandable way.
1. Install PAM_LDAP. The default options are fine, we'll edit the config file directly.
apt-get install libpam-ldap
2. Setup /etc/pam_ldap.conf something like this:
host 127.0.0.1 base o=ispman ldap_version 3
I recommend you install Cyrus 2.1 along with Perdition. Cyrus 2.1 includes SSL support and sieve mail sorting. I've left the steps for Cyrus 1.5 for reference, but I'm not updating them.
1. Add these line to /etc/apt/sources.list
#Cyrus21 Backports deb http://people.debian.org/~hmh/woody/ hmh/cyrus/
2. Update and install Cyrus2.1
apt-get update apt-get install cyrus21-pop3d cyrus21-common cyrus21-imapd \ cyrus21-admin cyrus21-admin cyrus21-clients cyrus21-doc gawk \ libcyrus-imap-perl21 libsasl2 libsnmp-base libsnmp4.2 \ sasl2-bin libsasl2-modules libsasl2 sasl2-bin
NOTE: You could use just libsasl2-modules-plain instead of libsasl2-modules but it had dependency problems when I tried it.
3. Setup /etc/imapd.conf. This setups an admin, uses SASL for password authentication and sets us up to support SSL/TLS.
admins: cyrus popminpoll: 0 allowplaintext: yes sasl_minimum_layer: 0 sasl_mech_list: plain login sasl_pwcheck_method: saslauthd lmtp_downcase_rcpt: yes tls_ca_file: /etc/ssl/cyrus.pem tls_cert_file: /etc/ssl/cyrus.pem tls_key_file: /etc/ssl/cyrus.pem
4. Edit /etc/cyrus.conf and make sure IMAP and POP3 are listening.
imap cmd="imapd -s -U 30" listen="imap" prefork=0 maxchild=100 pop3 cmd="pop3d -U 30" listen="pop3" prefork=0 maxchild=50
5. Create SSL key and pem file for cyrus
openssl req -new -nodes -out req.pem -keyout key.pem openssl rsa -in key.pem -out new.key.pem openssl x509 -in req.pem -out ca-cert -req \ -signkey new.key.pem -days 999 mv new.key.pem /etc/ssl/cyrus.pem cat ca-cert >> /etc/ssl/cyrus.pem chown cyrus.mail /etc/ssl/cyrus.pem chmod 600 /etc/ssl/cyrus.pem
6. Setup IMAP and POP PAM files. This lets the authentication go Cyrus to SASLAUTHD to PAM_LDAP. The files are imap pop in /etc/pam.d.
auth sufficient pam_ldap.so account sufficient pam_ldap.so
7. Add cyrus to the sasl group
adduser cyrus sasl
8. Make saslauthd use PAM by modifying /etc/default/saslauthd
start=yes MECHANISMS="pam"
NOTE: I've seen configs where saslauthd goes straight to LDAP.
The example I followed didn't work, so I stuck with pam. YMMV.
9. Restart saslauthd and cyrus
/etc/init.d/cyrus21 restart /etc/init.d/saslauthd restart
10. Test the setup by doing this:
#cyradm --user cyrus localhost localhost password: localhost> lm
If you don't get a hostname> prompt, check the syslog for errors. Verify LDAP is running. If you have other SASL mechnanisms installed, you may need to use “cyradm --auth plain –user cyrus localhost”.
THEN the ultimate: Create a domain with an email user and verify! Commit the session and verify that the Process list is empty before continuing. If processes stay in the queue, verify the machine's hostname and make sure you have at least 1 host in the mailserver group.
telnet localhost 110 USER someuser_domain_com PASS password LIST
1. Configure /etc/imapd.conf. I change the popminpoll since POP users complained when they got the error message from Cyrus. Make sure you have atleast 1 admin setup, never EVER use that account to read mail.
popminpoll:0 admins: cyrus
2. Make sure there is a system user named cyrus. This is for permissions on the mail spool.
adduser --system cyrus
3. Configure pwcheck to use PAM.
update-alternatives --config pwcheck
choose #2 /usr/sbin/pwcheck_pam
NOTE: Unless you stop pwcheck before this step, restarting it will leave you with the old pwcheck_standard running. I do a killall pwcheck after this step for good measure.
4. Configure PAM rules for cyrus. Edit /etc/pam.d/cyrus so it says:
auth sufficient /lib/security/pam_ldap.so account sufficient /lib/security/pam_ldap.so
5. Test it! sample test for cyrus 1.5:
cyradm -u cyrus localhost localhost password: <--- compile time cyrus password localhost> lm <-- lm shows installed mailboxes
If you get anything but a hostname> prompt, check the syslog and auth.log for errors. Verify that pwcheck_pam is really running. Permission problems in /var/lib/cyrus or /var/spool/cyrus can 'block' a cyradm session. If you are still stuck, try strace'ing a pwcheck agent and see what it spits out.
Perdition allows your users to use user@domain.com or user_domain_com as user names for POP, and IMAP to Cyrus. This is needed because Cyrus doesn't allow @ in account names, so ISPMan uses '_'. Larger ISP's will have Perdition on separate server, as a IMAP/POP multiplexer. Smaller ISPMan installations can still benefit from Perdition by installing it on the same machine. Perdition can also be used to help migrate existing email user by adding or stripping off parts of the user name. However, that is outside the scope of what we're doing.
1. If running ISPMan 1.0 or higher, otherwise, you should upgrade or read the archives on patching the older version.
2. Make sure you have access to your LDAP server(s)
You may have to edit tcpwrappers (/etc/hosts.allow), iptables/ipchains or other firewall rules depending on your security setup.
3. Verify the LDAP server is reachable, something like this works well
ldapsearch -xvu -h 127.0.0.1 -LLL -b "o=ispman" ispmanVar=*
4. Install perdition
You can use packages for your distribution, or compile from source available from: http://www.vergenet.net/linux/perdition/download/
apt-get install perdition perdition-ldap
5. Configure Perdition
Keep in mind that your map_library file may be in a different location. When you “go live” you should have multiple LDAP servers. As long as they are all on standard ports, set these up on the map_library_opt line.
A basic /etc/perdition/perdition.conf looks like so:
map_library /usr/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
A single domain setup config file will probably look more like
map_library /usr/lib/libperditiondb_ldap.so.0 # The following map_library_opt line needs to be on a single line # Customize the @azxws.com to match your domain. map_library_opt “ldap://127.0.0.1//o=ispman?mailroutingaddress?sub?(uid=%25s@azxws.com)" server_ok_line username_from_database
A multi-LDAP server config file will probably look more like :
map_library /usr/lib/libperditiondb_ldap.so.0 # The following map_library_opt line needs to be on a single line map_library_opt “ldap://127.0.0.1 192.168.2.10 192.168.3.10 \ /o=ispman?mailroutingaddress?sub?(uid=%25s)" server_ok_line username_from_database
6. Make sure Perdition starts on boot up and start it manually now.
/etc/init.d/perdition start
7. Verify the account and password are correct by logging in directly
against the mail server. I usually do something like this against my Cyrus mail server:
telnet localhost 110 USER user_domain_com PASS thepassword
Then I repeat these steps using the Perdition proxy. If it fails, check the logs (perdition uses syslog). You may also use a system debugger (like strace) and a network sniffer to verify LDAP is functioning. I have also had good success setting an outgoing_server in perdition.conf as a debugging measure
Once you have underscore names working, use the user@domain.com name through Perdition. Voila! It works...
On a side note, you'll most likely want to setup postfix to do SMTP authentication. It's pretty easy to get PLAIN and LOGIN working. If you want other mechanisms, you'll need to work harder. Remember, since there are two UIDs, either user@domain.com and user_domain_com works.
1. Install Bind8
apt-get install bind
2. Add this line to /etc/named/named.conf:
include "/etc/named.ispman.conf";
NOTE: The ; at the end is critical, without it the logs will say:
/etc/bind/named.conf:67: parse error near
3. Make sure bind is looking in the right place for the zone files. I ended up linking /etc/bind with /var/named, since ISPMan was mad when I tried using /etc/bind during my original install. This should no longer be an issue, but this is what I had to do.
ln -s /etc/bind/ /var/named
4. Reload bind and check the logs, it should be happy.
/etc/init.d/bind reload
NOTE: You can force DNS updates by running ispman.ldap2named
1. Install apache
apt-get install squirrelmail apache apache-ssl
2. Setup apache for ISPMan hosting by editing httpd.conf add adding a section like this:
UseCanonicalName Off NameVirtualHost * #this is where ispman-agent adds vhosts Include /etc/apache/vhosts.conf
NOTE: With UseCanonicalName Off the server name comes from the contents of the Host: header in the request.
3. Make sure /etc/apache/vhosts.conf exists. 'touch' it if it doesn't exist.
4. Restart apache and make sure the logs are clean.
/etc/init.d/apache restart
NOTE: You can force an update by running ispman.ldap2apache. I have run into bugs where a vhost would still not update and so I erased the vhosts.conf.hash and then ran ispman.ldap2apache
NOTE: postfix-snap packages are postfix 2.0 and some config options have changed, this setup is for plain 2) Edit /etc/pam.d/smtpd like so:postfix
1. Install Postfix with TLS and LDAP support.
apt-get install postfix-ldap postfix-tls libsasl-modules-plain
2. Edit /etc/pam.d/smtpd like so:
auth sufficient pam_ldap.so account sufficient pam_ldap.so
3. Setup the Postfix to SASL for SMTP Authentication.
mkdir /etc/postfix/sasl
4. Create /etc/postfix/sasl/smtpd.conf like so:
pwcheck_method: pam
5. Edit /etc/postfix/master.cf
Make sure smtpd is NOT chrooted -- This lets it do SMTP Auth.
WARNING: SMTP Authentication is an addon to postfix, it does decrease the overall security. You have been warned.
6. Create TLS cert and key in /etc/postfix
openssl req -new -x509 -nodes -out cert.pem chown root.postfix *.pem chmod 640 *.pem
7. edit /etc/postfix/main.cf using the example in build/install-data/examples/postfix_configuration/main.cf.reasonable with these exceptions:
mailbox_transport=cyrus # NOTE: myorigin MUST match the maildrop hostname in ISPMan. myorigin = /etc/mailname #These options gave me trouble, I am not a guru so I commented them out. #relocated_maps = hash:/etc/postfix/relocated #smtpd_sender_restrictions = hash:/etc/postfix/access # SMTP Auth Stuff see http://killyridols.net/postfixtlssmtpauth.shtml smtpd_sasl_auth_enable = yes smtpd_sasl_security_options = noanonymous smtpd_sasl_local_domain = $myhostname smtpd_recipient_restrictions = permit_sasl_authenticated, check_relay_domains #For STARTTLS SMTP smtpd_tls_cert_file = /etc/postfix/cert.pem smtpd_tls_key_file = /etc/postfix/privkey.pem smtpd_use_tls = yes tls_random_source = dev:/dev/urandom tls_daemon_random_source = dev:/dev/urand
8. Test it using telnet.
$telnet localhost 25
You should see something like:
Connected to 10.98.76.54 Escape character is '^]'. 220 test.somewhere.com ESMTP Postfix
If postfix drops the connection, read syslog. Most of my install problems are with SMTP auth settings, try commenting that out and restarting if postfix components are dying. Also ensure that your pam files are correct and that smtpd is NOT in a chroot environment.
LMTP can speed up stuff, you can set that up if you like.
Proftpd doesn't support the ISPMan LDAP space quotas or denied users so we run pure-ftpd-ldap. PureFTPD 1.2 is also reported to work.
1. Install pureftpd, I used a backport listed on apt-get.org. This went in /etc/apt/sources.list:
#PureFTPd deb http://pureftpd.sourceforge.net/debian/woody/ . Then I updated and installed: apt-get update apt-get install pure-ftpd-ldap
2. Configure /etc/pure-ftpd.conf to enable LDAP. I changed these 2 lines. Yes, you could also run this through PAM_LDAP.
LDAPConfigFile /etc/pureftp-ldap.conf #PAMAuthentication yes
3. Setup the LDAP config file, in this case /etc/pureftpd-ldap.conf . In the past I had used a uid filter, pureftpd complained when I did that with this release, so my config is simpler.
LDAPServer localhost LDAPPort 389 LDAPBaseDN o=ispman
4. Create a domain and make sure FTP access is enabled.
5. Restart pureftpd and test:
/etc/init.d/pureftpd restart
ftp localhost
USER www.domain.com
PASS password