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

NAME

6       snmp.conf - configuration files for the Net-SNMP applications
7

DESCRIPTION

9       Applications  built  using  the Net-SNMP libraries typically use one or
10       more configuration files to control various aspects of their operation.
11       These  files  (snmp.conf  and snmp.local.conf) can be located in one of
12       several locations, as described in the snmp_config(5) manual page.
13
14       In particular, /etc/snmp/snmp.conf is a  common  file,  containing  the
15       settings  shared  by  all  users of the system.  ~/.snmp/snmp.conf is a
16       personal file, with the settings specific to a particular user.
17

HOST-SPECIFIC FILES

19       Host-specific files may also be loaded and will be searched  for  if  a
20       transport  name  is specified that matches a PATH/hosts/HOST.conf file.
21       For example, if you wanted a particular host to use SNMPv2c by  default
22       you could create a ~/.snmp/hosts/NAME.conf file and in it put:
23
24              defVersion 2c
25
26       Any  connections  set to connect to the hostname NAME will use SNMPv2c.
27       Also see the transport token below for additional  host-specific  exam‐
28       ples.
29
30       Host-specific configuration files are loaded at the time the connection
31       is opened.  Thus they're generally loaded after all other configuration
32       files and can be used to override settings from the generic files.
33
34       To avoid loading any host-specific config files set "dontLoadHostConfig
35       true" in your snmp.conf file.
36

COMMAND-LINE OPTIONS

38       All of the tokens described in this file can be  used  on  the  command
39       line of Net-SNMP applications as well by prefixing them with "--".  EG,
40       specifying --dontLoadHostConfig=true on the command line will  turn  of
41       loading of the host specific configuration files.
42

IMPORTANT NOTE

44       Several  of these directives may contain sensitive information (such as
45       pass phrases).  Configuration files that include such  settings  should
46       only be readable by the user concerned.
47
48       As well as application-specific configuration tokens, there are several
49       directives that relate to standard library behaviour, relevant to  most
50       Net-SNMP  applications.   Many of these correspond to standard command-
51       line options, which are described in the snmpcmd(1) manual page.
52
53       These directives can be divided into several distinct groups.
54

CLIENT BEHAVIOUR

