| .TH SNMP.CONF 5 "21 Apr 2010" VVERSIONINFO "Net-SNMP" |
| .SH NAME |
| snmp.conf - configuration files for the Net-SNMP applications |
| .SH DESCRIPTION |
| Applications built using the Net-SNMP libraries typically use one or |
| more configuration files to control various aspects of their operation. |
| These files (\fBsnmp.conf\fR and \fBsnmp.local.conf\fR) can be located |
| in one of several locations, as described in the \fIsnmp_config(5)\fR |
| manual page. |
| .PP |
| In particular, \fCSYSCONFDIR/snmp/snmp.conf\fR is a common file, |
| containing the settings shared by all users of the system. |
| \fC~/.snmp/snmp.conf\fR is a personal file, with the settings |
| specific to a particular user. |
| .SH HOST-SPECIFIC FILES |
| Host-specific files may also be loaded and will be searched for if a |
| transport name is specified that matches a \fIPATH/hosts/HOST.conf\fR |
| file. For example, if you wanted a particular host to use SNMPv2c by |
| default you could create a ~/.snmp/hosts/NAME.conf file and in it put: |
| .RS |
| .PP |
| defVersion 2c |
| .RE |
| .PP |
| Any connections set to connect to the hostname \fINAME\fR will use |
| SNMPv2c. Also see the \fItransport\fR token below for additional |
| host-specific examples. |
| .PP |
| Host-specific configuration files are loaded at the time the |
| connection is opened. Thus they're generally loaded after all other |
| configuration files and can be used to override settings from the |
| generic files. |
| .PP |
| To avoid loading any host-specific config files set |
| "dontLoadHostConfig true" in your snmp.conf file. |
| .SH COMMAND-LINE OPTIONS |
| All of the tokens described in this file can be used on the command |
| line of Net-SNMP applications as well by prefixing them with "\-\-". |
| EG, specifying \fI\-\-dontLoadHostConfig=true\fR on the command line will |
| turn of loading of the host specific configuration files. |
| .SH IMPORTANT NOTE |
| Several of these directives may contain sensitive information |
| (such as pass phrases). Configuration files that include such |
| settings should only be readable by the user concerned. |
| .PP |
| As well as application-specific configuration tokens, there are |
| several directives that relate to standard library behaviour, |
| relevant to most Net-SNMP applications. Many of these correspond |
| to standard command-line options, which are described in the |
| \fIsnmpcmd(1)\fR manual page. |
| .PP |
| These directives can be divided into several distinct groups. |
| .SH CLIENT BEHAVIOUR |
| .IP "defDomain application domain" |
| The transport domain that should be used for a certain application type unless |
| something else is specified. |
| .IP "defTarget application domain target" |
| The target that should be used for connections to a certain application if the |
| connection should be in a specific domain. |
| .IP "defaultPort PORT" |
| defines the default UDP port that client SNMP applications will |
| attempt to connect to. This can be overridden by explicitly |
| including a port number in the \fIAGENT\fR specification. |
| See the \fIsnmpcmd(1)\fR manual page for more details. |
| .IP |
| If not specified, the default value for this token is 161. |
| .IP "transport HOSTSPECIFIER" |
| This special token should go into a hostname-specific configuration |
| file in a \fIhosts\fR sub-directory. For example if the file |
| \fIhosts/foo.conf\fR exists in the search path it will be loaded if a |
| transport name of \fIfoo\fR was used. Within the foo.conf file you may |
| put both general snmp.conf settings as well as a special |
| \fItransport\fR string to specify the destination to connect to. For |
| example, putting: |
| .RS |
| .IP |
| transport tcp:foo.example.com:9876 |
| .RE |
| .IP |
| in the \fIhosts/foo.conf\fR file will make applications referencing |
| the \fIfoo\fR hostname (e.g. \fIsnmpget\fR) to actually connect via |
| TCP to \fIfoo.exmaple.com\fR on port 9876. |
| .IP "defVersion (1|2c|3)" |
| defines the default version of SNMP to use. |
| This can be overridden using the \fB\-v\fR option. |
| .IP "defCommunity STRING" |
| defines the default community to use for SNMPv1 and SNMPv2c requests. |
| This can be overridden using the \fB\-c\fR option. |
| .\".IP "dumpPacket (1|yes|true|0|no|false)" |
| .IP "alias NAME DEFINITION" |
| Creates an aliased tied to NAME for a given transport definition. The |
| alias can the be referred to using an alias: prefix. Eg, a line of |
| "alias here udp:127.0.0.1:6161" would allow you to use a destination |
| host of "alias:here" instead of "udp:127.0.0.1:6161". This becomes |
| more useful with complex transport addresses involving IPv6 addresses, |
| etc. |
| .IP "dumpPacket yes" |
| defines whether to display a hexadecimal dump of the raw SNMP requests |
| sent and received by the application. |
| This is equivalent to the \fB\-d\fR option. |
| .IP "doDebugging (1|0)" |
| turns on debugging for all applications run if set to 1. |
| .\" |
| .\" XXX - why not full boolean values? |
| .\" what is the purpose of this directive ?? |
| .\" |
| .IP "debugTokens TOKEN[,TOKEN...]" |
| defines the debugging tokens that should be turned on when |
| \fIdoDebugging\fR is set. |
| This is equivalent to the \fB\-D\fR option. |
| .\".IP "16bitIDs (1|yes|true|0|no|false)" |
| .IP "16bitIDs yes" |
| restricts requestIDs, etc to 16-bit values. |
| .IP |
| The SNMP specifications define these ID fields as 32-bit quantities, |
| and the Net-SNMP library typically initialises them to random values |
| for security. |
| However certain (broken) agents cannot handle ID values greater than |
| 2^16 - this option allows interoperability with such agents. |
| .IP "clientaddr [<transport-specifier>:]<transport-address>" |
| specifies the source address to be used by command-line applications |
| when sending SNMP requests. See \fIsnmpcmd(1)\fR for more information |
| about the format of addresses. |
| .IP |
| This value is also used by \fBsnmpd\fR when generating notifications. |
| .\" |
| .\" But not responses to an incoming request? |
| .\" What about snmptrapd? |
| .\" |
| .IP "clientRecvBuf INTEGER" |
| specifies the desired size of the buffer to be used when receiving |
| responses to SNMP requests. |
| If the OS hard limit is lower than the \fIclientRecvBuf\fR value, |
| then this will be used instead. |
| Some platforms may decide to increase the size of the buffer |
| actually used for internal housekeeping. |
| .IP |
| This directive will be ignored if the platforms does not support |
| \fIsetsockopt()\fR. |
| .IP "clientSendBuf INTEGER" |
| is similar to \fIclientRecvBuf\fR, but applies to the size |
| of the buffer used when sending SNMP requests. |
| .IP "noRangeCheck yes" |
| disables the validation of varbind values against the MIB definition |
| for the relevant OID. |
| This is equivalent to the \fB\-Ir\fR option. |
| .IP |
| This directive is primarily relevant to the \fBsnmpset\fR command, |
| but will also apply to any application that calls \fIsnmp_add_var()\fR |
| .\" what else ?? |
| with a non-NULL value. |
| .\" |
| .\" XXX - including snmpd ?? |
| .\" |
| .IP "noTokenWarnings" |
| disables warnings about unknown config file tokens. |
| .IP "reverseEncodeBER (1|yes|true|0|no|false)" |
| controls how the encoding of SNMP requests is handled. |
| .IP |
| The default behaviour is to encode packets starting from the end of |
| the PDU and working backwards. |
| This directive can be used to disable this behaviour, and build |
| the encoded request in the (more obvious) forward direction. |
| .IP |
| It should not normally be necessary to change this setting, as |
| the encoding is basically the same in either case - but working |
| backwards typically produces a slightly more efficient encoding, |
| and hence a smaller network datagram. |
| .IP "dontLoadHostConfig (1|yes|true|0|no|false)" |
| Specifies whether or not the host-specific configuration files are |
| loaded. Set to "true" to turn off the loading of the host specific |
| configuration files. |
| .IP "retries INTEGER" |
| Specifies the number of retries to be used in the requests. |
| .IP "timeout INTEGER" |
| Specifies the timeout in seconds between retries. |
| .\" |
| .\" XXX - It is probably about time to remove this choice! |
| .\" |
| .SH SNMPv3 SETTINGS |
| .IP "defSecurityName STRING" |
| defines the default security name to use for SNMPv3 requests. |
| This can be overridden using the \fB\-u\fR option. |
| .IP "defSecurityLevel noAuthNoPriv|authNoPriv|authPriv" |
| defines the default security level to use for SNMPv3 requests. |
| This can be overridden using the \fB\-l\fR option. |
| .IP |
| If not specified, the default value for this token is \fInoAuthNoPriv\fR. |
| .\" |
| .\" XXX - Is this correct ? |
| .\" |
| .RS |
| .IP "Note: |
| \fIauthPriv\fR is only available if the software has been compiled |
| to use the OpenSSL libraries. |
| .RE |
| .IP "defPassphrase STRING" |
| .IP "defAuthPassphrase STRING" |
| .IP "defPrivPassphrase STRING" |
| define the default authentication and privacy pass phrases to use |
| for SNMPv3 requests. |
| These can be overridden using the \fB\-A\fR and \fB\-X\fR options respectively. |
| .IP |
| The |
| .B defPassphrase |
| value will be used for the authentication and/or privacy pass phrases |
| if either of the other directives are not specified. |
| .IP "defAuthType MD5|SHA" |
| .IP "defPrivType DES|AES" |
| define the default authentication and privacy protocols to use for |
| SNMPv3 requests. |
| These can be overridden using the \fB\-a\fR and \fB\-x\fR options respectively. |
| .IP |
| If not specified, SNMPv3 requests will default to MD5 authentication |
| and DES encryption. |
| .RS |
| .IP "Note: |
| If the software has not been compiled to use the OpenSSL libraries, |
| then only MD5 authentication is supported. |
| Neither SHA authentication nor any form of encryption will be available. |
| .RE |
| .IP "defContext STRING" |
| defines the default context to use for SNMPv3 requests. |
| This can be overridden using the \fB\-n\fR option. |
| .IP |
| If not specified, the default value for this token is the default context |
| (i.e. the empty string ""). |
| .IP "defSecurityModel STRING" |
| defines the security model to use for SNMPv3 requests. |
| The default value is "usm" which is the only widely |
| used security model for SNMPv3. |
| .IP "defAuthMasterKey 0xHEXSTRING" |
| .IP "defPrivMasterKey 0xHEXSTRING" |
| .IP "defAuthLocalizedKey 0xHEXSTRING" |
| .IP "defPrivLocalizedKey 0xHEXSTRING" |
| define the (hexadecimal) keys to be used for SNMPv3 secure communications. |
| SNMPv3 keys are frequently derived from a passphrase, as discussed in |
| the \fIdefPassphrase\fR section above. However for improved security a |
| truely random key can be generated and used instead (which would |
| normally has better entropy than a password unless it is |
| amazingly long). |
| The directives are equivalent to the short-form |
| command line options \fB\-3m\fR, \fB\-3M\fR, \fB\-3k\fR, and \fB\-3K\fR. |
| .IP |
| Localized keys are |
| master keys which have been converted to a unique key which is only |
| suitable for on particular SNMP engine (agent). The length of the key |
| needs to be appropriate for the authentication or encryption type |
| being used (auth keys: MD5=16 bytes, SHA1=20 bytes; |
| priv keys: DES=16 bytes (8 |
| bytes of which is used as an IV and not a key), and AES=16 bytes). |
| .IP "sshtosnmpsocket PATH" |
| Sets the path of the \fBsshtosnmp\fR socket created by an application |
| (e.g. snmpd) listening for incoming ssh connections through the |
| \fBsshtosnmp\fR unix socket. |
| .IP "sshtosnmpsocketperms MODE [OWNER [GROUP]]" |
| Sets the mode, owner and group of the \fBsshtosnmp\fR socket created by |
| an application (e.g. \fBsnmpd\fR) listening for incoming ssh connections |
| through the \fBsshtosnmp\fR unix socket. The socket needs to be read/write |
| privileged for SSH users that are allowed to connect to the SNMP |
| service (VACM access still needs to be granted as well, most likely |
| through the TSM security model). |
| .IP "sshusername NAME" |
| Sets the SSH user name for logging into the remote system. |
| .IP "sshpubkey FILE" |
| Set the public key file to use when connecting to a remote system. |
| .IP "sshprivkey FILE" |
| Set the private key file to use when connecting to a remote system. |
| .\" |
| .\" XXX - are these lengths still correct ? |
| .\" |
| .SH SERVER BEHAVIOUR |
| .IP "persistentDir DIRECTORY" |
| defines the directory where \fBsnmpd\fR and \fBsnmptrapd\fR store |
| persistent configuration settings. |
| .IP |
| If not specified, the persistent directory defaults to |
| PERSISTENT_DIRECTORY |
| .IP "noPersistentLoad yes" |
| .IP "noPersistentSave yes" |
| disable the loading and saving of persistent configuration information. |
| .RS |
| .IP "Note:" |
| This will break SNMPv3 operations (and other behaviour that relies |
| on changes persisting across application restart). Use With Care. |
| .RE |
| .IP "tempFilePattern PATTERN" |
| defines a filename template for creating temporary files, |
| for handling input to and output from external shell commands. |
| Used by the \fImkstemp()\fR and \fImktemp()\fR functions. |
| .IP |
| If not specified, the default pattern is \fCNETSNMP_TEMP_FILE_PATTERN\fR. |
| .IP "serverRecvBuf INTEGER" |
| specifies the desired size of the buffer to be used when receiving |
| incoming SNMP requests. |
| If the OS hard limit is lower than the \fIserverRecvBuf\fR value, |
| then this will be used instead. |
| Some platforms may decide to increase the size of the buffer |
| actually used for internal housekeeping. |
| .IP |
| This directive will be ignored if the platforms does not support |
| \fIsetsockopt()\fR. |
| .IP "serverSendBuf INTEGER" |
| is similar to \fIserverRecvBuf\fR, but applies to the size |
| of the buffer used when sending SNMP responses. |
| .SH MIB HANDLING |
| .IP "mibdirs DIRLIST" |
| specifies a list of directories to search for MIB files. |
| This operates in the same way as the \fB\-M\fR option - |
| see \fIsnmpcmd(1)\fR for details. |
| Note that this value can be overridden by the |
| .B MIBDIRS |
| environment variable, and the \fB\-M\fR option. |
| .IP "mibs MIBLIST" |
| specifies a list of MIB modules (not files) that should be loaded. |
| This operates in the same way as the \fB\-m\fR option - |
| see \fIsnmpcmd(1)\fR for details. |
| Note that this list can be overridden by the |
| .B MIBS |
| environment variable, and the \fB\-m\fR option. |
| .IP "mibfile FILE" |
| specifies a (single) MIB file to load, in addition to the |
| list read from the \fImibs\fR token (or equivalent configuration). |
| Note that this value can be overridden by the |
| .B MIBFILES |
| environment variable. |
| .IP "showMibErrors (1|yes|true|0|no|false)" |
| whether to display MIB parsing errors. |
| .IP "commentToEOL (1|yes|true|0|no|false)" |
| whether MIB parsing should be strict about comment termination. |
| Many MIB writers assume that ASN.1 comments extend to the end of |
| the text line, rather than being terminated by the next "\-\-" token. |
| This token can be used to accept such (strictly incorrect) MIBs. |
| .br |
| Note that this directive was previous (mis-)named \fIstrictCommentTerm\fR, |
| but with the reverse behaviour from that implied by the name. |
| This earlier token is still accepted for backwards compatibility. |
| .IP "mibAllowUnderline (1|yes|true|0|no|false)" |
| whether to allow underline characters in MIB object names and |
| enumeration values. |
| This token can be used to accept such (strictly incorrect) MIBs. |
| .IP "mibWarningLevel INTEGER" |
| the minimum warning level of the warnings printed by the MIB parser. |
| .SH OUTPUT CONFIGURATION |
| .IP "logTimestamp (1|yes|true|0|no|false)" |
| Whether the commands should log timestamps with their error/message |
| logging or not. Note that output will not look as pretty with |
| timestamps if the source code that is doing the logging does |
| incremental logging of messages that are not line buffered before |
| being passed to the logging routines. This option is only used when file logging is active. |
| .IP "printNumericEnums (1|yes|true|0|no|false)" |
| Equivalent to |
| .BR \-Oe . |
| .IP "printNumericOids (1|yes|true|0|no|false)" |
| Equivalent to |
| .BR \-On . |
| .IP "dontBreakdownOids (1|yes|true|0|no|false)" |
| Equivalent to |
| .BR \-Ob . |
| .IP "escapeQuotes (1|yes|true|0|no|false)" |
| Equivalent to |
| .BR \-OE . |
| .IP "quickPrinting (1|yes|true|0|no|false)" |
| Equivalent to |
| .BR \-Oq . |
| .IP "printValueOnly (1|yes|true|0|no|false)" |
| Equivalent to |
| .BR \-Ov . |
| .IP "dontPrintUnits (1|yes|true|0|no|false)" |
| Equivalent to |
| .BR \-OU . |
| .IP "numericTimeticks (1|yes|true|0|no|false)" |
| Equivalent to |
| .BR \-Ot . |
| .IP "printHexText (1|yes|true|0|no|false)" |
| Equivalent to |
| .BR \-OT . |
| .IP "hexOutputLength integer" |
| Specifies where to break up the output of hexadecimal strings. |
| Set to 0 to disable line breaks. Defaults to 16. |
| .IP "suffixPrinting (0|1|2)" |
| The value 1 is equivalent to |
| .B \-Os |
| and the value 2 is equivalent to |
| .BR \-OS . |
| .IP "oidOutputFormat (1|2|3|4|5|6)" |
| Maps \-O options as follow: \-Os=1, \-OS=2, \-Of=3, \-On=4, \-Ou=5. |
| The value 6 has no matching \-O option. It suppresses output. |
| .IP "extendedIndex (1|yes|true|0|no|false)" |
| Equivalent to |
| .BR \-OX . |
| .IP "noDisplayHint (1|yes|true|0|no|false)" |
| Disables the use of DISPLAY-HINT information when parsing indices and |
| values to set. Equivalent to |
| .BR \-Ih . |
| .SH FILES |
| .IP "System-wide configuration files:" |
| SYSCONFDIR/snmp/snmp.conf |
| .br |
| SYSCONFDIR/snmp/snmp.local.conf |
| .IP "User-specific configuration settings:" |
| $HOME/.snmp/snmp.conf |
| .br |
| $HOME/.snmp/snmp.local.conf |
| .IP "Destination host specific files: |
| SYSCONFDIR/snmp/hosts/HOSTNAME.conf |
| .br |
| $HOME/.snmp/hosts/HOSTNAME.conf |
| |
| .SH "SEE ALSO" |
| snmp_config(5), netsnmp_config_api(3), snmpcmd(1). |
| .\" Local Variables: |
| .\" mode: nroff |
| .\" End: |