[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 RFC 1856

Internet-Draft                                                H. Clark
Opstat Working Group                                            OARnet
draft-ietf-opstat-client-server-02.txt                     30 Jan 1995
Expires:  30 Jul 1995


        The Opstat Client-Server Model for Statistics Retrieval



Status of this Memo

   This document is an Internet-Draft.  Internet-Drafts are working
   documents of the Internet Engineering Task Force (IETF), its areas,
   and its working groups.  Note that other groups may also distribute
   working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet- Drafts as reference
   material or to cite them other than as ``work in progress.''

   To learn the current status of any Internet-Draft, please check the
   ``1id-abstracts.txt'' listing contained in the Internet- Drafts
   Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net
   (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific
   Rim).

Abstract

   Network administrators gather data related to the performance,
   utilization, usability and growth of their data network.  The amount
   of raw data gathered is usually quite large, typically ranging
   somewhere between several megabytes to several gigabytes of data each
   month.  Few (if any) tools exist today for the sharing of that raw
   data among network operators or between a network service provider
   (NSP) and its customers.  This document defines a model and protocol
   for a set of tools which could be used by NSPs and Network Operation
   Centers (NOCs) to share data among themselves and with customers.

1.0  Introduction

   Network administrators gather data related to the performance,
   utilization, usability and growth of their data network.  The primary
   goal of gathering the data is to facilitate near-term problem
   isolation and longer-term network planning within the organization.
   The amount of raw data gathered is usually quite large, typically
   ranging somewhere between several megabytes to several gigabytes of



Clark                                                           [Page 1]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   data each month.  From this raw data, the network administrator
   produces various types of reports.  Few (if any) tools exist today
   for the sharing of that raw data among network operators or between a
   network service provider (NSP) and its customers.  This document
   defines a model and protocol for a set of tools which could be used
   by NSPs and Network Operation Centers (NOCs) to share data among
   themselves and with customers.

1.1 The OPSTAT Model

   Under the Operational Statistics model [1], there exists a common
   model under which tools exist for the collection, storage, retrieval
   and presentation of network management data.

   This document defines a protocol which would allow a client on a
   remote machine to retrieve data from a central server, which itself
   retrieves from the common statistics database.  The client then
   presents the data to the user in the form requested (maybe to a X-
   window, or to paper).

   The basic model used for the retrieval methods defined in this
   document is a client-server model.  This architecture envisions that
   each NOC (or NSP) should install a server which provides locally
   collected information for clients.  Using a query language the client
   should be able to define the network object of interest, the
   interface, the metrics and the time period to be examined.  Using a
   reliable transport-layer protocol (e.g. TCP), the server will
   transmit the requested data.  Once this data is received by the
   client it could be processed and presented by a variety of tools
   including displaying the data in a X window, sending postscript to a
   printer, or displaying the raw data on the user's terminal.

   The remainder of this document describes how the client and server
   interact, describes the protocol used between the client and server,
   and discusses a variety of other issues surrounding the sharing of
   data.

   2.0  Client-Server Description

   2.1  The Client

   The basic function of the client is to retrieve data from the server.
   It will accept requests from the user, translate those requests into
   the common retrieval protocol and transmit them to the server, wait
   for the server's reply, and send that reply to the user.

   Note that this document does not define how the data should be
   presented to the user.  There are many methods of doing this



Clark                                                           [Page 2]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   including:


   - use a X based tool that displays graphs (a line, a histogram, etc.)
   - generate PostScript output to be sent to a printer
   - dump the raw data to the user's terminal


   Future documents based on the Operational Statistics model may define
   standard  graphs  and variables to be displayed, but this is work yet
   to be done (as of this writing).

   2.2  The Server

   The basic function of the server is  to  accept  connections  from  a
   client,  accept some series of commands from the client and perform a
   series of actions based on the commands, and then close  the  connec-
   tion to the client.

   The server must have some type of configuration file, which  is  left
   undefined  in this document.  The configuration file would list users
   that could access the server along with  the  authentication  strings
   they would use.  The configuration file should also allow the specif-
   ication of the data items that the user should be permitted to access
   (and,  by  implication, not allowed to access).  Server security con-
   cerns are specifically addressed in Section 4.

   3.0  Protocol Commands

   This section defines the commands which may  be  transmitted  to  the
   server  and  the  server  responses to those commands.  The available
   commands are:


   LOGIN  - accept new connection
   EXIT   - disconnect
   LIST   - show available variables
   SELECT - mark data for retrieval
   STATUS - show the state of the server
   GET    - download data to the client


   In addition, a state  machine  describing  specific  actions  by  the
   server  is  included.  Server security concerns are addressed in Sec-
   tion 4.

   Note that in some of the descriptions below, the term  <ASCII-STRING>
   is  used.   This refers to printable ASCII characters, defined as all



Clark                                                           [Page 3]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   letters, numbers, and special characters such as  $,  %,  or  *.   It
   specifically  excludes  all  special  control characters in the lower
   parts of the character set (i.e. 0x00 - 0x1F).

   3.1  Command Return Codes

   The only responses a server may return to a client are:


   RETURN-CODE  ::=  <OK-TYPE> | <ERROR-TYPE>
   OK-TYPE      ::=  OK | OK <ASCII-STRING>
   ERROR-TYPE   ::=  ERROR | ERROR <ASCII-STRING>


   The server should strive to  return  text  along  with  the  "OK"  or
   "ERROR"  when appropriate to help guide the user in using the server.
   If a command is sent where the server should return data, the  server
   must  also  return  an OK (or ERROR, if appropriate) when if finishes
   sending the data.

   3.2  The LOGIN Command

   The LOGIN command authenticates a user to the server.  The format  of
   the LOGIN command is:


   LOGIN-CMD    ::=  LOGIN <username> <auth-string>
   USERNAME     ::=  " <ASCII-STRING> "
   AUTH-STRING  ::=  " <ASCII-STRING> "


   A sample LOGIN command might look like:

   LOGIN "user1" "cows"

   The <auth-string> entry is just a simple ASCII string which helps  to
   authenticate  a  user  to  the server.  This could be, for example, a
   clear-text password or an encrypted/one-time password (preferred).

   3.3  The EXIT Command

   The EXIT command disconnects a current user  from  the  server.   The
   format of the EXIT command is:

   EXIT

   Note that upon reception of an EXIT command, the server  MUST  always
   close  the  connection,  even if it would be appropriate to return an



Clark                                                           [Page 4]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   ERROR return code.

   3.4  The SELECT Command

   The SELECT command is the function used to  tag  data  for  retrieval
   from the server.  The SELECT command has the format:


   SELECT-COM   ::=  SELECT <NETWORK> <ROUTER> <INTERFACE> <VARNAME>
                     <GRANULARITY> <START-DATE> <END-DATE> <AGG> <SELECT-COND>
   NETWORK      ::=  <ASCII-STRING>
   ROUTER       ::=  <ASCII-STRING>
   INTERFACE    ::=  <ASCII-STRING>
   VARNAME      ::=  <ASCII-STRING>
   GRANULARITY  ::=  <ASCII-STRING>
   START-DATE   ::=  <DATE-TYPE>
   END-DATE     ::=  <DATE-TYPE>
   DATE-TYPE    ::=  YYYY-MM-YY
   AGG          ::=  <AGG-TYPE> | NULL
   AGG-TYPE     ::=  TOTAL | PEAK
   SELECT-COND  ::=  <SELECT-STMT> | NULL
   SELECT-STMT  ::=  WITH DATA <COND-TYPE> <ASCII-STRING>
   COND-TYPE    ::=  LE | GE | EQ | NE | LT | GT


   If any conditional within the SELECT does  not  match  existing  data
   within the database (such as VARNAME, the S-DATE or E-DATE, or GRANU-
   LARITY), the server must return an ERROR (and hopefully a  meaningful
   error  message).  The  granularity  should  always  be  specified  in
   seconds.  A sample query might be:

   SELECT net rtr1 eth-0 ifInOctets 900 1992-01-01 1992-02-01

   which would select all data from network "net" router  "rtr1"  inter-
   face "eth-0" from Jan 1, 1992 to Feb 1, 1992.

   Note that if the client requests some type of aggregation to be  per-
   formed  upon  the  data,  then the aggregation field specifies how to
   perform the aggregration (i.e. total or  peak)  and  the  granularity
   specifies  to  what  interval (in seconds) to agggregate the data to.
   If the server cannot perform  the  requested  action,  then  it  must
   return an error.

   Upon completion of the data lookup, the SELECT  must  return  the  an
   indication  of  whether  the lookup was successful and (if the search
   was successful) the tag associated with that data.  If the lookup was
   successful,  then  information  in  the  "OK"  return  code should be
   encoded as:



Clark                                                           [Page 5]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   TAG <ASCII-STRING>

   In this case, the use of the word TAG is used as  a  handle  for  the
   selected  data on the server.  Note that this single handle may refer
   to one or more specific SNMP variables (refer to [1]  for  a  further
   explanation).

   For example, if the tag "foobar" were assigned to the select  example
   above, then the OK would be as:

   OK TAG foobar

   It is recommended that the return tag string be less  than  10  bytes
   long  (this  gives  many  tag combinations), although the server (and
   client) should be  capable  of  handling  arbitrary  length  strings.
   There  is no requirement that the TAG have any particular meaning and
   may be composed of arbitrary strings.

   The server must keep any internal information it needs during a  ses-
   sion  so  that  all SELECT tags can be processed by GET or other com-
   mands.  If a server doesn't have the resources to process  the  given
   SELECT, it must return an error message.

   It is the responsibility of the client to store information about the
   data  that  a  particular  tag corresponds to, i.e. if the client had
   requested all ifInOctet data for October 1993 to be placed in  a  tag
   called  "1234", then the client must store that information someplace
   as the variables will not be listed for each tag.

   3.5  The STATUS Command

   The STATUS command shows the general state of the server plus listing
   all  data  sets  which  have been tagged via the SELECT command.  The
   STATUS command has no arguments.  The output from  a  STATUS  command
   is:


   STATUS-RETURN    ::=  START-STATUS <STATUS-DATA> END-STATUS
   STATUS-DATA      ::=  <SERVER-STATUS> <SERVER-TAG-LIST>
   SERVER-STATUS    ::=  "STATUS= " <STATUS-FIELDS>
   STATUS-FIELDS    ::=  "OK" | "NOT-OK"
   SERVER-TAG-LIST  ::=  <SERVER-TAG> | NULL
   SERVER-TAG       ::=  "TAG" <TAG-ID> "SIZE" <NUMBER>


   For example, a sample output might look like:





Clark                                                           [Page 6]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   START-STATUS
   STATUS= OK
   TAG 1234 SIZE 123456
   TAG ABCD SIZE 654321
   END-STATUS


   3.6  The GET Command


   The GET command actually retrieves the data  chosen  via  a  previous
   SELECT command.  The GET command has the format:


   GET-CMD  ::=  GET <TAG>
   TAG      ::=  <ASCII-STRING>


   If the TAG matches a previously returned TAG from a SELECT statement,
   then  the  previously tagged data is returned.  If the TAG is invalid
   (i.e. it hasn't been previously assigned by  the  server),  then  the
   server  must  return  an  error.  If the server, while retrieving the
   data, cannot retrieve some portion of the data (i.e. some of the data
   previously  found  disappeared between the time of the SELECT and the
   time of the GET), then the server must return an error.

   The data to be returned may be in any of several formats.  Currently,
   the  only defined format is RFC1404.  To handle these different types
   of data, the following constructs are used:

   RETURN-DATA-TYPE   ::=   START-DATA  <RETURN-TYPE>  <DATA>   END-DATA
   RETURN-TYPE       ::=  1404

   An example would be:

   START-DATA 1404 1404 data stream here...  END-DATA

   After the end of data, an OK (or ERROR) must still be  returned.   If
   an  ERROR is returned, the client must discard all data received from
   the server.

   3.7  The LIST Command

   The LIST command allows the client to query the server  about  avail-
   able data residing on the server.  The LIST command has the format:


   LIST-CMD  ::=  LIST <net> <rtr> <intf> <var> <gran> <sdate> <edate>



Clark                                                           [Page 7]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   <net>     ::=  <ASCII-STRING> | *
   <rtr>     ::=  <ASCII-STRING> | *
   <intf>    ::=  <ASCII-STRING> | *
   <var>     ::=  <ASCII-STRING> | *
   <gran>    ::=  <ASCII-STRING> | *
   <sdate>   ::=  <DATE-TYPE>    | *
   <edate>   ::=  <DATE-TYPE>    | *


   For example, to get a list of networks that the server has data  for,
   you would use the command

   LIST * * * * * * *

   The command

   LIST netx rtry * * * * *

   will list all interfaces for rtry.  The command

   LIST netx rtry * ifInOctets * 1993-02-01 *

   will get the list of interfaces on router "rtry"  in  network  "netx"
   which  have values for the variable "ifInOctets" after the start date
   of Februrary 1, 1993.

   To process wildcards in a LIST command, follow these rules:


   1)  Only the leftmost wildcard will be serviced for a given
       LIST command
   2)  If all fields to the right of the leftmost wildcard are
       wildcards, then all values for the wildcard being processed
       will be returned.
   3)  If specific values are given for fields to the right of the
       wildcard being serviced, then the specific values must match
       a known value


   The output from the LIST command is formatted as follows:


   LIST-RETURN  ::=  START-LIST <LIST-ENTRY> END-LIST
   LIST-ENTRY   ::=  <net> <rtr> <intf> <var> <gran> <sdate> <edate>
   <net>        ::=  <ASCII-STRING>
   <rtr>        ::=  <ASCII-STRING> | <NULL>
   <intf>       ::=  <ASCII-STRING> | <NULL>
   <var>        ::=  <ASCII-STRING> | <NULL>



