Enabling and using apache's mod_status on Gentoo

Apache's mod_status module allows it to display a web page containing statistics about the web server's current state, including worker processes and active connections.


What is mod_status?

While you can get information on the connections being made to apache by checking its access log, if you want more immediate information about what apache is up to you can enable mod_status. This module allows you to view a detailed status page for your web server. This information can be useful for watching your web server's performance during load testing or for allowing a monitoring program like munin or mrtg to gather activity data for later aggregation.

The Apache Project keeps their server status page available to the general public. To get a look at a fairly busy web site's status page, visit:

http://www.apache.org/server-status

Enable mod_status

To enable mod_status you'll need to add the "STATUS" keyword to apache's start options. Open the configuration file at:

/etc/conf.d/apache2

Edit the list of keywords in the APACHE2_OPTS setting to include "-D STATUS", similar to:

APACHE2_OPTS="-D DEFAULT_VHOST -D INFO -D SSL -D SSL_DEFAULT_VHOST -D LANGUAGE -D PHP5 -D STATUS"

That keyword is used to tell apache to load the configuration file for mod_status, which is:

/etc/apache2/modules.d/00_mod_status.conf

Configure access

In the mod_status config file:

/etc/apache2/modules.d/00_mod_status.conf

Look for the following section:

# Allow server status reports generated by mod_status,
# with the URL of http://servername/server-status
<Location /server-status>
    SetHandler server-status
    Order deny,allow
    Deny from all
    Allow from 127.0.0.1
</Location>

If you haven't set up any virtual hosts in apache (i.e. you're just using the default configuration), you'll be editing this configuration block in place.

If you have created one or more virtual hosts, you'll want to paste this configuration for the /server-status location into the default virtual host for any domains configured in apache (basically, any that could return something if you request "domainname.com/server-status"). Then you would make needed changes to the Location configuration block in each file. When that's done, comment out the Location block in the 00modstatus.conf file.

The "Allow from .example.com" line should reflect what host or range of hosts you want to allow to view your server status page. We recommend setting that permission to localhost only (the default "127.0.0.1") so outsiders can't see detailed information about your web server. We'll talk about how you'll be able to view the status page from the slice itself in a later section.

ExtendedStatus

The ExtendedStatus setting adds more information to the status page apache returns, like CPU use and requests per second. Enabling ExtendedStatus makes apache do a little extra work when it gets a status request, so you might weigh the extra information gained against the potential performance hit to a busy server.

Many monitoring applications that record performance over time, like munin, require that ExtendedStatus be enabled before they can monitor apache.

The ExtendedStatus setting must be set at the server level and applies to all virtual hosts running under apache. It's best to set it in the mod_status config file, which once again is:

/etc/apache2/modules.d/00_mod_status.conf

It will likely be enabled by default:

# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called.
ExtendedStatus On

Comment out that last line to disable ExtendedStatus, changing the configuration block to:

# ExtendedStatus controls whether Apache will generate "full" status
# information (ExtendedStatus On) or just basic information (ExtendedStatus
# Off) when the "server-status" handler is called.
#ExtendedStatus On

Restart apache

Now that we've made sure the apache server status page is enabled and configured the way we want it we'll need to restart apache:

sudo /usr/sbin/apache2ctl restart

Install lynx

With apache's server status page restricted to localhost-only access we won't be able to see the page from our desktop's web browser. Luckily the server status page is just a bunch of text with no graphics, letting us use a simple approach: Run a text-based web browser while logged into the slice itself.

To try this option out we'll need to install a browser on the slice first. The browser we'll use is called "lynx", and you can install it with the following command:

sudo emerge --sync
sudo emerge lynx

No configuration is necessary, but lynx is keyboard-controlled so it's handy to know a few basic keystrokes when using it. There is a list of the most frequently-used commands at the bottom of the screen while lynx is running. If you visit a site with lynx you can navigate with the up and down keys and follow a highlighted link by hitting enter. Hit "q" to quit (and hit "y" to confirm the quit). Hit "h" to access lynx's documentation.

View the status page

The URL of the apache status page will be your domain name with "/server-status" tacked onto the end. In this section we're assuming you've configured your default server instance or virtual host to accept connections from the localhost only. Tell lynx to view your apache status page with the following command:

lynx http://localhost/server-status

