« A look at AppleScriptObjC | Main | UTI's don't work if you don't set them correctly [UPDATES] »

So, as promised, here is the Cacti version of my Nagios articles, (here and here.) Note, if you do not have a lot of experience with SNMP, you'll want to read up on that, as Cacti is all about the SNMP. I've a couple articles on those too. A primer here, and one focusing specifically on SNMPv3 is here.

Basic Install

Fortunately, setting up Cacti is really simple, and the docs are reasonably solid, with only a few things that tripped me up. For me, the biggest annoyance was creating the MySQL Database, mostly because I just don't deal with MySQL that much, so I tend to gradually forget what I've learned. I didn't have to spend a lot of time mucking about with the PHP configuration. In fact, as I remember, I didn't mess with the PHP config at all.

For MySQL, since I'm running Cacti and Nagios on the same box, I'm using the "nagios" user as the MySQL user for Cacti, and that user has full control over the Cacti DB, but only on that machine. I also highly recommend not allowing root MySQL access from anywhere but the physical MySQL server.

You can put Cacti anywhere you want on your machine, as long as Apache knows about it. I install it inside of /usr/local/nagios/share/, which is the root directory for my Nagios site, and symlink then actual Cacti install directory to /usr/local/nagios/share/cacti, so that I can take advantage of my Nagios setup, and make upgrades/rollbacks easier.

Actually installing Cacti is pretty simple:

1. Download the Cacti distribution


2. Unpack it in location you want it to be, and set the user/group permissions as needed.

That's the basic install for Cacti: Pretty simple, but there's a few more things to do before we can start configuring Cacti. (One thing I highly recommend is not renaming the Cacti directory to just "cacti", but rather making a symlink for that. As I said before, it makes upgrades and rolling back FAR easier.)

You'll need to make sure you have RRD installed, as Cacti needs that to actually create the graphs you'll view. I install RRD from MacPorts, one, because it's much simpler, (RRD has a lot of requirements & prereqs), and two, because with MacPorts, it's not installed in system directories, so OS updates are less likely to mess you up.

RRD

With the current version of Cacti, (0.8.7e), you want to make sure you are current on your version of RRDTool. I'm using 1.3.6 with Cacti, and it seems to work fine. If you upgrade RRDTool, you'll want to do so in a way that lets you revert easily (such as MacPorts). I've had to do that once or twice when I installed a too-new version for Cacti to work with.

MySQL

You'll also want to make sure the MySQL libraries & headers are installed as they aren't installed by default in Leopard and Leopard Server. (Yes, I agree, stupid.)

If you haven't yet done so, you'll want to set up and configure SNMP on the Cacti Server itself, including SNMPv3, as you will be spending a lot of time getting used to configuring Cacti, and making mistakes, so doing your initial setup and testing all on the local server is much simpler.

Once that's done, then set up MySQL for Cacti (Note: I am assuming you are conversant with basic MySQL setups under Mac OS X Server. If not, you'll want to spend some time on the MySQL web site, and Apple's documentation first. However, tackling that here is a bit out of scope for this article.):

1. Create the user Cacti will access the database as. If the database server is on the same server as Cacti, then this user only needs access from localhost/127.0.0.1. If not, then limit the network access as much as possible.
2. Create the Cacti database. You can name it whatever you want, but everything assumes you name it "Cacti" and if you get clever here, you'll be doing extra work forever. Clever should be saved for when you need it, and there's no reason to be clever here.
3. Import the default Cacti database via the cacti.sql script in the root of the Cacti directory
4. Give the Cacti user full rights to the Cacti database and only the Cacti database.

Next, set up the config.php file in $CACTIHOME$/include/config.php, so that Cacti knows what database on what server to use and has access to it.

Cacti Spine

Now, you'll want to install and set up Spine. Normally, Cacti's poller engine is a PHP process, and for light monitoring, that's fine. However, at some point, you can get to where the poller never finishes, because a scan takes longer than the polling period timeout. To help with that, you can optionally use Spine, which is a compiled poller engine written in C. It's a lot faster, but requires separate compilation and setup. The directions for its setup are solid, and it really does allow you to manage a lot more machines than the straight PHP poller.

