manpage

Copy of the man page rendered on 2016-11-06.

NAME
       nad - node-agent daemon

SYNOPSIS
       nad  [-h] [-i] [-u uid] [-c configdir] [-p [ip:]port] [-s [ip:]sslport]
       [-v] [--debugdir debugdir] [--wipedebugdir]

DESCRIPTION
       The node-agent daemon provides a simple mechanism to expose systems and
       application  metrics  to  external  onlookers.  It inventories all exe-
       cutable programs in configdir and executes them upon  external  request
       (via http or https) and returns the results in JSON format.

       It is recommended that executable checks be stored in subdirectories of
       the configdir.  Because those subdirectories  are  not  scanned,  those
       scripts  will  not  be executed with an additional step.  Those scripts
       that the administrator wishes activated can  be  soft  linked  directly
       within configdir.

       No arguments are accepted from the onlooker and thus no special precau-
       tions must be taken handling/validating/sanitizing arguments.

       The daemon provides several locations for information:

       / and /run
              cause execution and consolidation of all scripts and their  out-
              put.

       /run/scriptname
              causes  the  executation of a single script (minus the extension
              on script if it exists)

       /inventory
              returns the current active inventory of scripts.

OPTIONS
       -h     Display the help text.

       -i     Display an inventory of plugins.

       -u <uid>
              Will setuid to this specified uid after starting.

       -c <configdir>
              Sets the configuration directory (home of scripts and  SSL  cre-
              dentials).

       -p <port>
              Sets  the  port  (and IP) on which the HTTP server shall listen.
              (default 2609).

       -s <sslport>
              Sets the port (and IP) on which the HTTPS server  shall  listen.
              If  this  option is specified, na.key and na.crt must be present
              in the configdir.

       -v     Causes the daemon to validate the connecting  client's  certifi-
              cate  against the provided certificate authorities. A list of CA
              certificates must exist in the na.ca file in the configdir.

       --debugdir
              Writes debug files for each script in the  directory  specified.
              Existing  files will be removed when nad starts up and new files
              will be created. Files  will  be  in  the  format  of  <name  of
              script>.nad_debug.

       --wipedebugdir
              Existing  debug files for each script in the configdir directory
              will be removed before each write. This  allows  only  the  most
              recent debug output to persist on disk.

SCRIPT OUTPUT
       The  executable  programs  that you place in the configdir must produce
       metrics to standard output. They may  produce  JSON  output.   Alterna-
       tively, the may produce simple tab-separated metric output that adheres
       to the folling format.

       metric_name metric_type
              Indicating the the metric specified has a null value.

       metric_name metric_type value
              Indicating the the metric specified has value

   The metric_type
       i - indicating a signed 32bit integer value,

       I - indicating an unsigned 32bit integer value,

       l - indicating a signed 64bit integer value,

       L - indicating an unsigned 64bit integer value,

       n - indicating a value to be represented as a double, or

       s - indicating the the value is a string.

   Control Information
       You may provide control information in a line starting with a # charac-
       ter  and  followed  by  a  JSON  block.  Currently, timeout is the only
       parameter accepted and the argument is interpretted  as  seconds.   For
       example, to indicate that the script should be aborted if a set of out-
       put metrics cannot be completed in 1.12 seconds:

          # { "timeout": 1.12 }

   Continuous Output
       Continuous output is supported by long-running scripts.  After a set of
       metrics  is  emitted to standard output, emit a single empty line.  nad
       will accept the previous metrics into a result set and return  them  on
       the  next request for data.  The program can then pause for some ad-hoc
       amount of time and produce another set of metrics followed by  a  blank
       line.  This mode can be useful for collectin information such as mpstat
       or vmstat information.

       Note, that in most cases  if  you  can  get  raw  accumulated  counters
       (instead  of averages over some amount of time), that the output can be
       more useful to monitoring applications as a derivative can  be  applied
       after the fact without the risk of data loss.

   JSON format
       If  you  elect  to  product JSON formatted output in your programs, you
       must provide a JSON object whose keys have values that look so:

          { "_type": <metric_type>, "_value": "yourvalue" }

BUGS
       No known bugs, report bugs to Theo Schlossnagle <jesus@omniti.com>

AUTHOR
       Theo Schlossnagle (jesus@omniti.com).

       Copyright (c) 2011, OmniTI Computer Consulting, Inc.



version 1.0                     March 20, 2011                          nad(8)