The Cacti Manual

Ian Berry Tony Roman Larry Adams

The Cacti Manual by Ian Berry, Tony Roman, and Larry Adams Published 2005 Copyright 2005 The Cacti Group
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 identication purposes only and are not indicative of endorsement by or of any company, organization, product, or platform.

Table of Contents
I. Installation...................................................................................................................................................................................1 1. Requirements .....................................................................................................................................................................1 2. Installing Under Unix .......................................................................................................................................................2 3. Installing Under Windows...............................................................................................................................................3 4. Upgrading Cacti ................................................................................................................................................................8 II. Basics ...........................................................................................................................................................................................9 5. Graph Overview ................................................................................................................................................................9 6. How to Graph Your Network........................................................................................................................................10 6.1. Creating a Device................................................................................................................................................10 6.2. Creating the Graphs ...........................................................................................................................................11 7. Viewing Graphs ...............................................................................................................................................................12 7.1. Graph Trees..........................................................................................................................................................12 8. User Management ...........................................................................................................................................................13 8.1. Creating a New User ..........................................................................................................................................13 8.2. Realm Permissions..............................................................................................................................................14 8.3. Graph Permissions..............................................................................................................................................14 8.4. Graph Settings.....................................................................................................................................................14 III. Advanced Topics....................................................................................................................................................................15 9. Data Input Methods ........................................................................................................................................................15 9.1. Creating a Data Input Method..........................................................................................................................15 9.2. Making Your Scripts Work With Cacti.............................................................................................................16 10. Data Queries...................................................................................................................................................................17 10.1. Creating a Data Query .....................................................................................................................................17 10.2. SNMP Query XML Syntax ..............................................................................................................................18 10.3. Script Query XML Syntax................................................................................................................................20 11. Templates........................................................................................................................................................................23 11.1. Graph Templates ...............................................................................................................................................23 11.2. Data Templates..................................................................................................................................................26 11.3. Host Templates..................................................................................................................................................28 12. PHP Script Server ..........................................................................................................................................................29 12.1. Using the Script Server.....................................................................................................................................29 12.2. Upgrade Steps for the Example HostMib Data Queries .............................................................................29 12.3. Migration of Existing PHP Scripts to Script Server .....................................................................................29 12.4. Testing Your Script in the Script Server .........................................................................................................31 IV. Using Cacti..............................................................................................................................................................................32 13. How To............................................................................................................................................................................32 13.1. Graph a Single SNMP OID..............................................................................................................................32 13.2. Simplest Method of Going from Script to Graph (Walkthrough)..............................................................32 14. Frequently Asked Questions .......................................................................................................................................37 V. Reference ..................................................................................................................................................................................40 15. Variables..........................................................................................................................................................................40 15.1. Graph Variables.................................................................................................................................................40 15.2. Host Variables....................................................................................................................................................42 16. RRDTool Specic Features ...........................................................................................................................................44 16.1. GPRINT Presets.................................................................................................................................................44 16.2. CDEFs .................................................................................................................................................................44

List of Tables
6-1. SNMP Retrieval Types ..........................................................................................................................................................10 8-1. Field Description: User Management .................................................................................................................................13 9-1. Field Description: Data Input Methods..............................................................................................................................15 9-2. Field Description: Data Input Fields...................................................................................................................................15 10-1. Field Description: Data Queries ........................................................................................................................................17 10-2. Field Description: Associated Graph Templates .............................................................................................................17 10-3. SNMP Query XML Field Reference ..................................................................................................................................18 10-4. Script Query XML Field Reference ...................................................................................................................................20 11-1. Field Description: Graph Templates .................................................................................................................................23 11-2. Field Description: Graph Template Items ........................................................................................................................24 11-3. Field Description: Graph Template Items ........................................................................................................................25 11-4. Field Description: Data Templates ....................................................................................................................................26 11-5. Field Description: Data Source Items................................................................................................................................27 13-1. Field Description: SNMP - Generic OID Template .........................................................................................................32 15-1. Nth Percentile Argument Description..............................................................................................................................40 15-2. Nth Percentile Types ...........................................................................................................................................................41 15-3. Bandwidth Summation Argument Description..............................................................................................................42 15-4. Host Variables ......................................................................................................................................................................42 16-1. CDEF Item Types .................................................................................................................................................................44

Chapter 1. Requirements
Cacti requires that the following software is installed on your system.
RRDTool MySQL PHP

1.0.49 or 1.2.x or greater

3.23 or greater, 4.0.20d or greater highly recommended for advanced features

4.1 or greater, 4.3.6 or greater highly recommended for advanced features

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 conguration.
$database_default = "cacti"; $database_hostname = "localhost"; $database_username = "cactiuser"; $database_password = "cacti";

6. Set the appropriate permissions on cactis directories for graph/log generation. You should execute these commands from inside cactis 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 le similar to:
*/5 * * * * cactiuser php /var/www/html/cacti/poller.php > /dev/null 2>&1

Replace cactiuser with the valid user specied 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 ll in all of the path variables carefully and correctly on the following screen.

Chapter 3. Installing Under Windows

Software Compoents Required 1. (Optional) Apache> - This software is optional if running Windows Internet Information Server. 2. Cacti> - Install from the zip distribution and intstall in the web root or your choice. Many choose to install into a "Cacti" sub folder. 3. Cactid - Install from the zip distribution into the c:\cacti directory. Make sure your cactid.conf.dist is located in that directory as well. 4. RRDTool - Install from the Cacti website. Install it into the c:\cacti directory. 5. PHP 4.3.6+ or 5.x - Install into the c:\php folder. If you choose to install into c:\Program Files\php, you will have to use 8.3 lenames to reference its binaries in Cacti. 6. MySQL 4.x or MySQL 5.x - Install into the default location. This is typically c:\Program Files\MySQL\MySQL Server X.XX. 7. (Optional) Cygwin - Download and execute setup.exe from the Cygwin website. Keep the setup.exe le for later use. 8. (Optional) Net-SNMP - Install to the c:\net-snmp directory. If you choose to use c:\Program Files\net-snmp you will have tu use 8.3 lenames to reference its binaries in Cacti. Congure PHP 1. If using PHP 4, move the les in c:\php\dlls to c:\php 2. Add the following directory to the existing Windows System PATH environment variable: c:\php. The Windows path can be accessed via the Control Panel at: System | Advanced | Environment Variables | System Variables. 3. Add the following directory to a new Windows System environment variable called PHPRC: c:\php. 4. Add a new Windows System environment variable called MIBDIRS. If using PHP 4, set it to c:\php\mibs. If using PHP 5, set it to c:\php\extras\mibs 5. If using PHP 4.3.5 or less, create the following directory c:\tmp. 6. Rename the le c:\php\php.ini.dist to php.ini, and make the following changes to it: If using PHP 4 add/uncomment the following lines.
extension_dir = c:\php\extensions extension=php_snmp.dll extension=php_sockets.dll cgi.force_redirect = 0