56       defDomain application domain
57              The transport domain that should be used for a certain  applica‐
58              tion type unless something else is specified.
59
60       defTarget application domain target
61              The  target that should be used for connections to a certain ap‐
62              plication if the connection should be in a specific domain.
63
64       defaultPort PORT
65              defines the default UDP port that client SNMP applications  will
66              attempt to connect to.  This can be overridden by explicitly in‐
67              cluding a port number in the AGENT specification.  See the  snm‐
68              pcmd(1) manual page for more details.
69
70              If not specified, the default value for this token is 161.
71
72       transport HOSTSPECIFIER
73              This special token should go into a hostname-specific configura‐
74              tion file in a hosts sub-directory.  For  example  if  the  file
75              hosts/foo.conf  exists in the search path it will be loaded if a
76              transport name of foo was used.  Within the  foo.conf  file  you
77              may  put  both  general  snmp.conf settings as well as a special
78              transport string to specify the destination to connect to.   For
79              example, putting:
80
81                     transport tcp:foo.example.com:9876
82
83              in  the  hosts/foo.conf  file will make applications referencing
84              the foo hostname (e.g. snmpget) to actually connect via  TCP  to
85              foo.exmaple.com on port 9876.
86
87       defVersion (1|2c|3)
88              defines  the  default version of SNMP to use.  This can be over‐
89              ridden using the -v option.
90
91       defCommunity STRING
92              defines the default community to use for SNMPv1 and SNMPv2c  re‐
93              quests.  This can be overridden using the -c option.
94
95       alias NAME DEFINITION
96              Creates  an  aliased  tied to NAME for a given transport defini‐
97              tion.  The alias can the be referred to using an alias:  prefix.
98              Eg, a line of "alias here udp:127.0.0.1:6161" would allow you to
99              use   a   destination   host   of   "alias:here"   instead    of
100              "udp:127.0.0.1:6161".   This  becomes  more  useful with complex
101              transport addresses involving IPv6 addresses, etc.
102
103       dumpPacket yes
104              defines whether to display a hexadecimal dump of  the  raw  SNMP
105              requests  sent and received by the application.  This is equiva‐
106              lent to the -d option.
107
108       doDebugging (1|0)
109              turns on debugging for all applications run if set to 1.
110
111       debugTokens TOKEN[,TOKEN...]
112              defines the debugging tokens that should be turned on when doDe‐
113              bugging is set.  This is equivalent to the -D option.
114
115       debugLogLevel (emerg|alert|crit|err|warning|notice|info|debug)
116              Set  the priority level for logging of debug output. Defaults to
117              debug.
118
119       16bitIDs yes
120              restricts requestIDs, etc to 16-bit values.
121
122              The SNMP specifications define these ID fields as 32-bit quanti‐
123              ties,  and  the  Net-SNMP  library typically initialises them to
124              random values for security.   However  certain  (broken)  agents
125              cannot  handle  ID values greater than 2^16 - this option allows
126              interoperability with such agents.
127
128       clientaddr [<transport-specifier>:]<transport-address>
129              specifies the source address to be used by command-line applica‐
130              tions when sending SNMP requests. See snmpcmd(1) for more infor‐
131              mation about the format of addresses.
132
133              This value is also used by snmpd when generating notifications.
134
135       clientaddrUsesPort no
136              specifies, if clientaddr option contains a port number. Set this
137              option  to  "yes", if clientaddr contains a port number and this
138              port should be used for sending outgoing SNMP requests. This op‐
139              tion  only affects IPv4 client addresses and is ignored for IPv6
140              client addresses.
141
142       clientRecvBuf INTEGER
143              specifies the desired size of the buffer to be used when receiv‐
144              ing  responses  to SNMP requests.  If the OS hard limit is lower
145              than the clientRecvBuf value, then this will  be  used  instead.
146              Some platforms may decide to increase the size of the buffer ac‐
147              tually used for internal housekeeping.
148
149              This directive will be ignored if the platforms does not support
150              setsockopt().
151
152       clientSendBuf INTEGER
153              is similar to clientRecvBuf, but applies to the size of the buf‐
154              fer used when sending SNMP requests.
155
156       noRangeCheck yes
157              disables the validation of varbind values against the MIB  defi‐
158              nition  for the relevant OID.  This is equivalent to the -Ir op‐
159              tion.
160
161              This directive is primarily relevant to the snmpset command, but
162              will  also  apply  to  any application that calls snmp_add_var()
163              with a non-NULL value.
164
165       noTokenWarnings
166              disables warnings about unknown config file tokens.
167
168       reverseEncodeBER (1|yes|true|0|no|false)
169              controls how the encoding of SNMP requests is handled.
170
171              The default behaviour is to encode packets starting from the end
172              of the PDU and working backwards.  This directive can be used to
173              disable this behaviour, and build the  encoded  request  in  the
174              (more obvious) forward direction.
175
176              It  should  not normally be necessary to change this setting, as
177              the encoding is basically the same in either case - but  working
178              backwards typically produces a slightly more efficient encoding,
179              and hence a smaller network datagram.
180
181       dontLoadHostConfig (1|yes|true|0|no|false)
182              Specifies whether or not the host-specific  configuration  files
183              are  loaded.   Set to "true" to turn off the loading of the host
184              specific configuration files.
185
186       retries INTEGER
187              Specifies the number of retries to be used in the requests.
188
189       timeout INTEGER
190              Specifies the timeout in seconds between retries.
191

SNMPv1/SNMPv2c SETTINGS

193       disableSNMPv1  (1|yes|true|0|no|false)
194
195       disableSNMPv2c (1|yes|true|0|no|false)
196              Disables protocol versions at  runtime.  Incoming  and  outgoing
197              packets for the protocol will be dropped.
198

SNMPv3 SETTINGS

