CACTI howto

Cacti 0.8.6j Manual

The Cacti Manual
Ian Berry
Tony Roman
Larry Adams
J.P. Pasnak, CD
Jimmy Conner
Reinhard Scheck

© 2007 The Cacti Group

1. Installation

This section covers some general installation instructions. Detailed OS specific installation instructions are available for and

1. Requirements

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

• RRDTool 1.0.49 or 1.2.x or greater

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

• PHP 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

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

  • RRDTool 1.0.49 or 1.2.x or greater

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

  • PHP 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

  • net/net-snmp

  • www/php4-cgi

  • lang/php4 (With MySQL and SNMP Support)

  • databases/mysql323-server

2. Installing Under Unix

1. Extract the distribution tarball.

   shell> tar xzvf cacti-version.tar.gz
   

2. Create the MySQL database:

   shell> mysqladmin --user=root create cacti
   

3. Import the default cacti database:

   shell> mysql cacti < cacti.sql
   
   

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

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

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

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

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

   shell> chown -R cactiuser rra/ log/
   
   

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

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

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

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

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

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

   shell> chown -R cactiuser rra/ log/
   
   

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

9. Edit your PHP Config File at /etc/php.ini to allocate sufficient memory for Cacti:

   memory_limit=128m

10. Point your web browser to:

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

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 filenames to reference it's 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 file 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 filenames to reference it's binaries in Cacti.

Configure PHP

1. If using PHP 4, move the files 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 file 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
   

   You must configure PHP to have sufficient memory to return database rows. In order to accomplish that, you must set the memory_limit variable.

   memory_limit=128m

   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 DLL's to the c:\winnt\system32 directory. If so, you will have to remove those files. Please review the PHP installation documentation for instructions on removing those files.

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 file in the location pointed to by the MIBDIRS Windows System environment variable.

Configure the Webserver (Apache)

1. Make sure you have stopped any IIS web servers before you proceed with Apache installation, or make sure Apache is configured 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 file. You can edit that file by selecting Start | All Programs | Apache HTTP Server X.XX | Configure Server | Edit the httpd.conf file pick from the Taskbar.

   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
   

Configure 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 Configuration 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 file. Name the filter "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 file, enable Set Extension status to Enable, and click OK.

6. Give the IUSR_XXXX and IIS_WPG users read & execute permissions to the file %windir%\system32\cmd.exe. They will also need read permissions on cacti_web_root/cacti and it's 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 conflicts.

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 file from the Cacti web site to c:\cacti\rrdtool.exe.

Install MySQL

1. Extract the MySQL zip file 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.

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 field. 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 file names as Cacti does not them as long file 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 file to c:\cacti and modify the cactid.conf.dist file 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 files and sh.exe from the c:\cacti directory.

Configure Cacti

1. Edit cacti_web_root/cacti/include/config.php and specify the MySQL user, password, database, and database port for your Cacti configuration.

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

2. Point your web browser to:

   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
   

   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 Logfile 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 it's name, there should be some SNMP information listed, if not you should double check the SNMP settings on the server and firewall 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 you'll 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 HostsPerProcess:2 DataSources:4 RRDsProcessed:2
   

   After this has ran once, you should have cacti.log in /cacti/log/ and rrd files 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.

   1. Select Start --> Settings --> Control Panel and double click on Scheduled Tasks.

   2. Double click on Add Scheduled Task.

   3. Click Next and Browse on the following screen. Find c:\php and select php.exe. Choose Daily on and click Next.

   4. Click Next again without changing the time or date settings.

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

   6. Click Next and Finish to close the wizard.

   7. Right click on the task you just created, and select Properties.

   8. Select the Schedule tab.

   9. Make sure Daily is selected and click the Advanced button.

   10. Check the Repeat checkbox, set it for 5 minutes and set the duration for 24 hours.

   11. Click Ok

   12. 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:

   1. If you have Cygwin installed, then the patch instructions which use wget and patch, will work.

   2. The other method requires you to visit and manually download and replace the patched files.

2. You might need to reapply file/folder security on the files patched. Double check they are correct.

4. Upgrading Cacti

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 flags for the MySQL username and password. This user must have permission to read from Cacti's database or you will end up with an empty backup.

Backup the old Cacti directory.

shell> mv cacti cacti_old

Extract the distribution tarball.

shell> tar xzvf cacti-version.tar.gz

Rename the new Cacti directory to match the old one.

shell> mv cacti-version cacti

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

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

Copy the *.rrd files from the old Cacti directory.

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

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 don't exist or are newer than the distribution's.

shell> cp -u cacti_old/scripts/* cacti/scripts/

Copy any relevant custom resource XML files from the old Cacti directory. Some resource XML files are updated between versions. Therefore, make sure you only over write if the XML files either don't exist or are newer than the distribution's.

shell> cp -u -R cacti_old/resource/* cacti/resource/

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

shell> chown -R cactiuser rra/ log/

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

Point your web browser to:

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

2. Basics

Insert some filler text, so it's not just blank.

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

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

6. How to Graph Your Network

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

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

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

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

Figure 6-1. Adding a New Device

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

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

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

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

Table 6-1. SNMP Retrieval Types

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

7. Viewing Graphs

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.

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

Figure 7-1. Editing a Graph Tree

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

8. User Management

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

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

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