If using PHP 5 uncomment the following lines.

extension_dir = c:\php\ext extension=php_mysql.dll extension=php_snmp.dll extension=php_sockets.dll cgi.force_redirect = 0

If using PHP 4.3.5 or less include the following line. If using 4.3.6 or greater, you should remove this line if present.
session.save_path=c:\tmp

7. In earlier installation guides to PHP, they recommended moving certain DLLs to the c:\winnt\system32 directory. If so, you will have to remove those les. Please review the PHP installation documentation for instructions on removing those les. 8. If you want to allow template importing, uncomment the following line:
file_uploads = On

9. Give the user who will be running the scheduled task, modify rights to the .index le in the location pointed to by the MIBDIRS Windows System environment variable. Congure the Webserver (Apache) 1. Make sure you have stopped any IIS web servers before you proceed with Apache installation, or make sure Apache is congured on an alternate port. 2. If you are using Apache 1.3.x, installation of PHP 5 is not recommended. If using PHP 4, add the following lines to your httpd.conf le. You can edit that le by selecting Start | All Programs | Apache HTTP Server X.XX | Congure Server | Edit the httpd.conf le pick from the Taskbar.

Chapter 3. Installing Under Windows If using Apache 1.3.x and PHP 4, then add the following lines:
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

If using Apache 2.x and PHP 4, then add the following lines:
LoadModule php4_module c:\php\sapi\php4apache2.dll AddType application/x-httpd-php .php DirectoryIndex index.html index.htm index.php

If using Apache 2.x and PHP 5, then add the following lines.
LoadModule php5_module c:\php\php5apache2.dll AddType application/x-httpd-php .php DirectoryIndex index.html index.htm index.php

Congure the Webserver (IIS) 1. Start the Internet Information Services (IIS) Manager, right click on the Default Web Site (in most cases) and select Properties. 2. Under the Home Directory tab, select Conguration and click Add. Browse to the path of php4isapi.dll or php5isapi.dll, and type in .php as the extension. Note: if using IIS6, Enable All Verbs and Script Engine. 3. Under the ISAPI Filters tab, click Add and browse to the php4isapi.dll or php5isapi.dll le. Name the lter "php" and click OK. 4. Under the Documents tab, add index.php to the list. 5. If using IIS6, goto Web Service Extensions and add a new Web Service Extension. Name the extension "php", and click Add and browse to the php4isapi.dll or php5isapi.dll le, enable Set Extension status to Enable, and click OK. 6. Give the IUSR_XXXX and IIS_WPG users read & execute permissions to the le %windir%\system32\cmd.exe. They will also need read permissions on cacti_web_root/cacti and its subfolders. 7. If using IIS6, give the IIS_WPG user modify permissions to the folders cacti_web_root/cacti/log and cacti_web_root/cacti/rrd. 8. Completely stop and start the IIS service using the following commands:
net stop iisadmin net start w3svc

Install Cygwin (optional) 1. Installing a single instance of Cygwin, and using it for all applications that require it is recommended so you do not have different versions of the Cygwin dlls laying around on your system, which can cause conicts. 2. Run setup.exe you previously download. 3. Once you reach the portion of setup entitled Select Packages, install the following:
Base (include all items) Libs libart_lgpl libfreetype26 libpng12 zlib openssl Utils patch Web wget

4. Add c:\cygwin\bin to your Windows System PATH environment variable. 5. Move setup.exe to c:\cygwin for future use. Install RRDTool 1. Extract the RRDTool zip le from the Cacti web site to c:\cacti\rrdtool.exe. Install MySQL 1. Extract the MySQL zip le to a temp directory and run setup.exe. 2. Install MySQL to the default directory, or for the purposes of this manual to the c:\mysql directory. 4

Chapter 3. Installing Under Windows 3. If running an older version of MySQL, start it by running c:\mysql\bin\winmysqladmin.exe. In more recent versions, this is not required. 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. 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;

8. If you are running MySQl 4.1 and above, you will need to apply the old password setting in order to authenticate with Cacti. To make this change, stop the MySQL service and add the following to the Start Parameter eld. Start it again once it has been added.
--old-password

You will also need to update the cactiuser account with the old password style.

shell> UPDATE mysql.user SET Password = OLD_PASSWORD(cactipwd) WHERE Host = localhost AND User = cactiuser mysql> FLUSH PRIVILEGES;

Install Net-SNMP 1. If you plan to use any hosts with SNMP v2c support, and are using early versions of PHP, you must download and install the Net-SNMP libraries. Net-SNMP provides installers to install their product. However, caution must be taken if you choose to use long le names as Cacti does not them as long le names. You will have to user 8.3 notation. For example c:\Program Files\Net-SNMP\bin becomes c:\progra~1\net-snmp\bin. Install Cactid 1. Extract the Cactid zip le to c:\cacti and modify the cactid.conf.dist le to include the following statements.
DB_Host 127.0.0.1 or hostname (not localhost) DB_Database cacti DB_User cactiuser DB_Password cacti DB_Port 3306

All other pre 0.8.6 settings are obsolete. 2. Cactid now comes with a binary distribution. However, we strongly suggest that you install Cygwin and then remove all the DLL les and sh.exe from the c:\cacti directory. Congure Cacti 1. Edit cacti_web_root/cacti/include/config.php and specify the MySQL user, password, database, and database port for your Cacti conguration.
$database_default = "cacti"; $database_hostname = "localhost"; $database_username = "cactiuser"; $database_password = "cacti"; $database_port = "3306";

2. Point your web browser to:

http://your-server/cacti/

Log in using the username and password of admin/admin. You will be required to change this password immediately. 3. From Cacti, go to Settings->Paths and verify/udate your paths to point to the correct locations. Recommended examples are posted below. If you plan on using Cactid, then it is very important that all paths include forward slashes instead of backslashes. PHP Binary Path:
c:/php/php.exe

Chapter 3. Installing Under Windows RRDTool Binary Path:

c:/cacti/rrdtool.exe

SNMPGET, SNMPWALK, SNMPBULKWALK, SNMPGETNEXT Paths:

c:/progra~1/net-snmp/bin/snmpget.exe c:/progra~1/net-snmp/bin/snmpwalk.exe c:/progra~1/net-snmp/bin/snmpbulkwalk.exe c:/progra~1/net-snmp/bin/snmpgetnext.exe

Cacti Logle Path:

c:/mycacti/website/cacti/log/cacti.log

Cactid Path:
c:/cacti/cactid.exe

4. Click on Devices. Delete the Localhost devices as it intended for Linux environments In the upper right corner, click Add. Fill in the following information and then click Add.
Description: My Windows localhost Hostname: localhost Host Template: Windows 2000/XP

