idnits 2.17.1 draft-ietf-opstat-client-server-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-23) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 80 instances of weird spacing in the document. Is it really formatted ragged-right, rather than justified? ** There are 2 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 180: '...EXIT command, the server MUST always...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 101 has weird spacing: '...tandard graph...' == Line 106 has weird spacing: '...rver is to a...' == Line 108 has weird spacing: '...n close the ...' == Line 111 has weird spacing: '..., which is l...' == Line 112 has weird spacing: '...defined in th...' == (75 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (30 Jan 1995) is 10676 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 470 looks like a reference -- Missing reference section? 'InBytes' on line 510 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft H. Clark 2 Opstat Working Group OARnet 3 draft-ietf-opstat-client-server-02.txt 30 Jan 1995 4 Expires: 30 Jul 1995 6 The Opstat Client-Server Model for Statistics Retrieval 8 Status of this Memo 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its areas, 12 and its working groups. Note that other groups may also distribute 13 working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six months 16 and may be updated, replaced, or obsoleted by other documents at any 17 time. It is inappropriate to use Internet- Drafts as reference 18 material or to cite them other than as ``work in progress.'' 20 To learn the current status of any Internet-Draft, please check the 21 ``1id-abstracts.txt'' listing contained in the Internet- Drafts 22 Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net 23 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 24 Rim). 26 Abstract 28 Network administrators gather data related to the performance, 29 utilization, usability and growth of their data network. The amount 30 of raw data gathered is usually quite large, typically ranging 31 somewhere between several megabytes to several gigabytes of data each 32 month. Few (if any) tools exist today for the sharing of that raw 33 data among network operators or between a network service provider 34 (NSP) and its customers. This document defines a model and protocol 35 for a set of tools which could be used by NSPs and Network Operation 36 Centers (NOCs) to share data among themselves and with customers. 38 1.0 Introduction 40 Network administrators gather data related to the performance, 41 utilization, usability and growth of their data network. The primary 42 goal of gathering the data is to facilitate near-term problem 43 isolation and longer-term network planning within the organization. 44 The amount of raw data gathered is usually quite large, typically 45 ranging somewhere between several megabytes to several gigabytes of 46 data each month. From this raw data, the network administrator 47 produces various types of reports. Few (if any) tools exist today 48 for the sharing of that raw data among network operators or between a 49 network service provider (NSP) and its customers. This document 50 defines a model and protocol for a set of tools which could be used 51 by NSPs and Network Operation Centers (NOCs) to share data among 52 themselves and with customers. 54 1.1 The OPSTAT Model 56 Under the Operational Statistics model [1], there exists a common 57 model under which tools exist for the collection, storage, retrieval 58 and presentation of network management data. 60 This document defines a protocol which would allow a client on a 61 remote machine to retrieve data from a central server, which itself 62 retrieves from the common statistics database. The client then 63 presents the data to the user in the form requested (maybe to a X- 64 window, or to paper). 66 The basic model used for the retrieval methods defined in this 67 document is a client-server model. This architecture envisions that 68 each NOC (or NSP) should install a server which provides locally 69 collected information for clients. Using a query language the client 70 should be able to define the network object of interest, the 71 interface, the metrics and the time period to be examined. Using a 72 reliable transport-layer protocol (e.g. TCP), the server will 73 transmit the requested data. Once this data is received by the 74 client it could be processed and presented by a variety of tools 75 including displaying the data in a X window, sending postscript to a 76 printer, or displaying the raw data on the user's terminal. 78 The remainder of this document describes how the client and server 79 interact, describes the protocol used between the client and server, 80 and discusses a variety of other issues surrounding the sharing of 81 data. 83 2.0 Client-Server Description 85 2.1 The Client 87 The basic function of the client is to retrieve data from the server. 88 It will accept requests from the user, translate those requests into 89 the common retrieval protocol and transmit them to the server, wait 90 for the server's reply, and send that reply to the user. 92 Note that this document does not define how the data should be 93 presented to the user. There are many methods of doing this 94 including: 96 - use a X based tool that displays graphs (a line, a histogram, etc.) 97 - generate PostScript output to be sent to a printer 98 - dump the raw data to the user's terminal 100 Future documents based on the Operational Statistics model may define 101 standard graphs and variables to be displayed, but this is work yet 102 to be done (as of this writing). 104 2.2 The Server 106 The basic function of the server is to accept connections from a 107 client, accept some series of commands from the client and perform a 108 series of actions based on the commands, and then close the connec- 109 tion to the client. 111 The server must have some type of configuration file, which is left 112 undefined in this document. The configuration file would list users 113 that could access the server along with the authentication strings 114 they would use. The configuration file should also allow the specif- 115 ication of the data items that the user should be permitted to access 116 (and, by implication, not allowed to access). Server security con- 117 cerns are specifically addressed in Section 4. 119 3.0 Protocol Commands 121 This section defines the commands which may be transmitted to the 122 server and the server responses to those commands. The available 123 commands are: 125 LOGIN - accept new connection 126 EXIT - disconnect 127 LIST - show available variables 128 SELECT - mark data for retrieval 129 STATUS - show the state of the server 130 GET - download data to the client 132 In addition, a state machine describing specific actions by the 133 server is included. Server security concerns are addressed in Sec- 134 tion 4. 136 Note that in some of the descriptions below, the term 137 is used. This refers to printable ASCII characters, defined as all 138 letters, numbers, and special characters such as $, %, or *. It 139 specifically excludes all special control characters in the lower 140 parts of the character set (i.e. 0x00 - 0x1F). 142 3.1 Command Return Codes 144 The only responses a server may return to a client are: 146 RETURN-CODE ::= | 147 OK-TYPE ::= OK | OK 148 ERROR-TYPE ::= ERROR | ERROR 150 The server should strive to return text along with the "OK" or 151 "ERROR" when appropriate to help guide the user in using the server. 152 If a command is sent where the server should return data, the server 153 must also return an OK (or ERROR, if appropriate) when if finishes 154 sending the data. 156 3.2 The LOGIN Command 158 The LOGIN command authenticates a user to the server. The format of 159 the LOGIN command is: 161 LOGIN-CMD ::= LOGIN 162 USERNAME ::= " " 163 AUTH-STRING ::= " " 165 A sample LOGIN command might look like: 167 LOGIN "user1" "cows" 169 The entry is just a simple ASCII string which helps to 170 authenticate a user to the server. This could be, for example, a 171 clear-text password or an encrypted/one-time password (preferred). 173 3.3 The EXIT Command 175 The EXIT command disconnects a current user from the server. The 176 format of the EXIT command is: 178 EXIT 180 Note that upon reception of an EXIT command, the server MUST always 181 close the connection, even if it would be appropriate to return an 182 ERROR return code. 184 3.4 The SELECT Command 186 The SELECT command is the function used to tag data for retrieval 187 from the server. The SELECT command has the format: 189 SELECT-COM ::= SELECT 190 191 NETWORK ::= 192 ROUTER ::= 193 INTERFACE ::= 194 VARNAME ::= 195 GRANULARITY ::= 196 START-DATE ::= 197 END-DATE ::= 198 DATE-TYPE ::= YYYY-MM-YY 199 AGG ::= | NULL 200 AGG-TYPE ::= TOTAL | PEAK 201 SELECT-COND ::= | NULL 202 SELECT-STMT ::= WITH DATA 203 COND-TYPE ::= LE | GE | EQ | NE | LT | GT 205 If any conditional within the SELECT does not match existing data 206 within the database (such as VARNAME, the S-DATE or E-DATE, or GRANU- 207 LARITY), the server must return an ERROR (and hopefully a meaningful 208 error message). The granularity should always be specified in 209 seconds. A sample query might be: 211 SELECT net rtr1 eth-0 ifInOctets 900 1992-01-01 1992-02-01 213 which would select all data from network "net" router "rtr1" inter- 214 face "eth-0" from Jan 1, 1992 to Feb 1, 1992. 216 Note that if the client requests some type of aggregation to be per- 217 formed upon the data, then the aggregation field specifies how to 218 perform the aggregration (i.e. total or peak) and the granularity 219 specifies to what interval (in seconds) to agggregate the data to. 220 If the server cannot perform the requested action, then it must 221 return an error. 223 Upon completion of the data lookup, the SELECT must return the an 224 indication of whether the lookup was successful and (if the search 225 was successful) the tag associated with that data. If the lookup was 226 successful, then information in the "OK" return code should be 227 encoded as: 229 TAG 231 In this case, the use of the word TAG is used as a handle for the 232 selected data on the server. Note that this single handle may refer 233 to one or more specific SNMP variables (refer to [1] for a further 234 explanation). 236 For example, if the tag "foobar" were assigned to the select example 237 above, then the OK would be as: 239 OK TAG foobar 241 It is recommended that the return tag string be less than 10 bytes 242 long (this gives many tag combinations), although the server (and 243 client) should be capable of handling arbitrary length strings. 244 There is no requirement that the TAG have any particular meaning and 245 may be composed of arbitrary strings. 247 The server must keep any internal information it needs during a ses- 248 sion so that all SELECT tags can be processed by GET or other com- 249 mands. If a server doesn't have the resources to process the given 250 SELECT, it must return an error message. 252 It is the responsibility of the client to store information about the 253 data that a particular tag corresponds to, i.e. if the client had 254 requested all ifInOctet data for October 1993 to be placed in a tag 255 called "1234", then the client must store that information someplace 256 as the variables will not be listed for each tag. 258 3.5 The STATUS Command 260 The STATUS command shows the general state of the server plus listing 261 all data sets which have been tagged via the SELECT command. The 262 STATUS command has no arguments. The output from a STATUS command 263 is: 265 STATUS-RETURN ::= START-STATUS END-STATUS 266 STATUS-DATA ::= 267 SERVER-STATUS ::= "STATUS= " 268 STATUS-FIELDS ::= "OK" | "NOT-OK" 269 SERVER-TAG-LIST ::= | NULL 270 SERVER-TAG ::= "TAG" "SIZE" 272 For example, a sample output might look like: 274 START-STATUS 275 STATUS= OK 276 TAG 1234 SIZE 123456 277 TAG ABCD SIZE 654321 278 END-STATUS 280 3.6 The GET Command 282 The GET command actually retrieves the data chosen via a previous 283 SELECT command. The GET command has the format: 285 GET-CMD ::= GET 286 TAG ::= 288 If the TAG matches a previously returned TAG from a SELECT statement, 289 then the previously tagged data is returned. If the TAG is invalid 290 (i.e. it hasn't been previously assigned by the server), then the 291 server must return an error. If the server, while retrieving the 292 data, cannot retrieve some portion of the data (i.e. some of the data 293 previously found disappeared between the time of the SELECT and the 294 time of the GET), then the server must return an error. 296 The data to be returned may be in any of several formats. Currently, 297 the only defined format is RFC1404. To handle these different types 298 of data, the following constructs are used: 300 RETURN-DATA-TYPE ::= START-DATA END-DATA 301 RETURN-TYPE ::= 1404 303 An example would be: 305 START-DATA 1404 1404 data stream here... END-DATA 307 After the end of data, an OK (or ERROR) must still be returned. If 308 an ERROR is returned, the client must discard all data received from 309 the server. 311 3.7 The LIST Command 313 The LIST command allows the client to query the server about avail- 314 able data residing on the server. The LIST command has the format: 316 LIST-CMD ::= LIST 317 ::= | * 318 ::= | * 319 ::= | * 320 ::= | * 321 ::= | * 322 ::= | * 323 ::= | * 325 For example, to get a list of networks that the server has data for, 326 you would use the command 328 LIST * * * * * * * 330 The command 332 LIST netx rtry * * * * * 334 will list all interfaces for rtry. The command 336 LIST netx rtry * ifInOctets * 1993-02-01 * 338 will get the list of interfaces on router "rtry" in network "netx" 339 which have values for the variable "ifInOctets" after the start date 340 of Februrary 1, 1993. 342 To process wildcards in a LIST command, follow these rules: 344 1) Only the leftmost wildcard will be serviced for a given 345 LIST command 346 2) If all fields to the right of the leftmost wildcard are 347 wildcards, then all values for the wildcard being processed 348 will be returned. 349 3) If specific values are given for fields to the right of the 350 wildcard being serviced, then the specific values must match 351 a known value 353 The output from the LIST command is formatted as follows: 355 LIST-RETURN ::= START-LIST END-LIST 356 LIST-ENTRY ::= 357 ::= 358 ::= | 359 ::= | 360 ::= | 361 ::= | 362 ::= | 363 ::= | 365 Note that only the fields with values in them will be returned by the 366 server. For example, the query to find the interfaces on rtry: 368 LIST netx rtry * * * * * 370 might return 372 START-LIST 373 netx rtry intf1 374 netx rtry intf2 375 netx rtry intf3 376 END-LIST 378 The query to find interfaces having ifInOctets data with a 15 minute 379 granularity: 381 LIST netx rtry * ifInOctets 15min * * 383 might return 385 START-LIST 386 netx rtry intf1 387 netx rtry intf2 388 netx rtry intf3 389 END-LIST 391 If, while processing a LIST command, the server encounters an error, 392 then the server must return an "ERROR" message. 394 3.8 The Server State Machine 396 The state machine pictured below describes how a server should 397 interact with a client: 399 +------+ 400 +-------->| WAIT |<-----+ 401 | +------+ | 402 | New | | 403 | Connect | | LOGIN Failure 404 EXIT | \ / | 405 Received | +-------+ | 406 | | LOGIN |-----+ 407 | +-------+ 408 | | 409 | | LOGIN Successful 410 | \ / 411 | +---------+ 412 +--------| PROCESS |<----+ 413 +---------+ | 414 | | Process Commands 415 | | 416 +----------+ 418 The server normally stays in WAIT (after starting and initialization) 419 until a new connection is made from a client. The first command a 420 client must issue is a LOGIN command, otherwise the server must 421 immediately close the connection. If a client issues a LOGIN command 422 using a invalid username or password, then the server must immedi- 423 ately close the connection. 425 Once a successful LOGIN is received, the server enters the PROCESS 426 state where it processes some number of LIST, GET, STATUS, and SELECT 427 commands. Any other command received while in this state must be 428 ignored, except for the EXIT command. Once an EXIT command is 429 received, the server exits immediately (after perfoming any needed 430 internal bookkeeping) and returns to the WAIT state. 432 4.0 Security Issues 434 There are legal, ethical and political concerns of data sharing. For 435 this reason there is a need to insure integrity and confidentiality 436 of any shared data. Although not specified in this standard, mechan- 437 isms to control a user's access to specific data about specific 438 objects may need to be included in server implementations. This 439 could potentially be done in several ways, including a configuration 440 file that listed the objects a user was allowed to access or limiting 441 file access by using file permissions within a given file system. At 442 a minimum, the server should not allow default access to all data on 443 the server. 445 Additionally, the server should strictly follow the state diagram 446 shown in section 3.8. The server should be tested with arbitrary 447 strings in the command fields to ensure that no unexpected security 448 problems will be caused by the server. The server should specifi- 449 cally discard illegal ASCII characters as discussed in section 3.0. 450 If the server executes other programs, then the server must verify 451 that no unexpected side-effects will occur as the result of the invo- 452 cation or the arguments given to that program. 454 5.0 Summary 456 This document defines a protocol which could be used in a client- 457 server relationship to retrieve statistics from a remote database 458 server. 460 Much work remains to be done in the area of Operational Statistics 461 including questions such as: 463 - what "standard" graphs or "variables" should always be made available 464 to the user? 465 - what additions to the standard MIB would make the network 466 manager's job easier? 468 6.0 References 470 [1] RFC1404 A Model for Common Operational Statistics, B. Stockman 472 Appendix A: Sample Client-Server Sessions 474 Session 1: Failed LOGIN 476 LOGIN henryc foobar 477 ERROR LOGIN Incorrect 479 Session 2: Check available variables on router rtr1 interface eth0 481 LOGIN henry foobar 482 OK 483 LIST OARnet rtr1 eth0 * * * * 484 START-LIST 485 OARnet rtr1 eth0 ifInOctets 486 OARnet rtr1 eth0 ifOutOctets 487 OARnet rtr1 eth0 ifInErrors 488 OARnet rtr1 eth0 ifOutErrors 489 END-LIST 490 OK 491 EXIT 492 OK 494 Session 3: Retrieve a bit of data from the server 496 LOGIN henryc foobar 497 OK 498 SELECT OARnet rtr1 eth0 InBytes 15min 1993-02-01 1993-03-01 499 OK TAG blah 500 STATUS 501 START-STATUS 502 STATUS= OK 503 TAG blah SIZE 654321 504 END-STATUS 505 OK 506 GET blah 507 START-DATA 1404 508 START-DATA 509 BEGIN_LABEL,, 510 [InBytes],19930201000000,19930301000000, 511 END_LABEL 512 BEGIN_DEVICE, 513 OARnet,rtr1,eth0,1536000,IP,1.2.3.4,+0500, 514 [InBytes,peak,[ifInOctets,900,900]], 515 END_DEVICE 516 BEGIN_DATA 517 19920730000000,InBytes,300,1, 518 19920730000300,InBytes,300,2, 519 19920730000600,InBytes,300,3, 520 END-DATA 521 END-DATA 522 OK 523 EXIT 524 OK 526 Author's Address 528 Henry Clark 529 OARnet 530 2455 North Star Rd 531 Columbus, OH 43221 533 Phone: (614) 728-8100 x 212 535 EMail: henryc@oar.net