topvhost 0.5

A Virtual Host Monitor

  Add it to your Download Basket!

 Add it to your Watch List!


Rate it!

What's new in topvhost 0.5:

  • This release adds proper man(1) documentation.
  • There are minor parser corrections for both input and output.
Read full changelog
send us
an update
GPL v3 
Gary Wuertz
ROOT \ System \ Monitoring
topvhost is a virtual host monitor tool for Linux.


The apache mod status module provides very detailed real time server information but does not provide much intuition on how that activity is spread over the virtual host configuration. I had once written a php prototype that built a list of virtual host log files using glob(), then scanned those files every second to collect the last modified date time, and finally enumerated those files and time stamps in descending order. It was not very pretty and very inefficient but it provided the inspiration for a better server monitor.

Linux provides a very effecient mechanism (inotify) to monitor file system changes, so I set about creating a curses application to reproduce my prototype. To be generally useful, the file list specification had to be flexible to account for the various ways virtual host logging is setup. I parameterized and slightly generalized the glob() mechanism and added an explicit list mechanism. To hold these and other parameterizations a configuration file "~/.topvhosts" was created.

The efficiency of this approach, allowed me to add add information incrementally extracted from each log file by scanning the records added to the file since it last changed. Record count is used as a proxy for "hits" and the fields from the last parsed record can be displayed to provide "almost" real-time information.


The application is currently provided as a source tarball released under the GPL. A c++ compiler and a curses development environment are required to build the application. The build uses GNU autotools so the installation follows the typical pattern of expanding the tarball, changing your directory to the main distribution directory, then executing "./configure", "make", and "make install". I have only tested the build in 32 and 64 bit CentOs environments. In those environments, you may need to install the gcc-c++ and ncurses devel packages in order to sucessfully complete the ./configure step. You must configure your application before use - see the next section.


The configuration file is named '.topvhosts' and is stored in the home directory. A prototype of this file is found in the main distribution distribution. This file should be customized and placed in the user's home directory (it is hoped that this step may become an addition make target in the future). The general features of this "INI" style text file are:

* Lines with a leading '#' or ';' are treated as commentary
* Lines of a format '[name]' create a new named configuration section
* Settings take the form of an assignment 'name = value'
* The second occurence of an assignment overrides the first (but see next)
* The run-time configuration is determined by merging the assignments appearing before the first section with the assignments in a designated section

The currently recognized configuration settings are:
default The name of the configuration file section used if none is specified on the command line
hdr_format A sprintf like format string that describes the topmost line of the display. See details below.
row_format A sprintf like format string that describes the other lines of the display. See details below.
log_format A sprintf like format string that describes the format of the log records. See details below.
glob_src A path containing '%s' as a place holder for the domain name. The place holder will be replaced by '*' and expanded by glob() to produce a file list
glob_omit The extension of any files to be removed from the list generated by glob()
config_src The name of a section in the configuration file whose assignments will be added to the file list. The left hand value is presumed to be the domain name and the right hand value is presumed to be the complete path to the log file
file_src The full path to an external configuration file whose topmost assignments use the same assignment format as used by config_src

The final file list is obtained by merging the *_src specifications. The distributed configuration file contains sections for virtual hosts managed by the Direct Admin and Plesk control panels. I am open to extending the configuration methods for any other reasonable log file setups.

Log and display fields are treated as named columns and construction of the row display takes place as the transfer of log columns to row columns. It makes sense to use the same nomenclature to describe both the source and destination of this transfer. The source record is specified by apache LogFormat syntax, so the destination (the display row) is described by a similar syntax:

* The output specification inserts a sprintf-like width/precision following the leading '%' i.e %< [key] >.
* The apache %{name}[key] construct is represented by %< width >[key]{name} in the output specification
* Output fields must be fixed width.
* A compatable syntax is used to format the screen header display.

Last updated on August 28th, 2009

#vhost monitoring #virtual host #system monitoring #virtual #host #monitoring #vhost

Add your review!