Annotation of src/usr.bin/snmp/snmp.1, Revision 1.1
1.1 ! martijn 1: .\" $OpenBSD$
! 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$
! 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
! 26: .Op Fl c Ar community
! 27: .Op Fl O Cm afnQqSvx
! 28: .Op Fl r Ar retries
! 29: .Op Fl t Ar timeout
! 30: .Op Fl v Ar version
! 31: .Ar agent
! 32: .Ar oid ...
! 33: .Nm
! 34: .Cm walk
! 35: .Op Fl C Cm cIipt
! 36: .Op Fl C Cm E Ar endoid
! 37: .Op Fl c Ar community
! 38: .Op Fl O Cm afnQqSvx
! 39: .Op Fl r Ar retries
! 40: .Op Fl t Ar timeout
! 41: .Op Fl v Ar version
! 42: .Ar agent
! 43: .Op Ar oid
! 44: .Nm
! 45: .Cm bulkget
! 46: .Op Fl C Cm n Ns Ar nonrep Ns Cm r Ns Ar maxrep
! 47: .Op Fl c Ar community
! 48: .Op Fl O Cm afnQqSvx
! 49: .Op Fl r Ar retries
! 50: .Op Fl t Ar timeout
! 51: .Op Fl v Ar version
! 52: .Ar agent
! 53: .Ar oid ...
! 54: .Nm
! 55: .Cm bulkwalk
! 56: .Op Fl C Cm cipn Ns Ar nonrep Ns Cm r Ns Ar maxrep
! 57: .Op Fl c Ar community
! 58: .Op Fl O Cm afnQqSvx
! 59: .Op Fl r Ar retries
! 60: .Op Fl t Ar timeout
! 61: .Op Fl v Ar version
! 62: .Ar agent
! 63: .Op Ar oid
! 64: .Nm
! 65: .Cm trap
! 66: .Op Fl c Ar community
! 67: .Op Fl v Ar version
! 68: .Ar agent uptime trapoid
! 69: .Oo Ar varoid type value Oc ...
! 70: .Nm
! 71: .Cm mibtree
! 72: .Op Fl O Cm fnS
! 73: .Sh DESCRIPTION
! 74: The
! 75: .Nm
! 76: utility is a simple SNMP client.
! 77: .Pp
! 78: The subcommands are as follows:
! 79: .Bl -tag -width bulkwalk
! 80: .It Cm get
! 81: Retrieve the MIB for
! 82: .Ar oid
! 83: from the
! 84: .Ar agent .
! 85: If more than one
! 86: .Ar oid
! 87: is specified, retrieve the MIB for each one.
! 88: .It Cm getnext
! 89: Retrieve the MIB that follows
! 90: .Ar oid
! 91: from the
! 92: .Ar agent .
! 93: If more than one
! 94: .Ar oid
! 95: is specified, retrieve the MIB following each one of them.
! 96: .It Cm walk
! 97: Retrieve all the MIBs that are branches of
! 98: .Ar oid
! 99: from the
! 100: .Ar agent .
! 101: This uses the
! 102: .Cm getnext
! 103: subcommand internally and requests a single MIB at a time.
! 104: If no OID is specified it defaults to mib-2
! 105: .Pq .1.3.6.1.2.1 .
! 106: .It Cm bulkget
! 107: Retrieve the next 10 MIBs following each
! 108: .Ar oid
! 109: from the
! 110: .Ar agent .
! 111: This command is not available for
! 112: .Fl v Cm 1 .
! 113: .It Cm bulkwalk
! 114: Retrieve all the MIBs from the
! 115: .Ar agent
! 116: that are branches of
! 117: .Ar oid .
! 118: This uses the
! 119: .Cm bulkget
! 120: subcommand internally to retrieve multiple MIBs at a time.
! 121: This command is not available for
! 122: .Fl v Cm 1 .
! 123: .It Cm trap
! 124: Send a trap message to the
! 125: .Ar agent .
! 126: The
! 127: .Ar uptime
! 128: is specified in timeticks
! 129: .Pq centiseconds
! 130: or defaults to the system uptime if an empty string is given.
! 131: The
! 132: .Ar trapoid
! 133: is the identification OID used by the trap handler to determine its action.
! 134: The triple
! 135: .Op Ar varoid , type, value
! 136: is described below
! 137: .Sx Data types .
! 138: This command is not available for
! 139: .Fl v Cm 1 .
! 140: .It Cm mibtree
! 141: Dump the tree of compiled-in MIB objects.
! 142: .El
! 143: .Pp
! 144: The options are as follows:
! 145: .Bl -tag -width Ds
! 146: .It Fl C Ar appopt
! 147: Set the application specific
! 148: .Ar appopt
! 149: options by supplying a string of one or more
! 150: of the following modifier letters:
! 151: .Bl -tag -width Ds
! 152: .It Cm c
! 153: During a
! 154: .Cm walk
! 155: or
! 156: .Cm bulkwalk ,
! 157: disable checking the order of MIBs.
! 158: On some devices that return MIBs out of order,
! 159: this may cause an infinite loop.
! 160: .It Cm E Ar endoid
! 161: Walk the tree up to but excluding
! 162: .Ar endoid .
! 163: .It Cm I
! 164: If no branches are found during a
! 165: .Cm walk ,
! 166: do not fall back to returning the original MIB via a
! 167: .Cm get
! 168: request.
! 169: .It Cm i
! 170: Before starting a
! 171: .Cm walk
! 172: or
! 173: .Cm bulkwalk ,
! 174: always do a
! 175: .Cm get
! 176: request on the specified
! 177: .Ar oid
! 178: first.
! 179: .It Cm n Ns Ar nonrep
! 180: Set the non-repeaters field in the request to the non-negative integer
! 181: .Ar nonrep .
! 182: This causes the first
! 183: .Ar nonrep
! 184: .Ar oid
! 185: arguments to only return a single MIB instead of
! 186: .Ar maxrep .
! 187: This value defaults to 0.
! 188: .It Cm p
! 189: At the end of a
! 190: .Cm walk
! 191: or
! 192: .Cm bulkwalk ,
! 193: show a summary of the total variables received.
! 194: .It Cm r Ns Ar maxrep
! 195: Set the max-repetitions field in the request to the positive integer
! 196: .Ar maxrep .
! 197: For
! 198: .Cm bulkget
! 199: or
! 200: .Cm bulkwalk
! 201: this determines the amount of MIBs to return for each specified OID.
! 202: This value defaults to 10.
! 203: .It Cm t
! 204: Show how long it took to
! 205: .Cm walk
! 206: the entire tree.
! 207: .El
! 208: .It Fl c Ar community
! 209: Set the
! 210: .Ar community
! 211: string.
! 212: Defaults to
! 213: .Cm public .
! 214: .It Fl O Ar output
! 215: Set the
! 216: .Ar output
! 217: options by supplying a string of one or more
! 218: of the following modifier letters:
! 219: .Bl -tag -width 1n
! 220: .It Cm a
! 221: Print the varbind string unchanged
! 222: rather than replacing non-printable bytes with dots.
! 223: .It Cm f
! 224: When displaying an OID, include the full list of MIB objects.
! 225: By default only the last textual MIB object is shown.
! 226: .It Cm n
! 227: Display the OID numerically.
! 228: .It Cm Q
! 229: Remove the type information.
! 230: .It Cm q
! 231: Remove the type information and the equal sign.
! 232: .It Cm S
! 233: Display the MIB name and the type information.
! 234: This is the default behaviour.
! 235: .It Cm v
! 236: Only display the varbind value, removing the OID.
! 237: .It Cm x
! 238: Display the varbind string values as hexadecimal strings.
! 239: .El
! 240: .It Fl r Ar retries
! 241: Set the number of
! 242: .Ar retries
! 243: in case of packet loss.
! 244: Defaults to 5.
! 245: .It Fl t Ar timeout
! 246: Set the
! 247: .Ar timeout
! 248: to wait for a reply, in seconds.
! 249: Defaults to 1.
! 250: .It Fl v Ar version
! 251: Set the snmp protocol
! 252: .Ar version
! 253: to either
! 254: .Cm 1
! 255: or
! 256: .Cm 2c .
! 257: Currently defaults to
! 258: .Cm 2c .
! 259: .El
! 260: .Pp
! 261: The syntax for the
! 262: .Ar agent
! 263: argument is
! 264: .Oo Ar protocol : Oc Ns Ar address
! 265: with the follwing forms:
! 266: .Bl -column udp6XXXtcp6X address -offset indent
! 267: .It Ar protocol Ta Ar address
! 268: .It Cm udp | tcp Ta Ar hostname Ns Oo Pf : Ar port Oc |
! 269: .Ar IPv4-address Ns Op Pf : Ar port
! 270: .It Cm udp6 | tcp6 Ta Ar hostname Ns Oo Pf : Ar port Oc |
! 271: .Cm \&[ Ns Ar IPv6-address Ns Cm \&] Ns Oo Pf : Ar port Oc |
! 272: .Ar IPv6-address Ns Pf : Ar port
! 273: .It Cm unix Ta Ar pathname
! 274: .El
! 275: .Pp
! 276: The default
! 277: .Ar protocol
! 278: is
! 279: .Cm udp
! 280: and the default
! 281: .Ar port
! 282: is 161; except for the
! 283: .Nm snmp Cm trap
! 284: command which uses 162.
! 285: .Cm udpv6
! 286: and
! 287: .Cm udpipv6
! 288: are aliases for
! 289: .Cm udp6 ;
! 290: .Cm tcpv6
! 291: and
! 292: .Cm tcpipv6
! 293: for
! 294: .Cm tcp6 .
! 295: To specify an IPv6-address without a
! 296: .Ar port ,
! 297: the
! 298: .Ar IPv6-address
! 299: must be enclosed in square brackets.
! 300: If the square brackets are omitted,
! 301: the value after the last colon is always interpreted as a
! 302: .Ar port .
! 303: .Ss Data types
! 304: Additional data sent to the server is formatted by specifying one or more
! 305: triples of
! 306: .Ar varoid ,
! 307: .Ar type ,
! 308: and
! 309: .Ar value .
! 310: Supported types are:
! 311: .Bl -tag -width 1n
! 312: .It Cm a
! 313: An IPv4 Address.
! 314: .It Cm b
! 315: A bitstring.
! 316: A list of individual bit offsets separated by comma, space or tab.
! 317: Must be supplied as a single argument.
! 318: .It Cm c
! 319: A counter32.
! 320: .It Cm d
! 321: A decimal string.
! 322: A list of individual bytes in decimal form separated by space or tab.
! 323: .It Cm i
! 324: An integer.
! 325: .It Cm n
! 326: A null object.
! 327: .It Cm o
! 328: An OID.
! 329: .It Cm s
! 330: A regular string.
! 331: .It Cm t
! 332: Timeticks in centiseconds.
! 333: .It Cm u
! 334: Unsigned integer.
! 335: Actually a normal integer for compatibility with netsnmp.
! 336: .It Cm x
! 337: A hex string.
! 338: Similar to a decimal string, but in hexadecimal format.
! 339: .El
! 340: .Sh SEE ALSO
! 341: .Xr snmpd 8
! 342: .Sh HISTORY
! 343: The
! 344: .Nm
! 345: program first appeared in
! 346: .Ox 6.6 .
! 347: .Sh AUTHORS
! 348: The
! 349: .Nm
! 350: program was written by
! 351: .An Martijn van Duren Aq Mt martijn@openbsd.org .