home *** CD-ROM | disk | FTP | other *** search
/ Unix System Administration Handbook 1997 October / usah_oct97.iso / rfc / 1800s / rfc1856.txt < prev    next >
Text File  |  1995-10-18  |  30KB  |  956 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                           H. Clark
  8. Request For Comments: 1856                                    BBN Planet
  9. Category: Informational                                   September 1995
  10.  
  11.  
  12.         The Opstat Client-Server Model for Statistics Retrieval
  13.  
  14. Status of this Memo
  15.  
  16.    This memo provides information for the Internet community.  This memo
  17.    does not specify an Internet standard of any kind.  Distribution of
  18.    this memo is unlimited.
  19.  
  20. Abstract
  21.  
  22.    Network administrators gather data related to the performance,
  23.    utilization, usability and growth of their data network.  The amount
  24.    of raw data gathered is usually quite large, typically ranging
  25.    somewhere between several megabytes to several gigabytes of data each
  26.    month.  Few (if any) tools exist today for the sharing of that raw
  27.    data among network operators or between a network service provider
  28.    (NSP) and its customers.  This document defines a model and protocol
  29.    for a set of tools which could be used by NSPs and Network Operation
  30.    Centers (NOCs) to share data among themselves and with customers.
  31.  
  32. 1.0  Introduction
  33.  
  34.    Network administrators gather data related to the performance,
  35.    utilization, usability and growth of their data network.  The primary
  36.    goal of gathering the data is to facilitate near-term problem
  37.    isolation and longer-term network planning within the organization.
  38.    The amount of raw data gathered is usually quite large, typically
  39.    ranging somewhere between several megabytes to several gigabytes of
  40.    data each month.  From this raw data, the network administrator
  41.    produces various types of reports.  Few (if any) tools exist today
  42.    for the sharing of that raw data among network operators or between a
  43.    network service provider (NSP) and its customers.  This document
  44.    defines a model and protocol for a set of tools which could be used
  45.    by NSPs and Network Operation Centers (NOCs) to share data among
  46.    themselves and with customers.
  47.  
  48. 1.1 The OPSTAT Model
  49.  
  50.    Under the Operational Statistics model [1], there exists a common
  51.    model under which tools exist for the collection, storage, retrieval
  52.    and presentation of network management data.
  53.  
  54.  
  55.  
  56.  
  57.  
  58. Clark                        Informational                      [Page 1]
  59.  
  60. RFC 1856               Opstat Client-Server Model           October 1995
  61.  
  62.  
  63.    This document defines a protocol which would allow a client on a
  64.    remote machine to retrieve data from a central server, which itself
  65.    retrieves from the common statistics database.  The client then
  66.    presents the data to the user in the form requested (maybe to a X-
  67.    window, or to paper).
  68.  
  69.    The basic model used for the retrieval methods defined in this
  70.    document is a client-server model.  This architecture envisions that
  71.    each NOC (or NSP) should install a server which provides locally
  72.    collected information for clients.  Using a query language the client
  73.    should be able to define the network object of interest, the
  74.    interface, the metrics and the time period to be examined.  Using a
  75.    reliable transport-layer protocol (e.g., TCP), the server will
  76.    transmit the requested data.  Once this data is received by the
  77.    client it could be processed and presented by a variety of tools
  78.    including displaying the data in a X window, sending postscript to a
  79.    printer, or displaying the raw data on the user's terminal.
  80.  
  81.    The remainder of this document describes how the client and server
  82.    interact, describes the protocol used between the client and server,
  83.    and discusses a variety of other issues surrounding the sharing of
  84.    data.
  85.  
  86. 2.0  Client-Server Description
  87.  
  88. 2.1  The Client
  89.  
  90.    The basic function of the client is to retrieve data from the server.
  91.    It will accept requests from the user, translate those requests into
  92.    the common retrieval protocol and transmit them to the server, wait
  93.    for the server's reply, and send that reply to the user.
  94.  
  95.    Note that this document does not define how the data should be
  96.    presented to the user.  There are many methods of doing this
  97.    including:
  98.  
  99.     - use a X based tool that displays graphs (line, histogram, etc.)
  100.     - generate PostScript output to be sent to a printer
  101.     - dump the raw data to the user's terminal
  102.  
  103.    Future documents based on the Operational Statistics model may define
  104.    standard  graphs  and variables to be displayed, but this is work yet
  105.    to be done (as of this writing).
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114. Clark                        Informational                      [Page 2]
  115.  
  116. RFC 1856               Opstat Client-Server Model           October 1995
  117.  
  118.  
  119. 2.2  The Server
  120.  
  121.    The basic function of the server is to accept connections from a
  122.    client, accept some series of commands from the client and perform a
  123.    series of actions based on the commands, and then close the
  124.    connection to the client.
  125.  
  126.    The server must have some type of configuration file, which is left
  127.    undefined in this document.  The configuration file would list users
  128.    that could access the server along with the authentication they would
  129.    use.  The configuration file should also allow the specification of
  130.    the data items that the user should be permitted to access (and, by
  131.    implication, not allowed to access).  Server security concerns are
  132.    specifically addressed in Section 4.
  133.  
  134. 3.0  Protocol Commands
  135.  
  136.    This section defines the commands which may be transmitted to the
  137.    server and the server responses to those commands.  The available
  138.    commands are:
  139.  
  140.     LOGIN  - accept new connection
  141.     EXIT   - disconnect
  142.     LIST   - show available variables
  143.     SELECT - mark data for retrieval
  144.     STATUS - show the state of the server
  145.     GET    - download data to the client
  146.  
  147.    In addition, a state machine describing specific actions by the
  148.    server is included.  Server security concerns are addressed in
  149.    Section 4.
  150.  
  151.    Note that in some of the descriptions below, the term <ASCII-STRING>
  152.    is used.  This refers to printable ASCII characters, defined as all
  153.    letters, numbers, and special characters such as $, %, or *.  It
  154.    specifically excludes all special control characters in the lower
  155.    parts of the character set (i.e., 0x00 - 0x1F), and any such
  156.    characters that are received by the server or client should be
  157.    ignored.
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170. Clark                        Informational                      [Page 3]
  171.  
  172. RFC 1856               Opstat Client-Server Model           October 1995
  173.  
  174.  
  175. 3.1  Command Return Codes
  176.  
  177.    The responses a server will return to a client are of the form:
  178.  
  179.     RETURN-INFO  ::=  <RETURN-CODE> " <ASCII-STRING> " | <RETURN-CODE>
  180.     RETURN-CODE  ::=  <MAIN-CODE><COMMAND><SUB-CODE>
  181.     MAIN-CODE    ::=  1..9
  182.     COMMAND      ::=  1..9
  183.     SUB-CODE     ::=  0..9
  184.  
  185.    For each command sent to the server, the server returns a series of
  186.    three digit numeric codes which specifies the result of the
  187.    operation, plus optional ASCII text for humans.  The value of MAIN-
  188.    CODE specifies what happened, as in:
  189.  
  190.     1   Error
  191.     9   Success / Informational
  192.  
  193.     The commands are encoded as:
  194.  
  195.     1   LOGIN
  196.     2   SELECT
  197.     3   STATUS
  198.     4   LIST
  199.     5   GET
  200.     9   EXIT
  201.  
  202.    The following specific error codes must be supported by  all  servers
  203.    and clients:
  204.  
  205.     110  Login Invalid
  206.     113  Scanning Error during LOGIN
  207.     120  SELECT Failed
  208.     130  STATUS Failed
  209.     140  LIST Failed
  210.     141  Bad LIST encoding
  211.     150  GET Failed
  212.     151  GET doesn't support that type of encoding
  213.     910  Login Accepted
  214.     920  SELECT successful
  215.     931  STATUS Output Starting
  216.     932  STATUS Output Done
  217.     941  LIST lookup successful, here comes the data!
  218.     942  LIST dump done!
  219.     951  GET lookup successful, here comes the data!
  220.     952  GET dump done!
  221.     990  Server closing connection after EXIT received
  222.  
  223.  
  224.  
  225.  
  226. Clark                        Informational                      [Page 4]
  227.  
  228. RFC 1856               Opstat Client-Server Model           October 1995
  229.  
  230.  
  231.    Other codes may be used, but may not be supported by all clients or
  232.    servers.
  233.  
  234. 3.2  The LOGIN Command
  235.  
  236.    The LOGIN command authenticates a user to the server.  The format  of
  237.    the LOGIN command is:
  238.  
  239.     LOGIN-CMD    ::=  LOGIN <username> <auth-type>
  240.     USERNAME     ::=  " <ASCII-STRING> "
  241.     AUTH-TYPE    ::=  "none" | "password" | " <ASCII-STRING> "
  242.     CHAL-CMD     ::=  CHAL " <ASCII-STRING> "
  243.     AUTH-CMD     ::=  AUTH " <ASCII-STRING> "
  244.  
  245.    The authentication types supported by each server will vary, but must
  246.    include "none" and "password".  Note that a server may or may not
  247.    choose to allow logins via either of these methods, but it must
  248.    recognize the two special authentication types.
  249.  
  250.    In processing a LOGIN command sequence, the server first checks the
  251.    username and authentication type requested.  If the username is
  252.    invalid (e.g., there's no such user known to the server) or the
  253.    authentication type requested is not supported by the server, then
  254.    the server must return a 110 error and close the connection after
  255.    faking the challenge/authentication process (see examples below).
  256.  
  257.    After passing the username and authentication type checking, a
  258.    challenge must be sent.  Note that the challenge will be specific to
  259.    the type of authentication requested, and the ASCII string may be an
  260.    empty string if no specific challenge is needed (such as in the
  261.    password-only case). The next command the client returns must be an
  262.    AUTH response, and if not, the server must close the connection.
  263.    After processing the authentication information, the server must
  264.    return a 910 code if the authentication process is successful, or a
  265.    110 error messsage if unsuccessful. Additionally, if the
  266.    authentication fails, the server must immediately close the
  267.    connection.
  268.  
  269.    If, at any point, during the LOGIN sequence, a syntax error occurs (a
  270.    client doesn't send the correct number of arguments in the LOGIN
  271.    command, for example), the server must return a 113 error and close
  272.    the connection.
  273.  
  274.    If the special AUTH-TYPE of "none" is used, and the server allows the
  275.    specified username (such as anonymous) to login without
  276.    authentication, then the server should still send a "CHAL" response
  277.    to get additional information about the person logging in.  The
  278.    server may then choose to allow or disallow the login based on the
  279.  
  280.  
  281.  
  282. Clark                        Informational                      [Page 5]
  283.  
  284. RFC 1856               Opstat Client-Server Model           October 1995
  285.  
  286.  
  287.    information returned in the AUTH response.
  288.  
  289.    An example of an invalid authentication type requested:
  290.  
  291.     >LOGIN "cow" "s/key"
  292.     <CHAL "lo35098 98"
  293.     >AUTH "COW DOG BARK CAT MOO MEOW"
  294.     <110 "Login invalid"
  295.  
  296.     The server didn't support S/Key, but it made it appear to the user as
  297.     if it did.  An example of an authentication failure:
  298.  
  299.     >LOGIN "dog" "securid"
  300.     <CHAL "enter passcode"
  301.     >AUTH "103945"
  302.     <110 "Login invalid"
  303.  
  304.    The user gave the wrong number for SecurID authentication.  An
  305.    example of a successful login:
  306.  
  307.     >LOGIN "cat" "password"
  308.     <CHAL "send the dumb clear-text password"
  309.     >AUTH "foobar"
  310.     <910 "Login accepted"
  311.  
  312.     or
  313.  
  314.     >LOGIN "anonymous" "none"
  315.     <CHAL "tell me who you are anyway"
  316.     >AUTH "bessie@barn.farm.com"
  317.     <910 "Login accepted"
  318.  
  319.     An example of a invalid username:
  320.  
  321.     >LOGIN "mule" "skey"
  322.     <CHAL "78 lo39065"
  323.     >AUTH "COW DOG FRED LOG COLD WAR"
  324.     <110 "Login invalid"
  325.  
  326.    The server should have some type of logging mechanism to record  both
  327.    successful  and unsuccessful login attempts for a system adminstrator
  328.    to peruse.
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338. Clark                        Informational                      [Page 6]
  339.  
  340. RFC 1856               Opstat Client-Server Model           October 1995
  341.  
  342.  
  343. 3.3  The EXIT Command
  344.  
  345.    The EXIT command disconnects a current user from the server.  The
  346.    format of the EXIT command is:
  347.  
  348.    EXIT
  349.  
  350.    Note that upon reception of an EXIT command, the server must always
  351.    close the connection, even if it would be appropriate to return an
  352.    ERROR return code.
  353.  
  354.     A sample EXIT command:
  355.  
  356.     >EXIT
  357.     <990 "OK, Bye now"
  358.  
  359. 3.4  The SELECT Command
  360.  
  361.    The SELECT command is the function used to tag data for retrieval
  362.    from the server.  The SELECT command has the format:
  363.  
  364.     SELECT-COM   ::=  SELECT <NETWORK> <DEVICE> <INTERFACE> <VARNAME>
  365.                       <GRANULARITY> <START-DATE> <START-TIME> <END-DATE>
  366.                       <END-TIME> <AGG> <SELECT-COND>
  367.  
  368.     NETWORK      ::=  <ASCII-STRING>
  369.  
  370.     DEVICE       ::=  <ASCII-STRING>
  371.     INTERFACE    ::=  <ASCII-STRING>
  372.     VARNAME      ::=  <ASCII-STRING>
  373.     GRANULARITY  ::=  <ASCII-STRING>
  374.     START-DATE   ::=  <DATE-TYPE>
  375.     END-DATE     ::=  <DATE-TYPE>
  376.     DATE-TYPE    ::=  YYYY-MM-YY
  377.     START-TIME   ::=  <TIME-TYPE>
  378.     END-TIME     ::=  <TIME-TYPE>
  379.     TIME-TYPE    ::=  HH:MM:SS
  380.     AGG          ::=  <AGG-TYPE> | NULL
  381.     AGG-TYPE     ::=  TOTAL | PEAK
  382.     SELECT-COND  ::=  <SELECT-STMT> | NULL
  383.     SELECT-STMT  ::=  WITH DATA <COND-TYPE> <ASCII-STRING>
  384.     COND-TYPE    ::=  LE | GE | EQ | NE | LT | GT
  385.  
  386.    If any conditional within the SELECT does not match existing data
  387.    within the database (such as VARNAME, the S-DATE or E-DATE, or
  388.    GRANULARITY), the server must return an ERROR (and hopefully a
  389.    meaningful error message).  The time values must be specified in GMT,
  390.    and hours are specified in the range from 0-23.  The granularity
  391.  
  392.  
  393.  
  394. Clark                        Informational                      [Page 7]
  395.  
  396. RFC 1856               Opstat Client-Server Model           October 1995
  397.  
  398.  
  399.    should always be specified in seconds. A sample query might be:
  400.  
  401.       SELECT net rtr1 eth-0 ifInOctets 900 1992-01-01 00:00:00 1992-02-
  402.       01 23:59:59
  403.  
  404.    which would select all data from network "net" device "rtr1"
  405.    interface "eth-0" from Jan 1, 1992 @ 00:00:00 to Feb 1, 1992 @
  406.    23:59:59.
  407.  
  408.    Note that if the client requests some type of aggregation to be
  409.    performed upon the data, then the aggregation field specifies how to
  410.    perform the aggregration (i.e., total or peak) and the granularity
  411.    specifies to what interval (in seconds) to agggregate the data to.
  412.    For more details about the granularity types, see [1].  If the server
  413.    cannot perform the requested action, then it must return a 120 error.
  414.    The server may, if it wishes, use other error codes in the range
  415.    121-129 to convey more information about the specific error that
  416.    occured.  In either case, its recommended that the server return
  417.    ASCII text describing the error.
  418.  
  419.    Upon completion of the data lookup, the SELECT must return the an
  420.    indication of whether the lookup was successful and (if the search
  421.    was successful) the tag associated with that data.  If the lookup was
  422.    successful, then information in the return code should be encoded as:
  423.  
  424.     920 " TAG <ASCII-STRING> "
  425.  
  426.    In this case, the use of the word TAG is used as a handle for the
  427.    selected data on the server.  Note that this single handle may refer
  428.    to one or more specific SNMP variables (refer to [1] for a further
  429.    explanation).
  430.  
  431.    For example, if the tag "foobar" were assigned to the select example
  432.    above, then the OK would be as:
  433.  
  434.     920 "TAG foobar"
  435.  
  436.    It is recommended that the return tag string be less than 10 bytes
  437.    long (this gives many tag combinations), although the server (and
  438.    client) should be capable of handling arbitrary length strings.
  439.    There is no requirement that the TAG have any particular meaning and
  440.    may be composed of arbitrary strings.
  441.  
  442.    The server must keep any internal information it needs during a
  443.    session so that all SELECT tags can be processed by GET or other
  444.    commands.  If a server doesn't have the resources to process the
  445.    given SELECT, it must return an error message.
  446.  
  447.  
  448.  
  449.  
  450. Clark                        Informational                      [Page 8]
  451.  
  452. RFC 1856               Opstat Client-Server Model           October 1995
  453.  
  454.  
  455.    It is the responsibility of the client to store information about the
  456.    data that a particular tag corresponds to, i.e., if the server had
  457.    returned a tag "1234" for ifInOctet data for October 1993, then the
  458.    client must store that information someplace as the variables which
  459.    correspond to that tag cannot be retrieved from the server.
  460.  
  461. 3.5  The STATUS Command
  462.  
  463.    The STATUS command shows the general state of the server plus listing
  464.    all data sets which have been tagged via the SELECT command.  The
  465.    STATUS command has no arguments.  The output from a STATUS command
  466.    is:
  467.  
  468.     STATUS-DATA      ::=  <SERVER-STATUS> <SERVER-TAG-LIST>
  469.     SERVER-STATUS    ::=  "STATUS= " <STATUS-FIELDS>
  470.     STATUS-FIELDS    ::=  "OK" | "NOT-OK"
  471.     SERVER-TAG-LIST  ::=  <SERVER-TAG> | NULL
  472.     SERVER-TAG       ::=  "TAG" <TAG-ID> "SIZE" <NUMBER>
  473.  
  474.    The number returned in the SIZE field represents the number of octets
  475.    of data represented by the particular TAG.  The server must return a
  476.    931 message before the STATUS output starts, and a 932 message at the
  477.    end of the STATUS output.  If any type of failure occurs, then a 130
  478.    error messages must be sent.  If the server prefers, it may send a
  479.    message in the range of 131-139 if it wishes, but its recommended
  480.    that the server always return ASCII describing the enoutered error.
  481.    For example, a sample output might look like:
  482.  
  483.     >STATUS
  484.     <931 "STATUS Command Starting"
  485.     <STATUS= OK
  486.     <TAG 1234 SIZE 123456
  487.     <TAG ABCD SIZE 654321
  488.     <932 "STATUS Command successful"
  489.  
  490.     or
  491.  
  492.     >STATUS
  493.     <130 "Can't get STATUS right now, sorry."
  494.  
  495.     or
  496.  
  497.     >STATUS
  498.     <931 "STATUS Command Starting"
  499.     <STATUS= OK
  500.     <TAG 1234 SIZE 1
  501.     <131 "Oops, error reading TAG table, sorry."
  502.  
  503.  
  504.  
  505.  
  506. Clark                        Informational                      [Page 9]
  507.  
  508. RFC 1856               Opstat Client-Server Model           October 1995
  509.  
  510.  
  511.  3.6  The GET Command
  512.  
  513.    The GET command actually retrieves the data chosen via a previous
  514.    SELECT command.  The GET command has the format:
  515.  
  516.     GET-CMD  ::=  GET <TAG> <TYPE>
  517.     TAG      ::=  <ASCII-STRING>
  518.     TYPE     ::=  1404 | <ASCII-STRING>
  519.  
  520.    If the TAG matches a previously returned TAG from a SELECT statement,
  521.    then the previously tagged data is returned.  If the TAG is invalid
  522.    (i.e., it hasn't been previously assigned by the server), then the
  523.    server must return an error.  The TYPE specifies the encoding of the
  524.    data stream.  All servers must support "1404" encoding.  Others forms
  525.    may be supported as desired.
  526.  
  527.    If the server, while retrieving the data, cannot retrieve some
  528.    portion of the data (i.e., some of the data previously found
  529.    disappeared between the time of the SELECT and the time of the GET),
  530.    then the server must return a 150 error.  If the client requests an
  531.    encoding type not supported by the server, then the server must
  532.    return a 151 error.
  533.  
  534.    The format of the returned data is as follows:
  535.  
  536.     RETURN-DATA-TYPE   ::=   START-DATA  <RETURN-TYPE>  <DATA>   END-DATA
  537.     RETURN-TYPE       ::=  1404 | <ASCII-STRING>
  538.  
  539.     An example would be:
  540.  
  541.     >GET ABC 1404
  542.     <951 "OK, here it comes!"
  543.     <START-DATA 1404
  544.  
  545.     1404 data stream here...
  546.  
  547.     <END-DATA
  548.     <952 "All done!"
  549.  
  550.     Error examples:
  551.  
  552.     >GET ABC STRONG-CRYPT
  553.     <151 "Sorry, that encoding not available here"
  554.  
  555.     or
  556.  
  557.     >GET ABC 1404
  558.     <951 "OK, here it comes!"
  559.  
  560.  
  561.  
  562. Clark                        Informational                     [Page 10]
  563.  
  564. RFC 1856               Opstat Client-Server Model           October 1995
  565.  
  566.  
  567.     <START-DATA 1404
  568.  
  569.     1404 data stream here...
  570.  
  571.     <END-DATA
  572.     <150 "Whoa, bad data..."
  573.  
  574.    If any type of error code is returned by the server, the client must
  575.    discard all data received from the server.
  576.  
  577. 3.7  The LIST Command
  578.  
  579.    The LIST command allows the client to query the server about
  580.    available data residing on the server.  The LIST command has the
  581.    format:
  582.  
  583.     LIST-CMD  ::=  LIST <net> <dev> <intf> <var> <gran> <sdate> <stime>
  584.                    <edate> <etime>
  585.     <net>     ::=  <ASCII-STRING> | *
  586.     <dev>     ::=  <ASCII-STRING> | *
  587.     <intf>    ::=  <ASCII-STRING> | *
  588.     <var>     ::=  <ASCII-STRING> | *
  589.     <gran>    ::=  <ASCII-STRING> | *
  590.     <sdate>   ::=  <DATE-TYPE>    | *
  591.     <edate>   ::=  <DATE-TYPE>    | *
  592.     <stime>   ::=  <TIME-TYPE>    | *
  593.     <etime>   ::=  <TIME-TYPE>    | *
  594.  
  595.    For example, to get a list of networks that the server has data for,
  596.    you would use the command:
  597.  
  598.     LIST * * * * * * * * *
  599.  
  600.     The command
  601.  
  602.     LIST netx rtry * * * * * * *
  603.  
  604.     will list all interfaces for rtry.  The command
  605.  
  606.     LIST netx rtry * ifInOctets * 1993-02-01 * * *
  607.  
  608.    will get the list of interfaces on device "rtry" in network "netx"
  609.    which have values for the variable "ifInOctets" after the start date
  610.    of Februrary 1, 1993.
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618. Clark                        Informational                     [Page 11]
  619.  
  620. RFC 1856               Opstat Client-Server Model           October 1995
  621.  
  622.  
  623.    To process wildcards in a LIST command, follow these rules:
  624.  
  625.     1)  Only the leftmost wildcard will be serviced for a given
  626.         LIST command
  627.     2)  If all fields to the right of the leftmost wildcard are
  628.         wildcards, then all values for the wildcard being processed
  629.         will be returned.
  630.     3)  If specific values are given for fields to the right of the
  631.         wildcard being serviced, then the specific values must match
  632.         a known value
  633.  
  634.    The output from the LIST command is formatted as follows:
  635.  
  636.     LIST-RETURN  ::=  START-LIST <LIST-ENTRY> END-LIST
  637.     LIST-ENTRY   ::=  <net> <device> <intf> <var> <gran> <sdate> <stime>
  638.                       <edate> <etime>
  639.     <net>        ::=  <ASCII-STRING>
  640.     <device>     ::=  <ASCII-STRING> | <NULL>
  641.     <intf>       ::=  <ASCII-STRING> | <NULL>
  642.     <var>        ::=  <ASCII-STRING> | <NULL>
  643.     <gran>       ::=  <ASCII-STRING> | <NULL>
  644.     <sdate>      ::=  <DATE-TYPE>    | <NULL>
  645.     <edate>      ::=  <DATE-TYPE>    | <NULL>
  646.     <stime>      ::=  <TIME-TYPE>    | <NULL>
  647.     <etime>      ::=  <TIME-TYPE>    | <NULL>
  648.  
  649.    Note that only the fields with values in them will be returned by the
  650.    server.  For example, the query to find the interfaces on rtry:
  651.  
  652.     >LIST netx rtry * * * * * * *
  653.     <941 "OK, here comes the list..."
  654.     <START-LIST
  655.     <netx rtry intf1
  656.     <netx rtry intf2
  657.     <netx rtry intf3
  658.     <END-LIST
  659.     <942 "all done"
  660.  
  661.    The query to find interfaces having ifInOctets data with a 15 minute
  662.    granularity:
  663.  
  664.     >LIST netx rtry * ifInOctets 15min * * * *
  665.     <941 "OK, here comes the list..."
  666.     <START-LIST
  667.     <netx rtry intf1
  668.     <netx rtry intf2
  669.     <netx rtry intf3
  670.     <END-LIST
  671.  
  672.  
  673.  
  674. Clark                        Informational                     [Page 12]
  675.  
  676. RFC 1856               Opstat Client-Server Model           October 1995
  677.  
  678.  
  679.     <942 "all done"
  680.  
  681.    If, while processing a LIST command, the server encounters an error,
  682.    then the server must return a 140 error message.  If the server
  683.    cannot process the LIST command (syntax error, etc.), then it must
  684.    return a 141 message.  For example:
  685.  
  686.     >LIST netx rtry
  687.     <141 "huh, bad list dude"
  688.  
  689.     or
  690.  
  691.     >LIST netx rtry * ifInOctets 15min * * * *
  692.     <941 "OK, here comes the list..."
  693.     <START-LIST
  694.     <netx rtry intf1
  695.     <netx rtry intf2
  696.     <netx rtry intf3
  697.     <END-LIST
  698.     <140 "Whoa, bad list dude, please ignore"
  699.  
  700. 3.8  The Server State Machine
  701.  
  702.    The state machine pictured below describes how a server should
  703.    interact with a client:
  704.  
  705.  
  706.                          +------+
  707.                +-------->| WAIT |<-----+
  708.                |         +------+      |
  709.                |  New       |          |
  710.                |  Connect   |          |  LOGIN Failure
  711.      EXIT      |           \ /         |
  712.      Received  |         +-------+     |
  713.                |         | LOGIN |-----+
  714.                |         +-------+
  715.                |             |
  716.                |             |  LOGIN Successful
  717.                |            \ /
  718.                |        +---------+
  719.                +--------| PROCESS |<----+
  720.                         +---------+     |
  721.                              |          |  Process Commands
  722.                              |          |
  723.                              +----------+
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730. Clark                        Informational                     [Page 13]
  731.  
  732. RFC 1856               Opstat Client-Server Model           October 1995
  733.  
  734.  
  735.    The server normally stays in WAIT (after starting and initialization)
  736.    until a new connection is made from a client.  The first command a
  737.    client must issue is a LOGIN command, otherwise the server must
  738.    immediately close the connection.  If the login process fails in any
  739.    way (as described in 3.2), then the server must immediately close the
  740.    connection and return to the WAIT state.
  741.  
  742.    Once a successful LOGIN is received, the server enters the PROCESS
  743.    state where it processes some number of LIST, GET, STATUS, and SELECT
  744.    commands. Any other command received while in this state must be
  745.    ignored, except for the EXIT command.  Once an EXIT command is
  746.    received, the server exits immediately (after perfoming any needed
  747.    internal bookkeeping) and returns to the WAIT state.  Any command a
  748.    server receives while processing a command (e.g., if you send an
  749.    "EXIT" while a large "GET" is being processed) will be ignored until
  750.    the command being processed completes.
  751.  
  752.    If the data connection to the client closes for any reason while the
  753.    server is in the PROCESS state, the server must immediately close its
  754.    connection and do any associated internal cleanup and return to the
  755.    LOGIN state.
  756.  
  757. 4.0  Security Issues
  758.  
  759.    There are legal, ethical and political concerns of data sharing.  For
  760.    this reason there is a need to insure integrity and confidentiality
  761.    of any shared data.  Although not specified in this standard,
  762.    mechanisms to control a user's access to specific data about specific
  763.    objects may need to be included in server implementations.  This
  764.    could potentially be done in several ways, including a configuration
  765.    file that listed the objects a user was allowed to access or limiting
  766.    file access by using file permissions within a given file system.  At
  767.    a minimum, the server should not allow default access to all data on
  768.    the server.
  769.  
  770.    Additionally, the server should strictly follow the state diagram
  771.    shown in section 3.8.  The server should be tested with arbitrary
  772.    strings in the command fields to ensure that no unexpected security
  773.    problems will be caused by the server.  The server should
  774.    specifically discard illegal ASCII characters as discussed in section
  775.    3.0.  If the server executes other programs, then the server must
  776.    verify that no unexpected side-effects will occur as the result of
  777.    the invocation or the arguments given to that program.  The server
  778.    should always verify that all data is contained within the input
  779.    buffer, and that a long input string from a client will not cause
  780.    unexpected side-effects.
  781.  
  782.  
  783.  
  784.  
  785.  
  786. Clark                        Informational                     [Page 14]
  787.  
  788. RFC 1856               Opstat Client-Server Model           October 1995
  789.  
  790.  
  791.    Finally, given the relative insecurity of the global Internet, and
  792.    the presence of packet-sniffing capability, several considerations
  793.    must be weighed.  The authentication process via the LOGIN process
  794.    must be strictly adhered to, and the use of one-time authentication
  795.    is strongly encouraged.  It is also suggested that the data returned
  796.    from the server be protected (such as through encryption) so that no
  797.    sensitive data is revealed by accident.
  798.  
  799. 5.0  Summary
  800.  
  801.    This document defines a protocol which could be used in a client-
  802.    server relationship to retrieve statistics from a remote database
  803.    server.
  804.  
  805.    Much work remains to be done in the area of Operational Statistics
  806.    including questions such as:
  807.  
  808.     - what "standard" graphs or "variables" should always be made
  809.       available to the user?
  810.     - what additions to the standard MIB would make the network
  811.       manager's job easier?
  812.  
  813. 6.0  References
  814.  
  815.    [1] Stockman, B., "A Model for Common Operational Statistics", RFC
  816.        1404, NORDUnet/SUNET, January 1993.
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842. Clark                        Informational                     [Page 15]
  843.  
  844. RFC 1856               Opstat Client-Server Model           October 1995
  845.  
  846.  
  847. Appendix A:  Sample Client-Server Sessions
  848.  
  849.    Session 1: Check available variables on device rtr1 interface eth0
  850.  
  851.     >LOGIN "henry" "skey"
  852.     <CHAL "78 lo35098"
  853.     >AUTH "COW MOO DOG BARK CAT MEOW"
  854.     <910 "Login OK, what now?"
  855.     >LIST OARnet rtr1 eth0 * * * *
  856.     <941 "List lookup OK, here it comes!"
  857.     <START-LIST
  858.     <OARnet rtr1 eth0 ifInOctets
  859.     <OARnet rtr1 eth0 ifOutOctets
  860.     <OARnet rtr1 eth0 ifInErrors
  861.     <OARnet rtr1 eth0 ifOutErrors
  862.     <END-LIST
  863.     <942 "List done!"
  864.     >EXIT
  865.     <990 "OK, Bye now!"
  866.  
  867.  
  868.     Session 2: Retrieve a bit of data from the server
  869.  
  870.  
  871.     >LOGIN henryc "skey"
  872.     <CHAL "78 lo35098"
  873.     >AUTH "COW MOO DOG BARK CAT MEOW"
  874.     <910 "Login OK, what now?"
  875.     >SELECT OARnet rtr1 eth0 InBytes 15min 1993-02-01 00:00:00 1993-03-01 23:59:59
  876.     <920 "TAG blah"
  877.     >STATUS
  878.     <931 "here it comes..."
  879.     <STATUS= OK
  880.     <TAG blah SIZE 654321
  881.     <932 "all done"
  882.     >GET blah 1404
  883.     <951 "here it comes..."
  884.     <START-DATA 1404
  885.  
  886.       1404 data here
  887.  
  888.     <END-DATA
  889.     <952 "wow, all done"
  890.     >EXIT
  891.     <990 "OK, bye"
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898. Clark                        Informational                     [Page 16]
  899.  
  900. RFC 1856               Opstat Client-Server Model           October 1995
  901.  
  902.  
  903. Author's Address
  904.  
  905. Henry Clark
  906. BBN Planet Corp.
  907. 150 Cambridge Park Dr.
  908. Cambridge, MA 02140
  909.  
  910. Phone:  (617) 873-4622
  911. EMail:  henryc@bbnplanet.com
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954. Clark                        Informational                     [Page 17]
  955.  
  956.