Spine & SNMP on Mac OS X 10.5.7 Warning
If you read the notes on the security updates in 10.5.7, you'll notice that some SNMP libraries were changed. For the most part, this doesn't affect much of anything other than Spine. If you're trying to run Spine on 10.5.7, you will probably see, (up through version 0.8.7d, this is fixed in 0.8.7e and later) the following error:

SPINE: Poller[0] ERROR: SNMP Library Version Mismatch (5.4.1 vs 5.4.2.1) (Spine parent)

This is because Spine is very particular about versions and when they arent explicitly declared, things break. The workaround, until Spine changes how they do things, or whatever in netsnmplib 5.4.x isn't causing problems is to add the following line:

#define PACKAGE_VERSION "5.4.2.1"

to /usr/include/net-snmp/net-snmp-config.h, and then rebuild Spine. I did that, and it's been working fine ever since.

Apache

So we now have the Cacti side of things done, next, Apache. For Cacti to be able to work, you have to have PHP enabled and functional in Mac OS X Server. Cacti can't run without PHP. Period. For Mac OS X Server, you just create a site for Cacti, with the root of the site pointing to $CACTIHOME$. You'll want to make sure that index.php is a valid home page for the site, as that is Cacti's home page.

Initial Setup

So now, assuming you have everything set up correctly, load up Cacti's home page. The initial userid and password are both "admin", so you'll want to change those immediately. Cacti has a wizard of sorts, but that mostly is so you can set up the paths to things like the paths to rrdtool et al. (Shown in the screencap below.) Once that's done, you'll be at the base Cacti home page, and ready to do your initial setup.

Before we move on to the initial setup, let's look at the Cacti upgrade process, since it's pretty similar to the install.

Upgrade Notes

