                                                                              Ethernet Monitoring and
                                        Ethernet Monitoring and
                                        Ethernet Monitoring and                                          Documenting System
                                        Documenting System
                                        Documenting System                E                    This manual describes the architecture and current 3                    implementation of the EMU system                                                                                                                '                ________________________ J                June 1995
               June 1995
               June 1995                                  _________________________________________________________________
            Preface
            Preface
            Preface                                                                                               ]                                              _
                                             v                                   _________________________________________________________________
            preface
            preface
            preface           <             The manual is divided into two broad categories:  (                o  Architectural overview  (                o  Current implementation                                                                          _                                             ___
                                            vii                        h                _________________________________________________________________
               Contents                  _________________________________________________________________
               Preface                                                         v                   _________________________________________________________________
               preface                                                       vii     w                _________________________________________________________________
               Chapter 1  Introduction   P                       1.0.1     Main Features................................1-2    z                _________________________________________________________________
               Chapter 2  System Overview  P                2.1    Core System............................................2-1  P                       2.1.1     Listener.....................................2-1  P                       2.1.2     PSR..........................................2-1  P                       2.1.3     PSR interface................................2-2  P                       2.1.4     Network Views................................2-2  P                       2.1.5     Relater......................................2-3  P                       2.1.6     Identity.....................................2-3  P                       2.1.7     EMU network..................................2-4  P                       2.1.8     Database Overview............................2-5  P                       2.1.9     Record Structure.............................2-5  P                       2.1.10    Record Header................................2-5  P                       2.1.11    Database Access..............................2-6  P                2.2    Counter Processing System..............................2-6  y                _________________________________________________________________
               Chapter 3  Implementation   P                3.1    Introduction...........................................3-1  P                3.2    Listener...............................................3-1  P                       3.2.1     Description..................................3-1  P                       3.2.2     Processing abstract..........................3-1  P                       3.2.3     Ethernet buffers.............................3-2  P                       3.2.4     Protocol type formats........................3-3  P                3.3    PSR....................................................3-4  P                       3.3.1     Description..................................3-4  P                       3.3.2     Control Record...............................3-4  P                         3.3.2.1       PSR Records............................3-4  c                                               ___
                                              iii                  M                    3.3.3     General processing...........................3-7   M                      3.3.3.1       Adding records.........................3-7   M                      3.3.3.2       Deleting Records.......................3-7   M                      3.3.3.3       Compression............................3-7   M                      3.3.3.4       Locking................................3-7   M                      3.3.3.5       Exit and restart.......................3-8   M                      3.3.3.6       Command Mailbox........................3-8   M                      3.3.3.7       Other process interaction..............3-8   M             3.4    Relater................................................3-8   M                    3.4.1     Description..................................3-8   M                    3.4.2     Relater database.............................3-8   M                    3.4.3     Relater Frame................................3-9   M                    3.4.4     BOXID Modification..........................3-10   M             3.5    Alert Subsystem.......................................3-11   M                    3.5.1     Description.................................3-11   M                    3.5.2     Alert generation............................3-13   M                    3.5.3     Alert processing............................3-14   M                    3.5.4     Alert Formatting and Transmission...........3-15   M                      3.5.4.1       Data typing...........................3-15   M                      3.5.4.2       Parameters and translation............3-15   M                      3.5.4.3       Alert log files.......................3-16   M             3.6    Counter Processing....................................3-17   M             3.7    Counter Processing....................................3-17   M                    3.7.1     Description.................................3-17   M                    3.7.2     Counter Processing files....................3-17   M                    3.7.3     CNTRPOLL.DAT................................3-17   v             _________________________________________________________________
            Chapter 4  Programming Notes  M             4.1    General Notes..........................................4-1   M             4.2    Acknowledgements.......................................4-1   M             4.3    System Tour............................................4-2   M                    4.3.1     Startup and Shutdown.........................4-2   M                    4.3.2     LISTEN.......................................4-2   M                    4.3.3     PSR..........................................4-3   M                      4.3.3.1       PSR Tour...............................4-4   M                      4.3.3.2       PSR Database...........................4-5   M                      4.3.3.2.1     PSR Mapping............................4-8   M                    4.3.4     Relater Tour.................................4-9   M                      4.3.4.1       Relater Frame.........................4-10   M                    4.3.5     Configuration Pollers.......................4-11   M                    4.3.6     Main Database - EMUDB.......................4-12   ]                                             __
                                            iv                  M                    4.3.7     User Interface..............................4-12   M                      4.3.7.1       Query Overview........................4-13   M                      4.3.7.2       Report Overview.......................4-13   M                    4.3.8     Alert Mechanism.............................4-13   M             4.4    Summary...............................................4-14   _             _________________________________________________________________
            Index   `             _________________________________________________________________
            Tables  M                    3-1    Ethernet Buffers................................3-2   M                    3-2    Protocol Types..................................3-3   M                    3-3    PSR Control Record..............................3-4   M                    3-4    PSR Record Header...............................3-4   M                    3-5    System Control..................................3-6   M                    3-6    Relater Database................................3-8   M                    3-7    Relater Frame...................................3-9   M                    3-8    Alert Format...................................3-11   M                    3-9    EMU_CNTPOLL.DAT Format.........................3-17   M                    3-10   EMU_CNTPOLL.DAT Format.........................3-18   M                    3-11   CNTRPRC Record.................................3-18   M                    4-1    PSR First Record................................4-5   M                    4-2    PSR Common Record Header........................4-6   M                    4-3    Map Structure...................................4-8                   ]                                              _
                                             v                                   _________________________________________________________________
            Chapter  1
            Chapter  1
            Chapter  1  J             Introduction
            Introduction
            Introduction    J                Ethernet monitoring and documentation system is intended toI                achieve two major goals: Document and Monitor the network.   D                In it's simplest form, the system listens to the LAN,K                receives all packets and passes selected packets to protocol K                specific routines which extract information specific to that I                protocol. This is used to build an internal database which I                in turn drives the monitor and documenting functions. More                 specifically:                  o  Document:   '                   o  For all addresses:   2                     o  Protocols in use by address  #                     o  Manufacturer   ,                   o  For selected protocols:  #                     o  Node name(s)   /                     o  Higher layer address(es)   8                     o  Functions address will respond to  G                     o  Protocol specific data useful for Monitoring and "                        documenting                  o  Monitor:  )                   o  Provide alert system   5                   o  Monitor param and status changes   D                   o  Collect and monitor counter data (as available)  L                In this version (5) it is intended to move the system towardsH                a wide area system where the information gathered locallyM                directs the system to collect information about devices not on M                the local LAN. As topologies evolve, it is clear that a system ?                restricted to the local LAN will be less useful.   N                                                              Introduction  1-1                 _             1.0.1 Main Features
            1.0.1 Main Features
            1.0.1 Main Features   G                The two main features of this system are it's ability to L                build and provide a database of current network devices, it'sI                ability to listen to and understand the real time activity I                of individual protocols and report problems quickly and in                 context. D                This system (working title is EMU) is a client/serverG                arrangement with the server providing database and alert )                information to the client.   H                The system is plug and play: On the server side, the userL                simply starts the system and it starts listening and buildingF                the database. There is little interaction at this levelG                although a programming interface may be provided. On the F                client side the system starts up and listens for serverI                broadcasts. The information displayed is mainly raw alerts G                accompanied by addition information from other protocols H                running on the same address and current counter data. TheL                actual presentation is not yet defined but it is thought thatK                it will be a mixture of text and graphics under windows. See 1                the Client Description for detail.   J                The system is extensible. It is not possible for any singleM                tool to provide necessary information on every known protocol. E                A standard interface is defined to allow any number of H                protocol routines to be present and tools are provided toL                aid in interface to the system. These tools will be publishedI                and made available to users. The current version processes L                MOP, LAT, LAVC, IP, DECnet,OSI, IP, IPX/SPX, Ethernet and STP                (bridge)   C                The system is self maintaining. To the degree possi- J                ble/practical, the system provides extensive feedback loopsL                and is aware of bottlenecks in itself. Simple counter data isJ                maintained by each major routine and is made available to aJ                system monitor that can reset base parameters used to startH                the system. Think about AUTOGEN, what is does and what it                could/should be.   K                EMU can operate primarily as a passive device in which there L                are no special requirements for any node on the network to beM                included for monitoring and documentation purposes. In future, I                node server processes may be available and when run on the M                client will add significant functionality. It is intended that                  this be optional.  E                EMU now requires both a DECnet and IP address and must F                integrate into the customer's addressing schemes. Also,H                with the addition of Counter processing, and SNMP and NMLL                access, EMU adds data to the customer net. The amount of data               1-2  Introduction                  K                is somewhat controllable and easily estimated should this be                 necessary.   K                In addition to VMS and DECnet software, EMU now requires UCX >                (AKA TCPIP Services) software to operate fully.  J                It is intended that this product address a critical lack in#                other products seen:   G                o  It is common for any single network device to utilise G                   multiple protocols in it's normal operations and this I                   trend is expected to expand greatly in the near future. J                   No product seen or heard to date has the ability to makeH                   the relationship between multiple protocols and singleI                   stations and use this information to enhance management L                   functionality. This is a central objective of this system.  F                o  All tools out there assume that the customer alreadyJ                   understands, to varying degrees, both the content of theM                   network and what constitutes 'proper' operation. This is an L                   unsafe assumption that this system does not make. It findsK                   all the devices and monitors them , building over time, a L                   simple profile of what normal operation is for any device.8                   It then reports changes and anomalies.  I                o  In addition to the assumption above, many tools require I                   that the customer manually enter this lack of knowledgesI                   into the system, defining the devices, possible errors, L                   actions to take and so on. EMU is self-configuring both inM                   finding stations and the protocols they they are using, and J                   in determining normal operation of the attached network.I                   There is no user configuration required to provide full5M                   function although interfaces are supplied if the user wants L                   to name items, group items together or selectively monitorK                   components. A comprehensive reporting package is inherit.   M                o  Many tools, particularly SNMP based ones use polling almost J                   exclusively to gather data and determine status. At thisH                   writing, more than 80% of the information known to theK                   EMU system is gathered by passive listening. EMU does notcK                   contribute to the loaded network problem while attemptingb                   to solve it.  J                In the longer term, it is intended that the system become aH                sort of 'system service', providing a dynamically updatedM                network information on request from any client. The client can M                also set up a window into the server to receive current alerts_J                and initiate specific monitoring functions. This product isH                not intended to be 'yet another Ethernet monitor'.It doesK                not count or record traffic volumes beyond those counts that L                are necessary to monitor a specific protocol. Neither does itL                display top talkers and listeners and it has only rudimentary  N                                                              Introduction  1-3 _  _            K                ability to show the traffic relationships between protocols.FH                Those types of monitors can be classed as Level 2 devicesK                in that it is at that level that they read and analyse data. K                This is a layer 3 monitor in that it uses layer 3 (and above.G                in some cases) data to determine protocol activity. It's.I                primary purpose is to provide an up to date picture of the.L                network that network and system managers can use to determineJ                the presence and state of protocols on the net and use thisH                information to monitor the net and automatically load any>                other monitoring tool with current information.                                                                                             1-4  Introduction  .                                _________________________________________________________________
            Chapter  2
            Chapter  2
            Chapter  2  S             System Overview
            System Overview
            System Overview     C             The system is currently described in 2 major divisions:                   o  Core system.                  o  Applications  L             The major distinction between a process existing at either levelJ             is the internal database and write access to it: Core routinesI             have direct access and applications do not. In implementationrK             there may be difficulty in maintaining this distinction clearly ?             but it requires persuasive reasoning to violate it.   S             2.1 Core System
            2.1 Core System
            2.1 Core System   C             The core system is made up of a number of processes and3J             structures who's main objective is to document the network andM             supply an API to the application layer who's main objective is to.              monitor the network.P             2.1.1 Listener
            2.1.1 Listener
            2.1.1 Listener  K             The listener is thoroughly documented elsewhere. Suffice to say L             here that it provides one of many inputs to the PSRs and acts as             a source of data. A             2.1.2 PSR
            2.1.2 PSR
            2.1.2 PSR   H             The array of PSRs provide the first level of 'understanding'H             in any particular network. A network is composed of multipleI             devices cooperating via a protocol. Most protocols provide an I             internal management facility in order to maintain orderlinessDJ             and will exchange information on the content and events withinM             that network among themselves. It is this 'conversation' that the4M             Listener picks up and passes to the PSRs. Each PSR is responsible3I             for a single protocol and extracts data useful for management J             purposes and stores it. Additionally as network changes ensue,H             the PSR detects and alerts those changes to higher layers. AL             fully implemented PSR will usually be implemented in a number ofJ             standalone but intercommunicating processes. Fully implemented#             includes the following:t  L                o  Ability to receive protocol data units (PDU) directly fromM                   the network and extract information useful to EMU purposes.B  M                o  Provide a poller function to inquire of the network furthery1                   data to enhance EMU usefulness.   N                                                           System Overview  2-1                 J                o  Provide a process to receive and process any asyncronous2                   events the network may generate.  D                o  Provide an analysis function able to correlate theI                   inputs from the other processes and make determinations.E                   as to protocol address and/or network integrity andm                    functionality.  _             2.1.3 PSR interface
            2.1.3 PSR interface
            2.1.3 PSR interface   M             It is essential to the success of this architecture that new PSRs I             can be added, changed and deleted easily. It is a fundamental H             goal here to add new functionality at this level as dictatedJ             by events and to retire older, less useful functions. Further,H             as functions change, they must integrate seamlessly with theL             supporting structures. In practice, the Listener(s) and PSRs are#             the centre of the core. _             2.1.4 Network Views
            2.1.4 Network Views
            2.1.4 Network Views.  L             There are a number of underlying principles driving the databaseH             structures. The most fundamental is the required 'view' of aI             network. From one perspective, the network is a collection of.J             devices all connected together and able to transport data fromL             any point to any other point. From another perspective a networkG             is a system offering a service wherein physical location ofTH             resources and the complexities of providing that service areL             hidden from consumers. That is to say the network is an extendedL             computer system, providing a seamless end to end service. EitherH             view is valid and it is a goal to support both views. An EMUI             user can view either a network and it's collection of devices L             or devices and it's attachments to various networks. As such theI             PSRs build network specific databases and pass on information J             about devices and other networks to another process that formsG             the relationship of any particular device to any particular F             network. A secondary design goal is to limit the amount ofE             traffic EMU adds to any network to absolute minimum while I             effectively attaining it's more primary purposes. As such the (             following is to be observed:  G                o  The main source of data for any PSR is that which the.J                   network uses to control itself. This data is listened toL                   by the system and understood by the PSR. A more successfulJ                   PSR understands this conversation and is able to extractF                   more information from it than a less successful PSR.  K                o  EMU does not attempt to monitor all available data on the.H                   network. Primary parameters are those contained in theL                   control messages sent by the network. Secondary params areL                   those deemed to be essential to network operation but must                    be polled for.                2-2  System Overview a  e            L                o  The majority of useful parameter data can be gathered fromM                   the network on an as necessary basis - that is to provide a.-                   complete report or similar.   M             2.1.5 Relater
            2.1.5 Relater
            2.1.5 Relater   M             Information gathered on any single network often has implications K             for (and about) other networks, particularly when multiple net- L             works interconnect as is common practice. It is a responsibilityL             of the PSRs to make this information available and it is the re-L             later that acts upon the results. The relater essentially buildsI             the 'device' level database and ensures the relationships the M             PSRs detect are propagated correctly. As such the relater is part_(             of the 'centre of the core'.I                Essentially, the relater database is device specific. Each L                record specifies EMU's view of a single device, the protocolsH                that it implements (that is the networks it attaches to),I                and other device specific information such as device type,tM                class and services. Additionally it specifies which EMU server I                contains the network level information for this device. Ito(                does this with the BOXID.  P             2.1.6 Identity
            2.1.6 Identity
            2.1.6 Identity  K                For both internal purposes and external representation it isoK                necessary to uniquely identify any single device. Internally K                EMU defines a BOXID - simply a number that is used to relate H                disparate pieces of data together. In EMU, the basic unitK                of information is an address/protocol combination. That is a M                known address and the protocol it runs is considered an atomic K                structure and they are indivisible because knowledge of eachoK                part is useless without knowledge of the other. This unit isiK                termed a protocol address. As information becomes available, F                various protocol addresses are found to exist on singleH                devices and via various mechanisms, further device and/orJ                network specific information is gathered. The relater tableL                is the place where this information is correlated and the keyI                between this table and the network databases is the BOXID. J                This identifier is quite fluid - as any protocol address isL                detected it is assigned a unique BOXID and if, as and when itK                is found to relate to another BOXID the number is changed so L                that the related data is keyed with the same BOXID. The BOXID.                is made up of 2 distinct parts:  D                o  EMU part. Each EMU server is assigned a number. InG                   implementation it simplifies a number of processes if J                   this ID directly relates to it's network address in thatK                   it is guaranteed to be unique in the network and where itcK                   is located is immediately known without requiring furtherr                   translation.  N                                                           System Overview  2-3                 I                o  Local part. This is simply a number unique in the local                    system.n  Y             2.1.7 EMU network
            2.1.7 EMU network
            2.1.7 EMU networka  H             EMU servers cooperate in their own private network. The goalM             here is to have each server contain the complete list of protocolvL             addresses on the network. Each instance of a protocol address isJ             assigned 'responsibility' to a single server. That is only oneM             server will undertake to monitor any particular protocol address. M             This is to prevent multiple servers from polling a single device. I                Each EMU server periodically sends changes to it's network I                databases to all other EMU servers on the network. The EMUsH                server to server update exchanges information on protocolH                addresses. The system must have sufficient information toH                decide which EMU server any protocol address is local to.E                Essentially this is supplied by the combination of theiJ                protocol address and the management capability it offers toK                a particular server. The majority of protocol addresses seen M                from multiple servers will provide identical facilities to alleK                but there are some circumstances where this is not true. The L                system then compares the management capabilities as seen fromL                each server and sets the location based upon that server withL                the greatest capabilities. In (the usual) case of equality, aL                scheme ensuring only one server has 'responsibility' needs toL                be present to ensure a single device is not being polled fromJ                multiple servers. Additionally, the following rules must be,                applied in an update message:  M                o  Send only those addresses detected locally. Do not send any K                   updates containing addresses that were created or changede3                   as a result of a received update.   M                o  Each update will contain the BOXID and the protocol address I                   it refers to followed by an action. the actions may be:C  K                   o  New (or updated) protocol address showing a managementeM                      level. This could be simply a number with a higher valuen;                      indicating more management capability.u  L                   o  Delete. The sender has deleted this from it's database.6                      the Receiver must also delete it.                              2-4  System Overview                 k             2.1.8 Database Overview
            2.1.8 Database Overview
            2.1.8 Database Overviewe  M             The database is divided into protocol specific sections with eachrL             section independent of all others. Thus there is a LAT database,H             an IP database and so on. Above this is the relater databaseG             which is in effect the device database. That is the relaternJ             collates information from the PSR databases and correlates theI             addresses that coexist on any single device. In each case the 7             database itself is divided into 3 sections:   L                o  The first record in any database describes the size of theJ                   following structure. That is it supplies the size of theI                   records and number of each type of record to follow (at M                   minimum). This record is used to initialise the database at 5                   startup. It is written at shutdown.i  I                o  The next section is termed the summary section and it's F                   contents and use are directed by the protocol. It isH                   effectively a summary of network contents and activity#                   on this protocol.   L                o  The remainder of the database is made up of the individualA                   records of addresses appearing on this network.s  h             2.1.9 Record Structure
            2.1.9 Record Structure
            2.1.9 Record Structure  H             While the contents and size of any record in any database isE             dictated by the needed and available information from theeJ             associated network, there are a number of common features that)             each database must adhere to:h  M                o  The database is created and maintained by a single process.nL                   This means that only that process may add and (physically)D                   delete records and further it is at that process'sF                   discretion if as and when the database is available.  M                o  Each record any any database begins with a standard header.   L                o  Each parameter stored is typed with a standard descriptor.  b             2.1.10 Record Header
            2.1.10 Record Header
            2.1.10 Record Header  L             The record header supplies information to accessing processes inK             standard format so that these processes can access any database G             using common algorithms. The header, it's size and contents J             are strictly defined and it is required that any participatingJ             database implement it. An extract will make the purpose clear:  9                o  BOXID. Assigned and written by Relater.e  J                o  Other protocols present.Assigned and written by Relater.  %                o  System control bitsb  N                                                           System Overview  2-5 v  m            I                o  Status. A field showing current status of this protocolo                   address.  -                o  Time last packet this addr.a  ,                o  Time last alert this addr.  0                o  Time this node 1st heard from.                  o  and so on...  F             The data record itself can only be written by the PSR (andL             possibly some associated pollers and such) but the header allowsM             specific process to write specific areas in the header. Note that I             any area allows only a single writer - any specific field can M             only be written by a single process. Thus the BOXID is written byiL             the Relater and can only be written by that process. ImmediatelyM             following the header is the data record for a particular protocole             address.  h             2.1.11 Database Access
            2.1.11 Database Access
            2.1.11 Database Access  L             There are 2 standard keys that any record in the database alwaysJ             has: The BOXID and the protocol address. Beyond this, a lookupH             routine must be able to specify a series of specified paramsH             used to find records. Wildcarding of any param or address isL             supported. The BOXID is internal and not displayable. The returnL             is always a pointer to the record satisfying search criteria andK             a context variable used internally to find the next record in aeL             recursive search. For security purposes any field not accessibleL             by the caller is not displayed and any search specifying a fieldF             not accessible is rejected. Given the structures above anyI             parameter stored by EMU is directly addressable by specifyingtJ             the database, a record key (any field) and a symbol specifyingL             the offset to the parameter . In this context a parameter is theJ             combination of it's Datatype and value. For most purposes this%             structure is indivisible. }             2.2 Counter Processing System
            2.2 Counter Processing System
            2.2 Counter Processing Systemw  M             This subsystem is intended to be a universally useful system usediJ             to process and store a related stream of numbers showing theirH             relationship over time. It has the following basic features:  J                o  Stores a limited number of previous samples received and-                   the time each was received.   M                o  Processes each sample as it is received into the tables andd                   determines:d  M                   o  Long term average - The average of all samples received.   H                   o  Short term average - The average of the previous 48                      samples.a                2-6  System Overview D               L                   o  Min/Max - Stores the highest and lowest values for this                      stream.  M                o  Calculates the movement range in both long and short terms. F                   That is, the system determines what the normal rangeI                   that this stream of samples is in and expresses this asi6                   a percentage of the current average.  L                o  Adjusts the range of each stream based on received values.  E                o  Calculates thresholds based on current averages ande"                   movement ranges.  M                o  Returns a status block to the caller showing which (if any)tJ                   thresholds were exceeded with an error value relative to?                   the amount and number of thresholds exceeded.   L             In general, the following sequence is used to identify addressesE             with useful data, and include them in the counter system.   M                o  On each cycle EMU_CNTPOLL determines which counter analyser G                   to call for the set of counters and calls it with the L                   address param. If the counters do not have CNTID set, theyJ                   are registered with EMU_CNTRPRC and that routine returnsK                   a CNTID - a unique ID to be associated with this counter.dL                   Each received counter is passed to CNTRPRC with it's CNTIDK                   and if the return specifies any error status, an alert isS                   generated.  G                o  On each cycle CNTRPOLL determines if it is any use to H                   continue polling this address for data. If the addressG                   answers less that 10% of attempts with good data, the I                   record is removed from the database and this is flagged L                   in the DB1 MOP record. This flag prevents the address fromC                   being inadvertently reintroduced to the database.   K                The counter system, is intended to be universal. That is any.I                stream of related numbers can be processed through it with $                only 2 prerequisites:  H                o  The samples are integer only and must be 64 bits wide.  3                o  The samples must not be negative.v  G             However, to provide usefulness the following should also beh             observed:t  M                o  The samples should be passed to the subsystem on a regular,nK                   cyclical basis. The resulting outputs are less meaningfulo@                   if the time between samples is highly erratic.  K                o  Each counter uses significant disk space processing time. I                   For a single MOP node about 6300 bytes of disk space isiM                   used and again, some processing time. The point is that thenJ                   system is a heavy user of resources and should be called  N                                                           System Overview  2-7                 M                   upon only when the returns are useful and worth the effort.iJ                   To that end, one of the calculations always performed isH                   the number of times a node was polled for data and theJ                   number of times it responded with good data. Should thisF                   fall below 10% the entry is deleted from the system.                                                                                                        2-8  System Overview    d                             _________________________________________________________________
            Chapter  3
            Chapter  3
            Chapter  3  P             Implementation
            Implementation
            Implementation    V             3.1 Introduction
            3.1 Introduction
            3.1 Introduction  G             This is the 5th major revision of EMU and it's 3rd complete.F             re-write. While many of the essential ideas and approachesH             are preserved, virtually all of the data structures and manyL             algorithms are changed. This section specifies an implementation5             of the architecture described previously. ;                Core
               Core
               Coreh  J             The core routines are the basic building blocks upon which theM             rest of the system depends. The individual routines are describedo             here.mJ             3.2 Listener
            3.2 Listener
            3.2 Listener  Y             3.2.1 Description
            3.2.1 Description
            3.2.1 Description   M             The listener assigns a channel to the first Ethernet device found K             on the local system and enables it in promiscuous mode enabling J             it to receive all frames on the cable. Through logic describedH             below it distributes selected frames to the PSRs for further             processing.cq             3.2.2 Processing abstract
            3.2.2 Processing abstract
            3.2.2 Processing abstract   I                o  Acquire control lock to ensure exit at system shutdown.s  B                o  Open error log. See Error processing for details                  o  Map to:w  L                   o  Monitor section. See system monitor section for detail.  E                   o  Control Section. See Control section for detail.f  5                   o  Ethernet buffers. Details below.s  ?                o  Create command mailbox and que read with AST.   @                o  Create Ethernet buffer address. Details below.  7                o  Associate with CEF 63-127. (64 flags)n  I                o  Call ASSETHCHN to locate and assign channel to EthernetF                   device  .                o  Que all buffers to Ethernet.  p                   Main Routine:
                  Main Routine:
                  Main Routine:
               o  "                o  On any flag set:  N                                                            Implementation  3-1 m  o            .                o  Locate buffer using flag set  4                o  Validate source addr and Dest addr  =                o  Determine and set PTYTYP. See Detail below.e  ,                o  Apply all defined filters:  0                o  Lookup PSR table for processor  :                o  If found set corresponding bit in frame.  K                o  If at end any bits are set, set the corresponding CEF(s).t*                   If not reque to Ethernet  I                o  Scan outstanding table and reques any returned buffers.o  h             3.2.3 Ethernet buffers
            3.2.3 Ethernet buffers
            3.2.3 Ethernet buffers  D             There is an architectural limit of 64 buffers set by theG             maximum number of Common Event Flags available in VMS. ThisoE             implementation uses 32 for Ethernet buffers reserving thenH             remaining 32 flags for other uses. Each buffer is associatedK             with a single event flag through the Ebuff_addr table set up attI             init time. The table is a list of addresses of the buffer and J             is 32x4 bytes long. After mapping Ebuffs, the start address ofI             this section is placed in the first location of the table and L             this +1552 is placed at the second location and so on for all 32L             locations. Thus when a buffer is read off the Ethernet, locatingF             it is a simple task. The buffer itself is used as follows:                  ______________________________________________________________
               Table 3-1:  Ethernet Buffers
               Table 3-1:  Ethernet Buffers
               Table 3-1:  Ethernet Buffers                   ______________________________________________________________
               Offset Len    Description
               Offset Len    Description
               Offset Len    Description  1                0      4      Target process flagsf  )                4      4      Return Flagso  *                8      4      Buffer Number  "                12     4      Spare  !                16     8      IOSB   ,                24     20     Ethernet header  *                44     4      Buffer number  !                48     1500   Datap  p                ______________________________________________________________
               1548   4      Spare               Notes:  M                o  The Ethernet header is as returned by VMS and NOT as on thec2                   network. See VMS doc for detail.               3-2  Implementationn n  m            K                o  IOSB is the input output status block as returned by VMS. I                   The listener must check status completion and all other <                   processes use the len field in processing.  M                o  Data can be up to 1500 bytes long (Ethernet specification).   M                o  Target Flags, Return Flags. When LISTEN determines a buffer F                   should be passed to a process, it sets the processesG                   corresponding flag in Target. This collection is theneI                   used as a mask to set the corresponding CEFs, waking uprJ                   the process(es). Once the process has completed, it setsG                   it's corresponding flag in the return field. When alliJ                   Target Flags are matched by Return flags, the buffer may                   be requed.  w             3.2.4 Protocol type formats
            3.2.4 Protocol type formats
            3.2.4 Protocol type formats   J             There are 2 major Ethernet types and within 1 type there are 24             subtypes - effectively 3 types in total.  I                o  Ethernet type 2 - also known as DIX, specifies a 2 byte L                   protocol type and in the VMS return is found at offset 12.K                   Byte 14 - 2- are not written. We will know this as type 1   J                o  802.3 also known as IEEE specifies Service Access PointsM                   (SAPs) with the source SAP at offset 12 and the destination E                   SAP at offset 13. Byte 14 is written with a control I                   field. A SAP is often meaningless to us though some are M                   universally defined as protocol types. We know this as types                   2.  M                o  SNAP. An IEEE frame with both saps set to %XAA that is byteeL                   12-13 are %XAAAA. This defines the SNAP SAP and means thatJ                   a 5 byte protocol field follows at offset 15. The is EMU                   type 3.s  K             In order to speed processing. EMU converts these to an internale'             standard format as follows:t                  ______________________________________________________________
               Table 3-2:  Protocol Types
               Table 3-2:  Protocol Types
               Table 3-2:  Protocol Types                   ______________________________________________________________
               Offset Len    Description
               Offset Len    Description
               Offset Len    Description  8                0      1      EMU defined type - as above  /                1      5      SNAP protocol typer  3                4      2      Ethernet protocol type   z                ______________________________________________________________
               5      1      IEEE source SAP  M             Note that any part of the above not defined for a particular type K             must be zero. That is bytes 1 - 4 are 0 in type 2 and bytes 1-3n              are zero for type 1.  N                                                            Implementation  3-3 o               ;             3.3 PSR
            3.3 PSR
            3.3 PSRc  Y             3.3.1 Description
            3.3.1 Description
            3.3.1 Descriptionl  J             The Protocol Specific Routines are exactly that - they processM             all frames received for a particular protocol, extract the usefuloK             data (formatting as necessary), build and maintain the databasetK             and perform basic analysis as possible with the data available. I                Each PSR is responsible for it's own separate database. ItdL                creates, saves and restores it largely under it's own controlJ                and discretion. The database itself is made of fixed length3                records in memory and is in 2 parts:a  b             3.3.2 Control Record
            3.3.2 Control Record
            3.3.2 Control Record  K                The 1st record of all PSR databases is a control record thateM                the PSR uses to map to the section. The size of this record isfM                set by the record size for that PSR but cannot be less than 64rK                bytes (standard header) The 1st (undefined number) of fieldsaI                in the control record are standard and the PSR may use theq5                remaining space for it's own purposes:e                  ______________________________________________________________
               Table 3-3:  PSR Control Record
               Table 3-3:  PSR Control Record
               Table 3-3:  PSR Control Recordn                  ______________________________________________________________
               Symbol                Offset  Description
               Symbol                Offset  Description
               Symbol                Offset  Description  G                COM_DBHDR_L_ENTRIES   0       Number of physical entries   =                COM_DBHDR_L_RECSIZE   4       Size of each reco  K                COM_DBHDR_L_          8       Max number of physical entriesd                MAXENTRIES                   ______________________________________________________________
               COM_DBHDR_L_FLAG      12      EMUPID of the DB ownerr  M             This record is read by the PSR on startup and is used to size thetJ             section initially. It is written at exit or any time a re-sizeM             is executed. This record is the same length as all records in the K             associated DB so will be various lengths in different DBs. Some.F             part of the rec should be reserved for PSR specific needs.  _             3.3.2.1 PSR Records
            3.3.2.1 PSR Records
            3.3.2.1 PSR Recordse  J             This is the familiar DB1 structure with a new header. All recs             have this header:t                  ______________________________________________________________
               Table 3-4:  PSR Record Header
               Table 3-4:  PSR Record Header
               Table 3-4:  PSR Record Header                  ______________________________________________________________
               Symbol                Offs Len  Description
               Symbol                Offs Len  Description
               Symbol                Offs Len  Description  :                COM_HDR_L_FLAGS       0    4    Flags below               3-4  Implementation  u  r                            ______________________________________________________________
               Table 3-4 (Cont.):  PSR Record Header
               Table 3-4 (Cont.):  PSR Record Header
               Table 3-4 (Cont.):  PSR Record Header                  ______________________________________________________________
               Symbol                Offs Len  Description
               Symbol                Offs Len  Description
               Symbol                Offs Len  Description  ?                COM_HDR_L_BOXID       4    4    Unique device id   F                COM_HDR_L_PTYBITS     8    4    Other protocols present  C                COM_HDR_L_SYSCTL      12   4    System control flags   >                COM_HDR_Q_LSTHRD      16   8    Last time heard  C                COM_HDR_Q_LSTALT      24   8    Time last alert sent   =                COM_HDR_Q_FSTHRD      32   8    Time 1st heardd  =                COM_HDR_L_STATUS      40   4    Current statusm  G                COM_HDR_L_ACNT        44   4    Count of access this reco  9                COM_HDR_L_LEN         48   4    Len of KEY   B                COM_HDR_L_HOWSET      52   4    How this addr found  H                COM_HDR_Q_LOCKFIELD   56   8    Count of current accesses  F                COM_HDR_L_READLOCK    56   43   Count of read accessors  G                COM_HDR_L_WRITELOCK   60   4    Count of write accessorse  +                Configuration         64   4 d                ______________________________________________________________
               Monitor  =                1. FLGS. The EMU defined PID for this process.e  G                2. ID is unique to that box an may be duplicated in manyoI                   PSRDBs when the box runs multiple protocols on multiple J                   devices. It is the method EMU uses to 'tie' addresses toJ                   boxes. Made of 2 parts: bytes 0-2: locally generated ID,L                   byte 3: EMU station ID that target is local to. Results in)                   a unique ID over space.s  F                3. PTYBITS is a bit pattern wherein a bit set indicatesK                   that this box runs that (EMU supported) protocol. Thus ifnM                   DECnet, MOP and IP all appear on a specific Ethernet devicenK                   the appropriate bits are set and propagated to this field M                   in each DB. Use of this field is at 1st two-fold: IndicatestI                   to the PSR that the corresponding protocol is known andwJ                   exists in the corresponding DB. Indicates to a searchingM                   process where to find additional data for this box. The PSRtK                   will use this field when it discovers another protocol DB M                   should contain this address. If the bit is not set it sendsiJ                   the info to the relater and continues to do so until the                   bit is set.a  <                4. SYSCTL. System Control bits. Defined below  N                                                            Implementation  3-5 d  s            5                5. STATUS. Status bits. defined below.a  D                6. LSTHRD. Time the last frame received this address.  @                7. LSTALT. Time the last alert sent this address.  E                8. FSTHRD. Time the first frame received this address.   H                9. LEN. The len of data after the header. Constant in any"                   single database.  G               10. HOWSET. or more accurately how found. Each process in I                   EMU is assigned an ID for various purposes. The process H                   that found this data and caused this rec to be createdI                   is set here. Additionally the field could indicate 'seteG                   by management' if we allow user input to create recs.i5                   Essential field in troubleshooting.   L               11. ACNT is a count incremented whenever this rec is accessed.I                   Since all access is by sequential search, arranging the L                   recs so that the most often accessed are nearer the top is                   an advantage.   L               12. Spare. Exactly that - spare space for unanticipated needs.  L               13. LOCKFIELD. Should a process which to access the record, ifK                   call the locking routine with the type (read or write) of L                   access required. That routine allows shared read or sharedK                   write but not shared read/write. If it grants access, theeJ                   appropriate field is incremented so the count of currentF                   readers and writers is kept in the record. UnlockingG                   reverses this - the appropriate field is decremented._  E               14. Configuration Monitor area. Area used by the configC8                   monitor. See that routine for details.                  ______________________________________________________________
               Table 3-5:  System Control
               Table 3-5:  System Control
               Table 3-5:  System Control                   ______________________________________________________________
               Symbol                Bit  When Set
               Symbol                Bit  When Set
               Symbol                Bit  When Set  =                SYS_COM_V_SCDEL       0    This rec is deleted   D                SYS_COM_V_SC_UPDATE   1    Update this rec next cycle  B                SYS_COM_V_SC_NOPOLL   2    Do not poll this address  =                SYS_COM_V_SC_PSEUD    3    Pseudo Node - alias   F                SYS_COM_V_SC_CNTDB    4    Has been added to Counter DB  9                SYS_COM_V_SC_DISCNT   6    Counts disabledt                  ______________________________________________________________
               SYS_COM_V_SC_PROPOG   7    Addr has been propagated to EMUDB                3-6  Implementationt    m            n             3.3.3 General processing
            3.3.3 General processing
            3.3.3 General processing  K             At startup acquire the exclusive access lock and open the file. K             If not found generate one using defaults either embedded in the L             PSR code or system params. The 1st rec gives the layout and infoK             needed to create the section. Create it and read the records inoI             using the ACNT field as the key (descending). This starts the H             DB with the most accessed recs at the top. Write the size ofL             the section to the LOCK VALUE BLOCK to signal to other processesH             the current size and release lock allowing general access to             section.h             3.3.3.1 Adding records
            3.3.3.1 Adding records
            3.3.3.1 Adding records  I             In all cases, the protocol address is unique in the database.eI             Search down for this address (ignore any deleted recs) and if L             not found add it. During search note 1st deleted rec. If deletedL             rec found, overwrite with new else add it at end. Update ControlI             rec. Zero ACNT field in header Note that ONLY ONE process can L             create/delete the records while individual fields may be written"             by multiple processes.                Note that any protocol address is integrated into the system
               Note that any protocol address is integrated into the system
               Note that any protocol address is integrated into the system                 via BOXID only - it is the key by which all relationships
               via BOXID only - it is the key by which all relationships
               via BOXID only - it is the key by which all relationships                are known. When a record is added it sends the alert to the
               are known. When a record is added it sends the alert to the
               are known. When a record is added it sends the alert to the                Relater with the BOXID = 0 and no parameters. A common routine
               Relater with the BOXID = 0 and no parameters. A common routine
               Relater with the BOXID = 0 and no parameters. A common routinel                generates the BOXID and guarantees uniqueness.
               generates the BOXID and guarantees uniqueness.
               generates the BOXID and guarantees uniqueness.r  n             3.3.3.2 Deleting Records
            3.3.3.2 Deleting Records
            3.3.3.2 Deleting Records  J                Same as add - list is keyed by address. Recs can be deletedM                by address (single delete) or by ID (multiple delete). Set the.-                delete bit in any rec deleted. _             3.3.3.3 Compression
            3.3.3.3 Compression
            3.3.3.3 Compression   M                If no deleted recs and no space invoke a compress routine thateK                may ageout or otherwise identify recs to delete. If none are_L                found then invoke end processing (writes new params and exits>                - Control process will restart with new params)S             3.3.3.4 Locking
            3.3.3.4 Locking
            3.3.3.4 Locking   L                Normal mode has readers holding a concurrent read and writersE                holding a concurrent write lock respectively, allowing L                unlimited readers and writers. With the exception of the PSR,K                locks are queued with a blocking AST. Should the PSR need to_I                compress or re-size the DB, it requests an exclusive lock, L                causing delivery of the BLAST to all other accessors. In thisJ                case the BLAST routine deaccsses the section and deletes VMK                and waits for the section to recreate and the exclusive lock C                to release. The new size is in the Lock Value block.     N                                                            Implementation  3-7                 n             3.3.3.5 Exit and restart
            3.3.3.5 Exit and restart
            3.3.3.5 Exit and restart  K                An exit handler is included in all PSRs to guarantee (withineJ                reason) that the last action is to write the DB. First scanK                the DB to determine how many undeleted recs will be written. I                Calculate from this what the size of the section should be K                on next re-start (some room for expansion) and write this to K                the control record. Write the control record followed by all #                (undeleted) DB recs.ek             3.3.3.6 Command Mailbox
            3.3.3.6 Command Mailbox
            3.3.3.6 Command Mailbox   K                Each PSR has a command mailbox defined. Periodically the PSR K                reads this mailbox to determine if any messages are waiting. J                There are no specified uses for this facility but it seemedJ                a good idea at the time and might even prove useful at some                stage. It stays.d             3.3.3.7 Other process interaction
            3.3.3.7 Other process interaction
            3.3.3.7 Other process interactions  J                When mapping to any DB section, the subroutine will acquireL                the appropriate lock (share_read, Share_write) and set up theK                blocking AST. The AST routine deletes the virtual memory andsI                releases the lock. This implies that ASTs must be disabled F                during all (write anyway - not sure about read) so that/                partial records are not written.aG             3.4 Relater
            3.4 Relater
            3.4 Relater   Y             3.4.1 Description
            3.4.1 Description
            3.4.1 Description   K                The Relater accepts inputs from many sources and essentiallyrI                builds and maintains the device database. A device in this H                context is a single physical processor that at minimum isL                attached to a network and cooperates in 1 protocol. While theL                PSRs build and maintain the Network databases, the Relater is                device specific._h             3.4.2 Relater database
            3.4.2 Relater database
            3.4.2 Relater database  L                The relater database contains the BOXID and all EMU supportedE                protocols along with some device specific information:                   ______________________________________________________________
               Table 3-6:  Relater Database
               Table 3-6:  Relater Database
               Table 3-6:  Relater Databaseh                  ______________________________________________________________
               Field       offs   Description
               Field       offs   Description
               Field       offs   Descriptionp  8                BOXID       4      Key to other databases  G                PTYBITS     4      Bit pattern showing protocols present   9                MGMTBITS    4      Management capabilities   +                Device      4      See belowa                typee  y                ______________________________________________________________
               Facilities  4      See Below)               3-8  Implementation                                  Notes:o  J                o  Class. Number indicating the relative importance of this<                   device. It is (privileged) user writeable.  G                o  Services. A bit pattern showing the OSI level(s) thisoM                   device operates at. A bit set indicates the device supportsy.                   the corresponding OSI layer.  H                o  BOXID Table Table of BOXIDs that exist on this device.H                   Within each DB a single BOXID associates the addressesM                   together such that a device with 3 IP addresses will have 3dK                   entries in IP database with the same BOXID. This BOXID ishM                   placed in the relater table at the IP offset. The Offset iseM                   dictated by SYS_PID_C_xxxx in sysdef (that is the IP offsetqM                   is SYS_PID_C_PSRIP (7). The current table size accommodates_                   24 entries._  _             3.4.3 Relater Frame
            3.4.3 Relater Frame
            3.4.3 Relater FrameP  M             Any process wishing to send info that the relater acts upon sends &             the following frame to it:                  ______________________________________________________________
               Table 3-7:  Relater Frame
               Table 3-7:  Relater Frame
               Table 3-7:  Relater Frame                  ______________________________________________________________
               Field     Len   Description
               Field     Len   Description
               Field     Len   Description  -                BOXID     4     This device ID_  +                SENDER    4     Sender's PID_  3                Message   4     Add, delete or start                 Typew  /                Targets   4     Count of targetso                  ______________________________________________________________
               Data      Var   1 target structure per target               Notes:  J                o  Message type defines the action the relater will performL                   and the format and content of the data field. Each messageM                   type specifies strict format and this is used to verify the #                   received message.d  J                o  Sender is the identity of the sending PSR. It is used toM                   locate the correct database and defines the contents of the_                   record._  K                o  Data is specifically formatted according to message type.   N                                                            Implementation  3-9 _  _            n             3.4.4 BOXID Modification
            3.4.4 BOXID Modification
            3.4.4 BOXID Modification  F             If as and when a PSR or other process finds an associationM             between this address and another protocol, and the bit associated E             with this protocol is not set in the header, it sends the <             following frame to a process called the RELATER:  :                o  BOXID = Value written in this rec header  "                o  Message type = 1  #                o  Message len = Varb                  o  Data :  &                   o  Number of targets  #                     o  Target PSRID_  .                     o  Target protocol address  L             All fields must be present. Each PSR has an ID which may be usedL             to control many things but here it denotes the format and lengthJ             of the following address. The Relater puts the ID on a subject6             list and executes the following algorithm:  G             Locate each target on list and check the ID. If .eq. 0 copyCC             subject ID to it and continue. This is an unusual case.H  5                o  If set and .eq. to input, continue.   K                o  If set and .ne. to subject add to subject list, overwriteH                   and restart.  H                o  At end (all possible locations scanned and made equal)M                   delete all references to ID's overwritten in relater table.   J             Other messages will be defined to allow PSRs to send data that3             belongs at device level to the relater.c                                    3-10  Implementation u  o            _             3.5 Alert Subsystem
            3.5 Alert Subsystem
            3.5 Alert Subsystem   Y             3.5.1 Description
            3.5.1 Description
            3.5.1 Description_  G             The alert system exists to allow output of important eventseH             to the human interface. It's goal is to provide a convenientF             interface for both sides. For processing and architecturalM             considerations, the alert subsystem is broken out into 3 distinct              stages:r  G                o  Generator. Any process wishing to notify the operatorrK                   through the alert mechanism for any purpose is called thee                   generator.  L                o  Processing. The 1st level where the alert is compared withJ                   other alerts, further information is added and passed to                   next stage.   K                o  Format/Transmit. The alert is formatted for screen output >                   and sent to all currently connected clients.                  ______________________________________________________________
               Table 3-8:  Alert Format
               Table 3-8:  Alert Format
               Table 3-8:  Alert Formatn                                             Len
                                          Len
                                          Leni                                           in
                                          in
                                          in                ______________________________________________________________
               Field                      BytesDescription
               Field                      BytesDescription
               Field                      BytesDescription  :                Time                       8    System time  @                Expirey                    4    Number of Seconds  =                Sender                     4    EMU process ID   J                BLINK                      4    Location of address sending  :                Device                     4    Device Type  7                Priority                   1    Priority   >                Class                      1    Perf,config etc  F                Recent                     1    Number of recent events  G                related                    1    Number of related eventse  J                Param Count                1    No. of Params in data field  D                Display Name               49   .ascic name displayed  5                Spare                      12   Futureg                  ______________________________________________________________
               Data                       var  Params   K             A binary alert minimum length is the standard header (88 bytes)a'             and can be up to 512 bytes.n  N                                                           Implementation  3-11    d                            Notes:S  L                o  Time is the system time the alert was logged at. It is set>                   by the generator and not changed thereafter.  M                o  Expirey. If this field .gt. 0 then the message is placed intK                   the timed que. If an identical message is in the que (andrK                   not expired) then the alert is generated. See Timed Alertr                   que below.  J                o  Sender. The EMU defined identity of the sending process.J                   It is used to locate the correct database of the sending                   process.  K                o  Blink. Backward link. Offset to the record for which this_K                   alert was sent. In combination with the Sender field, ando@                   record in any database can be located quickly.  M                o  Device. The device type this alert is for. Device is an EMU_J                   Datatype (which see). This is a placeholder that layer 2                   fills in.   G                o  Priority is dynamic through the system. The generator H                   sets the initial value according to some scheme (needsH                   consistency) and the processor can adjust it in eitherH                   direction depending on other related conditions (other4                   alerts, other protocols down etc).  M                o  Class is the general area the alert falls into. This is OSI                    standard:                      o  Accounting_                      o  Performance  "                   o  Configuration                     o  Fault                     o  Security   K                   o  system *  This is a bit field so that any alert can beeM                      classified in multiple types - Often a config change hasrK                      security implications. The system class is not part of K                      the standard but we will use it to alert problems withd8                      EMU (disk full etc) to the user(s).  E                o  Recent. Layer 1 will determine if recent events are L                   present, adjust the priority if indicated and pass a countG                   of these with the alert. The user interface uses thiseI                   to advise the user of their presence. Recent events are K                   defined as any event of any class for this address in thel$                   previous 24 hours.                3-12  Implementation i  r            I                o  Related. Again. Layer 1 works out the number of related G                   events and passes this as a count. Related events are D                   defined as any event of the same class on any nodeL                   logically on the the same network as the address the event;                   is for. Some examples to make this clear:   I                   o  If the event is DECnet protocol down, any other node H                      currently down in the same DECnet area is a related                      event.   N                   o  If the event is IP down, any other IP node currently down3                      on the same subnet is related.o  N                   o  So, DECnet is divided into areas, IP into subnets and IPXM                      into subnets. This works for routed protocols but otherseN                      such as LAT, MOP and bridging do not fit well here. It isL                      for this reason mainly that future versions of EMU willN                      begin the efforts of determining the physical topology of!                      the network.w  I                o  Param count. The number of parameters found in the data                    field.  K                o  Display name. This is a placeholder filled in by layer 2.t-                   Acceptable values here are:t  L                   o  Valid BOXID. That is a BOXID that exists in the relater                      table.r  M                   o  -1 The alert class must be system and there is no BOXID.s5                      The system is sending a message.q  K                   o  Any other value results in an error and the message is                       rejected.  h             3.5.2 Alert generation
            3.5.2 Alert generation
            3.5.2 Alert generation  G             Any process can generate an alert and pass it to the systemlI             for processing. All fields must be present with the followingn             exceptions:   E                o  Device type. Layer 2 fills this field in (if known).  >                o  Recent,related and param count may all be 0.  L                o  Display name. If 0, this layer assigns and writes a unique                   ID.n  M             The alert may include no parameters or any number of params up toiH             the max len of 512 bytes. Parameter formats are given below.  D                The goal here is to simplify the processing the alertJ                generator will have to do in order to get an alert out, and9                allow any params to be present or missing.r  N                                                           Implementation  3-13 i  o            h             3.5.3 Alert processing
            3.5.3 Alert processing
            3.5.3 Alert processing  K                Here is where we accept a single alert and piece it together J                with other related events and objects in an attempt to showK                the alert as it relates to other problems on either the nodeeM                or network. Basically, the alert generator (Usually PSR) sendswJ                an initial alert to the alert processor where the following                happens:p  J                o  If the BOXID is 0 (not present) this layer assigns a newL                   BOXID, creates a record in the relater table and writes itM                   to the location given by the following parameters. Skip all M                   remaining processing and pass 'new protocol' to next layer.   I                o  If the class is 'fault' get status by calling EMU_NODE_ K                   STATUS. This routine will perform all currently available J                   tests on the node and return a complete status report inG                   specific format. If all protocols respond then ignore J                   (positive check). Set priority by adding fixed value for$                   each protocol down  K                o  All alerts: Look up BOXID for last alert this address, IfiJ                   < 24 hrs old then: Search log file for other alerts thisI                   address. Log file is an indexed file. If any are found,rM                   insert symbol at end of current param list showing start ofeM                   recent event list and record the key of each one found. Put K                   the count in the header. The number of recent alerts will L                   be limited by the first occurrence of MAX_RECENT_ALERTS orM                   total message len (512). Raise priority according to numbers2                   (and priority) of recent events.  L                o  Fill in device type field. PSR does not usually know this.<                   Adjust priority according to device class.  J                o  FUTURE: Allow for 'related' events. Again, sear log fileK                   and supply count and record number of each related event. >                   See below for description of related events.  K                o  Set displayed name for this address. First occurrence of:   E                   o  Name if known - protocol specific if appropriate   %                   o  Protocol Addresse  J                o  Because each class will have to have a separate routine,E                   it becomes possible to institute some sophisticatedeJ                   alert processing in future. Some examples: If alert is aK                   performance class and the alert is 'excessive collisions' E                   the routine could look in the Ethernet DB for other F                   nodes sharing this segment and determine if they areK                   also experiencing 'excessive collision'. If so report thecK                   segment in trouble, not the node. See segmentation below._                3-14  Implementation    T            I                o  If alert is configuration class and alert is 'parameterTF                   change' then check param value against user providedI                   template for legality. Adjust priority accordingly. Seec5                   below for description of templates.   H                o  Note that an alert can exist in multiple classes. ThusJ                   some config class alerts, particularly param changes mayL                   have security implications and will also exist as securityM                   class alerts. This process will make that determination viap6                   templates and/or hardcoded routines.  J                o  This is also the point where we will provide the hook soJ                   that the user can supply external procedures to run when(                   specific events occur.  M                o  Log alert. Set time field to current time and log the erroruH                   using the time as the key. The file is indexed and setJ                   to noduplicates. If the record does not store because ofK                   duplicate key, simply repeat the get time and store until 8                   it does. This guarantees a unique key.  K                o  Look up the address in the index and copy the time to thes5                   last alert field. (new index field)3  L                o  If there are no clients currently connected then end, elseA                   pass to Layer2 for formatting and transmission.a               3.5.4 Alert Formatting and Transmission
            3.5.4 Alert Formatting and Transmission
            3.5.4 Alert Formatting and Transmission   _             3.5.4.1 Data typing
            3.5.4.1 Data typing
            3.5.4.1 Data typingr  K                The alert is only partially processed and displayed in brief                 format.  H                Brief format is the translation of the header (all fieldsF                always present) + the first param (if present). BecauseJ                each type produces both the translation of the param and anI                associated string, a single param is adequate to produce a K                brief but useful message to alert the operator. The operator H                can then selectively display the full format which is the=                header and all params formatted and displayed.                3.5.4.2 Parameters and translation
            3.5.4.2 Parameters and translation
            3.5.4.2 Parameters and translation  H                The display process will translate the header in standard                format:  @                o  Lookup class and put address of string on list  -                o  Put address of time on list   5                o  Put address of display name on listt  J                o  Convert BOXID to DISPLAY_NAME to name and put address of                    string on list  N                                                           Implementation  3-15                 M                o  If any params present, translate param 1 and put address of.+                   resulting string on list.c  J                o  Set colour of display string according to priority. VeryI                   simple: low priority alerts are green and hi are red. AeH                   very simple calculation allows the priority to set theL                   'redness' by adjusting the green down and the red up. ThusB                   we can show priority clearly in 255 equal steps.  M                o  Display alert on all clients currently connected and having '                   alert screen present.o  H                In implementation the translation is in two parts: Part 1K                translates the individual params according to the directivesEL                and modifiers producing both the FAO directive string and theC                faolist and then part 2 assembles the final message.   E                Note that for initial display the message is only part L                translated and displayed - that is in brief format. Only whenJ                the operator selects the displayed alert for expansion doesK                the entire message become translated and displayed. Thus the L                programmer need not be concerned with message length and such:                but just include any and all relevant data.  .                A symbol file will be supplied.  k             3.5.4.3 Alert log files
            3.5.4.3 Alert log files
            3.5.4.3 Alert log files   K                Above implies a lot of log file access and disk is too slow,.M                so... The alert log file can be made as a RAM disk and limited I                to storing only alerts for the previous 24 hours. After 24 J                hours the brief version is written to disk and removed fromL                the RAM disk. At 512 bytes (max) per alert we can store 2,000L                alerts/ MB of RAM space so a 5MB RAM disk should be more thanH                adequate. If the disk file is limited to storing only theG                header (+- 100 bytes) we can store something like 10,000sI                rec/MB while keeping enough info for history lookups. This I                will relieve the current problem of the alert file growinguK                uncontrollably. The message file could also be copied to ther.                ram disk for faster processing.                                  3-16  Implementation o  d            h             3.6 Counter Processing
            3.6 Counter Processing
            3.6 Counter Processing  h             3.7 Counter Processing
            3.7 Counter Processing
            3.7 Counter Processing  Y             3.7.1 Description
            3.7.1 Description
            3.7.1 Description   H             The counter system supplies a standard method of determiningF             normal ranges any counter moves in. It can then be used toA             determine abnormal operation of the monitored device.              3.7.2 Counter Processing files
            3.7.2 Counter Processing files
            3.7.2 Counter Processing files  L             There are 2 data files , one standalone routine and one callable6             object associated with the counter system:  K                o  CNTRPOLL.DAT. Contains the list of addresses and counters M                   that will be polled for data on the next cycle. Any process J                   detecting that counter data is available (and desirable)'                   can add to this file.   J                o  CNTRPRC.DAT. Contains the sample data and so on for each                   stream.   F                o  EMU_CNTPOLL.EXE. Is the main standalone process thatL                   initiates polls to the devices and submits the raw results                   to CNTRPRC.   M                o  EMU_CNTRPC is a callable routine that processes the streamseH                   as described here. This is the main counter processing                   routine.  \             3.7.3 CNTRPOLL.DAT
            3.7.3 CNTRPOLL.DAT
            3.7.3 CNTRPOLL.DAT  I             This file contains entries that the CNTRPOLL routine reads ontF             each cycle. Each entry specifies the routine that requestsE             and formats the counter data and address to request from. H             Additionally, it control information and indexes to the data             in CNTRPRC.DAT.t                  ______________________________________________________________
               Table 3-9:  EMU_CNTPOLL.DAT Format
               Table 3-9:  EMU_CNTPOLL.DAT Format
               Table 3-9:  EMU_CNTPOLL.DAT Format_                  ______________________________________________________________
               Field         Len   Description
               Field         Len   Description
               Field         Len   Description  4                BOXID         4     Identifies device  =                Routine       4     Counter processing routine   <                Last Seen     8     Time last successful poll  <                Polls         4     Number of polls this addr  J                Success       4     Number of answered polls with good data  =                Address       8     Protocol address of devicei                  ______________________________________________________________
               Counter Tbl   488   Counters - See table below   N                                                           Implementation  3-17    d            E             The file is indexed and the key is the 1st 8 bytes of the I             record (BOXID/Routine). Each 512 byte record will accommodate F             40 individual counters. Each counter is stored as follows:                  ______________________________________________________________
               Table 3-10:  EMU_CNTPOLL.DAT Format
               Table 3-10:  EMU_CNTPOLL.DAT Format
               Table 3-10:  EMU_CNTPOLL.DAT Format                  ______________________________________________________________
               Field         Len   Description
               Field         Len   Description
               Field         Len   Description  0                Name          8     Record header                  ______________________________________________________________
               CNTID         4     CNTID assigned by EMU_CNTRPRC  F             The name field is the standard PARAMTBL entry given to all             params:t                  o  Table 4 bytesm  #                o  Param no. 4 bytesi  J             The CNTID is an index to the CNTRPRC database. In general, theH             following sequence is used to identify addresses with useful9             data, and include them in the counter system.f  L                o  Among it's many functions, SETFUNC determines if and underI                   which protocols any address responds to defined counter J                   requests. When this is identified, SETFUNC adds a recordI                   with the appropriate fields filled in to this database.   M                o  On each cycle EMU_CNTPOLL determines which counter analyser G                   to call for the set of counters and calls it with the L                   address param. If the counters do not have CNTID set, theyJ                   are registered with EMU_CNTRPRC and that routine returnsK                   a CNTID - a unique ID to be associated with this counter. L                   Each received counter is passed to CNTRPRC with it's CNTIDK                   and if the return specifies any error status, an alert is                    generated.  G                o  On each cycle CNTRPOLL determines if it is any use toeH                   continue polling this address for data. If the addressG                   answers less that 10% of attempts with good data, theCL                   record is removed from the database and this is flagged inK                   the PSR record. This flag prevents the address from being =                   inadvertently reintroduced to the database.n  >             Each count is processed into the following record:                  ______________________________________________________________
               Table 3-11:  CNTRPRC Record
               Table 3-11:  CNTRPRC Record
               Table 3-11:  CNTRPRC Record                  ______________________________________________________________
               Field            Ofs  Len  Description
               Field            Ofs  Len  Description
               Field            Ofs  Len  Descriptiono  <                CTP_W_CNTID      0    4    This record number  5                CTP_L_SPARE      4    4    Align/sparel                3-18  Implementation                                 ______________________________________________________________
               Table 3-11 (Cont.):  CNTRPRC Record
               Table 3-11 (Cont.):  CNTRPRC Record
               Table 3-11 (Cont.):  CNTRPRC Record                  ______________________________________________________________
               Field            Ofs  Len  Description
               Field            Ofs  Len  Description
               Field            Ofs  Len  Description   9                CTP_L_LTCNT      8    8    Long term countl  9                CTP_L_LTTOT      16   8    Long term totall  D                CTP_L_LTRNG      24   8    Long term range % movement  E                CTP_L_STRNG      32   8    Short term range % movement   <                CTP_L_STCNT      40   8    Short term Counter  8                CTP_L_MAX        48   8    Max Value seen  8                CTP_L_MIN        56   8    Min Value seen  A                CTP_L_LASTSN     64   8    System time last Sample   I                CTP_L_TBLPNT     72   8    Index Pointer to current sample   K                CTP_TL_TIMTBL    80   384  Time in Sec since previous Sample                   ______________________________________________________________
               CTP_TL_SAMTBL    464  384  Last 48 samples                Notes:  K                o  CNTID is the key for the indexed record and is the unique K                   ID stored by the caller to process further samples. It isr;                   generated at create time by this process.l  C                o  LTCNT. Count of samples added to long term total.d  L                o  LTTOT. Sum of all samples. Routine to reset on overflow is                   included.   J                o  LTRNG. Long term range. The %(+ or -) that the long termK                   average is allowed to move in and not generate a warning. J                   The long term average is calculated by dividing LTTOT byI                   LTCNT. LTRNG is then divided by this sum, multiplied byeH                   100 and added back to the sum to find the current highM                   value allowed. If exceeded a warning is written to OUTP andpM                   LTRNG is incremented. If not exceeded LTRNG is decremented. K                   Over time LTRNG indicated the 'normal' range this counter M                   moved in. A similar calculation is performed to find if then8                   current sample is below the low range.  M                o  STRNG. Short term range. It is similar to LTRNG except that K                   the values used to find Short term average are taken from .                   the table (last 48 samples).  ?                o  MAX. The highest value seen for this counter.:  >                o  MIN. The lowest value seen for this counter.  F                o  LASTSN. The time the last sample for this record was                   received.a  N                                                           Implementation  3-19 a  o            >                o  TBLPNT. Pointer to current sample in tables.  %                o  Spare. Spare space.m  I                o  TIMTBL. Table of times at which corresponding sample in &                   SAMTBL was received.  L                o  SAMTBL. Table of last 48 samples. Both tables are circularI                   buffers in which the oldest value is overwritten by the                    newest.c  K                The counter system, is intended to be universal. That is anysI                stream of related numbers can be processed through it withr$                only 2 prerequisites:  H                o  The samples are integer only and must be 64 bits wide.  3                o  The samples must not be negative.   H             Note that counters must be presented in the standard format.E             This means that for any counter subsystem there exists athK             least a routine to request and receive the data in the protocolsM             required format and an analyser that transforms the raw data intouL             meaningful information for this system. As of this writing, onlyM             the MOP counters are fully implemented but others are well on the              way:  /                o  DECnet Phase IV one each for:e  $                   o  Executor counts                     o  LAPB linese  #                   o  Ethernet lines   "                   o  LAPB Circuits                  o  SNMP:w                  o  System                  o  Bridge                              3-20  Implementation                                  _________________________________________________________________
            Chapter  4
            Chapter  4
            Chapter  4  Y             Programming Notes
            Programming Notes
            Programming Notesn    E                This section is aimed at programmers. Whether you wantlH                to extend EMU, pick it apart and recycle code or are justK                interested in it's mechanisms, this chapter is for you - yous                sad case.      Y             4.1 General Notes
            4.1 General Notes
            4.1 General Noteso  G                EMU is entirely written in Macro. The choice of language I                was easy; In spite of protestations to the contrary, MACRO M                produces tighter, faster code than any other language, howevereJ                in the transition to Alpha, this may no longer be the case.I                That and the fact that MACRO was the only language I coulddK                write in made the choice obvious. The only external softwaregG                EMU relies on is VMS (V6.0 or later), DECnet (any phase,iH                any version) and UCX (any version). In many ways, this isH                the hard way but it also allowed any broken feature to beH                fixed at home. (which is where most of this was written).I                It is quite modular - or not, depending on how you measure M                modularity. Essentially, I tried to make discrete functions astL                discrete modules and document the interface to each one. EachI                standalone program is an individual file. Library routines H                are (generally) functionally grouped together into singleJ                files. All files have a standard format and are extensivelyG                commented. The block comments are structured such that a M                simple DCL procedure can extract them and create help files. AuL                quick tour at this level can be obtained by: $HELP/LIBR=EMU5_#                HLP:EMU_ROUTINES.HLBcb             4.2 Acknowledgements
            4.2 Acknowledgements
            4.2 Acknowledgements  J                EMU was conceived and written by myself, however there wereI                very important contributions by others along the way. SomesJ                are as follows: Adrian Challinor for education on CALLS vs.I                CALLG, Alan Rawson for the DECnet NCB, Eric Von Dijk for alI                clever use of flags, Simon Stevens for help in documenting G                the undocumented, The Dutch PTT for knowingly letting meuI                write this while paying me for other work and Bank America ;                for unknowingly supplying the same facility.o        N                                                         Programming Notes  4-1                 I                Special mention of Ron James who at one point attempted toaI                convert this to C and in the effort discovered a number of L                very useful techniques. While I couldn't use his code, (can'tK                read C!), I am grateful for the opportunity to steal all his L                ideas. Finally Keith O'Brien to whom I owe a great debt. FromH                teaching me MACRO (his fault!) to advice on technique, toJ                writing a good third of the previous version, his influenceH                and code remain a large part of the present system. It isG                entirely true to say that without Keith's generosity and K                patience, EMU would not exist beyond a bunch of disconnected                 code.    S             4.3 System Tour
            4.3 System Tour
            4.3 System Tourt  H                Following is a rather wordy explanation of how the systemH                works at code level. This is the $0.25 tour - it is briefK                and skips sometimes important detail but should be useful asiK                an introduction and supplements reading of the code (or modee,                correctly the code comments).t             4.3.1 Startup and Shutdown
            4.3.1 Startup and Shutdown
            4.3.1 Startup and Shutdown  K                Executing START_EMU.COM gives options to clear the databases L                and start from fresh and then runs EMU_CONTROL detached. ThisH                process reads EMU5_DAT:PRCTBL.DAT, a list of processes itJ                should start. It is a 2 phase startup with a flag being setJ                by RELATER indicating when EMU_CONTROL should continue withH                phase 2. EMU_CONTROL acquires an exclusive lock (which ifI                it doesn't get, exits without doing anything) and for eachsK                process started, creates a termination mailbox. If a process I                exits with error, EMU_CONTROL restarts it. All activity iskJ                written to EMU5_LOG:EMU_CONTROL.LOG which you can only readL                when the system is not running (one of the less useful designI                features). Every process tries to acquire the CONTROL lock J                and if it gets it, runs it's exit procedure and stops. ThusL                to stop the system gracefully, delete the EMU_CONTROL process)                (which EMU_STOP.COM does). J             4.3.2 LISTEN
            4.3.2 LISTEN
            4.3.2 LISTEN  A                The central process at this point is LISTENV5. It:C  H                o  creates a section for Ethernet buffers and maps to it.  ?                o  creates a table of Ethernet buffer addresses.o  G                o  Creates the PSR table by reading EMU5_DAT:PSRTBL.DAT.tL                   This file specifies which process (PSR) will receive which,                   frames read from Ethernet.  H                o  Starts the Ethernet controller in promiscuous mode andJ                   queues all (32) buffers to it. Each buffer is associated                   with a flag.  "             4-2  Programming Notes    .            J                o  when an Ethernet read completes, the flag is set and theK                   flag is used as an index to the buffer section to quickly 7                   locate which buffer has been written.e  G                o  the buffer is scanned and compared with the PSRTBL toeI                   determine which, if any PSR should process this buffer.aK                   For any PSR this is destined for, a corresponding flag is J                   set in the buffer and at end all corresponding flags are,                   set to wake up the PSR(s).  L                o  at end of each loop, Listen scans for returned buffers and.                   reques them to the Ethernet.  K                o  Any PSR woken up, scans the Ethernet buffer table for theeM                   buffer(s) it should process, processes them and sets a flagmM                   in the buffer indicating it is finished. When all the flagsLM                   LISTEN set in it's area are matched by FLAGS set in the PSR +                   area, the buffer is free.L  M             Other detail in this process: LISTEN tracks the number of buffers J             outstanding to any process and should it reach it's (settable)L             limit does not pass any more buffers to it and counts a discard.  D                LISTEN validates each frame for validity by checking:  6                o  Top 3 bytes of source address .eq. 0  ;                o  Top 3 bytes of destination address .eq. 0C  ;                o  Protocol type field (or 802.3 len) .eq. 0r  K             If any of the above are true, an error is counted and the frame_:             discarded (requed without further processing).  K                There is a hook for special processing. Most frames that arerI                not multicast are discarded but there are some exceptions. J                The hardcoded filter in use now is to catch and process allK                ICMP and ARP frames under IP. A hook for OSI error frames is )                present also but not used.   A             4.3.3 PSR
            4.3.3 PSR
            4.3.3 PSR   L                Protocol Specific Routines are just that - each one processesI                a specific protocol - or more accurately a specific frame.uK                Thus PSRMOP processes MOP SYSID broadcasts, PSRLAT processes M                LAT service announcements etc. The essential purpose for a PSR K                is to extract the (protocol specific) address in use and anyoJ                other useful information that may be present and store thisK                in it's database. Each protocol address may appear only once_I                in the database. A mechanism termed BOXID is used to 'tie'bK                multiple addresses on a single device together where this isF                possible.  N                                                         Programming Notes  4-3 _  _            V             4.3.3.1 PSR Tour
            4.3.3.1 PSR Tour
            4.3.3.1 PSR Tour  K                PSRs are all implemented using identical mechanisms and if I L                was a better programmer, they would probably use shared code.J                As it stands it is more like copied code. Follows here is aL                list of generic activities any PSR will perform and followingK                that, the specific parts of those PSRs that currently exist.e  H                o  Set local symbols THIS_PROCESS, and THIS_PROCESS_FLAG.+                   Allows common code later.   K                o  Request CONTROL_LOCK. When received, it means the control L                   process has died and we join in the mass suicide. Once theM                   exit procedure is enabled, that will run just before death.   -                o  Map to all common sections:   %                   o  Ethernet bufferss  $                   o  Control Section                     o  PSRTBLa  J                o  Map to our DB. Each PSR conceptually owns it's database.G                   All other processes that map to it use a BLOCKING AST I                   and common procedure to ensure that when this PSR wants.J                   exclusive access, it can regain it. Thus each PSR uses aL                   unique procedure to map to it's own DB. To ensure no staleJ                   data is included, once the PSR maps and loads the latest<                   file in (if present), the file is deleted.  I                o  Enable the exit handler. This procedure (unique to each L                   PSR) analyses the in memory DB, sets the size it should beL                   on next startup and writes it all out to file. The process                   then dies.  F                o  Map to common event flags used. EMU uses all 64 CEFs                   available.  M                o  Initialise our area in PSTRTBL. This is where LISTEN storest9                   buffer counts associated with this PSR.n  M                o  Send a message to the relater telling it we are alive, welli'                   and waiting for work._  M                o  Wait for our flag to be set indicating a message is waitingRL                   for us to process. The flag is set by the Listener when itK                   determines a frame in the EBUFFS area should be processed_                   by this PSR.  L                o  Here starts the part that is unique to each PSR though the"                   logic is common:  #                   o  Clear the flag   "             4-4  Programming Notes    s            I                   o  Call LOCATE_PSR. This routine searches the specified N                      PSRDB for the specified address and if not found, createsK                      a new record. If created, it assigns the next (unique)NJ                      BOXID or optionally assigns one provided in the call,J                      initialises the PSR record header and indicates a newI                      record was created. If the record is found it simply D                      increments the access count and exits normally.  J                   o  If the record is created, the PSR stores parts of theL                      Ethernet frame in the PSRREC and finishes this section.K                      If the record is not created, those parts of the framegH                      that are recorded are checked against the frame andH                      if changed, overwrites the old data and sets a flag7                      indicating this record is updated.   L                o  ensure we are in the relater DB. If we are the relater hasJ                   set a flag in this record indicating such. If not createL                   a relater frame with our address in it. Some PSRs are ableJ                   to detect that this frame also belongs in another PSRDB.I                   If so, again the corresponding bits in this record will G                   indicate if it is in that DB and if not, include thisoG                   information in the relater frame. Some protocols sendtI                   node names in the frame. The NAMER DB is implemented asmL                   a pseudo PSR and as such, if the name has not been sent orL                   it has changed, include this in the relater frame. At end,J                   if a relater frame has been created for any of the above#                   reasons, send it.   G                o  Clear our bit in the Ethernet frame indicating we are K                   finished with the buffer and go back for more. If no more J                   buffers waiting, wait for the next time the flag is set.  b             4.3.3.2 PSR Database
            4.3.3.2 PSR Database
            4.3.3.2 PSR Database  J             Each PSR implements a separate database in shared memory only.F             It is recorded to file on shutdown and reloaded and erasedE             on startup. The PSR conceptually owns the database and istG             responsible for it's sizing and if necessary, resizing. AnyoH             process mapping to a PSR database uses a common routine thatM             ensures the PSR created the database and allows the PSR to regainrJ             exclusive access should it be deemed necessary. Details of the             contents follow:J                All PSRDB databases have a commonly formatted first record:                  ______________________________________________________________
               Table 4-1:  PSR First Record
               Table 4-1:  PSR First Record
               Table 4-1:  PSR First Record                  ______________________________________________________________
               EMU Symbol                 Length Description
               EMU Symbol                 Length Description
               EMU Symbol                 Length Description  K                COM_DBHDR_L_ENTRIES        0      Number of physical entries   N                                                         Programming Notes  4-5                                 ______________________________________________________________
               Table 4-1 (Cont.):  PSR First Record
               Table 4-1 (Cont.):  PSR First Record
               Table 4-1 (Cont.):  PSR First Record                  ______________________________________________________________
               EMU Symbol                 Length Description
               EMU Symbol                 Length Description
               EMU Symbol                 Length Description  D                COM_DBHDR_L_RECSIZE        4      Size of each record  G                COM_DBHDR_L_MAXENTRIES     8      Max number of physicalr8                                                  entries                  ______________________________________________________________
               COM_DBHDR_L_FLAG           12     EMUPID of the DB ownero  B             This allows common routines to map and search the DBs.  H                The remainder of the DB is specific to each PSR. A common.                header is used for each record:                  ______________________________________________________________
               Table 4-2:  PSR Common Record Header
               Table 4-2:  PSR Common Record Header
               Table 4-2:  PSR Common Record Header_                 ______________________________________________________________
               EMU Symbol                 Offset Description
               EMU Symbol                 Offset Description
               EMU Symbol                 Offset Description  6                COM_HDR_L_FLAGS            0      PSRID  A                COM_HDR_L_BOXID            4      Unique device ids  H                COM_HDR_L_PTYBITS          8      Other protocols present  E                COM_HDR_L_SYSCTL           12     System control flagsa9                                                  (SYSDEF).  @                COM_HDR_Q_LSTHRD           16     Last time heard  E                COM_HDR_Q_LSTALT           24     Time last alert sent   ?                COM_HDR_Q_FSTHRD           32     Time 1st heardi  ?                COM_HDR_L_STATUS           40     Current status   I                COM_HDR_L_ACNT             44     Count of access this reci  K                COM_HDR_L_LEN              48     Len of KEY - Protocol addre  D                COM_HDR_L_HOWSET           52     How this addr found  J                COM_HDR_Q_LOCKFIELD        56     Count of current accesses  H                COM_HDR_L_READLOCK         56     Count of read accessors                  ______________________________________________________________
               COM_HDR_L_WRITELOCK        60     Count of write accessorsi                  Notes:c  G                1. PSRID is the ID assigned to the PSR at generation. ItaJ                   corresponds to the flag used to wake the process up (and                   other uses).  K                2. BOXID is as described above: an assigned (and changeable)fL                   ID that associates records in this and other PSRDBs with a?                   specific device (computer, comms device etc.)   "             4-6  Programming Notes m  d            J                3. PTYBITS. A bit pattern in which a bit is set to indicateI                   the protocols this BOXID is running. The bit set corre-e1                   sponds to the associated PSRID.   :                4. SYSCTL. System Control Flags. These are:  +                   o  bit 0 ; Rec is deleted   I                   o  bit 1 ; Update this rec in DB. Forces update on next                       cycle.h  N                   o  bit 3 ; Don't poll. Exactly that. Don't poll this device.B                      There is no interface to control this as yet.  0                   o  bit 4 ; Pseudo node (alias)  L                   o  bit 5 ; Rec has been added to CNTDB. Hmmm ... this is a/                      facility not yet complete.r  7                   o  bit 6 ; Disable CNTPOLL. Same as 5i  K                   o  bit 7 ; Propagated PSRDB -> EMUDB. If during polling amI                      station does not answer (see EMU_CONFIGMON) this bitaG                      (when 0) forces an EMUDB record to be created withiH                      the address only. As will be described later, EMUDBK                      is the configuration database built solely by polling.fI                      It naturally does not create records when nothing istM                      received via polling but this flag forces the address toi&                      appear in the DB.  K                5. Last heard, Last alert and 1st Heard are all standard VMS B                   binary times showing exactly what they describe.  M                6. Current status. Not used. Intended to hold the latest state K                   determined for an address (available or not etc) and used /                   to alert when status changes.   J                7. Count of accesses. Each time a lookup finds this record,L                   this field is incremented. As the search is sequential, itJ                   was thought that sorting the records accesses most oftenK                   to the top of the section would speed up searching. It isiM                   probably true but as the search time is insignificant, thisc;                   remains a solution looking for a problem.   I                8. Len of Key. Essentially the len of the protocol address L                   that forms the primary key for this record. Some addressesH                   are variable length and this field also allow a common2                   routine to do all the searching.  J                9. How this address found. Originally a debug filed showingL                   the process that caused this record to be created. As thisL                   screwed up other processing, it was changed to reflect theE                   owning PSR and as such is a useless waste of space.n  N                                                         Programming Notes  4-7    c            M               10. Locking. Each .long is a count of readers/writers currently I                   accessing this record. The locking routine is such that H                   is allows shared reads or shared writes but not sharedJ                   read/write. The mechanism determines the access requiredK                   and if not currently allowed, waits a short time and then &                   completes (usually).  J             The remainder of each PSR rec is specific to that PSR. Each is<             documented in the corresponding PSR source file.  e             4.3.3.2.1 PSR Mapping
            4.3.3.2.1 PSR Mapping
            4.3.3.2.1 PSR Mappinge  K             As indicated, mapping to the PSRDBs (in fact, individual memory J             sections) uses common routines. MAPLVB_DB routine in file MAP_H             SECTIONS.MAR is used by any process other than the PSR ownerK             to map to a particular PSRDB. The address of a MAP_STRUCTURE isEI             passed to this routine and if successful, returns the section '             addresses in the structure:2                  ______________________________________________________________
               Table 4-3:  Map Structure
               Table 4-3:  Map Structure
               Table 4-3:  Map Structure                  ______________________________________________________________
               EMU Symbol            Access Description
               EMU Symbol            Access Description
               EMU Symbol            Access Descriptionc  K                SYS_MAP_Q_ADDR        Write  Returned 1st and last addressesi6                                             of section  ?                SYS_MAP_L_PID         Read   PID of DB to map to   J                SYS_MAP_L_KEY         Read   Offset in DB rec where primary5                                             key found   @                SYS_MAP_L_LCKID       Write  VMS assigned Lock id  7                SYS_MAP_L_SPR         None   Spare/Align   @                SYS_MAP_L_LOCK        Read   Address of Lock name                  ______________________________________________________________
               SYS_MAP_L_SEC         Read   Address of section nameh  L             The routine always sets up a Blocking AST to allow the PSR ownerM             to regain exclusive access if required. If not supplied, UNMAPLVB I             is set as the routine which runs as a result of receiving then             blocking AST.   L                In addition, the Lock Value Block is written by the PSR ownerJ                when it has exclusive access. The value written is the sizeI                (in pages) of the section and all other users read this to J                determine section size to map to. Should resizing occur the                PSR:n  K                1. Request the lock in EX mode thus causing the blocking AST ;                   to deliver to all other processes mapped.o  M                2. The blocking AST routine runs, withdrawing from the sectione9                   and reques the lock request in CW mode.e  "             4-8  Programming Notes                 L                3. The PSR writes out it's memory section, deletes the memoryL                   section and calculates a new size. The section is created,M                   the size is written to the LVB and the lock is converted to                    CW.   K                4. All other processes the acquire the lock, map the section H                   using the size in the LVB and normal relations resume.  \             4.3.4 Relater Tour
            4.3.4 Relater Tour
            4.3.4 Relater Tour  F             The relater is process which receives frames from PSRs andK             constructs what might be called the device level database. This I             database relates the disparate addresses together and forms aiG             view of the network as boxes. A box in EMU terminology is a H             device running one or more protocols that is detected by the             system. M                When a PSR receives a frame from the Listener, one of the main M                checks it does is to determine if the relater knows about this K                address. If not a frame is sent and the relater acknowledgesiL                receipt by setting the corresponding bit in the PTYBITS fieldK                in the PSR record. It also creates (or adds to) a relater DBc                record.  E                The theory is simple (and at odds with the code!): AnyiH                frame contains the protocol and address it is running on.I                In some cases, it can be detected that other protocols areSG                also present. For example any Ethernet address beginning J                with AA-00-04-00 runs DECnet regardless of the protocol theH                address was received on. Additionally some protocols sendJ                the node name in the frame. This information is sent to theL                relater where it assigns a BOXID, creates the PSR records (ifK                necessary) and stores the related BOXIDs in a single relater K                record. The Relater DB is implemented as a PSRDB but most of K                the common fields are not used. The data part is an array in I                which a BOXID appears in the position corresponding to the M                protocol. For example, if a MOPSYSID frame containing Ethernet I                address AA-00-04-00-14-04 is received from the Listener by J                PSRMOP, the MOP processor recognises this as a MOP address,I                a DECnet address and an Ethernet address and sends this to I                the relater along with the assigned BOXID. The MOP address J                will exist (it has been created by the sending process) butG                the others may or may not. The relater searches it's own I                database for this BOXID on this protocol and if not found,sH                creates a new record. Each other address appearing in theH                relater frame is searches for in the corresponding DB andH                if found, the BOXID is added to the relater record at theI                offset corresponding to the PID of the DB. If not found itnI                is created then added. BOXIDs are allowed to be duplicatedmI                within any single PSRdb in the case where a device can run M                multiple address (IP for example). In the case where disparateh  N                                                         Programming Notes  4-9 h  a            M                addresses are related together and the BOXIDs don't match, one                 is changed.  G                The relater then becomes the focus of most user oriented H                searches. If an IP address is searched for and found, theJ                corresponding relater record is located and what appears onL                the screen is not simply the IP address but the entire familyI                of protocols running on the device that IP address appears                 on.  e             4.3.4.1 Relater Frame
            4.3.4.1 Relater Frame
            4.3.4.1 Relater Frame   I                Following is a list and explanation of each field that canlL                appear. This is constructed piece by piece by calling CREATE_M                RELATER_FRAME repeatedly until all information is included and.>                then calling SEND_RELATER_FRAME to dispatch it.  B                o  BOXID. longword. Sending process's current BOXID  0                o  Sender. longword Sending PSRID  J                o  Message type. longword. Symbol Add, Delete or Start. TheJ                   targets are either Added to all PSRs or Deleted from allL                   PSRs. In the case of start, only the sender field is used.  A                o  Targets. longword. Number of targets to follow.d  K                o  Follows is a list of PSR/Addr targets. It is an unalignedo                   structure:  D                   o  .long process id (SYS_C_PID_xxxx) of target PSR  0                   o  .long len of following addr  K                   o  protocol address of the record in this PSR. This is ineG                      the format expected in the receiving PSR. That is:   3                     o  DECnet addresses are 2 bytesa  /                     o  IP addresses are 4 bytes   4                     o  NOVELL addresses are 10 bytes  4                     o  OSI address are variable lens  !                     o  and so on.   H             Maximum relater frame len is 512 bytes. If it is assumed theK             average len of an address is 8 bytes (actually a bit high) thendJ             this leaves room for up to 31 relationships in 1 frame. In theI             unlikely event this is not enough, the sender can continue in E             another frame - Each relationship is an independent item.   #             4-10  Programming Notes  s  e            w             4.3.5 Configuration Pollers
            4.3.5 Configuration Pollers
            4.3.5 Configuration Pollerso  I             There are 2 and are distinguished from other possible pollerssK             such as Counter pollers or Test pollers (neither of which existmL             much beyond a twinkle in the eye). The Configuration pollers areL             divided into WAN and LAN types largely because WAN traffic tendsM             to be relatively heavy and across slower and more expensive linkssL             as compared to LAN types. The LAN types (Ethernet, LAT, MOP, SCSM             and IPX) are polled for more often than the WAN types (DECnet, IPrG             and OSI). Other than that, they are identical in structure.eG                Each protocol poller is implemented separately and it is_L                beyond the scope of this section to describe them completely,L                particularly as this is done in the source code already (EMU_L                CONFIGMON.MAR). This section is more an overview on approach.  L                In general, each protocol has a routine that is called givingK                the address to poll and the address of a buffer to place the K                received data in. In the more complex protocols (WAN mostly)_I                a function code is also implemented such that a section isbJ                polled for on each call. The LAN protocols tend to be quiteJ                simple and the data is formatted directly from the receivedI                frame and sent to the database. The WAN protocols are muchnM                more complicated and intervening routines format the data intoUK                standard arrangements before they are written. In all cases,I6                the resulting data is written to EMUDB.  D                Developers Note: The access routines are functionallyK                standalone and could be incorporated into, and used by other_J                management packages. It is the purpose here to supply theseM                difficult and often tedious routines for other purposes beyonduK                EMU. Some of the modules to look in (should you be so sad as #                to pursue this) are:                   o  EMU_CMIP.MAR  0                o  GETSNMP.MAR and GETSNMPROW.MAR                  o  EMU_MOP.MAR_                  o  GETDN4.MAR                  o  GETOSI.MAR                  o  EMU_IPX.MARd  H             Should you manage to get through this code, the idea will beJ             obvious and all the others should be easily located. It is notL             intended to take a unix approach here (It was tough for me so itK             should be tough for you) but simply to avoid repeating what hasfL             been said better elsewhere and cluttering up what is intended to&             be a succinct description.  N                                                        Programming Notes  4-11 p  o            w             4.3.6 Main Database - EMUDB
            4.3.6 Main Database - EMUDB
            4.3.6 Main Database - EMUDB   K             EMUDB is a disk resident, RMS indexed file and contains all thedH             system knows about the network it is sitting on. Each recordG             contains exactly one parameter from exactly one address and J             is indexed by BOXID. If the system crashes and the PSRs cannotH             save their data, EMUDB is useless as the main index is lost.M             There is a possibility of rebuilding the PSRDBs from EMUDB and an L             effort is underway to complete that but as of now, if the systemJ             crashes, delete everything and start over. EMUDB fields are as             follows:  I                o  Protocol: The EMU assigned PID this entry is associated_F                   with. The list of PIDS assigned is in _EMUSYSDEF.MAR  C                o  BOXID :System generated unique physical device idc  G                o  Table :EMU defined table this param is in. Tables area+                   defined in _EMUDBDEF.MAR.s  L                o  Instance: The specific instance of an entity. This is a 161                   bit CRC of the parameter value.h  K                o  Param : The parameter number of this particular instance.BL                   If the protocol assigns parameter numbers, these are used.+                   If not, EMU defines them.   M             The primary key is concatenation of all of the above and dups areaM             not allowed. Any other key or combination may be duplicated A 6th K             .long is provided in the key field for use as processing flags.LL             This field is defined as part of the key but never used as such.  I                Following this is the value of the specified parameter. ItnK                is kept in 'simplified' protocol specific format. All access.I                to (and complete descriptions of) the DB is through commont1                routines found in EMUDB_ACCESS.MAR   b             4.3.7 User Interface
            4.3.7 User Interface
            4.3.7 User Interface  I                This is currently SMG and can be run multiple times on the K                same node without interference between them. It is implementaL                carefully to preserve the boundary between the system and theJ                interface as it was intended from the outset to replace it.H                This has not happened for a variety of reasons. Laziness,E                ineptitude and trying to regain a life are just a few.fA                However, it is ready for some enterprising soul...I        #             4-12  Programming Notesi i               h             4.3.7.1 Query Overview
            4.3.7.1 Query Overview
            4.3.7.1 Query Overview  H                A query is started by filling out a QUERY_STRUCTURE. ThisK                structure is passed to the search routines and is updated on L                each 'find'. It allows for any single database to be searchedJ                either forward or backward, the relater record to be lookedH                up (thus finding all BOX data) and finally formatting andF                presenting the data as a series of menu selected items.J                The formatting routines are protocol specific and are oftenJ                (especially in the ASN.1 encoded protocols - SNMP and CMIP)L                hugely complex. Full explanations are provided in the sources#                - see EMU_UILIB.MAR.ik             4.3.7.2 Report Overview
            4.3.7.2 Report Overview
            4.3.7.2 Report Overview   L                A report is generated from a report parameter file. This fileH                is created using the menus which select the parameters toL                include in the report. The report is generated in spreadsheetM                format, that is it is easily imported to Excel or other PeeWeenK                program. See EMU_RPT.MAR for full details. EMU_REPORTING.MARc@                provides a DCL interface to the report subsystem.e             4.3.8 Alert Mechanism
            4.3.8 Alert Mechanism
            4.3.8 Alert Mechanisms  J                A basic alert mechanism (that doesn't work very well) is inJ                EMU_ALTLIB.MAR and is executed with ALERT.MAR, a standaloneD                process that fields alerts, stores and displays them.G                Essentially, an alert generator acquires an alert packetrJ                (memory section), fills in the alert parameters and signalsI                ALERT to process it. The ALERT process then stores the raweG                frame on disk, then translates and displays the alert ifuF                an alert display process is running. A number of unusedE                mechanisms are in play here and need some explanation:fL                What is present is the lower layer of a 2 layer process. WhatM                is intended is a smarter alert than is present on most systemsRI                however this part has never been completed. The raw alert,sK                as stored and displayed, is intended to be further processedcJ                to allow a much wider context to be alerted. The concept ofL                'related' and 'recent' events is built in but not implementedH                in this version. The definition of recent and related areI                in the architecture section of this manual. Currently, the_G                usefulness of this process is it's ability to review all K                events recorded. As a monitor, it is limited (generous!) and_H                some work is required to remove restrictions on parameter                specification.t              N                                                        Programming Notes  4-13 A  s            G             4.4 Summary
            4.4 Summary
            4.4 Summaryd  H                EMU was originally conceived as a tool to assist me in myI                day to day job as a network manager and to that end it hasSJ                been very successful. As it developed (and became an end inH                itself) it became a commercial endeavour and managed someK                limited success here also. Along the way it also served as a J                teaching tool and hobby. In this it was successful. FinallyH                it became an imprisonment, an activity that demanded moreG                time and effort than anyone could supply. This aspect ofiH                it was entirely successful. Now it is a gift - Anyone whoL                uses, develops it or even has an interest is welcome to do asL                they see fit. I would be pleased to hear from you and if timeL                permits, (I have a life now!) assist in your endeavour. I canI                be contacted at system@ccci4.demon.co.uk. The code is wellcJ                documented and as readable as Macro code can be. It is alsoM                modular enough to take functions out and reuse them elsewhere.sJ                EMU was very much a reaction to the poor quality of networkL                management packages available - a situation that IMHO has notL                changed. Without prejudice to any group, I would suggest thatL                not enough network people can program or even understand whatK                can be done with a good system and programmers in general do K                not understand what network managers need. That is the gap IeK                am attempting to bridge however, it is a bridge too far. ThecM                multiple skills required and the sheer size is beyond a single (                person working part time.                                                #             4-14  Programming Notes                                      _________________________________________________________________
               Index
               Index
               Index     ?                _______________________________
               A                                                   _______________________________
                                                 I
               Alert Format, 3-11w  b                                                  Identity, 2-3
               Alert Formatting and  2                   Transmission, 3-15             Lv                                                  _______________________________
               Alert generation, 3-13h                                                  Listener, 2-1, 3-1
               Alert log files, 3-16  2                Alert Parameters and              Nt                                                  _______________________________
                  translation, 3-15i                                                  Network Views, 2-2
               Alert processing, 3-14fd                                                  non-goals, 1-3
               Alert Subsystem, 3-112                Autogen, 1-2                      P  a                                                  _______________________________
               Baw                _______________________________
                                                 Physical Topology, 3-13n`                                                  Protocol Address, 2-3
               BOXID, 2-3s                                                  Protocol type formats, 3-3
               BOXID Modification, 3-10 O                                                  PSR, 2-1, 3-4
               C z                _______________________________
                                                 PSR Database Overview, 2-5p                                                  PSR - General processing, 3-7
               CNTRPOLL.DAT, 3-17d                                                  PSR interface, 2-2
               CNTRPRC.DAT, 3-17p                                                  PSR Record Header, 2-5, 3-4
               CNTRPRC Record, 3-18a                                                  PSR Records, 3-4
               Core System, 2-1sx                                                  PSR Record Structure, 2-5
               Counter Processing files, 3-17  2                Counter Processing System, 2-6    R}                                                  _______________________________
               Customer Network - Effect on,eS                                                  Relater, 3-8
                  1-2dW                                                  Relater Database, 3-8
               DBr                _______________________________
                                                 Relater Frame, 3-9  2                Database Access, 2-6              Sq                                                  _______________________________
               Data typing, 3-15 T                                                  Segmentation, 3-13
               Ei                _______________________________
                                                 SNMP, 1-3Ti                                                  System Control bits, 3-6
               EMU network, 2-4cl                                                  System extensions, 1-2
               EMU_CNTPOLL.EXE, 3-17f                                                  System Functions, 1-1
               EMU_CNTRPC, 3-17B                                                  System goals, 1-1a                _______________________________
               F                                 T                                                     _______________________________
                         1-2
                         1-2
                         1-2
               Features,k                                                  TCPIP Services, 1-3
               Future incarnation, 1-1                                                     _______________________________
                                                 Ue  9                                                  UCX, 1-3                                                                             _______
                                                                         Index-1o