1SNMPD.CONF(5)                      Net-SNMP                      SNMPD.CONF(5)
2
3
4

NAME

6       snmpd.conf - configuration file for the Net-SNMP SNMP agent
7

DESCRIPTION

9       The  Net-SNMP agent uses one or more configuration files to control its
10       operation and the management information provided.   These  files  (sn‐
11       mpd.conf  and  snmpd.local.conf) can be located in one of several loca‐
12       tions, as described in the snmp_config(5) manual page.
13
14       The (perl) application snmpconf can be used to  generate  configuration
15       files for the most common agent requirements.  See the snmpconf(1) man‐
16       ual page for more information, or try running the command:
17
18              snmpconf -g basic_setup
19
20       There are a large number of directives that can be specified, but these
21       mostly fall into four distinct categories:
22
23       •      those controlling who can access the agent
24
25       •      those configuring the information that is supplied by the agent
26
27       •      those controlling active monitoring of the local system
28
29       •      those concerned with extending the functionality of the agent.
30
31       Some directives don't fall naturally into any of these four categories,
32       but this covers the majority of the contents of  a  typical  snmpd.conf
33       file.   A full list of recognised directives can be obtained by running
34       the command:
35
36              snmpd -H
37

AGENT BEHAVIOUR

39       Although most configuration directives are concerned with the  MIB  in‐
40       formation supplied by the agent, there are a handful of directives that
41       control the behaviour of snmpd considered simply as a daemon  providing
42       a network service.
43
44       agentaddress [<transport-specifier>:]<transport-address>[,...]
45              defines  a  list of listening addresses, on which to receive in‐
46              coming SNMP requests.  See the section  LISTENING  ADDRESSES  in
47              the  snmpd(8)  manual page for more information about the format
48              of listening addresses.
49
50              The default behaviour is to listen on UDP port 161 on  all  IPv4
51              interfaces.
52
53       agentgroup {GROUP|#GID}
54              changes  to  the  specified  group  after  opening the listening
55              port(s).  This may refer to a group by name (GROUP),  or  a  nu‐
56              meric group ID starting with '#' (#GID).
57
58       agentuser {USER|#UID}
59              changes  to  the  specified  user  after  opening  the listening
60              port(s).  This may refer to a user by name (USER), or a  numeric
61              user ID starting with '#' (#UID).
62
63       leave_pidfile yes
64              instructs  the  agent  to  not  remove its pid file on shutdown.
65              Equivalent to specifying "-U" on the command line.
66
67       maxGetbulkRepeats NUM
68              Sets the maximum number of responses allowed for a single  vari‐
69              able  in  a getbulk request.  Set to 0 to enable the default and
70              set it to -1 to enable unlimited.  Because memory  is  allocated
71              ahead  of time, setting this to unlimited is not considered safe
72              if your user population can not be  trusted.   A  repeat  number
73              greater than this will be truncated to this value.
74
75              This is set by default to -1.
76
77       maxGetbulkResponses NUM
78              Sets  the  maximum number of responses allowed for a getbulk re‐
79              quest.  This is set by default to 100.  Set to 0 to  enable  the
80              default and set it to -1 to enable unlimited.  Because memory is
81              allocated ahead of time, setting this to unlimited is  not  con‐
82              sidered safe if your user population can not be trusted.
83
84              In general, the total number of responses will not be allowed to
85              exceed the maxGetbulkResponses number, and the total number  re‐
86              turned  will  be  an integer multiple of the number of variables
87              requested times the calculated number of repeats  allow  to  fit
88              below this number.
89
90              Also note that processing of maxGetbulkRepeats is handled first.
91
92       ifmib_max_num_ifaces NUM
93              Sets  the  maximum  number of interfaces included in IF-MIB data
94              collection.  For servers with a large number of interfaces (ppp,
95              dummy,  bridge,  etc)  the  IF-MIB  processing will take a large
96              chunk of CPU for ioctl calls (on Linux).  Setting  a  reasonable
97              maximum  for  the  CPU  used will reduce the CPU load for IF-MIB
98              processing.  For example, configuring "ifmib_max_num_ifaces 500"
99              will  include only the first 500 interfaces based on ifindex and
100              ignore all others for IF-MIB processing.
101
102              The default (without this configured) is to include  all  inter‐
103              faces.
104
105       include_ifmib_iface_prefix PREFIX1 PREFIX2 ...
106              Sets  the  interface name prefixes to include in the IF-MIB data
107              collection.  For servers with a large number of interfaces (ppp,
108              dummy,  bridge,  etc)  the  IF-MIB  processing will take a large
109              chunk of CPU for ioctl calls (on Linux). A set  of  space  sepa‐
110              rated  interface  name prefixes will reduce the CPU load for IF-
111              MIB    processing.     For     example,     configuring     "in‐
112              clude_ifmib_iface_prefix  eth dummy lo" will include only inter‐
113              faces with these prefixes and ignore all others for IF-MIB  pro‐
114              cessing.  If  regex support is compiled in, each of the prefixes
115              is a regular expression (which is not  permitted  to  contain  a
116              space or tab character).
117
118              The  default  (without this configured) is to include all inter‐
119              faces.
120
121   SNMPv3 Configuration - Real Security
122       SNMPv3 is added flexible security models to the SNMP  packet  structure
123       so that multiple security solutions could be used.  SNMPv3 was original
124       defined with a "User-based Security Model"  (USM)  [RFC3414]  that  re‐
125       quired  maintaining  a SNMP-specific user database.  This was later de‐
126       termined to be troublesome to maintain and had some minor security  is‐
127       sues.   The  IETF  has since added additional security models to tunnel
128       SNMP over SSH [RFC5592] and DTLS/TLS  [RFC-to-be].   Net-SNMP  contains
129       robust  support  for  SNMPv3/USM, SNMPv3/TLS, and SNMPv3/DTLS.  It con‐
130       tains partial support for SNMPv3/SSH as well but has not been as exten‐
131       sively  tested.   It also contains code for support for an experimental
132       Kerberos based SNMPv3 that never got standardized.
133
134       Hopefully more SNMP software and devices will eventually  support  SNMP
135       over (D)TLS or SSH, but it is likely that devices with original support
136       for SNMP will only contain support for USM users.  If your network man‐
137       ager  supports SNMP over (D)TLS or SNMP over SSH we suggest you use one
138       of these mechanisms instead of using USM, but as always  with  Net-SNMP
139       we give you the options to pick from so you can make the choice that is
140       best for you.
141
142   SNMPv3 generic parameters
143       These parameters are generic to all the forms of  SNMPv3.   The  SNMPv3
144       protocol  defines  "engineIDs"  that  uniquely  identify an agent.  The
145       string must be consistent through time and should not  change  or  con‐
146       flict  with  another  agent's engineID.  Ever.  Internally, Net-SNMP by
147       default creates a unique engineID that is based off of the current sys‐
148       tem time and a random number.  This should be sufficient for most users
149       unless you're embedding our agent in a device where these numbers won't
150       vary between boxes on the devices initial boot.
151
152              EngineIDs are used both as a "context" for selecting information
153              from the device and SNMPv3 with USM uses it to create unique en‐
154              tries for users in its user table.
155
156              The  Net-SNMP  agent offers the following mechanisms for setting
157              the engineID, but again you should only use  them  if  you  know
158              what you're doing:
159
160       engineID STRING
161              specifies  that the engineID should be built from the given text
162              STRING.
163
164       engineIDType 1|2|3
165              specifies that the engineID should be built from  the  IPv4  ad‐
166              dress  (1),  IPv6  address  (2)  or  MAC address (3).  Note that
167              changing the IP address  (or  switching  the  network  interface
168              card) may cause problems.
169
170       engineIDNic INTERFACE
171              defines which interface to use when determining the MAC address.
172              If engineIDType 3 is not specified, then this directive  has  no
173              effect.
174
175              The default is to use eth0.
176
177   SNMPv3 over TLS
178       SNMPv3  may  be tunneled over TLS and DTLS.  TLS runs over TCP and DTLS
179       is the UDP equivalent.  Wes Hardaker (the  founder  of  Net-SNMP)  per‐
180       formed a study and presented it at an IETF meeting that showed that TCP
181       based protocols are sufficient for stable networks but quickly  becomes
182       a problem in unstable networks with even moderate levels of packet loss
183       (~ 20-30%).  If you are going to use TLS or DTLS, you  should  use  the
184       one  appropriate  for  your  networking environment.  You should poten‐
185       tially turn them both on so your management system  can  access  either
186       the UDP or the TCP port as needed.
187
188       Many  of  the  configuration tokens described below are prefixed with a
189       '[snmp]' tag.  If you place these tokens in your snmpd.conf file,  this
190       take  is  required.  See the snmp_config(5) manual page for the meaning
191       of this context switch.
192
193       [snmp] localCert <specifier>
194              This token defines the default X.509 public key to  use  as  the
195              server's identity.  It should either be a fingerprint or a file‐
196              name.   To  create  a  public  key  for  use,  please  run   the
197              "net-snmp-cert"  utility which will help you create the required
198              certificate.
199
200              The default value for this is the  certificate  in  the  "snmpd"
201              named certificate file.
202
203       [snmp] tlsAlgorithms <algorithms>
204              This  string  will select the algorithms to use when negotiating
205              security during (D)TLS session establishment.  See  the  openssl
206              manual  page  ciphers(1)  for  details  on the format.  Examples
207              strings include:
208
209              DEFAULT
210              ALL
211              HIGH
212              HIGH:!AES128-SHA
213
214              The default value is  whatever  openssl  itself  was  configured
215              with.
216
217       [snmp] x509CRLFile
218              If  you  are using a Certificate Authority (CA) that publishes a
219              Certificate Revocation List (CRL) then this token can be used to
220              specify  the  location  in  the  filesystem of a copy of the CRL
221              file.  Note that Net-SNMP will not pull a CRL over http and this
222              must  be  a  file,  not  a  URL.  Additionally, OpenSSL does not
223              reload a CRL file when it has changed so  modifications  or  up‐
224              dates to the file will only be noticed upon a restart of the sn‐
225              mpd agent.
226
227
228       certSecName PRIORITY FINGERPRINT OPTIONS
229              OPTIONS can be one of <--sn SECNAME | --rfc822 | --dns | --ip  |
230              --cn | --any>.
231
232              The  certSecName  token  will  specify  how to map a certificate
233              field from the client's X.509 certificate to a SNMPv3  username.
234              Use the --sn SECNAME flag to directly specify a securityName for
235              a given certificate.  The other flags extract a particular  com‐
236              ponent  of  the  certificate  for  use as a snmpv3 securityName.
237              These fields are one of: A SubjectAltName containing  an  rfc822
238              value  (eg hardaker@net-snmp.org), A SubjectAltName containing a
239              dns  name  value  (eg  foo.net-snmp.org),  an  IP  address   (eg
240              192.0.2.1)  or  a  common  name  "Wes Hardaker".  The --any flag
241              specifies that any of the  subjecAltName  fields  may  be  used.
242              Make sure once a securityName has been selected that it is given
243              authorization via the VACM controls discussed later in this man‐
244              ual page.
245
246              See  the  http://www.net-snmp.org/wiki/index.php/Using_DTLS  web
247              page for more detailed instructions for setting up (D)TLS.
248
249       trustCert <specifier>
250              For X509 to properly verify a certificate, it should be  verifi‐
251              able up until a trust anchor for it.  This trust anchor is typi‐
252              cally a CA certificate but it could also be a  self-signed  cer‐
253              tificate.  The "trustCert" token should be used to load specific
254              trust anchors into the verification engine.
255
256       SNMP over (D)TLS requires the  use  of  the  Transport  Security  Model
257       (TSM), so read the section on the usage of the Transport Security Model
258       as well.  Make sure when you configure the VACM to  accept  connections
259       from (D)TLS that you use the "tsm" security model.  E.G.:
260
261       rwuser -s tsm hardaker@net-snmp.org
262
263   SNMPv3 over SSH Support
264       To  use SSH, you'll need to configure sshd to invoke the sshtosnmp pro‐
265       gram as well as configure the access control settings to  allow  access
266       through the tsm security model using the user name provided to snmpd by
267       the ssh transport.
268
269   SNMPv3 with the Transport Security Model (TSM)
270       The Transport Security Model [RFC5591] defines a SNMPv3 security system
271       for  use with "tunneled" security protocols like TLS, DTLS and SSH.  It
272       is a very simple security model that  simply  lets  properly  protected
273       packets  to  pass  through into the snmp application.  The transport is
274       required to pass a securityName to use to the TSM and the TSM  may  op‐
275       tionally prefix this with a transport string (see below).
276
277       tsmUseTransportPrefix (1|yes|true|0|no|false)
278              If  set  to  true,  the  TSM module will take every securityName
279              passed to it from the transports underneath and prefix it with a
280              string  that specifically identities the transport it came from.
281              This is useful to avoid  securityName  clashes  with  transports
282              that generate identical security names.  For example, if the ssh
283              security transport delivered the security name of "hardaker" for
284              a  SSH  connection and the TLS security transport also delivered
285              the security name of "hardaker" for a  TLS  connection  then  it
286              would  be  impossible to separate out these two users to provide
287              separate access control rights.  With the  tsmUseTransportPrefix
288              set to true, however, the securityNames would be prefixed appro‐
289              priately with one of: "tls:", "dtls:" or "ssh:".
290
291   SNMPv3 with the User-based Security Model (USM)
292       SNMPv3 was originally  defined  using  the  User-Based  Security  Model
293       (USM),  which contains a private list of users and keys specific to the
294       SNMPv3 protocol.  The operational community,  however,  declared  it  a
295       pain  to manipulate yet another database and would prefer to use exist‐
296       ing infrastructure.  To that end the  IETF  created  the  ISMS  working
297       group  to  battle  that  problem, and the ISMS working group decided to
298       tunnel SNMP over SSH and DTLS to make use existing user and authentica‐
299       tion infrastructures.
300
301   SNMPv3 USM Users
302       To use the USM based SNMPv3-specific users, you'll need to create them.
303       It is recommended you use the net-snmp-config command to do  this,  but
304       you  can  also do it by directly specifying createUser directives your‐
305       self instead:
306
307       createUser             [-e              ENGINEID]              username
308       (MD5|SHA|SHA-512|SHA-384|SHA-256|SHA-224)    authpassphrase   [DES|AES]
309       [privpassphrase]
310
311              MD5|SHA|SHA-512|SHA-384|SHA-256|SHA-224 are  the  authentication
312              types to use.  DES and AES are the privacy protocols to use.  If
313              the privacy passphrase is not specified, it is assumed to be the
314              same as the authentication passphrase.  Note that the users cre‐
315              ated will be useless unless they are also added to the VACM  ac‐
316              cess control tables described above.
317
318              SHA|SHA-512|SHA-384|SHA-256|SHA-224  authentication  and DES/AES
319              privacy require OpenSSL to be installed  and  the  agent  to  be
320              built  with  OpenSSL  support.   MD5  authentication may be used
321              without OpenSSL.
322
323              Warning: the minimum pass phrase length is 8 characters.
324
325              SNMPv3 users can be created at runtime using the snmpusm(1) com‐
326              mand.
327
328              Instead  of  figuring out how to use this directive and where to
329              put it  (see  below),  just  run  "net-snmp-config  --create-sn‐
330              mpv3-user"  instead,  which  will  add one of these lines to the
331              right place.
332
333              This directive should be placed into  the  /var/lib/net-snmp/sn‐
334              mpd.conf file instead of the other normal locations.  The reason
335              is that the information is read from the file and then the  line
336              is  removed  (eliminating the storage of the master password for
337              that user) and replaced with the key that is  derived  from  it.
338              This  key is a localized key, so that if it is stolen it can not
339              be used to access other agents.  If the password is stolen, how‐
340              ever, it can be.
341
342              If  you need to localize the user to a particular EngineID (this
343              is useful mostly in the similar snmptrapd.conf  file),  you  can
344              use  the  -e argument to specify an EngineID as a hex value (EG,
345              "0x01020304").
346
347              If you want to generate either your master or localized keys di‐
348              rectly, replace the given password with a hexstring (preceded by
349              a "0x") and precede the hex string by a -m or -l token  (respec‐
350              tively).  EGs:
351
352              [these keys are *not* secure but are easy to visually parse for
353              counting purposes.  Please generate random keys instead of using
354              these examples]
355
356              createUser myuser SHA -l 0x0001020304050607080900010203040506070809 AES -l 0x00010203040506070809000102030405
357              createUser myuser SHA -m 0x0001020304050607080900010203040506070809 AES -m 0x0001020304050607080900010203040506070809
358
359              Due  to the way localization happens, localized privacy keys are
360              expected to be the length needed by the algorithm (128 bits  for
361              all supported algorithms).  Master encryption keys, though, need
362              to be the length required by the  authentication  algorithm  not
363              the  length required by the encrypting algorithm (MD5: 16 bytes,
364              SHA: 20 bytes).
365

ACCESS CONTROL

367       snmpd supports the View-Based Access Control Model (VACM) as defined in
368       RFC  2575,  to control who can retrieve or update information.  To this
369       end, it recognizes various directives relating to access control.
370
371   Traditional Access Control
372       Most simple access control requirements can be specified using the  di‐
373       rectives rouser/rwuser (for SNMPv3) or rocommunity/rwcommunity (for SN‐
374       MPv1 or SNMPv2c).
375
376       rouser [-s SECMODEL] USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
377
378       rwuser [-s SECMODEL]  USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
379              specify an SNMPv3 user that will be allowed read-only  (GET  and
380              GETNEXT)  or  read-write  (GET,  GETNEXT and SET) access respec‐
381              tively.  By default, this will provide access to  the  full  OID
382              tree  for  authenticated  (including encrypted) SNMPv3 requests,
383              using the default  context.   An  alternative  minimum  security
384              level  can  be  specified using noauth (to allow unauthenticated
385              requests), or priv (to enforce  use  of  encryption).   The  OID
386              field  restricts  access  for that user to the subtree rooted at
387              the given OID, or the named view.  An optional context can  also
388              be  specified,  or "context*" to denote a context prefix.  If no
389              context field is specified (or the token "*" is used),  the  di‐
390              rective will match all possible contexts.
391
392              If  SECMODEL is specified then it will be the security model re‐
393              quired for that user (note that identical user names may come in
394              over  different  security models and will be appropriately sepa‐
395              rated via the access control settings).   The  default  security
396              model  is  "usm" and the other common security models are likely
397              "tsm" when using (D)TLS or SSH support and "ksm" if the Kerberos
398              support has been compiled in.
399
400       rocommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
401
402       rwcommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
403              specify  an  SNMPv1  or  SNMPv2c  community that will be allowed
404              read-only (GET and GETNEXT) or read-write (GET, GETNEXT and SET)
405              access  respectively.   By  default, this will provide access to
406              the full OID tree for such requests, regardless  of  where  they
407              were  sent from. The SOURCE token can be used to restrict access
408              to requests from the specified system(s) - see com2sec  for  the
409              full details.  The OID field restricts access for that community
410              to the subtree rooted at the given OID, or named view.  Contexts
411              are  typically  less  relevant to community-based SNMP versions,
412              but the same behaviour applies here.
413
414       rocommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
415
416       rwcommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
417              are directives relating to requests received using IPv6 (if  the
418              agent  supports  such transport domains).  The interpretation of
419              the SOURCE, OID, VIEW and CONTEXT tokens are exactly the same as
420              for the IPv4 versions.
421
422       In each case, only one directive should be specified for a given SNMPv3
423       user, or community string.  It  is  not  appropriate  to  specify  both
424       rouser  and  rwuser  directives  referring  to the same SNMPv3 user (or
425       equivalent community settings). The rwuser directive provides  all  the
426       access  of  rouser  (as  well as allowing SET support).  The same holds
427       true for the community-based directives.
428
429       More complex access requirements (such as access to two  or  more  dis‐
430       tinct OID subtrees, or different views for GET and SET requests) should
431       use one of the other access control mechanisms.  Note that  if  several
432       distinct  communities or SNMPv3 users need to be granted the same level
433       of access, it would also be more efficient to use the main VACM config‐
434       uration directives.
435
436   VACM Configuration
437       The  full flexibility of the VACM is available using four configuration
438       directives - com2sec, group, view and  access.   These  provide  direct
439       configuration of the underlying VACM tables.
440
441       com2sec  [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
442
443       com2sec6 [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
444              map  an  SNMPv1 or SNMPv2c community string to a security name -
445              either from a particular range of source addresses, or  globally
446              ("default").  A restricted source can either be a specific host‐
447              name (or address), or a subnet - represented  as  IP/MASK  (e.g.
448              10.10.10.0/255.255.255.0),  or  IP/BITS (e.g. 10.10.10.0/24), or
449              the IPv6 equivalents.  A restriction preceded by an  exclamation
450              mark  (!)  denies  access  from  that  address  or subnet, e.g.,
451              !10.10.10.0/24 denies requests from that sources in that subnet.
452              Deny  restrictions  must  be before permit.  E.g., the following
453              example  permits  access  from  all  of  10.0.0.0/8  except  for
454              10.10.10.0/24:
455                     com2sec sec1 !10.10.10.0/24 public
456                     com2sec sec1 10.0.0.0/8 public
457
458              Access from outside of 10.0.0.0/8 would still be denied.
459
460              The  same  community string can be specified in several separate
461              directives (presumably with different source  tokens),  and  the
462              first source/community combination that matches the incoming re‐
463              quest will be selected.  Various  source/community  combinations
464              can also map to the same security name.
465
466              If a CONTEXT is specified (using -Cn), the community string will
467              be mapped to a security name in the named SNMPv3 context. Other‐
468              wise the default context ("") will be used.
469
470       com2secunix [-Cn CONTEXT] SECNAME SOCKPATH COMMUNITY
471              is the Unix domain sockets version of com2sec.
472
473       group GROUP {v1|v2c|usm|tsm|ksm} SECNAME
474              maps  a  security  name (in the specified security model) into a
475              named group.  Several group  directives  can  specify  the  same
476              group name, allowing a single access setting to apply to several
477              users and/or community strings.
478
479              Note that groups must be set up for the two community-based mod‐
480              els separately - a single com2sec (or equivalent) directive will
481              typically be accompanied by two group directives.
482
483       view VNAME TYPE OID [MASK]
484              defines a named "view" - a subset of the overall OID tree.  This
485              is  most  commonly a single subtree, but several view directives
486              can be given with the same view name (VNAME), to build up a more
487              complex  collection  of  OIDs.   TYPE  is either included or ex‐
488              cluded, which can again define a more complex view (e.g  by  ex‐
489              cluding  certain  sensitive objects from an otherwise accessible
490              subtree).
491
492              MASK is a list of hex octets (optionally  separated  by  '.'  or
493              ':')  with  the  set bits indicating which subidentifiers in the
494              view OID to match against.  If not specified, this  defaults  to
495              matching  the OID exactly (all bits set), thus defining a simple
496              OID subtree.  So:
497                     view iso1 included .iso  0xf0
498                     view iso2 included .iso
499                     view iso3 included .iso.org.dod.mgmt  0xf0
500
501              would all define the  same  view,  covering  the  whole  of  the
502              'iso(1)' subtree (with the third example ignoring the subidenti‐
503              fiers not covered by the mask).
504
505              More usefully, the mask can be used to define a view covering  a
506              particular row (or rows) in a table, by matching against the ap‐
507              propriate table index value, but skipping the column  subidenti‐
508              fier:
509
510                     view ifRow4 included .1.3.6.1.2.1.2.2.1.0.4  0xff:a0
511
512              Note that a mask longer than 8 bits must use ':' to separate the
513              individual octets.
514
515       access GROUP CONTEXT {any|v1|v2c|usm|tsm|ksm} LEVEL  PREFX  READ  WRITE
516       NOTIFY
517              maps  from a group of users/communities (with a particular secu‐
518              rity model and minimum security level, and in  a  specific  con‐
519              text) to one of three views, depending on the request being pro‐
520              cessed.
521
522              LEVEL is one of noauth, auth, or priv.  PREFX specifies how CON‐
523              TEXT  should  be matched against the context of the incoming re‐
524              quest, either exact or prefix.  READ, WRITE and NOTIFY specifies
525              the  view to be used for GET*, SET and TRAP/INFORM requests (al‐
526              thought the NOTIFY view is not currently used).  For v1  or  v2c
527              access, LEVEL will need to be noauth.
528
529   Typed-View Configuration
530       The  final  group  of  directives  extend the VACM approach into a more
531       flexible mechanism, which can be applied to other  access  control  re‐
532       quirements.  Rather  than  the  fixed  three views of the standard VACM
533       mechanism, this can be used to configure various different view  types.
534       As far as the main SNMP agent is concerned, the two main view types are
535       read and write, corresponding to the READ and WRITE views of  the  main
536       access  directive.  See the 'snmptrapd.conf(5)' man page for discussion
537       of other view types.
538
539       authcommunity TYPES  COMMUNITY   [SOURCE [OID | -V VIEW [CONTEXT]]]
540              is an alternative  to  the  rocommunity/rwcommunity  directives.
541              TYPES will usually be read or read,write respectively.  The view
542              specification can either be an OID subtree  (as  before),  or  a
543              named view (defined using the view directive) for greater flexi‐
544              bility.  If this is omitted, then access will be allowed to  the
545              full  OID  tree.   If CONTEXT is specified, access is configured
546              within this SNMPv3 context.  Otherwise the default context  ("")
547              is used.
548
549       authuser   TYPES [-s MODEL] USER  [LEVEL [OID | -V VIEW [CONTEXT]]]
550              is  an  alternative to the rouser/rwuser directives.  The fields
551              TYPES, OID, VIEW and CONTEXT have the same meaning as for  auth‐
552              community.
553
554       authgroup  TYPES [-s MODEL] GROUP [LEVEL [OID | -V VIEW [CONTEXT]]]
555              is  a companion to the authuser directive, specifying access for
556              a particular group (defined using the group directive as usual).
557              Both  authuser and authgroup default to authenticated requests -
558              LEVEL can also be specified as noauth or priv to allow unauthen‐
559              ticated  requests, or require encryption respectively.  Both au‐
560              thuser and authgroup directives also default to configuring  ac‐
561              cess  for  SNMPv3/USM requests - use the '-s' flag to specify an
562              alternative security model (using the same values as for  access
563              above).
564
565       authaccess TYPES [-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]
566              also  configures  the  access for a particular group, specifying
567              the name and type of view to apply. The MODEL and  LEVEL  fields
568              are interpreted in the same way as for authgroup.  If CONTEXT is
569              specified, access is configured within this SNMPv3  context  (or
570              contexts  with  this prefix if the CONTEXT field ends with '*').
571              Otherwise the default context ("") is used.
572
573       setaccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES
574              is a direct equivalent to the original access  directive,  typi‐
575              cally  listing the view types as read or read,write as appropri‐
576              ate.  (or see 'snmptrapd.conf(5)' for other possibilities).  All
577              other fields have the same interpretation as with access.
578

SYSTEM INFORMATION

580       Most  of  the  information  reported by the Net-SNMP agent is retrieved
581       from the underlying system, or dynamically configured via SNMP SET  re‐
582       quests  (and retained from one run of the agent to the next).  However,
583       certain MIB objects  can  be  configured  or  controlled  via  the  sn‐
584       mpd.conf(5) file.
585
586   System Group
587       Most  of  the scalar objects in the 'system' group can be configured in
588       this way:
589
590       sysLocation STRING
591
592       sysContact STRING
593
594       sysName STRING
595              set the system location, system contact or system name (sysLoca‐
596              tion.0,  sysContact.0 and sysName.0) for the agent respectively.
597              Ordinarily these objects are writable  via  suitably  authorized
598              SNMP  SET requests.  However, specifying one of these directives
599              makes the corresponding object read-only, and attempts to SET it
600              will result in a notWritable error response.
601
602       sysServices NUMBER
603              sets  the value of the sysServices.0 object.  For a host system,
604              a good value is 72 (application + end-to-end layers).   If  this
605              directive  is  not specified, then no value will be reported for
606              the sysServices.0 object.
607
608       sysDescr STRING
609
610       sysObjectID OID
611              sets the system description or object ID  for  the  agent.   Al‐
612              though these MIB objects are not SNMP-writable, these directives
613              can be used by a network  administrator  to  configure  suitable
614              values for them.
615
616   Interfaces Group
617       interface NAME TYPE SPEED
618              can  be  used to provide appropriate type and speed settings for
619              interfaces where the agent fails to determine  this  information
620              correctly.  TYPE is a type value as given in the IANAifType-MIB,
621              and can be specified numerically or by name (assuming  this  MIB
622              is loaded).
623
624       interface_fadeout TIMEOUT
625              specifies, for how long the agent keeps entries in ifTable after
626              appropriate interfaces have been removed from system  (typically
627              various  ppp,  tap  or tun interfaces). Timeout value is in sec‐
628              onds. Default value is 300 (=5 minutes).
629
630       interface_replace_old yes
631              can be used to remove already existing entries in  ifTable  when
632              an interface with the same name appears on the system. E.g. when
633              ppp0 interface is removed, it is still listed in the  table  for
634              interface_fadeout  seconds.  This  option  ensures, that the old
635              ppp0 interface is  removed  even  before  the  interface_fadeout
636              timeour when new ppp0 (with different ifIndex) shows up.
637
638   Host Resources Group
639       This requires that the agent was built with support for the host module
640       (which is now included as part of the default  build  configuration  on
641       the major supported platforms).
642
643       ignoreDisk STRING
644              controls  which  disk  devices are scanned as part of populating
645              the hrDiskStorageTable (and hrDeviceTable).  The HostRes  imple‐
646              mentation code includes a list of disk device patterns appropri‐
647              ate for the current operating system, some of  which  may  cause
648              the  agent  to  block when trying to open the corresponding disk
649              devices.  This might lead to a timeout when  walking  these  ta‐
650              bles, possibly resulting in inconsistent behaviour.  This direc‐
651              tive can be used to specify particular devices (either individu‐
652              ally or wildcarded) that should not be checked.
653
654              Note:  Please  consult the source (host/hr_disk.c) and check for
655                     the Add_HR_Disk_entry calls relevant for a particular O/S
656                     to determine the list of devices that will be scanned.
657
658              The  pattern  can include one or more wildcard expressions.  See
659              snmpd.examples(5) for illustration of the wildcard syntax.
660
661       skipNFSInHostResources true
662              controls whether NFS and NFS-like file systems should be omitted
663              from the hrStorageTable (true or 1) or not (false or 0, which is
664              the default).  If the Net-SNMP agent gets  hung  on  NFS-mounted
665              filesystems, you can try setting this to '1'.
666
667       storageUseNFS [1|2]
668              controls how NFS and NFS-like file systems should be reported in
669              the hrStorageTable.  as 'Network Disks' (1) or 'Fixed Disks' (2)
670              Historically,  the Net-SNMP agent has reported such file systems
671              as 'Fixed Disks', and this is still the default behaviour.  Set‐
672              ting this directive to '1' reports such file systems as ´Network
673              Disks', as required by the Host Resources MIB.
674
675       realStorageUnits
676              controlls  how  the  agent   reports   hrStorageAllocationUnits,
677              hrStorageSize  and  hrStorageUsed  in  hrStorageTable.   For big
678              storage drives with small allocation units the  agent  re-calcu‐
679              lates  these values so they all fit Integer32 and hrStorageAllo‐
680              cationUnits x hrStorageSize gives real size of the storage.
681
682              Example:
683                     Linux xfs 16TB filesystem with 4096  bytes  large  blocks
684                     will  be reported as  hrStorageAllocationUnits = 8192 and
685                     hrStorageSize = 2147483647, so 8192  x  2147483647  gives
686                     real size of the filesystem (=16 TB).
687
688              Setting this directive to '1' turns off this calculation and the
689              agent reports real hrStorageAllocationUnits, but it might report
690              wrong  hrStorageSize  for big drives because the value won't fit
691              into Integer32. In this case, hrStorageAllocationUnits x hrStor‐
692              ageSize won't give real size of the storage.
693
694   Process Monitoring
695       The  hrSWRun group of the Host Resources MIB provides information about
696       individual processes running on the local system.  The prTable  of  the
697       UCD-SNMP-MIB  complements this by reporting on selected services (which
698       may involve multiple processes).  This  requires  that  the  agent  was
699       built  with  support for the ucd-snmp/proc module (which is included as
700       part of the default build configuration).
701
702       proc NAME [MAX [MIN]]
703              monitors the number of processes called  NAME  (as  reported  by
704              "/usr/bin/ps -e") running on the local system.
705
706              If  the  number  of  NAMEd processes is less than MIN or greater
707              than MAX, then the corresponding prErrorFlag  instance  will  be
708              set  to  1,  and a suitable description message reported via the
709              prErrMessage instance.
710
711              Note:  This situation will not automatically trigger a  trap  to
712                     report  the  problem  -  see the DisMan Event MIB section
713                     later.
714
715              If neither MAX nor MIN are specified, they will default  to  in‐
716              finity  and  1  respectively  ("at  least one").  If only MAX is
717              specified, MIN will default to 0 ("no more than MAX").   If  MAX
718              is 0 (and MIN is not), this indicates infinity ("at least MIN").
719              If both MAX and MIN are 0, this indicates a process that  should
720              not be running.
721
722       procfix NAME PROG ARGS
723              registers a command that can be run to fix errors with the given
724              process NAME.  This will be invoked when the corresponding  prE‐
725              rrFix instance is set to 1.
726
727              Note:  This command will not be invoked automatically.
728
729              The  procfix directive must be specified after the matching proc
730              directive, and cannot be used on its own.
731
732       If no proc directives are defined, then walking the prTable  will  fail
733       (noSuchObject).
734
735   Disk Usage Monitoring
736       This   requires   that  the  agent  was  built  with  support  for  the
737       ucd-snmp/disk module (which is included as part of  the  default  build
738       configuration).
739
740       disk PATH [ MINSPACE | MINPERCENT% ]
741              monitors  the  disk  mounted  at  PATH for available disk space.
742              Disks mounted after the agent has started will not be monitored,
743              unless includeAllDisks option is specified.
744
745              The  minimum  threshold can either be specified in kB (MINSPACE)
746              or as a percentage of the total disk  (MINPERCENT%  with  a  '%'
747              character),  defaulting  to  100kB if neither are specified.  If
748              the free disk space falls below this threshold, then the  corre‐
749              sponding  dskErrorFlag instance will be set to 1, and a suitable
750              description message reported via the dskErrorMsg instance.
751
752              Note:  This situation will not automatically trigger a  trap  to
753                     report  the  problem  -  see the DisMan Event MIB section
754                     later.
755
756       includeAllDisks MINPERCENT%
757              configures monitoring of all disks found on  the  system,  using
758              the  specified  (percentage) threshold.  The dskTable is dynami‐
759              cally updated, unmounted disks  disappear  from  the  table  and
760              newly  mounted  disks are added to the table.  The threshold for
761              individual disks can be adjusted using suitable disk  directives
762              (which  can  come either before or after the includeAllDisks di‐
763              rective).
764
765              Note:  Whether disk  directives  appears  before  or  after  in‐
766                     cludeAllDisks may affect the indexing of the dskTable.
767
768              Only  one  includeAllDisks  directive  should be specified - any
769              subsequent copies will be ignored.
770
771              The list of mounted  disks  will  be  determined  from  HOST-RE‐
772              SOURCES-MIB::hrFSTable.
773
774       If  neither  any  disk  directives or includeAllDisks are defined, then
775       walking the dskTable will fail (noSuchObject).
776
777   Disk I/O Monitoring
778       This  requires  that  the  agent  was  built  with  support   for   the
779       ucd-snmp/diskio  module  (which  is not included as part of the default
780       build configuration).
781
782       By default, all block devices known to the  operating  system  are  in‐
783       cluded  in  the diskIOTable. On platforms other than Linux, this module
784       has no configuration directives.
785
786       On Linux systems, it is possible to exclude several  classes  of  block
787       devices  from  the  diskIOTable  in order to avoid cluttering the table
788       with useless zero statistics for pseudo-devices that often are  not  in
789       use but are configured by default to exist in most recent Linux distri‐
790       butions.
791
792       diskio_exclude_fd yes
793              Excludes all Linux floppy disk block devices, whose names  start
794              with "fd", e.g. "fd0"
795
796       diskio_exclude_loop yes
797              Excludes  all  Linux  loopback  block devices, whose names start
798              with "loop", e.g. "loop0"
799
800       diskio_exclude_ram yes
801              Excludes all LInux ramdisk block devices, whose names start with
802              "ram", e.g.  "ram0"
803
804       On  Linux  systems,  it  is also possible to report only explicitly ac‐
805       cepted devices. It may take  significant  amount  of  time  to  process
806       diskIOTable data on systems with tens of thousands of block devices and
807       accept only the important ones avoids large CPU consumption.
808
809       diskio <device>
810              Enables acceptlist of devices and adds the  device  to  the  ac‐
811              ceptlist. Only explicitly acceptlisted devices will be reported.
812              This option may be used multiple times.
813
814   System Load Monitoring
815       This requires that the agent was built  with  support  for  either  the
816       ucd-snmp/loadave  module  or  the  ucd-snmp/memory  module respectively
817       (both of which are included as part of  the  default  build  configura‐
818       tion).
819
820       load MAX1 [MAX5 [MAX15]]
821              monitors  the  load  average  of  the  local  system, specifying
822              thresholds for the 1-minute, 5-minute  and  15-minute  averages.
823              If  any of these loads exceed the associated maximum value, then
824              the corresponding laErrorFlag instance will be set to 1,  and  a
825              suitable  description  message reported via the laErrMessage in‐
826              stance.
827
828              Note:  This situation will not automatically trigger a  trap  to
829                     report  the  problem  -  see the DisMan Event MIB section
830                     later.
831
832              If the MAX15 threshold is omitted, it will default to  the  MAX5
833              value.  If both MAX5 and MAX15 are omitted, they will default to
834              the MAX1 value.  If this directive is not specified,  all  three
835              thresholds will default to a value of DEFMAXLOADAVE.
836
837              If  a  threshold  value of 0 is given, the agent will not report
838              errors via the relevant laErrorFlag or  laErrMessage  instances,
839              regardless of the current load.
840
841       Unlike  the  proc  and disk directives, walking the walking the laTable
842       will succeed (assuming the ucd-snmp/loadave module was configured  into
843       the agent), even if the load directive is not present.
844
845       swap MIN
846              monitors the amount of swap space available on the local system.
847              If this falls below the specified threshold (MIN kB),  then  the
848              memErrorSwap object will be set to 1, and a suitable description
849              message reported via memSwapErrorMsg.
850
851              Note:  This situation will not automatically trigger a  trap  to
852                     report  the  problem  -  see the DisMan Event MIB section
853                     later.
854       If this directive is not specified, the default threshold is 16 MB.
855
856   Log File Monitoring
857       This requires that the agent was built  with  support  for  either  the
858       ucd-snmp/file  or ucd-snmp/logmatch modules respectively (both of which
859       are included as part of the default build configuration).
860
861       file FILE [MAXSIZE]
862              monitors the size of the specified file (in kB).  If MAXSIZE  is
863              specified, and the size of the file exceeds this threshold, then
864              the corresponding fileErrorFlag instance will be set to 1, and a
865              suitable  description  message reported via the fileErrorMsg in‐
866              stance.
867
868              Note:  This situation will not automatically trigger a  trap  to
869                     report  the  problem  -  see the DisMan Event MIB section
870                     later.
871
872              Note: A maximum of 20 files can be monitored.
873
874              Note: If no  file  directives  are  defined,  then  walking  the
875              fileTable will fail (noSuchObject).
876
877       logmatch NAME FILE CYCLETIME REGEX
878              monitors the specified file for occurances of the specified pat‐
879              tern REGEX. The file position is stored internally so the entire
880              file  is  only  read  initially, every subsequent pass will only
881              read the new lines added to the file since the last read.
882
883              NAME   name of the logmatch instance (will appear  as  logMatch‐
884                     Name under logMatch/logMatchTable/logMatchEntry/logMatch‐
885                     Name in the ucd-snmp MIB tree)
886
887              FILE   absolute path to the logfile to be monitored.  Note  that
888                     this  path  can contain date/time directives (like in the
889                     UNIX 'date' command). See the manual page for  'strftime'
890                     for the various directives accepted.
891
892              CYCLETIME
893                     time interval for each logfile read and internal variable
894                     update in seconds.  Note: an SNMPGET* operation will also
895                     trigger an immediate logfile read and variable update.
896
897              REGEX  the  regular  expression to be used. Note: DO NOT enclose
898                     the regular expression in quotes even if there are spaces
899                     in  the expression as the quotes will also become part of
900                     the pattern to be matched!
901
902              Example:
903
904                     logmatch      apache-GETs      /usr/local/apache/logs/ac‐
905                     cess.log-%Y-%m-%d 60 GET.*HTTP.*
906
907                     This  logmatch  instance  is  named  'apache-GETs',  uses
908                     'GET.*HTTP.*' as its regular expression and it will moni‐
909                     tor  the  file  named  (assuming  today is May 6th 2009):
910                     '/usr/local/apache/logs/access.log-2009-05-06',  tomorrow
911                     it  will look for 'access.log-2009-05-07'. The logfile is
912                     read every 60 seconds.
913
914              Note: A maximum of 250 logmatch directives can be specified.
915
916              Note: If no logmatch directives are defined,  then  walking  the
917              logMatchTable will fail (noSuchObject).
918

ACTIVE MONITORING

920       The  usual  behaviour of an SNMP agent is to wait for incoming SNMP re‐
921       quests and respond to them - if no requests are received, an agent will
922       typically  not initiate any actions. This section describes various di‐
923       rectives that can configure snmpd to take a more active role.
924
925   Notification Handling
926       trapcommunity STRING
927              defines the default community string to  be  used  when  sending
928              traps.   Note that this directive must be used prior to any com‐
929              munity-based trap destination directives that need to use it.
930
931       trapsink [-profile p] [-name n]  [-tag  t]  [-s  src]  HOST  [COMMUNITY
932       [PORT]]
933
934       trap2sink  [-profile  p]  [-name  n]  [-tag t] [-s src] HOST [COMMUNITY
935       [PORT]]
936
937       informsink [-profile p] [-name n] [-tag t]  [-s  src]  HOST  [COMMUNITY
938       [PORT]]
939              define  the  address  of  a notification receiver that should be
940              sent SNMPv1 TRAPs, SNMPv2c TRAP2s, or  SNMPv2  INFORM  notifica‐
941              tions  respectively.  See the section LISTENING ADDRESSES in the
942              snmpd(8) manual page for more information about  the  format  of
943              listening  addresses.   If  COMMUNITY is not specified, the most
944              recent trapcommunity string will be used.
945
946              If the transport address does not include an explicit port spec‐
947              ification,  then  PORT  will be used.  If this is not specified,
948              the well known SNMP trap port (162) will be used.
949
950              Note:  This mechanism is being  deprecated,  and  the  listening
951                     port  should be specified via the transport specification
952                     HOST instead.
953
954              The optional name and tag parameters specifies the name  or  tag
955              that  will  be used for SNMP-NOTIFICATION-MIB table entries. The
956              profile specifies which notification filter profile  entry  will
957              be used for filtering outgoing notifications. (See notification‐
958              Filter)
959
960              The optional src parameter specifies  the  source  address  that
961              will  be  used when sending the trap packet to this sink.  It is
962              specified as a <transport-address>, using the  same  <transport-
963              specifier>  as  the destination HOST.  See the section LISTENING
964              ADDRESSES in the snmpd(8) manual page for more information about
965              the format.
966
967              If  several  sink  directives  are specified, multiple copies of
968              each notification (in the appropriate formats)  will  be  gener‐
969              ated.
970
971              Note:  It is not normally appropriate to list two (or all three)
972                     sink directives with the same destination.
973
974       trapsess [-profile p] [-name n] [-tag t] [-s src] [SNMPCMD_ARGS] HOST
975              provides a more generic mechanism for defining notification des‐
976              tinations.   SNMPCMD_ARGS should be the command-line options re‐
977              quired for an equivalent snmptrap  (or  snmpinform)  command  to
978              send the desired notification.  The option -Ci can be used (with
979              -v2c or -v3) to generate an INFORM notification rather  than  an
980              unacknowledged TRAP.
981
982              The  optional  name and tag parameters specifies the name or tag
983              that will be used for SNMP-NOTIFICATION-MIB table  entries.  The
984              profile  specifies  which notification filter profile entry will
985              be used for filtering outgoing notifications. (See notification‐
986              Filter)
987
988              This  is  the appropriate directive for defining SNMPv3 trap re‐
989              ceivers.   See  http://www.net-snmp.org/tutorial/tutorial-5/com
990              mands/snmptrap-v3.html for more information about SNMPv3 notifi‐
991              cation behaviour.
992
993       notificationFilter NAME OID MASK TYPE
994              specifies a SNMP-NOTIFICATION-MIB notification  filter  profile,
995              which  may be used to filter traps. TYPE must be included or ex‐
996              cluded, Some examples:
997
998                     notificationFilter all_ok .1.3 0x00 included
999                     notificationFilter no_coldstart .1.3 0x00 included
1000                     notificationFilter no_coldstart .1.3.6.1.6.3.1.1.5.1 0x00 excluded
1001
1002                     trapsink -profile no_coldstart 192.168.1.3:3162 secret3
1003
1004       authtrapenable {1|2}
1005              determines whether to generate authentication failure traps (en‐
1006              abled(1))  or  not  (disabled(2) - the default).  Ordinarily the
1007              corresponding  MIB  object  (snmpEnableAuthenTraps.0)  is  read-
1008              write,  but  specifying  this  directive makes this object read-
1009              only, and attempts to set the value via SET requests will result
1010              in a notWritable error response.
1011
1012       v1trapaddress HOST
1013              defines  the agent address, which is inserted into SNMPv1 TRAPs.
1014              Arbitrary local IPv4 address is chosen if  this  option  is  om‐
1015              mited.  This  option  is useful mainly when the agent is visible
1016              from outside world by specific address only  (e.g.   because  of
1017              network address translation or firewall).
1018
1019   DisMan Event MIB
1020       The  previous directives can be used to configure where traps should be
1021       sent, but are not concerned with when to send such traps (or what traps
1022       should  be generated).  This is the domain of the Event MIB - developed
1023       by the Distributed Management (DisMan) working group of the IETF.
1024
1025       This requires that the agent  was  built  with  support  for  the  dis‐
1026       man/event  module  (which  is now included as part of the default build
1027       configuration for the most recent distribution).
1028
1029              Note:  The behaviour of the  latest  implementation  differs  in
1030                     some  minor respects from the previous code - nothing too
1031                     significant, but existing scripts may possibly need  some
1032                     minor adjustments.
1033
1034       iquerySecName NAME
1035
1036       agentSecName NAME
1037              specifies  the  default  SNMPv3 username, to be used when making
1038              internal queries to retrieve any necessary  information  (either
1039              for evaluating the monitored expression, or building a notifica‐
1040              tion payload).  These internal queries always use  SNMPv3,  even
1041              if normal querying of the agent is done using SNMPv1 or SNMPv2c.
1042
1043              Note that this user must also be explicitly created (createUser)
1044              and given appropriate access rights (e.g. rouser).  This  direc‐
1045              tive is purely concerned with defining which user should be used
1046              - not with actually setting this user up.
1047
1048       monitor [OPTIONS] NAME EXPRESSION
1049              defines a MIB object to monitor.  If  the  EXPRESSION  condition
1050              holds  (see  below),  then  this  will trigger the corresponding
1051              event, and either send a notification or apply a SET  assignment
1052              (or  both).   Note  that  the event will only be triggered once,
1053              when the expression first matches.  This monitor entry will  not
1054              fire  again  until  the monitored condition first becomes false,
1055              and then matches again.  NAME is an administrative name for this
1056              expression,  and  is  used for indexing the mteTriggerTable (and
1057              related tables). Each monitor line must have a unique NAME. Mon‐
1058              itor  lines  with a duplicate name are discarded and cause snmpd
1059              to log a duplicate index complaint.  Note also that  such  moni‐
1060              tors use an internal SNMPv3 request to retrieve the values being
1061              monitored (even if normal agent queries typically use SNMPv1  or
1062              SNMPv2c).  See the iquerySecName token described above.
1063
1064       EXPRESSION
1065              There  are  three  types  of monitor expression supported by the
1066              Event MIB - existence, boolean and threshold tests.
1067
1068              OID | ! OID | != OID
1069                     defines an existence(0) monitor test.  A bare OID  speci‐
1070                     fies a present(0) test, which will fire when (an instance
1071                     of) the monitored OID is created.  An expression  of  the
1072                     form  !  OID specifies an absent(1) test, which will fire
1073                     when the monitored OID is delected.  An expression of the
1074                     form  != OID specifies a changed(2) test, which will fire
1075                     whenever the monitored value(s) change.  Note that  there
1076                     must be whitespace before the OID token.
1077
1078              OID OP VALUE
1079                     defines  a  boolean(1) monitor test.  OP should be one of
1080                     the defined comparison operators (!=, ==, <, <=,  >,  >=)
1081                     and  VALUE should be an integer value to compare against.
1082                     Note that there must be whitespace around the  OP  token.
1083                     A  comparison  such  as  OID !=0 will not be handled cor‐
1084                     rectly.
1085
1086              OID MIN MAX [DMIN DMAX]
1087                     defines a threshold(2) monitor test.  MIN and MAX are in‐
1088                     teger  values, specifying lower and upper thresholds.  If
1089                     the value of the monitored  OID  falls  below  the  lower
1090                     threshold (MIN) or rises above the upper threshold (MAX),
1091                     then the monitor entry  will  trigger  the  corresponding
1092                     event.
1093
1094                     Note  that  the  rising  threshold event will only be re-
1095                     armed when the monitored  value  falls  below  the  lower
1096                     threshold  (MIN).  Similarly, the falling threshold event
1097                     will be re-armed by the upper threshold (MAX).
1098
1099                     The optional parameters DMIN and DMAX configure a pair of
1100                     similar  threshold tests, but working with the delta dif‐
1101                     ferences between successive sample values.
1102
1103       OPTIONS
1104              There are various options to control the behaviour of the  moni‐
1105              tored expression.  These include:
1106
1107              -D     indicates  that  the expression should be evaluated using
1108                     delta differences between sample values (rather than  the
1109                     values themselves).
1110
1111              -d OID
1112
1113              -di OID
1114                     specifies  a  discontinuity  marker  for validating delta
1115                     differences.  A -di object instance will be used  exactly
1116                     as  given.  A -d object will have the instance subidenti‐
1117                     fiers from the corresponding (wildcarded) expression  ob‐
1118                     ject  appended.   If the -I flag is specified, then there
1119                     is no difference between these two options.
1120
1121                     This option also implies -D.
1122
1123              -e EVENT
1124                     specifies the event to be invoked when this monitor entry
1125                     is  triggered.   If this option is not given, the monitor
1126                     entry will generate one of the standard notifications de‐
1127                     fined in the DISMAN-EVENT-MIB.
1128
1129              -I     indicates that the monitored expression should be applied
1130                     to the specified OID as a single instance.   By  default,
1131                     the  OID  will be treated as a wildcarded object, and the
1132                     monitor expanded to cover all matching instances.
1133
1134              -i OID
1135
1136              -o OID define additional varbinds to be added to  the  notifica‐
1137                     tion  payload  when  this  monitor  trigger fires.  For a
1138                     wildcarded expression, the suffix of the matched instance
1139                     will  be added to any OIDs specified using -o, while OIDs
1140                     specified using -i will be treated  as  exact  instances.
1141                     If  the -I flag is specified, then there is no difference
1142                     between these two options.
1143
1144                     See strictDisman for details of the ordering of notifica‐
1145                     tion payloads.
1146
1147              -r FREQUENCY
1148                     monitors the given expression every FREQUENCY, where FRE‐
1149                     QUENCY is in seconds or optionally suffixed by one  of  s
1150                     (for  seconds),  m  (for  minutes), h (for hours), d (for
1151                     days), or w (for weeks).  By default, the expression will
1152                     be evaluated every 600s (10 minutes).
1153
1154              -S     indicates that the monitor expression should not be eval‐
1155                     uated when the agent first starts up.  The first  evalua‐
1156                     tion  will be done once the first repeat interval has ex‐
1157                     pired.
1158
1159              -s     indicates that the monitor expression should be evaluated
1160                     when  the agent first starts up.  This is the default be‐
1161                     haviour.
1162
1163                     Note:  Notifications triggered by this initial evaluation
1164                            will be sent before the coldStart trap.
1165
1166              -u SECNAME
1167                     specifies  a  security name to use for scanning the local
1168                     host, instead of the default iquerySecName.  Once  again,
1169                     this  user  must be explicitly created and given suitable
1170                     access rights.
1171
1172       notificationEvent ENAME NOTIFICATION [-m] [-i OID | -o OID ]*
1173              defines a notification event named ENAME.  This can be triggered
1174              from  a  given  monitor  entry by specifying the option -e ENAME
1175              (see above).  NOTIFICATION should be the OID  of  the  NOTIFICA‐
1176              TION-TYPE definition for the notification to be generated.
1177
1178              If the -m option is given, the notification payload will include
1179              the standard varbinds as specified in the OBJECTS clause of  the
1180              notification  MIB  definition.   This option must come after the
1181              NOTIFICATION OID (and the relevant MIB file  must  be  available
1182              and  loaded  by  the  agent).  Otherwise, these varbinds must be
1183              listed explicitly (either here or in the  corresponding  monitor
1184              directive).
1185
1186              The  -i OID and -o OID options specify additional varbinds to be
1187              appended to the notification payload, after the  standard  list.
1188              If  the monitor entry that triggered this event involved a wild‐
1189              carded expression, the suffix of the matched  instance  will  be
1190              added to any OIDs specified using -o, while OIDs specified using
1191              -i will be treated as exact instances.  If the -I flag was spec‐
1192              ified  to the monitor directive, then there is no difference be‐
1193              tween these two options.
1194
1195       setEvent ENAME [-I] OID = VALUE
1196              defines a set event named ENAME, assigning the  (integer)  VALUE
1197              to  the specified OID.  This can be triggered from a given moni‐
1198              tor entry by specifying the option -e ENAME (see above).
1199
1200              If the monitor entry that triggered this event involved a  wild‐
1201              carded  expression, the suffix of the matched instance will nor‐
1202              mally be added to the OID.  If the -I flag was specified to  ei‐
1203              ther  of  the  monitor or setEvent directives, the specified OID
1204              will be regarded as an exact single instance.
1205
1206       strictDisman yes
1207              The definition of SNMP notifications states  that  the  varbinds
1208              defined  in  the  OBJECT  clause should come first (in the order
1209              specified), followed by any "extra" varbinds that the  notifica‐
1210              tion generator feels might be useful.  The most natural approach
1211              would be to associate these mandatory varbinds with the  notifi‐
1212              cationEvent  entry,  and append any varbinds associated with the
1213              monitor entry that triggered the notification to the end of this
1214              list.   This  is the default behaviour of the Net-SNMP Event MIB
1215              implementation.
1216
1217              Unfortunately, the  DisMan  Event  MIB  specifications  actually
1218              state  that the trigger-related varbinds should come first, fol‐
1219              lowed by the event-related ones.  This directive can be used  to
1220              restore this strictly-correct (but inappropriate) behaviour.
1221
1222              Note:  Strict  DisMan  ordering may result in generating invalid
1223                     notifications payload lists if the  notificationEvent  -n
1224                     flag is used together with monitor -o (or -i) varbind op‐
1225                     tions.
1226
1227              If no monitor entries specify payload varbinds, then the setting
1228              of this directive is irrelevant.
1229
1230       linkUpDownNotifications yes
1231              will  configure  the Event MIB tables to monitor the ifTable for
1232              network interfaces being taken up  or  down,  and  triggering  a
1233              linkUp or linkDown notification as appropriate.
1234
1235              This is exactly equivalent to the configuration:
1236
1237                     notificationEvent  linkUpTrap    linkUp   ifIndex ifAdminStatus ifOperStatus
1238                     notificationEvent  linkDownTrap  linkDown ifIndex ifAdminStatus ifOperStatus
1239
1240                     monitor  -r 60 -e linkUpTrap   "Generate linkUp" ifOperStatus != 2
1241                     monitor  -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
1242
1243       defaultMonitors yes
1244              will  configure  the  Event  MIB  tables  to monitor the various
1245              UCD-SNMP-MIB tables for problems (as indicated by the  appropri‐
1246              ate xxErrFlag column objects).
1247
1248              This is exactly equivalent to the configuration:
1249
1250                     monitor   -o prNames -o prErrMessage "process table" prErrorFlag != 0
1251                     monitor   -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
1252                     monitor   -o extNames -o extOutput "extTable" extResult != 0
1253                     monitor   -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
1254                     monitor   -o laNames -o laErrMessage  "laTable" laErrorFlag != 0
1255                     monitor   -o fileName -o fileErrorMsg  "fileTable" fileErrorFlag != 0
1256
1257       In  both these latter cases, the snmpd.conf must also contain a iquery‐
1258       SecName directive, together with a corresponding createUser  entry  and
1259       suitable access control configuration.
1260
1261   DisMan Schedule MIB
1262       The  DisMan working group also produced a mechanism for scheduling par‐
1263       ticular actions (a specified SET assignment) at given times.  This  re‐
1264       quires  that  the  agent was built with support for the disman/schedule
1265       module (which is included as part of the  default  build  configuration
1266       for the most recent distribution).
1267
1268       There are three ways of specifying the scheduled action:
1269
1270       repeat FREQUENCY OID = VALUE
1271              configures  a  SET  assignment of the (integer) VALUE to the MIB
1272              instance OID, to be run every FREQUENCY seconds, where FREQUENCY
1273              is  in seconds or optionally suffixed by one of s (for seconds),
1274              m (for minutes), h (for hours), d (for days), or w (for weeks).
1275
1276       cron MINUTE HOUR DAY MONTH WEEKDAY  OID = VALUE
1277              configures a SET assignment of the (integer) VALUE  to  the  MIB
1278              instance  OID,  to  be  run at the times specified by the fields
1279              MINUTE to WEEKDAY.  These follow the same pattern as the equiva‐
1280              lent crontab(5) fields.
1281
1282              Note:  These  fields  should be specified as a (comma-separated)
1283                     list of numeric values.  Named values for the  MONTH  and
1284                     WEEKDAY  fields  are not supported, and neither are value
1285                     ranges. A wildcard match can be specified as '*'.
1286
1287              The DAY field can also accept negative values, to indicate  days
1288              counting backwards from the end of the month.
1289
1290       at MINUTE HOUR DAY MONTH WEEKDAY  OID = VALUE
1291              configures  a  one-shot  SET  assignment, to be run at the first
1292              matching time as specified by the fields MINUTE to WEEKDAY.  The
1293              interpretation  of  these  fields is exactly the same as for the
1294              cron directive.
1295
1296   Data Delivery via Notfiications
1297       Note: this functionality is only available if the  deliver/deliverByNo‐
1298       tify mib module was complied in to the agent
1299
1300       In  some  situations  it  may be advantageous to deliver SNMP data over
1301       SNMP Notifications (TRAPs and INFORMs) rather than the typical  process
1302       of  having  the  manager issue requests for the data (via GETs and GET‐
1303       NEXTs).  Reasons for doing this are  numerous,  but  frequently  corner
1304       cases.   The  most common reason for wanting this behaviour might be to
1305       monitor devices that reside behind NATs or Firewalls that  prevent  in‐
1306       coming SNMP traffic.
1307
1308       It should be noted that although most management software is capable of
1309       logging notifications, very little (if any)  management  software  will
1310       updated  their "knowledge database" based on the contents of SNMP noti‐
1311       fications.  IE, it won't (for example)  update  the  interface  traffic
1312       counter  history  that  is used to produce graphs.  Most larger network
1313       management packages have a separate database for storing data  received
1314       via  SNMP requests (GETs and GETNEXTs) vs those received from notifica‐
1315       tions.  Researching the capabilities of your management  station  soft‐
1316       ware  is  required  before  assuming this functionality will solve your
1317       data delivery requirements.
1318
1319       Notifications generated via this mechanism will be sent to the standard
1320       set  of  configured  notification  targets.  See the "Notification Han‐
1321       dling" section of this document for further information.
1322
1323       deliverByNotify [-p] [-m] [-s MAXSIZE] FREQUENCY OID
1324              This directive tells the SNMP agent to self-walk the  OID,  col‐
1325              lect all the data and send it out every FREQUENCY seconds, where
1326              FREQUENCY is in seconds or optionally suffixed by one of s  (for
1327              seconds),  m  (for  minutes),  h (for hours), d (for days), or w
1328              (for weeks).  By default scalars are included in  the  notifica‐
1329              tion  that  specify  the how often the notification will be sent
1330              (unless the -p option is specified) and which message number  of
1331              how  many  messages  a  particular notification is (unless -m is
1332              specified).  To break the notifications into  manageable  packet
1333              sizes, use the -s flag to specify the approximate maximum number
1334              of bytes that a notification message should be limited  to.   If
1335              more than MAXSIZE of bytes is needed then multiple notifications
1336              will be sent to deliver the data.  Note  that  the  calculations
1337              for ensuring the maximum size is met are approximations and thus
1338              it can be absolutely guaranteed they'll be under that  size,  so
1339              leave a padding buffer if it is critical that you avoid fragmen‐
1340              tation.  A value of -1 indicates force everything into a  single
1341              message no matter how big it is.
1342
1343              Example  usage:  the  following will deliver the contents of the
1344              ifTable once an hour and the contents of the system  group  once
1345              every 2 hours:
1346
1347              deliverByNotify 3600 ifTable
1348              deliverByNotify 7200 system
1349
1350       deliverByNotifyMaxPacketSize SIZEINBYTES
1351              Sets  the  default  notification  size  limit  (see  the -s flag
1352              above).
1353
1354       deliverByNotifyOid OID
1355
1356       deliverByNotifyFrequencyOid OID
1357
1358       deliverByNotifyMessageNumberOid OID
1359
1360       deliverByNotifyMaxMessageNumberOid OID
1361              These set the data OID that the notification will be sent under,
1362              the  scalar OID, the message number OID, and the maximum message
1363              number OID.  These default  to  objects  in  the  NET-SNMP-PERI‐
1364              ODIC-NOTIFY-MIB.
1365

EXTENDING AGENT FUNCTIONALITY

1367       One  of the first distinguishing features of the original UCD suite was
1368       the ability to extend the functionality of the agent - not just by  re‐
1369       compiling  with  code  for new MIB modules, but also by configuring the
1370       running agent to report additional information. There are a  number  of
1371       techniques to support this, including:
1372
1373       •      running external commands (exec, extend, pass)
1374
1375       •      loading new code dynamically (embedded perl, dlmod)
1376
1377       •      communicating with other agents (proxy, SMUX, AgentX)
1378
1379   Arbitrary Extension Commands
1380       The  earliest extension mechanism was the ability to run arbitrary com‐
1381       mands or shell scripts. Such commands do not need to be aware  of  SNMP
1382       operations, or conform to any particular behaviour - the MIB structures
1383       are designed to accommodate any form of command output.   Use  of  this
1384       mechanism  requires  that  the  agent  was  built  with support for the
1385       ucd-snmp/extensible and/or agent/extend modules  (which  are  both  in‐
1386       cluded as part of the default build configuration).
1387
1388       exec [MIBOID] NAME PROG ARGS
1389
1390       sh [MIBOID] NAME PROG ARGS
1391              invoke  the  named  PROG with arguments of ARGS.  By default the
1392              exit status and first line of output from the  command  will  be
1393              reported via the extTable, discarding any additional output.
1394
1395              Note:  Entries  in  this table appear in the order they are read
1396                     from the configuration file.  This means that adding  new
1397                     exec (or sh) directives and restarting the agent, may af‐
1398                     fect the indexing of other entries.
1399
1400              The PROG argument for exec directives must be a full path  to  a
1401              real  binary,  as it is executed via the exec() system call.  To
1402              invoke a shell script, use the sh directive instead.
1403
1404              If MIBOID is specified, then the results will be rooted at  this
1405              point  in  the  OID  tree,  returning  the exit statement as MI‐
1406              BOID.100.0 and the entire command output in a pseudo-table based
1407              at MIBNUM.101 - with one 'row' for each line of output.
1408
1409              Note:  The  layout  of  this  "relocatable" form of exec (or sh)
1410                     output does not strictly  form  a  valid  MIB  structure.
1411                     This  mechanism  is being deprecated - please see the ex‐
1412                     tend directive (described below) instead.
1413
1414              The agent does not cache the exit status or output of  the  exe‐
1415              cuted program.
1416
1417       execfix NAME PROG ARGS
1418              registers a command that can be invoked on demand - typically to
1419              respond to or fix errors with the corresponding exec or  sh  en‐
1420              try.  When the extErrFix instance for a given NAMEd entry is set
1421              to the integer value of 1, this command will be called.
1422
1423              Note:  This directive can only be used  in  combination  with  a
1424                     corresponding exec or sh directive, which must be defined
1425                     first.  Attempting to define an unaccompanied execfix di‐
1426                     rective will fail.
1427
1428       exec  and sh extensions can only be configured via the snmpd.conf file.
1429       They cannot be set up via SNMP SET requests.
1430
1431       extend [-cacheTime TIME] [-execType TYPE] [MIBOID] NAME PROG ARGS
1432              works in a similar manner to the exec directive, but with a num‐
1433              ber  of  improvements.  The MIB tables (nsExtendConfigTable etc)
1434              are indexed by the NAME token, so are unaffected by the order in
1435              which  entries are read from the configuration files.  There are
1436              two result tables - one  (nsExtendOutput1Table)  containing  the
1437              exit status, the first line and full output (as a single string)
1438              for each extend entry, and the other (nsExtendOutput2Table) con‐
1439              taining the complete output as a series of separate lines.
1440
1441              If  -cacheTime  is  specified,  then its argument is used as the
1442              cache timeout (in whole seconds) for  this  extend  entry.  This
1443              mechanism provides a non-volatile way to specify the cache time‐
1444              out.
1445
1446              If -execType is specified and has a value of sh, then  this  ex‐
1447              tend  entry  will be run in a shell. Otherwise it will be run in
1448              the default exec fashion. This mechanism provides a non-volatile
1449              way to specify the exec type.
1450
1451              If MIBOID is specified, then the configuration and result tables
1452              will be rooted at this point in the OID tree, but are  otherwise
1453              structured in exactly the same way. This means that several sep‐
1454              arate extend directives can specify the same MIBOID root,  with‐
1455              out conflicting.
1456
1457              The  exit  status  and output is cached for each entry individu‐
1458              ally, and can be cleared (and the caching behaviour  configured)
1459              using the nsCacheTable.
1460
1461       extendfix NAME PROG ARGS
1462              registers  a  command  that can be invoked on demand, by setting
1463              the appropriate nsExtendRunType instance to the  value  run-com‐
1464              mand(3).  Unlike the equivalent execfix, this directive does not
1465              need to be paired with a corresponding extend entry, and can ap‐
1466              pear on its own.
1467
1468       Both extend and extendfix directives can be configured dynamically, us‐
1469       ing SNMP SET requests to the NET-SNMP-EXTEND-MIB.
1470
1471   MIB-Specific Extension Commands
1472       The first group of extension directives invoke arbitrary commands,  and
1473       rely  on  the  MIB  structure  (and management applications) having the
1474       flexibility to accommodate and interpret the output.  This is a  conve‐
1475       nient  way  to make information available quickly and simply, but is of
1476       no use when implementing specific MIB objects, where the extension must
1477       conform  to the structure of the MIB (rather than vice versa).  The re‐
1478       maining extension mechanisms are all concerned with  such  MIB-specific
1479       situations  - starting with "pass-through" scripts.  Use of this mecha‐
1480       nism  requires  that  the  agent  was  built  with  support   for   the
1481       ucd-snmp/pass  and  ucd-snmp/pass_persist  modules  (which are both in‐
1482       cluded as part of the default build configuration).
1483
1484       pass [-p priority] MIBOID PROG
1485              will pass control of the subtree rooted at MIBOID to the  speci‐
1486              fied  PROG  command.   GET  and GETNEXT requests for OIDs within
1487              this tree will trigger this command, called as:
1488
1489                     PROG -g OID
1490
1491                     PROG -n OID
1492
1493              respectively, where OID is the requested OID.  The PROG  command
1494              should  return  the  response  varbind  as  three separate lines
1495              printed to stdout - the first line should be the OID of the  re‐
1496              turned  value,  the  second  should be its TYPE (one of the text
1497              strings integer, gauge, counter, timeticks, ipaddress, objectid,
1498              octet,  or  string  ), and the third should be the value itself.
1499              (Note: octets are sent as ASCII,  space-separated  hex  strings,
1500              e.g. "00 3f dd 00 c6 be".)
1501
1502              If  the  command  cannot return an appropriate varbind - e.g the
1503              specified OID did not correspond to a valid instance for  a  GET
1504              request,  or  there  were no following instances for a GETNEXT -
1505              then it should exit without producing any output.  This will re‐
1506              sult in an SNMP noSuchName error, or a noSuchInstance exception.
1507
1508                     Note:  The  SMIv2  type counter64 and SNMPv2 noSuchObject
1509                            exception are not supported.
1510
1511              A SET request will result in the command being called as:
1512
1513                     PROG -s OID TYPE VALUE
1514
1515              where TYPE is one of the tokens  listed  above,  indicating  the
1516              type of the value passed as the third parameter.
1517
1518              If  the  assignment  is successful, the PROG command should exit
1519              without producing any output.  Errors  should  be  indicated  by
1520              writing  one  of the strings not-writable, or wrong-type to std‐
1521              out, and the agent will generate the appropriate error response.
1522
1523                     Note:  The other SNMPv2 errors are not supported.
1524
1525              In either case, the command should exit  once  it  has  finished
1526              processing.   Each request (and each varbind within a single re‐
1527              quest) will trigger a separate invocation of the command.
1528
1529              The default registration priority is 127.  This can  be  changed
1530              by supplying the optional -p flag, with lower priority registra‐
1531              tions being used in preference to higher priority values.
1532
1533       pass_persist [-p priority] MIBOID PROG
1534              will also pass control of the subtree rooted at  MIBOID  to  the
1535              specified  PROG  command.  However this command will continue to
1536              run after the initial request has been answered,  so  subsequent
1537              requests can be processed without the startup overheads.
1538
1539              Upon  initialization, PROG will be passed the string "PING\n" on
1540              stdin, and should respond by printing "PONG\n" to stdout.
1541
1542              For GET and GETNEXT requests, PROG will be passed two  lines  on
1543              stdin,  the  command (get or getnext) and the requested OID.  It
1544              should respond by printing three lines to stdout - the  OID  for
1545              the  result  varbind, the TYPE and the VALUE itself - exactly as
1546              for the pass directive above.  If the command cannot  return  an
1547              appropriate  varbind,  it  should print print "NONE\n" to stdout
1548              (but continue running).
1549
1550              For SET requests, PROG will be passed three lines on stdin,  the
1551              command  (set)  and  the requested OID, followed by the type and
1552              value (both on the same line).  If the assignment is successful,
1553              the  command  should print "DONE\n" to stdout.  Errors should be
1554              indicated  by  writing  one   of   the   strings   not-writable,
1555              wrong-type,  wrong-length,  wrong-value or inconsistent-value to
1556              stdout, and the agent will generate the  appropriate  error  re‐
1557              sponse.  In either case, the command should continue running.
1558
1559              The  registration  priority can be changed using the optional -p
1560              flag, just as for the pass directive.
1561
1562       pass and pass_persist extensions can only be  configured  via  the  sn‐
1563       mpd.conf file.  They cannot be set up via SNMP SET requests.
1564
1565   Embedded Perl Support
1566       Programs  using the previous extension mechanisms can be written in any
1567       convenient programming language - including perl,  which  is  a  common
1568       choice for pass-through extensions in particular.  However the Net-SNMP
1569       agent also includes support for embedded perl  technology  (similar  to
1570       mod_perl  for  the Apache web server).  This allows the agent to inter‐
1571       pret perl scripts directly, thus avoiding the overhead of spawning pro‐
1572       cesses and initializing the perl system when a request is received.
1573
1574       Use  of  this  mechanism requires that the agent was built with support
1575       for the embedded perl mechanism, which is not part of the default build
1576       environment.  It  must  be explicitly included by specifying the '--en‐
1577       able-embedded-perl' option to the configure script when the package  is
1578       first built.
1579
1580       If enabled, the following directives will be recognised:
1581
1582       disablePerl true
1583              will  turn off embedded perl support entirely (e.g. if there are
1584              problems with the perl installation).
1585
1586       perlInitFile FILE
1587              loads the specified initialisation file (if present) immediately
1588              before  the  first  perl directive is parsed.  If not explicitly
1589              specified, the agent will look for  the  default  initialisation
1590              file /usr/share/snmp/snmp_perl.pl.
1591
1592              The  default  initialisation  file creates an instance of a Net‐
1593              SNMP::agent object - a variable $agent which can be used to reg‐
1594              ister perl-based MIB handler routines.
1595
1596       perl EXPRESSION
1597              evaluates the given expression.  This would typically register a
1598              handler routine to be called when a section of the OID tree  was
1599              requested:
1600                     perl use Data::Dumper;
1601                     perl sub myroutine  { print "got called: ",Dumper(@_),"\n"; }
1602                     perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);
1603
1604              This expression could also source an external file:
1605                     perl 'do /path/to/file.pl';
1606
1607              or  perform  any  other  perl-based processing that might be re‐
1608              quired.
1609
1610   Dynamically Loadable Modules
1611       Most of the MIBs supported by the Net-SNMP agent are implemented  as  C
1612       code  modules,  which were compiled and linked into the agent libraries
1613       when the suite was first built.  Such implementation modules  can  also
1614       be compiled independently and loaded into the running agent once it has
1615       started.  Use of this mechanism requires that the agent was built  with
1616       support for the ucd-snmp/dlmod module (which is included as part of the
1617       default build configuration).
1618
1619       dlmod NAME PATH
1620              will load the shared object module from the file PATH (an  abso‐
1621              lute filename), and call the initialisation routine init_NAME.
1622
1623              Note:  If  the specified PATH is not a fully qualified filename,
1624                     it     will     be      interpreted      relative      to
1625                     /usr/lib(64)/snmp/dlmod,  and .so will be appended to the
1626                     filename.
1627
1628       This functionality can also be configured using SNMP  SET  requests  to
1629       the UCD-DLMOD-MIB.
1630
1631   Proxy Support
1632       Another  mechanism  for  extending the functionality of the agent is to
1633       pass selected requests (or selected varbinds) to  another  SNMP  agent,
1634       which  can  be running on the same host (presumably listening on a dif‐
1635       ferent port), or on a remote system.  This can be viewed either as  the
1636       main  agent delegating requests to the remote one, or acting as a proxy
1637       for it.  Use of this mechanism requires that the agent was  built  with
1638       support for the ucd-snmp/proxy module (which is included as part of the
1639       default build configuration).
1640
1641       proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]
1642              will pass any incoming requests under OID to the agent listening
1643              on  the  port  specified by the transport address HOST.  See the
1644              section LISTENING ADDRESSES in the snmpd(8) manual page for more
1645              information about the format of listening addresses.
1646
1647              Note:  To  proxy  the entire MIB tree, use the OID .1.3 (not the
1648                     top-level .1)
1649
1650       The SNMPCMD_ARGS should provide sufficient version  and  administrative
1651       information to generate a valid SNMP request (see snmpcmd(1)).
1652
1653       Note:  The  proxied  request  will  not use the administrative settings
1654              from the original request.
1655
1656       If a CONTEXTNAME is specified, this will register the proxy  delegation
1657       within  the  named context in the local agent.  Defining multiple proxy
1658       directives for the same OID but different contexts can be used to query
1659       several  remote agents through a single proxy, by specifying the appro‐
1660       priate SNMPv3 context in the incoming request (or using  suitable  con‐
1661       figured community strings - see the com2sec directive).
1662
1663       Specifying  the  REMOID parameter will map the local MIB tree rooted at
1664       OID to an equivalent subtree rooted at REMOID on the remote agent.
1665
1666   SMUX Sub-Agents
1667       The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate
1668       with  SMUX-based  subagents  (such  as gated, zebra or quagga).  Use of
1669       this mechanism requires that the agent was built with support  for  the
1670       smux  module,  which  is not part of the default build environment, and
1671       must be explicitly included by specifying the '--with-mib-modules=smux'
1672       option to the configure script when the package is first built.
1673
1674              Note:  This extension protocol has been officially deprecated in
1675                     favour of AgentX (see below).
1676
1677       smuxpeer OID PASS
1678              will register a subtree for SMUX-based processing, to be authen‐
1679              ticated using the password PASS.  If a subagent (or "peer") con‐
1680              nects to the agent and registers this subtree then requests  for
1681              OIDs within it will be passed to that SMUX subagent for process‐
1682              ing.
1683
1684              A suitable entry for an OSPF routing daemon (such as gated,  ze‐
1685              bra or quagga) might be something like
1686                     smuxpeer .1.3.6.1.2.1.14 ospf_pass
1687
1688       smuxsocket <IPv4-address>
1689              defines  the IPv4 address for SMUX peers to communicate with the
1690              Net-SNMP agent.  The default is to listen on all IPv4 interfaces
1691              ("0.0.0.0"),  unless the package has been configured with "--en‐
1692              able-local-smux" at build time, which causes it to  only  listen
1693              on 127.0.0.1 by default. SMUX uses the well-known TCP port 199.
1694
1695       Note  the  Net-SNMP  agent will only operate as a SMUX master agent. It
1696       does not support acting in a SMUX subagent role.
1697
1698   AgentX Sub-Agents
1699       The Net-SNMP agent supports the AgentX protocol (RFC 2741) in both mas‐
1700       ter  and subagent roles.  Use of this mechanism requires that the agent
1701       was built with support for the agentx module (which is included as part
1702       of  the default build configuration), and also that this support is ex‐
1703       plicitly enabled (e.g. via the snmpd.conf file).
1704
1705       There are two directives specifically relevant to running as an  AgentX
1706       master agent:
1707
1708       master agentx
1709              will  enable  the  AgentX  functionality  and cause the agent to
1710              start listening for incoming  AgentX  registrations.   This  can
1711              also be activated by specifying the '-x' command-line option (to
1712              specify an alternative listening socket).
1713
1714       agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]
1715              Defines the permissions and ownership of the AgentX Unix  Domain
1716              socket,  and  the  parent directories of this socket.  SOCKPERMS
1717              and DIRPERMS must be octal digits (see chmod(1)  ).  By  default
1718              this  socket will only be accessible to subagents which have the
1719              same userid as the agent.
1720
1721       There is one directive specifically relevant to running  as  an  AgentX
1722       sub-agent:
1723
1724       agentXPingInterval NUM
1725              will  make  the  subagent try and reconnect every NUM seconds to
1726              the master if it ever becomes (or starts) disconnected.
1727
1728       The remaining directives are relevant to both AgentX  master  and  sub-
1729       agents:
1730
1731       agentXSocket [<transport-specifier>:]<transport-address>[,...]
1732              defines the address the master agent listens at, or the subagent
1733              should connect to.   The  default  is  the  Unix  Domain  socket
1734              "/var/agentx/master".   Another common alternative is tcp:local‐
1735              host:705.  See the section LISTENING ADDRESSES in  the  snmpd(8)
1736              manual page for more information about the format of addresses.
1737
1738              Note:  Specifying an AgentX socket does not automatically enable
1739                     AgentX functionality (unlike the  '-x'  command-line  op‐
1740                     tion).
1741
1742       agentXTimeout NUM
1743              defines  the timeout period (NUM seconds) for an AgentX request.
1744              Default is 1 second.  NUM also be specified with a suffix of one
1745              of  s  (for  seconds),  m  (for  minutes), h (for hours), d (for
1746              days), or w (for weeks).
1747
1748       agentXRetries NUM
1749              defines the number of retries for an AgentX request.  Default is
1750              5 retries.
1751
1752       net-snmp  ships  with  both  C and Perl APIs to develop your own AgentX
1753       subagent.
1754

OTHER CONFIGURATION

1756       override [-rw] OID TYPE VALUE
1757              This directive allows you to override a particular  OID  with  a
1758              different  value  (and possibly a different type of value).  The
1759              -rw flag will allow snmp SETs to  modify  it's  value  as  well.
1760              (note  that  if  you're  overriding original functionality, that
1761              functionality will be entirely lost.  Thus SETS will do  nothing
1762              more than modify the internal overridden value and will not per‐
1763              form any of the original functionality intended to  be  provided
1764              by the MIB object.  It's an emulation only.)  An example:
1765
1766                     override sysDescr.0 octet_str "my own sysDescr"
1767
1768              That  line will set the sysDescr.0 value to "my own sysDescr" as
1769              well as make it modifiable with SNMP SETs as well (which is  ac‐
1770              tually illegal according to the MIB specifications).
1771
1772              Note  that  care must be taken when using this.  For example, if
1773              you try to override a property  of  the  3rd  interface  in  the
1774              ifTable  with  a  new  value  and later the numbering within the
1775              ifTable changes it's index ordering you'll end up with  problems
1776              and  your  modified value won't appear in the right place in the
1777              table.
1778
1779              Valid  TYPEs  are:  integer,  uinteger,  octet_str,   object_id,
1780              counter,  null (for gauges, use "uinteger"; for bit strings, use
1781              "octet_str").  Note that setting an object to "null" effectively
1782              delete's  it as being accessible.  No VALUE needs to be given if
1783              the object type is null.
1784
1785              More types should be available in the future.
1786
1787       If you're trying to figure out aspects of the various mib modules (pos‐
1788       sibly some that you've added yourself), the following may help you spit
1789       out some useful debugging information.  First off, please read the  sn‐
1790       mpd  manual  page on the -D flag.  Then the following configuration sn‐
1791       mpd.conf token, combined with the -D flag, can produce useful output:
1792
1793       injectHandler HANDLER modulename [beforeThis]
1794              This will insert new handlers into the section of the  mib  tree
1795              referenced  by  "modulename".  If "beforeThis" is specified then
1796              the module will be injected before the named  module.   This  is
1797              useful  for  getting  a handler into the exact right position in
1798              the chain.
1799
1800              The types of handlers available for insertion are:
1801
1802              stash_cache
1803                     Caches information returned from the lower  level.   This
1804                     greatly help the performance of the agent, at the cost of
1805                     caching the data such that its no longer  "live"  for  30
1806                     seconds  (in  this  future,  this  will be configurable).
1807                     Note that this means snmpd will use more memory  as  well
1808                     while  the  information  is  cached.  Currently this only
1809                     works for handlers registered  using  the  table_iterator
1810                     support,  which is only a few mib tables.  To use it, you
1811                     need to make sure to install it before the table_iterator
1812                     point in the chain, so to do this:
1813
1814                       injectHandler stash_cache NAME table_iterator
1815
1816                     If  you want a table to play with, try walking the nsMod‐
1817                     uleTable with and without this injected.
1818
1819
1820              debug  Prints  out  lots  of  debugging  information  when   the
1821                     -Dhelper:debug flag is passed to the snmpd application.
1822
1823
1824              read_only
1825                     Forces turning off write support for the given module.
1826
1827
1828              serialize
1829                     If  a module is failing to handle multiple requests prop‐
1830                     erly (using the new 5.0 module API), this will force  the
1831                     module to only receive one request at a time.
1832
1833
1834              bulk_to_next
1835                     If  a module registers to handle getbulk support, but for
1836                     some reason is failing to  implement  it  properly,  this
1837                     module  will  convert all getbulk requests to getnext re‐
1838                     quests before the final module receives it.
1839
1840       dontLogTCPWrappersConnects
1841              If the snmpd was compiled with TCP Wrapper support, it logs  ev‐
1842              ery  connection made to the agent. This setting disables the log
1843              messages for accepted connections. Denied connections will still
1844              be logged.
1845
1846       Figuring out module names
1847              To figure out which modules you can inject things into, run snm‐
1848              pwalk on the nsModuleTable which will give a list of  all  named
1849              modules registered within the agent.
1850
1851   Internal Data tables
1852       table NAME
1853
1854       add_row NAME INDEX(ES) VALUE(S)
1855

NOTES

1857       o      The Net-SNMP agent can be instructed to re-read the various con‐
1858              figuration files, either via an snmpset assignment of integer(1)
1859              to                           UCD-SNMP-MIB::versionUpdateConfig.0
1860              (.1.3.6.1.4.1.2021.100.11.0), or by sending a kill  -HUP  signal
1861              to the agent process.
1862
1863       o      All  directives  listed  with a value of "yes" actually accept a
1864              range of boolean values.  These will accept any  of  1,  yes  or
1865              true  to  enable the corresponding behaviour, or any of 0, no or
1866              false to disable it.  The default in each case is for  the  fea‐
1867              ture  to  be  turned off, so these directives are typically only
1868              used to enable the appropriate behaviour.
1869

EXAMPLE CONFIGURATION FILE

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

FILES

1875       /etc/snmp/snmpd.conf
1876

SEE ALSO

1878       snmpconf(1),  snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAM‐
1879       PLE.conf, netsnmp_config_api(3).
1880
1881
1882
1883V5.9.1                            30 Jun 2010                    SNMPD.CONF(5)
Impressum