.\" $OpenBSD: snmp.1,v 1.3 2019/08/14 14:40:23 deraadt Exp $
.\"
.\" Copyright (c) 2019 Martijn van Duren <martijn@openbsd.org>
.\"
.\" 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 14 2019 $
.Dt SNMP 1
.Os
.Sh NAME
.Nm snmp
.Nd simple SNMP client
.Sh SYNOPSIS
.Nm
.Cm get | getnext
.Op Fl 3 Ns Cm K Ar localpriv
.Op Fl 3 Ns Cm k Ar localauth
.Op Fl 3 Ns Cm M Ar masterpriv
.Op Fl 3 Ns Cm m Ar masterauth
.Op Fl A Ar authpass
.Op Fl a Ar digest
.Op Fl c Ar community
.Op Fl E Ar ctxengineid
.Op Fl e Ar secengineid
.Op Fl l Ar seclevel
.Op Fl n Ar ctxname
.Op Fl O Cm afnQqSvx
.Op Fl r Ar retries
.Op Fl t Ar timeout
.Op Fl u Ar user
.Op Fl v Ar version
.Op Fl X Ar privpass
.Op Fl x Ar cipher
.Op Fl Z Ar boots , Ns Ar time
.Ar agent
.Ar oid ...
.Nm
.Cm walk
.Op Fl 3 Ns Cm K Ar localpriv
.Op Fl 3 Ns Cm k Ar localauth
.Op Fl 3 Ns Cm M Ar masterpriv
.Op Fl 3 Ns Cm m Ar masterauth
.Op Fl A Ar authpass
.Op Fl a Ar digest
.Op Fl c Ar community
.Op Fl E Ar ctxengineid
.Op Fl e Ar secengineid
.Op Fl l Ar seclevel
.Op Fl n Ar ctxname
.Op Fl O Cm afnQqSvx
.Op Fl r Ar retries
.Op Fl t Ar timeout
.Op Fl u Ar user
.Op Fl v Ar version
.Op Fl X Ar privpass
.Op Fl x Ar cipher
.Op Fl Z Ar boots , Ns Ar time
.Op Fl C Cm cIipt
.Op Fl C Cm E Ar endoid
.Ar agent
.Op Ar oid
.Nm
.Cm bulkget
.Op Fl 3 Ns Cm K Ar localpriv
.Op Fl 3 Ns Cm k Ar localauth
.Op Fl 3 Ns Cm M Ar masterpriv
.Op Fl 3 Ns Cm m Ar masterauth
.Op Fl A Ar authpass
.Op Fl a Ar digest
.Op Fl c Ar community
.Op Fl E Ar ctxengineid
.Op Fl e Ar secengineid
.Op Fl l Ar seclevel
.Op Fl n Ar ctxname
.Op Fl O Cm afnQqSvx
.Op Fl r Ar retries
.Op Fl t Ar timeout
.Op Fl u Ar user
.Op Fl v Ar version
.Op Fl X Ar privpass
.Op Fl x Ar cipher
.Op Fl Z Ar boots , Ns Ar time
.Op Fl C Cm n Ns Ar nonrep Ns Cm r Ns Ar maxrep
.Ar agent
.Ar oid ...
.Nm
.Cm bulkwalk
.Op Fl 3 Ns Cm K Ar localpriv
.Op Fl 3 Ns Cm k Ar localauth
.Op Fl 3 Ns Cm M Ar masterpriv
.Op Fl 3 Ns Cm m Ar masterauth
.Op Fl A Ar authpass
.Op Fl a Ar digest
.Op Fl c Ar community
.Op Fl E Ar ctxengineid
.Op Fl e Ar secengineid
.Op Fl l Ar seclevel
.Op Fl n Ar ctxname
.Op Fl O Cm afnQqSvx
.Op Fl r Ar retries
.Op Fl t Ar timeout
.Op Fl u Ar user
.Op Fl v Ar version
.Op Fl X Ar privpass
.Op Fl x Ar cipher
.Op Fl Z Ar boots , Ns Ar time
.Op Fl C Cm cipn Ns Ar nonrep Ns Cm r Ns Ar maxrep
.Ar agent
.Op Ar oid
.Nm
.Cm trap
.Op Fl 3 Ns Cm K Ar localpriv
.Op Fl 3 Ns Cm k Ar localauth
.Op Fl 3 Ns Cm M Ar masterpriv
.Op Fl 3 Ns Cm m Ar masterauth
.Op Fl A Ar authpass
.Op Fl a Ar digest
.Op Fl c Ar community
.Op Fl E Ar ctxengineid
.Op Fl e Ar secengineid
.Op Fl l Ar seclevel
.Op Fl n Ar ctxname
.Op Fl r Ar retries
.Op Fl t Ar timeout
.Op Fl u Ar user
.Op Fl v Ar version
.Op Fl X Ar privpass
.Op Fl x Ar cipher
.Op Fl Z Ar boots , Ns Ar time
.Ar agent uptime trapoid
.Oo Ar varoid type value Oc ...
.Nm
.Cm mibtree
.Op Fl O Cm fnS
.Sh DESCRIPTION
The
.Nm
utility is a simple SNMP client.
.Pp
The subcommands are as follows:
.Bl -tag -width bulkwalk
.It Cm get
Retrieve the MIB for
.Ar oid
from the
.Ar agent .
If more than one
.Ar oid
is specified, retrieve the MIB for each one.
.It Cm getnext
Retrieve the MIB that follows
.Ar oid
from the
.Ar agent .
If more than one
.Ar oid
is specified, retrieve the MIB following each one of them.
.It Cm walk
Retrieve all the MIBs that are branches of
.Ar oid
from the
.Ar agent .
This uses the
.Cm getnext
subcommand internally and requests a single MIB at a time.
If no OID is specified it defaults to mib-2
.Pq .1.3.6.1.2.1 .
.It Cm bulkget
Retrieve the next 10 MIBs following each
.Ar oid
from the
.Ar agent .
This command is not available for
.Fl v Cm 1 .
.It Cm bulkwalk
Retrieve all the MIBs from the
.Ar agent
that are branches of
.Ar oid .
This uses the
.Cm bulkget
subcommand internally to retrieve multiple MIBs at a time.
This command is not available for
.Fl v Cm 1 .
.It Cm trap
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.
The triple
.Op Ar varoid , type, value
is described below
.Sx Data types .
This command is not available for
.Fl v Cm 1 .
.It Cm mibtree
Dump the tree of compiled-in MIB objects.
.El
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl 3 Ar snmpv3opt
Set the snmpv3 and USM
.Ar snmpv3opt
options by supplying a single modifier letter per invocation.
The modifier letters are:
.Bl -tag -width Ds
.It Cm A Ar authpass
The authentication password for the user.
This will be transformed to
.Ar localauth .
.It Cm 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 MD5 .
.It Cm E Ar ctxengineid
The snmpv3 context engine id.
Most of the time this value can be safely ignored.
.It Cm 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.
.It Cm K Ar localpriv
The localized privacy password for the user in hexadecimal format
.Po
optionally prefixed with a
.Cm 0x
.Pc .
.It Cm k Ar localauth
The localized authentication password for the user in hexadecimal format
.Po
optionally prefixed with a
.Cm 0x
.Pc .
.It Cm l Ar seclevel
The security level.
Values can be
.Cm noAuthNoPriv Pq default ,
.Cm authNoPriv
.Po
requires either
.Fl 3 Ns Cm A ,
.Fl 3 Ns Cm m
or
.Fl 3 Ns Cm k
.Pc
or
.Cm authPriv
.Po
requires either
.Fl 3 Ns Cm X ,
.Fl 3 Ns Cm M
or
.Fl 3 Ns Cm K
in addition to the
.Cm authNoPriv
requirements
.Pc .
.It Cm M Ar masterpriv
The master privacy password for the user in hexadecimal format
.Po
optionally prefixed with a
.Cm 0x
.Pc .
This will be transformed to
.Ar localpriv .
.It Cm m Ar masterauth
The master authentication password for the user in hexadecimal format
.Po
optionally prefixed with a
.Cm 0x
.Pc .
This will be transformed to
.Ar localauth .
.It Cm n Ar ctxname
Sets the context name.
Defaults to an empty string.
.It Cm u Ar user
Sets the username.
If
.Fl v Cm 3
is used this option is required.
.It Cm X Ar privpass
The privacy password for the user.
This will be tansformed to
.Ar localpriv .
.It Cm x Ar cipher
Sets the cipher
.Pq privacy
protocol.
Options are
.Cm DES
and
.Cm AES .
.It Cm 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.
.El
.It Fl A Ar authpass
An alias for
.Fl 3 Ns Cm A Ar authpass .
.It Fl a Ar digest
An alias for
.Fl 3 Ns Cm a Ar digest .
.It Fl C Ar appopt
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
During a
.Cm walk
or
.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
Walk the tree up to but excluding
.Ar endoid .
The blank before
.Ar endoid
is mandatory.
.It Cm I
If no branches are found during a
.Cm walk ,
do not fall back to returning the original MIB via a
.Cm get
request.
.It Cm i
Before starting a
.Cm walk
or
.Cm bulkwalk ,
always do a
.Cm get
request on the specified
.Ar oid
first.
.It Cm n Ns Ar nonrep
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
At the end of a
.Cm walk
or
.Cm bulkwalk ,
show a summary of the total variables received.
.It Cm r Ns Ar maxrep
Set the max-repetitions field in the request to the positive integer
.Ar maxrep .
For
.Cm bulkget
or
.Cm bulkwalk
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 t
Show how long it took to
.Cm walk
the entire tree.
.El
.It Fl c Ar community
Set the
.Ar community
string.
Defaults to
.Cm public .
This option is only used by
.Fl v Cm 1
and
.Fl v Cm 2c .
.It Fl E Ar ctxengineid
An alias for
.Fl 3 Ns Cm E Ar ctxengineid .
.It Fl e Ar secengineid
An alias for
.Fl 3 Ns Cm e Ar secengineid .
.It Fl l Ar seclevel
An alias for
.Fl 3 Ns Cm l Ar seclevel .
.It Fl n Ar ctxname
An alias for
.Fl 3 Ns Cm n Ar ctxname .
.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
.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
An alias for
.Fl 3 Ns Cm u Ar user .
.It Fl v Ar version
Set the snmp protocol
.Ar version
to either
.Cm 1 ,
.Cm 2c
or
.Cm 3 .
Currently defaults to
.Cm 2c .
.It Fl X Ar privpass
An alias for
.Fl 3 Ns Cm X Ar privpass .
.It Fl x Ar cipher
An alias for
.Fl 3 Ns Cm x Ar cipher .
.It Fl Z Ar boots , Ns Ar time
An alias for
.Fl 3 Ns Cm Z Ar boots , Ns Ar time .
.El
.Pp
The syntax for the
.Ar agent
argument is
.Oo Ar protocol : Oc Ns Ar address
with the follwing forms:
.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
.Nm snmp Cm trap
command 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
.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.
Actually a normal integer for compatibility with netsnmp.
.It Cm x
A hex string.
Similar to a decimal string, but in hexadecimal format.
.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 .