contrib/bsnmp/snmp_target/snmp_target.3

   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
  41 The
  42 .Nm snmp_target
  43 module implements SNMPv3 Management Target MIB and basic functionality from
  44 Notification MIB as defined in RFC 3413. The module is used to manage the
  45 internal list of SNMPv3 notification target addresses in
  46 .Nm bsnmpd
  47 and their associated transport and encapsulation parameters.
  48 The module must be loaded for
  49 .Nm bsnmpd
  50 to send SNMPv3 Trap-PDUs to the configured notification target addresses.
  51 .Sh IMPLEMENTATION NOTES
  52 A short description of the objects implemented in the module follows.
  53 .Bl -tag -width "XXXXXXXXX"
  54 .It Va snmpTargetSpinLock
  55 An advisory lock used to coordinate several Command Generator Applications when
  56 altering the SNMP Target addresses and their associated parameters.
  57 .It Va snmpTargetAddrTable
  58 The table contains the transport addresses to be used in generation of SNMP
  59 messages.
  60 The table contains the following objects
  61 .Bl -tag -width ".It Va snmpTargetAddrName"
  62 .It Va snmpTargetAddrName
  63 A unique local identifier used as entry key. Not accessible for GET or SET
  64 operations.
  65 .It Va snmpTargetAddrTDomain
  66 The transport domain of the target address. Currently only UDP over IPv4 is
  67 supported and any attempt to SET the value of this object will return an
  68 "inconsistentValue" error. Additional transport domains will be supported
  69 in future via the object definitions in TRANSPORT-ADDRESS-MIB (RFC 3419).
  70 .It Va snmpTargetAddrTAddress
  71 The transport address of this entry interpreted within the context of the value
  72 of
  73 .Va snmpTargetAddrTDomain .
  74 For UDP over IPv4, this is a 6-byte long octetstring, with the first 4 bytes
  75 representing the IPv4 address and the last 2 bytes the UDP port number in
  76 network-byte order.
  77 .It Va snmpTargetAddrTimeout
  78 The value of this object is only relevant when the receiver of the SNMP
  79 message is to send an acknowledgment that the message was received, i.e
  80 for SNMP notifications it is relevant if the notification is SNMP Inform
  81 rather than SNMP Trap. Currently
  82 .Nm bsnmpd
  83 supports only SNMP Trap notifications, so the value of this object is
  84 meaningless.
  85 .It Va snmpTargetAddrRetryCount
  86 As with
  87 .Va snmpTargetAddrTimeout
  88 the value of this object currently is meaningless.
  89 .It Va snmpTargetAddrTagList
  90 A list of human-readable tag values used to select target addresses for a
  91 particular operation. Recognized ASCII delimiting characters between tags are
  92 space (0x20), tab (0x20), carriage return (0xOD) and line feed (0x0A).
  93 .It Va snmpTargetAddrParams
  94 The value of this object contains the value of a key in snmpTargetParamsTable
  95 containing SNMP parameters used when generating messages to this transport
  96 address.
  97 .It Va snmpTargetAddrStorageType
  98 This column always has either of two values. Entries created via
  99 .Nm bsnmpd's
 100 configuration file always have this column set to readOnly (5) and
 101 it is not possible to modify those entries. Entries created by Command Generator
 102 Applications always have this column set to volatile(2) and such entries are
 103 lost when the module is restarted. A SET operation on this column is not
 104 allowed.
 105 .It Va snmpTargetAddrRowStatus
 106 This column is used to create new target address entries or delete existing ones
 107 from the table.
 108 .El
 109 .It Va snmpTargetParamsTable
 110 The table contains the target information to be used in generation of SNMP
 111 messages.
 112 The table contains the following objects
 113 .Bl -tag -width ".It Va snmpTargetParamsName"
 114 .It Va snmpTargetParamsName
 115 A unique local identifier used as entry key. Not accessible for GET or SET
 116 operations.
 117 .It Va snmpTargetParamsMPModel
 118 The Message Processing Model to be used when generating SNMP PDUs using this
 119 entry. Supported values are 0 for SNMPv1, 1 for SNMPv2c and 3 for SNMPv3.
 120 .It Va snmpTargetParamsSecurityModel
 121 The Security Model to be used when generating SNMP PDUs using this entry.
 122 Supported values are 1  for SNMPv1, 2 for SNMPv2c and 3 for SNMPv3 User-Based
 123 Security Model.
 124 .It Va snmpTargetParamsSecurityName
 125 The securityName which identifies the Principal on whose behalf SNMP PDUs
 126 will be generated using this entry. For SNMPv1 and SNMPv2c this is the
 127 name of a community configured in
 128 .Nm bsnmpd ,
 129 and for SNMPv3 USM, this is the name of an existing user configured via the
 130 .Nm snmp_usm
 131 module.
 132 .It Va snmpTargetParamsSecurityLevel
 133 The Security Level to be used when generating SNMP PDUs using this entry.
 134 Supported values are noAuthNoPriv(1) for plain-text PDUs with no authentication,
 135 authNoPriv(2) for authenticated plain-text PDUs and authPriv(3) for encrypted
 136 PDUs.
 137 .It Va snmpTargetParamsStorageType
 138 As with
 139 .Va snmpTargetAddrStorageType
 140 this column always has either of two values. Entries created via
 141 .Nm bsnmpd's
 142 configuration file always have this column set to readOnly (5), while entries
 143 created by Command Generator Applications always have this column set to
 144 volatile(2). A SET operation on this column is not allowed.
 145 .It Va snmpTargetParamsRowStatus
 146 This column is used to create new target address parameters entries or delete
 147 existing ones from the table.
 148 .El
 149 .It Va snmpNotifyTable
 150 The table is used to select the management targets which should receive SNMP
 151 notifications.
 152 The table contains the following objects
 153 .Bl -tag -width ".It Va snmpNotifyName"
 154 .It Va snmpNotifyName
 155 A unique local identifier used as entry key. Not accessible for GET or SET
 156 operations.
 157 .It Va snmpNotifyTag
 158 This object contains a single tag value used to select target addresses from
 159 the
 160 .Va snmpTargetAddrTable
 161 to which the notifications will be send.
 162 .It Va snmpNotifyType
 163 The type of SNMP notifications that will be send to the target addresses
 164 matching the corresponding
 165 .Va snmpNotifyTag .
 166 Possible values are Trap (1) or Inform (2). Currently only SNMP Traps are
 167 supported and any attempt to SET the value of this object will return an
 168 "inconsistentValue" error.
 169 .It Va snmpNotifyStorageType
 170 Again this column always has either of two values. Entries created via
 171 .Nm bsnmpd's
 172 configuration file always have this column set to readOnly (5), while entries
 173 created by Command Generator Applications always have this column set to
 174 volatile(2). A SET operation on this column is not allowed.
 175 .It Va snmpNotifyRowStatus
 176 This column is used to create new notification target entries or delete existing
 177 ones from the table.
 178 .El
 179 .El
 180 .Pp
 181 The
 182 .Va snmpNotifyFilterProfileTable
 183 and
 184 .Va snmpNotifyFilterTable
 185 tables from the SNMP-NOTIFICATION-MIB are not supported by the module.
 186 Notification filtering is supported via the
 187 .Xr snmp_vacm 3
 188 module instead.
 189 .Sh FILES
 190 .Bl -tag -width "XXXXXXXXX"
 191 .It Pa /usr/share/snmp/defs/target_tree.def
 192 The 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
 202 IETF RFC 3413
 203 .Sh AUTHORS
 204 .An Shteryana Shopova Aq syrinx@FreeBSD.org