Gentoo Wiki


Apache2 Series



Addons & Tunnels






Peruser is an Apache mpm that allows the apache process to run as a specified user:group and jail that process to a specified location. This can be quite useful for vhosts as it can prevent different hosts from accessing other hosts or parts of the operating system.

Warning: Peruser is very new and has a lot of bugs but after installing with the following instructions it seems to be stable enough.

Note: This installation has only been tested with standard Gentoo and not with the hardened sources.

Setting up use flags

For this installation I am going to be using apache2 mysql5 and php5 without a gui. You will need to setup both your make make.conf file and package.use files to use the appropriate use flags.

Note: Apache can only use ONE mpm which includes threads.
File: /etc/make.conf
   USE="-alsa -kde -qt -gnome -gtk -X mmx sse apache2 php mysql ssl urandom"
File: /etc/portage/package.use
   dev-lang/php cli pcre xml zlib gd-external -gd ldap curl simplexml snmp imap
   net-www/apache -mpm-itk -mpm-leader -mpm-peruser -mpm-prefork -mpm-threadpool -mpm-worker -threads mpm-peruser

Installing Apache PHP and MySql

We are at the point now when its time to install apache and friends.

Code: Emerge Apache, PHP, and MySql
~ # emerge -av apache php mysql

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild  N    ] dev-libs/apr-1.2.8  USE="ipv6 urandom -debug" 1,082 kB
[ebuild  N    ] dev-libs/libpcre-6.6  USE="-doc" 545 kB
[ebuild  N    ] perl-core/Sys-Syslog-0.18  51 kB
[ebuild  N    ] app-misc/mime-types-7  7 kB
[ebuild  N    ] media-libs/gd-2.0.34  USE="-fontconfig -jpeg -png -truetype -xpm" 1,109 kB
[ebuild  N    ] sys-apps/ed-0.5  53 kB
[ebuild  N    ] dev-db/mysql-init-scripts-1.2  0 kB
[ebuild  N    ] virtual/perl-Storable-2.15  0 kB
[ebuild  N    ] dev-perl/Net-Daemon-0.39  31 kB
[ebuild  N    ] dev-libs/libmcrypt-2.5.7  512 kB
[ebuild  N    ] dev-libs/libxml2-2.6.28  USE="ipv6 python readline -debug -doc -test" 4,606 kB
[ebuild  N    ] net-nds/openldap-2.3.35-r1  USE="berkdb crypt gdbm ipv6 perl readline ssl tcpd -debug -kerberos -minimal -odbc -overlays -samba -sasl (-selinux) -slp -smbkrb5passwd" 3,707 kB
[ebuild  N    ] dev-perl/TermReadKey-2.30  37 kB
[ebuild  N    ] net-libs/c-client-2004a-r1  USE="pam ssl" 2,173 kB
[ebuild  N    ] app-admin/php-toolkit-1.0-r2  0 kB
[ebuild  N    ] dev-db/mysql-5.0.42  USE="berkdb perl ssl -big-tables -cluster -debug -embedded -extraengine -latin1 -max-idx-128 -minimal (-selinux) -static" 23,738 kB
[ebuild  N    ] dev-libs/apr-util-1.2.8  USE="berkdb gdbm -ldap -postgres -sqlite -sqlite3" 632 kB
[ebuild  N    ] dev-perl/PlRPC-0.2018  18 kB
[ebuild  N    ] virtual/perl-Sys-Syslog-0.18  0 kB
[ebuild  N    ] net-analyzer/net-snmp-5.4  USE="ipv6 perl ssl tcpd -X -diskio -doc -elf -lm_sensors -mfd-rewrites -minimal -rpm (-selinux) -sendmail -smux" 4,914 kB
[ebuild  N    ] net-www/apache-2.2.4-r7  USE="mpm-peruser ssl -debug -doc -ldap -mpm-event -mpm-itk -mpm-prefork -mpm-worker -no-suexec (-selinux) -static-modules -threads" 4,872 kB
[ebuild  N    ] virtual/mysql-5.0  0 kB
[ebuild  N    ] dev-perl/DBI-1.54  450 kB
[ebuild  N    ] app-admin/apache-tools-2.2.4-r3  USE="ssl" 0 kB
[ebuild  N    ] dev-lang/php-5.2.2-r1  USE="apache2 berkdb cli crypt gd-external gdbm iconv imap ipv6 ldap mysql ncurses nls pcre readline reflection session simplexml snmp spl ssl unicode xml zlib -adabas -bcmath -birdstep -bzip2 -calendar -cdb -cgi -cjk -concurrentmodphp -ctype -curl -curlwrappers -db2 -dbase -dbmaker -debug -discard-path -doc -empress -empress-bcs -esoob -exif -fastbuild -fdftk -filter -firebird -flatfile -force-cgi-redirect -frontbase -ftp -gd -gmp -hash -inifile -interbase -iodbc -java-external -json -kerberos -ldap-sasl -libedit -mcve -mhash -msql -mssql -mysqli -oci8 -oci8-instant-client -odbc -pcntl -pdo -pdo-external -pic -posix -postgres -qdbm -recode -sapdb -sharedext -sharedmem -soap -sockets -solid -spell -sqlite -suhosin -sybase -sybase-ct -sysvipc -threads -tidy -tokenizer -truetype -wddx -xmlreader -xmlrpc -xmlwriter -xpm -xsl -yaz -zip -zip-external" 7,151 kB
[ebuild  N    ] dev-perl/DBD-mysql-3.0008  114 kB