5. You should now be looking at the localhost device screen. Right under its name, there should be some SNMP information listed, if not you should double check the SNMP settings on the server and rewall settings. In the upper right-hand corner, click on Create Graphs for this Host. On the following screen, select a disk partition and network interface. At the bottom of the page, click on Create. 6. Log into the user account youll be using for the scheduled task and verify starting a Cacti polling cycle works. Do this by running the following from the command prompt:
php c:/cacti_web_root/cacti/poller.php

The output should look something like the following:

C:\>php c:\inetpub\wwwroot\cacti\poller.php OK u:0.00 s:0.06 r:1.32 OK u:0.00 s:0.06 r:1.32 OK u:0.00 s:0.16 r:2.59 OK u:0.00 s:0.17 r:2.62 10/28/2005 04:57:12 PM - SYSTEM STATS: Time:4.7272 Method:cmd.php Processes:1 Threads:N/A Hosts:1 HostsPerProces

After this has ran once, you should have cacti.log in /cacti/log/ and rrd les in /cacti/rra/. 7. You are going to need to schedule a task while logged on as an Administrator. This task is required to you can run poller.php every 5 minutes. Make sure the Task Scheduler service is started and follow the steps below to begin. Note: The following instructions are based on Windows XP and Windows Server 2003. You should be able to follow these instructions close enough for Windows 2000 as well. a. Select Start --> Settings --> Control Panel and double click on Scheduled Tasks. b. Double click on Add Scheduled Task. c. Click Next and Browse on the following screen. Find c:\php and select php.exe. Choose Daily on and click Next. d. Click Next again without changing the time or date settings. e. When entering a username and password make sure the user has read and write access to the following directories:
cacti_web_root/cacti/rra cacti_web_root/log

Make sure the user has read, write, and execute access to the following directories:
c:\php c:\php\sapi

f. Click Next and Finish to close the wizard. g. Right click on the task you just created, and select Properties. h. Select the Schedule tab. i. Make sure Daily is selected and click the Advanced button. j. Check the Repeat checkbox, set it for 5 minutes and set the duration for 24 hours. 6

Chapter 3. Installing Under Windows k. Click Ok l. In the Run textbox enter the following text making sure to use the appropriate paths.
c:\php\php.exe c:\mycacti\website\cacti\poller.php

The start in box should say c:\mycacti\website\cacti.

Apply Patches 1. There are two methods of applying patches to Cacti: a. If you have Cygwin installed, then the patch instructions which use wget and patch, will work. b. The other method requires you to visit http://www.cacti.net/downloads/patches/0.8.6h/pre-patched/ and manually download and replace the patched les. 2. You might need to reapply le/folder security on the les patched. Double check they are correct.

Chapter 4. Upgrading Cacti

1. Backup the old Cacti database.
shell> mysqldump -l --add-drop-table cacti > mysql.cacti

Note: You will probably have to specify the -u and -p ags for the MySQL username and password. This user must have permission to read from Cactis database or you will end up with an empty backup. 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 conguration.
$database_default = "cacti"; $database_hostname = "localhost"; $database_username = "cactiuser"; $database_password = "cacti";

6. Copy the *.rrd les from the old Cacti directory.

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

