1.\" $OpenBSD: snmpd.conf.5,v 1.64 2024/02/06 12:39:13 martijn 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: February 6 2024 $ 18.Dt SNMPD.CONF 5 19.Os 20.Sh NAME 21.Nm snmpd.conf 22.Nd SNMP daemon configuration file 23.Sh DESCRIPTION 24.Nm 25is the configuration file for the 26.Xr snmpd 8 27daemon. 28.Pp 29The 30.Nm 31file is divided into the following 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 blocklist Ar oid 82Remove the 83.Ar oid 84subtree from view. 85Multiple 86.Ic blocklist 87statements are supported. 88.It Ic filter-routes Pq Ic yes | no 89If set to 90.Ic yes , 91ask the kernel to filter route update messages on the routing socket. 92Routing table information will not be available, but CPU use will be 93reduced during bulk updates. 94The default is 95.Ic no . 96.It Ic listen on Oo Ic tcp | udp Oc Ar address Oo Ic port Ar port Oc Op Ar flags 97Specify the local 98.Ar address 99.Xr snmpd 8 100should listen on for incoming SNMP messages, 101or 102.Cm any 103to listen on all local IPv4 and IPv6 addresses. 104Multiple 105.Ic listen on 106statements are supported. 107If no 108.Ic listen on 109statement is present, the default is 110.Ic listen on Cm any . 111.Pp 112The 113.Ar flags 114are as follows: 115.Bl -tag -width Ds 116.It Ic read 117Accept get, getnext and bulkget requests. 118.It Ic write 119Accepts set requests. 120.It Ic notify 121Accepts trapv1 and trapv2 requests. 122.It Ic snmpv1 123Enable SNMPv1 subsystem on the listen address. 124.It Ic snmpv2c 125Enable SNMPv2c subsystem on the listen address. 126.It Ic snmpv3 127Enable SNMPv3 subsystem on the listen address. 128.El 129.Pp 130The default protocol is 131.Ic udp . 132The default 133.Ar port 134is 161, unless 135.Ic notify 136is the only permission flag; which sets the 137.Ar port 138to 162. 139If no permission flags are specified it defaults to 140.Dq Ic read Ic write , 141or 142.Ic notify 143when 144.Ar port 145is 162. 146If no subsystem flags are specified, it defaults to 147.Ic snmpv3 . 148.Pp 149Having 150.Ic notify 151set requires at least one 152.Ic trap handle 153statement. 154.It Ic agentx Oo Ic path Ar path Oc Oo Ic owner Ar owner Oc Oo Ic group Ar group Oc Oo Ic mode Ar mode Oc 155Set up an agentx master socket at 156.Ar path 157and defaults to 158.Pa /var/agentx/master . 159Socket owner, group, and permissions can be set with 160.Ar owner , 161.Ar group , 162and 163.Ar mode 164respectively and defaults to root, _agentx, and 660. 165Multiple 166.Ic agentx 167statements are supported. 168Only unix sockets are supported. 169.It Ic engineid Oo Ic pen Ar enterprise Oc Ar format 170Set the snmp engineid, used for instance identification and key 171generation for the 172.Ic user 173.Ar auth 174and 175.Ar key . 176.Ar enterprise 177specifies the private enterprise number of the instance and can be either an 178integer or 179.Ic openbsd 180.Pq default . 181.Pp 182.Ar format 183can be one of the following: 184.Bl -tag -width Ds 185.It Ic ipv4 Ar address 186The engineID's format identifier is set to 1 and the ipv4 187.Ar address 188is used in the format. 189.It Ic ipv6 Ar address 190The engineID's format identifier is set to 2 and the ipv6 191.Ar address 192is used in the format. 193.It Ic mac Ar address 194The engineID's format identifier is set to 3 and the mac 195.Ar address 196is used in the format. 197.It Ic text Ar text 198The engineID's format identifier is set to 4 and the ASCII 199.Ar text 200is used in the format. 201.It Ic octets Ar octetstring 202The engineID's format identifier is set to 5 and the 203.Ar octetstring 204in hexadecimal is used in the format. 205.It Ic hosthash Op Ar hostname 206The engineID's format identifier is set to 129 and the first 27 bytes of the 207sha256 hash of the 208.Ar hostname 209are used in the format. 210This option is only valid for 211.Ar enterprise 212.Ic openbsd . 213If used for the local engineID, then 214.Ar hostname 215defaults to the value of 216.Xr hostname 1 . 217This format is the default. 218.It Ar number Ar octetstring 219The engineID's format identifier is set to 220.Ar number 221and the 222.Ar octetstring 223in hexadecimal is used in the format. 224This format is only available if 225.Ar enterprise 226is not 227.Ic openbsd . 228.It Ic agentid Ar octetstring 229RFC1910 legacy format. 230.Ar octetstring 231must be 8 bytes 232.Pq or 16 characters in hexadecimal format . 233.El 234.It Ic mib directory Ar path 235Specify which directories to recursively search for MIB files. 236Multiple directories can be specified. 237If no directory is specified it defaults to 238.Pa /usr/share/snmp/mibs . 239.It Ic read-only community Ar string 240Specify the name of the read-only community. 241There is no default value. 242.It Ic read-write Ic community Ar string 243Specify the name of the read-write community. 244There is no default value. 245.It Ic seclevel Pq Ic none | auth | enc 246Specify the lowest security level that 247.Xr snmpd 8 248accepts on SNMPv3: 249.Bl -tag -width "auth" -offset ident 250.It Ic none 251Both authentication and encryption of messages is optional. 252.It Ic auth 253Authentication of messages is mandatory. 254.Xr snmpd 8 255will discard any messages that don't have a valid digest. 256Encryption of messages is optional. 257.It Ic enc 258Messages must be encrypted and must have a valid digest for authentication. 259Otherwise they will be discarded. 260This is the default value. 261.El 262.It Ic system contact Ar string 263Specify the name or description of the system contact, typically a 264name or an email address. 265The default value is 266.Ar root@hostname 267using the hostname of the local machine. 268.It Ic system description Ar string 269Specify a description of the local system. 270The default value is the operating system identification as printed by the 271.Xr uname 1 272command using the 273.Fl a 274flag: 275.Bd -literal -offset indent 276OpenBSD myhost.example.com 4.2 GENERIC#595 i386 277.Ed 278.It Ic system location Ar string 279Specify the string describing the location of the local system, 280typically a physical location. 281The default value is an empty string. 282.It Ic system name Ar string 283Specify the name of the local system, typically a fully-qualified 284domain name. 285The default value is the hostname of the local system. 286.It Ic system oid Ar oid-string 287Specify the authoritative identification of the local system. 288The default value is 289.Ar 1.3.6.1.4.1.30155.23.1 290.Pq iso.org.dod.internet.private.enterprises.openbsd.23.1 291identifying a common 292.Ox 293system. 294.It Ic system services Ar number 295Specify a magic value which indicates the set of services that the local 296system may provide. 297Refer to the 298.Ar sysServices 299description in the SNMP MIB for details. 300The value is given in decimal. 301.\"XXX describe the complicated services alg here 302.It Ic trap community Ar string 303Specify the name of the trap community. 304There is no default value. 305.It Ic trap handle Ar oid Qq Ar command 306Execute 307.Ic command 308upon receipt of an SNMP trap that begins with a prefix of 309.Ic oid . 310Alternately, the string 311.Qq Ic default 312may be used, in which case the prefix used is 313.Ic 1.3 . 314The invoked 315.Ar command 316will receive the following information about the trap on standard input, 317one per line, in this order: 318the resolved hostname of the host sending the trap, 319the IP address of the host sending the trap, 320and any variable bindings contained in the trap 321(the OID followed by the value, separated by a single space). 322This option requires at least one 323.Ic listen on 324statement with a 325.Ic notify 326flag set. 327Traps over SNMPv3 are currently unsupported. 328.It Xo 329.Ic trap receiver Ar address 330.Op Ic oid Ar oid-string 331.Ic snmpv2c 332.Op Ic community Ar string 333.Op Ic source-address Ar address 334.Xc 335Specify the 336.Ar address 337or FQDN of a remote trap receiver for outgoing traps 338sent by 339.Xr snmpd 8 . 340This option may be specified multiple times. 341The daemon will send outgoing traps in 342.Ic snmpv2c 343format. 344The default community is specified by the global 345.Ic trap community 346option. 347The IPv4 or IPv6 source address of the traps can be enforced using 348.It Xo 349.Ic trap receiver Ar address 350.Op Ic oid Ar oid-string 351.Op Ic snmpv3 352.Ic user Ar name Oo Ic seclevel Ar level Oc 353.Op Ic source-address Ar address 354.Xc 355Specify the 356.Ar address 357or FQDN of a remote trap receiver for outgoing traps 358sent by 359.Xr snmpd 8 . 360This option may be specified multiple times. 361The daemon will send outgoing traps in 362.Ic snmpv3 363format. 364.Ic user 365must point to an existing global 366.Ic user . 367If 368.Ic seclevel 369is not defined, it defaults to the global 370.Ic seclevel 371option. 372The IPv4 or IPv6 source address of the traps can be enforced using 373.Ic source-address . 374.El 375.Sh USER CONFIGURATION 376Users for the SNMP User-based Security Model (USM, RFC 3414) must be 377defined in the configuration file: 378.Bl -tag -width xxxx 379.It Xo 380.Ic user Ar name 381.Op Ic authkey Ar key Ic auth Ar hmac 382.Op Ic enckey Ar key Ic enc Ar cipher 383.Xc 384Defines a known user. 385The 386.Ic authkey 387keyword is required to specify the digest key used to authenticate 388messages. 389If this keyword is omitted then authentication is disabled 390for this user account. 391Optionally the HMAC algorithm used for authentication can be specified. 392.Ar hmac 393must be either 394.Ic hmac-md5 , 395.Ic hmac-sha1 , 396.Ic hmac-sha224 , 397.Ic hmac-sha256 , 398.Ic hmac-sha384 , 399or 400.Ic hmac-sha512 . 401If omitted, the default is 402.Ic hmac-sha1 . 403.Pp 404With 405.Ic enckey 406the encryption key used to encrypt and decrypt messages for privacy is defined. 407Without an 408.Ic enckey 409specification the user account will neither accept encrypted incoming 410messages nor will it encrypt outgoing messages. 411The 412.Ar enc 413algorithm can be either 414.Ic des 415or 416.Ic aes 417and defaults to 418.Ic aes . 419.Pp 420Any user account that has encryption enabled requires authentication to 421be enabled too. 422.El 423.Sh OID CONFIGURATION 424It is possible to specify user-defined OIDs in the configuration file: 425.Bl -tag -width Ds 426.It Xo 427.Ic oid Ar oid-string 428.Ic name Ar name 429.Op Ic read-only | read-write 430.Op Ar type 431.Ar value 432.Xc 433Return the specified value to the client for this OID. 434The 435.Ic read-write 436option may allow the client to override it, 437and the type is either 438.Ic string 439or 440.Ic integer . 441.El 442.Sh FILES 443.Bl -tag -width /etc/examples/snmpd.conf -compact 444.It Pa /etc/snmpd.conf 445Default location of the configuration file. 446.It Pa /etc/examples/snmpd.conf 447Example configuration file. 448.El 449.Sh EXAMPLES 450The following example will tell 451.Xr snmpd 8 452to listen on localhost for SNMPv2c messages only with the community 453.Dq 8LHQtm1QLGzk , 454override the default system OID, set the magic services value, 455and provide some custom OID values: 456.Bd -literal -offset indent 457listen on 127.0.0.1 snmpv2c 458read-only community 8LHQtm1QLGzk 459 460system oid 1.3.6.1.4.1.30155.23.2 461system services 74 462 463oid 1.3.6.1.4.1.30155.42.1 name myName read-only string "humppa" 464oid 1.3.6.1.4.1.30155.42.2 name myStatus read-only integer 1 465.Ed 466.Pp 467The next example will enforce SNMPv3 with authenticated and encrypted 468communication and the user-based security model. 469The configuration defines several users using varying encryption and 470authentication algorithms. 471.Bd -literal -offset indent 472seclevel enc 473 474user "mgmt" auth hmac-sha256 authkey "password123" enc aes enckey "321drowssap" 475user "hans" auth hmac-sha1 authkey "password456" enc aes enckey "654drowssap" 476user "sophie" auth hmac-md5 authkey "password789" enc des enckey "987drowssap" 477.Ed 478.Sh SEE ALSO 479.Xr snmp 1 , 480.Xr snmpd 8 481.Sh HISTORY 482The 483.Nm 484file format first appeared in 485.Ox 4.3 . 486.Sh AUTHORS 487The 488.Xr snmpd 8 489program was written by 490.An Reyk Floeter Aq Mt reyk@openbsd.org . 491