2006-11-14 Haefelfinger Philipp philipp.haefelfinger@syscp.org Brand Ron ron.brand@syscp.org Aders Florian florian.aders@syscp.org 2005 2006 SysCP This work is licensed under the Creative Commons Attribution-Noncommercial-Share Alike 2.0 Germany License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/2.0/de/ or send a letter to Creative Commons, 543 Howard Street, 5th Floor, San Francisco, California, 94105, USA. 1 2005-07-17 First rewrite completed 1.1 2005-07-18 Translation completed / Completed Part of Postfix-MySQL connection 1.2 2005-09-22 Added 2 basic php-packages to the packagelist 1.3 2006-09-13 Converted the HowTo into LaTeX 1.4 2006-09-20 Rearrangement for the use with SysCP 1.2.14 1.5 2006-11-10 Converted into DocBook 1.6 2006-11-14 Added hint about ini_restore, inserted the cronscript and added licensing-information

Welcome to the installation - process for the SysCP server-management-tool. You have chosen a powerful tool with a very small need of resources. Just execute the commands we show you in this HowTo and you should be happy. If problems occur, ask in our IRC channel or visit our forum. Do yourself a favour and use the powerful search function before asking any question. The results you get might be more efficient than a single question about a particular problem.

In this HowTo, we used the following basic naming conventions: Commands executed as root: syscp ~ # /execute/this/command Commands executed as a specific user: vmail@syscp $ /execute/this/command/as/user/vmail Output of various programs: I am the echo of a normal command, executed in a shell Content of a file:# The following sets the variable PATH to a useless value PATH=/dev/nullFilenames: /etc/apache/httpd.conf Variable names: $iamavariable

It is essentially to be familiar with your Linux-Environment. You might encounter situations, where you definitely need a shell. If you wish to install your server according to this HowTo it is advisable to consult and understand the basics of networking, DNS and - of course - Linux itself. You don't need to know every detail of your mail system already, this will be discussed here in this HowTo. Should you, however, have no experience at all how to operate a server which is connected to the Internet, we strongly recommend the usage of a test-environment. A wrongly configured server is a target for all kind of attack and misuse. This HowTo requires also basic-knowledge about the MySQL database server. Installation and configuration will not be discussed here. Last but not least you need to know basics about your apache webserver, without this basic knowledge you wont be able to configure your SysCP setup, and the software might not function properly. Every admin should be aware what kind of software is running on his/her system. Please keep in mind one basic thing: The best admintool can never replace a good administrator

To perform a successful installation of SysCP it is assumed to have a minimal Debian Sarge up and running. A discussion about how to install Linux itself will not take place here. Certainly there are enough good HowTos available elsewhere and are misplaced here. In addition a MySQL database is needed too. Likewise there are good HowTos for helping you to install MySQL.