7. Copy any relevant custom scripts from the old Cacti directory. Some script are updated between versions. Therefore, make sure you only over write if the scripts either dont exist or are newer than the distributions.
shell> cp -u cacti_old/scripts/* cacti/scripts/

8. Copy any relevant custom resource XML les from the old Cacti directory. Some resource XML les are updated between versions. Therefore, make sure you only over write if the XML les either dont exist or are newer than the distributions.
shell> cp -u -R cacti_old/resource/* cacti/resource/

9. Set the appropriate permissions on Cactis directories for graph/log generation. You should execute these commands from inside Cactis 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.) 10. 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 1, you will immediately recognize that a graph in Cacti is closely modeled after RRDTools 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 dene the overall properties of a graph, the graph items dene the data that is to be represented on the graph. So the graph items dene which data to display and how it should displayed, and also dene 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 eld to create graphs for your network. When you are ready to take on the task of creating your own graph templates, extensive eld descriptions for both graphs and graph items are provided in that section of the manual.

Notes
1. http://www.rrdtool.org/

Chapter 6. How to Graph Your Network

At this point, you probably realize that graphing is Cactis 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.

6.1. Creating a Device

The rst step to creating graphs for your network is adding a device for each network device that you want to create graphs for. A device species 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 rst two elds, Description and Hostname are the only two elds that require your input beyond the defaults. If your host type is dened under the host template dropdown, be sure to select it here. You can always choose "Generic SNMP-enabled Host" if you are just graphing trafc or "None" if you are unsure. It is important to remember that the host template you choose will not lock you into any particular conguration, 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 congured 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.

6.1.1. 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

Chapter 6. How to Graph Your Network Type External SNMP Description Calls the net-snmp snmpwalk and snmpget binaries that are installed on your system. Supported Options All SNMP options Places Used Web interface and PHP poller (poller.php)

Internal SNMP (php-snmp) Uses PHPs SNMP functions which are linked against net-snmp or ucd-snmp at compile time. Cactid SNMP

Version 1 Only (Community and Port)

Web interface and PHP poller (poller.php)

Links directly against All SNMP options net-snmp or ucd-snmp and calls the API directly.

C-Based Poller (cactid)

6.2. 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 elds 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.

11

Chapter 7. Viewing Graphs

7.1. 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.

7.1.1. 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, ll 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 eld.

Chapter 8. User Management

In addition to giving you the tools to create sophisticated graphs, Cacti enables you to create users that are tailored specically 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 rst 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.

8.1. 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 eld is described in more detail below. In addition to these elds, 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 User Name Description This eld contains the actual login name for the user. There are no character limits this eld, but it would make sense to keep it to alphanumeric characters to maintain simplicity. (Optional) You can use this eld as a more descriptive identier for the user. It is currently only used for display on the user management page. 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.

Full Name Password

Chapter 8. User Management Name Account Options Description There are currently two account related options that can be set for each user. The rst, 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. 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. These options dictate what occurs immediately after the user logs in. The rst 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.

Graph Options

Login Options

8.2. Realm Permissions

Realm permissions control which areas of Cacti a user can access. You can edit a users 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 ne tune each users 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 ne 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 t.

8.3. Graph Permissions

Graph permissions control which graphs a user is allowed to view, it does not apply to editing graphs. You can edit a users 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 users 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 graphs default policy to Deny, but kept host and graph template at Allow, the users effective policy would be Deny since the graph assignment type is evaluated rst. 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 Cactis graph permissions system, these default policies can be combined to provide very complex results.

8.4. 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.

14

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.

9.1. 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 elds to populate on the following screen. Table 9-1. Field Description: Data Input Methods Name Name Input Type Input String Description 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. Select the type of data input method you are trying to create. Valid options here are Script/Command, SNMP, SNMP Query, and Script Query. This eld is only used when the Input Type is set to Script/Command. It species 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 eld is only here for legacy purposes and will probably go away in a future version of Cacti.

When you are nished lling in all necessary elds, 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 dene any elds that require information from the user. Any input elds referenced to in the input string must be dened here. The Output Fields box is used to dene each eld that you expect back from the script. All data input methods must have at least one output eld dened, but may have more for a script.

9.1.1. Data Input Fields

To dene a new eld, click Add next to the input or output eld boxes. You will be presented with some or all of the elds below depending on whether you are adding an input or output eld. Table 9-2. Field Description: Data Input Fields Name Field/Field Name Friendly Name Regular Expression Match (Input Only) Allow Empty Input (Input Only) Special Type Code (Input Only) Description Either select or type in the name of the eld you want to dene. No spaces or other non-alphanumeric characters (except - or _) should be used in this eld. Enter a more descriptive name for this eld which will be used for identication throughout Cacti. If you want to enforce a certain regular expression pattern when the user enters a value for this eld, enter it here. The regular expression must follow POSIX syntax as it will be passed to PHPs ereg() function. Select whether you want to allow the user to leave the value of this eld blank or not. Sometimes Cacti needs to reference a eld internally, but needs to rely on more than just the eld name. For instance, if your eld requires an IP address from the user, you can enter management_ip here and Cacti will ll this eld in with the current IP address of the selected host. Valid values for this eld are: hostname, management_ip, snmp_community, snmp_username, snmp_password, and snmp_version.

Chapter 9. Data Input Methods Name Update RRD File (Output Only) Description Check this box if you want Cacti to insert the return value from this eld into the RRD le. Obviously, this box needs to be checked for at least one output eld per data input source, but can be left blank to have Cacti store the value in the database instead.

When you are nished lling in all necessary elds, 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 elds, or click Save on this screen when nished.

9.2. Making Your Scripts Work With Cacti

The simplest way to extend Cactis 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 eld. See the previous section, Creating a Data Input Method1 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 specied in the Input String eld. 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 dene your data input method, you are required to dene one or more output elds. The number of output elds that you dene here is important to your scripts output. For a data input method with only one output eld, 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 eld
67

Data input methods with more than one output eld 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 elds 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 elds
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.

Notes
1. data_input_methods.html

16

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 trafc of a network interface, rst 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 rst 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 denes 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 le and the denition within Cacti. An XML le must be created for each query, that denes 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 denition within Cacti, which tells Cacti where to nd the XML le and associates the data query with one or more graph templates.

10.1. Creating a Data Query

Once you have created the XML le that denes 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 Name Description XML Path Description 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. (Optional) Enter a more detailed description of the data query including the information it queries or additional requirements. Fill in the full path to the XML le that denes 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 nd the XML le. This is how you tell Cacti to handle the data it 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.

Data Input Method

When you are nished lling in all necessary elds, click the Create button to continue. You will be redirected back to the same page, but this time with some additional information to ll in. If you receive a red warning that says XML File Does Not Exist, correct the value specied in the XML Path eld.

10.1.1. 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 elds specied in the XML le. 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 trafc, 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 elds to ll in: Table 10-2. Field Description: Associated Graph Templates Name Name Description 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.

Chapter 10. Data Queries Name Graph Template Description Choose the actual graph template that you want to make the association with.

When you are nished lling in these elds, click the Create button. You will be redirected back to the same page with some additional information to ll 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 eld 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 eld values of data sources and graphs created using this data query. If you specify multiple suggested values for the same eld, Cacti will evaluate them in order which you can control using the up or down arrow icons. For more information about valid eld names and variables, read the section on suggested values. When you are nished lling in all necessary elds 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 le. When you are nished with this, you should be ready to start adding your data query to hosts.

10.2. 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> <oid_index_parse>OID/REGEXP:.*\.([0-9]{1,3}\.[0-9]{1,3})$</oid_index_parse> <oid_num_indexes>.1.3.6.1.2.1.2.1.0</oid_num_indexes> <index_order>ifDescr:ifName:ifIndex</index_order> <index_order_type>numeric</index_order_type> <index_title_format>|chosen_order_field|</index_title_format> <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-3. SNMP Query XML Field Reference Field query->name query->description query->oid_index Description (Optional) You can enter a "friendly name" for the SNMP query here. It will not be used by Cacti, and is for identication only. (Optional) You can enter a description for the SNMP query here. It will not be used by Cacti, and is for identication only. 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 eld that uniquely identies each row returned by the query. In the example above, the oid_index points to the OID of ifIndex in the interface MIB. Note: Starting with version 0.8.6c, Cacti is able to parse unique indexes from the OID itself. While the regular expression used for parsing the value from the OID is dened below, you must still specify an OID that can be walked by Cacti in order to obtain the list of OIDs. Any OID dened for one of your input elds should work in this case. The values returned from the snmpwalk walk will be completely disregarded.

18

Chapter 10. Data Queries Field query->oid_index_parse Description This eld should only be used if you are trying to parse the unique index from the OID itself. If this eld is dened, to obtain a list of indexes, Cacti walks the OID provided in the oid_index eld above. It then applies the regular expression provided in this eld to the list of OIDs that are returned. The matched substrings that remain become the list of indexes for this SNMP query. An OID that can be queried to determine the total number of available indexes. If specied, this will be used to determine when to automatically recache this SNMP query when it is attached to a device. As of version 0.8.6, Cacti will attempt to nd the best eld to index off of based on whether each row in the query is unique and non-null. If specied, Cacti will perform this check on the elds listed here in the order specied. Only input elds can be specied and multiple elds should be delimited with a colon. For sorting purposes, specify whether the index is numeric or alphanumeric. numeric: The indexes in this SNMP query are to be sorted numerically (ie. 1,2,3,10,20,31)
alphabetic: The indexes in this SNMP query are to be sorted alphabetically

query->oid_num_indexes

query->index_order

query->index_order_type

(1,10,2,20,3,31).

query->index_title_format

Specify the title format to use when representing an index to the user. Any input eld name can be used as a variable if enclosed in pipes (|). The variable |chosen_order_field| will be substituted with the eld chosen by Cacti to index off of (see index_order above). Each eld contained within the SNMP query must be dened under this tag. Each dened eld 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 identiable within Cacti. Here you can specify a "friendly name" for the eld. This name will be used by Cacti to help the user identify this eld. Tell Cacti how you want it to gather SNMP information for this eld. get: The get method obtains a list of indexes and does an snmpget for each index of the OID specied for this eld.
walk : The walk method does a walk of the OID specied for this eld.

query->elds query->elds->ifIndex

query->elds->ifIndex->name query->elds->ifIndex->method

Both methods will return the same values, even though the walk method is typically more efcient.

19

Chapter 10. Data Queries Field query->elds->ifIndex->source Description When Cacti obtains a list for this eld, you need to tell it how to derive its value for each row. value: The value option simply returns the result of the snmpget for each row.
OID/REGEXP:(regexp_match): 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 le. VALUE/REGEXP:(regexp_match): The OID/REGEXP:(regexp_match) op-

tion can be used to parse the value based on a regular expression, returning the rst match.
index : Simply use the value of the index for this row as the value. If the

index is being parsed from the OID using the oid_index_parse eld, you must specify index here.

query->elds->ifIndex->direction

input: 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. output: Output values are "unknown" values that are returned from the script. An SNMP query may return multiple statistics for a single index. For instance, a single interface could return bytes/sec in, errors, packets/sec, etc. A rule of thumb is that input elds contain semi-static data that is not graphable, while the output elds contain the data that will be graphed.

query->elds->ifIndex->oid

You must specify the actual OID that corresponds with the eld. Each value for this eld can be obtained by doing an snmpget on oid.(each)snmpindex.

10.3. 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.</descri <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> <arg_num_indexes>num_indexes</arg_num_indexes> <output_delimeter>:</output_delimeter> <index_order>dskDevice:dskMount</index_order> <index_order_type>alphabetic</index_order_type> <index_title_format>|chosen_order_field|</index_title_format> <fields> <dskDevice> <name>Device Name</name> <direction>input</direction> <query_name>device</query_name> </dskDevice> </fields> </query>

Table 10-4. Script Query XML Field Reference Field Description 20

Chapter 10. Data Queries Field query->name query->description query->script_path Description (Optional) You can enter a "friendly name" for the script query here. It will not be used by Cacti, and is for identication only. (Optional) You can enter a description for the script query here. It will not be used by Cacti, and is for identication only. 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. Enter the argument that is to be passed to the script to retrieve a list of indexes. Enter the argument that is to be passed to the script to retrieve a list of values given a eld name. Enter the argument that is to be passed to the script to retrieve a single value given a eld name and index value. Enter the argument that is to be passed to the script to determine the total number of available indexes. If specied, this will be used to determine when to automatically recache this script query when it is attached to a device. 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. As of version 0.8.6, Cacti will attempt to nd the best eld to index off of based on whether each row in the query is unique and non-null. If specied, Cacti will perform this check on the elds listed here in the order specied. Only input elds can be specied and multiple elds should be delimited with a comma. For sorting purposes, specify whether the index is numeric or alphanumeric. numeric: The indexes in this script query are to be sorted numerically (ie. 1,2,3,10,20,31)
alphabetic: The indexes in this script query are to be sorted alphabetically

query->arg_index query->arg_query query->arg_get query->arg_num_indexes

query->output_delimeter

query->index_order

query->index_order_type

(1,10,2,20,3,31).

query->index_title_format

Specify the title format to use when representing an index to the user. Any input eld name can be used as a variable if enclosed in pipes (|). The variable |chosen_order_field| will be substituted with the eld chosen by Cacti to index off of (see index_order above). Each eld contained within the script query must be dened under this tag. Each dened eld 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 identiable within Cacti. Here you can specify a "friendly name" for the eld. This name will be used by Cacti to help the user identify this eld.
input: Input values are the "known" values that you will use to derive the

query->elds query->elds->dskDevice

query->elds->dskDevice->name query->elds->dskDevice>direction

output values, this is where the "query" part of script query comes in. When you create a graph based on a script query, Cacti will prompt you to choose the input value to base the graph on. output: Output values are "unknown" values that are returned from the script. A script query may return multiple statistics for a single index. For instance, a single partition could return free disk space, total disk space, fragmentation percentage, etc. A rule of thumb is that input elds contain semi-static data that is not graphable, while the output elds contain the data that will be graphed.

21

Chapter 10. Data Queries Field query->elds->dskDevice>query_name Description Enter the name that Cacti must use when asking the script for information about this eld. For instance, the following should return values: (script_name) query (query_name).

22

Chapter 11. Templates

11.1. 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.

11.1.1. Creating a Graph Template

To create a new graph template, select Graph Templates under the Templates heading and click Add. The rst 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 eld 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 eld on a per-eld 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 eld. Table 11-1. Field Description: Graph Templates Name Title Description 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 eld, 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 manual1 PNG is preferred because it is both smaller and faster. The height of the graph area in pixels The width of the graph area in pixels 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. Choose whether you would like to use --alt-autoscale or --alt-autoscale-max on the graph. The RRDTool graph manual1 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 dened on the command line, will be 0. This option can be useful when graphing router trafc when the WAN line uses compression, and thus the throughput may be higher than the WAN line speed. Choose if you want logarithmic y-axis scaling. From the RRDTool manual Normally rrdgraph will 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. 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. If you choose to use Cactis static HTML/image export, you can choose whether you want each individual graph to be exported. The maximum value that will be displayed on the y-axis. This value is ignored is auto-scaling is turned on. The minimum value that will be displayed on the y-axis. This value is ignored is auto-scaling is turned on. Whether you want to base the y-axis labels on 1000 or 1024. This eld will typically be set to 1024 for memory and 1000 for trafc measurements.

Height Width Auto Scale

Auto Scale Options

Logarithmic Auto Scaling Rigid Boundaries Mode

Auto Padding

Allow Graph Export Upper Limit Lower Limit Base Value

Chapter 11. Templates Name Unit Value Unit Exponent Value Description Sets the unit value for the y-axis. You should probably keep the unit short as to keep it readable. Sets the 10^e scaling of the y-axis. Valid values for this eld 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). The text to print on the left edge of the graph. Usually is the units the data on the graph is measured in.

Vertical Label

Note: For most graph templates, you will want to check the Use Per-Graph Value checkbox for the title eld so each graph using this template has its own unique title. It also makes sense to enter an initial value in this eld that includes the variable |host_description| for organizational purposes. When you are nished lling 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

11.1.1.1. Graph Items

The rst 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 doesnt have to make unnecessary assumptions later. Table 11-2. Field Description: Graph Template Items Name Data Source Description 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. Depending on the graph item type, you can select a color for the graph item. This eld only applies to the graph item types AREA, STACK, LINE1, LINE2, and LINE3.

Color

24

Chapter 11. Templates Name Graph Item Type Description This eld is important because it denes 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 specic 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 Function

This tells RRDTool which consolidation function to 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. 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. This eld 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. 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. You can enter text to be displayed on the legend here. This eld is applicable for all graph item types except for the virtual LEGEND type. Check this box to force graph items onto the next line.

CDEF Function Value GPRINT Type Text Format Hard Return

11.1.1.2. 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 eld, 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 elds that must be lled in for every graph item input: Table 11-3. Field Description: Graph Template Items Name Name Description Field Type Associated Graph Items Description This will be the name used to identify the graph item input on both the graph template and graph edit pages. (Optional) This description will be displayed on the graph edit page of any graph using this template if specied. You must choose the eld that you are going to associate with one or more graph items. Choose one or more graph items to associate with the eld selected for "Field Type". When the user species a value for the eld, it will be applied to all of the items you select here.

11.1.2. Applying Graph Templates to Graphs

Applying a graph template to a graph is a very simple process. The rst 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 elds 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 dened in the graph template. The values specied here will be applied to each graph item tied to the graph item input. 25

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

11.2. 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.

11.2.1. Creating a Data Template

To create a new data template, select Data Templates under the Templates heading and click Add. The rst 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 eld 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 eld on a per-eld 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 eld. Table 11-4. Field Description: Data Templates Name Name Description 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 eld, which will be automatically substituted with the current host description.

Data Source Path

The full path to the RRD le associated with this data source. When creating a new data source you will typically leave this eld blank as Cacti will generate one for you. If you are using an RRD le generated outside of Cacti, you need to specify it here. Here is where you tell cacti how it is supposed to 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 le is being populated outside of cacti, make sure to leave this eld set to "None". 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. This tells RRDTool how many seconds there will be between updates. The default is 300 seconds (5 minutes), and is sufcient for most installations. This is a quick and easy to tell Cacti to stop 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.

Data Input Method

Associated RRAs

Step Data Source Active

Note: For most data templates, you will want to check the Use Per-Graph Value checkbox for the name eld so each data source using this template has its own unique name. It also makes sense to enter an inital value in this eld that includes the variable |host_description| for organizational purposes. When you are nished lling in values for the data template, click Create and you will be presented with a screen similar to the data source edit screen.

26

Chapter 11. Templates

Figure 11-2. Adding a Data Template

11.2.1.1. 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 trafc, rather than having to create a separate data template for each. Table 11-5. Field Description: Data Source Items Name Description

Internal Data Source Name This is the name used by RRDTool to identify this particular data source within the RRD le. RRDTool places a limit of 19 alphanumeric characters (plus _ and -) on this eld. Minimum Value Here is where you specify the minimum value that is expected for this data source in the RRD le. If a value lower than the minimum is given, it will be stored as Unknown (U). Here is where you specify the maximum value that is expected for this data source in the RRD le. If a value higher than the maximum is given, it will be stored as Unknown (U). 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 overow, while a derive does not overow. The absolute type is used for counters that are reset upon reading. As dened by RRDTool: The maximum amount of time that can pass before data is entered as "unknown". This eld is usually 600 or 2 data gathering intervals.

Maximum Value

Data Source Type

Heartbeat

11.2.1.2. 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 eld is per-eld templatable as all of the other data source elds 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.

11.2.2. Applying Data Templates to Data Sources

Applying a data template to a data source is a very simple process. The rst thing you must do is select the data source 27

Chapter 11. Templates 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 elds 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.

11.3. Host Templates

Host templates in Cacti serve a different purpose then data and graph templates. Instead of abstracting the elds 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.

11.3.1. 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

28

Chapter 12. PHP Script Server

The PHP Script Server is a new feature in Cacti 0.8.6. This new feature allows for the rapid execution of PHP based Data Queries in Cacti. The Script Server process is launched by the poller during every polling cycle. It listens for commands from the poller, executes them, and then waits for an quit signal. The reason that it is so fast is that PHP is started in memory only one time, and for every Data Query called, its code is interpreted only once. The resulting Data Query binaries are therefore very efcient. Using the Script Server process over the traditional POPEN process nets a 20+ fold speed improvement in Cacti. Since PHP scripts are so powerful, this new feature in Cacti, makes it an excellent choice for collecting non-SNMP and SNMP based data.

12.1. Using the Script Server

Cacti 0.8.6 contains two sample script server routines. They are for the collection of HostMib CPU and Disk Partition information. These two examples are based off the traditional POPEN version of the HostMib functions found in earlier versions of Cacti. For new installs, the HostMib functions are defaulted to using the PHP Script Server, therefore, you dont need to do anything to use it. For upgrades, you must make several changes to start using the PHP Script Server for the HostMib CPU and HostMib Partitions Data Queries. To migrate you must follow the step below.

12.2. Upgrade Steps for the Example HostMib Data Queries

If you are using the two built in script queries, "SNMP - Get Mounted Partitions" and "SNMP - Get Processor Information", you can migrate to the PHP Script Server using the steps below: 1. Verify the existence of New Data Input Method - Go to Data Input Methods, verify that you see the "Get Script Server Data (Indexed)" Data Input Method exists and that it is using the "Script Query - Script Server" method. 2. Disable the Poller - Goto Settings->Poller and uncheck the Poller Enabled checkbox. Press Save. 3. Update Your Data Queries - Go to Data Queries and Edit the two Data Queries below. Change both their Data Input Method to "Get Script Server Data (Indexed)" and in the XML path replace "script_query" with "script_server" as shown below: a. SNMP - Get Mounted Partitions
<path_cacti>/resource/script_server/host_disk.xml

b. SNMP - Get Processor Information

<path_cacti>/resource/script_server/host_cpu.xml

4. Update Your Data Templates - Goto Data Templates, locate the following two data templates and change their data input method to "Get Script Server Data (Indexed)". a. Host MIB - Hard Drive Space b. Host MIB - CPU Utilization 5. Re Enable the Poller - Go to Settings->Poller and check the Poller Enabled checkbox. Press Save. Following those steps should complete your migration to the new PHP Script Server for the two example HostMIB Data Queries.

12.3. Migration of Existing PHP Scripts to Script Server

If you have other PHP scripts that you wish to migrate, you must follow the steps below to migrate your scripts to the PHP Script Server required format.

Chapter 12. PHP Script Server

12.3.1. Script File Changes

Each PHP Script le must be changed to the new Script Server format. The changes are not dramatic, but required for the proper operation of the PHP Script Server. Follow the steps below to complete. 1. Copy you existing script to a new name. The name must begin "ss_" followed by your script name. The "ss_" identies the script as being a script server variety of the a PHP script. For example, if you previously had a script called "get_mysql_stats.php", its new name would be "ss_get_mysql_stats.php". 2. Edit the new PHP script and add the following required lines to the le, where "ss_myfunction" is the same as your lename.
<?php $no_http_headers = true; /* display No errors */ error_reporting(E_ERROR); include_once(dirname(__FILE__) . "/../include/config.php"); include_once(dirname(__FILE__) . "/../lib/snmp.php"); if (!isset($called_by_script_server)) { array_shift($_SERVER["argv"]); print call_user_func_array("ss_myfunction", $_SERVER["argv"]); }

