snmp man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



snmp(n)			Tnm Tcl Extension		  snmp(n)

_________________________________________________________________

NAME
       snmp - Send SNMP messages to devices on the Internet.
_________________________________________________________________

DESCRIPTION
       The  Tnm	 Tcl  extension includes an implementation of the
       Simple Network Management Protocol (SNMP) which is used to
       monitor	and  control  devices  on  the	Internet. The Tnm
       extension supports SNMP version 1 (SNMPv1) as  defined  in
       RFC  1155  and  RFC  1157,  community based SNMP version 2
       (SNMPv2C) as defined in RFC 1901-1908  as  well	as  User-
       based SNMP version 2 (SNMPv2U) as defined in RFC1909-1910.
       The Tcl commands described in this  man	page  follow  the
       conventions defined in the SNMPv2 standard (RFC1902-1908).
       The differences between SNMPv1 and SNMPv2  are  hidden  as
       far  as possible from the user of this extension by apply-
       ing automatic conversions where possible.

       All SNMP messages are send or received by using so  called
       SNMP  sessions. SNMP sessions are lightweight objects that
       keep control about the transport address of the SNMP  peer
       entity,	the  authentication  mechanism	in use as well as
       some parameters that control the	 behaviour  of	the  SNMP
       protocol engine itself.

       The  programming	 interface described in this man page can
       be split in four groups:

       [1]    Commands to create and control SNMP sessions.

       [2]    Commands to invoke simple SNMP operations	 on  SNMP
	      sessions.

       [3]    Commands	to invoke complex SNMP operations on SNMP
	      sessions.

       [4]    Commands to implement SNMP agents.

       The SNMP commands described in this man page  are  usually
       used  together  with  the  mib(n)  command which allows to
       retrieve	 information  from  Management	Information  Base
       (MIB) definitions.

SNMP DATA TYPES
       The  SNMP  protocol  uses  a  fixed  set of primitive data
       types. These data types are mapped to a	primitive  string
       representation  in  Tcl.	 Below	is  the list of SNMP data
       types with a short description of the corresponding primi-
       tive representation in Tcl:

Tnm								1

snmp(n)			Tnm Tcl Extension		  snmp(n)

       OCTET STRING	   An  OCTET  STRING  is  a  sequence  of
			   octect (= bytes).  The  primitive  Tcl
			   string  representation  for	an  OCTET
			   STRING value is  a  string  containing
			   hexadecimal	numbers	 (from	00 to ff)
			   separated by colons. For example,  the
			   ASCII  string "rose" is represented as
			   "72:6f:73:65".

       OBJECT IDENTIFIER   OBJECT IDENTIFIER are used to  address
			   information	in a MIB. An OBJECT IDEN-
			   TIFIER is a sequence of positive  num-
			   bers which defines a path through from
			   the root of	the  global  registration
			   tree	 to a MIB object or MIB instance.
			   The primitive Tcl  string  representa-
			   tion	 is  the  dotted  notation, where
			   sub-identifier are separated by  dots.
			   For example, the OBJECT IDENTIFIER for
			   the MIB node labelled  mib-2	 has  the
			   Tcl	      string	   representation
			   "1.3.6.1.2.1".   The	  Tnm	extension
			   always returns sub-identifier as deci-
			   mal numbers. However, the  Tnm  exten-
			   sion accepts sub-identifier which con-
			   tain hexadecimal values. A hexadecimal
			   sub-identifier  is either preceeded by
			   a colon instead of a	 dot  or  by  the
			   sequence "0x". For example, the OBJECT
			   IDENTIFIER  value  "1.3.6.1:4:1.0x627"
			   is accepted and converted to the value
			   "1.3.6.1.4.1.1575".

       IpAddress	   Values of type IpAddress are converted
			   into	 the  usual dotted notation where
			   each byte is converted into a  decimal
			   value,  which  is  separated	 from its
			   predecessor by a dot. A typical  exam-
			   ple is "134.169.34.15".

       TimeTicks	   TimeTicks values are used to represent
			   time intervals. The	resolution  of	a
			   TimeTicks  values  is  a  deci-second.
			   TimeTicks values are	 converted  to	a
			   string  of  the  form "nd hh:mm:ss.cc"
			   where n is the number of days,  hh  is
			   the	number hours, mm is the number of
			   minutes, ss is the number  of  seconds
			   and	cc is the number of hundreds of a
			   seconds.  A	typical	  primitive   Tcl
			   string  representation  of a TimeTicks
			   value looks	like  "48d  12:36:43.22".
			   The	Tnm  extension	accepts TimeTicks
			   values where the number of days and/or

Tnm								2

