qmail Plugin

qmail Plugin

This example combines protocol metrics, process metrics and scripting to build a plugin that monitors qmail. The plugin is composed of the following components:

• Process Metrics - Monitor the qmail-send process

• Script Metrics - Wrap the qmail-qstat script

• Protocol Metrics - Monitor SMTP and POP3

Resource Type Declarations

The example qmail plugin defines the qmail server type with two services, SMTP and POP3:

<plugin>
  <server name="qmail" description="MTA">
   ...
   <service name="SMTP">
     ...
   </service>
   <service name="POP3">
     ...
   </service>
  </server>
</plugin>

Measurement Plugin

A measurement plugin must be defined for the server type:

<plugin type="measurement"
        class="org.hyperic.hq.product.MeasurementPlugin"/>

Process Metrics

Process metrics are included as described in the Process Monitor Plugin:

<plugin>
  <server name="qmail" description="MTA">

    <config>
      <option name="process.query"
              description="Process Query"
              default="State.Name.eq=qmail-send"/>
    </config>
    
    <!-- process metrics -->
    <metric name="Availability"
            template="sigar.ptql:Type=ProcState,Arg=$!:State:%process.query%"
            indicator="true"/>
    ...
  </server>
</plugin>

Script Metrics

qmail includes a simple script to monitor its queue and todo directories:

% /var/qmail/bin/qmail-qstat
messages in queue: 32
messages in queue but not yet preprocessed: 12

As described in the Script Plugin example, HQ expects the output to be in key=value format. We could pipe the output to sed or perl to format, but the script is so simple that we'll just roll our own and tweak the names to match the plugin's metric aliases:

% /var/qmail/bin/hq-qmail-qstat 
MessagesInQueue=32
MessagesAwaitingPreprocessing=12

The other catch is that the user running the script must have permissions to read the queue directories (root or group qmail). We will use sudo in the example, by adding exec=sudo to the metric template:

<filter name="template"
        value="exec:file=/var/qmail/bin/hq-qmail-qstat,exec=sudo:${alias}"/>

<metric name="Messages In Queue"
        indicator="true"/>

<metric name="Messages Awaiting Preprocessing"
        indicator="true"/>

Protocol Metrics

The qmail example plugin defines two services, SMTP and POP3. Both define the following metrics:

• Availability - Standard check for the given protocol

• Inbound Connections - SIGAR provided NetStat metric of current inbound connections to the protocol's port

• Outbound Connections - SIGAR provided NetStat metric of current inbound connections to the protocol's port

Each service defines a hostname configuration property, which defaults to localhost.

<service name="SMTP">
  <config>
    <option name="hostname"
            description="SMTP Hostname"
            default="localhost"/>
  </config>

  <filter name="template"
          value="SMTP:hostname=%hostname%:${alias}"/>

  <metric name="Availability"
          indicator="true"/>

  <metric name="Inbound Connections"
          indicator="true"/>

  <metric name="Outbound Connections"
          indicator="true"/>
</service>

<service name="POP3">
  <config>
    <option name="hostname"
            description="POP3 Hostname"
            default="localhost"/>
  </config>

  <filter name="template"
          value="POP3:hostname=%hostname%:${alias}"/>

  <metric name="Availability"
          indicator="true"/>

  <metric name="Inbound Connections"
          indicator="true"/>

  <metric name="Outbound Connections"
          indicator="true"/>
</service>

Command Line Test

% java -jar pdk/lib/hq-product.jar -Dplugins.include=qmail -Dmetric-indicator=true
qmail Availability:
   qmail:sigar.ptql:Type=ProcState,Arg=$!:State:State.Name.eq=qmail-send
   =>100.0%<=
qmail Process Resident Memory Size:
   qmail:sigar.ptql:Type=ProcMem,Arg=$!:Resident:State.Name.eq=qmail-send
   =>372.0 KB<=
qmail Process Cpu Usage:
   qmail:sigar.ptql:Type=ProcCpu,Arg=$!:Percent:State.Name.eq=qmail-send
   =>0.0%<=
qmail Messages In Queue:
   qmail:exec:file=/var/qmail/bin/hq-qmail-qstat,exec=sudo:MessagesInQueue
   =>0.0<=
qmail Messages Awaiting Preprocessing:
   qmail:exec:file=/var/qmail/bin/hq-qmail-qstat,exec=sudo:MessagesAwaitingPreprocessing
   =>0.0<=
qmail SMTP Availability:
   qmail SMTP:SMTP:hostname=localhost:Availability
   =>100.0%<=
qmail SMTP Inbound Connections:
   qmail SMTP:SMTP:hostname=localhost:InboundConnections
   =>1.0<=
qmail POP3 Availability:
   qmail POP3:POP3:hostname=localhost:Availability
   =>0.0%<=
qmail POP3 Inbound Connections:
   qmail POP3:POP3:hostname=localhost:InboundConnections

qmail Plugin Sources

• The qmail-plugin.xml HQ plugin descriptor (Download)
  Deploy following these steps

• The qmail-qstat wrapper script (Download)
  Copy this file to /var/qmail/bin/hq-qmail-qstat and chmod +x /usr/qmail/bin/hq-qmail-qstat

  Script Permissions This script requires that user running it is either in group qmail or has the proper /etc/sudoers configuration: hqagent ALL=(root)NOPASSWD: /var/qmail/bin/hq-qmail-qstat

qmail Plugin Usage

After the plugin has been deployed, instances are created manually in HQ:

• "Browse Resources" -> "Platforms" -> click platform name of choice ->

• Click the "New Server" link and fill in the properties:
  • Name: [My qmail server]
  • Server Type: [qmail]
  • Install Path: [/var/qmail]

• Click the [OK] button

• Click "Configuration Properties"

• Click the [OK] button

The qmail monitor will begin collecting metrics and services can be added by clicking the "New Service" link and selecting SMTP or POP3