Because the basic Cacti install is not much beyond moving the new version to where the old version was, (assuming you aren't using plugins. Cacti plugins will of course, complicate this right up), building and installing a new version of Spine and pointing things to the new version, the upgrades are pretty simple. My method is:

1. Download and unpack the new version of Cacti and Spine


2. Copy the new version of Cacti, (not Spine), to the directory I keep Cacti in. (In my case, /usr/local/nagios/share) Don't rename the directory, keep the original name with version numbers.


3. Make sure the permissions on the new version's directory are correct


4. In the new version, set the database info in $CACTIHOME/include/config.php for the new version to match the info in the old version


5. Copy the .rrd files from the $CACTIHOME/rra/ in the old version to the new version, watch their permissions


6. Build and install Spine in its default location


7. Copy the spine executable from the install location, /usr/local/spine/bin, to its working location, (this makes rebuilding, building new versions easier), after making a backup of the 'old' version of spine. For me, this is /usr/local/nagios/share/cacti_spine


8. To be on the safe side, you should also do a backup of your MySQL DB. Sometimes new versions of Cacti change things, and if you don't back up your DB, rolling back could be hard, if you end up needing to.


9. Point the 'cacti' symlink from the old version of Cacti to the new version of Cacti


10. Log into the Cacti homepage, and let the upgrade wizard do its thing.


11. Fire up the poller, (detailed later) and test. If something doesn't work, then you can usually roll back by pointing the symlink at the old version, and (if you have to), restoring the database from your backup.

(Note: We'll get to setting up the launchd job to run the Cacti Poller once we've gone over some of the basic setttings and setup.)

Settings

By default, Cacti is primarily an SNMP tool, so you'll need to have SNMP set up on the machines you want to monitor. However, instead of immediately creating devices, you'll want to spend some time in the settings. (This is assuming you made it through the first run setup script, which is pretty easy to deal with. You make sure the paths to things like snmpget, snmpbulkwalk, rrdtool, and php are set correctly, and you should be at the login page)

General Settings

This is where you set up things like logging, SNMP versions, RRDTool versions, and your SNMP defaults. That last bit is something you'll really want to pay attention to, as you'll save yourself a lot of really tedious work here. The SNMP Defaults section is where you set up the default SNMP v1/v2c & v3 defaults, along with the default version of SNMP to use. You can override this in the templates, and I'll show you that later on. (Templates are your life in Cacti. Time spent with them saves you GOBs of time later.) One warning is that Cacti displays the SNMP v3 Privacy Passphrase in plain text. So don't just let anyone in the settings page. Luckily, Cacti lets you create multiple levels of user.

Paths

Pretty obvious, this is where you set the paths to things. Normally, this is created on initial setup, so the only thing you'll normally have to add manually is the path to Spine, if you're using it.

Poller

This is where you'll probably spend the most time, settings-wise. If you are going to tweak the poller settings, either max number of processes, (cmd.php) or max threads/process, (spine), do so in small amounts, and monitor the results carefully. It's really easy to cause yourself a lot of pain if you get too radical with things.

In general, the big thing is to watch your Poller & Cron interval. If a complete polling takes longer than the allowed period, you can run into problems. So, you'll want to keep an eye on the log files, which will tell you how long things take. You can also run the poller manually, via php $CACTIHOME$/poller.php At the end of the run, Cacti prints timing info. Pay attention to that.

Authentication

While Cacti supports LDAP auth, I've not implemented that, since we don't have a lot of users, (really, only two categories: View Graphs Only, God. Keeps it simple), and I haven't had a need to change it. However, be careful here, authentication issues can make it not only hard to use Cacti, but can keep you from using it at all. In other words, don't be too clever.

User Management

Cacti gives you the ability to create multiple levels of users with really fine-tuned permissions. However, be careful, and don't create more classes of user than you have to. For my setup, I have two users. The administrator, who's god, and a "viewgraph" user, who can only view existing graphs, nothing more. So far that's worked well for me, but if you find yourself needing more, well, here's what you can do for user settings:

Realms settings

Graph permissions

Default graph settings

System Utilities

This is primarily for things like log access, cache access, etc. Cacti has a configurable logging level that can be invaluable when you're first getting used to the application, or troubleshooting errors, as you can set it to varying degrees of detail from "Yes, stuff happened", aka "Apple Release Note" to "here we see the interaction of quarks at the subatomic level". If you have a large number of users using Cacti, the User Log is handy for tracking user activity.

That takes care of the initial installation, and some of the settings. Next up...creating our graph trees and first devices!

Comments

So, as promised, here is the Cacti version of my Nagios articles, (here and here.) Note, if you do not have a lot of experience with SNMP, you'll want to read up on that, as Cacti is all about the SNMP. I've a couple articles on those too. A primer here, and one focusing specifically on SNMPv3 is here. Basic Install Fortunately, setting up Cacti is really simple, and the docs are reasonably solid, with only a few things that tripped me up. For me, the biggest annoyance was creating the MySQL Database, mostly because I just don't deal with MySQL that much, so I tend to gradually forget what I've learned. I didn't have to spend a lot of time mucking about with the PHP configuration. In fact, as I remember, I didn't mess with the PHP config at all. For MySQL, since I'm running Cacti and Nagios on the same box, I'm using the "nagios" user as the MySQL user for Cacti, and that user has full control over the Cacti DB, but only on that machine. I also highly recommend not allowing root MySQL access from anywhere but the physical MySQL server. You can put Cacti anywhere you want on your machine, as long as Apache knows about it. I install it inside of /usr/local/nagios/share/, which is the root directory for my Nagios site, and symlink then actual Cacti install directory to /usr/local/nagios/share/cacti, so that I can take advantage of my Nagios setup, and make upgrades/rollbacks easier. Actually installing Cacti is pretty simple:

1. Download the Cacti distribution
2. Unpack it in location you want it to be, and set the user/group permissions as needed.

That's the basic install for Cacti: Pretty simple, but there's a few more things to do before we can start configuring Cacti. (One thing I highly recommend is not renaming the Cacti directory to just "cacti", but rather making a symlink for that. As I said before, it makes upgrades and rolling back FAR easier.) You'll need to make sure you have RRD installed, as Cacti needs that to actually create the graphs you'll view. I install RRD from MacPorts, one, because it's much simpler, (RRD has a lot of requirements & prereqs), and two, because with MacPorts, it's not installed in system directories, so OS updates are less likely to mess you up. RRD With the current version of Cacti, (0.8.7e), you want to make sure you are current on your version of RRDTool. I'm using 1.3.6 with Cacti, and it seems to work fine. If you upgrade RRDTool, you'll want to do so in a way that lets you revert easily (such as MacPorts). I've had to do that once or twice when I installed a too-new version for Cacti to work with. MySQL You'll also want to make sure the MySQL libraries & headers are installed as they aren't installed by default in Leopard and Leopard Server. (Yes, I agree, stupid.) If you haven't yet done so, you'll want to set up and configure SNMP on the Cacti Server itself, including SNMPv3, as you will be spending a lot of time getting used to configuring Cacti, and making mistakes, so doing your initial setup and testing all on the local server is much simpler. Once that's done, then set up MySQL for Cacti (Note: I am assuming you are conversant with basic MySQL setups under Mac OS X Server. If not, you'll want to spend some time on the MySQL web site, and Apple's documentation first. However, tackling that here is a bit out of scope for this article.):

1. Create the user Cacti will access the database as. If the database server is on the same server as Cacti, then this user only needs access from localhost/127.0.0.1. If not, then limit the network access as much as possible.
2. Create the Cacti database. You can name it whatever you want, but everything assumes you name it "Cacti" and if you get clever here, you'll be doing extra work forever. Clever should be saved for when you need it, and there's no reason to be clever here.
3. Import the default Cacti database via the cacti.sql script in the root of the Cacti directory
4. Give the Cacti user full rights to the Cacti database and only the Cacti database.

Next, set up the config.php file in $CACTIHOME$/include/config.php, so that Cacti knows what database on what server to use and has access to it. Cacti Spine Now, you'll want to install and set up Spine. Normally, Cacti's poller engine is a PHP process, and for light monitoring, that's fine. However, at some point, you can get to where the poller never finishes, because a scan takes longer than the polling period timeout. To help with that, you can optionally use Spine, which is a compiled poller engine written in C. It's a lot faster, but requires separate compilation and setup. The directions for its setup are solid, and it really does allow you to manage a lot more machines than the straight PHP poller. Spine & SNMP on Mac OS X 10.5.7 Warning If you read the notes on the security updates in 10.5.7, you'll notice that some SNMP libraries were changed. For the most part, this doesn't affect much of anything other than Spine. If you're trying to run Spine on 10.5.7, you will probably see, (up through version 0.8.7d, this is fixed in 0.8.7e and later) the following error: SPINE: Poller[0] ERROR: SNMP Library Version Mismatch (5.4.1 vs 5.4.2.1) (Spine parent) This is because Spine is very particular about versions and when they arent explicitly declared, things break. The workaround, until Spine changes how they do things, or whatever in netsnmplib 5.4.x isn't causing problems is to add the following line: #define PACKAGE_VERSION "5.4.2.1" to /usr/include/net-snmp/net-snmp-config.h, and then rebuild Spine. I did that, and it's been working fine ever since. Apache So we now have the Cacti side of things done, next, Apache. For Cacti to be able to work, you have to have PHP enabled and functional in Mac OS X Server. Cacti can't run without PHP. Period. For Mac OS X Server, you just create a site for Cacti, with the root of the site pointing to $CACTIHOME$. You'll want to make sure that index.php is a valid home page for the site, as that is Cacti's home page. Initial Setup So now, assuming you have everything set up correctly, load up Cacti's home page. The initial userid and password are both "admin", so you'll want to change those immediately. Cacti has a wizard of sorts, but that mostly is so you can set up the paths to things like the paths to rrdtool et al. (Shown in the screencap below.) Once that's done, you'll be at the base Cacti home page, and ready to do your initial setup. Before we move on to the initial setup, let's look at the Cacti upgrade process, since it's pretty similar to the install. Upgrade Notes Because the basic Cacti install is not much beyond moving the new version to where the old version was, (assuming you aren't using plugins. Cacti plugins will of course, complicate this right up), building and installing a new version of Spine and pointing things to the new version, the upgrades are pretty simple. My method is:

1. Download and unpack the new version of Cacti and Spine
2. Copy the new version of Cacti, (not Spine), to the directory I keep Cacti in. (In my case, /usr/local/nagios/share) Don't rename the directory, keep the original name with version numbers.
3. Make sure the permissions on the new version's directory are correct
4. In the new version, set the database info in $CACTIHOME/include/config.php for the new version to match the info in the old version
5. Copy the .rrd files from the $CACTIHOME/rra/ in the old version to the new version, watch their permissions
6. Build and install Spine in its default location
7. Copy the spine executable from the install location, /usr/local/spine/bin, to its working location, (this makes rebuilding, building new versions easier), after making a backup of the 'old' version of spine. For me, this is /usr/local/nagios/share/cacti_spine
8. To be on the safe side, you should also do a backup of your MySQL DB. Sometimes new versions of Cacti change things, and if you don't back up your DB, rolling back could be hard, if you end up needing to.
9. Point the 'cacti' symlink from the old version of Cacti to the new version of Cacti
10. Log into the Cacti homepage, and let the upgrade wizard do its thing.
11. Fire up the poller, (detailed later) and test. If something doesn't work, then you can usually roll back by pointing the symlink at the old version, and (if you have to), restoring the database from your backup.

(Note: We'll get to setting up the launchd job to run the Cacti Poller once we've gone over some of the basic setttings and setup.) Settings By default, Cacti is primarily an SNMP tool, so you'll need to have SNMP set up on the machines you want to monitor. However, instead of immediately creating devices, you'll want to spend some time in the settings. (This is assuming you made it through the first run setup script, which is pretty easy to deal with. You make sure the paths to things like snmpget, snmpbulkwalk, rrdtool, and php are set correctly, and you should be at the login page) General Settings This is where you set up things like logging, SNMP versions, RRDTool versions, and your SNMP defaults. That last bit is something you'll really want to pay attention to, as you'll save yourself a lot of really tedious work here. The SNMP Defaults section is where you set up the default SNMP v1/v2c & v3 defaults, along with the default version of SNMP to use. You can override this in the templates, and I'll show you that later on. (Templates are your life in Cacti. Time spent with them saves you GOBs of time later.) One warning is that Cacti displays the SNMP v3 Privacy Passphrase in plain text. So don't just let anyone in the settings page. Luckily, Cacti lets you create multiple levels of user. Paths Pretty obvious, this is where you set the paths to things. Normally, this is created on initial setup, so the only thing you'll normally have to add manually is the path to Spine, if you're using it. Poller This is where you'll probably spend the most time, settings-wise. If you are going to tweak the poller settings, either max number of processes, (cmd.php) or max threads/process, (spine), do so in small amounts, and monitor the results carefully. It's really easy to cause yourself a lot of pain if you get too radical with things. In general, the big thing is to watch your Poller & Cron interval. If a complete polling takes longer than the allowed period, you can run into problems. So, you'll want to keep an eye on the log files, which will tell you how long things take. You can also run the poller manually, via php $CACTIHOME$/poller.php At the end of the run, Cacti prints timing info. Pay attention to that. Authentication While Cacti supports LDAP auth, I've not implemented that, since we don't have a lot of users, (really, only two categories: View Graphs Only, God. Keeps it simple), and I haven't had a need to change it. However, be careful here, authentication issues can make it not only hard to use Cacti, but can keep you from using it at all. In other words, don't be too clever. User Management Cacti gives you the ability to create multiple levels of users with really fine-tuned permissions. However, be careful, and don't create more classes of user than you have to. For my setup, I have two users. The administrator, who's god, and a "viewgraph" user, who can only view existing graphs, nothing more. So far that's worked well for me, but if you find yourself needing more, well, here's what you can do for user settings: Realms settings Graph permissions Default graph settings System Utilities This is primarily for things like log access, cache access, etc. Cacti has a configurable logging level that can be invaluable when you're first getting used to the application, or troubleshooting errors, as you can set it to varying degrees of detail from "Yes, stuff happened", aka "Apple Release Note" to "here we see the interaction of quarks at the subatomic level". If you have a large number of users using Cacti, the User Log is handy for tracking user activity. That takes care of the initial installation, and some of the settings. Next up...creating our graph trees and first devices!