diff options
Diffstat (limited to 'contrib/ngatm/snmp_atm/snmp_atm.3')
| -rw-r--r-- | contrib/ngatm/snmp_atm/snmp_atm.3 | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/contrib/ngatm/snmp_atm/snmp_atm.3 b/contrib/ngatm/snmp_atm/snmp_atm.3 new file mode 100644 index 0000000..7fe2f46 --- /dev/null +++ b/contrib/ngatm/snmp_atm/snmp_atm.3 @@ -0,0 +1,217 @@ +.\" +.\" Copyright (c) 2001-2002 +.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). +.\" All rights reserved. +.\" Copyright (c) 2003-2004 +.\" Hartmut Brandt. +.\" All rights reserved. +.\" +.\" Author: Hartmut Brandt <harti@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. +.\" +.\" $Begemot: libunimsg/snmp_atm/snmp_atm.3,v 1.1 2004/07/20 16:30:03 brandt Exp $ +.\" +.Dd July 20, 2004 +.Dt snmp_atm 3 +.Os +.Sh NAME +.Nm atmif_event_f , +.Nm atm_find_if_name , +.Nm atm_find_if , +.Nm atm_notify_aif , +.Nm atm_unnotify_aif +.Nd "ATM driver module for snmpd. +.Sh LIBRARY +.Pq begemotSnmpdModulePath."netgraph" = "@MODPATH@snmp_netgraph.so" (FreeBSD) +.Pq begemotSnmpdModulePath."mibII" = "@MODPATH@snmp_mibII.so" +.Pq begemotSnmpdModulePath."atm" = "@MODPATH@snmp_atm.so" +.Sh SYNOPSIS +.In bsnmp/snmpmod.h +.In bsnmp/snmp_mibII.h +.In bsnmp/snmp_atm.h +.Ft typedef void +.Fn (*atmif_event_f) "struct atmif *aif" "enum atmif_notify event" "uintptr_t data" "void *uarg" +.Ft struct atmif * +.Fn atm_find_if_name "const char *name" +.Ft struct atmif * +.Fn atm_find_if "u_int ifindex" +.Ft void * +.Fn atm_notify_aif "struct atmif *aif" "const struct lmodule *mod" "atmif_event_f func" "void *uarg" +.Ft void +.Fn atm_unnotify_aif "void *not" +.Sh DESCRIPTION +The +.Nm snmp_atm +module implements a number of tables and scalars that enable remote access to +the ATM devices in the system. It also exports a number of +functions, that allow other modules to easily access ATM devices. +.Pp +The module maintains an extension to the interface structure exported by +.Xr snmp_mibII 3 +for all ATM devices. This structure has the following fields: +.Bd -literal -offset indent +struct atmif { + struct mibif *ifp; /* common interface data */ + struct atmif_mib *mib; /* ATM MIB */ + enum atmif_carrier_state carrier; + enum atmif_suni_mode mode; /* SUNI mode SDH or SONET */ +}; +.Ed +.Pp +The fields have the following meaning: +.Bl -tag -width XXX +.It Fa ifp +The field points to the +.Xr snmp_mibII 3 +interface structure. +.It Fa mib +The special ATM interface MIB (see below). +.It Fa carrier +The current state of the carrier. One of the following: +.Bl -tag -width XXX +.It Dv ATMIF_CARRIER_ON +carrier detected, +.It Dv ATMIF_CARRIER_OFF +no carrier, +.It Dv ATMIF_CARRIER_UNKNOWN +the state of the carrier is unknown, +.It Dv ATMIF_CARRIER_NONE +the device has no notion of carrier or is not able to sense it. +.El +.It Fa mode +For ATM devices with a SUNI chip this is the current mode of the interface: +.Bl -tag -width XXX +.It Dv ATMIF_SUNI_MODE_SONET +The interface is in SONET mode. +.It Dv ATMIF_SUNI_MODE_SDH +The interface is in SDH mode. +.It Dv ATMIF_SUNI_MODE_UNKNOWN +The interface either has no SUNI interface or the mode is unknown (for example, +interface is down). +.El +.El +.Pp +An ATM interface can be found by name or by SNMP interface index (see +.Xr snmp_mibII 3 +for a discussion of interface indexes). +The function +.Fn atm_find_if_name +searches an interface given a name. +The function +.Fn atm_find_if +searches an interface by its interface index. +Both functions return NULL if an interface cannot be found. +.Pp +The ATM MIB contains the following fields: +.Bd -literal -offset indent +struct atmif_mib { + u_int version; /* currently 0 */ + + u_int device; /* type of hardware (system specific) */ + u_int serial; /* card serial number (device specific) */ + u_int hw_version; /* card version (device specific) */ + u_int sw_version; /* firmware version (device specific) */ + u_int media; /* physical media (see MIB) */ + + u_char esi[6]; /* end system identifier (MAC) */ + u_int pcr; /* supported peak cell rate */ + u_int vpi_bits; /* number of used bits in VPI field */ + u_int vci_bits; /* number of used bits in VCI field */ + u_int max_vpcs; /* maximum number of VPCs */ + u_int max_vccs; /* maximum number of VCCs */ +}; +.Ed +.Ss NOTIFICATIONS +An other module can register with +.Nm +to receive notifications when certain events happen on the ATM interface. +The registration is done with +.Fn atm_notify_aif +which takes a pointer to the interface, the calling module pointer, a callback +function and a user argument that is passed to the callback function. +The callback function is called with the interface pointer, a notification +code, a notification argument and the user argument. The following +notifications are defined: +.Bl -tag -width XXX +.It Dv ATMIF_NOTIFY_DESTROY +The interface is destroyed. The notification argument is not used. +.It Dv ATMIF_NOTIFY_CARRIER +The carrier state on the interface has changed. The argument is the +.Em old +state of the carrier. The new state can be obtained from the interface +structure. +.It Dv ATMIF_NOTIFY_VCC +A permanent VCC has been created or destroyed. The argument is an u_int that +can be decoded as follows: +.Bd -literal -offset indent +vpi = (arg >> 24) & 0xff; +vci = (arg >> 8) & 0xffff; +state = arg & 1; +.Ed +.Pp +.Va state +is 0 if the VCC was destroyed and 1 if it was created. +.El +The registration for notification can be undone by passing the return +value from +.Fn atm_notify_aif +to +.Fn atm_unnotify_aif . +The registrations is automatically removed if the interface is destroyed. +.Ss MIB +The MIB implemented by the module is defined in +.Pa BEGEMOT-ATM.txt . +In the generic part there are two tables and one scalar, there is also +a system specific group: +.Bl -tag -width XXX +.It Va begemotAtmIfTable +This table is an extension of +.Va ifTable . +It contains a row for each ATM interface and is index with +.Va ifIndex . +All fields are read-only except the +.Va begemotAtmIfMode +column. +.It Va begemotAtmIfTableLastChange +Contains the tick when a row was created or destroyed in the above table or +0, if the table did not change since start of the SNMP agent. +.It Va begemotAtmHWTable +Is also indexed by +.Va ifIndex +and contains hardware specific information. This table is read-only. +.El +.Sh FILES +.Bl -tag -width "XXXXXXXXX" +.It Pa @DEFPATH@atm_tree.def +The description of the MIB tree implemented by +.Nm . +.It Pa @MIBSPATH@BEGEMOT-ATM.txt +This is the MIB that is implemented by this module. +.Sh SEE ALSO +.Xr bsnmpd 1 , +.Xr snmpmod 3 , +.Xr snmp_mibII 3 , +.Xr snmp_netgraph 3 , +.Xr gensnmptree 1 +.Sh AUTHORS +.An Hartmut Brandt Aq harti@freebsd.org |
