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