xref: /freebsd/contrib/bsnmp/snmp_target/snmp_target.3 (revision 9f23cbd6cae82fd77edfad7173432fa8dccd0a95)
1.\"-
2.\" Copyright (C) 2010 The FreeBSD Foundation
3.\"
4.\" This documentation was written by Shteryana Sotirova Shopova under
5.\" sponsorship from the FreeBSD Foundation.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" $FreeBSD$
29.\"
30.Dd December 16, 2010
31.Dt SNMP_TARGET 3
32.Os
33.Sh NAME
34.Nm snmp_target
35.Nd "Target addresses and notifications module for"
36.Xr bsnmpd 1
37.Sh LIBRARY
38.Pq begemotSnmpdModulePath."target" = "/usr/lib/snmp_target.so"
39.Sh DESCRIPTION
40The
41.Nm snmp_target
42module implements SNMPv3 Management Target MIB and basic functionality from
43Notification MIB as defined in RFC 3413. The module is used to manage the
44internal list of SNMPv3 notification target addresses in
45.Nm bsnmpd
46and their associated transport and encapsulation parameters.
47The module must be loaded for
48.Nm bsnmpd
49to send SNMPv3 Trap-PDUs to the configured notification target addresses.
50.Sh IMPLEMENTATION NOTES
51A short description of the objects implemented in the module follows.
52.Bl -tag -width "XXXXXXXXX"
53.It Va snmpTargetSpinLock
54An advisory lock used to coordinate several Command Generator Applications when
55altering the SNMP Target addresses and their associated parameters.
56.It Va snmpTargetAddrTable
57The table contains the transport addresses to be used in generation of SNMP
58messages.
59The table contains the following objects
60.Bl -tag -width ".It Va snmpTargetAddrName"
61.It Va snmpTargetAddrName
62A unique local identifier used as entry key. Not accessible for GET or SET
63operations.
64.It Va snmpTargetAddrTDomain
65The transport domain of the target address. Currently only UDP over IPv4 is
66supported and any attempt to SET the value of this object will return an
67"inconsistentValue" error. Additional transport domains will be supported
68in future via the object definitions in TRANSPORT-ADDRESS-MIB (RFC 3419).
69.It Va snmpTargetAddrTAddress
70The transport address of this entry interpreted within the context of the value
71of
72.Va snmpTargetAddrTDomain .
73For UDP over IPv4, this is a 6-byte long octetstring, with the first 4 bytes
74representing the IPv4 address and the last 2 bytes the UDP port number in
75network-byte order.
76.It Va snmpTargetAddrTimeout
77The value of this object is only relevant when the receiver of the SNMP
78message is to send an acknowledgment that the message was received, i.e
79for SNMP notifications it is relevant if the notification is SNMP Inform
80rather than SNMP Trap. Currently
81.Nm bsnmpd
82supports only SNMP Trap notifications, so the value of this object is
83meaningless.
84.It Va snmpTargetAddrRetryCount
85As with
86.Va snmpTargetAddrTimeout
87the value of this object currently is meaningless.
88.It Va snmpTargetAddrTagList
89A list of human-readable tag values used to select target addresses for a
90particular operation. Recognized ASCII delimiting characters between tags are
91space (0x20), tab (0x20), carriage return (0xOD) and line feed (0x0A).
92.It Va snmpTargetAddrParams
93The value of this object contains the value of a key in snmpTargetParamsTable
94containing SNMP parameters used when generating messages to this transport
95address.
96.It Va snmpTargetAddrStorageType
97This column always has either of two values. Entries created via
98.Nm bsnmpd's
99configuration file always have this column set to readOnly (5) and
100it is not possible to modify those entries. Entries created by Command Generator
101Applications always have this column set to volatile(2) and such entries are
102lost when the module is restarted. A SET operation on this column is not
103allowed.
104.It Va snmpTargetAddrRowStatus
105This column is used to create new target address entries or delete existing ones
106from the table.
107.El
108.It Va snmpTargetParamsTable
109The table contains the target information to be used in generation of SNMP
110messages.
111The table contains the following objects
112.Bl -tag -width ".It Va snmpTargetParamsName"
113.It Va snmpTargetParamsName
114A unique local identifier used as entry key. Not accessible for GET or SET
115operations.
116.It Va snmpTargetParamsMPModel
117The Message Processing Model to be used when generating SNMP PDUs using this
118entry. Supported values are 0 for SNMPv1, 1 for SNMPv2c and 3 for SNMPv3.
119.It Va snmpTargetParamsSecurityModel
120The Security Model to be used when generating SNMP PDUs using this entry.
121Supported values are 1  for SNMPv1, 2 for SNMPv2c and 3 for SNMPv3 User-Based
122Security Model.
123.It Va snmpTargetParamsSecurityName
124The securityName which identifies the Principal on whose behalf SNMP PDUs
125will be generated using this entry. For SNMPv1 and SNMPv2c this is the
126name of a community configured in
127.Nm bsnmpd ,
128and for SNMPv3 USM, this is the name of an existing user configured via the
129.Nm snmp_usm
130module.
131.It Va snmpTargetParamsSecurityLevel
132The Security Level to be used when generating SNMP PDUs using this entry.
133Supported values are noAuthNoPriv(1) for plain-text PDUs with no authentication,
134authNoPriv(2) for authenticated plain-text PDUs and authPriv(3) for encrypted
135PDUs.
136.It Va snmpTargetParamsStorageType
137As with
138.Va snmpTargetAddrStorageType
139this column always has either of two values. Entries created via
140.Nm bsnmpd's
141configuration file always have this column set to readOnly (5), while entries
142created by Command Generator Applications always have this column set to
143volatile(2). A SET operation on this column is not allowed.
144.It Va snmpTargetParamsRowStatus
145This column is used to create new target address parameters entries or delete
146existing ones from the table.
147.El
148.It Va snmpNotifyTable
149The table is used to select the management targets which should receive SNMP
150notifications.
151The table contains the following objects
152.Bl -tag -width ".It Va snmpNotifyName"
153.It Va snmpNotifyName
154A unique local identifier used as entry key. Not accessible for GET or SET
155operations.
156.It Va snmpNotifyTag
157This object contains a single tag value used to select target addresses from
158the
159.Va snmpTargetAddrTable
160to which the notifications will be send.
161.It Va snmpNotifyType
162The type of SNMP notifications that will be send to the target addresses
163matching the corresponding
164.Va snmpNotifyTag .
165Possible values are Trap (1) or Inform (2). Currently only SNMP Traps are
166supported and any attempt to SET the value of this object will return an
167"inconsistentValue" error.
168.It Va snmpNotifyStorageType
169Again this column always has either of two values. Entries created via
170.Nm bsnmpd's
171configuration file always have this column set to readOnly (5), while entries
172created by Command Generator Applications always have this column set to
173volatile(2). A SET operation on this column is not allowed.
174.It Va snmpNotifyRowStatus
175This column is used to create new notification target entries or delete existing
176ones from the table.
177.El
178.El
179.Pp
180The
181.Va snmpNotifyFilterProfileTable
182and
183.Va snmpNotifyFilterTable
184tables from the SNMP-NOTIFICATION-MIB are not supported by the module.
185Notification filtering is supported via the
186.Xr snmp_vacm 3
187module instead.
188.Sh FILES
189.Bl -tag -width "XXXXXXXXX"
190.It Pa /usr/share/snmp/defs/target_tree.def
191The description of the MIB tree implemented by
192.Nm .
193.El
194.Sh SEE ALSO
195.Xr bsnmpd 1 ,
196.Xr gensnmptree 1 ,
197.Xr snmpmod 3 ,
198.Xr snmp_usm 3 ,
199.Xr snmp_vacm 3
200.Sh STANDARDS
201IETF RFC 3413
202.Sh AUTHORS
203.An Shteryana Shopova Aq syrinx@FreeBSD.org
204