Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



SysCP (System Control Panel) is a server administration tool which enables an internet service provider to give their customers a web-based application to administrate their email addresses, their subdomains etc. The project was founded in autumn 2003 by Florian Lippert and was published on June, 15th 2004 under the GNU General Public Licence. It has few dependencies (apache, mysql, php and cronjob) and is basically an OSS alternative to applications like Confixx. SysCP can also be extended via a module API. You can extend the functionality with features like webftp/mail etc, it's features are a bit limited- but it's main features are handled well.

About this Howto

This howto has been treated badly from the beginning, time to change it. Basically what we want to explain here is a manual installation method and one using the ebuild. My goal is to keep it as slim as possible, so i deleted most of the general install and configuring comments! --the_mgt 21:10, 22 April 2007 (UTC)


SysCP is using the general LAMP (Linux Apache Mysql Php) environment, so please see the dedicated howtos on setting up the following services since installation and basic configuration will not be explained here!

Optional Components

SysCP will run without them!

Alternative Components

Installing manually

If you do not already have these services installed, you can pull them in with this command:

emerge postfix cyrus-sasl courier-imap mysql apache webalizer proftpd -av

This howto will give NO indepth information on how to get these services runnning for the first time! Please see other howtos, we just expect that they are up and running!

USE flags you need

The USE flags you see here are minimal configuration, see other dedicated howtos and the general Gentoo handbooks for more specific infos!

File: /etc/make.conf
USE="apache2 mysql unicode"
File: /etc/portage/package.use
#SysCP flags:
# we only need mysql auth
dev-libs/cyrus-sasl -authdaemond ssl
mail-mta/postfix ssl sasl
www-servers/apache php ssl
dev-php/php cli

Apache2 with php

File: /etc/conf.d/apache2


See dedicated howto on setting up MySQL. You will need the root password for SysCP installation!

SysCP Layout

When mysql and apache are running we can install syscp itself.

Paths & Files:

This is the path, were some local homepage is kept. We will install the SysCP interface to a subfolder of this homepage. In the following example called "MANAGEMENT.TLD"

This is were we will install syscp to. So that we see the webinterface, when we type http://MANAGEMENT.TLD/syscp/ into our preferred browser, after it is installed properly.

This is were we put the "customers" directory.

Here we will have the subdirectories:

you need to create all this directories.

mkdir -p /var/customers/{mail,webs,logs}

Is the directory, where apache vhosts configs are saved.

Is the file where we will store the syscp vhosts.

SysCP installation

CD to /var/www/localhost/htdocs/ do the following:

tar xzf syscp-current.tar.gz
chown apache:apache syscp/lib/
chmod 777 syscp/lib/

The chmod 777 of the will be changed back to 440 after the installation has been finished. The configuration dialog should now be avaiable via http://MANAGEMENT.TLD/syscp/

SysCP configuration

If you see the SysCP configuration dialog and have passed the installation of the MySQL database, you have to configure some things in the SysCP dialog itself and you will have adjust some configuration files of the programs SysCP is using:

Settings in the SysCP dialog

Now you should configure syscp according to these (or your own) installpaths.

Configuring the services


File: /etc/apache2/httpd.conf
Include /etc/apache2/vhosts.d/99_syscp_vhosts.conf

Don't forget to reload apache:

/etc/init.d/apache2 reload


Webalizer is run by the SysCP php-cli cron script

Cron Jobs

To get the SysCP cronjob running, do this:

 echo "*/5 * * * *     root    /usr/bin/php /var/www/localhost/htdocs/syscp/scripts/cron_tasks.php " >> /etc/crontab
 echo "0 0 * * *     root    /usr/bin/php /var/www/localhost/htdocs/syscp/scripts/cron_traffic.php " >> /etc/crontab
 echo "30 0 * * *     root    /usr/bin/php /var/www/localhost/htdocs/syscp/scripts/cron_ticketarchive.php " >> /etc/crontab


By default, SysCP makes use of ProFTPD

File: modify /etc/proftpd/proftpd.conf

Don't forget to change the mysql password!

ServerName                      "FTP Server"
ServerType                      standalone
DeferWelcome                    off

MultilineRFC2228                on
DefaultServer                   on
ShowSymlinks                    on
AllowOverwrite                  on

TimeoutNoTransfer               600
TimeoutStalled                  600
TimeoutIdle                     1200

DisplayLogin                    welcome.msg
DisplayFirstChdir               .message
ListOptions                     "-l"

DenyFilter                      \*.*/

Port                            21
MaxInstances                    30