You will see something like the following page if you have ExtendedStatus enabled (the example server was running Ubuntu Hardy, but it should look similar for all recent versions of Linux and Apache). With ExtendedStatus disabled the page will look similar, but with a few lines missing.

                                                                     Apache Status (p1 of 2)
                             Apache Server Status for localhost                             

   Server Version: Apache/2.2.8 (Ubuntu) PHP/5.2.4-2ubuntu5.10 with Suhosin-Patch           
   Server Built: Nov 13 2009 21:58:02                                                       
     ______________________________________________________________________________         

   Current Time: Friday, 26-Mar-2010 19:04:17 UTC                                           
   Restart Time: Friday, 19-Mar-2010 20:21:03 UTC                                           
   Parent Server Generation: 1                                                              
   Server uptime: 6 days 22 hours 43 minutes 14 seconds                                     
   Total accesses: 386 - Total Traffic: 317 kB                                              
   CPU Usage: u0 s0 cu0 cs0                                                                 
   .000643 requests/sec - 0 B/second - 840 B/request                                        
   1 requests currently being processed, 9 idle workers                                     

W_________......................................................                            
................................................................                            
................................................................                            
................................................................                            

   Scoreboard Key:                                                                          
   "_" Waiting for Connection, "S" Starting up, "R" Reading Request,                        
   "W" Sending Reply, "K" Keepalive (read), "D" DNS Lookup,                                 
   "C" Closing connection, "L" Logging, "G" Gracefully finishing,                           
   "I" Idle cleanup of worker, "." Open slot with no current process                        

   Srv PID Acc M CPU SS Req Conn Child Slot Client VHost Request                            
   0-1 3425 0/36/45 W 0.00 0 0 0.0 0.04 0.04 127.0.0.1 www.example.com GET                
   /server-status HTTP/1.0                                                                  
   1-1 3426 0/44/58 _ 0.00 4277 0 0.0 0.04 0.05 173.65.120.190 www.example.com GET        
   /favicon.ico HTTP/1.1  

-- press space for next page --                                                             
  Arrow keys: Up and Down to move.  Right to follow a link; Left to go back.                
 H)elp O)ptions P)rint G)o M)ain screen Q)uit /=search [delete]=history list                                                                  

If you get an error, troubleshoot accordingly. A "not found" error would indicate that mod_status isn't properly enabled. A "forbidden" error would mean that the Location configuration for /server-status is restricting you from accessing the page. A "connection refused" error means apache isn't listening on port 80 and may not be running.

Following the "Scoreboard Key" will be a list of current connections, including the source addresses and the file being accessed.

Most of the server status page should be pretty self-explanatory. The apache version is listed at the top, along with some of the modules loaded in apache. Some important stats following that include how long the apache server has been running since its last restart, the traffic it's handled since then, how much CPU is being used by apache at that moment, and how frequently apache is serving requests.

The section between the number of current requests and the "Scoreboard Key" is a representation of apache's "workers" and their status. The "worker" is essentially apache's request handler. Apache keeps several active at a time.

The Scoreboard Key shows what each symbol in the worker list means. In the example you can see the apache server isn't very busy — several "_" characters show a handful of workers waiting for requests, while a lone "W" shows a worker replying to a request (the request for the server status page, in fact). All the periods show slots that could be filled with workers if the server gets busy enough to need them.

If you visit the Apache Project's server status page you can see a more active server and a greater variety of worker states, like "K" (keep-alive, a reused connection waiting for a new request from a browser), "R" (reading a request from a browser), and "C" (closing a terminated connection).

Yes, but what does it all mean?

Most often the mod_status output is used by other tools to chart the server's activity over time. Viewed directly, the status page is handy for a quick overview of what your server is doing at a given moment. Some of the displayed data can indicate problems that merit investigation.

Examples of items to watch for on the status page include:

• A high CPU usage for apache could indicate a problem with an application being run through a module like mod_php.

• While it's normal to see several keep-alives being handled by apache's workers, if they constitute a vast majority of the worker statuses you see then your web server might be keeping old connections alive too long. You may want to look into reducing the amount of time connections are kept alive by apache via the KeepAliveTimeout directive.

• If you see very few inactive workers (represented by "." characters) you may want to increase the MaxClients value for your apache server. Making sure you have idle workers ready to handle new requests can improve the web server's responsiveness (assuming you have enough memory on the slice available to handle the extra connections).

Summary

Apache's status module is a handy complement to a monitor program, and the snapshot it provides of a web server's activity can highlight problems that would be otherwise difficult to isolate using standard system tools like top and lsof. Even if you're only enabling mod_status for a monitoring tool, knowing how to access and read the status page can help you be a more effective web server administrator.

For more information about mod_status and the details it reports check the Apache mod_status documentation.

  • -- Jered

Article Comments:

Cristian commented Thu Dec 27 19:10:01 UTC 2012:

Good tutorial. Helped me a lot. Many thanks.

Want to comment?


(not made public)

(optional)

(use plain text or Markdown syntax)