1) Extract the cacti tarball, like 'tar -xvzf cacti-0.3.tar.gz', and cd to the new directory.

2) Create a database for cacti using syntax like: mysqladmin -u root -p create cacti

3) Then import the cacti database: mysql -u root -p cacti < SQL

4) Edit config.php in 'include/', make sure to give a valid SQL user name, password, and database.

NOTE: Be sure the MySQL user you give cacti has at least:

SELECT
INSERT
UPDATE
DELETE
CREATE
ALTER

Privileges to cacti's database!

5) For cacti to run correctly, you must have the following settings set accordingly in your php.ini file:

register_globals = On
register_argc_argv = On

6) Become root, and add a line to your /etc/crontab similar to:
*/5 * * * * apache php PATH_TO_CMD.PHP/cmd.php > /dev/null 2>&1

Make sure to fill in the correct path to cacti on your system.

IMPORTANT!
Also, make sure you replace 'apache' with your web server user, this user MUST have write access to the following directories in order to log data and create the rrdtool RRA files.

log/*
rra/*

If files do not start appearing in the 'rra/' directory after 5 minutes of adding your crontab entry, check your permissions.

7) Point your browser to http://servername/cacti/, or where ever else you put it.

8) For each new install/upgrade, cacti will check the variables in config.php to make sure everything is valid. If everything looks ok, then cacti will update the database if it finds a previous version and give you any last minute information.

9) Go to http://servername/cacti/ again to use cacti. For new installs, you must login in with the account name of admin with a password of admin you will be forced to change this password once you successfully login for the first time.

10) Sample graphs have already been created, yet data will not begin to be gathered until the entry in crontab has been successfully setup.

By default cacti comes with the following users:

admin - This user has privileges to everything in cacti, comes with the password 'admin' by default.
guest - The user that is used to view graphs with. You do not need a password to view graphs by default, so it is advised not to give this user extra permissions.

Login to cacti with 'admin' or another eqivilant user and select "User Administration" on the cacti menu.

To add a new user, click the 'Add' link on the main user administration page.

Full Name - A description of this user.

User Name (Required) - The user name assigned to this user, no spaces please.

Password (Required) - Enter this user's password twice.

User Must Change Password at Next Login - Check this box to force this user to change their password upon their next successful login.

Allow this User to Keep Custom Graph Settings - If you check this box this user will be allowed to set custom graph-view settings such as graph columns, height, width and page refresh times. This will also determine if a user can expand/contract branches in a graph hierarchy. NOTE: Even if you deny a user from changing their graph settings, the existing settings will still be used. This will allow administrators to create "default" settings for each user.

User Has Rights to View ... - This allows you to specify what graph sections this user is allowed to view.

Login Settings - Control what page is displayed immediatly after this user logs in.

Once the user is created, it will not be able to login until you assign it at least the 'Console Access' privilege under 'Allowed Sections'.

To change the graph permissions for any user, select "Graph Permissions" next to the username under the "User Administration" section of cacti.

In the first section, check each graph you want to DENY this user from. This is the most secure way to deny users from viewing graphs, since there is no obvious way a sneaky user could bookmark an unauthorized graph to view it. Graphs which users do not have permission to view will be hidden from the user in all areas of cacti.

In the second section, check each graph hierarchy you want to HIDE from this user. Please note that this method only hides the graph hierarchy from view and does not explicitly deny it like the above options.

For further user control, refer to the "User Has Rights to View ..." section of Adding a New User.

Creating a simple, rrdtool based graph is a very easy with cacti. Even using more advanced features such as CDEF's are much easier than implementing them manually.

The basic "flow" of things in cacti is as follows:

Data Input Sources are required for Data Sources to gather data. They pretty much tell where a Data Source to get data from. A Data Source is some piece of data you are gathering whether is be processes on a server, traffic on a switch, or whatever. You can then place Data Sources on graphs to show the data that has been gathered.

A data input source is simply an external program that is called to gather data for cacti.

Every five minutes, each data input is called for each data source it is used in. Input for the external programs can be gathered on a per-data source basis and can be fully customized. Output parameters are also defined telling cacti what to expect back from the external program. One of these parameters must be used to for updating the .rrd file, but more can be specified and stored in the database for use on the graph.

The following data sources come with cacti and can be used to gather data for your graphs.

Get Custom TCP Connections - Give a string to "grep" for in netstat output and outputs the number of resulting lines.
Get Load Average - Specify either (5,15, or 30) to return a load average for that interval (yes I know it's 1, 5, and 10, probably only works right on Linux).
Get Logged In Users - Pass a username to get the number of instances of that user logged in, or NULL to return the total number of users logged in.
Get Memory Usage - Give it a "grep" string to use on the output of /proc/meminfo to return memory statistics on a Linux machine.
Get Number of Open Samba Files - Returns the number of open Samba files.
Get SNMP Data - Give it a host, SNMP community and OID and it returns the value for that SNMP OID.
Get SNMP Network Data - (Used for builtin SNMP support) Give it a host, SNMP community, "in" or "out", and one or more of the following: interface MAC Address, IP Address, Number, or Description. This script will then return the SNMP counter value representing this interface's traffic.
Get SQL Connections - Returns the number of "questions" asked of a MySQL server. You may have to edit the username and password in the script (sql.pl).
Get Web Hits - Returns the number of lines in any file specified (you would normally specify the path to an Apache log file).
Ping Host - Return the number of milliseconds it takes to respond given a hostname and the number of times to ping the host.

1. Click "Data Source" on the cacti menu and click "Add" to create a new data input source.

Name - Make up some meaningful name for this data input source to identify what it is used for.

Input String - You must specify the path to the external program you are calling, along with any parameters (optional) that the user must enter. A typical input string looks similar to the following:

/path/to/script.pl <arg1> <arg2>

With the following setup, every time the user created a data source using this data input source they would have to enter a value for "arg1" and "arg2". For demonstration sake, let's say this was a ping script that took an IP address and number of times to ping as arguments, cacti would then execute a command similar to:

/path/to/script.pl 192.168.1.1 2

Output String - Cacti needs to know what to expect back from the script and is setup the same way as the input string. Let's say our ping script above returns milliseconds and "up" or "down". The output string would probably looks something like:

That of course assumes that the external program delimits the output arguments with spaces, make to sure format your output string appropriately. Also note that unlike the input string, every data input source must have at least one output argument!

2. Click save once you have finished filling in all of the fields. You will now see "Current Data Input Source Fields" lower down on the page. You must create an entry here for EVERY input and output argument used above.

3. Click "Add" to begin defining your fields.

Name - The friendly name cacti will use to refer to this field, you may type anything meaningful here.

Data Name - Enter the name of this field matching it EXACTLY to its use in the input/output string. Please do not include the "<" and ">" signs here. This field also cannot contain spaces or other non-alphanumeric characters. Good entries here would be like ("ms", "output_str", "arg1", or "string").

Input/Output Field - You MUST select whether this argument is used in the input or output string.

Use for RRA - If you want data sources using this data input source to keep track of the data gathered then you MUST check this box for at one of your output arguments. Since rrdtool can only store numbers, only check this box for an output argument that returns a number. UPDATE: You may check this box for each output argument you want to write to the .rrd file. If you check this box more than once, cacti will automatically create an additional data sources for each output item when creating a new data source using this data input source.

4. Your data input source will now be available for use in any data source.

A data source is basically some piece of data that is being gathered. This data can come from cacti's builtin data input sources or can come from an external .rrd file. Both methods allow you to graph data the same way. Whether you want to graph incoming traffic on a switch port or the 1 minute load average on your mail server, you will need to create a data source for it.

1. Click "Data Sources" on the cacti menu and click "Add" to create a new data source. Keep in mind that if cacti is not gathering data for this data source, only the first 3 fields are required!

Name - The name used by rrdtool and cacti to identify this data source. You cannot use names longer than 19 characters or use non-alphanumeric characters (except "_"). Bad names in this field are one of the most common reasons a graph does not render or a data source does not get created.

(Optional) Internal Data Source Name - Used only if cacti is not gathering data for this data source! Enter the data source name used in your .rrd file here. Remember that MRTG uses the data source names of "ds0" and "ds1" for incoming out outgoing traffic.

(Optional) Data Source Path - Used only if cacti is not gathering data for this data source! Enter the full unix path to the .rrd file containing the data for this data source.

Data Source Type - Describes what kind of data this data source will handle. Basically use "GAUGE" for numbers that do not increment (processes, temperature, etc) and "COUNTER" for values that increment (traffic, etc). More information can be found here.

Data Input Type - If cacti is gathering data for this data source, please select the data input source to use from the list. You will be able to enter the input arguments for the data input source after saving the data source.

Associated RRA's - What RRA's to use when gathering data. Unless you know to do otherwise, select ALL of the values from this list.

Heartbeat - As defined by rrdtool: The maximum amount of time that can pass before data is entered as "unknown". This field is usually "600" or 2 data gathering intervals.

Minimum Value - The lowest possible number that rrdtool will allow for this data source, usually "0" for most purposes.

Maximum Value - The highest possible number that rrdtool will allow for this data source. Remember to be generous with this value as numbers higher than the maximum will be stored as "Unknown". When graphing traffic, this number is usually the maximum throughput (in bytes) of an interface.

Update Changes in .rrd File - If this box is checked, cacti will attempt to execute an rrdtool 'tune' function when you save this data source. This allows you to save updated min/max values, heartbeat, data source type and name settings to the .rrd file.

Active - Only check this box if cacti is to be gathering data for this data source. Also can be useful to temporarily stop cacti from gathering data for this data source.

2. Click save to return to the main data source screen.

UPDATE: If you create a data source that has more than one output to be saved to the .rrd file, cacti will automatically create the additional data sources necessary. These "sub-data sources" will inherit the basic settings (data source type, heartbeat, and min/max values) from the data source you just created. It is usually a good idea to make sure these settings are accurate before going any further.

3. If cacti is gathering data for this data source, click "Edit Data" next to the data source you just created. You will be able to enter data for any input arguments defined in the Input String (see Data Input Sources). You are required to enter data for all available fields or cacti will not gather data correctly!

4. Your data source will now be available for use in any graph.

Round Robin Archives (RRA's) usually do not need to be modified, but can be useful for graphing over non-standard time periods like two days or full resolution over a year. The fields for Round Robin Archives in cacti are pulled almost exactly from rrdtool. Beware that you can mess up data gathering and the look of your graphs by messing with these settings. Read more about how to use Round Robin Archives here.

CDEF's serve the same function as with traditional rrdtool-based graphs. If you don't understand CDEF's please see the official documentation or tutorial.

CDEF's are useful when you want to "alter" the data you have gathered for display on a graph. This is done builtin math functions in RPN (Reverse Polish Notation). Some common uses are: unit conversions, simple math, and summing up data are just a few.

In cacti you do write a out a CDEF statement like you may be used to, instead you "build" it.

1. Click "CDEF's" on the cacti menu and click "Add" to create a new CDEF.

Name - Enter any enter name to describe this CDEF.

2. Click save to return to the main CDEF page.

3. Click "Edit Current CDEF" next to the CDEF that you just created.

In this screen you will add each of the CDEF items separately. For instance if you had the statement: dsname,8,*; you would add the data source name, the "8" and finally the "*" separately. This is why I reffer to it as "building" a CDEF statement.

4. Click "Add" to add an item to this statement.

Data Source - Choose this option if you are inserting a data source, then choose it from the list. The "Use the current data source being used on the graph instead of a preset one." checkbox should be used when you do not know what data source will be used since it could vary depending on the graph it's used in. If you select this box, the data source you select above will be ignored.

CDEF Function - Select this if you want to insert a CDEF math function, then select it from the list.

Custom Entry - If you want to enter an arbitrary value such a number or other function, select this and enter your value in the box.

5. Click save and repeat this step as many times as is necessary. Also note that you do not have to include the commas in your CDEF statement, cacti will insert them for you.

1. Click "Graphs" on the cacti menu, and click "Add" to create a new graph.

Title - A name for this graph, can contain any character and is printed at the top of each graph.

Height - The height (in pixels) that the graph is.

Width - The width (in pixels) that the graph is.

Use Rigid Boundaries Mode (--rigid) - 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."

Auto Scale - Enable auto scale in 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.

Use --alt-autoscale - From the rrdtool manual "Compute Y range based on function absolute minimum and maximum values. Default algorithm uses predefined set of ranges. This is good in many cases but it fails miserably when you need to graph something like 260 + 0.001 * sin(x). Default algorithm will use Y range from 250 to 300 and on the graph you will see almost straight line. With --alt-autoscale Y range will be from slightly less the 260 - 0.001 to slightly more then 260 + 0.001 and periodic behavior will be seen. (contributed by Sasha Mikheev)"

Use --alt-autoscale-max - From the rrdtool manual "Where --alt-autoscale will modify both the absolute maximum AND minimum values, this option will only affect the maximum value. The minimum value, if not defined on the command line, will be 0. This option can be useful when graphing router traffic when the WAN line uses compression, and thus the throughput may be higher than the WAN line speed."

Auto Padding - If you have ever created rrdtool-based graphs manually, you may have realized how annoying it can be to get text to line up properly. With this option cacti will do its best to make the columns on your graph legend line up.

Auto Padding is not perfect and is best for graphs with consistent fields in each column. Auto padding also creates a small overhead when rendering graphs due to the extra text processing that is required.

Allow Grouping - Grouping a is new feature which "groups" the GPRINT items on a graph to its "parent" item. This allows you to change the sequence of an entire group without changing each item individually, removing a parent also removes its child items. It is recommended that you use this feature since if anything it makes the graph items easier to visualize. Also, if you are graphing MAX lines (like in newer versions of MRTG), you want this feature turned on since it will prevent anomalies from happening on the graph legend. Either way, this feature can be turned on and off at any time, cacti will take care of grouping any graph that was previously not grouped without changing the order of items.

Allow Graph Export - If you are using cacti's graph export feature, you can select whether this graph will be exported here.

Upper Limit - The highest value to display on the Y-axis.

Lower Limit - The lowest value to display on the Y-axis.

Base Value - How to label the Y-axis. Use 1024 for memory and 1000 for traffic measurements.

Vertical Label - The text to print on the left edge of the graph. Usually is the units the data in the graph is measured in.

2. Click save to return to the main graph page.

1. Click "Edit Graph Items" next to any graph on the Graphs page in cacti.

In the section of cacti, you will build your graph piece by piece; much how you would stack building blocks. Creating a graph is very simple; but it still helps to know a little about how rrdtool graphs work. Make sure to get comfortable with this manual first.

2. Click "Add" to add a new item to the graph.

Data Source - Where to get data from for this graph item. Whether you are printing out this information using text (GPRINT) or graphically (AREA, STACK, LINE[1-3]), you must select the data source to pull this information from. Some graph items will not have a data source, for instance if you are printing text or using HRULE/VRULE's.

Item Group - If you are using cacti's graph grouping feature; you can select which parent item this child item belongs to. Note: If you are adding a parent item (AREA, STACK, LINE[1-3]) this field will be ignored. Also, by default the last parent item added will automatically be selected for convenience.

Color - The color to use when putting the information on the graph. This color is only for graph data, and not for text. Only applies to: AREA, STACK, LINE[1-3], VRULE, and HRULE.

Graph Item Type - How the data is to be represented on the graph. Represent data on the graph using: AREA, STACK, and LINE[1-3]. Add vertical/horizontal lines to the graph using: VRULE and HRULE. Add text the legend area by using COMMENT and GPRINT.

One useful note: You must always put an AREA item before using STACK or your graph will not render.

Consolidation Function - How data is to be represented on a graph. Normally AVERAGE is used to represent an average over the selected time span. But LAST, MIN, and MAX can also be used to display other kinds of data too.

CDEF Function - If you want to apply a CDEF function to this graph item, select it here. Look at the CDEF section of the cacti documentation for more information.

Value - This field is only used with the HRULE/VRULE graph item types. Type the value of the appropriate (X/Y) axis to draw the line at.

Text Format - The text-based label for the legend. You may type any text here to appear on the graph's legend. You may also put data input/output sources here using the syntax: <dataname>. Get more information on data input sources in cacti if you do not understand how this works.

Insert Hard Return - Check this box to force graph items onto the next line.

3. Click save to return to the graph items page. Repeat step 2 until your graph is complete. Check out some of the graphs that come with cacti to see how to create a working graph.