Clark                                                           [Page 8]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   <gran>       ::=  <ASCII-STRING> | <NULL>
   <sdate>      ::=  <DATE-TYPE>    | <NULL>
   <edate>      ::=  <DATE-TYPE>    | <NULL>


   Note that only the fields with values in them will be returned by the
   server.  For example, the query to find the interfaces on rtry:

   LIST netx rtry * * * * *

   might return


   START-LIST
   netx rtry intf1
   netx rtry intf2
   netx rtry intf3
   END-LIST


   The query to find interfaces having ifInOctets data with a 15  minute
   granularity:

   LIST netx rtry * ifInOctets 15min * *

   might return


   START-LIST
   netx rtry intf1
   netx rtry intf2
   netx rtry intf3
   END-LIST


   If, while processing a LIST command, the server encounters an  error,
   then the server must return an "ERROR" message.

   3.8  The Server State Machine

   The state machine  pictured  below  describes  how  a  server  should
   interact with a client:









Clark                                                           [Page 9]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


                        +------+
              +-------->| WAIT |<-----+
              |         +------+      |
              |  New       |          |
              |  Connect   |          |  LOGIN Failure
    EXIT      |           \ /         |
    Received  |         +-------+     |
              |         | LOGIN |-----+
              |         +-------+
              |             |
              |             |  LOGIN Successful
              |            \ /
              |        +---------+
              +--------| PROCESS |<----+
                       +---------+     |
                            |          |  Process Commands
                            |          |
                            +----------+


   The server normally stays in WAIT (after starting and initialization)
   until  a  new  connection is made from a client.  The first command a
   client must issue is a  LOGIN  command,  otherwise  the  server  must
   immediately close the connection.  If a client issues a LOGIN command
   using a invalid username or password, then the  server  must  immedi-
   ately close the connection.

   Once a successful LOGIN is received, the server  enters  the  PROCESS
   state where it processes some number of LIST, GET, STATUS, and SELECT
   commands. Any other command received while  in  this  state  must  be
   ignored,  except  for  the  EXIT  command.   Once  an EXIT command is
   received, the server exits immediately (after  perfoming  any  needed
   internal bookkeeping) and returns to the WAIT state.

   4.0  Security Issues

   There are legal, ethical and political concerns of data sharing.  For
   this  reason  there is a need to insure integrity and confidentiality
   of any shared data.  Although not specified in this standard, mechan-
   isms  to  control  a  user's  access  to specific data about specific
   objects may need to be  included  in  server  implementations.   This
   could  potentially be done in several ways, including a configuration
   file that listed the objects a user was allowed to access or limiting
   file access by using file permissions within a given file system.  At
   a minimum, the server should not allow default access to all data  on
   the server.

   Additionally, the server should strictly  follow  the  state  diagram



