wiki:PeruserGettingStarted
Last modified 18 months ago

Getting started

  1. Getting started
    1. Installing
      1. Distribution packages
      2. Using the patch file
      3. Building from SVN
    2. Configuring
      1. Basic configuration
      2. The limits
    3. Monitoring
      1. Peruser status
      2. Peruser statistics

Installing

Distribution packages

There are binary packages available on the download page. If there isn't one for your distribution, you can help us, by grabbing the latest patch (from the front page), applying it to your latest apache package and sending it back to us.

Using the patch file

To get a working copy using the patch file, you need to grab the patch file's Apache version, eg if using httpd-2.2.16-peruser0.4.0rc2.patch, then you need the 2.2.16 Apache. The patch may work on older Apache versions, but its untested (if you try it, be sure to give us some feedback on it).

Grab the Apache: 

$ wget http://apache.mirrors.tds.net/httpd/httpd-2.2.16.tar.gz

Unpack it: 

$ tar -zxf httpd-2.2.16.tar.gz

Apply the patch (assuming you already have it): 

$ cd httpd-2.2.16
$ cat ../httpd-2.2.16-peruser0.4.0rc2.patch | patch -p1

Run autoconf and autoheader so that the build system would recognize peruser: 

$ autoconf
$ autoheader

Run the configure script and start the build: 

$ ./configure --with-mpm=peruser
$ make && make install

Building from SVN

The repository contains the latest stable apache version with peruser patch applied, so all you need to do, is basically grab the latest copy and you can build it straight from there.

Grab the latest version from the repository: 

$ svn co http://svn.peruser.org/svn/peruser/trunk apache-peruser
$ cd apache-peruser

Run autoconf and autoheader so that the build system would recognize peruser: 

$ autoconf
$ autoheader

Run the configure script and start the build: 

$ ./configure --with-mpm=peruser
$ make && make install

Configuring

So now that you have the peruser MPM installed, you want to configure it. For this, you might want to get to know how peruser internally works, so you can make the most of it.

Basic configuration

To get a minimal copy working, you need to specify the server environments and attach them to the virtualhosts. Note that the server environments must be specified before the virtualhosts. A single server environment can be applied to multiple virtualhosts.

To create a simple server environment, write this to your apache configuration file: 

<Processor myserver>
    User john
    Group john
</Processor>

This creates a server environment named myserver running under the john user and group. To apply this server environment to the virtualhost, add ServerEnvironment directive to your virtualhost: 

<Virtualhost *:80>
    ServerName john.example.com
    ServerEnvironment myserver
</Virtualhost>

So here you go, all requests for john.example.com will be using the myserver server environment and will be run under the john user and group.

Now just remember that all virtualhosts need to have server environment specified. Having a virtualhost without a server environment, will result in all requests for that virtualhost dropped with 503 (Internal Server Error).

The limits

Now that you have your server environments set up, you should specify the process limits. Here are your default limits: 

ServerLimit 256
MaxClients 256
MinProcessors 0
MaxProcessors 10
MinSpareProcessors 2
MaxSpareProcessors 0
MinMultiplexers 3
MaxMultiplexers 10
MultiplexerIdleTimeout 0
MaxRequestsPerChild 1000
ExpireTimeout 1800
IdleTimeout 900
ProcessorWaitTimeout 5 10
  • ServerLimit and MaxClients determine the total limit of all children. You should set them the same.
  • MinProcessors and MaxProcessors set the minimum and maximum worker limits for a single server environment.
  • MinSpareProcessors and MaxSpareProcessors sets the limits of idle workers in a single server environment.
  • MinMultiplexers and MaxMultiplexers set the minimum and maximum multiplexer count.
  • MultiplexerIdleTimeout sets the idle timeout (time the multiplexer can be idle, before stopped). 0 = disabled.
  • ExpireTimeout sets the maximum time a child can handle a single request (you want to set this high, if you want to allow long downloads). 0 = disable
  • IdleTimeout sets the maximum time a child can be idle. 0 = disable
  • ProcessorWaitTimeout sets the amount of time the multiplexer waits the processor, if it is busy. First argument sets the time, second argument the amount of levels between not waiting and waiting the maximum time. See Waiting for the processor.

Peruser also allows setting the next directives inside a <Processor> tag, to make them server-environment-specific:

  • MinProcessors
  • MaxProcessors
  • MinSpareProcessors
  • MaxSpareProcessors
  • Chroot
  • Cgroup

Monitoring

Now that you have your server set up and running, you want to know, how the peruser is handling itself and are the limits specified enough for the server to handle.

To do this, peruser has an in-built server-status hook, which displays the list of all children and statistic information about them. To see this, you need to enable the server-status page and ExtendedStatus: 

<Location /server-status>
    SetHandler server-status
</Location>

ExtendedStatus On

After enabling this, restart the server and go to the server-status page. Under the request list, you should see the peruser status.

Peruser status

An example of the peruser status is below: 

ID	PID	STATUS	SB STATUS	Type	        Processor	Pss	AVAIL
0	0	STANDBY	DEAD	        PROCESSOR	senv1	        0/0/30	100%
1	0	STANDBY	DEAD	        PROCESSOR	senv2	        0/0/30	100%
2	0	STANDBY	DEAD	        PROCESSOR	senv3	        0/0/30	100%
3	2653	ACTIVE	BUSY_WRITE      PROCESSOR	senv4	        5/3/30	100%
4	2654	READY	READY           MULTIPLEXER	Multiplexer     2/2/10	100%
5	2655	READY	READY           MULTIPLEXER	Multiplexer     2/2/10	100%
6	2656	READY	READY           WORKER	        senv4	        5/3/30	100%
7	2657	READY	READY           WORKER     	senv4	        5/3/30	100%
8	2658	READY	READY           WORKER     	senv4	        5/3/30	100%
9	2659	ACTIVE	BUSY_WRITE      WORKER   	senv4	        5/3/30	100%
10	0	STANDBY	DEAD	        UNKNOWN	        (null)	        0/0/0	0%
11	0	STANDBY	DEAD	        UNKNOWN	        (null)	        0/0/0	0%
12	0	STANDBY	DEAD	        UNKNOWN	        (null)	        0/0/0	0%
13	0	STANDBY	DEAD	        UNKNOWN	        (null)	        0/0/0	0%
14	0	STANDBY	DEAD	        UNKNOWN	        (null)	        0/0/0	0%
  • The ID and PID fields should be self-explanatory.
  • The status displays the peruser status of the child, it can be one of:
    • STANDBY (child is dying or is dead)
    • STARTING (child is starting up)
    • READY (child is idle)
    • ACTIVE (child is handling a request)
  • The SB STATUS is the child's scoreboard status (just for reference).
  • Type displays the child type (MULTIPLEXER, PROCESSOR, WORKER or UNKNOWN). See the process types for detailed explanation.
  • Processor displays the server environment.
  • Pss displays the server environment's children (alive/idle/max).
  • AVAIL displays the server environment's availability. This should be 100% at all times. If this gets below 100%, then there aren't enough free children for the server environment and the multiplexers have dropped requests to save the rest of the server from collapsing.

Also, in this list you can see some odd entries with STANDBY status and UNKNOWN child type. These slots mean that these were previously in use, but are currently free, so it's completely normal to have these.

Peruser statistics

As of Peruser 0.4.0rc2, it is now possible to see some statistics about each server environment. To see this, use the ?peruser_stats var to access server_status, /server_status?peruser_stats for example.

This displays the list of server environments set in the server, ordered by the most active (which has the most children alive) server environment. In the list you can see the count of handled connections, handled requests and the number of requests that have been dropped because of hitting the child limit.