snmp(n)			Tnm Tcl Extension		  snmp(n)

			   the number of deci-seconds is missing,
			   e.g.	 "1164:36:43".	The  deci-seconds
			   are set to 0 if they are missing.

       INTEGER,	  Integer32,   Counter,	  Counter32,   Gauge,
       Gauge32, Unsigned32
			   Values  of all these numeric types are
			   converted  into  an	integer	  number.
			   Counter, Counter32, Gauge, Gauge32 and
			   Unsigned32 values are always positive.
			   INTEGER  or	Integer32  values  can be
			   negative. The Counter32,  Gauge32  and
			   Integer32  types  are  limited  to  32
			   bits.

       Counter64	   The Counter64 type allows  to  use  64
			   bit	unsigned counters. A value of the
			   Counter64 type is mapped to an integer
			   number  on  64  bit	machines and to a
			   floating  point  number  on	 32   bit
			   machines.

       The  Tnm	 extension returns values in the primitive string
       representation if no other formatting rules  apply.  Other
       formatting  rules  are  extracted  from MIB specifications
       (see the mib(n) command on how to load MIB specifications)
       and  applied  automatically. This includes the interpreta-
       tion if DISPLAY-HINTs as well as the conversion of integer
       values to the corresponding enumeration. For example, Dis-
       playString values are  automatically  converted	from  the
       primitive OCTET STRING representation into an ASCII string
       by applying the "225a" DISPLAY-HINT  and	 values	 of  type
       TruthValue are represented as "true" or "false" instead of
       1 and 2 (RFC  1903).  Explicit  conversions  are	 possible
       using  the  mib	format and mib scan commands described in
       the mib(n) man page.

SNMP VARBIND LISTS
       The SNMP	 protocol  always  operates  of	 a  list  of  MIB
       instances.  This	 list is called a varbind list. A varbind
       list is represented as a Tcl list.  Each	 element  of  the
       varbind	list  is itself a Tcl list describing one varbind
       element. A fully specified varbind list element has  three
       elements:  an  object  identifier which identifies the MIB
       instance, the base type of the MIB instance and the  value
       of the MIB instance.  A fully specified varbind list might
       look like:

	      {
		{1.3.6.1.2.1.1.3.0 TimeTicks {0d  0:03:23.08}}
		{1.3.6.1.2.1.2.2.1.3.1 INTEGER softwareLoopback}

Tnm								3

snmp(n)			Tnm Tcl Extension		  snmp(n)

		{1.3.6.1.2.1.2.2.1.2.1 {OCTET STRING} lo0}
		{1.3.6.1.2.1.2.2.1.8.1 INTEGER up}
	      }

       It is often not necessary to use fully  specified  varbind
       lists. It is possible to omit the type and value fields if
       you are retrieving values of MIB instances.  For	 example,
       to  retrieve  the  fully	 specified  varbing  list example
       above, the following much shorter varbind  list	has  been
       used:

	      {
		1.3.6.1.2.1.1.3.0
		1.3.6.1.2.1.2.2.1.3.1
		1.3.6.1.2.1.2.2.1.2.1
		1.3.6.1.2.1.2.2.1.8.1
	      }

       It  is also allowed to use object type descriptors instead
       of object identifier in dotted notation. (See  the  mib(n)
       man  page for details about object identifier names.) This
       further simplifies the varbind list above to:

	      { sysUpTime.0 ifType.1 ifDescr.1 ifOperStatus.1 }

       In order to change a MIB instance, you have to include the
       new  value  in the varbind list. It is however possible to
       omit the type element if the type can be found  in  a  MIB
       module. This allows to use a list like

	      { {sysContact.0 "schoenw@cs.utwente.nl"} }

       to  change  to  value of the sysContact.0 instance. Please
       note, that the Tnm extension always returns  fully  speci-
       fied varbind list to avoid ambiguities.

       SNMPv2  varbind list may contain exceptions (noSuchObject,
       noSuchInstance, endOfMibView). These exceptions	are  sig-
       nalled  in the type element of a varbind list element. The
       value of the varbind is set to null value  which	 conforms
       to the type of the object type:

	      {
		{1.3.6.1.2.1.2.2.1.3.2 noSuchInstance 0}
		{1.3.6.1.2.1.2.2.1.2.2 noSuchInstance {}}
	      }

       It  is  the responsibility of the application to check for
       exceptions.  The application will not necessarily crash if
       such  a	check  is missing but it might get confused while
       interpreting null values.

Tnm								4

snmp(n)			Tnm Tcl Extension		  snmp(n)

