diff options
Diffstat (limited to 'usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1')
| -rw-r--r-- | usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 b/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 new file mode 100644 index 0000000..aa3f911 --- /dev/null +++ b/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 @@ -0,0 +1,401 @@ +.\" +.\" Copyright (c) 2010 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written by Shteryana Sotirova Shopova +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" Copyright (c) 2005-2007 The FreeBSD Project. +.\" All rights reserved. +.\" +.\" Author: Shteryana Shopova <syrinx@FreeBSD.org> +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 17, 2007 +.Dt BSNMPGET 1 +.Os +.Sh NAME +.Nm bsnmpget , +.Nm bsnmpwalk , +.Nm bsnmpset +.Nd "simple tools for querying SNMP agents" +.Sh SYNOPSIS +.Nm +.Op Fl aDdehnK +.Op Fl A Ar options +.Op Fl b Ar buffersize +.Op Fl C Ar options +.Op Fl I Ar options +.Op Fl i Ar filelist +.Op Fl l Ar filename +.Op Fl M Ar max-repetitions +.Op Fl N Ar non-repeaters +.Op Fl o Ar output +.Op Fl P Ar options +.Op Fl p Ar pdu +.Op Fl r Ar retries +.Op Fl s Ar [trans::][community@][server][:port] +.Op Fl t Ar timeout +.Op Fl U Ar options +.Op Fl v Ar version +.Op Ar OID ... +.Pp +.Nm bsnmpwalk +.Op Fl dhnK +.Op Fl A Ar options +.Op Fl b Ar buffersize +.Op Fl C Ar options +.Op Fl I Ar options +.Op Fl i Ar filelist +.Op Fl l Ar filename +.Op Fl o Ar output +.Op Fl P Ar options +.Op Fl r Ar retries +.Op Fl s Ar [trans::][community@][server][:port] +.Op Fl t Ar timeout +.Op Fl U Ar options +.Op Fl v Ar version +.Op Ar OID ... +.Pp +.Nm bsnmpset +.Op Fl adehnK +.Op Fl A Ar options +.Op Fl b Ar buffersize +.Op Fl C Ar options +.Op Fl I Ar options +.Op Fl i Ar filelist +.Op Fl l Ar filename +.Op Fl o Ar output +.Op Fl P Ar options +.Op Fl r Ar retries +.Op Fl s Ar [trans::][community@][server][:port] +.Op Fl t Ar timeout +.Op Fl U Ar options +.Op Fl v Ar version +.Ar OID Ns = Ar syntax Ns : Ns Ar value +.Op Ar OID Ns = Ar syntax Ns : Ns Ar value ... +.Sh DESCRIPTION +.Nm , +.Nm bsnmpwalk +and +.Nm bsnmpset +are simple tools for retrieving management information from and setting +management information to a Simple Network Managment Protocol (SNMP) agent. +.Pp +Depending on the options +.Nm bsnmpget +constructs either a SMNP GetRequest, GetNextRequest +or a GetBulkRequest packet, fills in the object identifiers (OIDs) of the +objects whose values will be retrived, waits for a response and prints it if +received successfully. +.Pp +.Nm Bsnmpwalk +queries an agent with SMNP GetNextRequest packets, +asking for values of OID instances that are a part of the object subtree +rooted at the provided OIDs. +.Pp +.Nm Bsnmpset +constructs a SMNP SetRequest packet, fills in the OIDs (object identifiers), +syntaxes and values of the objects whose values are to be set and waits for a +responce from server. +.Sh OPTIONS +.Pp +The options are as follows (not all apply to all three programs): +.Bl -tag -width ".It Fl D Ar options" +.It Fl A Ar options +Authentication options to use with SNMPv3 PDUs +.Bl -tag -width +.It Cm proto=[md5|sha] +The protocol to use when calculating the PDU message digest. +.It Cm key=authkey +A binary localized authentication key to use when calculating the PDU message +digest. +.El +.Pp +By default SNMPv3 PDUs are sent unauthenticated. +.It Fl a +Skip any sanity checks when adding OIDs to a Protocol Data Unit (PDU): +ingore syntax/access type, allow adding of non-leaf objects for GetPdu and +read-only objects to a SetPDU. +.It Fl b Ar buffersize +Tune the size of buffers used to send and receive packets. +The default size is 10000 bytes which should be enough unless an agent sends +a really large octetstring. +The maximum allowed length is 65535 according to the Structure of Management +Information (SMIv2). +.It Fl C Ar options +The context to query with SNMPv3 PDUs. +.Bl -tag -width +.It Cm context=name +The context name. Default is "" (empty). +.It Cm context-engine=engine-id +The SNMP Engine ID of the context to query with SNMPv3 PDUs, represented as +binary octet string. By default, this is set to the Engine ID of the SNMP agent. +.El +.It Fl D +Perform SNMP USM Engine Discovery, rather than sending a request for the value +of a specific object. +.It Fl d +Turn on debugging. +This option will cause the packets sent and received to be dumped to the +terminal. +.It Fl e +Retry on error. +If an error is returned in the response PDU, resend the request removing the +variable that caused the error until a valid response is received. +This is only usefull for a GetRequest- and a GetNextRequest-PDU. +.It Fl h +Print a short help text with default values for various options. +.It Fl I Ar options +Load each MIB description file from the given list to translate symbolic +object names to their numerical representation and vice versa. +Use the other options to obtain a non-default behaviour: +.Bl -tag -width +.It Cm cut=OID +Specifies the initial OID that was cut by +.Xr gensnmpdef 1 +when producing the MIB description file. +The default value is .iso(1).org(3).dod(6) which is what should have been +used for all the files installed under /usr/share/snmp/defs/ . +Use this only if you generated your own files, providing a '-c' option to +.Xr gensnmpdef 1 . +.It Cm path=filedir +The directory where files in the list will be searched. +The default is +.Pa /usr/share/snmp/defs/ . +.It Cm file=filelist +A comma separated list of files to which the two options above will apply. +.El +.Pp +The file suboption has to come after the other suboptions so that their +non-default values will be applied to the list of files. +The order of the other suboptions before each file suboption can be random. +Suboptions may be separated either by commas or by spaces. +If using spaces make sure the entire option string is one argument, for +example using quotes. +.It Fl i Ar filelist +List of MIB description files produced by +.Xr gensnmpdef 1 which +.Nm bsnmpget , +.Nm bsnmpwalk +or +.Nm bsnmpset +will search to translate numerical OIDs to their symbolic object names. +Multiple files can be provided either giving this option multiple times +or a comma separated list of file names. +If a filename begins with a letter the default directory, +/usr/share/snmp/defs/ , +will be searched. +.It Fl K +Calculate and display the localized authentication and privacy keys +corresponding to a plain text password. The password is obtain via the +environment. Additionally, if one or more OIDs are specified, the calculated +keys are used when processing the SNMPv3 requests. +.It Fl l Ar filename +The path of the posix local (unix domain) socket if local +transport is used. +.It Fl M Ar max-repetitions +The value for the max-repetitions field in a GetBulk PDU. +Default is 1. +.It Fl N Ar non-repeaters +The value for the non-repeaters field in a GetBulk PDU. +Default is 0. +.It Fl n +Only use numerical representations for input and output OIDs and do not +try to resolve symbolic object names. +Note that +.Nm bsnmpget , +.Nm bsnmpwalk +and +.Nm bsnmpset +will print numerical OIDs anyway if the corresponding string representation +is not found in the MIB description files. +.It Fl o Ar [quiet|short|verbose] +The format used to print the received response. +Quiet only prints values, short (default) prints an abbreviated OID +representation and the value. +In addition to the short output verbose prints the type before the value. +.It Fl P Ar options +Privacy options to use with SNMPv3 PDUs +.Bl -tag -width +.It Cm proto=[aes|des] +The protocol to use when encypting/decrypting SNMPv3 PDU data. +.It Cm key=privkey +A binary localized privacy key to use when encypting/decrypting SNMPv3 PDU data. +.El +.Pp +By default plain text SNMPv3 PDUs are sent. +.It Fl p Ar [get|getnext|getbulk] +The PDU type to send by +.Nm bsmpget . +Default is get. +.It Fl r Ar retries +Number of resends of request packets before giving up if the agent does +not respond after the first try. +Default is 3. +.It Fl s Ar [trans::] Ns Ar [community@] Ns Ar [server] Ns Ar [:port] +Each of the server specification components is optional but at least one +has to be provided if '-s' option is used. +The server specification is constructed in the following manner: +.Bl -tag -width +.It Cm trans:: +Transport type may be one of udp, stream or dgram. +If this option is not provided an udp inet/inet6 socket will be used, which +is the most common. +Stream stands for a posix local stream socket and a posix local datagram +socket will be used if dgram is specified. +.It Cm community@ +Specify an SNMP community string to be used when sending packets. +If the option is skipped the default "public" will be used for +.Nm +and +.Nm bsnmpwalk +and the default "private" community string will be used for +.Nm bsnmpset . +.It Cm server +This might be either the IP address or the hostname where the agent is +listening. +The default is 'localhost'. +.It Cm port +The destination port to send the requests to. +This is useful if the SNMP agent listens on a non-default port. +Default is given by the 'snmp' entry in /etc/services, port 161. +.El +.It Fl t Ar timeout +Number of seconds before resending a request packet if the agent does +not respond. +The default value is 3 seconds. +.It Fl U Ar options +User credentials when sending SNMPv3 PDUs. +.Bl -tag -width +.It Cm engine=id +The Engine ID of the SNMP agent represented as a binary octet string. +.It Cm engine-boots=value +The value of the snmpEngineBoots of the SNMP agent. +.It Cm engine-time=value +The value of the snmpEngineTime of the SNMP agent. +.Pp +If any of the above is not specified, SNMP USM Engine Discovery is attempted. +This is also the default behavior. +.It Cm name=username +The USM user name to include in the SNMPv3 PDUs. By default, the user name is +obtain via the environment +.El +.It Fl v Ar version +The SNMP protocol version to use when sending requests. SNMP versions 1, 2 and +3 are supported. +If no version option is provided +.Nm bsnmpget , +.Nm bsnmpwalk +and +.Nm bsnmpset +will use version 2. +Note that GetBulkRequest-PDUs were introduced in SNMPv2 thus setting the +version to 1 is incompatiable with sending a GetBulk PDU. +.It OID +The object identifier whose value to retrive. +At least one OID should be provided for +.Nm bsnmpget +to be able to send a request. +.Pp +For +.Nm bsnmpwalk +this is the root object identifier of the subtree whose values are to be +retrived. +If no OID is provided +.Nm bsnmpwalk +will walk the mib2 subtree rooted +at .iso(1).org(3).dod(6).internet(1).mgmt(2).mib2(1) . +.Pp +Any of the formats used to print a single variable +is valid as input OID: +.Bl -tag -width +.It 1.3.6.1.2.1.25.1.1.0 +.It sysDescr +.It ifPhysAddress.1 +.It ifRcvAddressStatus.2.6.255.255.255.255.255.255 +.It ifRcvAddressType[2,ff:ff:ff:ff:ff:ff] +.It ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff] +(requires '-o verbose' option) +.El +.Pp +Square brackets are used to denote an entry's indexes. +When used in an input OID, the square brackets may have to be +escaped or the OID has to be quoted to protect it from the shell. +Note there is no difference between ifName.1 and "ifName[1]". +.It OID Ns = Ns Ar [syntax Ns :] Ns Ar value +The object identifier with its syntax type and value that is to be set. +At least one such string OID=[syntax:]value should be provided to +.Nm bsnmpset +to be able to send a request. +.Bl -tag -width +.It Cm OID +OID may be input as a string, a string followed by a random number of integers +(suboids) separated by dots, a sequence of integers separated by dots - that is +if '-n' options is used - and in such case a syntax is required for every value, +or a string followed by square brackets (used to denote an entry's indexes) and +corresponding indexes. +Any of formats used to print a single variable by +.Nm bsnmpset is +valid for inpit OID as well: +.Bl -tag -width +.It 1.3.6.1.2.1.25.1.1.0=TimeTicks:537615486 +.It sysLocation=OctetString:"@ Home" (with '-o verbose' option) +.It sysLocation.0="@ Home" +.It 1.3.6.1.2.1.2.2.1.6.1=OctetString:ffffffffffff +.It ifPhysAddress.1="00:02:b3:1d:1c:a3" +.It ifRcvAddressStatus.1.6.255.255.255.255.255.255=1 +.It "ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff]=Integer:1" +(with '-o verbose' option) +.El +.It Cm syntax +where syntax string is one of : +Integer, OctetString, OID, IpAddress, Counter32, Gauge, TimeTicks, Counter64. +.It Cm value +The value to be set - IP address in form of u.u.u.u - for example +1.3.1.6.1.2.0=IpAddress:192.168.0.1, strings require inverted-commas if they +contain any special characters or spaces, all other numeric types don't. +.El +.Sh ENVIRONMENT +.Nm , +.Nm bsnmpwalk +and +.Nm bsnmpset +use the following environment variables: +.Bl -tag -width SNMPAUTH +.It Ev SNMPAUTH +Specifies a default SNMP USM authentication protocol. +.It Ev SNMPPRIV +Specifies a default SNMP USM privacy protocol. +.It Ev SNMPUSER +Specifies a default SNMP USM user name. +.It Ev SNMPPASSWD +Specifies the SNMP USM plain text password to use when calculating localized +authentication and privacy keys. If this variable exists in the environment, +SMNPv3 is the default version to use for outgoing requests. +.Sh SEE ALSO +.Xr gensnmpdef 1 +.Sh AUTHORS +.An Shteryana Shopova Aq syrinx@FreeBSD.org |
