Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       /usr/local/etc/snmp/snmpd.conf  -  configuration	 file for the Net-SNMP
       SNMP agent.

       snmpd.conf is the configuration file which  defines  how	 the  Net-SNMP
       SNMP  agent  operates.	These  files may contain any of	the directives
       found in	the DIRECTIVES section below.  This file is not	 required  for
       the agent to operate and	respond	to requests.

       First,  make sure you have read the snmp_config(5) manual page that de-
       scribes how the Net-SNMP	configuration files operate,  where  they  are
       located and how they all	work together.

       Also,  you  might  consider looking into	the snmpconf application (perl
       script) which can help you build	an snmpd.conf file  by	prompting  you
       for  information.   You	should try it.	Really.	 Go ahead.  Right now.

	      snmpconf -g basic_setup

       to get you started. See the snmpconf(1) manual page for	more  informa-

       The Net-SNMP SNMP agent reports much of its information through queries
       to the section of the MIB tree.	  Every	 MIB  in  this
       section has the following table entries in it.

       .1 -- index
	      This  is	the  table's  index numbers for	each of	the DIRECTIVES
	      listed below.

       .2 -- name
	      The name of the given table entry.  This should be  unique,  but
	      is not required to be.

       .100 -- errorFlag
	      This  is	a flag returning either	the integer value 1 or 0 if an
	      error is detected	for this table entry.

       .101 -- errorMsg
	      This is a	DISPLAY-STRING describing any error triggering the er-
	      rorFlag above.

       .102 -- errorFix
	      If this entry is set to the integer value	of 1 AND the errorFlag
	      defined above is indeed a	1, a program or	script will  get  exe-
	      cuted with the table entry name from above as the	argument.  The
	      program to be executed is	configured in  the  config.h  file  at
	      compile time.

       proc NAME

       proc NAME MAX

       proc NAME MAX MIN

	      Checks  to see if	processes called NAME are running on the agent
	      machine.	An error flag (1) and a	description message  are  then
	      passed	   to	    the	   and	MIB  columns  (respectively)  if   the
	      NAME'd  program is not found in the process table	as reported by
	      "/bin/ps acx".

	      If MAX and MIN are not specified,	MAX is assumed to be  infinity
	      and MIN is assumed to be 1.

	      If  MAX is specified but MIN is not specified, MIN is assumed to
	      be 0.

       procfix NAME PROG ARGS
	      This registers a command that knows how to fix errors  with  the
	      given  process  NAME.  When for a given
	      NAMEd program is set to the integer value	 of  1,	 this  command
	      will  be	called.	 It defaults to	a compiled value set using the
	      PROCFIXCMD definition in the config.h file.

       exec NAME PROG ARGS


	      If MIBNUM	is not specified, the agent executes  the  named  PROG
	      with arguments of	ARGS and returns the exit status and the first
	      line of the STDOUT output	of the PROG program to queries of  the	and mib col-
	      umns (respectively).  All	STDOUT output beyond the first line is
	      silently truncated.

	      If  MIBNUM  is  specified, it acts as above but returns the exit
	      status to	MIBNUM.100.0 and the entire STDOUT output to the table
	      MIBNUM.101  in  a	 MIB  table.  In this case, the	MIBNUM.101 mib
	      contains the entire STDOUT output, one MIB table entry per  line
	      of  output  (ie,	the  first line	is output as MIBNUM.101.1, the
	      second at	MIBNUM.101.2, etc...).

	      Note:  The MIBNUM	must be	specified in  dotted-integer  notation
		     and  can  not  be specified as ""
		     (should instead be	.

	      Note:  The agent caches the exit status and STDOUT of  the  exe-
		     cuted  program  for  30  seconds after the	initial	query.
		     This is to	increase speed and maintain consistency	of in-
		     formation	for  consecutive table queries.	 The cache can
		     be	 flushed  by  a	 snmp-set  request  of	integer(1)  to

       execfix NAME PROG ARGS
	      This  registers  a command that knows how	to fix errors with the
	      given exec or sh	NAME.	When	for  a
	      given NAMEd entry	is set to the integer value of 1, this command
	      will be called.  It defaults to a	compiled value set  using  the
	      EXECFIXCMD definition in the config.h file.

       disk PATH


	      Checks the named disks mounted at	PATH for available disk	space.
	      If the disk space	is less	than MINSPACE  (kB)  if	 specified  or
	      less   than  MINPERCENT  (%)  if	a  %  sign  is	specified,  or
	      DEFDISKMINIMUMSPACE (kB) if not specified, the associated	 entry
	      in the MIB table	will be	set to (1) and
	      a	descriptive error message  will	 be  returned  to  queries  of

       includeAllDisks MINPERCENT%

	      Adds  all	 the  disks  that can be found on the system using the
	      setmntent(3) and getmntent(3), or	fopen(3) and getmntent(3),  or
	      setfsent(3)  and	getfsent(3) system calls. If none of the above
	      system calls are available then it adds the root partition  "/",
	      (which  is  assumed to exist on any UNIX based system) using the
	      statfs(2)	system call.

	      There can	only be	one 'includeAllDisks' directive	in the config-
	      uration  file.  It  can  be  used	in conjunction with the	'disk'
	      directive. They may be used in any order.	The  'disk'  directive
	      overrides	 the  disk  usage  specified  by the 'includeAllDisks'
	      directive, no matter in which order they are  specified  in  the
	      configuration file.

	      The 'includeAllDisks' directive only includes the	disks that are
	      mounted when the snmpd daemon  is	 started.  It  cannot  include
	      disks  that are dynamically loadable, such as with automount. So
	      the preferred way	is to mount all	the disks that will ever  need
	      to be monitored before starting the snmpd	daemon.

       load MAX1

       load MAX1 MAX5

       load MAX1 MAX5 MAX15

	      Checks the load average of the machine and returns an error flag
	      (1),  and	 an  text-string   error   message   to	  queries   of	and (respec-
	      tively) when the 1-minute, 5-minute, or 15-minute	 averages  ex-
	      ceed  the	 associated maximum values.  If	any of the MAX1, MAX5,
	      or MAX15 values are unspecified, they default to a value of DEF-

       file FILE [MAXSIZE]
	      Monitors file sizes and makes sure they don't grow beyond	a cer-
	      tain size	(in kilobytes).	 MAXSIZE defaults to infinite  if  not
	      specified,  and  only monitors the size without reporting	errors
	      about it.	 A maximum of 20 files can be monitored.

       Any errors in obtaining the above  information  are  reported  via  the   flag  and  the
       text-string description.

       To enable AgentX	support	in the SNMP master agent,  put	the  following
       line in your snmpd.conf file:

       master agentx
	      See README.agentx	for further details.

       AgentXSocket addr
	      This  defines  the address the master agent listens at.  The de-
	      fault  is	 /var/agentx/master.  Another  possibility  is	local-

       AgentXTimeout addr
	      Defines  the timeout period for an AgentX	request.  Default is 1

       AgentXRetries addr
	      Defines the number of retries for	an AgentX request.  Default is
	      5	retries.

       You  can	also put the following in your subagent.conf file (where "sub-
       agent" is the name you used in your init_snmp("subagent") api call:

       agentPingInterval NUM
	      This makes the subagent try and reconnect	every NUM  seconds  to
	      the master if it ever becomes (or	starts)	disconnected.

       To  enable  and	SMUX  based sub-agent, such as gated, use the smuxpeer
       configuration entry

       smuxpeer	OID PASS
	      For gated	a sensible entry might be smuxpeer  .

       If  the agent is	built with support for the UCD-DLMOD-MIB it is capable
       of loading agent	MIB modules dynamically	at startup through  the	 dlmod
       directive  and  during  runtime	through	use of the UCD-DLMOD-MIB.  The
       following directive loads the shared object module file PATH which uses
       the module name prefix NAME.

       dlmod NAME PATH

       snmpd supports the View-Based Access Control Model (VACM) as defined in
       RFC 2575.  To this end, it recognizes the  following  keywords  in  the
       configuration  file:  com2sec,  group, access, and view as well as some
       easier-to-use wrapper  directives:  rocommunity,	 rwcommunity,  rouser,
       rwuser.	 If IPv6 support has been enabled, the rocommunity6 and	rwcom-
       munity6 tokens will also	be available.  This  section  defines  how  to
       configure  the  snmpd program to	accept various types and levels	of ac-

       rouser USER [noauth|auth|priv [OID]]

       rwuser USER [noauth|auth|priv [OID]]
	      Creates a	SNMPv3 USM user	in the VACM access  configuration  ta-
	      bles.   It  is more efficient (and powerful) to use the combined
	      group, access, and view directives instead,  but	these  wrapper
	      directives are much simpler.

	      The  minimum  level  of authentication and privacy the user must
	      use is specified by the first token (which defaults to  "auth").
	      The  OID	parameter restricts access for that user to everything
	      below the	given OID.

       rocommunity COMMUNITY [SOURCE [OID]]

       rwcommunity COMMUNITY [SOURCE [OID]]
	      These create read-only and read-write communities	 that  can  be
	      used  to	access the agent.  They	are a quick wrapper around the
	      more complex and powerful	com2sec, group,	access,	and  view  di-
	      rective  lines.	They  are  not	as efficient either, as	groups
	      aren't created so	the tables  are	 possibly  larger.   In	 other
	      words: don't use these if	you have complex situations to set up.
	      If your setup is simple or you don't mind	 a  small  performance
	      hit, use these directives.

	      The  format  of  the SOURCE is token is described	in the com2sec
	      directive	section	below.	The OID	 token	restricts  access  for
	      that community to	everything below that given OID.

       rocommunity6 COMMUNITY [SOURCE [OID]]

       rwcommunity6 COMMUNITY [SOURCE [OID]]
	      They are the alternative directives to the rocommunity, rwcommu-
	      nity for the transport domain UDPIPv6. They are  only  valid  in
	      specifing	UDPIPv6	as transport domain.

	      The  format  of the SOURCE is token is described in the com2sec6
	      directive	section	below.	The OID	 token	restricts  access  for
	      that community to	everything below that given OID.

	      This  directive  specifies  the  mapping from a source/community
	      pair to a	security name. SOURCE can be a hostname, a subnet,  or
	      the  word	 "default".   A	 subnet	can be specified as IP/MASK or
	      IP/BITS.	 For  example,	given  a  directive  "com2sec  myLocal public" then this would match requests from	IP ad-
	      dresses through to,  but	not  one  from  or  similar.	The first source/community combination
	      that matches the incoming	packet is selected.

	      This directive is	the IPv6 version of com2sec.  A	subnet can  be
	      specified	 as  IPv6/IPv6MASK  or IPv6/BITS.  It is only valid in
	      specifing	UDPIPv6	as transport domain.

	      This directive defines the mapping from  securitymodel/security-
	      name to group.  MODEL is one of v1, v2c, or usm.

	      The  access  directive  maps  from group/security	model/security
	      level to a view.	MODEL is one of	any, v1, v2c, or  usm.	 LEVEL
	      is  one  of  noauth, auth, or priv.  PREFX specifies how CONTEXT
	      should be	matched	against	the context of the incoming  pdu,  ei-
	      ther exact or prefix.  READ, WRITE and NOTIFY specifies the view
	      to be used for the corresponding access.	For v1 or v2c  access,
	      LEVEL will be noauth, and	CONTEXT	will be	empty.

	      This  defines  the  named	 view.	TYPE is	either included	or ex-
	      cluded.  MASK is a list of hex octets, separated by '.' or  ':'.
	      The MASK defaults	to "ff"	if not specified.

	      The reason for the mask is, that it allows you to	control	access
	      to one row in a table, in	a relatively simple way. As  an	 exam-
	      ple, as an ISP you might consider	giving each customer access to
	      his or her own interface:

	      view cust1 included interfaces.ifTable.ifEntry.ifIndex.1 ff.a0
	      view cust2 included interfaces.ifTable.ifEntry.ifIndex.2 ff.a0

	      (interfaces.ifTable.ifEntry.ifIndex.1 == .,
	      ff.a0 == 11111111.10100000. which	nicely covers up and including
	      the row index, but lets the user vary the	field of the row)

       VACM Examples:
	      #	 source		 community
	      com2sec  local	 localhost	 private
	      com2sec  mynet	 public
	      com2sec  public	 default	 public
	      com2sec6 mynet	 fec0::/64	 public

	      #		    sec.model
	      group mygroup v1	       mynet
	      group mygroup v2c	       mynet
	      group mygroup usm	       mynet
	      group local   v1	       local
	      group local   v2c	       local
	      group local   usm	       local
	      group public  v1	       public
	      group public  v2c	       public
	      group public  usm	       public

	      #		  incl/excl subtree			     mask
	      view all	  included  .1				     80
	      view system included  system			     fe
	      view mib2	  included fc

	      #		     context sec.model sec.level prefix	read   write notify
	      access mygroup ""	     any       noauth	 exact	mib2   none  none
	      access public  ""	     any       noauth	 exact	system none  none
	      access local   ""	     any       noauth	 exact	all    all   all

       Default VACM model
	      The default configuration	of the agent, as shipped, is functionally
	      equivalent to the	following entries:
	      com2sec	public	  default   public
	      group	public	  v1   public
	      group	public	  v2c  public
	      group	public	  usm  public
	      view	all  included  .1
	      access	public	  ""   any  noauth    exact	all  none none

       engineID	STRING
	      The snmpd	agent needs to be configured with an  engineID	to  be
	      able  to	respond	 to  SNMPv3 messages.  With this configuration
	      file line, the engineID will be configured from STRING.  The de-
	      fault  value of the engineID is configured with the first	IP ad-
	      dress found for the hostname of the machine.

       createUser [-e ENGINEID]	username (MD5|SHA) authpassphrase [DES]	[priv-

	      MD5  and	SHA  are the authentication types to use, but you must
	      have built the package with openssl installed in	order  to  use
	      SHA.   The only privacy protocol currently supported is DES.  If
	      the privacy passphrase is	not specified, it is assumed to	be the
	      same as the authentication passphrase.  Note that	the users cre-
	      ated will	be useless unless they are also	added to the VACM  ac-
	      cess control tables described above.

	      Warning: the minimum pass	phrase length is 8 characters.

	      SNMPv3 users can be created at runtime using the snmpusm(1) com-

	      Instead of figuring out how to use this directive	and  where  to
	      put  it  (see  below),  just  run	 "net-snmp-config --create-sn-
	      mpv3-user" instead, which	will add one of	 these	lines  to  the
	      right place.

	      This  directive  should  be  placed  into	 the /var/net-snmp/sn-
	      mpd.conf file instead of the other normal	locations.  The	reason
	      is  that the information is read from the	file and then the line
	      is removed (eliminating the storage of the master	 password  for
	      that  user)  and	replaced with the key that is derived from it.
	      This key is a localized key, so that if it is stolen it can  not
	      be used to access	other agents.  If the password is stolen, how-
	      ever, it can be.

	      If you need to localize the user to a particular EngineID	 (this
	      is  useful  mostly  in the similar snmptrapd.conf	file), you can
	      use the -e argument to specify an	EngineID as a hex  value  (EG,

       syslocation STRING

       syscontact STRING

       sysname STRING
	      Sets  the	system location, system	contact	or system name for the
	      agent.  This information is reported in the 'system'  group  the
	      mibII  tree.   Ordinarily	 these objects (sysLocation.0, sysCon-
	      tact.0 and sysName.0) are	read-write.  However,  specifying  the
	      value  for  one of these objects by giving the appropriate token
	      makes the	corresponding object read-only,	and  attempts  to  set
	      the  value  of the object	will result in a notWritable error re-

       sysservices NUMBER
	      Sets the value of	the system.sysServices.0 object.  For a	 host,
	      a	good value is 72.

       sysdescr	STRING

       sysobjectid OID
	      Sets  the	 system	 description  or object	ID for the agent.  Al-
	      though these values are not  SNMP-writable,  it  is  conceivable
	      that a network administrator may wish to configure them to some-
	      thing other than the default values.

       agentaddress [<transport-specifier>:]<transport-address>[,...]
	      Makes the	agent list on the specified  comma-separated  list  of
	      listening	 addresses  instead of the default behaviour, which is
	      to listen	on UDP port 161	on all IPv4 interfaces.	 See the  sec-
	      tion  LISTENING  ADDRESSES  in the snmpd(8) manual page for more
	      information about	the format of listening	addresses.  For	 exam-
	      ple,  specifying	agentaddress  161,tcp:161,localhost:9161  will
	      make the agent listen on UDP port	161 on	all  IPv4  interfaces,
	      TCP  port	 161  on all IPv4 interfaces and UDP port 9161 only on
	      the interface associated with the	localhost address.

       agentgroup groupid
	      Change to	this gid after opening port. The groupid may refer  to
	      a	group by name or a number if the group number starts with '#'.
	      For example, specifying agentgroup snmp will cause the agent  to
	      run  as the snmp group or	agentgroup #10 will cause the agent to
	      run as the group with groupid 10.

       agentuser uid
	      Change to	this uid after opening port. The userid	may refer to a
	      user by name or a	number if the user number starts with '#'. For
	      example, specifying agentuser snmp will cause the	agent  to  run
	      as the snmp user or agentuser #10	will cause the agent to	run as
	      the user with userid 10.

       interface NAME TYPE SPEED
	      For interfaces where the agent fails to guess correctly  on  the
	      type  and	 speed,	 this directive	can supply additional informa-
	      tion.  TYPE is a type value as given in the IANAifType-MIB.

       ignoredisk STRING
	      When scanning for	available disk devices the agent  might	 block
	      in  trying to open all possible disk devices. This might lead to
	      a	timeout	when walking the device	tree. Sometimes	the next  walk
	      will  run	 without timeout, sometimes it will timeout every time
	      you try it.

	      If you experience	such behaviour you might  add  this  directive
	      and  give	 all device names not to be checked (i.e. opened). You
	      might have more than one such directive  in  your	 configuration
	      file  stating all	devices	not to be opened. You might also spec-
	      ify those	devices	using wildcards	similar	to the syntax you  can
	      use in a bourne shell (see examples below).

	      Note: For	a list of devices scanned for every system please con-
	      sult  the	  sources   (host/hr_disk.c)   and   check   for   the
	      Add_HR_Disk_entry() calls	relevant for your type of OS.


	      ignoredisk /dev/rdsk/c0t2d0

	      This  directive  prevents	the device /dev/rdsk/c0t2d0 from being

	      ignoredisk /dev/rdsk/c0t[!6]d0

	      This directive  prevents	all  devices  /dev/rdsk/c0tXd0	except
	      .../c0t6d0  from	being scanned. For most	systems	similar	is the
	      following	directive:

	      ignoredisk /dev/rdsk/c0t[0-57-9a-f]d0

	      ignoredisk /dev/rdsk/c1*

	      This directive prevents all devices  whose  device  names	 start
	      with /dev/rdsk/c1	from being scanned.

	      ignoredisk /dev/rdsk/c?t0d0

	      This  directive prevents all devices /dev/rdsk/cXt0d0 ('X' might
	      be any char) from	being scanned.

	      You might	use more than one such wildcard	expression in any such

       storageUseNFS NUMBER
	      Setting storageUseNFS to 1 causes	all NFS	and NFS-like file sys-
	      tems to be marked	as 'Network Disks' in the hrStorageTable. This
	      is  according to RFC 2790.  Not setting storageUseNFS or setting
	      it to 2 causes NFS and NFS-like file systems  to	be  marked  as
	      'Fixed  Disks'  as  it has been in previous versions of the ucd-
	      snmp SNMP	agent.

       authtrapenable NUMBER
	      Setting authtrapenable to	1 enables generation of	authentication
	      failure  traps.	The  default value is disabled(2).  Ordinarily
	      the  corresponding  object  (snmpEnableAuthenTraps.0)  is	 read-
	      write,  but  setting  its	 value via this	token makes the	object
	      read-only, and attempts to set the value of the object will  re-
	      sult in a	notWritable error response.

       override	OID TYPE VALUE
	      This  directive  allows  you to override a particular OID	with a
	      different	value (and possibly a different	type  of  value).   An

	      override sysDescr.0 octet_str "my	own sysDescr"

	      That  line will set the sysDescr.0 value to "my own sysDescr" as
	      well as make it modifiable with SNMP SETs	as well	(which is  ac-
	      tually illegal according to the MIB specifications).

	      Note  that  care must be taken when using	this.  For example, if
	      you try to override a property  of  the  3rd  interface  in  the
	      ifTable  with  a	new  value  and	later the numbering within the
	      ifTable changes it's index ordering you'll end up	with  problems
	      and  your	 modified value	won't appear in	the right place	in the

	      Valid TYPEs are:	integer,  uinteger,  octet_str,	 bit_str,  ob-
	      ject_id,	counter,  gauge, null.	Note that setting an object to
	      "null" effectively delete's it as	being  accessible.   No	 VALUE
	      needs to be given	if the object type is null.

	      More  types  should  be  available  in  the  future,  as well as
	      writable object support.

       trapcommunity STRING
	      This defines the default community string	to be used when	 send-
	      ing  traps.  Note	that this command must be used prior to	any of
	      the following three commands that	are intended use  this	commu-
	      nity string.

       trapsink	HOST [COMMUNITY	[PORT]]

       trap2sink HOST [COMMUNITY [PORT]]

       informsink HOST [COMMUNITY [PORT]]
	      These  commands define the hosts to receive traps	(and/or	inform
	      notifications). The daemon sends	a  Cold	 Start	trap  when  it
	      starts  up.  If  enabled,	 it also sends traps on	authentication
	      failures.	 Multiple trapsink, trap2sink and informsink lines may
	      be specified to specify multiple destinations.  Use trap2sink to
	      send SNMPv2 traps	and informsink to send	inform	notifications.
	      If COMMUNITY is not specified, the string	from a preceding trap-
	      community	directive will be used.	If PORT	is not specified,  the
	      well known SNMP trap port	(162) will be used.

       trapsess	[SNMPCMD_ARGS] HOST
	      This  is a more generic trap configuration token that allows any
	      type of trap destination to be specified	with  any  version  of
	      SNMP.  See the snmpcmd(1)	manual page for	further	details	on the
	      arguments	that can be passed as SNMPCMD ARGS .  In  addition  to
	      the  arguments  listed there, the	special	argument -Ci specifies
	      that you want inform notifications to be used instead  of	 unac-
	      knowledged  traps	(this requires that you	also specify a version
	      number of	v2c or v3 as well).


	      This token specifies that	any incoming requests under OID	should
	      be  proxied  on  to  another  HOST instead.  If a	CONTEXTNAME is
	      specified, it assigns the	proxied	tree to	a  particular  context
	      name  within  the	 local agent.  This is the proper way to query
	      multiple agents through a	 single	 proxy.	  Assign  each	remote
	      agent  to	 a different context name.  Then you can use "snmpwalk
	      -n contextname1" to walk one remote proxied agent	and  "snmpwalk
	      -n  contextname2"	to walk	another, assuming you are using	SNMPv3
	      to talk to the proxy (snmpv1 and snmpv2c context mappings	aren't
	      currently	 supported  but	 might be in the future).  Optionally,
	      relocate the local OID tree to the new  location	at  the	 REMO-
	      TEOID.   To  authenticate	to HOST	you should use the appropriate
	      set of SNMPCMD ARGS.  See	the snmpcmd(1)	manual	page  for  de-


		     # assigns the entire mib tree on remotehost1 to the context of the
		     # same name:
		     proxy -Cn remotehost1 -v 1	-c public remotehost1 .1.3
		     # ditto, but for remotehost 2
		     proxy -Cn remotehost2 -v 1	-c public remotehost2 .1.3
		     # proxies only the	ucdavis	enterprises tree to the	remote host using snmpv1
		     proxy -v 1	-c public remotehost .
		     # uses v3 to access remotehost and	converts the remote .
		     # oid to local . oid (another way to access mulitple hosts
		     # without using contexts)
		     proxy -v 3	-l noAuthNoPriv	-u user	remotehost . .

       pass MIBOID EXEC
	      (If  you're  writing  perl scripts, please see the embedded perl
	      support information later	in this	manual page).	Passes	entire
	      control  of  MIBOID  to  the  EXEC program.  The EXEC program is
	      called in	one of the following three ways:

	      EXEC -g MIBOID

	      EXEC -n MIBOID

		     These call	lines match to SNMP get	and getnext  requests.
		     It	 is expected that the EXEC program will	take the argu-
		     ments passed to it	and return  the	 appropriate  response
		     through it's stdout.

		     The first line of stdout should be	the MIB	OID of the re-
		     turning value.  The second	line should  be	 the  TYPE  of
		     value  returned,  where  TYPE is one of the text strings:
		     string, integer,  unsigned,  objectid,  timeticks,	 ipad-
		     dress,  counter,  or  gauge.   The	 third	line of	stdout
		     should be the VALUE corresponding with the	returned TYPE.

		     For instance, if a	script was to return the value integer
		     value  "42"  when	a  request  for	. was re-
		     quested, the script should	return the following 3 lines:

		     To	indicate that the script is unable to comply with  the
		     request  due to an	end-of-mib condition or	an invalid re-
		     quest, simple exit	and return no output to	stdout at all.
		     An	SNMP error will	be generated corresponding to the SNMP
		     noSuchName	response.


		     For SNMP set requests, the	above  call  method  is	 used.
		     The  TYPE	passed	to the EXEC program is one of the text
		     strings: integer, counter,	gauge,	timeticks,  ipaddress,
		     objid,  or	string,	indicating the type of value passed in
		     the next argument.

		     Return nothing to stdout, and the	set  will  assumed  to
		     have  been	successful.  Otherwise,	return one of the fol-
		     lowing error strings to signal an error: not-writable, or
		     wrong-type	 and  the  appropriate	error response will be
		     generated instead.

		     Note:  By default,	the only community  allowed  to	 write
			    (ie	 snmpset) to your script will be the "private"
			    community,or community #2 if  defined  differently
			    by	the  "community" token discussed above.	 Which
			    communities	are  allowed  write  access  are  con-
			    trolled  by	 the  RWRITE  definition  in  the snm-
			    plib/snmp_impl.h source file.

	      Example (in snmpd.conf):

	      pass . /path/to/local/passtest

       pass_persist MIBOID EXEC
	      Passes entire control of MIBOID to the EXEC program.  Similar to
	      pass,  but  the  EXEC program continues to run after the initial
	      request is answered.

	      Upon initialization, EXEC	 is  passed  the  string  "PING\n"  in
	      stdin, and it should respond by printing "PONG\n"	to stdout.

	      For  get and getnext requests, EXEC program is passed two	lines,
	      the command (get or getnext) and the MIB OID.  It	should	return
	      three  lines, the	MIB OID, the TYPE of value returned, the VALUE
	      corresponding with the returned TYPE.

	      For example, if the value	for . was requested,  the
	      following	2 lines	would be passed	in to stdin:

	      To return	the value, say,	42, the	script would write to stdout:

	      To indicate that the script is unable to comply with the request
	      due to an	end-of-mib condition  or  an  invalid  request,	 print
	      "NONE\n" to stdout.

	      Example (in snmpd.conf):

	      pass_persist    .   /path/to/local/pass_per-

       Warning:	though embedded	perl is	working, not  much  functionality  has
       been  implemented  yet and thus writing mib module pieces for the agent
       within perl is not trivial at this point.  It should get	better in  fu-
       ture releases.

       The  net-snmp  package has ability to call perl scripts directly	inside
       the agent through embedded perl technology (similar to mod_perl for the
       apache  web server).  This must be turned on at compile time by passing
       --enable-embedded-perl to the configure	script	when  the  package  is
       built.	To see if your package was built with embedded perl, run "net-
       snmp-config --configure-options"	and see	if that	flag was used.

       If compiled in, it defines the following	snmpd.conf  configuration  di-

       disablePerl true
	      This  will turn off perl support entirely.  If the embedded perl
	      support stops working due	to a change in perl,  etc,  this  will
	      stop any calls to	the perl core.

       perlInitFile FILE
	      Use  FILE	 as  the  initialization  file.	 This file is normally
	      /usr/local/share/snmp/ but this token	 can  override
	      that  default.   This  file  performs any	in-perl	initialization
	      that is needed before the	rest of	the  perl  directives  (below)
	      are  called.   It	is sourced once	just before the	first perl di-
	      rective is parsed.  See the default file for an example  of  the
	      initialization it	performs.

       perl EXPRESSION
	      Calls perl to evaluate an	expression.  Normally you'd want to do
	      something	like register a	function to call when an  OID  is  re-
	      quested,	but  you can really do anything	perl related you want.
	      For example:

	      perl print "hello	world\n";

	      is the most basic	hello world example.

	      The init script by default initializes a $agent  variable	 which
	      is  a  pointer  to a NetSnmp::agent object through which you can
	      register callbacks when a	section	of the OID tree	is hit:

	      perl use Data::Dumper;
	      perl sub myroutine  { print "got called: ",Dumper(@_),"\n"; }
	      perl $agent->register('mylink', '.', \&myroutine);

	      Sourcing an external file:

	      perl 'do /path/to/';

	      No better	examples exist at the moment, unfortunately.  Look for
	      improved support in future releases.  Comments on	how this looks
	      as an architecture are certainly appreciated now.

       Warning:	this implementation has	not been extensively tested and	is ad-
       ditionally  not	known  to  be entirely complete.  The concepts defined
       here should function appropriately, however, but	no promises  are  made
       at this time.

       If  your	 agent was compiled with support for the DISMAN-EVENT-MIB (you
       can enable this by running  the	net-snmp  configure  script  with  the
       --with-mib-modules=disman/event-mib argument) you have support for hav-
       ing the agent check its own data	at regular intervals and to  send  out
       traps  when  certain conditions occur.  Traps are sent when expressions
       are first noticed, not once per evaluation.   Once  a  test  expression
       fires  a	 trap,	the  test will have to fail again before a new trap is
       sent.  See the DISMAN-EVENT-MIB documentation for  more	details.  This
       can  be	configured  either using the MIB tables	themselves or by using
       these special key words:

       agentSecName NAME
	      The DISMAN-EVENT-MIB support requires  a	valid  user  name  for
	      which to scan your agent with.  This can either be specified us-
	      ing the agentSecName token or by	explicitly  list  one  on  the
	      "monitor"	 lines	described  below  using	the -u switch.	Either
	      way, a "rouser" line (or	equivalent  access  control  settings)
	      must also	be specified with the same security name name.	If you
	      need an example, just do something like this:

		     agentSecName internal
		     rouser internal

	      And everything below should work just fine.

	      This token tells the agent to monitor itself for problems	 based
	      on  EXPRESSION.	Expression  is a simple	expression based on an
	      oid, a comparison	operator (!=, ==, <, <=, >, >=)	and an integer
	      value  (see  the	examples  below).  NAME	is merely an arbitrary
	      name of your choosing for	administrative purposes	only.  OPTIONS
	      include the following possibilities:

	      -t     Use  a  threshold	monitor	 instead of a boolean monitor.
		     This means	that expression	 should	 be  a	low  and  high
		     value.   If the given OID passes beyond the high value, a
		     rising alarm will triggered.  A falling alarm  will  then
		     be	triggered after	it falls below the low value.

	      -r FREQUENCY
		     Monitors  the  given  expression every FREQUENCY seconds.
		     The default is 600	(10 minutes).

	      -u SECNAME
		     Use the SECNAME security  name  for  scanning  the	 local
		     host.   Specifically, this	SECNAME	must then be given ac-
		     cess control rights via something like the	 "rouser"  sn-
		     mpd.conf  token  for  this	expression to be valid at all.
		     If	not specified, it uses the default security name spec-
		     ified  by	the agentsecname snmpd.conf token.  Either the
		     -u	flag or	a valid	agentsecname token must	 be  specified
		     (and that name must be given proper access	control	rights
		     via a "rouser" token).

	      -o OID Specifies additional object values	to be  delivered  with
		     in	 the resulting trap in addition	to the normal trap ob-
		     jects.  This is useful for	obtaining other	columns	in the
		     table for the row that triggered the expression.  See the
		     examples below for	more details.

	      -e EVENTNAME
		     Specifies an event	name that describes what  to  do  when
		     the  trigger  is fired.  Currently, this must be the name
		     of	a notificationEvent event as described below.

	      The following example configuration checks the  hrSWRunPerfTable
	      table  (listing running processes) for any process which is con-
	      suming > 10Mb of memory.	It performs this check every 600  sec-
	      onds  (the  default).   For every	process	it finds exceeding the
	      limit, it	will end out exactly one notification.	In addition to
	      the  normal  hrSWRunPerfMem  oid and value sent in the trap, the
	      hrSWRunName object will also be sent.  Note that the hrSWRunName
	      object  actually	occurs in a different table, but since the in-
	      dexes to the two tables are the same this	works out alright.

		     rouser me
		     monitor -u	me -o sysUpTime.0 -o hrSWRunName "high process memory" hrSWRunPerfMem >	10000

	      The above	line would produce a trap which, when formated by  sn-
	      mptrapd, would look like:

		     2002-04-05	13:33:53 localhost.localdomain [udp:]:
			     sysUpTimeInstance = Timeticks: (1629) 0:00:16.29	     snmpTrapOID.0 = OID: mteTriggerFired    mteHotTrigger = high process memory     mteHotTargetName =	     mteHotContextName =     mteHotOID = OID: hrSWRunPerfMem.1968    mteHotValue = 28564     hrSWRunName.1968 =	"xemacs"

	      This  shows  my  xemacs  process	using 28Mb of resident memory.
	      Which, considering it's xemacs, is not that surprising.

	      Threshold	example:

		     monitor -t	-r 15 -o prNames -o prErrMessage "process table" prErrorFlag 0 1

       notificationEvent NAME NOTIFICATION [[-w] OID_OBJECT ...]
	      This will	create a notification event, which can be fired	by at-
	      taching it to a monitor using a monitor's	-e switch and an iden-
	      tical NAME field.	 The NOTIFICATION to be	sent should be the OID
	      of  a  notification.  Additional objects can be included,	and by
	      default the suffix of the	row/object being monitored will	be ap-
	      pended  to  the  object  identifier unless it's told not to be a
	      wild-card	object by prefixing it with the	 -w  switch.   EG,  if
	      you're  monitoring the ifTable and you want your trap to include
	      the ifDescr object for the row that was  discovered,  don't  add
	      the -w switch and	the .INDEX field will be appended.  If the OID
	      is fully qualified (EG, "sysContact.0") and no  instance	suffix
	      should  be  appended  to it then add a -w	switch before it.  See
	      the linkUpDownNotifications token	below  for  example  usage  of
	      this token to send the linkUp and	linkDown traps.

       linkUpDownNotifications yes
	      This will	make the DISMAN-EVENT-MIB support watch	the ifTable to
	      determine	when a network interface is taken up  or  down.	  When
	      this  happens,  a	 linkUp	or linkDown notification will be trig-
	      gered.  This is exactly equivalent to doing:

		     notificationEvent	linkUpTrap    linkUp   ifIndex ifAdminStatus ifOperStatus
		     notificationEvent	linkDownTrap  linkDown ifIndex ifAdminStatus ifOperStatus

		     monitor  -r 60 -e linkUpTrap   "Generate linkUp" ifOperStatus != 2
		     monitor  -r 60 -e linkDownTrap "Generate linkDown"	ifOperStatus ==	2

       defaultMonitors yes
	      By default, the agent and	the DISMAN-EVENT-MIB support do	 noth-
	      ing until	configured.  Typically people wish to watch a bunch of
	      tables within the	UCD-SNMP-MIB which are	designed  specifically
	      for  reporting  problems.	  If the "defaultMonitors yes" line is
	      put into the snmpd.conf file (which must be  accompanied	by  an
	      appropriate  agentSecName	line and a rouser line), the following
	      monitoring conditions will be installed:

		     monitor   -o prNames -o prErrMessage "process table" prErrorFlag != 0
		     monitor   -o memErrorName -o memSwapErrorMsg "memory" memSwapError	!= 0
		     monitor   -o extNames -o extOutput	"extTable" extResult !=	0
		     monitor   -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
		     monitor   -o laNames -o laErrMessage  "laTable" laErrorFlag != 0
		     monitor   -o fileName -o fileErrorMsg  "fileTable"	fileErrorFlag != 0

       If you're trying	to figure out aspects of the various mib modules (pos-
       sibly some that you've added yourself), the following may help you spit
       out some	useful debugging information.  First off, please read the  sn-
       mpd  manual  page on the	-D flag.  Then the following configuration sn-
       mpd.conf	token, combined	with the -D flag, can produce useful output:

       injectHandler HANDLER modulename
	      This will	insert new handlers into the section of	the  mib  tree
	      referenced by "modulename".  The types of	handlers available for
	      insertion	are:
	      stash_cache  - Caches information	returned from the lower	level.	This
			     greatly help the performance of the agent,	at the cost
			     of	caching	the data such that its no longer "live"	for
			     30	seconds	(in this future, this will be configurable).
			     Note that this means snmpd	will use more memory as	well
			     while the information is cached.  Currently this only
			     works for handlers	registered using the table_iterator
			     support, which is only a few mib tables.  To use it,
			     you need to make sure to install it before	the
			     table_iterator point in the chain,	so to do this:

				injectHandler stash_cache NAME table_iterator

			     If	you want a table to play with, try walking the
			     nsModuleTable with	and without this injected.

	      debug	   - Prints out	lots of	debugging information when
			     the -Dhelper:debug	flag is	passed to the snmpd

	      read_only	   - Forces turning off	write support for the given module.

	      serialize	   - If	a module is failing to handle multiple requests
			     properly (using the new 5.0 module	API), this will	force
			     the module	to only	receive	one request at a time.

	      bulk_to_next - If	a module registers to handle getbulk support, but
			     for some reason is	failing	to implement it	properly,
			     this module will convert all getbulk requests to
			     getnext requests before the final module receives it.

       Figuring	out module names
	      To figure	out which modules you can inject things	into, snmpwalk
	      the  nsModuleTable  which	will give you a	list of	all named mod-
	      ules registered within the agent.

       See the EXAMPLE.CONF file in the	top level source directory for a  more
       detailed	example	of how the above information is	used in	real examples.

RE-READING snmpd.conf AND snmpd.local.conf
       The  Net-SNMP  agent  can be forced to re-read its configuration	files.
       It can be told to do so by one of two ways:

       1.     An snmpset of integer(1) to  UCD-SNMP-MIB::versionUpdateConfig.0

       2.     A	"kill -HUP" signal sent	to the snmpd agent process.


       snmpconf(1),  snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAM-
       PLE.conf, read_config(3).

4th Berkeley Distribution	  08 Feb 2002			 SNMPD.CONF(5)


Want to link to this manual page? Use this URL:

home | help