SNMP SESSION OPTIONS
       SNMP  sessions  are  configured	by  manipulating  session
       options.	 Some  of these options are the same for all sup-
       ported SNMP versions while some of them are specific to	a
       particular  version.  The  options  described below can be
       used with any SNMP session unless stated otherwise.

       -address address
	      The -address option defines the network address  of
	      the  SNMP	 peer.	The value of address may be an IP
	      address in dotted notation (e.g. 134.169.34.1) or a
	      hostname that can be resolved to an IP address. The
	      default address is 127.0.0.1.

       -port port
	      The -port option defines the UDP port which is used
	      by  the  SNMP  peer  to  receive SNMP messages. The
	      value of port may be a port  number  or  a  service
	      name  which  can	be resolved to a port number. The
	      default port number is 161.

       -version number
	      The -version option selects the SNMP  version  used
	      by  a SNMP session. The currently supported version
	      numbers are SNMPv1 (RFC 1157 style  SNMP),  SNMPv2C
	      (RFC  1901  style SNMP) and SNMPv2U (RFC 1910 style
	      SNMP). The default SNMP version is SNMPv1.

       -community string
	      The -community option is specific	 for  SNMPv1  and
	      SNMPv2C  sessions.  It defines the community string
	      which is used to identify the sender of  SNMP  mes-
	      sages. The default community string is "public".

       -writecommunity string
	      The  -writecommunity  option is specific for SNMPv1
	      and SNMPv2C  sessions.  It  defines  the	community
	      string which is used to identify the sender of SNMP
	      messages when invoking SNMP  set	operations.   The
	      default write community string is empty which means
	      that the community string defined by the -community
	      option is used.

       -user name
	      The  -user  option is specific to SNMPv2U sessions.
	      It is used  to  define  the  SNMP	 user  name.  The
	      default user name is "public".

Tnm								5

snmp(n)			Tnm Tcl Extension		  snmp(n)

       -password password
	      The  -password  option  is specific to SNMPv2U ses-
	      sions. It is used to specify the	password  of  the
	      user.  The password is automatically converted into
	      a key by applying the password2key algorithm of RFC
	      1910.  The key is also automatically localized once
	      the agentID of the SNMP agent is known.  Note  that
	      the  application should take care to keep the pass-
	      words safe from unauthorized access. An empty pass-
	      word  turns SNMPv2U authentication off. The default
	      password is "".

       -context context
	      The -context option is  specific	to  SNMPv2U  ses-
	      sions.  It  allows  to select between multiple con-
	      texts. The default context is "".

       -timeout time
	      The -timeout option defines the  time  the  session
	      will  wait  for  a response. The time is defined in
	      seconds with a default of 5 seconds.

       -retries number
	      The  -retries  option  defines  how  many	 times	a
	      request  is retransmitted during the timeout inter-
	      val. The default number of retries is 3.

       -delay delay
	      The -delay option can be used to define a delay  in
	      milliseconds  between two messages send by the SNMP
	      protocol engine. This can be used to avoid  network
	      congestion  problems.  The  default delay is 0 mil-
	      liseconds.

       -window size
	      The -window option allows to define a window  which
	      limits  the number of active asynchronous requests.
	      This can be used to prevent fast scripts	to  flood
	      an  agent	 with  asynchronous  messages.	 The  Tnm
	      extension queues requests	 internally  so	 that  no
	      more  than  size	asynchronous  requests are on the
	      wire. Setting the size to	 0  turns  the	windowing
	      mechanism	 off.  The default window size is 10 mes-
	      sages.

       -agent interp
	      The -agent option turns the SNMP	session	 into  an
	      SNMP  agent.   The  interp argument defines the Tcl

Tnm								6

snmp(n)			Tnm Tcl Extension		  snmp(n)

	      interpreter which will be used to evaluate bindings
	      associated with MIB instances. It is recommended to
	      use a safe Tcl interpreter if  you  are  evaluating
	      scripts  or arguments received over the network. It
	      is also possible to use the current Tcl interpreter
	      by using an empty interpreter name.

       -alias name
	      The  -alias option substitutes this option with the
	      configuration options contained in the alias  iden-
	      tified by name. You can define configuration option
	      aliases with the snmp alias command. It is possible
	      to  refer	 to other -alias options within an -alias
	      option. See the description of the snmp alias  com-
	      mand below for an example.

