1.\" $OpenBSD: snmp.1,v 1.12 2020/01/21 07:00:34 jmc Exp $ 2.\" 3.\" Copyright (c) 2019 Martijn van Duren <martijn@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: January 21 2020 $ 18.Dt SNMP 1 19.Os 20.Sh NAME 21.Nm snmp 22.Nd simple SNMP client 23.Sh SYNOPSIS 24.Nm 25.Cm get | getnext | bulkget 26.Op Ar options 27.Ar agent 28.Ar oid ... 29.Nm 30.Cm walk | bulkwalk 31.Op Ar options 32.Ar agent 33.Op Ar oid 34.Nm 35.Cm set 36.Op Ar options 37.Ar agent 38.Ar varoid type value 39.Oo Ar varoid type value Oc ... 40.Nm 41.Cm trap 42.Op Ar options 43.Ar agent uptime trapoid 44.Oo Ar varoid type value Oc ... 45.Nm 46.Cm df 47.Op Ar options 48.Ar agent 49.Nm 50.Cm mibtree 51.Op Fl O Ar fns 52.Sh DESCRIPTION 53The 54.Nm 55utility is a simple SNMP client. 56.Pp 57The subcommands are as follows: 58.Bl -tag -width Ds 59.It Xo 60.Nm snmp 61.Cm get 62.Op Ar options 63.Ar agent oid ... 64.Xc 65Retrieve the varbind for 66.Ar oid 67from the 68.Ar agent . 69If more than one 70.Ar oid 71is specified, retrieve the varbind for each one. 72.It Xo 73.Nm snmp 74.Cm getnext 75.Op Ar options 76.Ar agent oid ... 77.Xc 78Retrieve the varbind that follows 79.Ar oid 80from the 81.Ar agent . 82If more than one 83.Ar oid 84is specified, retrieve the varbind following each one of them. 85.It Nm snmp Cm walk Oo Ar options Oc Ar agent Op Ar oid 86Retrieve all the varbinds that are branches of 87.Ar oid 88from the 89.Ar agent . 90This uses the 91.Cm getnext 92subcommand internally and requests a single varbind at a time. 93If no 94.Ar oid 95is specified it defaults to mib-2 96.Pq .1.3.6.1.2.1 . 97.It Xo 98.Nm snmp 99.Cm bulkget 100.Op Ar options 101.Ar agent Ar oid ... 102.Xc 103Retrieve the next 10 varbinds following each 104.Ar oid 105from the 106.Ar agent . 107This command is not available for 108.Fl v Cm 1 . 109.It Xo 110.Nm snmp 111.Cm bulkwalk 112.Op Ar options 113.Ar agent 114.Op Ar oid 115.Xc 116Retrieve all the varbinds from the 117.Ar agent 118that are branches of 119.Ar oid . 120This uses the 121.Cm bulkget 122subcommand internally to retrieve multiple varbinds at a time. 123This command is not available for 124.Fl v Cm 1 . 125.It Xo 126.Nm snmp 127.Cm set 128.Op Ar options 129.Ar agent varoid type value ... 130.Xc 131Set one or more 132.Ar varoid to a new 133.Ar value . 134The format of the 135.Ar varoid type value 136triple is described in 137.Sx Data types , 138below. 139.It Xo 140.Nm snmp 141.Cm trap 142.Op Ar options 143.Ar agent uptime trapoid 144.Op Ar varoid type value ... 145.Xc 146Send a trap message to the 147.Ar agent . 148The 149.Ar uptime 150is specified in timeticks 151.Pq centiseconds 152or defaults to the system uptime if an empty string is given. 153The 154.Ar trapoid 155is the identification OID used by the trap handler to determine its action. 156This command is not available for 157.Fl v Cm 1 . 158.It Xo 159.Nm 160.Cm df 161.Op Ar options 162.Ar agent 163.Xc 164An SNMP based version of the 165.Xr df 1 166command. 167If no size suffix is shown the sizes are in kilobytes. 168.It Nm Cm mibtree Op Fl O Ar fnS 169Dump the tree of compiled-in MIB objects. 170.El 171.Pp 172The 173.Ar options 174are as follows: 175.Bl -tag -width Ds 176.It Fl A Ar authpass 177The authentication password for the user. 178This will be transformed to 179.Ar localauth . 180This option is only used by 181.Fl v Cm 3 . 182.It Fl a Ar digest 183Set the digest 184.Pq authentication 185protocol. 186Options are 187.Cm MD5 , 188.Cm SHA , 189.Cm SHA-224 , 190.Cm SHA-256 , 191.Cm SHA-384 192or 193.Cm SHA-512 . 194This option defaults to 195.Cm MD5 . 196This option is only used by 197.Fl v Cm 3 . 198.It Fl C Ar appopt 199For the 200.Cm bulkget , 201.Cm bulkwalk , 202.Cm df , 203and 204.Cm walk 205subcommands, set the application specific 206.Ar appopt 207options by supplying a string of one or more 208of the following modifier letters: 209.Bl -tag -width Ds 210.It Cm c 211For 212.Cm walk 213and 214.Cm bulkwalk , 215disable checking the order of MIBs. 216On some devices that return MIBs out of order, 217this may cause an infinite loop. 218.It Cm E Ar endoid 219For 220.Cm walk , 221walk the tree up to but excluding 222.Ar endoid . 223The blank before 224.Ar endoid 225is mandatory. 226.It Cm h 227For 228.Cm df 229print the output in 230.Dq human-readable 231format. 232.It Cm I 233For 234.Cm walk , 235do not fall back to returning the original MIB via a 236.Cm get 237request. 238.It Cm i 239For 240.Cm walk 241and 242.Cm bulkwalk , 243always do a 244.Cm get 245request on the specified 246.Ar oid 247first. 248.It Cm n Ns Ar nonrep 249For 250.Cm bulkget 251and 252.Cm bulkwalk , 253Set the non-repeaters field in the request to the non-negative integer 254.Ar nonrep . 255This causes the first 256.Ar nonrep 257.Ar oid 258arguments to only return a single MIB instead of 259.Ar maxrep . 260This value defaults to 0. 261No blank is allowed before 262.Ar nonrep . 263.It Cm p 264For 265.Cm walk 266or 267.Cm bulkwalk , 268also show a summary of the total variables received. 269.It Cm r Ns Ar maxrep 270For 271.Cm bulkget , 272.Cm bulkwalk 273and 274.Cm df , 275set the max-repetitions field in the request to the positive integer 276.Ar maxrep . 277This determines the amount of MIBs to return for each specified OID. 278This value defaults to 10. 279No blank is allowed before 280.Ar maxrep . 281.It Cm s Ar skipoid 282For 283.Cm walk 284or 285.Cm bulkwalk 286don't include 287.Ar skipoid 288or its children in the walk output. 289The blank before 290.Ar skipoid 291is mandatory. 292.It Cm t 293For 294.Cm walk , 295Show how long it took to walk the entire tree. 296.El 297.It Fl c Ar community 298Set the 299.Ar community 300string. 301Defaults to 302.Cm public . 303This option is only used by 304.Fl v Cm 1 305and 306.Fl v Cm 2c . 307.It Fl e Ar secengineid 308The USM security engine id. 309Under normal circumstances this value is discovered via snmpv3 discovery and 310does not need to be specified. 311This option is only used by 312.Fl v Cm 3 . 313.It Fl E Ar ctxengineid 314The snmpv3 context engine id. 315Most of the time this value can be safely ignored. 316This option is only used by 317.Fl v Cm 3 . 318.It Fl K Ar localpriv 319The localized privacy password for the user in hexadecimal format 320.Po 321optionally prefixed with a 322.Cm 0x 323.Pc . 324This option is only used by 325.Fl v Cm 3 . 326.It Fl k Ar localauth 327The localized authentication password for the user in hexadecimal format 328.Po 329optionally prefixed with a 330.Cm 0x 331.Pc . 332This option is only used by 333.Fl v Cm 3 . 334.It Fl l Ar seclevel 335The security level. 336Values can be 337.Cm noAuthNoPriv Pq default , 338.Cm authNoPriv 339.Po 340requires either 341.Fl A 342or 343.Fl k 344.Pc 345or 346.Cm authPriv 347.Po 348requires either 349.Fl X 350or 351.Fl K 352in addition to the 353.Cm authNoPriv 354requirements 355.Pc . 356This option is only used by 357.Fl v Cm 3 . 358.It Fl n Ar ctxname 359Sets the context name. 360Defaults to an empty string. 361This option is only used by 362.Fl v Cm 3 . 363.It Fl O Ar output 364Set the 365.Ar output 366options by supplying a string of one or more 367of the following modifier letters: 368.Bl -tag -width 1n 369.It Cm a 370Print the varbind string unchanged 371rather than replacing non-printable bytes with dots. 372.It Cm f 373When displaying an OID, include the full list of MIB objects. 374By default only the last textual MIB object is shown. 375.It Cm n 376Display the OID numerically. 377.It Cm Q 378Remove the type information. 379.It Cm q 380Remove the type information and the equal sign. 381.It Cm S 382Display the MIB name and the type information. 383This is the default behaviour. 384.It Cm v 385Only display the varbind value, removing the OID. 386.It Cm x 387Display the varbind string values as hexadecimal strings. 388.El 389.Pp 390The 391.Cm mibtree 392subcommand may only use the 393.Op Fl fnS 394output options; 395no output options are available for 396.Cm trap . 397.It Fl r Ar retries 398Set the number of 399.Ar retries 400in case of packet loss. 401Defaults to 5. 402.It Fl t Ar timeout 403Set the 404.Ar timeout 405to wait for a reply, in seconds. 406Defaults to 1. 407.It Fl u Ar user 408Sets the username. 409If 410.Fl v Cm 3 411is used this option is required. 412This option is only used by 413.Fl v Cm 3 . 414.It Fl v Ar version 415Set the snmp protocol 416.Ar version 417to either 418.Cm 1 , 419.Cm 2c 420or 421.Cm 3 . 422Currently defaults to 423.Cm 2c . 424.It Fl X Ar privpass 425The privacy password for the user. 426This will be tansformed to 427.Ar localpriv . 428This option is only used by 429.Fl v Cm 3 . 430.It Fl x Ar cipher 431Sets the cipher 432.Pq privacy 433protocol. 434Options are 435.Cm DES 436and 437.Cm AES . 438This option is only used by 439.Fl v Cm 3 . 440.It Fl Z Ar boots , Ns Ar time 441Set the engine boots and engine time. 442Under normal circumstances this value is discovered via snmpv3 discovery and 443does not need to be specified. 444This option is only used by 445.Fl v Cm 3 . 446.El 447.Pp 448The syntax for the 449.Ar agent 450argument is 451.Oo Ar protocol : Oc Ns Ar address , 452with the following format: 453.Bl -column udp6XXXtcp6X address -offset indent 454.It Ar protocol Ta Ar address 455.It Cm udp | tcp Ta Ar hostname Ns Oo Pf : Ar port Oc | 456.Ar IPv4-address Ns Op Pf : Ar port 457.It Cm udp6 | tcp6 Ta Ar hostname Ns Oo Pf : Ar port Oc | 458.Cm \&[ Ns Ar IPv6-address Ns Cm \&] Ns Oo Pf : Ar port Oc | 459.Ar IPv6-address Ns Pf : Ar port 460.It Cm unix Ta Ar pathname 461.El 462.Pp 463The default 464.Ar protocol 465is 466.Cm udp 467and the default 468.Ar port 469is 161, except for the 470.Cm trap 471subcommand, which uses 162. 472.Cm udpv6 473and 474.Cm udpipv6 475are aliases for 476.Cm udp6 ; 477.Cm tcpv6 478and 479.Cm tcpipv6 480for 481.Cm tcp6 . 482To specify an IPv6-address without a 483.Ar port , 484the 485.Ar IPv6-address 486must be enclosed in square brackets. 487If the square brackets are omitted, 488the value after the last colon is always interpreted as a 489.Ar port . 490.Ss Data types 491Additional data sent to the server is formatted by specifying one or more 492triples of 493.Ar varoid , 494.Ar type , 495and 496.Ar value . 497Supported types are: 498.Bl -tag -width 1n -offset indent 499.It Cm a 500An IPv4 Address. 501.It Cm b 502A bitstring. 503A list of individual bit offsets separated by comma, space or tab. 504Must be supplied as a single argument. 505.It Cm c 506A counter32. 507.It Cm d 508A decimal string. 509A list of individual bytes in decimal form separated by space or tab. 510.It Cm i 511An integer. 512.It Cm n 513A null object. 514.It Cm o 515An OID. 516.It Cm s 517A regular string. 518.It Cm t 519Timeticks in centiseconds. 520.It Cm u 521Unsigned integer. 522Actually a normal integer for compatibility with netsnmp. 523.It Cm x 524A hex string. 525Similar to a decimal string, but in hexadecimal format. 526.El 527.Sh SEE ALSO 528.Xr snmpd 8 529.Sh HISTORY 530The 531.Nm 532program first appeared in 533.Ox 6.6 . 534.Sh AUTHORS 535The 536.Nm 537program was written by 538.An Martijn van Duren Aq Mt martijn@openbsd.org . 539