Skip to content

Home

Jump to bottom
Serge edited this page May 13, 2017 · 34 revisions

Overview

Subagent Shell is the complete implementation of agent written in perl. It's provides a simple interface to extend functionality and allow to define a function or execute arbitrary command and provide it's results via SNMP

The main goal of the project is to provide any data required for a monitoring system using net-snmp snmpd service. As an instance integration with Zenoss is available at ZenPacks.ssv.SubagentShell

Install

The easiest way is to install from a package: Latest release packages

see INSTALL if you want to install it manually.

Ensure that snmpd configured to allow all MIBs. A minimal configuration of snmpd.conf looks like:

com2sec         notConfigUser  default       public
group           notConfigGroup v1            notConfigUser
group           notConfigGroup v2c           notConfigUser
access          notConfigGroup ""            any  noauth exact systemview none none

view            systemview     included      .1
master  agentx
agentxperms 770 770 daemon users

Than start subagent:

service subagent-shell start

Docker demo image

if you have docker, you can run demo image and overview the features:

docker run -it --rm sergevs42/net-snmp-subagent-shell

A Sample

Here is a sample output of snmpwalk:

snmpwalk  -v2c  -M+/etc/snmp/subagent-shell/mibs -mALL -c public localhost SUBAGENT-SHELL
SUBAGENT-SHELL-MIB::ssFunctionsCount = INTEGER: 6
SUBAGENT-SHELL-MIB::ssFunctionsSuccessCount = INTEGER: 6
SUBAGENT-SHELL-MIB::ssFunctionsFailedCount = INTEGER: 0
SUBAGENT-SHELL-MIB::ssTimeStamp = STRING: "29-Aug-2013 17:17:50 (1377782270)"
SUBAGENT-SHELL-MIB::ssTotalExecTime = STRING: "0.364"
SUBAGENT-SHELL-NTP-SYNCSTATUS-MIB::ntpSyncStatus = STRING: "-0.002"
SUBAGENT-SHELL-NTP-SYNCSTATUS-MIB::ntpSyncServer = STRING: "ntp"
SUBAGENT-SHELL-NTP-SYNCSTATUS-MIB::ntpSyncFuncExecTime = STRING: "0.321"
SUBAGENT-SHELL-NTP-SYNCSTATUS-MIB::ntpSyncExecStatus = INTEGER: 0
SUBAGENT-SHELL-PROC-STAT-MIB::procTotal = Gauge32: 346
SUBAGENT-SHELL-PROC-STAT-MIB::procRunning = Gauge32: 1
SUBAGENT-SHELL-PROC-STAT-MIB::procSleeping = Gauge32: 345
SUBAGENT-SHELL-PROC-STAT-MIB::procStopped = Gauge32: 0
SUBAGENT-SHELL-PROC-STAT-MIB::procZombie = Gauge32: 0
SUBAGENT-SHELL-PROC-STAT-MIB::procUninterruptible = Gauge32: 0
SUBAGENT-SHELL-PROC-STAT-MIB::procVirtualMemory.1 = INTEGER: 10372
SUBAGENT-SHELL-PROC-STAT-MIB::procVirtualMemory.2 = INTEGER: 0
...
SUBAGENT-SHELL-PROC-STAT-MIB::procOpenFdCount.1 = Gauge32: 1
SUBAGENT-SHELL-PROC-STAT-MIB::procOpenFdCount.2 = Gauge32: 0
SUBAGENT-SHELL-PROC-STAT-MIB::procOpenFdCount.3 = Gauge32: 0
...
SUBAGENT-SHELL-IP-CONNTRACK-MIB::ip-conntrackLoaded = INTEGER: true(1)
SUBAGENT-SHELL-IP-CONNTRACK-MIB::ip-conntrackCount = Gauge32: 600
SUBAGENT-SHELL-IP-CONNTRACK-MIB::ip-conntrackMax = Gauge32: 65536
SUBAGENT-SHELL-IP-CONNTRACK-MIB::ip-conntrackUsage = Gauge32: 1
SUBAGENT-SHELL-IP-CONNTRACK-MIB::ip-conntrackFuncExecTime = STRING: "0.004"
SUBAGENT-SHELL-IP-CONNTRACK-MIB::ip-conntrackExecStatus = INTEGER: 0
SUBAGENT-SHELL-OSINFO-MIB::osinfoRelease = STRING: "CentOS release 5.9 (Final) 2.6.18-348.3.1.el5 x86_64"
SUBAGENT-SHELL-OSINFO-MIB::osinfoSoftwareLastChange = STRING: "1377781734"
SUBAGENT-SHELL-LAST-LOGINS-MIB::loggedInUsersCount = Gauge32: 7
...
SUBAGENT-SHELL-VMSTAT-MIB::vmstatPswpin = Counter64: 53
SUBAGENT-SHELL-VMSTAT-MIB::vmstatPswpout = Counter64: 1586692
SUBAGENT-SHELL-VMSTAT-MIB::vmstatInterrupts = Counter64: 1101433585
SUBAGENT-SHELL-VMSTAT-MIB::vmstatCntxSwitches = Counter64: 1435055903
SUBAGENT-SHELL-VMSTAT-MIB::vmstatFuncExecTime = STRING: "0.003"
SUBAGENT-SHELL-VMSTAT-MIB::vmstatExecStatus = INTEGER: 0