SNMP CALLBACK SCRIPTS
       Many  SNMP commands described below allow to program asyn-
       chronous SNMP  operations.  Asynchronous	 SNMP  operations
       work  by	 sending  out  a  request  without  waiting for a
       response. The SNMP protocol engine keeps	 track	of  asyn-
       chronous	 requests  and processes callback scripts once an
       answer for an asynchronous  request  is	received  or  the
       request times out. The callback script is always evaluated
       at global level. Special % escape sequences can be used in
       the  callback  script  to  access details contained in the
       SNMP response. These %  escape  sequences  are  substitued
       before  the callback script is evaluated. The substitution
       depends on the character following the %,  as  defined  in
       the list below.

       %%   Replaced with a single percent.

       %V   Replaced with the fully specified varbind list.

       %R   Replaced with the request id.

       %S   Replaced with the session name.

       %E   Replaced  with  the error status. Possible values for
	    the error status  are  noError,  tooBig,  noSuchName,
	    badValue,	readOnly,  genErr,  noAccess,  wrongType,
	    wrongLength, wrongEncoding,	 wrongValue,  noCreation,
	    inconsistentValue, resourceUnavailable, commitFailed,
	    undoFailed, authorizationError,  notWritable,  incon-
	    sistentName, noResponse.

       %I   Replaced  with  the error index. The first element of
	    the varbind list has the position 1.

       %A   Replaced with the IP address of the peer sending  the

Tnm								7

snmp(n)			Tnm Tcl Extension		  snmp(n)

	    packet.

       %P   Replaced with the port number of the peer sending the
	    packet.

       %T   Replaced with the SNMP PDU type. Possible values  for
	    the	  PDU  type  are  get-request,	get-next-request,
	    response, snmpV1-trap, set-request, get-bulk-request,
	    inform-request, snmpV2-trap, report.

SNMP COMMAND
       This section describes SNMP commands that are used to cre-
       ate new SNMP sessions, to define SNMP aliases  and  to  do
       some houskeeping.

       snmp session [option value ...]
	      The snmp session command creates new SNMP sessions.
	      It returns a session handle which is used to invoke
	      operations.  It  is  possible  to add configuration
	      options as described above to the snmp session com-
	      mand in order to configure the SNMP session.

       snmp alias [name [options]]

	      The snmp alias command allows to create aliases for
	      a list of configuration options. This can	 be  used
	      to  define short names for complex session configu-
	      rations and it allows to share e.g. frequently used
	      community	 strings  between a number of devices. An
	      alias defined by the snmp alias command can be sub-
	      stitued  when  configuring  a SNMP session by using
	      the -alias session option as described above.

	      The snmp alias command  invoked  without	arguments
	      returns  the  list  of  all  known  alias names. If
	      invoked with an alias name, the list of  configura-
	      tion   options   associated   with  this	alias  is
	      returned. Invoking the snmp alias command	 with  an
	      alias  name and an options list associates the list
	      of configuration options contained in options  with
	      the alias name.

	      Below  is	 an examples that creates an SNMPv1 alias
	      private which defines a  SNMPv1  community  string.
	      The  aliases  hub1  and  hub2  define configuration
	      options  used  to	 access	 two  hubs.  The  aliases
	      hub1/private   and   hub2/private	  combine   these
	      aliases. It is now possible to update  the  private
	      community string for both hubs by changing the pri-
	      vate alias.  Nesting  alias  definitions	as  shown
	      below  allows  to	 build	a  flexible configuration

Tnm								8

snmp(n)			Tnm Tcl Extension		  snmp(n)

	      scheme.

	      snmp alias private "-community ncc1701"
	      snmp alias hub1 "-address 1.2.3.4 -window 2  -delay
	      10"
	      snmp alias hub2 "-address 1.2.3.5. -timeout 10"
	      snmp  alias  hub1/private	 "-alias hub1 -alias pri-
	      vate"
	      snmp alias hub2/private "-alias  hub1  -alias  pri-
	      vate"

       snmp info
	      The  snmp	 info  command returns a list of existing
	      SNMP sessions.

       snmp watch toggle
	      The snmp watch command turns hex printing	 of  SNMP
	      packets  on  or off. This is mostly a debugging aid
	      because you can't process the  output  with  a  Tcl
	      script.

       snmp wait
	      The snmp wait command blocks until all asynchronous
	      requests for all SNMP sessions have been processed.
	      Events  are processed while waiting for outstanding
	      responses which can have arbitrary side effects.

SIMPLE SNMP SESSION COMMANDS
       This sections describes simple SNMP session commands which
       correspond  directly  to SNMP protocol operations. It also
       discusses some commands to configure and	 control  of  the
       SNMP protocol engine.

       snmp# configure [option value ...]
	      The  snmp# configure session command can be used to
	      query or change the current configuration	 options.
	      See  the	description of SNMP session options above
	      for more details. The snmp# configure session  com-
	      mand  always  returns  the  current settings of the
	      configuration options.  Note,  invoking  the  snmp#
	      configure	 session  command  on a SNMP session that
	      has asynchronous requests pending	 can  have  arbi-
	      trary  side  effects  because  it	 processes events
	      until all pending requests for  this  session  have
	      either  timed  out  or  returned	a response.  This
	      behavior makes sure that pending	request	 are  not
	      affected	by  the	 any  change  to  a configuration
	      option.

