1.\" $OpenBSD: snmpd.conf.5,v 1.32 2014/04/25 14:54:45 jmc Exp $ 2.\" 3.\" Copyright (c) 2007, 2008, 2012 Reyk Floeter <reyk@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 25 2014 $ 18.Dt SNMPD.CONF 5 19.Os 20.Sh NAME 21.Nm snmpd.conf 22.Nd Simple Network Management Protocol daemon configuration file 23.Sh DESCRIPTION 24.Nm 25is the configuration file for the 26.Xr snmpd 8 27daemon. 28.Sh SECTIONS 29The 30.Nm 31file is divided into three main sections: 32.Bl -tag -width xxxx 33.It Sy Macros 34User-defined variables may be defined and used later, simplifying the 35configuration file. 36.It Sy Global Configuration 37Global runtime settings for 38.Xr snmpd 8 . 39.It Sy User Configuration 40USM user definitions. 41.It Sy OID Configuration 42Custom configuration of SNMP object identifiers and values. 43.El 44.Pp 45The current line can be extended over multiple lines using a backslash 46.Pq Sq \e . 47Comments can be put anywhere in the file using a hash mark 48.Pq Sq # , 49and extend to the end of the current line. 50Care should be taken when commenting out multi-line text: 51the comment is effective until the end of the entire block. 52.Pp 53Argument names not beginning with a letter, digit, or underscore 54must be quoted. 55.Pp 56Additional configuration files can be included with the 57.Ic include 58keyword, for example: 59.Bd -literal -offset indent 60include "/etc/snmpd.conf.local" 61.Ed 62.Sh MACROS 63Macros can be defined that will later be expanded in context. 64Macro names must start with a letter, digit, or underscore, 65and may contain any of those characters. 66Macro names may not be reserved words (for example, 67.Ic community , 68.Ic system , 69or 70.Ic oid ) . 71Macros are not expanded inside quotes. 72.Pp 73For example: 74.Bd -literal -offset indent 75ext_addr="192.168.0.1" 76listen on $ext_addr 77.Ed 78.Sh GLOBAL CONFIGURATION 79The following options can be set globally: 80.Bl -tag -width Ds 81.It Ic filter-routes Pq Ic yes | no 82If set to 83.Ic yes , 84ask the kernel to filter route update messages on the routing socket. 85Routing table information will not be available, but CPU use will be 86reduced during bulk updates. 87The default is 88.Ic no . 89.It Ic listen on Ar address 90Specify the local address 91.Xr snmpd 8 92should listen on for incoming SNMP messages. 93.It Ic read-only community Ar string 94Specify the name of the read-only community. 95The default value is 96.Ar public . 97.It Ic read-write Pq Ic community Ar string Ic | disabled 98Specify the name of the read-write community, or disallow writes completely. 99The default value is 100.Ar private . 101.It Ic seclevel Pq Ic none | auth | enc 102Specify the lowest security level that 103.Xr snmpd 8 104accepts: 105.Bl -tag -width "auth" -offset ident 106.It Ic none 107Both authentication and encryption of messages is optional. 108This is the default value. 109.It Ic auth 110Authentication of messages is mandatory. 111.Xr snmpd 8 112will discard any messages that don't have a valid digest. 113Encryption of messages is optional. 114.It Ic enc 115Messages must be encrypted and must have a valid digest for authentication. 116Otherwise they will be discarded. 117.El 118.Pp 119If the chosen value is different from 120.Ic none 121.Xr snmpd 8 122will accept only SNMPv3 requests since older versions neither support 123authentication nor encryption. 124.It Ic socket Qo Ar path Qc Op Ic restricted | agentx 125Create a control socket at 126.Ar path . 127If 128.Ic restricted 129is specified, a restricted control socket will be created. 130If 131.Ic agentx 132is specified, a socket which speaks the AgentX protocol will be created. 133Multiple 134.Ic restricted 135and 136.Ic agentx 137sockets may be created. 138By default 139.Pa /var/run/snmpd.sock 140is created and no other sockets are created. 141.It Ic system contact Ar string 142Specify the name or description of the system contact, typically a 143name or an e-mail address. 144The default value is 145.Ar root@hostname 146using the hostname of the local machine. 147.It Ic system description Ar string 148Specify a description of the local system. 149The default value is the operating system identification as printed by the 150.Xr uname 1 151command using the 152.Fl a 153flag: 154.Bd -literal -offset indent 155OpenBSD myhost.example.com 4.2 GENERIC#595 i386 156.Ed 157.It Ic system location Ar string 158Specify the string describing the location of the local system, 159typically a physical location. 160The default value is an empty string. 161.It Ic system name Ar string 162Specify the name of the local system, typically a fully-qualified 163domain name. 164The default value is the hostname of the local system. 165.It Ic system oid Ar oid-string 166Specify the authoritative identification of the local system. 167The default value is 168.Ar 1.3.6.1.4.1.30155.23.1 169.Pq iso.org.dod.internet.private.enterprises.openbsd.23.1 170identifying a common 171.Ox 172system. 173.It Ic system services Ar number 174Specify a magic value which indicates the set of services that the local 175system may provide. 176Refer to the 177.Ar sysServices 178description in the SNMP MIB for details. 179.\"XXX describe the complicated services alg here 180.It Ic trap community Ar string 181Specify the name of the trap community. 182The default value is 183.Ar public . 184.It Ic trap handle Ar oid Qq Ar command 185Execute 186.Ic command 187upon receipt of an SNMP trap that begins with a prefix of 188.Ic oid . 189Alternately, the string 190.Qq Ic default 191may be used, in which case the prefix used is 192.Ic 1.3 . 193The invoked 194.Ar command 195will receive the following information about the trap on standard input, 196one per line, in this order: 197the resolved hostname of the host sending the trap, 198the IP address of the host sending the trap, 199and any variable bindings contained in the trap 200(the OID followed by the value, separated by a single space). 201.It Xo 202.Ic trap receiver Ar string 203.Op Ic oid Ar oid-string 204.Op Ic community Ar string 205.Xc 206Specify the address or FQDN of a remote trap receiver for outgoing traps 207sent by 208.Xr snmpd 8 . 209This option may be specified multiple times. 210The daemon will send outgoing traps using the revised SNMPv2 format and the 211configured trap community. 212The default community is specified by the global 213.Ic trap community 214option. 215.El 216.Sh USER CONFIGURATION 217Users for the SNMP User-based Security Model (USM, RFC 3414) must be 218defined in the configuration file: 219.Bl -tag -width xxxx 220.It Xo 221.Ic user Ar name 222.Op Ic authkey Ar key Ic auth Ar hmac 223.Op Ic enckey Ar key Ic enc Ar cipher 224.Xc 225Defines a known user. 226The 227.Ic authkey 228keyword is required to specify the digest key used to authenticate 229messages. 230If this keyword is omitted then authentication is disabled 231for this user account. 232Optionally the HMAC algorithm used for authentication can be specified. 233.Ar hmac 234must be either 235.Ic hmac-md5 236or 237.Ic hmac-sha1 . 238If omitted the default is 239.Ic hmac-sha1 . 240.Pp 241With 242.Ic enckey 243the encryption key used to encrypt and decrypt messages for privacy is defined. 244Without an 245.Ic enckey 246specification the user account will neither accept encrypted incoming 247messages nor will it encrypt outgoing messages. 248The 249.Ar enc 250algorithm can be either 251.Ic des 252or 253.Ic aes 254and defaults to 255.Ic des . 256.Pp 257Any user account that has encryption enabled requires authentication to 258be enabled too. 259.El 260.Sh OID CONFIGURATION 261It is possible to specify user-defined OIDs in the configuration file: 262.Bl -tag -width Ds 263.It Xo 264.Ic oid Ar oid-string 265.Ic name Ar name 266.Op Ic read-only | read-write 267.Op Ar type 268.Ar value 269.Xc 270Return the specified value to the client for this OID. 271The 272.Ic read-write 273option may allow the client to override it, 274and the type is either 275.Ic string 276or 277.Ic integer . 278.El 279.Sh FILES 280.Bl -tag -width "/etc/snmpd.conf" 281.It Pa /etc/snmpd.conf 282Default location of the configuration file. 283.El 284.Sh EXAMPLES 285The following example will tell 286.Xr snmpd 8 287to listen on localhost, override the default system OID, set the 288magic services value and provides some custom OID values: 289.Bd -literal -offset indent 290listen on 127.0.0.1 291 292system oid 1.3.6.1.4.1.30155.23.2 293system services 74 294 295oid 1.3.6.1.4.1.30155.42.1 name myName read-only string "humppa" 296oid 1.3.6.1.4.1.30155.42.2 name myStatus read-only integer 1 297.Ed 298.Pp 299The next example will enforce SNMPv3 with authenticated and encrypted 300communication and the user-based security model. 301The configuration defines two users, 302the first one is using the 303.Ic aes 304encryption algorithm and the second one the default 305.Ic des 306algorithm. 307.Bd -literal -offset indent 308seclevel enc 309 310user "xaver" authkey "password123" enc aes enckey "321drowssap" 311user "traudl" authkey "password456" enckey "654drowssap" 312.Ed 313.Sh SEE ALSO 314.Xr snmpctl 8 , 315.Xr snmpd 8 316.Sh HISTORY 317The 318.Nm 319file format first appeared in 320.Ox 4.3 . 321.Sh AUTHORS 322The 323.Xr snmpd 8 324program was written by 325.An Reyk Floeter Aq Mt reyk@openbsd.org . 326