200       disableSNMPv3  (1|yes|true|0|no|false)
201              Disables  protocol  versions  at  runtime. Incoming and outgoing
202              packets for the protocol will be dropped.
203
204       defSecurityName STRING
205              defines the default security name to use  for  SNMPv3  requests.
206              This can be overridden using the -u option.
207
208       defSecurityLevel noAuthNoPriv|authNoPriv|authPriv
209              defines  the  default security level to use for SNMPv3 requests.
210              This can be overridden using the -l option.
211
212              If not specified, the default value for this token is  noAuthNo‐
213              Priv.
214
215              Note:  authPriv  is only available if the software has been com‐
216                     piled to use the OpenSSL libraries.
217
218       defPassphrase STRING
219
220       defAuthPassphrase STRING
221
222       defPrivPassphrase STRING
223              define the default authentication and privacy  pass  phrases  to
224              use  for  SNMPv3 requests.  These can be overridden using the -A
225              and -X options respectively.
226
227              The defPassphrase value will  be  used  for  the  authentication
228              and/or  privacy  pass  phrases if either of the other directives
229              are not specified.
230
231       defAuthType MD5|SHA|SHA-512|SHA-384|SHA-256|SHA-224
232
233       defPrivType AES
234              define the default authentication and privacy protocols  to  use
235              for  SNMPv3  requests.  These can be overridden using the -a and
236              -x options respectively.
237
238              If not specified, SNMPv3 requests will default to MD5  authenti‐
239              cation and AES encryption.
240
241              Note:  If  the software has not been compiled to use the OpenSSL
242                     libraries, then only  MD5  authentication  is  supported.
243                     Neither  SHA  authentication  nor  any form of encryption
244                     will be available.
245
246       defContext STRING
247              defines the default context to use for  SNMPv3  requests.   This
248              can be overridden using the -n option.
249
250              If  not  specified,  the default value for this token is the de‐
251              fault context (i.e. the empty string "").
252
253       defSecurityModel STRING
254              defines the security model to use for SNMPv3 requests.  The  de‐
255              fault  value  is  "usm"  which  is the only widely used security
256              model for SNMPv3.
257
258       defAuthMasterKey 0xHEXSTRING
259
260       defPrivMasterKey 0xHEXSTRING
261
262       defAuthLocalizedKey 0xHEXSTRING
263
264       defPrivLocalizedKey 0xHEXSTRING
265              define the (hexadecimal) keys to be used for SNMPv3 secure  com‐
266              munications.    SNMPv3   keys  are  frequently  derived  from  a
267              passphrase, as discussed in  the  defPassphrase  section  above.
268              However  for improved security a truely random key can be gener‐
269              ated and used instead (which would normally has  better  entropy
270              than  a  password  unless it is amazingly long).  The directives
271              are equivalent to the short-form command line options -3m,  -3M,
272              -3k, and -3K.
273
274              Localized  keys  are  master keys which have been converted to a
275              unique key which is only suitable for on particular SNMP  engine
276              (agent).   The length of the key needs to be appropriate for the
277              authentication or encryption type being used (auth keys:  MD5=16
278              bytes, SHA1=20 bytes; priv keys: AES=16 bytes).
279
280       sshtosnmpsocket PATH
281              Sets  the path of the sshtosnmp socket created by an application
282              (e.g. snmpd) listening for incoming ssh connections through  the
283              sshtosnmp unix socket.
284
285       sshtosnmpsocketperms MODE [OWNER [GROUP]]
286              Sets  the  mode, owner and group of the sshtosnmp socket created
287              by an application (e.g. snmpd) listening for incoming  ssh  con‐
288              nections through the sshtosnmp unix socket.  The socket needs to
289              be read/write privileged for SSH users that are allowed to  con‐
290              nect  to the SNMP service (VACM access still needs to be granted
291              as well, most likely through the TSM security model).
292
293       sshusername NAME
294              Sets the SSH user name for logging into the remote system.
295
296       sshpubkey FILE
297              Set the public key file to use when connecting to a remote  sys‐
298              tem.
299
300       sshprivkey FILE
301              Set the private key file to use when connecting to a remote sys‐
302              tem.
303

SERVER BEHAVIOUR

305       persistentDir DIRECTORY
306              defines the directory where snmpd and snmptrapd store persistent
307              configuration settings.
308
309              If   not   specified,   the  persistent  directory  defaults  to
310              /var/lib/net-snmp
311
312       noPersistentLoad yes
313
314       noPersistentSave yes
315              disable the loading and saving of persistent  configuration  in‐
316              formation.
317
318              Note:  This  will  break  SNMPv3 operations (and other behaviour
319                     that relies  on  changes  persisting  across  application
320                     restart).  Use With Care.
321
322       tempFilePattern PATTERN
323              defines  a  filename  template for creating temporary files, for
324              handling input to and output from external shell commands.  Used
325              by the mkstemp() and mktemp() functions.
326
327              If  not  specified,  the default pattern is "/run/net-snmp/snmp-
328              tmp-XXXXXX".
329
330       serverRecvBuf INTEGER
331              specifies the desired size of the buffer to be used when receiv‐
332              ing  incoming SNMP requests.  If the OS hard limit is lower than
333              the serverRecvBuf value, then this will be used  instead.   Some
334              platforms may decide to increase the size of the buffer actually
335              used for internal housekeeping.
336
337              This directive will be ignored if the platforms does not support
338              setsockopt().
339
340       serverSendBuf INTEGER
341              is similar to serverRecvBuf, but applies to the size of the buf‐
342              fer used when sending SNMP responses.
343
344       sourceFilterType none|acceptlist|blocklist
345              specifies whether or not addresses  added  with  sourceFilterAd‐
346              dress  are  accepted or blocked. The default is none, indicating
347              that incoming packets will not  be  checked  agains  the  filter
348              list.
349
350       sourceFilterAddress ADDRESS
351              specifies  an  address  to be added to the source address filter
352              list.  sourceFilterType configuration determines whether or  not
353              addresses are accepted or blocked.
354

MIB HANDLING

