Introduction

Butler is an internal service of sorts that allows you to manipulate and extract information from your web servers. You can also create new internal services on top of Butler for your own internal needs.

Installation

You can install Butler via PEAR's command line utility, pear. Run the following line on the server(s) you wish to run Butler on. Replace x.y.z with the latest version number from our project's homepage.

$ pear install http://digg.googlecode.com/files/Butler-x.y.z.tgz

Once you have the package installed you'll need to create a virtual host on the server(s) you're running it on. It's important that this virtual host only run on an internal address/port as Butler has no authentication. For instance, if your web servers are named www-01.example.com and www-02.example.com you might want to set Butler up on butler.www-01.example.com and butler.www-02.example.com.

You'll want to copy the example htaccess file and index.php file into the document root for your Butler virtual hosts. These should be in /path/to/pear/docs/Butler/examples. Either copy htaccess to your document root as .htaccess or add the rules to your virtual host's configuration (this may require some tweaking).

Usage

Once you have Butler installed point your browser (We suggest using Firefox since it has excellent XML support) to your Butler virtual host. You should get a listing of services and method names such as the one below.

<?xml version="1.0" encoding="UTF-8"?>
<response _type="array">
    <service _type="array">
        <name _type="string">pear</name>
        <method _type="array">packages</method>
    </service>
    <service _type="array">
        <name _type="string">php</name>

        <method _type="array">version</method>
        <method _type="array">extensions</method>
        <method _type="array">includepath</method>
    </service>
    <service _type="array">
        <name _type="string">apc</name>
        <method _type="array">info</method>

        <method _type="array">clear</method>
        <method _type="array">sma</method>
        <method _type="array">prime</method>
    </service>
    <status _type="integer">200</status>
</response>

Each service name has multiple methods. You can go to each method by pointing your browser to /$service/$method.(xml|json). For instance, going to /php/extensions.xml should give you a list of installed PHP extensions running on that server.

Extending

Let's say you want to create a new service that reports the uptime of your web servers. You can easily extend Butler by creating new services and placing them in Butler's path (e.g. /path/to/pear/Butler).

<?php

require_once 'Butler/Common.php';

class Butler_myexample extends Butler_Common
{
    public function uptime()
    {
        return array('uptime' => `uptime`);
    }
}

?>

Once you've put the above example into Butler's path you should find that it shows up in your service listing and, when you go to it you should see something like the following.

<?xml version="1.0" encoding="UTF-8"?>
<response _type="array">
    <uptime _type="string"> 18:06:10 up 10 days,  4:49, 33 users,  load average: 0.60, 0.64, 0.46</uptime>
    <status _type="integer">200</status>
</response>