Tnm								9

snmp(n)			Tnm Tcl Extension		  snmp(n)

       snmp# cget option
	      The snmp# cget session command allows  to	 retrieve
	      the  value  of  the  SNMP	 session  option given by
	      option. See the description of SNMP session options
	      above for more details.

       snmp# wait [request]
	      The  snmp#  wait	command	 blocks	 until	all asyn-
	      chronous requests for this SNMP session  have  been
	      processed.  Events  are processed while waiting for
	      outstanding responses which can have arbitrary side
	      effects.

       snmp# destroy
	      The snmp# destroy session command destroys the ses-
	      sion. All data associated with the SNMP session  is
	      removed (outstanding asynchronous requests are can-
	      celled).

       snmp# get varbindlist [script]
	      The snmp# get session command retrieves the list of
	      instances	 as specified in the varbindlist by using
	      an SNMP get-request.  If the snmp# get session com-
	      mand  contains  a callback script, then the command
	      sends the get-request and returns immediately.  The
	      result  is  the  request	id  for	 the asynchronous
	      request.

	      The snmp# get session  command  is  processed  syn-
	      chronously  if  the  callback script is missing. In
	      this case, the received varbind list is returned or
	      the  command fails if the agent does not respond or
	      if a protocol error happens.

	      Below is an example for a synchronous and an  asyn-
	      chronous	get  request to retrieve variables of the
	      system group:

	      $s get "sysDescr.0 sysName.0 sysContact.0"

	      $s get "sysDescr.0 sysName.0 sysContact.0" {
		  if {"%E" == "noError"} { puts "%V" }
	      }

       snmp# getnext varbindlist [script]
	      The snmp# getnext	 session  command  retrieves  the
	      values  of  the  lexicographical	successors to the
	      objects named in varbindlist.  If the snmp# getnext
	      session  command	contains  a callback script, then
	      the command sends the get-next-request and  returns

Tnm							       10

snmp(n)			Tnm Tcl Extension		  snmp(n)

	      immediately.  The	 result is the request id for the
	      asynchronous request.

	      The snmp# getnext session command is processed syn-
	      chronously  if  the  callback script is missing. In
	      this case, the received varbind list is returned or
	      the  command fails if the agent does not respond or
	      if a protocol error happens.

	      To retrieve the whole MIB tree,  you  can	 use  the
	      result  of a getnext command as an argument for the
	      next getnext command. Below are two  examples  that
	      show a synchronous and an asynchronous version.

	      set vbl 1
	      while {! [catch {$s getnext $vbl} vbl]} {
		  puts $vbl
	      }

	      proc dump {s vbl err} {
		  if {$err == "noError"} {
		      puts $vbl
		      $s getnext $vbl { dump "%S" "%V" "%E" }
		  }
	      }
	      $s getnext 1 { dump "%S" "%V" "%E" }

       snmp# getbulk nr mr varbindlist [script]
	      The  snmp#  getbulk  session command can be used to
	      implement fast MIB tree walks  by	 using	get-bulk-
	      requests. The snmp# getbulk command performs a get-
	      next  on	the  first  nr	elements  given	 in   the
	      varbindlist.  For the remaining elements, the agent
	      is asked to repeat the getnext operation mostly  mr
	      times.  SNMPv1 sessions automatically map get-bulk-
	      requests to get-next-requests.  If the  snmp#  get-
	      bulk  session  command  contains a callback script,
	      then the command	sends  the  get-bulk-request  and
	      returns  immediately.  The result is the request id
	      for the asynchronous request.

	      The snmp# getbulk session command is processed syn-
	      chronously  if  the  callback script is missing. In
	      this case, the received varbind list is returned or
	      the  command fails if the agent does not respond or
	      if a protocol error happens.

	      A typical example of the snmp# getbulk session com-
	      mand is shown below. It will return sysUpTime.0 and
	      the values for ifIndex.1, ifDescr.1, ifIndex.2  and
	      ifDescr.2 assuming the device has at least 2 inter-
	      faces and implements snmp version 2.

Tnm							       11