# Set the user and group that the server normally runs at.
User                            nobody
Group                           nogroup

<Directory /*>
# Umask 022 is a good standard umask to prevent new files and dirs
# (second parm) from being group and world writable.
  Umask                         022  022
# Normally, we want files to be overwriteable.
  AllowOverwrite                on

DefaultRoot ~
RequireValidShell off

# Don't use Plaintext, theres a high risk that anyone can log in your ftp-server!
# More info:
# SQLAuthTypes Crypt Plaintext
SQLAuthTypes Crypt
SQLAuthenticate users* groups*
SQLConnectInfo syscp@localhost syscp <SYSCP_MYSQL_PASSWD>
SQLUserInfo ftp_users username password uid gid homedir shell
SQLGroupInfo ftp_groups groupname gid members
SQLUserWhereClause "login_enabled = 'y'"

SQLLog PASS login
SQLNamedQuery login UPDATE "last_login=now(), login_count=login_count+1 WHERE username='%u'" ftp_users

SQLLog RETR download
SQLNamedQuery download UPDATE "down_count=down_count+1, down_bytes=down_bytes+%b WHERE username='%u'" ftp_users

SQLLog STOR upload
SQLNamedQuery upload UPDATE "up_count=up_count+1, up_bytes=up_bytes+%b WHERE username='%u'" ftp_users


The debian settings work perfectly, you just have to change the paths in the debian settings to reflect the gentoo settings.

If you don't use bind, set bind restart command in the syscp config interface to /bin/true


Installing the MailTransferAgent is explained in dedicated howtos! We need a vmail group for virtual mail transport:

groupadd -g 2000 vmail
useradd -u 2000 -g vmail vmail
chown -R vmail:vmail /var/customers/mail/
File: /etc/postfix/
smtpd_banner = $myhostname ESMTP $mail_name (Gentoo/GNU)
biff = no
queue_directory = /var/spool/postfix
command_directory = /usr/sbin
daemon_directory = /usr/lib/postfix
mail_spool_directory = /var/spool/mail

append_dot_mydomain = no
myhostname = MANAGEMENT.TLD
mydestination = $myhostname $mydomain localhost localhost.$mydomain
mynetworks =
alias_maps = $alias_database
inet_interfaces = all
mail_owner = postfix

readme_directory = /usr/share/doc/postfix-2.1.5-r1/readme
alias_database = hash:/etc/mail/aliases
local_destination_concurrency_limit = 2
default_destination_concurrency_limit = 10
alias_maps = hash:/etc/mail/aliases
sendmail_path = /usr/sbin/sendmail
newaliases_path = /usr/bin/newaliases
mailq_path = /usr/bin/mailq
setgid_group = postdrop
html_directory = no
manpage_directory = /usr/share/man
sample_directory = /etc/postfix

smtpd_recipient_restrictions = permit_sasl_authenticated, permit_mynetworks, reject_unauth_destination
smtpd_use_tls = yes

smtpd_tls_key_file = /etc/postfix/newreq.pem
smtpd_tls_cert_file = /etc/postfix/newcert.pem
smtpd_tls_CAfile = /etc/postfix/cacert.pem
smtpd_tls_loglevel = 3
smtpd_tls_received_header = yes
smtpd_tls_session_cache_timeout = 3600s
tls_random_source = dev:/dev/urandom

virtual_mailbox_base = /var/customers/mail/
virtual_mailbox_maps = mysql:/etc/postfix/
virtual_mailbox_domains = mysql:/etc/postfix/
virtual_alias_domains =
virtual_alias_maps = mysql:/etc/postfix/
virtual_uid_maps = static:2000
virtual_gid_maps = static:2000
smtpd_sasl_auth_enable = yes
smtpd_sasl_local_domain = $myhostname
smtpd_sasl_security_options = noanonymous
virtual_transport = virtual
File: /etc/postfix/
user = syscp
dbname = syscp
table = mail_users
select_field = maildir
where_field = email
hosts = localhost
File: /etc/postfix/
user = syscp
dbname = syscp
table = panel_domains
select_field = domain
where_field = domain
additional_conditions = and isemaildomain = 1
hosts = localhost
File: /etc/postfix/
user = syscp
dbname = syscp
table = mail_virtual
select_field = destination
where_field = email
hosts = localhost

Restarting Postfix:

/etc/init.d/postfix restart

If there is an error later in the /var/log/messages like:

warning: /usr/lib/postfix/local: bad command startup -- throttling

please try:


Cyrus-sasl with auxprop

File: /etc/sasl2/smtpd.conf
pwcheck_method: auxprop
auxprop_plugin: sql
password_format: crypt
sql_engine: mysql
sql_hostnames: localhost
sql_user: syscp
sql_passwd: <SYSCP_MYSQL_PASSWD>
sql_database: syscp
sql_select: select password_enc from mail_users where username='%u@%r'
mech_list: login plain


Restarting the service

/etc/init.d/saslauthd restart


(Note: For me [courier-authlib 0.55] authdaemonrc and authmysqlrc are in /etc/courier/authlib)</ br>

File: /etc/courier-imap/authdaemonrc
authmodulelistorig="authcustom authcram authuserdb authldap authmysql authpam"
File: /etc/courier-imap/authdaemond.conf
File: /etc/courier/authlib/authmysqlrc

edit the syscp_password

MYSQL_SERVER localhost
MYSQL_PASSWORD syscp_password

Create SSL-Certs for POP3 and IMAP

easy task :D


Restart Services

authdaemond is wanted by courier (Note: For me [authdaemon 0.55] /etc/init.d/authdaemond is not available. The courier-* seems to take care of that.)

/etc/init.d/authdaemond restart   (veraltet! -> /etc/init.d/courier-authlib)
/etc/init.d/courier-imapd restart
/etc/init.d/courier-pop3d restart
/etc/init.d/courier-imapd-ssl restart
/etc/init.d/courier-pop3d-ssl restart

SSL Certs for Postfix and Apache

Are not treated here because there are dedicated howtos!

Automated install with the ebuild

Note: A Portage-Overlay for Syscp is now aviable on You can add it e.g. by using layman. The package optionally supports suexec and suphp. Note: There is also an ebuild on which is more recent and secure. The overlay-ebuild is out of date.

There is a thread in the forum on SysCP here: Since i first wanted to give this whole Howto some of its dignity back, i first took care about the manual installation parts, will check out the ebuild install soon. the_mgt

Configuring optional Services

Nothing of this has been verified by me, the_mgt


Maildrop is optional, Postfix will run without it. But it is always nice to filter spam and block viruses, isn't it?

Get the latest Maildrop module from SysCP-Forum Modules Section and extract it to syscp_root.

File: scripts/modules/maildrop/getsettings.php

from the Maildropmodule

and change
#! /usr/bin/php4
#! /usr/bin/php

import the INSTALL.sql (from the maildrop module tar.gz) in your syscp database using phpmyadmin or commandline

For me, it only workes with maildrop version 1.7.


emerge app-antivirus/clamav mail-filter/spamassassin mail-filter/maildrop

Iv you need maildrop-1.7 instead of 1.8 force emerge to install it by using emerge =maildrop-1.7.0

File: /etc/maildrop/

don't forget to change this line:
dbpw syscp_password

# The attributes are:
# mail - The full email address of the user (ie
#        This is the primary attribute searched upon by maildrop.
# maildir - The location (full path including name) of the users
#           mail directory (Maildir)
# homedirectory - The location (full path including name) of the
#                 users home directory.  This may be the same as the
#                 users maildir.
# uidnumber - The uid of the user that owns the mail files for
#             this user.  This may be a specific uid per user,
#             or a single uid for every user (full 'virtual' user
#             configuration), or a combination.
# gidnumber - The gid of the user that owns the mail files for
#             this user.  This may be a specific gid per user,
#             or a single gid for every user (full 'virtual' user
#             configuration), or a combination.
# quota     - *OPTIONAL* The quota for this user.  If blank, or
#             non-existent defaults to no quota.
# mailstatus - account status
# A sample LDAP entry is given at the end of this file.
# --- Actual configuration begins here -----------------------------

# hostname - host name of your mysql server
hostname        localhost
port            3306
socket          /var/run/mysqld/mysqld.sock
database        syscp
dbuser          syscp
dbpw            syscp_password
dbtable         mail_users

#not used now
#timeout                5

# default_uid - default uid (number only) to use incase uidnumber attribute not
# found in users mysql entry
default_uidnumber       2000

# default_gid - default gid (number only) to use incase gidnumber attribute not
# found in users ldap entry
default_gidnumber       2000

# MySQL Field definitions
# This section allows you to specify the actual attributes you
# use in your Mysql record
# The example attribute mapping shown below is also the default
# mapping used by maildrop in the case that any are missing

# UID_FIELD - MySQL attribute which contains the users name (w or w/o domain)
uid_field               email

# UIDNUMBER_FIELD - MySQL attribute which contains the system uid to deliver
# mail as
uidnumber_field         uid

# GIDNUMBER_FIELD - MySQL attribute which contains the system gid to deliver
# mail as
gidnumber_field         gid

# MAILDIR_FIELD - MySQL attribute which contains the path to the users
# custom maildir
maildir_field           maildir

# HOMEDIRECTORY_FIELD - MySQL attribute which contains the path to the users
# home directory
homedirectory_field     homedir

# QUOTA_FIELD - MySQL attribute which contains the users quota
# set standard for all maildirs or use a new mysql field
quota_field             '50000000'

# MYSQL_DEFAULT_STATUS_FIELD - MySQL attribute which could be created in the
# MySQL entry to set whether or not the user is allowed to receive email on
# this box..
#               -- looks unused for now; but must be valid column ! (2001-11-03)
mailstatus_field        postfix

# MYSQL_DEFAULT_WHERE_CLAUSE - This is optional !
# It can be set to any fixed string starting with keyword 'AND'.
# It will then be appended to the WHERE clause of our query.
where_clause            AND postfix = "Y"

File: /etc/maildroprc
# Settings:
SCANSPAMSIZE="250000"   # mails, which are smaller will not be scanned
logfile "/var/log/maildrop.log"

# Let's start


# the current users maildir is located in $DEFAULT
DELIVERY = $DEFAULT     # where the mail will go at the end of the script

# Has the maildir already been created?
`test -d "$MAILDIR"`
if( $RETURNCODE == 1 )
        `mkdir -p $DELIVERY`
        `rmdir $DELIVERY`
        `/usr/bin/maildirmake "$MAILDIR"`

# Obtain settings from the mysql db
# first we have to init the vars
# Run our script and get the values :)
`$SYSCPBASEDIR/scripts/modules/maildrop/getsettings.php "$LOGNAME"`
if ($RETURNCODE >= 2)
{       VSCAN=1;
if ($RETURNCODE >= 1)
{       SPAMFILTER=1;

exception {

#ok, let's filter

if ($VSCAN)
{       if($SIZE < $VSCANSIZE)
                exception {
                        xfilter "$SYSCPBASEDIR/scripts/modules/maildrop/"
        if ((/^X-Virus-Status:.*INFECTED/))
                DELIVERY = $MAILDIR.Infected

{       # Is the mail already marked as spam?
        if (/^X-Spam-Flag: YES/)
        {       DELIVERY = $MAILDIR.Spam
        if ( $SIZE < $SCANSPAMSIZE )
        {       exception {
                      xfilter "spamc -u $LOGNAME"
                # Spam?
                if (/^X-Spam-Flag: YES/)
                {       DELIVERY = $MAILDIR.Spam

# create needed sub-directory, if it doesn't exist
`test -d "$DELIVERY"`
if( $RETURNCODE == 1 )
        `mkdir -p $DELIVERY`
        `rmdir $DELIVERY`
        `/usr/bin/maildirmake "$DELIVERY"`

log "=========="

# finally, deliver the mail

Now we need to create the log file:

touch /var/log/maildrop.log && chown vmail:vmail /var/log/maildrop.log && chmod 700 /var/log/maildrop.log

A littlebit security: Nobody else need to read both files so chmod & chown it

 chmod 700 /etc/maildroprc /etc/maildrop/ && chown vmail:vmail /etc/maildroprc /etc/maildrop/

Before you can start services, you need to edit /etc/freshclam.conf & /etc/clamd.conf and remove the "example". Another thing you need to dois enable clamd.

File: /etc/conf.d/clamd

now you need to start the daemons.

/etc/init.d/spamd start


/etc/init.d/clamd start

Test maildrop

su vmail -c "echo maildummy | maildrop -d validmailuser@domain"

i don't know how to fix the quota error, but you can ignore it. check the mail account for new mails .. and tada you got mail :D

File: /etc/postfix/

if you got no errors (except the quota) enable maildrop in postfix

virtual_transport = maildrop
maildrop_destination_recipient_limit = 1
File: /etc/postfix/

should looks like this (the gentoo orginal looks littlebit different)

maildrop  unix  -       n       n       -       -       pipe
  flags=DRhu user=vmail:vmail argv=/usr/bin/maildrop -d ${recipient} ${extension} ${recipient} ${user} ${nexthop} ${sender}

add services to default runlevel

rc-update add spamd default
rc-update add clamd default

don't forget to reload postfix

/etc/init.d/postfix reload


Retrieved from ""

Last modified: Fri, 05 Sep 2008 23:27:00 +0000 Hits: 44,885