List of functions in the current stable release

Function name Description Parameters
apacheStatusMIB Parses apache server status status_url - url of apache status, description - optional description
nginxStatusMIB Parses nginx server status status_url - url of nginx status, description - optional description
httpResponseMIB Request an url using curl and provides statistic curl -url with optional args, match - a regexp to match content of url, description - optional description, monitoringTemplate - optional string which can be used for a monitoring system
ntpSyncMIB Status of time syncronization with a ntp server server - the server to check the time
procCountMIB Summary of processes by status extendedInfo [on |off] additional processes info: virtual memory size and open file descriptors. On by default
ip_conntrackMIB Information about conntrack state from /proc
dnsLookUpMIB Lookup DNS names fqdn - fully qualified domain name to resolve
osInfoMIB OS information from a release file
lastLoginsMIB Users activity statistics from w and last commands
execCommandMIB Execute a command cmd - command to execute, match - a regex to match output, description -optional description, monitoringTemplate - optional string which can be used for a monitoring system
rndcStatMIB Parses bind rndc stat stat_file - bind stats file
mailqMIB Parses output of mailq command
vmstatMIB vmstat -s summary
pingStatMIB ICMP host reachability using ping host - the host to ping, count - number of echo requests (default 10 ), options - other ping options
diskStatsMIB iostat statistic from /proc/diskstats command - optional command for /proc/diskstats file

Extending functionality

required components: a function a MIB file a function configuration

Function

a template of a function with comments:

sub someFunctionMIB {
  my $o=shift;             # 1nd argument: reference to hash MIB
  my $cfg=shift;           # 2rd argument: reference to function configuration,  optional data structure returned by perl-XML-Simple module, 
                           # as an instance see http://www.ibm.com/developerworks/ru/library/x-xmlperl1/
 
  my $a_param = $cfg->{'args'}[0]->{'server'}; # get a parameter - see function configuration below
   
  my $t=gettimeofday();    # timestamp of function start
  my $cmd="do_some_command $arg"; # command to execute
  logMessage(LOG_DEBUG, "executing $cmd"); # optional debug output
  foreach (`$cmd`) {       #run command and process lines
    chomp;
    if (/the required line/) {
       my $val = 'sample';
       $$o{"aMibVariable.$i"} = $val; #set value for a MIB variable with optional index  
    }
    # ....
    # more logic to fill MIB variables
    # ....
  }
 
  my $r = $? >> 8;                          # result code of the command
  $$o{"aMibVarExecTime.$i"} = sprintf('%.3f',scalar gettimeofday() - $t);
  $$o{"aMibVarExecStatus.$i"} = $r;
  return $r;                                # return command or function execution code, 0 success
}

IMPORTANT

when use_fork is not configured or not set to yes, all commands have to be reliable and executes in definitive period of time say less than 10 sec and have time out. you can use system $config->{'cmd_timeout'} variable ( default 10 sec ) or define your own timeout. There is no internal error handling for executed commands so please code a function carefully

when use_fork is set to yes each function executes in separate process and killed in the case cmd_timeout exceeds. For complete examples see /etc/snmp/subagent/subagent-shell-base.functions

MIB

a sample MIB:

SUBAGENT-SHELL-OSINFO-MIB DEFINITIONS ::= BEGIN

IMPORTS
  MODULE-IDENTITY, enterprises, Gauge32 FROM SNMPv2-SMI
  TimeStamp FROM SNMPv2-TC
  functionsEntry FROM SUBAGENT-SHELL-MIB;

SUBAGENT-SHELL-OSINFO MODULE-IDENTITY
  LAST-UPDATED "200906251500Z"
  ORGANIZATION "Noname, Inc."
  CONTACT-INFO "abrikus@gmail.com"
  DESCRIPTION "SNMP SUBAGENT SHELL various information about OS"
  ::= { functionsEntry 6 }

  osinfoRelease OBJECT-TYPE
    SYNTAX      OCTET STRING 
    MAX-ACCESS  read-only
    STATUS      current
    DESCRIPTION "OS Release information."
    ::= { SUBAGENT-SHELL-OSINFO 1 }

  osinfoSoftwareLastChange OBJECT-TYPE
    SYNTAX      OCTET STRING
    MAX-ACCESS  read-only
    STATUS      current
    DESCRIPTION "Last change of software."
    ::= { SUBAGENT-SHELL-OSINFO 2 }

END

For complete examples see MIB files in /etc/snmp/subagent-shell/mibs

Function configuration

there are several patterns where subagent loading functions configuration. these configuration files will be loaded on all hosts

/etc/snmp/subagent-shell/subagent-shell*-conf.xml

these configuration files will be only loaded on matched hostnames:

/etc/snmp/subagent-shell/conf.d/<hostname>*-conf.xml

a sample of function configuration file:

<config>
<function id="someFunctionMIB">
  <args server="my_server"/>
</function>
</config>

debug to debug a function you can use command:

subagent-shell -v[v] -b /your/functions/config/dir

the command run all configured functions and prints complete MIB tree in the output

see also:

/usr/bin/subagent-shell -h
cat /etc/snmp/subagent-shell/subagent-shell-conf.xml
cat /etc/snmp/subagent-shell/subagent-shell-functions-conf.xml
Clone this wiki locally