snmp(n)			Tnm Tcl Extension		  snmp(n)

	      $s getbulk 1 2 "sysUpTime ifIndex ifDescr"

       snmp# set varbindlist [callback]
	      The snmp# set session command can be used to create
	      and  alter MIB instances. The varbind list for set-
	      requests must contain at least the  object  identi-
	      fier  and	 the new value as described above. If the
	      snmp#  set  session  command  contains  a	 callback
	      script,  then the command sends the set-request and
	      returns immediately. The result is the  request  id
	      for the asynchronous request.

	      The  snmp#  set  session	command is processed syn-
	      chronously if the callback script	 is  missing.  In
	      this case, the received varbind list is returned or
	      the command fails if the agent does not respond  or
	      if a protocol error happens.

	      Below  is an example which shows how you can change
	      the sysContact.0 and sysLocation.0 variables of the
	      system group. Note that it is always recommended to
	      use the Tcl list command to build the varbind list.
	      This makes sure that quoting is done in the correct
	      way.

	      $s set [list \
		  [list sysContact.0 "Bert Nase"] \
		  [list sysLocation.0 "Hall6, Floor 5"] \
	      ]

       snmp# trap snmpTrapOid varbindlist

	      The snmp# trap command allows to notify  a  manager
	      that a special event has happened. The trap type is
	      defined by the snmpTrapOid object	 identifier.  The
	      standard	traps  defined in RFC 1907 are coldStart,
	      warmStart	 and  authenticationFailure.   Additional
	      trap  types  are	defined in other MIB modules. The
	      varbindlist contains variables that  provide  addi-
	      tional  information  for	the remote manager. Note,
	      the  value  of  sysUpTime.0   is	 added	 to   the
	      varbindlist automatically. However, it is up to the
	      user  to	provide	 any  other  required  additional
	      varbinds	like  the ifIndex for linkUp and linkDown
	      traps.

	      SNMPv1 traps are defined by  an  enterprise  object
	      identifier  and a generic and specific trap number.
	      It is possible to convert a SNMPv1 trap  definition
	      into  a  snmpTrapOid object identifier by appending
	      the generic and specific trap number to the  enter-
	      prise  object  identifier.  This conversion is done

Tnm							       12

snmp(n)			Tnm Tcl Extension		  snmp(n)

	      automatically if the SNMPv1 trap is defined using a
	      TRAP-TYPE macro (RFC 1212) in a MIB module.

	      SNMP traps are usually received on UDP port 162. It
	      is therefore necessary to change the  default  set-
	      tings  of	 the  SNMP session handle to send a trap.
	      Below is an example that	changes	 the  destination
	      port, sends a coldStart trap, and restores the des-
	      tination port. It is also possible to keep  a  spe-
	      cial session around just for sending trap messages.

	      set port [$s cget -port]
	      $s configure -port 162
	      $s trap coldStart [list [list sysDescr.0 "Fridge"]]
	      $s configure -port $port

       snmp# inform snmpTrapOid varbindlist [script]

	      The snmp# inform session command is only	available
	      for  SNMPv2 sessions and sends an inform-request to
	      a manager. In contrast to a trap, an inform-request
	      is  confirmed  by	 the manager with a response mes-
	      sage. The information request type  is  defined  by
	      the  snmpTrapOid	in  the same way as described for
	      the  snmp#  trap	 session   command   above.   The
	      varbindlist  contains  variables that provide addi-
	      tional information for the  remote  manager.  Note,
	      the   value   of	 sysUpTime.0   is  added  to  the
	      varbindlist automatically.

	      If the snmp#  inform  session  command  contains	a
	      callback script, then the command sends the inform-
	      request and returns immediately. The result is  the
	      request id for the asynchronous request.

	      The  snmp# inform session command is processed syn-
	      chronously if the callback script	 is  missing.  In
	      this case, the received varbind list is returned or
	      the command fails if the agent does not respond  or
	      if a protocol error happens.

	      set port [$s cget -port]
	      $s configure -port 162
	      $s inform tooHot [list [list sysDescr.0 "Fridge"]]
	      $s configure -port $port

       snmp# bind {} send [script]
       snmp# bind {} recv [script]
       snmp# bind {} trap [script]
       snmp# bind {} inform [script]
       snmp# bind {} report [script]
	      The  snmp#  bind	session	 command  allows  to bind

Tnm							       13

