SnmpCommandPlugin

The SnmpCommandPlugin handles the tag %SNMPCOMMAND% that queries a network device for information.

The plugin uses the SNMP commands snmpwalk, snmpget or snmptable to collect and then display a network device's information. A quick and easy method to get device system status from your browser.

Syntax Rules

Simple Network Management Protocol (SNMP) is a widely used protocol for monitoring network equipment (eg. routers), computer equipment and even devices like UPSs. The plugin uses commands from the NET-SNMP distribution, which is often shipped with Linux and the plugin retains the defaults from these commands.

If no attributes are given then the plugin will use snmpwalk to return information about the system tree on the localhost using snmp v1 on port 161 and with the community string public. Note that a device's snmp often has to be configured before allowing access to much of the information and that it should be configured keeping security issues in mind. For more information refer to the NET-SNMP documenatation. The snmp daemon can return a huge amount of information about the current status of a device: network speeds, disk space, numbers of users, memory usage... The information that a device can return depends on how it has been configured and this is way beyong the scope of this small plugin.

Users of this plugin should first understand what information a device can return before using this plugin.

The objects (OIDs) can be expressed as strings or as numbers.

Examples

Example1: To walk thorugh the information from the system tree on the localhost

   * %SNMPCOMMAND%

Example2: To get the sysUpTime of the machine called myPC1

   * %SNMPCOMMAND{host="myPC1" method ="get" oid="sysUpTime.0"}% 

Example3: To get the sysUpTime and sysContact of the machine called myPC1 using the OID number.

   * %SNMPCOMMAND{host="myPC1" method = "get" oid=".1.3.6.1.2.1.1.3.0 .1.3.6.1.2.1.1.4.0"}%

Example4: To display the network interface table for the machine called myPC2 using community string bob

   * %SNMPCOMMAND{host="myPC2" method = "table" oid="ifTable" comm="bob"}%

Example5: To display the storage information table for the machine called myPC2 using community string bob

   * %SNMPCOMMAND{host="myPC2" method = "table" oid="ifTable" comm="bob"}%

Example6: To display the UCD MIB tree information on the machine called myPC2.

   * %SNMPCOMMAND{host="myPC2" method = "walk" oid="1.3.6.1.4.1.2021" }%

Attributes

Attribute	Comment	Default / Example
cmdpath	The location of the snmp commands.	'/usr/local/bin'
method	get, walk or table.	'walk'
host	The name of the machine to poll.	'localhost'
oid	The object name or number.	'.1.3.6.1.2.1.1'
version	The SNMP version to use 1, 2c or 3.	1
port	The prot number of the remote snmp daemon.	161
comm	The community string (passowrd).	'public'
outopts	SNMP output options.	's'
tablecaption	A table is displayed with this caption.	undef
cellpadding	Table cellpadding.	1
cellspacing	Table cellspacing.	0
border	Does the tabel have a border?	1
topic	The name of the current topic.	"$web.$topic"
tableheadercolor	The colour of the table header.	The current web colour
tablebgcolor	The background colour of the table.	'white'
tablecaptionalign	The alignement of the table caption.	'top'

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %INTERWIKIPLUGIN_SHORTDESCRIPTION%

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Query network devices via the snmp protocol

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.

• Download the ZIP file from the Plugin web (see below)
• Unzip SnmpCommandPlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/SnmpCommandPlugin.txt	Plugin topic
  lib/TWiki/Plugins/SnmpCommandPlugin.pm	Plugin Perl module

• Test if the installation was successful:

If you are the administrator of the machine serving TWiki, type in the following on the command line to test if snmp is available and has been configured.

snmpwalk -v 1 -c public localhost system

If this works then test the installation by adding the following line in a new topic.

%SNMPCOMMAND%

Otherwise you will have to test the snmpwalk command on other devices on your network. For example:

snmpwalk -v 1 -c public myPC1 system

If this works then test the installation by adding the following line in a new topic.

%SNMPCOMMAND{host="myPC1"}%

If you are an administrator of a network device remember to configure the snmp daemon correctly. Read the NET-SNMP documentation for this.

Plugin Info

Plugin Author:	TWiki:Main.PeterJones
Plugin Version:	29 Jun 2005 (V1.000)
Change History:
29 Jun 2005:	Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.024
CPAN Dependencies:	none
Other Dependencies:	http://net-snmp.sourceforge.net/
Perl Version:	5.005
License:	GPL (GNU General Public License)
TWiki:Plugins/Benchmark:	GoodStyle nn%, FormattedSearch nn%, SnmpCommandPlugin nn%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/SnmpCommandPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/SnmpCommandPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/SnmpCommandPluginAppraisal

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main.PeterJones - 29 Jun 2005