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