snmp(n)			Tnm Tcl Extension		  snmp(n)

	      scripts to events processed inside of the SNMP pro-
	      tocol  engine. The first argument of the snmp# bind
	      session commands described here is always an  empty
	      string.  (See the description of the agent commands
	      below for additional bindings and the use	 of  this
	      parameter.)  The seconds argument of the snmp# bind
	      session command is the event type.  The snmp#  bind
	      session command always returns the script currently
	      bound to the given event type. A script is bound to
	      an  event	 type  by  providing  the optional script
	      argument. A script is  removed  from  an	event  by
	      binding an empty string to this event.

	      A	 send event is created whenever a SNMP message is
	      send to the network. Note, that the send event only
	      triggers	once  for every request and not for every
	      retransmission of the same message. Similarly,  the
	      recv  event  is  created whenever a SNMP message is
	      received from the network. These	commands  can  be
	      used  to	analyze the SNMP traffic from/to the SNMP
	      engine.

	      Notifications send by an agent or	 another  manager
	      can  be  received	 by  binding  scripts to trap and
	      inform events. Binding a script to one of these two
	      event  types starts the straps(8) daemon which lis-
	      tens for incoming notifications on UDP port 162 and
	      forwards	them  to  all interested processes on the
	      local machine.

	      A report event is created when the protocol  engine
	      receives	a  SNMPv2U report message. These messages
	      are used internally to implement clock synchroniza-
	      tion and agent discovery.

	      A script bound to an event is evaluated in the same
	      way as callback scripts. Substitution of	%  escape
	      sequence takes place as described above and scripts
	      are always evaluated at global level.

COMPLEX SNMP SESSION COMMANDS
       This section describes complex SNMP commands which usually
       perform	a sequence of SNMP operations. The implementation
       of these complex SNMP session comands does some	automatic
       error  handling	in  order to hide some of the differences
       between the SNMP version.

       snmp# walk varName varbindlist body
	      The snmp# walk session command walks  a  whole  MIB
	      subtree.	 The   command	repeats	 sending  getbulk
	      requests until the returned varbind list is outside
	      of the subtree given by varbindlist. For each valid

Tnm							       14

snmp(n)			Tnm Tcl Extension		  snmp(n)

	      varbind list retrieved  from  the	 agent,	 the  Tcl
	      script body is evaluated. Before evaluation of body
	      starts, the variable named varName is set	 to  con-
	      tain  the	 actual	 varbind  list. Below is a simple
	      example to walk and print the interface table:

	      $s walk x "ifIndex ifDescr" { puts $x }

       snmp# scalars scalarlist arrayName
	      The snmp# scalars session command can  be	 used  to
	      retrieve	potentially  large  lists of scalars. The
	      values  are  extracted  from  the	 varbindlist  and
	      stored  in  the  Tcl  array  named  arrayName.  The
	      scalarlist may include names of simple  scalar  MIB
	      instances	 or  names  of	SNMP  groups which can be
	      expanded to a list of MIB scalars. The array array-
	      Name  is	indexed	 by the names of scalars success-
	      fully  retrieved	from  the  agent.   The	 list  of
	      indexes  is  returned  by the snmp# scalars session
	      command. Protocol errors (e.g.  tooBig)  or  SNMPv2
	      varbind exceptions are handled internally.

	      The  example  below retrieves and prints the system
	      uptime and the all the scalars in the udp	 and  tcp
	      groups:

	      foreach name [$s scalars "sysUpTime udp tcp" s] {
		  puts "$name : $s($name)"
	      }

SNMP AGENT COMMANDS
       This  section  describes the SNMP session commands used to
       implement SNMP agents in Tcl. The SNMP agent  maintains	a
       tree  of	 MIB instances which are linked to Tcl variables.
       Whenever the value of a MIB instance is	required  by  the
       SNMP  protocol  engine,	the corresponding Tcl variable is
       read. This allows to update MIB instances easily from Tcl.
       However, some MIB instances are designed to have arbitrary
       side effects, especially if the value is changed. A  bind-
       ing  mechanism allows to bind Tcl scripts to events inside
       of the SNMP protocol engine so that a Tcl script can  con-
       trol the behavior of MIB instances.

       snmp# instance label varName [default]
	      The  snmp#  instance  session command creates a new
	      MIB instance if the session  is  configured  as  an
	      SNMP agent. The MIB instance identified by label is
	      linked to the global Tcl variable varName. The SNMP
	      protocol engine reads the value of varName and con-
	      verts it into the required  SNMP	data  type  while
	      processing  incoming requests. An agent script must

Tnm							       15