Clark                                                          [Page 10]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   shown  in  section  3.8.   The server should be tested with arbitrary
   strings in the command fields to ensure that no  unexpected  security
   problems  will  be  caused by the server.  The server should specifi-
   cally discard illegal ASCII characters as discussed in  section  3.0.
   If  the  server  executes other programs, then the server must verify
   that no unexpected side-effects will occur as the result of the invo-
   cation or the arguments given to that program.

   5.0  Summary

   This document defines a protocol which could be  used  in  a  client-
   server  relationship  to  retrieve  statistics from a remote database
   server.

   Much work remains to be done in the area  of  Operational  Statistics
   including questions such as:


   -  what "standard" graphs or "variables" should always be made available
      to the user?
   -  what additions to the standard MIB would make the network
      manager's job easier?


   6.0  References

   [1]  RFC1404 A Model for Common Operational Statistics, B. Stockman

   Appendix A:  Sample Client-Server Sessions

   Session 1: Failed LOGIN


   LOGIN henryc foobar
   ERROR LOGIN Incorrect


   Session 2: Check available variables on router rtr1 interface eth0


   LOGIN henry foobar
   OK
   LIST OARnet rtr1 eth0 * * * *
   START-LIST
   OARnet rtr1 eth0 ifInOctets
   OARnet rtr1 eth0 ifOutOctets
   OARnet rtr1 eth0 ifInErrors
   OARnet rtr1 eth0 ifOutErrors