3. What was originally just mainline code, must be replaced with a function name. For example, if your program previously contained the following three lines of code:
<?php $a = 100; $b = $a / 10; print $b; ?>

Would become:
function ss_myfunction() { $a = 100; $b = $a / 10; Print $b; }

4. If you have any additional functions declared within your script le, you must prex them to make then unique amongst all functions. Our recommendation would be to prex all functions with the name of the main function. For example if you have a function called "meme" you would rename it to "ss_myfunction_meme". This guarantees correct Script Server functionality. 5. The last step is to change the function call that could have traditionally returned the value to the Cacti poller using the PRINT function. You must change that line or lines in your code to utilize the RETURN function instead. However, this does not apply to PRINT statements that are not called from the Poller.

12.3.2. XML File Changes

If you are using a "Script Query" type function, then you must also change your XML le. Please reference the XML les in the <path_cacti>/resource/script_server directory for the specics related to your required modications. However, you may also follow the instructions below: 1. Modify the <script_path> tag. Change it from:
<script_path>|path_php_binary| -q |path_cacti|/scripts/myfucntion.php</script_path>

to simply the following:

<script_path>|path_cacti|/scripts/ss_myfunction.php</script_path>

2. Add the following two XML tags below the <script_path> tag. Replace ss_myfunction with your function name:
<script_function>ss_myfunction</script_function> <script_server>php</script_server>