356       mibdirs DIRLIST
357              specifies  a  list of directories to search for MIB files.  This
358              operates in the same way as the -M option - see  snmpcmd(1)  for
359              details.   Note that this value can be overridden by the MIBDIRS
360              environment variable, and the -M option.
361
362       mibs MIBLIST
363              specifies a list of MIB  modules  (not  files)  that  should  be
364              loaded.   This  operates  in the same way as the -m option - see
365              snmpcmd(1) for details.  Note that this list can  be  overridden
366              by the MIBS environment variable, and the -m option.
367
368       mibfile FILE
369              specifies  a  (single) MIB file to load, in addition to the list
370              read from the mibs token (or  equivalent  configuration).   Note
371              that  this  value  can be overridden by the MIBFILES environment
372              variable.
373
374       showMibErrors (1|yes|true|0|no|false)
375              whether to display MIB parsing errors.
376
377       commentToEOL (1|yes|true|0|no|false)
378              whether MIB parsing should be strict about comment  termination.
379              Many MIB writers assume that ASN.1 comments extend to the end of
380              the text line, rather than being terminated by the next "--" to‐
381              ken.  This token can be used to accept such (strictly incorrect)
382              MIBs.
383              Note that this directive was previous (mis-)named strictComment‐
384              Term,  but  with  the reverse behaviour from that implied by the
385              name.  This earlier token is still accepted for  backwards  com‐
386              patibility.
387
388       mibAllowUnderline (1|yes|true|0|no|false)
389              whether  to  allow  underline characters in MIB object names and
390              enumeration values.  This token  can  be  used  to  accept  such
391              (strictly incorrect) MIBs.
392
393       mibWarningLevel INTEGER
394              the  minimum  warning  level  of the warnings printed by the MIB
395              parser.
396

OUTPUT CONFIGURATION

398       logTimestamp (1|yes|true|0|no|false)
399              Whether the commands should log timestamps with their error/mes‐
400              sage  logging  or not.  Note that output will not look as pretty
401              with timestamps if the source code that  is  doing  the  logging
402              does  incremental logging of messages that are not line buffered
403              before being passed to the logging  routines.   This  option  is
404              only used when file logging is active.
405
406       printNumericEnums (1|yes|true|0|no|false)
407              Equivalent to -Oe.
408
409       printNumericOids (1|yes|true|0|no|false)
410              Equivalent to -On.
411
412       dontBreakdownOids (1|yes|true|0|no|false)
413              Equivalent to -Ob.
414
415       escapeQuotes (1|yes|true|0|no|false)
416              Equivalent to -OE.
417
418       quickPrinting (1|yes|true|0|no|false)
419              Equivalent to -Oq.
420
421       printValueOnly (1|yes|true|0|no|false)
422              Equivalent to -Ov.
423
424       dontPrintUnits (1|yes|true|0|no|false)
425              Equivalent to -OU.
426
427       numericTimeticks (1|yes|true|0|no|false)
428              Equivalent to -Ot.
429
430       printHexText (1|yes|true|0|no|false)
431              Equivalent to -OT.
432
433       hexOutputLength integer
434              Specifies  where  to break up the output of hexadecimal strings.
435              Set to 0 to disable line breaks.  Defaults to 16.
436
437       suffixPrinting (0|1|2)
438              The value 1 is equivalent to -Os and the value 2  is  equivalent
439              to -OS.
440
441       oidOutputFormat (1|2|3|4|5|6)
442              Maps  -O  options  as follow: -Os=1, -OS=2, -Of=3, -On=4, -Ou=5.
443              The value 6 has no matching -O option. It suppresses output.
444
445       extendedIndex (1|yes|true|0|no|false)
446              Equivalent to -OX.
447
448       noDisplayHint (1|yes|true|0|no|false)
449              Disables the use of DISPLAY-HINT information  when  parsing  in‐
450              dices and values to set. Equivalent to -Ih.
451
452       outputPrecision PRECISION
453              Uses  the  PRECISION  string  to allow modification of the value
454              output format. See snmpcmd(1) for details.   Equivalent  to  -Op
455              (which takes precedence over the config file).
456

FILES

458       System-wide configuration files:
459              /etc/snmp/snmp.conf
460              /etc/snmp/snmp.local.conf
461
462       User-specific configuration settings:
463              $HOME/.snmp/snmp.conf
464              $HOME/.snmp/snmp.local.conf
465
466       Destination host specific files:
467              /etc/snmp/hosts/HOSTNAME.conf
468              $HOME/.snmp/hosts/HOSTNAME.conf
469
470

SEE ALSO

472       snmp_config(5), netsnmp_config_api(3), snmpcmd(1).
473
474
475
476V5.9.1                            21 Apr 2010                     SNMP.CONF(5)
Impressum