Clark                                                          [Page 11]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   END-LIST
   OK
   EXIT
   OK


   Session 3: Retrieve a bit of data from the server


   LOGIN henryc foobar
   OK
   SELECT OARnet rtr1 eth0 InBytes 15min 1993-02-01 1993-03-01
   OK TAG blah
   STATUS
   START-STATUS
   STATUS= OK
   TAG blah SIZE 654321
   END-STATUS
   OK
   GET blah
   START-DATA 1404
   START-DATA
   BEGIN_LABEL,,
   [InBytes],19930201000000,19930301000000,
   END_LABEL
   BEGIN_DEVICE,
   OARnet,rtr1,eth0,1536000,IP,1.2.3.4,+0500,
   [InBytes,peak,[ifInOctets,900,900]],
   END_DEVICE
   BEGIN_DATA
   19920730000000,InBytes,300,1,
   19920730000300,InBytes,300,2,
   19920730000600,InBytes,300,3,
   END-DATA
   END-DATA
   OK
   EXIT
   OK





Author's Address

   Henry Clark
   OARnet
   2455 North Star Rd



Clark                                                          [Page 12]


Internet-Draft         Opstat Client-Server Model            30 Jan 1995


   Columbus, OH  43221

   Phone:  (614) 728-8100 x 212

   EMail:  henryc@oar.net














































Clark                                                          [Page 13]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/