.\" $OpenBSD: snmp.1,v 1.20 2021/08/11 18:53:45 martijn Exp $ .\" .\" Copyright (c) 2019 Martijn van Duren .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate: August 11 2021 $ .Dt SNMP 1 .Os .Sh NAME .Nm snmp .Nd simple SNMP client .Sh SYNOPSIS .Nm .Cm get | getnext | bulkget .Op Ar options .Ar agent .Ar oid ... .Nm .Cm walk | bulkwalk .Op Ar options .Ar agent .Op Ar oid .Nm .Cm set .Op Ar options .Ar agent .Ar varoid type value .Oo Ar varoid type value Oc ... .Nm .Cm trap .Op Ar options .Ar agent uptime trapoid .Oo Ar varoid type value Oc ... .Nm .Cm df .Op Ar options .Ar agent .Nm .Cm mibtree .Op Fl O Ar fns .Op Ar oid ... .Sh DESCRIPTION The .Nm utility is a simple SNMP client. .Pp The subcommands are as follows: .Bl -tag -width Ds .It Xo .Nm snmp .Cm get .Op Ar options .Ar agent oid ... .Xc Retrieve the varbind for .Ar oid from the .Ar agent . If more than one .Ar oid is specified, retrieve the varbind for each one. .It Xo .Nm snmp .Cm getnext .Op Ar options .Ar agent oid ... .Xc Retrieve the varbind that follows .Ar oid from the .Ar agent . If more than one .Ar oid is specified, retrieve the varbind following each one of them. .It Nm snmp Cm walk Oo Ar options Oc Ar agent Op Ar oid Retrieve all the varbinds that are branches of .Ar oid from the .Ar agent . This uses the .Cm getnext subcommand internally and requests a single varbind at a time. If no .Ar oid is specified it defaults to mib-2 .Pq .1.3.6.1.2.1 . .It Xo .Nm snmp .Cm bulkget .Op Ar options .Ar agent oid ... .Xc Retrieve the next 10 varbinds following each .Ar oid from the .Ar agent . This command is not available for .Fl v Cm 1 . .It Xo .Nm snmp .Cm bulkwalk .Op Ar options .Ar agent .Op Ar oid .Xc Retrieve all the varbinds from the .Ar agent that are branches of .Ar oid . This uses the .Cm bulkget subcommand internally to retrieve multiple varbinds at a time. This command is not available for .Fl v Cm 1 . .It Xo .Nm snmp .Cm set .Op Ar options .Ar agent varoid type value ... .Xc Set one or more .Ar varoid to a new .Ar value . The format of the .Ar varoid type value triple is described in .Sx Data types , below. .It Xo .Nm snmp .Cm trap .Op Ar options .Ar agent uptime trapoid .Op Ar varoid type value ... .Xc Send a trap message to the .Ar agent . The .Ar uptime is specified in timeticks .Pq centiseconds or defaults to the system uptime if an empty string is given. The .Ar trapoid is the identification OID used by the trap handler to determine its action. This command is not available for .Fl v Cm 1 . .It Xo .Nm .Cm df .Op Ar options .Ar agent .Xc An SNMP based version of the .Xr df 1 command. If no size suffix is shown the sizes are in kilobytes. .It Nm Cm mibtree Oo Fl O Ar fnS Oc Op Ar oid ... Dump the tree of compiled-in MIB objects. If .Ar oid is specified it will print the objects in the requested output format if available, or print a warning if the object can't be found. .El .Pp The .Ar options are as follows: .Bl -tag -width Ds .It Fl A Ar authpass The authentication password for the user. This will be transformed to .Ar localauth . This option is only used by .Fl v Cm 3 . .It Fl a Ar digest Set the digest .Pq authentication protocol. Options are .Cm MD5 , .Cm SHA , .Cm SHA-224 , .Cm SHA-256 , .Cm SHA-384 or .Cm SHA-512 . This option defaults to .Cm SHA . This option is only used by .Fl v Cm 3 . .It Fl C Ar appopt For the .Cm bulkget , .Cm bulkwalk , .Cm df , and .Cm walk subcommands, set the application specific .Ar appopt options by supplying a string of one or more of the following modifier letters: .Bl -tag -width Ds .It Cm c For .Cm walk and .Cm bulkwalk , disable checking the order of MIBs. On some devices that return MIBs out of order, this may cause an infinite loop. .It Cm E Ar endoid For .Cm walk , walk the tree up to but excluding .Ar endoid . The blank before .Ar endoid is mandatory. .It Cm h For .Cm df print the output in .Dq human-readable format. .It Cm I For .Cm walk , do not fall back to returning the original MIB via a .Cm get request. .It Cm i For .Cm walk and .Cm bulkwalk , always do a .Cm get request on the specified .Ar oid first. .It Cm n Ns Ar nonrep For .Cm bulkget and .Cm bulkwalk , Set the non-repeaters field in the request to the non-negative integer .Ar nonrep . This causes the first .Ar nonrep .Ar oid arguments to only return a single MIB instead of .Ar maxrep . This value defaults to 0. No blank is allowed before .Ar nonrep . .It Cm p For .Cm walk or .Cm bulkwalk , also show a summary of the total variables received. .It Cm r Ns Ar maxrep For .Cm bulkget , .Cm bulkwalk and .Cm df , set the max-repetitions field in the request to the positive integer .Ar maxrep . This determines the amount of MIBs to return for each specified OID. This value defaults to 10. No blank is allowed before .Ar maxrep . .It Cm s Ar skipoid For .Cm walk or .Cm bulkwalk don't include .Ar skipoid or its children in the walk output. The blank before .Ar skipoid is mandatory. .It Cm t For .Cm walk , Show how long it took to walk the entire tree. .El .It Fl c Ar community Set the .Ar community string. This option is only used by .Fl v Cm 1 and .Fl v Cm 2c and has no default. .It Fl e Ar secengineid The USM security engine id. Under normal circumstances this value is discovered via snmpv3 discovery and does not need to be specified. This option is only used by .Fl v Cm 3 . .It Fl E Ar ctxengineid The snmpv3 context engine id. Most of the time this value can be safely ignored. This option is only used by .Fl v Cm 3 . .It Fl K Ar localpriv The localized privacy password for the user in hexadecimal format .Po optionally prefixed with a .Cm 0x .Pc . This option is only used by .Fl v Cm 3 . .It Fl k Ar localauth The localized authentication password for the user in hexadecimal format .Po optionally prefixed with a .Cm 0x .Pc . This option is only used by .Fl v Cm 3 . .It Fl l Ar seclevel The security level. Values can be .Cm noAuthNoPriv Pq default , .Cm authNoPriv .Po requires either .Fl A or .Fl k .Pc or .Cm authPriv .Po requires either .Fl X or .Fl K in addition to the .Cm authNoPriv requirements .Pc . This option is only used by .Fl v Cm 3 . .It Fl n Ar ctxname Sets the context name. Defaults to an empty string. This option is only used by .Fl v Cm 3 . .It Fl O Ar output Set the .Ar output options by supplying a string of one or more of the following modifier letters: .Bl -tag -width 1n .It Cm a Print the varbind string unchanged rather than replacing non-printable bytes with dots. .It Cm f When displaying an OID, include the full list of MIB objects. By default only the last textual MIB object is shown. .It Cm n Display the OID numerically. .It Cm Q Remove the type information. .It Cm q Remove the type information and the equal sign. .It Cm S Display the MIB name and the type information. This is the default behaviour. .It Cm v Only display the varbind value, removing the OID. .It Cm x Display the varbind string values as hexadecimal strings. .El .Pp The .Cm mibtree subcommand may only use the .Op Fl fnS output options; no output options are available for .Cm trap . .It Fl r Ar retries Set the number of .Ar retries in case of packet loss. Defaults to 5. .It Fl t Ar timeout Set the .Ar timeout to wait for a reply, in seconds. Defaults to 1. .It Fl u Ar user Sets the username. If .Fl v Cm 3 is used this option is required. This option is only used by .Fl v Cm 3 . .It Fl v Ar version Set the snmp protocol .Ar version to either .Cm 1 , .Cm 2c or .Cm 3 . Currently defaults to .Cm 3 . .It Fl X Ar privpass The privacy password for the user. This will be tansformed to .Ar localpriv . This option is only used by .Fl v Cm 3 . .It Fl x Ar cipher Sets the cipher .Pq privacy protocol. Options are .Cm DES and .Cm AES . This option defaults to .Cm AES . This option is only used by .Fl v Cm 3 . .It Fl Z Ar boots , Ns Ar time Set the engine boots and engine time. Under normal circumstances this value is discovered via snmpv3 discovery and does not need to be specified. This option is only used by .Fl v Cm 3 . .El .Pp The syntax for the .Ar agent argument is .Oo Ar protocol : Oc Ns Ar address , with the following format: .Bl -column udp6XXXtcp6X address -offset indent .It Ar protocol Ta Ar address .It Cm udp | tcp Ta Ar hostname Ns Oo Pf : Ar port Oc | .Ar IPv4-address Ns Op Pf : Ar port .It Cm udp6 | tcp6 Ta Ar hostname Ns Oo Pf : Ar port Oc | .Cm \&[ Ns Ar IPv6-address Ns Cm \&] Ns Oo Pf : Ar port Oc | .Ar IPv6-address Ns Pf : Ar port .It Cm unix Ta Ar pathname .El .Pp The default .Ar protocol is .Cm udp and the default .Ar port is 161, except for the .Cm trap subcommand, which uses 162. .Cm udpv6 and .Cm udpipv6 are aliases for .Cm udp6 ; .Cm tcpv6 and .Cm tcpipv6 for .Cm tcp6 . To specify an IPv6-address without a .Ar port , the .Ar IPv6-address must be enclosed in square brackets. If the square brackets are omitted, the value after the last colon is always interpreted as a .Ar port . .Ss Data types Additional data sent to the server is formatted by specifying one or more triples of .Ar varoid , .Ar type , and .Ar value . Supported types are: .Bl -tag -width 1n -offset indent .It Cm a An IPv4 Address. .It Cm b A bitstring. A list of individual bit offsets separated by comma, space or tab. Must be supplied as a single argument. .It Cm c A counter32. .It Cm d A decimal string. A list of individual bytes in decimal form separated by space or tab. .It Cm i An integer. .It Cm n A null object. .It Cm o An OID. .It Cm s A regular string. .It Cm t Timeticks in centiseconds. .It Cm u Unsigned integer. .It Cm x A hex string. Similar to a decimal string, but in hexadecimal format. .El .Sh ENVIRONMENT .Bl -tag -width LC_CTYPE .It Ev LC_CTYPE The character encoding .Xr locale 1 used for output. It decides whether objects having a display format of UTF-8 are printed as UTF-8, and whether each byte invalid according to the object's display format is printed as a UTF-8 replacement character .Pq Sq \[uFFFD] . .Pp If unset or set to .Qq C , .Qq POSIX , or an unsupported value, for objects having a display format of UTF-8, each .Em printable non-ASCII character is replaced with a single dot .Pq Sq \&. . Each byte invalid according to the object's display format is printed as a question mark .Pq Sq \&? . .Pp Each non-printable character is always replaced with a single dot .Pq Sq \&. . .El .Sh SEE ALSO .Xr snmpd 8 .Sh HISTORY The .Nm program first appeared in .Ox 6.6 . .Sh AUTHORS The .Nm program was written by .An Martijn van Duren Aq Mt martijn@openbsd.org .