snmp(n)			Tnm Tcl Extension		  snmp(n)

	      ensure that varName contains an  acceptable  format
	      (see  above). The optional argument default defines
	      the initial value of varName.  The lifetime of  the
	      MIB  instance is bound to the Tcl variable varName.

       snmp# bind label event [script]
	      The snmp# bind session command binds a  Tcl  script
	      to  the  MIB instance tree node identified by label
	      and is only valid for sessions in agent  mode.  The
	      event  argument  defines	the  SNMP  operation that
	      triggers the evaluation of  the  script.	Supported
	      events  types  are get, set, create, check, commit,
	      rollback, begin and end.	The  snmp#  bind  session
	      command  returns	the  currently defined binding if
	      the script argument is missing.

	      The begin and end bindings are evaluated before PDU
	      processing starts and after PDU processing has fin-
	      ished. The label for begin and end bindings must be
	      empty. Get event bindings are evaluated, whenever a
	      MIB instance is read. They can be	 used  to  modify
	      the  contents of the associated Tcl variable before
	      the value is actually put into  the  response  mes-
	      sage.

	      Set,  create,  check,  commit and rollback bindings
	      are used to implement writable MIB  instances.  The
	      check,  commit  and rollback bindings are needed to
	      allow scripts to conform to the "as  if  simultane-
	      ously"   requirement  (RFC  1157,	 RFC  1905).  Set
	      requests are processed  in  three	 phases.  In  the
	      first phase, set and create events are processed to
	      modify existing or create new  MIB  instances.  The
	      seconds phase is processed only if no error occured
	      in the first  phase.  The	 second	 phase	activates
	      check  bindings  to allow scripts to check the con-
	      sistency of the new values. The final phase is  the
	      commit/rollback  phase  which  triggers  the commit
	      bindings if there has not been  any  error  in  the
	      earlier  phases.	An  error  in  one of the earlier
	      phases triggers the rollback bindings. The protocol
	      engine  will  also  restore  the Tcl variables with
	      previously saved values.

	      A Tcl script bound to an event can  signal  a  SNMP
	      specific	error  by  invoking the Tcl error command
	      and returning one of the SNMP error codes	 (tooBig,
	      noSuchName,  badValue,  readOnly, genErr, noAccess,
	      wrongType, wrongLength, wrongEncoding,  wrongValue,
	      noCreation, inconsistentValue, resourceUnavailable,
	      commitFailed,    undoFailed,    authorizationError,
	      notWritable, inconsistentName).

Tnm							       16

snmp(n)			Tnm Tcl Extension		  snmp(n)

	      All  the	% escapes sequences described in the sec-
	      tion about callback scripts will be expanded before
	      the  command  is	evaluated. In addition, there are
	      three more escapes defined for SNMP bindings:

	      %o   Replaced with the object identifier of the MIB
		   instance that triggered the event.

	      %i   Replaced  with  the instance identifier of the
		   MIB instance that triggered the event.

	      %v   Replaced with the value for the  MIB	 instance
		   that triggered the event.

	      %p   Replaced  with  the previous value for the MIB
		   instance during SNMP	 set  operations  and  an
		   empty string otherwise.

       Below  is  an example that implements a MIB instance tnmT-
       clCmdCount.0 which returns the actual number of	Tcl  com-
       mands processed by the Tcl interpreter:

	      $s instance tnmTclCmdCount.0 tnmTclCmdCount
	      $s bind tnmTclCmdCount.0 get {
		  set tnmTclCmdCount [info cmdcount]
	      }

       The  second  example  implements	 two MIB instances called
       tnmHttpSource.0 and  tnmHttpError.0.  The  tnmHttpSource.0
       instance	 shall	retrieve a Tcl file via HTTP and evaluate
       the contents. The second tnmHttpError.0 instance	 contains
       the error message of the last use of tnmHttpSource.0:

	      $s instance tnmHttpSource.0 tnmHttpSource
	      $s instance tnmHttpError.0 tnmHttpError

	      $s bind tnmHttpSource.0 set {
		  set tnmHttpSource "%v"
		  set msg [SNMP_HttpSource $tnmHttpSource]
		  if {$msg != ""} {
		      set tnmHttpError $msg
		      error inconsistentValue
		  }
	      }

	      $s bind tnmHttpSource.0 rollback {
		  set tnmHttpSource ""
	      }
	      $s bind tnmHttpSource.0 commit {
		  set tnmHttpError ""
	      }

       It  is  sometimes useful to bind scripts to non-leaf nodes

Tnm							       17

snmp(n)			Tnm Tcl Extension		  snmp(n)

       of the MIB instance tree. All bindings starting	from  the
       leaf node up to the root of the MIB instance tree are pro-
       cessed. You can use the Tcl break command to disable  fur-
       ther  binding processing. For example, the following bind-
       ing will trigger on all get events in the  enterprise  MIB
       subtree and can be used for debugging purposes:

	      $s bind 1.3.6.1.4.1 get {
		  puts "%T from %A:%P object %o (instance %i)"
	      }

BUGS
       The  Tcl	 arithmetic  is	 not  platform independent. It is
       therefore complicated to write portable scripts that  work
       correctly with large SNMP numbers.
       The  complex  SNMP  session  commands should support asyn-
       chronous operations.

SEE ALSO
       scotty(1), Tnm(8), Tcl(n)

AUTHORS
       Juergen Schoenwaelder <schoenw@cs.utwente.nl>
       Sven Schmidt <vschmidt@ibr.cs.tu-bs.de>

Tnm							       18

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net