3. Save the XML le.

30

Chapter 12. PHP Script Server

12.3.3. Data Query & Data Template Changes

Your Data Queries and Data Templates must be also changed. Although somewhat self explanatory by now, you must make the following changes: 1. Change its Input Method to "Get Script Server Data" or "Get Script Server Data (Index)" depending on its type. Change the XML le path to point to the new XML le in the <path_cacti>/resources/script_server/*.xml path. For all data templates that use the data query you must change their "Data Input Method" accordingly. Your nal step is to go to the System Utilities and Clear Poller Cache to apply the new settings. If you script is operating correctly, you should now be migrated to the script server.

12.4. Testing Your Script in the Script Server

To test your script in the script server, simply follow the instructions below. When you have nished you testing, simply type "quit" <cr< at the Script Server command line to exit the script server. 1. Start the script server - You can do this by typing the following command:
shell> php <path_cacti>/script_server.php

NOTE: Due to a bug in Windows implementation of PHP, you must type the full path name to the script_server.php le. 2. Type in your command - Using the example from above, you would type in the following:
script server> <path_myfunction> my_function argument1 argument2 ...

In the Windows environment, your example could be the following:

script server> c:\wwwroot\cacti\scripts\ss_myfunction.php ss_myfunction localhost public 1 get duddle

3. If your function is operating properly, you should get a result. 4. To quit the script server, simply type "quit" <cr> at the command line. NOTE: If there are errors in your script, you must restart the script server before your retest your code.

31

Chapter 13. How To

13.1. 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 elds that will require input before the new graph can be created. They are described in more detail below. Table 13-1. Field Description: SNMP - Generic OID Template Name (Graph) Title (Graph) Vertical Label (Graph Items) Legend Color (Graph Items) Legend Text (Data Source) Name (Data Source) Maximum Value [snmp_oid] Description 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. The text that will be printed along the y-axis of the graph. It is generally used to describe units, such as bytes or percent. The color that will be used to reprent the data on the graph. The text that will be used to describe the data on the graph legend. The title that is to be used for the new data source. It is generally a good idea to keep |host_description| in the title, as to make the data source easier to identify later. The maximum value that will be accepted from the OID. Make sure you choose a value that is 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. How the data from the OID should be stored by RRDTool and interpreted on the graph. If the value of the OID represents the actual data, you should use GAUGE for this eld. If the OID value is a constantly incrimenting number, you should use COUNTER for this eld. The two remaining eld values, DERIVE and ABSOLUTE can be ignored in most situations. The actual SNMP OID to graph. It is typically a good idea to enter the number OID here as opposed to using MIB names. For instance, to get the number of open les on a Netware server, you would use ".1.3.6.1.4.1.23.2.28.2.7.0" as the OID.

(Data Source) Data Source Type [snmp_oid]

(Custom Data) OID

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

13.2. 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 difcult time understanding how to graph anything that wasnt 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 signicant 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.

Chapter 13. How To Ive 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 its 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 elds 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, were not using templates for this example. Click Create. Name: random2ds Data Source Path: blank (Cacti will ll this in) Data Input Source: Random 2 Input (this is the data input method you created in step 1) Highlight each of the Associated RRAs 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 33

Chapter 13. How To

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: cant 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 34

Chapter 13. How To

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 Well 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 rst data point and poll 3 to have graphable points. While waiting, you can click the RANDOM NUMBERS graph. Youll see place holders for 4 graphs. Select [source] under Daily (5 Minute Average). Youll 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 rst poll I got a few empty graphs. A few minutes later data started showing up.

35

Chapter 13. How To

Notes
1. http://kdeuja.com/~kevin/

36

Chapter 14. Frequently Asked Questions

1. Using Cacti How do I create trafc graphs? Before you can create trafc 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 Cactis menu. 2. Click Add to add a new device. 3. Type a description, hostname, management IP, and SNMP community. Make sure to select "Generic SNMPenabled 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 "Undened variable: _SERVER" error message from Cacti. Cacti 0.8.6 and above requires that you have at least PHP 4.1 or greater installed. I get a "Call to undened 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 le. 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=md5(admin) where username=admin;

3. Monitoring I am polling thousands of items and poller.php takes more than 5 minutes to run. Give cactid, the future replacement for poller.php a try. Unlike poller.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.

Chapter 14. Frequently Asked Questions

Redhat 8.0 comes with a broken php-snmp package. Updating your php-snmp and net-snmp packages to

their latest versions should x this problem. How do I congure net-snmp so it will work with Cacti? Run snmpconf -g basic_setup and follow the prompts. Also check that the le being used by snmpd is the correct cong le. For Redhat Linux, snmpconf creates the /etc/snmpd.conf, but snmpd uses /etc/snmpd/snmpd.conf. If this doesnt work a very simple cong le is:
# contact syslocation Something syscontact "[email protected]" # 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, poller.php must run at least once so it can create .rrd les in Cactis rra/ directory. Double check that you congured your /etc/crontab le to execute poller.php every ve minutes. Also make sure that the user poller.php runs as has permission to create new les in Cactis rra/ directory. If all of your settings appear correct, try running poller.php manually by cding to Cactis directory and typing:
shell> php poller.php

If you have les 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 problems cause is permissions. For instance if you run poller.php manually as root for testing, any .rrd les that it creates will be owned by root. Now when poller.php runs from cron, it will not be able to update these .rrd les because they are owned by root. You can double check the owner of your .rrd les 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 eld for all data sources used by these graphs. If the value being fed to the .rrd le 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 SNMPs 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 script1 that will remove them for you. 38

Chapter 14. Frequently Asked Questions

RRDTool Says: ERROR: unknown option --slope-mode or RRDTool Says: ERROR: Garbage :39:24 To 2005/10/22 16:39:24\c after command: COMMENT:From 2005/10/21 16:39:24 To 2005/10/22 16:39:24\c This occurs because the version of RRDTool that you are running does not match the RRDTool version Cacti is congured to use. Double check your Cacti Settings and make sure that the RRDTool version matches what version of RRDTool you are running. 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 le to make sure there is not something like include_path = C:/Apache2/htdocs/cacti.

Notes
1. http://cricket.sourceforge.net/contrib/les/killspike2

39

Chapter 15. Variables

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

15.1.1. 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 MRTGs "graph last updated" feature.

15.1.2. Data Query Fields

|query_field_name|

You can place the value of any data query eld on the by including this variable. Make sure to substitute "eld_name" with the actual data query eld name. Example 15-1. Print the IP Address on a trafc graph
|query_ifIP|

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

|query_dskPath|

15.1.3. Nth Percentile

|[0-9]:(bits|bytes):[0-9]:(current|total|max|total_peak|all_max_current|all_max_peak|aggregate_max|aggregate_sum|aggr

Nth percentile is often used by hosting providers to bill customers based on their peak trafc usage while ignoring their top (100 - Nth) percent. This way if a customer has a fairly consistent trafc pattern and decides to download a huge le one day, the large spike will be ignored. Common Nth percentile is 95, which would cut off the top 5% of the trafc. In Cacti, Nth percentile works just like any other graph variable. To use this variable you must give it ve arguments: Table 15-1. Nth Percentile Argument Description Name
[0-9] (bits|bytes) [0-9]

Description The rst argument is a number between 1 and 99. This number represents the Nth percentile that you would like to calculate. Choose whether you want to represent your Nth percentile in bits or bytes. The only valid values for this eld are bits and bytes. This eld determines the power of 10 divisor that will be applied to your Nth percentile number. Enter 0 to leave the number alone, 3 for kilo or 6 for mega, etc.

Chapter 15. Variables Name

( current | total | max | total_peak | all_max_current | all_max_peak | aggregate_max | aggregate_sum | aggregate ) [0-9]

Description Nth Percentile Type - Refer to Nth Types

Enter the number of digits to use for oating point precision when printing out the nal number. The default value for this eld is two decimal places.

Table 15-2. Nth Percentile Types Type

current

Description Calculates the Nth percentile based off the selected data source on the graph item wich the variable is used. This type requires a selected Data Source Item in the graph item in which it is dened. Calculates the Nth percentile based off the selected data source on the graph item wich the variable is used. But unlike current, this function totals the Nth percentile results of all same named data source names on the graph. Example, all trafc_in would have their Nth percentile calculated and then totaled. This type requires a selected Data Source Item in the graph item in which it is dened. Calculates the Nth percentile based off the selected data source on the graph item which the variable is used, but it is important to note that it selects the higher of the values for each row in data source and then uses the resulting set to calculate the Nth percentile. Example, you have selected a interface data source for trafc_in, this will evaluate trafc_out and trafc_in for that selected data source (rrdtool le) and select the higher of the two values for each row of data. The resulting max values are used to calculate the Nth percentile value. This type requires a selected Data Source Item in the graph item in which it is dened. Calculates the Nth percentile based on the max for each data source dened on the graph. Example, the max is taken for each data source dened on the graph, but its the max of trafc_in or trafc_out for that data source (rrdtool le). The resulting max values are summed and returned. Calculates the Nth percentile based off the selected data source on the graph item which the variable is used, but it only selects the highest (max) value of all the data source items on the graph. Example, there are 3 data sources dened on the graph, the selected data source is trafc_in, all data sources for trafc_in will be compared against each other and the highest Nth value of all graph items will be selected as the result. This type requires a selected Data Source Item in the graph item in which it is dened. Calculates the Nth percentile by selecting the highest (max) calculated max Nth percentile value for each data source (rrdtool le) selected on the graph. Example, 3 data sources are dened on the graph, for each data source, the max Nth percentile is calculated, and out of the resulting set of values, the highest value is selected and returned. Calculates the Nth percentile by selecting the highest value for each summed value of like data sources and selecting the maximum value of that set to calculate the Nth percentile value. Example, you have a graph with 5 trafc_in and 18 trafc_out data sources. The trafc_in rows are summed together, then the trafc_out rows are summed together, then for each row, the higher of the 2 values is selected. The Nth percentile is calculated from the resulting maximum values. Calculates the Nth percentile by summing all data sources on the graph row for row and calculates the Nth value on the resulting summed data. Example, you have a graph with 4 trafc_in and 3 trafc_out data sources dened. All the dened trafc_in and trafc_out are summed together and then the Nth percentile value is calculated from that set.

total

max

total_peak

all_max_current

all_max_peak

aggregate_max

aggregate_sum

41

Chapter 15. Variables Type

aggregate

Description Calculates the Nth percentile by summing like data source names row for row from each data source dened on the graph and then returning the highest Nth percent value calculated for like data source names. Example, you have a graph with 3 trafc_out and 5 trafc_in data sources dened. The trafc_in and trafc_out are summed then the Nth value is calculated and the higher of the 2 values is returned as the variable.

Concerning aggregate Nth percentile functions and rra denitions: All data sources used in a graph MUST have the same rra denitions. If the number of rows do not match when calculations are attempted, the results may produce errors and invalid results. Please also be aware the aggregate functions take more memory and processor power when used. Recommended minimum of 64 megs memory limit for php when querying large ranges or graphs with a large ammount of aggregated data sources.

Example 15-3. Output in the following format, for 95th percentile: 42.58 mbit
|95:bits:6:max:2|

15.1.4. 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 le for a given time range. This is typically useful on trafc graphs where you can see a total of all trafc 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 15-3. Bandwidth Summation Argument Description Name
([0-9]|auto)

Description This eld 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 eld to have Cacti automatically scale the number and insert the appropriate label. 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 eld are current and total. Enter the number of digits to use for oating point precision when printing out the nal number. The default value for this eld is two decimal places. 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 eld to have Cacti use the graph timespan.

(current|total)

[0-9] ([0-9]+|auto)

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

|sum:auto:current:2:auto|

15.2. 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 elds the correspond to. 42

Chapter 15. Variables Table 15-4. Host Variables Variable Name

|host_description| |host_hostname| |host_snmp_community| |host_snmp_version| |host_snmp_username| |host_snmp_password|

Description Description Hostname SNMP Community SNMP Version SNMP Username (v3) SNMP Password (v3)

43

Chapter 16. RRDTool Specic Features

16.1. 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.

16.1.1. 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 elds. Enter a name for your GPRINT preset, and the actual printf-like string in the GPRINT Text eld. When you are nished, click the Create button to create your new GPRINT preset.

16.2. 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 tutorial1.

16.2.1. 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 16-1. CDEF Item Types Type Function Operator Special Data Source Description You can choose a CDEF function to use as the item. The RRDTool graph manual2 describes the purpose of each CDEF function. Just your standard math operators, including modulo (%). A special data source is basically a ag to tell 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. You can recursively use another CDEF within this CDEF. Sometimes its 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 rst data source on the graph.

Another CDEF Custom String

Notes
1. http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/doc/rrdgraph_data.en.html