Total: 26 packages (26 new), Size of downloads: 55,792 kB

Would you like to merge these packages? [Yes/No] 

Configuring Apache MySql and PHP

You can configure php and mysql exactly like you would without peruser.

We need to tell apache to load the appropriate modules. The key module here is PERUSER.

File: /etc/conf.d/apache2
   # Everything else is commented out.

The httpd.conf file is where the mpm-peruser config happens. I have included the relevant part of the httpd.conf file. Most of these setting are the defaults so modification will be needed to suit your needs.

File: /etc/apache2/modules.d/00_mpm.conf
# Peruser MPM
# ServerLimit: Maximum value of MaxClients for this run of Apache
# MaxClients: Maximum number of children alive at the same time
# MinSpareProcessors: Minimum number of idle children,
#                     to handle request spikes
# MinProcessors: Minimum number of processors per vhost
# MaxProcessors: Maximum number of processors per vhost
# ExpireTimeout: Maximum idle time before a child is killed, 0 to disable
# Multiplexer: Specify a Multiplexer child configuration.
# Processor: Specify a user and group for a specific child process
<IfModule mpm_peruser_module>
        ServerLimit                     256
        MaxClients                      256
        MinSpareProcessors      2
        MaxProcessors           10
        MaxRequestsPerChild     1000

        # KeepAlive *MUST* be set to off
        KeepAlive Off

        # kill off idle processors after this many seconds
        # set to 0 to disable
        ExpireTimeout       1800

        Multiplexer nobody nobody

        # Processor information has been moved to vhost
        #Processor apache apache
        # chroot dir is optional:
        # Processor user group /home/user


Setting Up The Apache Virtual Hosts

Setting up each of our Virtual Hosts is fairly easy and very similar to setting up standard vhosts. The major difference is the section for the mpm-peruser processor. In our example setup we will be adding 3 virtual hosts: a default vhost, site1 and site2. Please be aware that you will need a processor for each virtual host and if using in a production environment you will probably need to up the limits and max child processes.

File: /etc/apache2/vhosts.d/20_site1_vhost.conf
 <VirtualHost *:80>
        # Please not all paths a relative to the path specified in the peruser section.
        DocumentRoot /htdocs
        ErrorLog /logs/error_log
        CustomLog /logs/access_log common

        <Directory "/htdocs">
                Options Indexes FollowSymLinks
                AllowOverride All

                <IfModule mod_access.c>
                        Order deny,allow
                        Allow from all

        <IfModule mpm_peruser_module>
                # The server enviroment and the processor's user and group must match.
                # Jailing the processes does not seem to work with apache 2.2.
                # This does work with apache 2.0 but you dont get ssl.
                #Processor apache site1 /siteroot/site1
                #ServerEnvironment apache site1 /siteroot/site1
                Processor apache site1
                ServerEnvironment apache site1

                # These are overrides for what is in the httpd.conf file.
                MinSpareProcessors 4
                MaxProcessors 20

Site File and Permissions

We need to create/copy the files for each of our vhosts to the appropriate location. We also need to set the permissions of these files. Please be aware that the permissions I am setting up are borderline paranoid and are probably over kill but I feel its a better to be paranoid than to be hacked.

Note: You need to create a user and group for each of the peruser processes because apache is going to be running as the specifed user:group that you setup in the vhost file. In our example we are running each process as the user apache so that user already exists.
Code: Create Files and Folders
  # mkdir -p /siteroot/site1/logs /siteroot/site1/htdocs
  # echo "Welcome to site1." > /siteroot/site1/htdocs/index.html
  # groupadd site1
  # chown -R root:site1 /siteroot/site1
  # chmod -R 750 /siteroot/site1
  # chmod -R 500 /siteroot/site1/logs

SSL Support

SSL should work as expected as long as you installed >=net-www/apache-2.2.

Loose Ends

Ok a few things you don't want to install in the chroot are su, sudo, and suexec2. Suexec is enabled by default so you should probably just go ahead and disable it unless your sure you need it.

Code: Disable suexec2
   # chmod u-s /usr/sbin/suexec2

I Think you can disable this via the /etc/conf.d/apache2 file by removing -D SUEXEC

Retrieved from ""

Last modified: Tue, 20 May 2008 04:54:00 +0000 Hits: 4,493