In Debian Sarge the following softwarepackages will be needed. To make sure that all dependencies will be resolved, you must edit the file /etc/apt/sources.list. The following line needs to be inserted in /etc/apt/sources.list:deb http://debian.syscp.de/ sarge/It should look like this afterwards (you can find this in our F.A.Q. as well). Of course you can edit it to fit your needs.deb ftp://ftp.debian.de/debian sarge main deb-src ftp://ftp.debian.de/debian sarge main deb ftp://ftp.debian.de/debian-non-US sarge/non-US main deb-src ftp://ftp.debian.de/debian-non-US sarge/non-US main deb http://security.debian.org/ sarge/updates main deb-src http://security.debian.org/ sarge/updates main deb http://debian.syscp.de/ sarge/Once this line was added run the command syscp ~ # apt-get update to make sure that the internal database of the debian package maintainer is up to date with the latest package information. Please note: Debian will resolve all dependencies automatically! This is helpful, you do not need to install every single package manually. Now you are almost ready to start installation. We should check next if exim4 is installed which we need to remove, since SysCP depends on postfix (Note: most installations of Sarge include the exim4 by default). If exim4 is installed on your system please run the code syscp ~ # apt-get remove --purge exim4-base which will remove the exim4 mail-system completely from your server. Finally you are ready to run the command syscp ~ # apt-get install syscp Most package dependencies might be cleared after that. Special packages for special tasks must be installed manually e.g. courier-imap-ssl. postfix postfix-mysql postfix-tls (for crypted SMTP-Auth) mysql-client mysql-server mysql-common courier-authdaemon courier-authmysql courier-maildrop courier-pop (non-crypted POP3 access) courier-pop-ssl (SSL-secured POP3 access) courier-imap (non-crypted IMAP access) courier-imap-ssl (SSL-secured IMAP access) courier-ssl libsasl2 (the Cyrus SASL library) libsasl2-modules libsasl2-modules-sql spamassassin clamav clamav-daemon apache apache-common apache-utils libapache-mod-php4 libapache-mod-ssl php4 php4-mysql php4-common php4-cli bind9 bind9-host proftpd proftpd-mysql syscp openssl (SSL-library) unzip (Pack program) unarj (Pack program) phpmyadmin (Webadmin for MySQL) dpkg-dev (for compiling Maildrop) Most configuration files of the services might be already existing and don't have to be created. They might have been created during the install process of the service, and will be good enough for a default setup. WARNING: Do NOT use any Microsoft-Windows editor for editing configuration files, they might become corrupt due to wrong line-breaks. If working with windows, use an editor that can save files in Unix/Linux format. Before we start the configuration-process let's have a thought of how we organize our data. Mostly important is the directory where you store data of your customers. SysCP suggests /var/kunden (english/international users might want to use /var/customers). After all its up to you how you name this directory, but it's important that you know that now since the whole configuration and file-structure will be based on this. IMPORTANT: The configuration-files shown here are not complete. Most settings you learn here were done by the author in addition to those settings which will be generated by SysCP. You can find a complete list of all configuration files on the page "Configuration" in the SysCP - administration panel. These files can be used as a template, keep in mind that you have to adjust them according to your own needs. It will be much easier for you, to follow the templates suggested in this HowTo. In order to be able to configure SysCP we need the apache-webserver up and running. A default setup is recommended. For further help refer to the apache documentation or the apache2.conf itself, where all sections have detailed comments. The following adjustments - if not performed already - should be observed. Open the file /etc/apache/httpd.conf in your favourite editor (vim, nano, mc, etc.) and set the following values:[...] Listen <your-ip> [...] BindAddress <your-ip> or 0.0.0.0 [...] ServerAdmin <your email-address> [...] ServerName <your servername> (e.g.: root-server-142-175.your-provider.tld) [...] # Uncomment the following values AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phpsServerName should always be the official name given by your provider. This will ensure that all the domains you might want to host can be managed with one tool: SysCP. Save the file and leave your editor. Please note: Due to some security-issues inside PHP, a customer can disable open_basedir and / or safe_mode, if it's disabled in your php.ini. The function used for this is called ini_restore. To prevent these attacks, you can disable this function in your php.ini:disable_functions = ini_restoreNow you can restart the Apache-Server syscp ~ # /etc/init.d/apache restart Further it will be possible to have initial setup with SysCP by using the IP-address / provider name of the server. We type the following URL in the browser http://<YOUR-IP>/syscp. This URL results from the pre-installation of SysCP in the directory /var/www/syscp, since Apache points to /var/www by default. The first message will guide you through a link directly to the install-dialog and hopefully you will get the message in your browser: "You have to configure SysCP first!" Click on "configure". Here you go: you will be prompted to the installscreen of SysCP. The SysCP-installer As you will notice, the screen is already filled with some default values. It is recommended to leave most default values. Eventually you have to adjust the "Servername" according to your FQDN. Make your personal entries in the password fields and click "next". Note: in case the entries are missing/incorrect you will get a red "reminder". If all went fine you will get the message shown below from the installer and you are ready for the first login. Successful installation of the panel Hint: All following configuration-files can be generated by SysCP and shown on the webfrontend. Click "Configuration" in the main-menu and choose from "Debian Sarge" the daemon you wish to configure. You will realize, with a few exceptions all files in this HowTo are identical. First duty after login are the "Settings", it will make it a bit easier to create and edit the configuration files. SysCP uses this settings to create the templates of the configfiles. The following entries are quite important, errors will lead into malfunction. Here you have 2 of these important settings: the top of the path, in which the homepage of each users will reside, and the directory of the logfiles. In the logdirectory all logfiles generated by apache will be stored. For each website there is at least one webXY-access.log and one webXY-error.log where informations and errors are recorded. Be sure to fill in this two fields correctly. These IDs inform you which system account the mails will belong to after delivering. Normally this will be the user vmail. Should this user already exist on your system, the userid (UID) and groupid (GID) needs to be adjusted in order to match the correct user, otherwise you can freely use 2000. Here the directory for mail-deliverance will be set. Please note that this directory must be owned by the user vmail and the group vmail. The user vmail appears with the same UID and GID like the above mentioned informations about mailuser. Honestly, the sender-variable is not that important. Nevertheless it should be checked and changed according to your needs. It won't look quite professional if a welcome-mail from SysCP carries an address like info@example.org. Although SysCP will suggest a name, most users might use their special address. Now we will enter the most important section of your SysCP installation. We will configure the daemons which do all the hosting-work. To guarantee a smooth operation of all websites and domains, apache needs to be instructed precisely. This is realized through the file /etc/apache/vhosts.conf. Apache also must include this file in its configuration file /etc/apache/httpd.conf. Open the file /etc/apache/httpd.conf with your editor (vim, nano, mc, etc.) and at the very end - if not yet existing - type in the following:Include /etc/apache/vhosts.confSave and exit the editor. Of course this newly included file must exist. We will use the command touch. syscp ~ # touch /etc/apache/vhosts.conf The file vhosts.conf is automatically maintained by SysCP whenever domains and other apache relevant informations are added/changed. You might ask why there is no editing of the line with NameVirtualHost. SysCP will maintain this entry too in the vhosts.conf. Next, create directories of the customers. You can use the following commands: syscp ~ # mkdir -p /var/kunden/webs/ syscp ~ # mkdir -p /var/kunden/logs/ It is time now to restart apache: syscp ~ # /etc/init.d/apache restart Eventually there is a warning that an IP has no virtual host. This message will disappear after the creation of the first domain. We will now configure the nameserver, so that it will create entries of the domains automatically. The steps are like this: Open the file /etc/bind/named.conf in your editor and add the line following line at the end:include "/etc/bind/syscp_bind.conf";To avoid errors we have to create this file, otherwise bind would not start: syscp ~ # touch /etc/bind/syscp_bind.conf The standard-zonefile for all SysCP domains must be created, perform the command: syscp ~ # touch /etc/bind/default.zone Thereafter open the file /etc/bind/default.zone with your editor. Add this content:$TTL 1W @ IN SOA ns root ( 2004060501 ; serial 8H ; refresh 2H ; retry 1W ; expiry 11h) ; minimum IN NS ns IN NS nsX.provider.com. IN NS nsY.provider.com. IN MX 10 mail IN A <your-ip> IN MX 10 mail * IN A <your-ip> IN MX 10 mail ns IN A <your-ip> mail IN A <your-ip> IN MX 10 mailPlease replace <YOUR-IP> with the IP-address of your server. The entries for the secondary nameserver must be inserted, too. In the above example they are marked as ns[X|Y].provider.com. Attention: The dot "." on the end of these lines is mandatory. Otherwise this entry will be treated as a subdomain. The dot marks the URL as completed. Above inserted secondary DNS-server need the privileges for transferring the zones onto their own host. To enable this, we must insert the option allow-transfer in the following file. All IP-addresses of the servers are stored there. /etc/bind/named.conf.options or /etc/bind/named.conf section options:[...] allow-transfer { 12.34.56.78; 12.34.57.89; }; [...]To complete the nameserver setup we will restart bind with this command: syscp ~ # /etc/init.d/bind9 restart The nameserver is now configured and ready to use. The further settings will be done by the SysCP cronjob. Edit the file /etc/proftpd/proftpd.conf according to the sample on the SysCP webfrontend and make it identical. In the following listing are a few personal options, added to the SysCP template by the author. /etc/proftpd/proftpd.conf[...] <Global> # chroot all users DefaultRoot ~ # Reject rootlogin (just for security) RootLogin off # No need to require valid shell, because user is virtual RequireValidShell off </Global> <IfModule mod_delay.c> DelayEngine off </IfModule> [...]To ensure that ProFTPd is working with the MySQL-database, please verify that "LoadModule mod_sql_postgres.c" is commented out ("#LoadModule mod_sql_postgres.c") in the file /etc/proftpd/modules.conf. Otherwise ProFTPd will refuse logins. Restart your ProFTP-Server as follows: syscp ~ # /etc/init.d/proftpd restart The configuration of your FTP-Server is finished. From now on ProFTPD will verify the logins with the MySQL-database. To enable TLS-Mode on your FTP-Server two things need to be done. First you need a certificate, which is needed to establish a crypted connection. It can be created easily using this command: syscp ~ # openssl req -new -x509 -days 365 -nodes -out /etc/ssl/certs/proftpd.cert.pem -keyout /etc/ssl/certs/proftpd.key.pem For more Information regarding SSL and TLS please visit: http://www.chimera.ch/download.php?view.4. After creating the certificate we must adjust the configuration of ProFTPd. /etc/proftpd/proftpd.conf# Uncomment this if you would use TLS module: TLSEngine on TLSLog /var/log/ftp_tls.log TLSProtocol SSLv23 TLSOptions NoCertRequest TLSRSACertificateFile /etc/ssl/certs/proftpd.cert.pem TLSRSACertificateKeyFile /etc/ssl/certs/proftpd.key.pem TLSVerifyClient off # Uncomment the following line to force tls-login #TLSRequired onMeanwhile it should be understandable for you, to restart a service after changing its configuration to let the changes become effective. Lets do this now, you will be able to establish a FTP-connection via TLS: syscp ~ # /etc/init.d/proftpd restart It is not very wise to create a cronjob to manipulate services which are not configured yet. Therefore we waited until this point, to ensure a stable configuration before the cronjob will start its powerful duty. We will now hand over the configuration stored in the database to each service. Like mentioned earlier, the cronjob of SysCP is a key-feature, it will take care of the involved configuration files. On the SysCP Main page choose Configuration -> Debian Sarge -> Crond (cronscript). Create the here mentioned file /etc/php/syscpcron/php.ini and copy the shown content in the newly created file (note: the file needs to have an empty line at the very end).# # Set PATH, otherwise restart-scripts won't find start-stop-daemon # PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin # # Regular cron jobs for the syscp package # */5 * * * * root /usr/bin/php -q -C /etc/php/syscpcron /var/www/syscp/scripts/cron_tasks.php 0 0 * * * root /usr/bin/php -q -C /etc/php/syscpcron /var/www/syscp/scripts/cron_traffic.php 10 0 * * * root /usr/bin/php -q -C /etc/php/syscpcron /var/www/syscp/scripts/cron_traffic_report.php Repeat this step for /etc/cron.d/syscp. The usual restart will restart the cron-daemon and update the configuration. syscp ~ # /etc/init.d/cron restart Again: congratulations! The first huge part of your SysCP configuration is complete. Take a break for the second part to perform. First let us perform some commands in a shell to create a base for postfix and SASL. If not yet existing create the following directories: syscp ~ # mkdir -p /etc/postfix/sasl syscp ~ # mkdir -p /var/spool/postfix/etc/pam.d syscp ~ # mkdir -p /var/spool/postfix/var/run/mysqld Attention: Make sure that there is NO whitespace at the end of the configuration files. Otherwise it will be added to the path or the value of the setting and you get disastrous results. The same warning applies, when it comes to edit these files using file editors on Windows Systems (e.g. notepad.exe). This editors related to the DOS-world write <CR><LF> instead of <LF> on each end of a line, which is sometimes (and this is the bad news) unable to understand by a Unix-related System like Linux. The configuration files of postfix are one of those where you strictly need a Unix-conform editor editing them. To let postfix gain access to the MySQL database and its content we need the following configuration-files: /etc/postfix/main.cf /etc/postfix/mysql-virtual_alias_maps.cf /etc/postfix/mysql-virtual_mailbox_domains.cf /etc/postfix/mysql-virtual_mailbox_maps.cf Authors Note: the two files below will not be created by the official SysCP installation. However, the author likes to suggest to make usage of these files, since they are present in the database and won't harm anything. Therefore the postfix-configuration discussed here is slightly different from the one SysCP uses. Should you prefer the original SysCP version, go ahead! Just skip these 2 files, but in this case keep in mind to set virtual_uid_maps and virtual_gid_maps in main.cf on static. /etc/postfix/mysql-virtual_uid_maps.cfuser = syscp password = MYSQL_PASSWORD dbname = syscp table = mail_users select_field = uid where_field = email hosts = 127.0.0.1/etc/postfix/mysql-virtual_gid_maps.cfuser = syscp password = MYSQL_PASSWORD dbname = syscp table = mail_users select_field = gid where_field = email hosts = 127.0.0.1Let us now configure main.cf. You will notice the difference to the original SysCP version. Remark: You should avoid to set $myhostname and $mydomain to the IP of the server or a domain maintained by SysCP. You might experience difficulties upon mail delivery. It is a good idea to use the name of the server given from the provider (e.g. srv-lnx-XY.provider.tld) Whenever available use that name. /etc/postfix/main.cf# daemon configuration command_directory = /usr/sbin daemon_directory = /usr/lib/postfix program_directory = /usr/lib/postfix [...] # Virtual Mailbox settings virtual_mailbox_base = /var/kunden/mail/ virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual_mailbox_maps.cf virtual_mailbox_domains = mysql:/etc/postfix/mysql-virtual_mailbox_domains.cf virtual_alias_domains = virtual_alias_maps = mysql:/etc/postfix/mysql-virtual_alias_maps.cf virtual_uid_maps = mysql:/etc/postfix/mysql-virtual_uid_maps.cf #virtual_uid_maps = static:2000 virtual_gid_maps = mysql:/etc/postfix/mysql-virtual_gid_maps.cf #virtual_gid_maps = static:2000 # use this for virtual delivery / for usage without Maildrop virtual_transport = virtual #use this for maildrop-delivery / for usage with Maildrop #virtual_transport = maildrop [...] # TLS Mode for SMTP-service smtp_use_tls = yes smtp_tls_note_starttls_offer = yes smtpd_use_tls = yes smtpd_tls_key_file = /path/to/smtpd.pem smtpd_tls_cert_file = /path/to/smtpd.pem smtpd_tls_CAFile = /path/to/smtpd.pem smtpd_tls_loglevel = 0 smtpd_tls_received_header = yes smtpd_tls_session_cache_timeout = 3600s tls_random_source = dev:/dev/urandom smtpd_sender_restrictions = permit_mynetworks, permit_sasl_authenticated, reject_unauth_destination, reject_unknown_sender_domain, reject_non_fqdn_sender, reject_unknown_client, reject_non_fqdn_hostname Since we do not have system users but virtual users (stored in the database), the mail system needs a systempartner to "talk to". The mail system needs a system account under which the system itself can be executed. Here we go: syscp ~ # groupadd -g 2000 vmail syscp ~ # useradd -u 2000 -g vmail vmail syscp ~ # mkdir -p /var/kunden/mail/ syscp ~ # chown -R vmail:vmail /var/kunden/mail/ Note: The system user vmail will have it's home directory set to the SysCP mail directory. Following the standard installation we have this directory: /var/kunden/mail. SASL is easy to handle. It is used by postfix as an interface to MySQL by the time SMPT-Auth is needed. There is just one configuration file to create: /etc/postfix/sasl/smtpd.confpwcheck_method: auxprop auxprop_plugin: sql mech_list: plain login cram-md5 digest-md5 sql_engine: mysql sql_hostnames: localhost sql_user: syscp sql_passwd: MYSQL_PASSWORD sql_database: syscp sql_select: select password from mail_users where email='%u@%r' Again, ATTENTION to avoid whitespaces at the end of the file. Also courier is extremely sensitive for this kind of type errors. Below you find the configfiles for courier-pop and courier-imap. /etc/courier/authdaemonrc[...] authmodulelist="authmysql" [...]Courier daemons need to be instructed to have permission to start. /etc/courier/imapd[...] ##NAME: IMAPDSTART:0 # # IMAPDSTART is not used directly. Rather, this is a convenient flag to # be read by your system startup script in /etc/rc.d, like this: # # . ${sysconfdir}/imapd # # case x$IMAPDSTART in # x[yY]*) # /usr/lib/courier/imapd.rc start # ;; # esac # # The default setting is going to be NO, so you'll have to manually flip # it to yes. IMAPDSTART=YES/etc/courier/pop3d[...] ##NAME: POP3DSTART:0 # # POP3DSTART is not referenced anywhere in the standard Courier programs # or scripts. Rather, this is a convenient flag to be read by your system # startup script in /etc/rc.d, like this: # # . /etc/courier/pop3d # case x$POP3DSTART in # x[yY]*) # /usr/lib/courier/pop3d.rc start # ;; # esac # # The default setting is going to be NO, until Courier is shipped by default # with enough platforms so that people get annoyed with having to flip it to # YES every time. POP3DSTART=YES/etc/courier/authmysqlrc (Configfiles -> Debian Sarge -> Courier) is used by the authdaemon to get access to the MySQL database. Are no errors present, you have your mail system and the complete SysCP installation ready to use.

Finally! SysCP is installed and fully functional. At this point I wish you much fun with your server and SysCP. The huge amount of feedback that I received was quite unexpected. To be honest, it is exactly that point that made me going, especially critical comments. It also proved the wide usage of this document. No doubt that I am still encouraged to extend, maintain and improve this HowTo. I would like to thank the whole SysCP-community for suggestions, bugfixes and requests. Most suggestions were added to this document.

This HowTo was originally written by Philipp Haefelfinger. His "Thanks a lot" goes to some persons: Ron Brand for joining many times into discussions, and the English translation of this HowTo. Martin Burchert for countless assistance on many topics. This HowTo was rearranged and compiled in September / November 2006 by Florian Aders and Ron Brand.

This HowTo was written to the best of my knowledge. Although it will be maintained carefully, the author cannot guarantee a 100% error free work. Use it at your own risc. The author can not be held responsible for damage on hard/software due to the usage of this document. Feel free to distribute this HowTo as long as the Credits and Disclaimer will remain untouched.