For running nad, man nad.
These are the poor man's docs.
nad will run scripts from the config directory; only from that and not subdirectories. The best practice is to write your scripts in subdirectories of the config dir and soft link to them to enable their execution.
Some scripts distributed with nad need to be compiled (yes, they aren't actually scripts, they are ELF executables). Since not all programs can be compiled on all platforms, you need to go build them as needed. There are makefiles, pick and choose.
If you write a set of scripts/programs, you can describe them in a .index.json file and they will be reported on when you run nad -i.
If your operating system vendor doesn't package it for you, just check it out and run make install.
There are install targets for some operating systems, which enable all the default checks and install init scripts and default configuration helper files.
# make install-rhel
# make install-ubuntu
# make install-illumos
First, there are no config files for nad. You just run it and it works. It has a default directory out of which it executes scripts/executables. When you install it, all available plugins will be installed in subdirectories under the "config dir". To enable a script, simply link it from the "config dir".
By default, the config dir is /opt/circonus/etc/node-agent.d/, you can change this using -c on the command line. The default port is 2609, this can be changed using -p.
On Solaris or illumos you can use smf. First, node needs to be in your path, so you might need to edit the SMF manifest to alter the PATH. After install:
# svccfg import smf/nad.xml
If you used the install-illumos target above, this step is not necessary.
On RHEL/CentOS, assuming you did make install-rhel:
# /sbin/chkconfig nad on && /etc/init.d/nad start
On Ubuntu, assuming you did make install-ubuntu:
# /usr/sbin/update-rc.d nad defaults 98 02 && /etc/init.d/nad start
On other platforms, just run nad in the background. There is one required environment variable:
# export NODE_PATH="/opt/circonus/etc/node-agent.d/"
So, if you are on a Joyent SmartOS box and you want to monitor vm, cpu, and zfs stuff, you would do the following as root:
# cd /opt/circonus/etc/node-agent.d
# (cd illumos && test -f Makefile && make)
# ln -s illumos/aggcpu.elf
# ln -s illumos/zfsinfo.sh
# ln -s illumos/vminfo.sh
After which, you should be able to:
# curl http://localhost:2609/
and see all the beautiful metrics.
You'll notice above we actually did a "make" before we linked thing up. Why? For illumos, aggcpu.elf is a compiled binary (as calculating aggregate CPU info is expensive using "the UNIX way"). The make will compile and link any plugins that need compiling and linking. We don't build this on install because we're lazy and think it is a tad easier to only build what you need as you need it; it is very rare that you can't write your metrics check in shell or some other scripting language.
nad supports SSL, look at the man page.
nad can automatically configure itself with Circonus via a few command line options. When running in configuration mode, nad will create a check and graphs with Circonus and then exit, it will not attempt to bind to any port so is safe to use while running normally.
-
--authtoken The Circonus API auth token to use when talking with the API. This "activates" the configuration mode
-
--target This should be either the IP or hostname that the Circonus broker can talk to this host at. Required
-
--hostname The hostname to use in the check and graph names. If not passed nad will attempt to look it up via commands like /usr/bin/zonename
-
--brokerid The ID from Circonus for the broker you wish to configure the check on. Required
-
--configfile The path to the config file to use that defines the metrics and graphs to create in Circonus. Look at config/illumos.json for an example. Required
The --configfile parameter defines which config file to use when setting up checks and graphs in Circonus. There are two keys the nad looks for.
The check key contains the definition that will be passed to the check bundle endpoint in the Cirocnus API. You can set values like the period and timeout here, as well as config options (in the config key). The metrics key defines which metrics we will collect and has 2 subkeys, numeric and text which are simply lists of metric names. When nad attempts to create the check, if it gets back a pre-existing check, nad will update the check, adding the new metric names.
The graphs key defines a collection of graphs to create. Each subkey is the name of the graph that will be created in Circonus, with the hostname prepended to it. Under the names, the structure is identical to the documentation for the Circonus graph API, any values added will be passed to the API as is.