                                The Cacti Manual

  Ian Berry

   Copyright (c) 2003 by Ian Berry

   This project is licensed under the terms of the GPL.

   This program is free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by the Free
   Software Foundation; either version 2 of the License, or (at your option)
   any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
   or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
   for more details.

   All product names are property of their respective owners. Such names are
   used for identification purposes only and are not indicative of
   endorsement by or of any company, organization, product, or platform.

     ----------------------------------------------------------------------

   Table of Contents

   I. Installation

                1. Requirements

                2. Installing Under Unix

                3. Installing Under Windows

                4. Upgrading Cacti

   II. Basics

                5. Graph Overview

                6. How to Graph Your Network

                             Creating a Device

                             Creating the Graphs

                7. Viewing Graphs

                             Graph Trees

                8. User Management

                             Creating a New User

                             Realm Permissions

                             Graph Permissions

                             Graph Settings

   III. Advanced Topics

                9. Data Input Methods

                             Creating a Data Input Method

                             Making Your Scripts Work With Cacti

                10. Data Queries

                             Creating a Data Query

                             SNMP Query XML Syntax

                             Script Query XML Syntax

                11. Templates

                             Graph Templates

                             Data Templates

                             Host Templates

   IV. Using Cacti

                12. How To

                             Graph a Single SNMP OID

                             Simplest Method of Going from Script to Graph
                             (Walkthrough)

                13. Frequently Asked Questions

   V. Reference

                14. Variables

                             Graph Variables

                             Host Variables

                15. RRDTool Specific Features

                             GPRINT Presets

                             CDEFs

     ----------------------------------------------------------------------

                            Chapter 1. Requirements

   Cacti requires that the following software is installed on your system.

     * RRDTool

     * MySQL 3.23 or greater

     * PHP 4.1 or greater

   Packages for RPM-based Operating Systems

     * httpd

     * php

     * php-mysql

     * php-snmp

     * mysql

     * mysql-server

     * net-snmp

   Ports for FreeBSD

     * www/apache2

     * net/rrdtool

     * net/net-snmp

     * www/php4-cgi

     * lang/php4 (With MySQL and SNMP Support)

     * databases/mysql323-server

     ----------------------------------------------------------------------

                        Chapter 2. Installing Under Unix

    1. Extract the distribution tarball.

 shell> tar xzvf cacti-version.tar.gz

    2. Create the MySQL database:

 shell> mysqladmin --user=root create cacti

    3. Import the default cacti database:

 shell> mysql cacti < cacti.sql

    4. Optional: Create a MySQL username and password for Cacti.

 shell> mysql --user=root mysql
 mysql> GRANT ALL ON cacti.* TO cactiuser@localhost IDENTIFIED BY 'somepassword';
 mysql> flush privileges;

    5. Edit include/config.php and specify the MySQL user, password and
       database for your Cacti configuration.

 $database_default = "cacti";
 $database_hostname = "localhost";
 $database_username = "cactiuser";
 $database_password = "cacti";

    6. Set the appropriate permissions on cacti's directories for graph/log
       generation. You should execute these commands from inside cacti's
       directory to change the permissions.

 shell> chown -R cactiuser rra/ log/

       (Enter a valid username for cactiuser, this user will also be used in
       the next step for data gathering.)

    7. Add a line to your /etc/crontab file similar to:

 */5 * * * * cactiuser php /var/www/html/cacti/cmd.php > /dev/null 2>&1

       Replace cactiuser with the valid user specified in the previous step.

       Replace /var/www/html/cacti/ with your full Cacti path.

    8. Point your web browser to:

         http://your-server/cacti/

       Log in the with a username/password of admin. You will be required to
       change this password immediately. Make sure to fill in all of the path
       variables carefully and correctly on the following screen.

     ----------------------------------------------------------------------

                      Chapter 3. Installing Under Windows

   Install PHP

    1. Extract PHP to c:\ and rename the new directory to 'php'.

    2. Copy the files in c:\php\dlls to c:\winnt\system32.

    3. Copy the file c:\php\php4ts.dll to c:\winnt\system32.

    4. Move all MIB files from c:\php\mibs to c:\usr\mibs.

    5. Create the directory c:\tmp.

    6. In the c:\php directory, rename the php.ini-dist file to php.ini, copy
       it to c:\winnt, and make the following changes to the file:

 extension_dir = c:/php/extensions
 extension=php_snmp.dll
 session.save_path=c:\tmp

   Configure the Webserver (Apache)

    1. Install the Apache web server. This is as simple as double clicking
       the .msi file and following the prompts. Make sure to install it as a
       service and for the sake of the HOWTO, install it to c:\apache or
       c:\apache2.

    2. If you are using Apache 1.3.x, add the following lines to your
       httpd.conf file in the c:\apache\conf directory:

 LoadModule php4_module c:/php/sapi/php4apache.dll
 AddModule mod_php4.c
 AddType application/x-httpd-php .php
 DirectoryIndex index.html index.htm index.php

    3. If you are using Apache 2.x, add the following lines to your
       httpd.conf file in the c:\apache2\conf directory:

 LoadModule php4_module c:\php\sapi\php4apache2.dll
 AddType application/x-httpd-php .php
 DirectoryIndex index.html index.htm index.php

   Configure the Webserver (IIS)

    1. Start the Microsoft Management Console, right click on Default Web
       Server (in most cases) and select Properties.

    2. Under the Home Directory tab, select Configuration and click Add.
       Browse to the path of php4isapi.dll, and type in .php as the
       extension.

    3. Under the ISAPI Filters tab, click Add and browse to the php4isapi.dll
       file. Name the filter "php" and click OK.

    4. Under the Documents tab, add index.php to the list.

    5. Completely stop and start the IIS service using the following
       commands:

 net stop iisadmin
 net start w3svc

   Install MySQL

    1. Extract the MySQL zip file to a temp directory and run setup.exe.

    2. Install MySQL to the c:\mysql directory.

    3. Start MySQL by running c:\mysql\bin\winmysqladmin.exe.

    4. Set a password for the root user

 shell> cd mysql\bin
 shell> mysqladmin ?-user=root password somepassword
 shell> mysqladmin --user=root --password reload

    5. Create the MySQL database:

 shell> mysqladmin --user=root --password create cacti

    6. Import the default Cacti database:

 shell> mysql --user=root --password cacti < c:\apache2\htdocs\cacti\cacti.sql

    7. Optional: Create a MySQL username and password for Cacti.

 shell> mysql --user=root --password mysql
 mysql> GRANT ALL ON cacti.* TO cactiuser@localhost IDENTIFIED BY 'somepassword';
 mysql> flush privileges;

   Install Cacti

    1. Extract the distribution archive. These instructions will assume that
       the archive has been extracted to C:\Apache\htdocs\cacti, although you
       can use a different path if you wish. Make sure you extract with "Use
       folder names" enabled, so that the necessary sub-folders will be used.

    2. Unzip rrdtool and copy rrdtool.exe from the src/tool_release directory
       to somewhere such as C:\rrdtool.

    3. Edit include/config.php and specify the MySQL user, password and
       database for your Cacti configuration.

 $database_default = "cacti";
 $database_hostname = "localhost";
 $database_username = "cactiuser";
 $database_password = "cacti";

    4. You are going to need to schedule a task, so cmd.php can run every 5
       minutes. Make sure the Task Scheduler service is started and open up
       the Scheduled Tasks control panel item. Add a new task, browse to your
       php.exe file and click Next. Have the task run daily (for now) and
       click Next twice until you are at the username/password screen. You
       must enter a user that has read/write permissions to Cacti's rra/ and
       log/ directories here. Click Next, check the box to open Advanced
       Properties and click Finish.

       You are going to have to enter the full command line in the Run
       textbox. Using default paths, your command line should look something
       like:

 c:\php\php.exe c:\apache2\htdocs\cacti\cmd.php

       Select the Schedule tab and click Advanced. Check the Repeat task
       checkbox and change it to every 5 minutes, then change the Duration to
       24 hours. That should schedule cmd.php to run every 5 minutes.

    5. Point your web browser to:

         http://your-server/cacti/

       Log in the with a username/password of admin. You will be required to
       change this password immediately. Using the default paths described in
       this document, your paths should look something like:

       PHP Binary Path:

 c:\php\php.exe

       RRDTool Binary Path:

 c:\rrdtool\rrdtool.exe

     ----------------------------------------------------------------------

                           Chapter 4. Upgrading Cacti

    1. Backup the old Cacti database.

 shell> mysqldump cacti > mysql.cacti

    2. Backup the old Cacti directory.

 shell> mv cacti cacti_old

    3. Extract the distribution tarball.

 shell> tar xzvf cacti-version.tar.gz

    4. Rename the new Cacti directory to match the old one.

 shell> mv cacti-version cacti

    5. Edit include/config.php and specify the MySQL user, password and
       database for your Cacti configuration.

 $database_default = "cacti";
 $database_hostname = "localhost";
 $database_username = "cactiuser";
 $database_password = "cacti";

    6. Copy the *.rrd files from the old cacti directory.

 shell> cp cacti_old/rra/* cacti/rra/

    7. Set the appropriate permissions on Cacti's directories for graph/log
       generation. You should execute these commands from inside Cacti's
       directory to change the permissions.

 shell> chown -R cactiuser rra/ log/

       (Enter a valid username for cactiuser, this user will also be used in
       the next step for data gathering.)

    8. Point your web browser to:

         http://your-server/cacti/

       Follow the on-screen instructions so your database can be updated to
       the new version.

     ----------------------------------------------------------------------

                           Chapter 5. Graph Overview

   Almost everything in Cacti is somehow related to a graph. At any time, you
   can list all available graphs by clicking on the Graph Management menu
   item. While it is possible to manually create graphs through this screen,
   new users should follow the instructions provided in the next chapter for
   creating new graphs in Cacti.

   For users that are familiar with RRDTool , you will immediately recognize
   that a graph in Cacti is closely modeled after RRDTool's graphs. This
   makes sense since Cacti provides a user friendly interface to RRDTool
   without requiring users to understand how RRDTool works. With this in
   mind, every graph in Cacti has certain settings and at least one graph
   item associated with it. While graph settings define the overall
   properties of a graph, the graph items define the data that is to be
   represented on the graph. So the graph items define which data to display
   and how it should displayed, and also define what should be displayed on
   the legend.

   Each graph and graph item has a set of parameters which control various
   aspects of the graph. Fortunately through the use of graph templates, it
   is not necessary to understand the function of each field to create graphs
   for your network. When you are ready to take on the task of creating your
   own graph templates, extensive field descriptions for both graphs and
   graph items are provided in that section of the manual.

     ----------------------------------------------------------------------

                      Chapter 6. How to Graph Your Network

   At this point, you probably realize that graphing is Cacti's greatest
   strength. Cacti has many powerful features that provide complex graphing
   and data acquisition, some which have a slight learning curve. Do not let
   that stop you however, because graphing your network is incredibly simple.

   The next two sections will outline the two basic steps which are typically
   required to create graphs for most devices.

     ----------------------------------------------------------------------

Creating a Device

   The first step to creating graphs for your network is adding a device for
   each network device that you want to create graphs for. A device specifies
   important details such as the network hostname, SNMP parameters, and host
   type.

   To manage devices within Cacti, click on the Devices menu item. Clicking
   Add will bring up a new device form. The first two fields, Description and
   Hostname are the only two fields that require your input beyond the
   defaults. If your host type is defined under the host template dropdown,
   be sure to select it here. You can always choose "Generic SNMP-enabled
   Host" if you are just graphing traffic or "None" if you are unsure. It is
   important to remember that the host template you choose will not lock you
   into any particular configuration, it will just provide more intelligent
   defaults for that type of host.

   Figure 6-1. Adding a New Device

   After saving your new device, you should be redirected back to the same
   edit form with some additional information. If you configured SNMP for
   this host by providing a valid community string, you should see various
   statistics listed at the top of the page. If you see "SNMP error" instead,
   this indicates an SNMP problem between Cacti and your device.

   Towards the bottom of the page there will be two addition boxes,
   Associated Data Queries, and Associated Graph Templates. If you selected a
   host template on the previous page, there will probably be a few items in
   each box. If there is nothing listed in either box, you will need to
   associate at least one data query or graph template with your new device
   or you will not be able to create graphs in the next step. If no available
   graph template or data query applies to your device, you can check the
   Cacti templates repository or create your own if nothing currently exists.

     ----------------------------------------------------------------------

  A Word About SNMP

   The SNMP version that you choose can have a great effect on how SNMP works
   for you in Cacti. Version 1 should be used for everything unless you have
   reason to choose otherwise. If you plan on utilizing (and your device
   supports) high-speed (64-bit) counters, you must select version 2. At the
   present time, version 3 is not fully implemented and will not work.

   The way in which Cacti retrieves SNMP information from a host has an
   effect on which SNMP-related options are supported. Currently there are
   three types of SNMP retrieval methods in Cacti and are outlined below.

   Table 6-1. SNMP Retrieval Types

   +------------------------------------------------------------------------+
   |     Type      |     Description      |   Supported    |  Places Used   |
   |               |                      |    Options     |                |
   |---------------+----------------------+----------------+----------------|
   | External SNMP | Calls the net-snmp   | All SNMP       | Web interface  |
   |               | snmpwalk and snmpget | options        | and PHP poller |
   |               | binaries that are    |                | (cmd.php)      |
   |               | installed on your    |                |                |
   |               | system.              |                |                |
   |---------------+----------------------+----------------+----------------|
   | Internal SNMP | Uses PHP's SNMP      | Version 1 Only | Web interface  |
   | (php-snmp)    | functions which are  | (Community and | and PHP poller |
   |               | linked against       | Port)          | (cmd.php)      |
   |               | net-snmp or ucd-snmp |                |                |
   |               | at compile time.     |                |                |
   |---------------+----------------------+----------------+----------------|
   | Cactid SNMP   | Links directly       | All SNMP       | C-Based Poller |
   |               | against net-snmp or  | options        | (cactid)       |
   |               | ucd-snmp and calls   |                |                |
   |               | the API directly.    |                |                |
   +------------------------------------------------------------------------+

     ----------------------------------------------------------------------

Creating the Graphs

   Now that you have created some devices, it is time to create graphs for
   these devices. To do this, select the New Graphs menu option under the
   Create heading. You will see a screen similar to the image pictured below.

   Figure 6-2. Creating New Graphs

   The dropdown menu that contains each device should be used to select the
   host that you want to create new graphs for. The basic concept to this
   page is simple, place a check in each row that you want to create a graph
   for and click Create.

   If you are creating graphs from inside a "Data Query" box, there are a few
   additional things to keep in mind. First is that you may encounter the
   situation as pictured above with the "SNMP - Interface Statistics" data
   query. If this occurs you may want to consult the section on debugging
   data queries to see why your data query is not returning any results.
   Also, you may see a "Select a graph type" dropdown box under some data
   query boxes. Changing the value of this dropdown box affects which type of
   graph Cacti will make after clicking the Create button. Cacti only
   displays this dropdown box when there is more than one type to choose
   from, so it may not be displayed in all cases.

   Once you have selected the graphs that you want to create, simply click
   the Create button at the bottom of the page. You will be taken to a new
   page that allows you to specify additional information about the graphs
   you are about to create. You only see the fields here that are not part of
   each template, otherwise the value automatically comes from the template.
   When all of the values on this page look correct, click the Create button
   one last time to actually create your graphs.

   If you would like to edit or delete your graphs after they have been
   created, use the Graph Management item on the menu. Likewise, the Data
   Source menu item allows you to manage your data sources in Cacti.

     ----------------------------------------------------------------------

                           Chapter 7. Viewing Graphs

Graph Trees

   A graph tree can be thought of as a hierarchical way of organizing your
   graphs. Each graph tree consists of zero or more headers or branch nodes
   that contain leaf nodes such as graphs or trees. Multiple graph trees or
   branches within a single tree can be combined to form a very powerful way
   of organizing your graphs.

     ----------------------------------------------------------------------

  Creating a Graph Tree

   To create a new graph tree, select the Graph Trees menu item under the
   Management header. Select Add on this page to create a new tree. The
   following page will prompt you for a tree name, which will be used to
   identify the graph tree throughout Cacti. Once you type a name, click the
   Create button to continue. You will be redirected to a page similar to the
   one below, but without all of the items.

   Figure 7-1. Editing a Graph Tree

   To start adding items to your tree, click add in the Tree Items box. There
   are currently three different types of tree items you can choose from:
   header, graph, or host. Simply choose the type you want, fill in the value
   for that type, and click Create to make your new graph tree item. Clicking
   the Add link to the right of any branch will add the new item below that
   branch, you can change the branch that any item belongs to by changing its
   Parent Item field.

     ----------------------------------------------------------------------

                           Chapter 8. User Management

   In addition to giving you the tools to create sophisticated graphs, Cacti
   enables you to create users that are tailored specifically to their
   requirements. Each user has certain settings such as login actions, as
   well as graph viewing settings. There are also two levels of permissions
   control, realm permissions and graph permissions which enable you to
   control what the user can see and change.

   Out of the box, there are two users that come with every Cacti
   installation. The "admin" user, is the main user that by default has
   access to see and change everything in Cacti. This is the user that you
   first login with in Cacti, and is probably a good idea to keep around
   unless you know otherwise. The second user is the "guest" user, which
   controls which areas/graphs are allowed for unauthenticated users. By
   default this user only has rights to view, but not change all graphs. This
   enables any unauthenticated user to visit 'graph_view.php' and view your
   graphs. This behavior can be changed by either changing the realm
   permissions for the "guest" user, or disabling the guest user altogether
   under Cacti Settings.

     ----------------------------------------------------------------------

Creating a New User

   To create a new user, select the User Management item under the Utilities
   heading on the Cacti menu. Once at the user management screen, click Add.
   You will see a screen that looks similar to the image below.

   Figure 8-1. Adding a User

   At minimum, you must specify a User Name and a Password for each user.
   Each user field is described in more detail below. In addition to these
   fields, each user can have their own realm permissions", graph
   permissions, and graph settings. Each of these items are described in this
   section of the manual.

   Table 8-1. Field Description: User Management

   +------------------------------------------------------------------------+
   |      Name       |                     Description                      |
   |-----------------+------------------------------------------------------|
   | User Name       | This field contains the actual login name for the    |
   |                 | user. There are no character limits this field, but  |
   |                 | it would make sense to keep it to alphanumeric       |
   |                 | characters to maintain simplicity.                   |
   |-----------------+------------------------------------------------------|
   | Full Name       | (Optional) You can use this field as a more          |
   |                 | descriptive identifier for the user. It is currently |
   |                 | only used for display on the user management page.   |
   |-----------------+------------------------------------------------------|
   | Password        | Enter the password for the user twice, once in each  |
   |                 | text box. Keep in mind that passwords are case       |
   |                 | sensitive and the password will remain unchanged if  |
   |                 | the boxes are both left empty.                       |
   |-----------------+------------------------------------------------------|
   | Account Options | There are currently two account related options that |
   |                 | can be set for each user. The first, 'User Must      |
   |                 | Change Password at Next Login', forces a password    |
   |                 | change immediately after the user logs in. The       |
   |                 | second option, 'Allow this User to Keep Custom Graph |
   |                 | Settings', dictates whether the user can maintain    |
   |                 | their own custom graph viewing settings which        |
   |                 | includes expanding and collapsing trees.             |
   |-----------------+------------------------------------------------------|
   | Graph Options   | There are three permission related options that can  |
   |                 | be set for each user here. The 'User Has Rights to   |
   |                 | {Tree,List,Preview} View' checkboxes dictate which   |
   |                 | graph viewing areas the user can see.                |
   |-----------------+------------------------------------------------------|
   | Login Options   | These options dictate what occurs immediately after  |
   |                 | the user logs in. The first option, 'Show the page   |
   |                 | that user pointed their browser to.' will point the  |
   |                 | user to whatever page they were heading to before    |
   |                 | being interrupted by the login page. The 'Show the   |
   |                 | default console screen.' option will always point    |
   |                 | the user to 'index.php' after a successful login.    |
   |                 | The last option, 'Show the default graph screen.'    |
   |                 | will point the user to 'graph_view.php' after a      |
   |                 | successful login.                                    |
   +------------------------------------------------------------------------+

     ----------------------------------------------------------------------

Realm Permissions

   Realm permissions control which areas of Cacti a user can access. You can
   edit a user's realm permissions by selecting User Management and choosing
   the user you want to edit the permissions for. The Realm Permissions box
   will be displayed in the lower part of the screen. Each "realm" is a
   grouping that represents common tasks in Cacti, making it easier to fine
   tune each user's access.

   If you want to create a user that can only view graphs, you should select
   the View Graphs realm and leave everything else unchecked. See the Graph
   Permissions section for more information about how to fine tune this even
   more on a per-graph basis. Conversely, if the user needs to access the
   console, they will need Console Access and any additional realms that you
   see fit.

     ----------------------------------------------------------------------

Graph Permissions

   Graph permissions control which graphs a user is allowed to view, it does
   not apply to editing graphs. You can edit a user's graph permissions by
   selecting User Management and choosing the user you want to edit the
   permissions for. Now select the Graph Permissions tab to view this user's
   graph permissions. There are three different ways that you can apply graph
   permissions, by graph, by host, or by graph template. This works by
   allowing or denying the user to all graphs associated with the particular
   group. So you can deny a user to a single graph, all graphs associated
   with a particular host, or all graphs associated with a particular graph
   template. Combining these three types of assigning graph permissions
   results in a very powerful graph policy editor.

   Each assignment type contains a Default Policy dropdown which can be used
   to control whether the user should be allowed to view everything or be
   denied from everything by default in the particular group. It is very
   important to remember that these policies are evaluated in the order:
   graph, host, graph template. Therefore, if you set graph's default policy
   to Deny, but kept host and graph template at Allow, the user's effective
   policy would be Deny since the graph assignment type is evaluated first.
   You typically either want to set all default policies to Deny for a
   restrictive user, or Allow for a non-restrictive user. If you thoroughly
   understand Cacti's graph permissions system, these default policies can be
   combined to provide very complex results.

     ----------------------------------------------------------------------

Graph Settings

   Cacti stores certain graph viewing settings for each user, which enables
   each user to view graphs in an optimal way. These preferences controls
   things such as the preview graph size or the default graph viewing mode to
   use. In addition to managing these settings here under user management,
   each user can change their own settings by clicking on the Graphs tab and
   selecting the Settings tab on the following page. If you want to prevent a
   user from being able to keep their own graph preferences, uncheck the
   Allow this User to Keep Custom Graph Settings checkbox in user management.
   The user will be presented with an "Access Denied" error message if they
   attempt to click the Settings tab when this box is checked.

     ----------------------------------------------------------------------

                         Chapter 9. Data Input Methods

   Data input methods allow Cacti to retrieve data to insert into data
   sources and ultimately put on a graph. There are different ways for Cacti
   to retrieve data, the most popular being through an external script or
   from SNMP.

     ----------------------------------------------------------------------

Creating a Data Input Method

   To create a new data input method, select the Data Input Methods option
   under the Management heading. Once on that screen, click Add on the right.
   You will be presented with a few fields to populate on the following
   screen.

   Table 9-1. Field Description: Data Input Methods

   +------------------------------------------------------------------------+
   |     Name      |                      Description                       |
   |---------------+--------------------------------------------------------|
   | Name          | Give the data query a name that you will use to        |
   |               | identify it. This name will be used throughout Cacti   |
   |               | to identify the data input method.                     |
   |---------------+--------------------------------------------------------|
   | Input Type    | Select the type of data input method you are trying to |
   |               | create. Valid options here are 'Script/Command',       |
   |               | 'SNMP', 'SNMP Query', and 'Script Query'.              |
   |---------------+--------------------------------------------------------|
   | Input String  | This field is only used when the Input Type is set to  |
   |               | 'Script/Command'. It specifies the full path to the    |
   |               | script including any per data source variables inside  |
   |               | <>'s from the user. For instance, if you are passing   |
   |               | an IP address to a script, your input string might     |
   |               | look something like:                                   |
   |               |                                                        |
   |               | /path/to/script.pl <ip>                                |
   |               |                                                        |
   |               | When the user creates a data source based on this data |
   |               | input method, they will be prompted for an IP address  |
   |               | to pass onto the script.                               |
   |---------------+--------------------------------------------------------|
   | Output String | This field is only here for legacy purposes and will   |
   |               | probably go away in a future version of Cacti.         |
   +------------------------------------------------------------------------+

   When you are finished filling in all necessary fields, click the Create
   button to continue. You will be redirected back to the same page, but this
   time with two new boxes, Input Fields and Output Fields. The Input Fields
   box is used to define any fields that require information from the user.
   Any input fields referenced to in the input string must be defined here.
   The Output Fields box is used to define each field that you expect back
   from the script. All data input methods must have at least one output
   field defined, but may have more for a script.

     ----------------------------------------------------------------------

  Data Input Fields

   To define a new field, click Add next to the input or output field boxes.
   You will be presented with some or all of the fields below depending on
   whether you are adding an input or output field.

   Table 9-2. Field Description: Data Input Fields

   +------------------------------------------------------------------------+
   |       Name       |                     Description                     |
   |------------------+-----------------------------------------------------|
   | Field/Field Name | Either select or type in the name of the field you  |
   |                  | want to define. No spaces or other non-alphanumeric |
   |                  | characters (except '-' or '_') should be used in    |
   |                  | this field.                                         |
   |------------------+-----------------------------------------------------|
   | Friendly Name    | Enter a more descriptive name for this field which  |
   |                  | will be used for identification throughout Cacti.   |
   |------------------+-----------------------------------------------------|
   | Regular          | If you want to enforce a certain regular expression |
   | Expression Match | pattern when the user enters a value for this       |
   | (Input Only)     | field, enter it here. The regular expression must   |
   |                  | follow POSIX syntax as it will be passed to PHP's   |
   |                  | ereg() function.                                    |
   |------------------+-----------------------------------------------------|
   | Allow Empty      | Select whether you want to allow the user to leave  |
   | Input (Input     | the value of this field blank or not.               |
   | Only)            |                                                     |
   |------------------+-----------------------------------------------------|
   | Special Type     | Sometimes Cacti needs to reference a field          |
   | Code (Input      | internally, but needs to rely on more than just the |
   | Only)            | field name. For instance, if your field requires an |
   |                  | IP address from the user, you can enter             |
   |                  | 'management_ip' here and Cacti will fill this field |
   |                  | in with the current IP address of the selected      |
   |                  | host. Valid values for this field are: 'hostname',  |
   |                  | 'management_ip', 'snmp_community', 'snmp_username', |
   |                  | 'snmp_password', and 'snmp_version'.                |
   |------------------+-----------------------------------------------------|
   | Update RRD File  | Check this box if you want Cacti to insert the      |
   | (Output Only)    | return value from this field into the RRD file.     |
   |                  | Obviously, this box needs to be checked for at      |
   |                  | least one output field per data input source, but   |
   |                  | can be left blank to have Cacti store the value in  |
   |                  | the database instead.                               |
   +------------------------------------------------------------------------+

   When you are finished filling in all necessary fields, click the Create
   button to continue. You will be redirected back to the data input method
   edit page. From here you can continue to add additional fields, or click
   Save on this screen when finished.

     ----------------------------------------------------------------------

Making Your Scripts Work With Cacti

   The simplest way to extend Cacti's data gathering functionality is through
   external scripts. Cacti comes with a number of scripts out of the box
   which are located in the scripts/ directory. These scripts are used by the
   data input methods that are present in a new installation of Cacti.

   To have Cacti call an external script to gather data you must create a new
   data input method, making sure to specify Script/Command for the Input
   Type field. See the previous section, Creating a Data Input Method for
   more information about how to create a data input method. To gather data
   using your data input method, Cacti simply executes the shell command
   specified in the Input String field. Because of this, you can have Cacti
   run any shell command or call any script which can be written in almost
   any language.

   What Cacti is concerned with is the output of the script. When you define
   your data input method, you are required to define one or more output
   fields. The number of output fields that you define here is important to
   your script's output. For a data input method with only one output field,
   your script should output its value in the following format:

 <value_1>

   So if I wrote a script that outputs the number of running processes, its
   output might look like the following:

   Example 9-1. Example script output using 1 field

   67

   Data input methods with more than one output field are handled a bit
   differently when writing scripts. Scripts that output more than one value
   should be formatted like the following:

 <fieldname_1>:<value_1> <fieldname_2>:<value_2> ... <fieldname_n>:<value_n>

   Lets say that I write a script that outputs the 1, 5, and 10 minute load
   average of a Unix machine. In Cacti, I name the output fields '1min',
   '5min', and '10min', respectively. Based on these two things, the output
   of the script should look like the following:

   Example 9-2. Example script output using 3 fields

   1min:0.40 5min:0.32 10min:0.01

   One last thing to keep in mind when writing scripts for Cacti is that they
   will be executed as the user the data gatherer runs as. Sometimes a script
   may work correctly when executed as root, but fails due to permissions
   problems when executed as a less privileged user.

     ----------------------------------------------------------------------

                            Chapter 10. Data Queries

   Data queries are not a replacement for data input methods in Cacti.
   Instead they provide an easy way to query, or list data based upon an
   index, making the data easier to graph. The most common use of a data
   query within Cacti is to retrieve a list of network interfaces via SNMP.
   If you want to graph the traffic of a network interface, first Cacti must
   retrieve a list of interfaces on the host. Second, Cacti can use that
   information to create the necessary graphs and data sources. Data queries
   are only concerned with the first step of the process, that is obtaining a
   list of network interfaces and not creating the graphs/data sources for
   them. While listing network interfaces is a common use for data queries,
   they also have other uses such as listing partitions, processors, or even
   cards in a router.

   One requirement for any data query in Cacti, is that it has some unique
   value that defines each row in the list. This concept follows that of a
   'primary key' in SQL, and makes sure that each row in the list can be
   uniquely referenced. Examples of these index values are 'ifIndex' for SNMP
   network interfaces or the device name for partitions.

   There are two types of data queries that you will see referred to
   throughout Cacti. They are script queries and SNMP queries. Script and
   SNMP queries are virtually identical in their functionality and only
   differ in how they obtain their information. A script query will call an
   external command or script and an SNMP query will make an SNMP call to
   retrieve a list of data.

   All data queries have two parts, the XML file and the definition within
   Cacti. An XML file must be created for each query, that defines where each
   piece of information is and how to retrieve it. This could be thought of
   as the actual query. The second part is a definition within Cacti, which
   tells Cacti where to find the XML file and associates the data query with
   one or more graph templates.

     ----------------------------------------------------------------------

Creating a Data Query

   Once you have created the XML file that defines your data query, you must
   add the data query within Cacti. To do this you must click on Data Queries
   under the Data Gathering heading, and select Add. You will be prompted for
   some basic information about the data query, described in more detail
   below.

   Table 10-1. Field Description: Data Queries

   +------------------------------------------------------------------------+
   |    Name     |                       Description                        |
   |-------------+----------------------------------------------------------|
   | Name        | Give the data query a name that you will use to identify |
   |             | it. This name will be used throughout Cacti when         |
   |             | presented with a list of data queries.                   |
   |-------------+----------------------------------------------------------|
   | Description | (Optional) Enter a more detailed description of the data |
   |             | query including the information it queries or additional |
   |             | requirements.                                            |
   |-------------+----------------------------------------------------------|
   | XML Path    | Fill in the full path to the XML file that defines this  |
   |             | query. You can optionally use the <path_cacti> variable  |
   |             | that will be substituted with the full path to Cacti. On |
   |             | the next screen, Cacti will check to make sure that it   |
   |             | can find the XML file.                                   |
   |-------------+----------------------------------------------------------|
   | Data Input  | This is how you tell Cacti to handle the data it         |
   | Method      | receives from the data query. Typically, you will select |
   |             | "Get SNMP Data (Indexed)" for an SNMP query and "Get     |
   |             | Script Data (Indexed)" for a script query.               |
   +------------------------------------------------------------------------+

   When you are finished filling in all necessary fields, click the Create
   button to continue. You will be redirected back to the same page, but this
   time with some additional information to fill in. If you receive a red
   warning that says 'XML File Does Not Exist', correct the value specified
   in the 'XML Path' field.

   Under the Data Input Method box, you need to specify mappings that tell
   Cacti where to send data it recieves from the data query. There are three
   data source fields that Cacti cares about when referring to a data query;
   index type, index value, and output type ID. Index type refers to the name
   of the input field to search in, while the index value contains the value
   to search for in that field. Lastly, output type ID specifies the ID of
   the "Associated Graph Template" to use. You do not have to worry about
   filling in values for these fields when creating data sources, Cacti will
   do that for you. Below are the default mappings that will work in almost
   all cases:

   Table 10-2. Data Input Method Mappings

   +------------------------------------------------------------------------+
   |           Name           |                    Value                    |
   |--------------------------+---------------------------------------------|
   | Index Type:              | SNMP Field Name (Dropdown)                  |
   |--------------------------+---------------------------------------------|
   | Index Value:             | SNMP Field Value (From User)                |
   |--------------------------+---------------------------------------------|
   | Output Type ID:          | SNMP Output Type (Dropdown)                 |
   +------------------------------------------------------------------------+

   Make sure to check the checkboxes to the right of these three fields, or
   the mappings will not be saved.

     ----------------------------------------------------------------------

  Associated Graph Templates

   Every data query must have at least one graph template associated with it,
   and possibly more depending on the number of output fields specified in
   the XML file. This is where you get to choose what kind of graphs to
   generate from this query. For instance, the interface data query has
   multiple graph template associations, used to graph traffic, errors, or
   packets. To add a new graph template association, simply click Add at the
   right of the Associated Graph Templates box. You will be presented with a
   few fields to fill in:

   Table 10-3. Field Description: Associated Graph Templates

   +------------------------------------------------------------------------+
   |      Name      |                      Description                      |
   |----------------+-------------------------------------------------------|
   | Name           | Give a name describing what kind of data you are      |
   |                | trying to represent or graph. When the user creates a |
   |                | graph using this data query, they will see a list of  |
   |                | graph template associations that they will have to    |
   |                | choose from.                                          |
   |----------------+-------------------------------------------------------|
   | Graph Template | Choose the actual graph template that you want to     |
   |                | make the association with.                            |
   +------------------------------------------------------------------------+

   When you are finished filling in these fields, click the Create button.
   You will be redirected back to the same page with some additional
   information to fill in. Cacti will make a list of each data template
   referenced to in your selected graph template and display them under the
   Associated Data Templates box. For each data source item listed, you must
   selected the data query output field that corresponds with it. Do not
   forget to check the checkbox to the right of each selection, or your
   settings will not be saved.

   The Suggested Values box gives you a way to control field values of data
   sources and graphs created using this data query. If you specify multiple
   suggested values for the same field, Cacti will evaluate them in order
   which you can control using the up or down arrow icons. For more
   information about valid field names and variables, read the section on
   suggested values.

   When you are finished filling in all necessary fields on this form, click
   the Save button to return to the data queries edit screen. Repeat the
   steps under this heading as many times as necessary to represent all data
   in your XML file. When you are finished with this, you should be ready to
   start adding your data query to hosts.

     ----------------------------------------------------------------------

SNMP Query XML Syntax

 <query>
    <name>Get SNMP Interfaces</name>
    <description>Queries a host for a list of monitorable interfaces</description>
    <oid_index>.1.3.6.1.2.1.2.2.1.1</oid_index>

    <fields>
       <ifIndex>
          <name>Index</name>
          <method>walk</method>
          <source>value</source>
          <direction>input</direction>
          <oid>.1.3.6.1.2.1.2.2.1.1</oid>
       </ifIndex>
    </fields>
 </query>

   Table 10-4. SNMP Query XML Field Reference

   +------------------------------------------------------------------------+
   |               Field               |            Description             |
   |-----------------------------------+------------------------------------|
   | query->name                       | (Optional) You can enter a         |
   |                                   | "friendly name" for the SNMP query |
   |                                   | here. It will not be used by       |
   |                                   | Cacti, and is for identification   |
   |                                   | only.                              |
   |-----------------------------------+------------------------------------|
   | query->description                | (Optional) You can enter a         |
   |                                   | description for the SNMP query     |
   |                                   | here. It will not be used by       |
   |                                   | Cacti, and is for identification   |
   |                                   | only.                              |
   |-----------------------------------+------------------------------------|
   | query->oid_index                  | Every SNMP query must have an OID  |
   |                                   | that represents the index values   |
   |                                   | for the query when walked. As      |
   |                                   | described above, any data query in |
   |                                   | Cacti must contain a field that    |
   |                                   | uniquely identifies each row       |
   |                                   | returned by the query. In the      |
   |                                   | example above, the oid_index       |
   |                                   | points to the OID of ifIndex in    |
   |                                   | the interface MIB.                 |
   |-----------------------------------+------------------------------------|
   | query->fields                     | Each field contained within the    |
   |                                   | SNMP query must be defined under   |
   |                                   | this tag.                          |
   |-----------------------------------+------------------------------------|
   | query->fields->ifIndex            | Each defined field in the SNMP     |
   |                                   | query must have a unique name      |
   |                                   | given to it. Do not use spaces or  |
   |                                   | any non-alphanumeric characters,   |
   |                                   | this name must be identifiable     |
   |                                   | within Cacti.                      |
   |-----------------------------------+------------------------------------|
   | query->fields->ifIndex->name      | Here you can specify a "friendly   |
   |                                   | name" for the field. This name     |
   |                                   | will be used by Cacti to help the  |
   |                                   | user identify this field.          |
   |-----------------------------------+------------------------------------|
   | query->fields->ifIndex->method    | Tell Cacti how you want it to      |
   |                                   | gather SNMP information for this   |
   |                                   | field. Valid values are 'walk' and |
   |                                   | 'get'. The 'get' method obtains a  |
   |                                   | list of indexes and does an        |
   |                                   | snmpget for each index of the OID  |
   |                                   | specified for this field. The walk |
   |                                   | method simply does a walk of the   |
   |                                   | OID specified for this field. Both |
   |                                   | methods will return the same       |
   |                                   | values, even though the 'walk'     |
   |                                   | method is typically more           |
   |                                   | efficient.                         |
   |-----------------------------------+------------------------------------|
   | query->fields->ifIndex->source    | When Cacti obtains a list for this |
   |                                   | field, you need to tell it how to  |
   |                                   | derive its value for each row.     |
   |                                   | Valid options here are 'value',    |
   |                                   | 'OID/REGEXP:(regexp_match)', and   |
   |                                   | 'VALUE/REGEXP:(regexp_match)'. The |
   |                                   | 'value' option simply returns the  |
   |                                   | result of the snmpget for each     |
   |                                   | row. The                           |
   |                                   | 'OID/REGEXP:(regexp_match)' can be |
   |                                   | used when you need to use a        |
   |                                   | POSIX-based regular expression to  |
   |                                   | derive the value from the OID. The |
   |                                   | most common example of this is to  |
   |                                   | retreive the IP address of an      |
   |                                   | interface, and can be seen in the  |
   |                                   | 'interface.xml' file. Finally, the |
   |                                   | 'OID/REGEXP:(regexp_match)' option |
   |                                   | can be used to parse the value     |
   |                                   | based on a regular expression,     |
   |                                   | returning the first match.         |
   |-----------------------------------+------------------------------------|
   | query->fields->ifIndex->direction | There are two types of fields when |
   |                                   | dealing with an SNMP query,        |
   |                                   | 'input' and 'output'. Input values |
   |                                   | are the "known" values that you    |
   |                                   | will use to derive the output      |
   |                                   | values, this is where the "query"  |
   |                                   | part of SNMP query comes in. When  |
   |                                   | you create a graph based on an     |
   |                                   | SNMP query, Cacti will prompt you  |
   |                                   | to choose the input value to base  |
   |                                   | the graph on. A rule of thumb is   |
   |                                   | that input fields contain          |
   |                                   | semi-static data that is not       |
   |                                   | graphable, while the output fields |
   |                                   | contain the data that will be      |
   |                                   | graphed.                           |
   |-----------------------------------+------------------------------------|
   | query->fields->ifIndex->oid       | You must specify the actual OID    |
   |                                   | that corresponds with the field.   |
   |                                   | Each value for this field can be   |
   |                                   | obtained by doing an snmpget on    |
   |                                   | 'oid.(each)snmpindex'.             |
   +------------------------------------------------------------------------+

     ----------------------------------------------------------------------

Script Query XML Syntax

 <query>
    <name>Get Unix Mounted Partitions</name>
    <description>Queries a list of mounted partitions on a unix-based host with the 'df' command.</description>
    <script_path>perl |path_cacti|/scripts/query_unix_partitions.pl</script_path>
    <arg_index>index</arg_index>
    <arg_query>query</arg_query>
    <arg_get>get</arg_get>
    <output_delimeter>:</output_delimeter>
   
    <fields>
       <dskDevice>
          <name>Device Name</name>
          <direction>input</direction>
          <query_name>device</query_name>
       </dskDevice>
    </fields>
 </query>

   Table 10-5. Script Query XML Field Reference

   +------------------------------------------------------------------------+
   |                Field                 |           Description           |
   |--------------------------------------+---------------------------------|
   | query->name                          | (Optional) You can enter a      |
   |                                      | "friendly name" for the script  |
   |                                      | query here. It will not be used |
   |                                      | by Cacti, and is for            |
   |                                      | identification only.            |
   |--------------------------------------+---------------------------------|
   | query->description                   | (Optional) You can enter a      |
   |                                      | description for the script      |
   |                                      | query here. It will not be used |
   |                                      | by Cacti, and is for            |
   |                                      | identification only.            |
   |--------------------------------------+---------------------------------|
   | query->script_path                   | Enter the complete path to the  |
   |                                      | script or executable that is    |
   |                                      | going to handle your script     |
   |                                      | query. When in doubt, specify   |
   |                                      | the pull path to all binaries   |
   |                                      | referenced in this path, the    |
   |                                      | query may not execute           |
   |                                      | otherwise.                      |
   |--------------------------------------+---------------------------------|
   | query->arg_index                     | Enter the argument that is to   |
   |                                      | be passed to the script to      |
   |                                      | retrieve a list of indexes.     |
   |--------------------------------------+---------------------------------|
   | query->arg_query                     | Enter the argument that is to   |
   |                                      | be passed to the script to      |
   |                                      | retrieve a list of values given |
   |                                      | a field name.                   |
   |--------------------------------------+---------------------------------|
   | query->arg_get                       | Enter the argument that is to   |
   |                                      | be passed to the script to      |
   |                                      | retrieve a single value given a |
   |                                      | field name and index value.     |
   |--------------------------------------+---------------------------------|
   | query->output_delimeter              | Enter the one character         |
   |                                      | delimiter that will be used to  |
   |                                      | separate output values. This is |
   |                                      | only used when you "query" the  |
   |                                      | script in which case it outputs |
   |                                      | 'index(delimiter)value'.        |
   |--------------------------------------+---------------------------------|
   | query->fields                        | Each field contained within the |
   |                                      | script query must be defined    |
   |                                      | under this tag.                 |
   |--------------------------------------+---------------------------------|
   | query->fields->dskDevice             | Each defined field in the       |
   |                                      | script query must have a unique |
   |                                      | name given to it. Do not use    |
   |                                      | spaces or any non-alphanumeric  |
   |                                      | characters, this name must be   |
   |                                      | identifiable within Cacti.      |
   |--------------------------------------+---------------------------------|
   | query->fields->dskDevice->name       | Here you can specify a          |
   |                                      | "friendly name" for the field.  |
   |                                      | This name will be used by Cacti |
   |                                      | to help the user identify this  |
   |                                      | field.                          |
   |--------------------------------------+---------------------------------|
   | query->fields->dskDevice->direction  | There are two types of fields   |
   |                                      | when dealing with an script     |
   |                                      | query, 'input' and 'output'.    |
   |                                      | Input values are the "known"    |
   |                                      | values that you will use to     |
   |                                      | derive the output values, this  |
   |                                      | is where the "query" part of    |
   |                                      | script query comes in. When you |
   |                                      | create a graph based on an      |
   |                                      | script query, Cacti will prompt |
   |                                      | you to choose the input value   |
   |                                      | to base the graph on. A rule of |
   |                                      | thumb is that input fields      |
   |                                      | contain semi-static data that   |
   |                                      | is not graphable, while the     |
   |                                      | output fields contain the data  |
   |                                      | that will be graphed.           |
   |--------------------------------------+---------------------------------|
   | query->fields->dskDevice->query_name | Enter the name that Cacti must  |
   |                                      | use when asking the script for  |
   |                                      | information about this field.   |
   |                                      | For instance, the following     |
   |                                      | should return values:           |
   |                                      | '(script_name) query            |
   |                                      | (query_name)'.                  |
   +------------------------------------------------------------------------+

     ----------------------------------------------------------------------

                             Chapter 11. Templates

Graph Templates

   In Cacti, a graph template provides a skeleton for an actual graph. If you
   have many graphs that share most of their characteristics, using a graph
   template would probably make sense. After a graph is attached to a
   particular graph template, all changes made to the graph template will
   propagate out to all of its graphs.

     ----------------------------------------------------------------------

  Creating a Graph Template

   To create a new graph template, select Graph Templates under the Templates
   heading and click Add.

   The first thing you must do is give the template a name. This name has
   nothing to do with the graph title, but is what you will use to identify
   the template throughout Cacti. Second, you will notice a list of graph
   field names with Use Per-Graph Value checkboxes next to each one. The nice
   thing about templates in Cacti is that you can choose whether to template
   each field on a per-field basis. If you leave the checkbox uncheked, every
   graph attached to the template will inherit its value from the template.
   If the checkbox is checked, every graph attached to the template will
   contain its own value for that particular field.

   Table 11-1. Field Description: Graph Templates

   +------------------------------------------------------------------------+
   |       Name       |                     Description                     |
   |------------------+-----------------------------------------------------|
   | Title            | The title of the graph within Cacti and the title   |
   |                  | that will be printed on the actual graph itself.    |
   |                  |                                                     |
   |                  | Note: You can use the keyword |host_description| in |
   |                  | this field, which will be automatically substituted |
   |                  | with the current host description.                  |
   |------------------+-----------------------------------------------------|
   | Image Format     | Choose whether you would prefer to output your      |
   |                  | graph images in PNG or GIF. According to the        |
   |                  | RRDTool graph manual PNG is preferred because it is |
   |                  | both smaller and faster.                            |
   |------------------+-----------------------------------------------------|
   | Height           | The height of the graph area in pixels              |
   |------------------+-----------------------------------------------------|
   | Width            | The width of the graph area in pixels               |
   |------------------+-----------------------------------------------------|
   | Auto Scale       | Enable auto scale for the graph. This option must   |
   |                  | be check to use the next two options. Upper/Lower   |
   |                  | limit values are ignored when using autoscale since |
   |                  | these boundaries are determined automatically.      |
   |------------------+-----------------------------------------------------|
   | Auto Scale       | Choose whether you would like to use                |
   | Options          | --alt-autoscale or --alt-autoscale-max on the       |
   |                  | graph. The RRDTool graph manual says: "Where        |
   |                  | --alt-autoscale will modify both the absolute       |
   |                  | maximum AND minimum values, this option will only   |
   |                  | affect the maximum value. The minimum value, if not |
   |                  | defined on the command line, will be 0. This option |
   |                  | can be useful when graphing router traffic when the |
   |                  | WAN line uses compression, and thus the throughput  |
   |                  | may be higher than the WAN line speed".             |
   |------------------+-----------------------------------------------------|
   | Logarithmic Auto | Choose if you want logarithmic y-axis scaling.      |
   | Scaling          |                                                     |
   |------------------+-----------------------------------------------------|
   | Rigid Boundaries | From the RRDTool manual "Normally rrdgraph will     |
   | Mode             | automatically expand the lower and upper limit if   |
   |                  | the graph contains a value outside the valid range. |
   |                  | With this option you can disable this behavior".    |
   |------------------+-----------------------------------------------------|
   | Auto Padding     | If you have ever created RRDTool-based graphs       |
   |                  | manually, you may have realized how annoying it can |
   |                  | be to get text to line up properly. With this       |
   |                  | option Cacti will do its best to make the columns   |
   |                  | on your graph legend line up. This option works     |
   |                  | best when your graph legend has a consistent number |
   |                  | of columns.                                         |
   |------------------+-----------------------------------------------------|
   | Allow Graph      | If you choose to use Cacti's static HTML/image      |
   | Export           | export, you can choose whether you want each        |
   |                  | individual graph to be exported.                    |
   |------------------+-----------------------------------------------------|
   | Upper Limit      | The maximum value that will be displayed on the     |
   |                  | y-axis. This value is ignored is auto-scaling is    |
   |                  | turned on.                                          |
   |------------------+-----------------------------------------------------|
   | Lower Limit      | The minimum value that will be displayed on the     |
   |                  | y-axis. This value is ignored is auto-scaling is    |
   |                  | turned on.                                          |
   |------------------+-----------------------------------------------------|
   | Base Value       | Whether you want to base the y-axis labels on 1000  |
   |                  | or 1024. This field will typically be set to 1024   |
   |                  | for memory and 1000 for traffic measurements.       |
   |------------------+-----------------------------------------------------|
   | Unit Value       | Sets the unit value for the y-axis. You should      |
   |                  | probably keep the unit short as to keep it          |
   |                  | readable.                                           |
   |------------------+-----------------------------------------------------|
   | Unit Exponent    | Sets the 10^e scaling of the y-axis. Valid values   |
   | Value            | for this field are between -18 and 18. For example, |
   |                  | you could use 3 to display everything in 'k' (kilo) |
   |                  | or -6 to display everything in 'u' (micro).         |
   |------------------+-----------------------------------------------------|
   | Vertical Label   | The text to print on the left edge of the graph.    |
   |                  | Usually is the units the data on the graph is       |
   |                  | measured in.                                        |
   +------------------------------------------------------------------------+

   Note: For most graph templates, you will want to check the Use Per-Graph
   Value checkbox for the title field so each graph using this template has
   its own unique title. It also makes sense to enter an initial value in
   this field that includes the variable |host_description| for
   organizational purposes.

   When you are finished filling in values for the graph template, click
   Create and you will be presented with a page similar to the graph edit
   page.

   Figure 11-1. Adding a Graph Template

     ----------------------------------------------------------------------

    Graph Items

   The first thing you should do is create graph items for this graph
   template, just like for a regular graph. One difference you will notice is
   that the Data Sources dropdown will contain a list of data template items
   rather than data source items. It is important that Cacti can make this
   association here, so that Cacti doesn't have to make unnecessary
   assumptions later.

   Table 11-2. Field Description: Graph Template Items

   +------------------------------------------------------------------------+
   |      Name       |                     Description                      |
   |-----------------+------------------------------------------------------|
   | Data Source     | If this graph item is to represent some sort of      |
   |                 | data, you must select a your data source here. Keep  |
   |                 | in mind that not all graph items have a data source. |
   |                 | Graph item types such as COMMENT, VRULE, and HRULE   |
   |                 | typically do not.                                    |
   |-----------------+------------------------------------------------------|
   | Color           | Depending on the graph item type, you can select a   |
   |                 | color for the graph item. This field only applies to |
   |                 | the graph item types AREA, STACK, LINE1, LINE2, and  |
   |                 | LINE3.                                               |
   |-----------------+------------------------------------------------------|
   | Graph Item Type | This field is important because it defines what kind |
   |                 | of graph item this is. Types such as AREA, STACK,    |
   |                 | LINE1, LINE2, and LINE3 are used to represent data   |
   |                 | on the graph, while COMMENT and GPRINT are used put  |
   |                 | on the legend. The LEGEND type is specific to Cacti  |
   |                 | only and can be used if you want to Cacti to         |
   |                 | automatically create a                               |
   |                 | GPRINT-LAST/GPRINT-AVERAGE/GPRINT-MAXIMUM graph item |
   |                 | for you.                                             |
   |                 |                                                      |
   |                 | Note:: You must always put an AREA item before using |
   |                 | STACK or your graph will not render.                 |
   |-----------------+------------------------------------------------------|
   | Consolidation   | This tells RRDTool which consolidation function to   |
   | Function        | use when representing this data on the graph. You    |
   |                 | will typically use AVERAGE for most things on the    |
   |                 | graph area, and LAST/MAXIMUM as well for GPRINT      |
   |                 | items.                                               |
   |-----------------+------------------------------------------------------|
   | CDEF Function   | If you want to apply a CDEF function to the graph    |
   |                 | item, select one here. Check out the CDEF section of |
   |                 | the manual for more information.                     |
   |-----------------+------------------------------------------------------|
   | Value           | This field is only used with the HRULE/VRULE graph   |
   |                 | item types. Type any valid integer to draw the line  |
   |                 | at for HRULE or the time of the day HH:MM for VRULE. |
   |-----------------+------------------------------------------------------|
   | GPRINT Type     | If this item is a GPRINT, you can choose how you     |
   |                 | want the number to be formatted. You can add your    |
   |                 | own in the GPRINT Presets section of Cacti.          |
   |-----------------+------------------------------------------------------|
   | Text Format     | You can enter text to be displayed on the legend     |
   |                 | here. This field is applicable for all graph item    |
   |                 | types except for the virtual LEGEND type.            |
   |-----------------+------------------------------------------------------|
   | Hard Return     | Check this box to force graph items onto the next    |
   |                 | line.                                                |
   +------------------------------------------------------------------------+

     ----------------------------------------------------------------------

    Graph Item Inputs

   After creating graph items for your template, you will need to create some
   graph item inputs. Graph item inputs are unique to graph templates because
   of the large number of items they sometimes contain. Graph item inputs
   enable you to take one graph item field, and associate it with multiple
   graph items.

   To create a new graph item input, click Add on the right of the Graph Item
   Inputs box. There are various fields that must be filled in for every
   graph item input:

   Table 11-3. Field Description: Graph Template Items

   +------------------------------------------------------------------------+
   |       Name       |                     Description                     |
   |------------------+-----------------------------------------------------|
   | Name             | This will be the name used to identify the graph    |
   |                  | item input on both the graph template and graph     |
   |                  | edit pages.                                         |
   |------------------+-----------------------------------------------------|
   | Description      | (Optional) This description will be displayed on    |
   |                  | the graph edit page of any graph using this         |
   |                  | template if specified.                              |
   |------------------+-----------------------------------------------------|
   | Field Type       | You must choose the field that you are going to     |
   |                  | associate with one or more graph items.             |
   |------------------+-----------------------------------------------------|
   | Associated Graph | Choose one or more graph items to associate with    |
   | Items            | the field selected for "Field Type". When the user  |
   |                  | specifies a value for the field, it will be applied |
   |                  | to all of the items you select here.                |
   +------------------------------------------------------------------------+

     ----------------------------------------------------------------------

  Applying Graph Templates to Graphs

   Applying a graph template to a graph is a very simple process. The first
   thing you must do is select the graph you want to apply the template to
   under Graph Management. Under the Graph Template Selection box, select the
   graph template that you want to apply to the graph and click Save. If this
   is a new graph or the graph and graph template contains an equal number of
   graph items, the graph template will be automatically applied. If number
   of graph items varies from the graph to the target graph template, you
   will be propmted with a warning that your graph will be changed.

   Once the template is applied to the graph, you will notice that you can
   only change values for the fields that you checked Use Per-Graph Value
   for. You will also notice a new box, called Graph Item Inputs. This is
   where you can specify values for the graph items inputs that you defined
   in the graph template. The values specified here will be applied to each
   graph item tied to the graph item input.

   Now any time a change is made to the graph template, it will be
   automatically propagated to the graphs attached to it.

     ----------------------------------------------------------------------

Data Templates

   In Cacti, a data template provides a skeleton for an actual data source.
   If you have many data sources that share most of their characteristics,
   using a data template would probably make sense. After a data source is
   attached to a particular data template, all changes made to the data
   template will propagate out to all of its data sources.

     ----------------------------------------------------------------------

  Creating a Data Template

   To create a new data template, select Data Templates under the Templates
   heading and click Add.

   The first thing you must do is give the template a name. This name has
   nothing to do with the data source name, but is what you will use to
   identify the template throughout Cacti. Second, you will notice a list of
   data source/data source item field names with Use Per-Data Source Value
   checkboxes next to each one. The nice thing about templates in Cacti is
   that you can choose whether to template each field on a per-field basis.
   If you leave the checkbox unchecked, every data source attached to the
   template will inherit its value from the template. If the checkbox is
   checked, every data source attached to the template will contain its own
   value for that particular field.

   Table 11-4. Field Description: Data Templates

   +------------------------------------------------------------------------+
   |       Name       |                     Description                     |
   |------------------+-----------------------------------------------------|
   | Name             | This is the name that cacti uses to identify this   |
   |                  | data source. You must type something here, but you  |
   |                  | may include spaces and other non-alphanumeric       |
   |                  | characters.                                         |
   |                  |                                                     |
   |                  | Note: You can use the keyword |host_description| in |
   |                  | this field, which will be automatically substituted |
   |                  | with the current host description.                  |
   |------------------+-----------------------------------------------------|
   | Data Source Path | The full path to the RRD file associated with this  |
   |                  | data source. When creating a new data source you    |
   |                  | will typically leave this field blank as Cacti will |
   |                  | generate one for you. If you are using an RRD file  |
   |                  | generated outside of Cacti, you need to specify it  |
   |                  | here.                                               |
   |------------------+-----------------------------------------------------|
   | Data Input       | Here is where you tell cacti how it is supposed to  |
   | Method           | fetch data for this data source. There are several  |
   |                  | data input sources that come with cacti, and you    |
   |                  | can add your own by going to Data Input Methods. If |
   |                  | this RRD file is being populated outside of cacti,  |
   |                  | make sure to leave this field set to "None".        |
   |------------------+-----------------------------------------------------|
   | Associated RRAs  | You need to associate the data source with at least |
   |                  | one RRA so RRDTool knows how often and for how long |
   |                  | to keep its data. You will almost always want to    |
   |                  | select all of these values however so you can       |
   |                  | render daily, weekly, monthly, and yearly graphs.   |
   |------------------+-----------------------------------------------------|
   | Step             | This tells RRDTool how many seconds there will be   |
   |                  | between updates. The default is 300 seconds (5      |
   |                  | minutes), and is sufficient for most installations. |
   |------------------+-----------------------------------------------------|
   | Data Source      | This is a quick and easy to tell Cacti to stop      |
   | Active           | gathering data for this data source. The data       |
   |                  | source can still be used on graphs, but no data     |
   |                  | will be fed to it until it is made active again.    |
   +------------------------------------------------------------------------+

   Note: For most data templates, you will want to check the Use Per-Graph
   Value checkbox for the name field so each data source using this template
   has its own unique name. It also makes sense to enter an inital value in
   this field that includes the variable |host_description| for
   organizational purposes.

   When you are finished filling in values for the data template, click
   Create and you will be presented with a screen similar to the data source
   edit screen.

   Figure 11-2. Adding a Data Template

     ----------------------------------------------------------------------

    Data Source Items

   Like a graph, a data source can have more than one items. This is useful
   in situations where a script returns more than piece of data at one time.
   This also applies to data queries, so you can have a single data template
   that contains both inbound and outbound traffic, rather than having to
   create a separate data template for each.

   Table 11-5. Field Description: Data Source Items

   +------------------------------------------------------------------------+
   |       Name       |                     Description                     |
   |------------------+-----------------------------------------------------|
   | Internal Data    | This is the name used by RRDTool to identify this   |
   | Source Name      | particular data source within the RRD file. RRDTool |
   |                  | places a limit of 19 alphanumeric characters (plus  |
   |                  | '_' and '-') on this field.                         |
   |------------------+-----------------------------------------------------|
   | Minimum Value    | Here is where you specify the minimum value that is |
   |                  | expected for this data source in the RRD file. If a |
   |                  | value lower than the minimum is given, it will be   |
   |                  | stored as Unknown (U).                              |
   |------------------+-----------------------------------------------------|
   | Maximum Value    | Here is where you specify the maximum value that is |
   |                  | expected for this data source in the RRD file. If a |
   |                  | value higher than the maximum is given, it will be  |
   |                  | stored as Unknown (U).                              |
   |------------------+-----------------------------------------------------|
   | Data Source Type | There are four types of data that RRDTool can       |
   |                  | represent for any given data source: COUNTER,       |
   |                  | GAUGE, ABSOLUTE, and DERIVE. A gauge is for numbers |
   |                  | that are not continuously incrementing. A counter   |
   |                  | is for continuously incrementing values that might  |
   |                  | overflow, while a derive does not overflow. The     |
   |                  | absolute type is used for counters that are reset   |
   |                  | upon reading.                                       |
   |------------------+-----------------------------------------------------|
   | Heartbeat        | As defined by RRDTool: "The maximum amount of time  |
   |                  | that can pass before data is entered as "unknown".  |
   |                  | This field is usually '600' or 2 data gathering     |
   |                  | intervals".                                         |
   +------------------------------------------------------------------------+

     ----------------------------------------------------------------------

    Custom Data

   Assuming you selected a data input source on the previous screen, you
   should now be presented with a Custom Data box. Each custom data field is
   per-field templatable as all of the other data source fields are. Even if
   you select the Use Per-Data Source Value checkbox, it might be useful to
   specify a value that will be used as an "inital value" for any data source
   using this data template.

     ----------------------------------------------------------------------

  Applying Data Templates to Data Sources

   Applying a data template to a data source is a very simple process. The
   first thing you must do is select the data source you want to apply the
   template to under Data Sources. Under the Data Template Selection box,
   select the data template that you want to apply to the data source and
   click Save.

   Once the template is applied to the data source, you will notice that you
   can only change values for the fields that you checked Use Per-Data Source
   Value for.

   Now any time a change is made to the data template, it will be
   automatically propagated to the data sources attached to it.

     ----------------------------------------------------------------------

Host Templates

   Host templates in Cacti serve a different purpose then data and graph
   templates. Instead of abstracting the fields of a host, a host template
   allows you to associate graph templates and data queries with a given host
   type. This way when you assign a host template to a host, all of the
   relevant graphs to that host type are only one click away from the user.

     ----------------------------------------------------------------------

  Adding a Host Template

   To create a new host template in Cacti, select the Host Templates option
   under the Templates heading. Once on that screen, click Add on the right.
   Type a unique name for the host template and click the Create button. You
   will be redirected back to the edit page with the Associated Graph
   Templates and Associated Data Queries boxes. These two boxes allow you to
   associate certain graph templates or data queries with the host template.
   Simply select something from the dropdown menu and click Add to associate
   it with your host template.

   Figure 11-3. Adding a Host Template

     ----------------------------------------------------------------------

                               Chapter 12. How To

Graph a Single SNMP OID

   When dealing with SNMP-enabled devices, there are often times when you
   want to graph the value of a single OID. This tutorial explains how to do
   this in Cacti. It also assumes that you have the "SNMP - Generic OID
   Template" graph template, which is now included in Cacti as of version
   0.8.5. If you do not see this template listed under Graph Templates,
   download the template from the Cacti website in XML form and import it
   using the Import Templates menu item.

   To start the process of creating a new graph for your OID, click the New
   Graphs menu item and select the host that contains the target OID from the
   dropdown. Under the Graph Templates box, you will see a dropdown on the
   last line that reads (Select a graph type to create). From this dropdown,
   choose "SNMP - Generic OID Template" and click the Create button at the
   bottom of the page.

   You will be presented with several fields that will require input before
   the new graph can be created. They are described in more detail below.

   Table 12-1. Field Description: SNMP - Generic OID Template

   +------------------------------------------------------------------------+
   |       Name       |                     Description                     |
   |------------------+-----------------------------------------------------|
   | (Graph) Title    | The title that is to be used for the new graph. It  |
   |                  | is generally a good idea to keep |host_description| |
   |                  | in the title, as to make the graph easier to        |
   |                  | identify later.                                     |
   |------------------+-----------------------------------------------------|
   | (Graph) Vertical | The text that will be printed along the y-axis of   |
   | Label            | the graph. It is generally used to describe units,  |
   |                  | such as 'bytes' or 'percent'.                       |
   |------------------+-----------------------------------------------------|
   | (Graph Items)    | The color that will be used to reprent the data on  |
   | Legend Color     | the graph.                                          |
   |------------------+-----------------------------------------------------|
   | (Graph Items)    | The text that will be used to describe the data on  |
   | Legend Text      | the graph legend.                                   |
   |------------------+-----------------------------------------------------|
   | (Data Source)    | The title that is to be used for the new data       |
   | Name             | source. It is generally a good idea to keep         |
   |                  | |host_description| in the title, as to make the     |
   |                  | data source easier to identify later.               |
   |------------------+-----------------------------------------------------|
   | (Data Source)    | The maximum value that will be accepted from the    |
   | Maximum Value    | OID. Make sure you choose a value that is           |
   | [snmp_oid]       | reasonable for the data you are trying to graph     |
   |                  | because anything larger than the maximum will be    |
   |                  | ignored. If you are graphing a percentage, you      |
   |                  | should use '100' as the value should never exceed   |
   |                  | this.                                               |
   |------------------+-----------------------------------------------------|
   | (Data Source)    | How the data from the OID should be stored by       |
   | Data Source Type | RRDTool and interpreted on the graph. If the value  |
   | [snmp_oid]       | of the OID represents the actual data, you should   |
   |                  | use GAUGE for this field. If the OID value is a     |
   |                  | constantly incrimenting number, you should use      |
   |                  | COUNTER for this field. The two remaining field     |
   |                  | values, DERIVE and ABSOLUTE can be ignored in most  |
   |                  | situations.                                         |
   |------------------+-----------------------------------------------------|
   | (Custom Data)    | The actual SNMP OID to graph. It is typically a     |
   | OID              | good idea to enter the number OID here as opposed   |
   |                  | to using MIB names. For instance, to get the number |
   |                  | of open files on a Netware server, you would use    |
   |                  | ".1.3.6.1.4.1.23.2.28.2.7.0" as the OID.            |
   +------------------------------------------------------------------------+

   When finished filling in values for these fields, click the Create button.
   Your new graph can now be accessed through the Graph Management page or
   the Graphs tab inside of Cacti.

     ----------------------------------------------------------------------

Simplest Method of Going from Script to Graph (Walkthrough)

   Written by Kevin der Kinderen, http://kdeuja.com/~kevin/

   This HOWTO walks you through the simplest steps of graphing the output of
   a single value from a script. As a new user of cacti, I had a difficult
   time understanding how to graph anything that wasn't canned with the
   original load. After a lot of playing around, I came up with these
   procedures which can be built upon for more sophisticated collections and
   graphs.

   I do not use templates in this HOWTO. Templates provide a significant
   advantage if you are graphing the output for multiple instances or
   creating graphs for multiple hosts. They help to maintain consistency and
   simplify setup.

   The example here is not realistic, but can be used and expanded upon as a
   model for creating your own graphs.

   I've not put a lot of explanations in the procedures. Refer to the Cacti
   manual for more details.

   Have a tested script ready to go. I used the following script located in
   /home/cactiuser/bin called random2.pl:

 #!/usr/bin/perl -w
 
 print int(rand(10));

   This script simply prints out a random integer between 0 and 9 every time
   it's called.

   The minimal steps to create a graph from a script are simply:

    1. Create a Data Input Method to tell Cacti how to call the script and
       what to expect from it.

    2. Create a Data Source to tell cacti how and where the data will be
       stored.

    3. Create a Graph to tell cacti how the data will be presented in graph
       form.

    4. Add Graph to Graph View so you can view the graph.

    5. View the Graph

   The details are below:

    1. Create Data Input Method

          * Click the Console tab at the top

          * Click Data Input Methods under Management

          * Click Add

          * Name: Random 2 Input

          * Input Type: Script/Command

          * Input String: /home/cactiuser/bin/random2.pl

          * Click Create

          * Should see "Save Successful." at the top of the page.

          * Click Add by Output Fields (there are no input fields for this
            example)

          * Field [Output]: random_number

          * Friendly Name: Random Number

          * Update RRD File: checked

          * Click Create

          * Should see "Save Successful." and random_number listed under
            Output Fields.

          * Click Save

          * Should see "Save Successful." and Random Input listed in Data
            Input Methods.

    2. Create a Data Source

          * Click Data Sources under Management

          * Click Add in the top right

          * The Data Template Section should be None and None, we're not
            using templates for this example.

          * Click Create.

          * Name: random2ds

          * Data Source Path: blank (Cacti will fill this in)

          * Data Input Source: Random 2 Input (this is the data input method
            you created in step 1)

          * Highlight each of the Associated RRA's using control-click

          * Step: 300 (300 seconds = 5 minutes)

          * Data Source Active: checked

          * Describe the Data Source Item inside the RRA by...

          * Internal Data Source Name: random_number

          * Minimum Value: 0

          * Maximum Value: 0

          * Data Source Type: GAUGE

          * Heartbeat: 600

          * Click Create

          * Should see "Save Successful." at the top and the Data Source Path
            should now have a value (my example
            <path_rra>/random_number_286.rrd)

          * Click Turn On Data Source Debugging Mode to see the results of
            this step.

          * Click Save

          * Should see "Save Successful" and your new Data Source listed.

    3. Create Graph

          * Select Graph Management under Management

          * Click Add

          * Selected Graph Template: None

          * Host: None

          * Click Create

          * Title: RANDOM NUMBERS

          * Image Format: PNG

          * Height: 120

          * Width: 500

          * Auto Scale: checked

          * Auto Scale Options: Use --alt-autoscale-max

          * Logarithmic Auto Scaling: unchecked

          * Rigid Boundaries: unchecked

          * Auto Padding: checked

          * Allow Graph Export: checked

          * Upper Limit: 100

          * Lower Limit: 0

          * Base Value: 1000

          * Unit Value: blank

          * Unit Exponent Value: 0

          * Vertical Label: Random Number

          * Click Create

          * Should see "Save Successful."

          * If you click "Turn On Graph Debug Mode." now you will see:
            "Error: can't make a graph without contents." We need to add
            Graph Items:

          * Click Add by Graph Items

          * Data Source: (from list) No Host - random2ds (random_number)

          * Color: 0000FF (Blue)

          * Graph Item Type: LINE2

          * Consolidation Function: AVERAGE

          * CDEF Function: None

          * Value: blank

          * GPRINT Type: Normal

          * Text Format: blank

          * Insert Hard Return: unchecked

          * Click Create

          * Should see "Save Successful.", Item #1 listed and a graph under
            debug (probably with nothing in it yet)

          * To add a legend, click Add by Graph Items again

          * Data Source: No Host - random2ds (random_number)

          * Color: None

          * Graph Item Type: GPRINT

          * Consolidation Function: LAST

          * CDEF Function: None

          * Value: blank

          * GPRINT Type: Normal

          * Text Format: Cur:

          * Insert Hard Return: unchecked

          * Click Create

          * Should see "Save Successful." and the graph will have a legend
            showing the current value. Note: your integer random number has
            been averaged over the past 5 minutes. At the bottom of the page,
            click save.

          * At the bottom of the page, click Save.

          * Should see "Save Successful." and your graph listed.

    4. Add graph to the graph view

          * Click Graph Trees under Management

          * We'll create a tree called "test" to place our graph

          * Click Add

          * Name: test

          * Should see "Save Successful"

          * Click Add beside Tree Items (to add our graph to this tree)

          * Under Tree Items [graph]...

          * Graph: RANDOM NUMBERS (we named this in step 3)

          * Round Robin Archive: Daily (5 Minute Average)

          * Click Create

          * Should see "Save Successful." and RANDOM NUMBERS listed under
            Tree Items

          * Click Save

          * Should see "Save Successful." and test listed under Graph Trees

    5. View Graph

          * Select Graphs tab

          * Select tree view (Tree beside settings tab)

          * Select test tree on left

          * You may see "Random Graph" but no graph. It takes two or three
            polls (10 - 15 minutes) to see a graph. I believe poll 1 to
            create the rrd, poll 2 to get the first data point and poll 3 to
            have graphable points.

          * While waiting, you can click the RANDOM NUMBERS graph. You'll see
            place holders for 4 graphs. Select [source] under Daily (5 Minute
            Average). You'll see the source for the call to rrdtool graph.
            Give it a sanity check.

          * Now be patient. Hit your refresh button every few minutes. After
            the first poll I got a few empty graphs. A few minutes later data
            started showing up.

     ----------------------------------------------------------------------

                     Chapter 13. Frequently Asked Questions

   1. Using Cacti

                How do I create traffic graphs?

   2. General

                I get a "Undefined variable: _SERVER" error message from
                Cacti.

                I get a "Call to undefined function: mysql_connect()" error
                message from Cacti.

                I have forgotten my 'admin' password to Cacti, how do I reset
                it?

   3. Monitoring

                I am polling thousands of items and cmd.php takes more than 5
                minutes to run.

                I changed x, and now some of my graphs are not updating.

                I am using Redhat 8.0 and SNMP is not working.

                How do I configure net-snmp so it will work with Cacti?

   4. Graphs

                I just installed Cacti and all of my graphs appear as broken
                images.

                My graphs render, but they do not contain any data.

                A lot of my graphs contain long ifAlias names, but they are
                being truncated to 15 characters.

                One of my devices rebooted and now I have a huge spike on my
                graph!

   5. Windows Related

                I get a "Fatal error: Cannot redeclare title_trim()" error
                message from Cacti.

  1. Using Cacti

   How do I create traffic graphs?

   Before you can create traffic graphs, Cacti must have working SNMP
   support. One way to do this is to compile PHP with SNMP support built in,
   many times you can install the 'php-snmp' package to do this. The second
   option is to have Cacti call the snmpget and snmpwalk binaries from your
   ucd-snmp or net-snmp installation. You can use the about page to determine
   whether to are using "built-in" or "external" SNMP support.

   Now that you have working SNMP support, follow these steps.

    1. Click Devices on Cacti's menu.

    2. Click Add to add a new device.

    3. Type a description, hostname, management IP, and SNMP community. Make
       sure to select "Generic SNMP-enabled Host" under Host Template and
       click Create.

    4. Click Create Graphs for this Host at the top of the page.

    5. You should see one or more interfaces listed under the Data Query
       [SNMP - Interface Statistics] box. Place a check next to each
       interface that you want to graph. Below the box, select type of graph
       that you want to create (bits, bytes, summation, etc).

    6. Click Create, and Create again on the following screen to create your
       graphs.

  2. General

   I get a "Undefined variable: _SERVER" error message from Cacti.

   Cacti 0.8 and above requires that you have at least PHP 4.1 or greater
   installed.

   I get a "Call to undefined function: mysql_connect()" error message from
   Cacti.

   Your installation of PHP does not have MySQL installed or enabled. On
   binary-based distributions, make sure you have the 'php-mysql' package
   installed. Also make sure that 'extension=mysql.so' is uncommented in your
   php.ini file.

   I have forgotten my 'admin' password to Cacti, how do I reset it?

   To reset the admin account password back to the default of 'admin',
   connect to your Cacti database at the command line.

 shell> mysql -u root -p cacti

   Now execute the following SQL:

 mysql> update user_auth set password='21232f297a57a5a743894a0e4a801fc3' where username='admin';

  3. Monitoring

   I am polling thousands of items and cmd.php takes more than 5 minutes to
   run.

   Give cactid, the future replacement for cmd.php a try. Unlike cmd.php,
   cactid is written in c and makes use of pthreads. On a typical
   installation, it is not uncommon for cactid to poll about 500 items in
   less then 10 seconds.

   I changed x, and now some of my graphs are not updating.

   The best thing to do here is to force Cacti to rebuild its poller cache.
   To do this click Utilities on the Cacti menu, and select Clear Poller
   Cache.

   I am using Redhat 8.0 and SNMP is not working.

   Redhat 8.0 comes with a broken php-snmp package. Updating your 'php-snmp'
   and 'net-snmp' packages to their latest versions should fix this problem.

   How do I configure net-snmp so it will work with Cacti?

   Run snmpconf -g basic_setup and follow the prompts. Also check that the
   file being used by snmpd is the correct config file. For Redhat Linux,
   snmpconf creates the /etc/snmpd.conf, but snmpd uses
   /etc/snmpd/snmpd.conf.

   If this doesn't work a very simple config file is:

 # contact
 syslocation Something
 syscontact "root@someone.com"

 # auth
 rocommunity public

 # disk monitoring
 disk /

  4. Graphs

   I just installed Cacti and all of my graphs appear as broken images.

   For you to actually get graph images, cmd.php must run at least once so it
   can create .rrd files in Cacti's 'rra/' directory. Double check that you
   configured your /etc/crontab file to execute cmd.php every five minutes.
   Also make sure that the user cmd.php runs as has permission to create new
   files in Cacti's 'rra/' directory.

   If all of your settings appear correct, try running cmd.php manually by
   cd'ing to Cacti's directory and typing:

 shell> php cmd.php

   If you have files in your 'rra/' directory, but your graphs still appear
   as broken images, you should enable graph debug mode see exactly why the
   graphs are not rendering. To do this go into Cacti, select Graph
   Management from the menu, select any graph listed, and select Turn On
   Graph Debug Mode.

   My graphs render, but they do not contain any data.

   More often than not, this problem's cause is permissions. For instance if
   you run cmd.php manually as root for testing, any .rrd files that it
   creates will be owned by root. Now when cmd.php runs from cron, it will
   not be able to update these .rrd files because they are owned by root. You
   can double check the owner of your .rrd files by running the following
   command in your Cacti directory:

 shell> ls -al rra/

   If only some of your graphs are not updating correctly, double check the
   Maximum Value field for all data sources used by these graphs. If the
   value being fed to the .rrd file exceeds its Maximum Value, RRDTool will
   insert an Unknown and you will see no data on the graph.

   A lot of my graphs contain long ifAlias names, but they are being
   truncated to 15 characters.

   Cacti does this by default to better control graph title formatting. You
   can change this limit, by going to Cacti Settings on the Cacti menu,
   selecting the Visual tab, and changing the value for Data Queries -
   Maximum Field Length.

   One of my devices rebooted and now I have a huge spike on my graph!

   This occurs because the reboot causes SNMP's counters to reset, which can
   cause a rather large spike on the graph when RRDTool tries to determine
   the change between the new small counter value and the large previous
   value. One way to combat this issue is to specify realistic maximum values
   for your data sources. RRDTool will ignore any value that is larger than
   the maximum value.

   If you already have a spike on one or more of your graphs, there is a
   really useful Perl script that will remove them for you.

  5. Windows Related

   I get a "Fatal error: Cannot redeclare title_trim()" error message from
   Cacti.

   Contrary to previous versions of Cacti, you must not put Cacti in your PHP
   include path. Check your php.ini file to make sure there is not something
   like include_path = C:/Apache2/htdocs/cacti.

     ----------------------------------------------------------------------

                             Chapter 14. Variables

Graph Variables

   The following variables can be used in the Text Format and Value graph
   item fields. Below is a description of each of these variables.

     ----------------------------------------------------------------------

  Date/Time

 |date_time|

   This variable will place the date and time of the last poller run on the
   graph. It can be used to replicate MRTG's "graph last updated" feature.

     ----------------------------------------------------------------------

  Data Query Fields

 |query_field_name|

   You can place the value of any data query field on the by including this
   variable. Make sure to substitute "field_name" with the actual data query
   field name.

   Example 14-1. Print the IP Address on a traffic graph

   |query_ifIP|

   Example 14-2. Print the mount point on net-snmp disk graph

   |query_dskPath|

     ----------------------------------------------------------------------

  95th Percentile

 |95:(bits|bytes):[0-9]:(current|total|max):[0-9]|

   95th percentile is often used by hosting providers to bill customers based
   on their peak traffic usage while ignoring their top 5 percent. This way
   if a customer has a fairly consistent traffic pattern and decides to
   download a huge file one day, the large spike will be ignored.

   In Cacti, 95th percentile works just like any other graph variable. To use
   this variable you must give it four arguments:

   Table 14-1. 95th Percentile Argument Description

   +------------------------------------------------------------------------+
   |        Name         |                   Description                    |
   |---------------------+--------------------------------------------------|
   | (bits|bytes)        | Choose whether you want to represent your 95th   |
   |                     | percentile in bits or bytes. The only valid      |
   |                     | values for this field are 'bits' and 'bytes'.    |
   |---------------------+--------------------------------------------------|
   | [0-9]               | This field determines the power of 10 divisor    |
   |                     | that will be applied to your 95th percentile     |
   |                     | number. Enter '0' to leave the number alone, '3' |
   |                     | for kilo or '6' for mega, etc.                   |
   |---------------------+--------------------------------------------------|
   | (current|total|max) | You can choose to calculate the 95th percentile  |
   |                     | based on the current data source or a total of   |
   |                     | all data sources used on the graph. The only     |
   |                     | valid values for this field are 'current' and    |
   |                     | 'total'.                                         |
   |---------------------+--------------------------------------------------|
   | [0-9]               | Enter the number of digits to use for floating   |
   |                     | point precision when printing out the final      |
   |                     | number. The default value for this field is two  |
   |                     | decimal places.                                  |
   +------------------------------------------------------------------------+

   Example 14-3. Output in the following format: 42.58 mbit

   |95:bits:6:max:2|

     ----------------------------------------------------------------------

  Bandwidth Summation

 |sum:([0-9]|auto):(current|total):([0-9]):([0-9]+|auto)|

   Bandwidth summation is useful for summing up all values in an RRD file for
   a given time range. This is typically useful on traffic graphs where you
   can see a total of all traffic that has gone through an interface in a
   given time period.

   In Cacti, bandwidth summation works just like any other graph variable. To
   use this variable you must give it three arguments:

   Table 14-2. Bandwidth Summation Argument Description

   +------------------------------------------------------------------------+
   |      Name       |                     Description                      |
   |-----------------+------------------------------------------------------|
   | ([0-9]|auto)    | This field determines the power of 10 divisor that   |
   |                 | will be applied to your number. Enter '0' to leave   |
   |                 | the number alone, '3' for kilo or '6' for mega, etc. |
   |                 | You can also enter 'auto' for this field to have     |
   |                 | Cacti automatically scale the number and insert the  |
   |                 | appropriate label.                                   |
   |-----------------+------------------------------------------------------|
   | (current|total) | You can choose to calculate the summation based on   |
   |                 | the current data source or a total of all data       |
   |                 | sources used on the graph. The only valid values for |
   |                 | this field are 'current' and 'total'.                |
   |-----------------+------------------------------------------------------|
   | [0-9]           | Enter the number of digits to use for floating point |
   |                 | precision when printing out the final number. The    |
   |                 | default value for this field is two decimal places.  |
   |-----------------+------------------------------------------------------|
   | ([0-9]+|auto)   | Enter the number of seconds in the past to perform   |
   |                 | the summation calculation for. For instance '86400'  |
   |                 | for 24 hours, '172800' for 48 hours, etc. You can    |
   |                 | also enter 'auto' for this field to have Cacti use   |
   |                 | the graph timespan.                                  |
   +------------------------------------------------------------------------+

   Example 14-4. Output in the following format: 36.47 GB

   |sum:auto:current:2:auto|

     ----------------------------------------------------------------------

Host Variables

   Host variables represent host data and can be placed in graph or data
   source titles. The following table describes which host variables can be
   used and which host fields the correspond to.

   Table 14-3. Host Variables

   +------------------------------------------------------------------------+
   |     Variable Name     |                  Description                   |
   |-----------------------+------------------------------------------------|
   | |host_description|    | Description                                    |
   |-----------------------+------------------------------------------------|
   | |host_hostname|       | Hostname                                       |
   |-----------------------+------------------------------------------------|
   | |host_snmp_community| | SNMP Community                                 |
   |-----------------------+------------------------------------------------|
   | |host_snmp_version|   | SNMP Version                                   |
   |-----------------------+------------------------------------------------|
   | |host_snmp_username|  | SNMP Username (v3)                             |
   |-----------------------+------------------------------------------------|
   | |host_snmp_password|  | SNMP Password (v3)                             |
   +------------------------------------------------------------------------+

     ----------------------------------------------------------------------

                     Chapter 15. RRDTool Specific Features

GPRINT Presets

   A GPRINT is a graph item type that enables you to print the values of data
   sources on a graph. They are typically used to represent legend values on
   the graph. The output format of these numbers are controlled by a
   printf-like format string. Cacti enables you to keep a global list of
   these strings that can be applied to any graph item throughout Cacti.

     ----------------------------------------------------------------------

  Creating a GPRINT Preset

   To create a new GPRINT preset, select the Graph Management menu item under
   the Management heading, and select GPRINT Presets. Click Add to the right
   and you will be presented with an edit page containing two fields. Enter a
   name for your GPRINT preset, and the actual printf-like string in the
   GPRINT Text field. When you are finished, click the Create button to
   create your new GPRINT preset.

     ----------------------------------------------------------------------

CDEFs

   CDEFs allow you to apply mathematical functions to graph data to alter
   output. The concept of a CDEF comes straight from RRDTool, and are written
   in reverse polish notation (RPN). For more information regarding the
   syntax of CDEFs, check out the CDEF tutorial.

     ----------------------------------------------------------------------

  Creating a CDEF

   To create a new CDEF in Cacti, select the Graph Management option under
   the Management heading, and select CDEFs. Once at this screen, click Add
   to the right. You will be prompted for a CDEF name, for which you can type
   anything used to describe your CDEF. Click the Create button so you are
   redirected back to the edit page, now with an empty CDEF Items box.
   Construct your CDEF by adding an item for each element in the CDEF string,
   common types such as operators and functions are enumerated for your
   convenience. Below is a basic description of each CDEF item type.

   Table 15-1. CDEF Item Types

   +------------------------------------------------------------------------+
   |     Type      |                      Description                       |
   |---------------+--------------------------------------------------------|
   | Function      | You can choose a CDEF function to use as the item. The |
   |               | RRDTool graph manual describes the purpose of each     |
   |               | CDEF function.                                         |
   |---------------+--------------------------------------------------------|
   | Operator      | Just your standard math operators, including modulo    |
   |               | (%).                                                   |
   |---------------+--------------------------------------------------------|
   | Special Data  | A special data source is basically a flag to tell      |
   | Source        | Cacti to do some special processing when it encounters |
   |               | this CDEF item. The "Current Graph Item Data Source"   |
   |               | type basically inserts the name of the data source     |
   |               | that is referenced by the graph item that references   |
   |               | to this CDEF. Both of the "All Data Sources" types     |
   |               | insert a summation of all data sources used on a       |
   |               | graph.                                                 |
   |---------------+--------------------------------------------------------|
   | Another CDEF  | You can recursively use another CDEF within this CDEF. |
   |---------------+--------------------------------------------------------|
   | Custom String | Sometimes it's just easier to type out the literal     |
   |               | CDEF string manually. When referencing to data sources |
   |               | on the graph, remember that Cacti names them 'a', 'b', |
   |               | 'c', '...', starting with the first data source on the |
   |               | graph.                                                 |
   +------------------------------------------------------------------------+
