/[marcuscom]/IETF/trunk/i2rs-traceability/draft-clarke-i2rs-traceability.xml
ViewVC logotype

Diff of /IETF/trunk/i2rs-traceability/draft-clarke-i2rs-traceability.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 19720 by marcus, Tue Jun 3 19:50:32 2014 UTC revision 19721 by marcus, Fri Jun 6 05:09:49 2014 UTC
# Line 3  Line 3 
3  <!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">  <!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
4  <!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">  <!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
5  <!ENTITY RFC3339 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml">  <!ENTITY RFC3339 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3339.xml">
 <!ENTITY RFC3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">  
 <!ENTITY RFC4122 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4122.xml">  
 <!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">  
6  <!ENTITY RFC5424 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5424.xml">  <!ENTITY RFC5424 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5424.xml">
7  <!ENTITY RFC5737 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5737.xml">  <!ENTITY RFC5737 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5737.xml">
8    <!ENTITY RFC6020 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6020.xml">
9  <!ENTITY I2RS-ARCHITECTURE SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-i2rs-architecture.xml">  <!ENTITY I2RS-ARCHITECTURE SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-i2rs-architecture.xml">
10  <!ENTITY I2RS-PROBLEM-STATEMENT SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-i2rs-problem-statement.xml">  <!ENTITY I2RS-PROBLEM-STATEMENT SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-i2rs-problem-statement.xml">
11  <!ENTITY I2RS-RIB-INFO-MODEL SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.nitinb-i2rs-rib-info-model.xml">  <!ENTITY I2RS-RIB-INFO-MODEL SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.nitinb-i2rs-rib-info-model.xml">
# Line 196  Line 194 
194        |  Actor ID   |        |  Actor ID   |
195        +-------------+        +-------------+
196               ^               ^
197               :               :   0 .. N
198               :               :
199               V               V
200        +-------------+        +-------------+
# Line 205  Line 203 
203        |  Client ID  |        |  Client ID  |
204        +-------------+        +-------------+
205               ^               ^
206               |               |  1 .. N
207               |               |
208               V               V
209        +-------------+                 +-----------------------------+        +-------------+                 +-----------------------------+
210        |I2RS Agent   |---------------->|Trace Log                    |        |I2RS Agent   |---------------->|Trace Log                    |
211        |             |                 |.............................|        |             |                 |.............................|
212        +-------------+                 |Timestamp                    |        +-------------+                 |Entry ID                     |
213                                          |Timestamp                    |
214               ^                        |Client ID                    |               ^                        |Client ID                    |
215               |      ^                 |Actor ID                     |               |      ^                 |Actor ID                     |
216   Operation + | Result Code            |Client Address               |   Operation + | Result Code            |Client Address               |
# Line 235  Line 234 
234          trace log.</t>          trace log.</t>
235          <t>          <t>
236            <list style="hanging">            <list style="hanging">
237                <t hangText="Entry ID: ">This is a unique identifier for
238                each entry in the I2RS trace log.  Since multiple operations can occur
239                from the same client at the same time, it is important to have an
240                identifier that can be unambiguously associated to a
241                specific entry.</t>
242              <t hangText="Timestamp: ">The specific time, adhering to              <t hangText="Timestamp: ">The specific time, adhering to
243              <xref target="RFC3339"/> format, at which the I2RS              <xref target="RFC3339"/> format, at which the I2RS
244              transaction occurred. Given that many I2RS transactions              transaction occurred. Given that many I2RS transactions
# Line 303  Line 307 
307        </section>        </section>
308        <section anchor="syntax" title="I2RS Trace Log Syntax">        <section anchor="syntax" title="I2RS Trace Log Syntax">
309          <t>The following describes the trace log information model          <t>The following describes the trace log information model
310          using Augmented Backus-Naur Form (ABNF) syntax <xref target="RFC5234"/>:</t>          using YANG syntax <xref target="RFC6020"/>:</t>
311          <figure>          <figure align="center">
312            <artwork type="abnf"><![CDATA[i2rs-trace-log = timestamp client-id actor-id client-addr operation                          <artwork align="left">
313                   operation-data result-code  module: i2rs-trace-log
314  client-id      = uuid     +--rw i2rs-trace-log
315  actor-id       = byte-string        +--rw log-enable?   boolean
316  byte-string    = *( %x01-09  /  %x0B-0C  /  %x0E-FF )        +--ro log-entry* [log-entry-id]
317                   ; any byte except NUL, CR or LF           +--ro log-entry-id      log-entry-id
318  client-addr    = IP-literal / IPv4address           +--ro timestamp         timestamp
319  operation      = ALPHA *( ALPHA / "_" / "-" / "(" / ")" )           +--ro client-id         client-id
320  operation-data = *VCHAR           +--ro actor-id          actor-id
321  result-code    = 1*( ALPHA / DIGIT / "-" / "_" / "(" / ")" )            ]]></artwork>           +--ro client-addr       client-addr
322          </figure>           +--ro operation         operation
323          <t>The ABNF syntax rules &lt;IP-literal&gt;,           +--ro operation-data    operation-data
324          &lt;IPv4address&gt;, and &lt;sub-delims&gt; are specified in           +--ro result-code       result-code
325          <xref target="RFC3986"/>. The core rules &lt;DIGIT&gt;,                          </artwork>
326          &lt;ALPHA&gt; and &lt;VCHAR&gt; are used as described in                  </figure>
327          Appendix B of <xref target="RFC5234"/>.</t>          <t>The idea of using a UUID for the Client
         <t>Here, &lt;uuid&gt; is specified in <xref target="RFC4122"/>. The idea of using a UUID for the Client  
328          identifier ensures the ID is unique not just in the scope of          identifier ensures the ID is unique not just in the scope of
329          the current I2RS Agent, but across Agents as well. This          the current I2RS Agent, but across Agents as well. This
330          ensures that two clients that are unaware of each other will          ensures that two clients that are unaware of each other will
331          not allocate the same Client ID. That does not preclude two          not allocate the same Client ID. That does not preclude two
332          Clients acting as one for purposes of high availability from          Clients acting as one for purposes of high availability from
333          sharing the same UUID as generated by one one of the Clients.          sharing the same UUID as generated by one one of the Clients.</t>
         [Note: the format of the Client ID has not yet been decided by  
         the I2RS WG. This is subject to change.]</t>  
334          <t>The &lt;timestamp&gt; field is defined in <xref target="RFC3339"/>. As stated in <xref target="info_required"/> the fractional second format MUST be          <t>The &lt;timestamp&gt; field is defined in <xref target="RFC3339"/>. As stated in <xref target="info_required"/> the fractional second format MUST be
335          used to provide proper granularity.</t>          used to provide proper granularity.</t>
336          <t>The values for &lt;operation&gt;, &lt;operation-data&gt;          <t>The values for &lt;operation&gt;, &lt;operation-data&gt;
# Line 342  result-code    = 1*( ALPHA / DIGIT / "-" Line 343  result-code    = 1*( ALPHA / DIGIT / "-"
343          translations MUST be included in the log. The opcodes          translations MUST be included in the log. The opcodes
344          themselves MAY appear in parentheses after the textual          themselves MAY appear in parentheses after the textual
345          representation.</t>          representation.</t>
346            <section title="I2RS Trace Log Yang Module">
347              <t>
348                <figure>
349                  <artwork>
350    &lt;CODE BEGINS&gt;
351    file "i2rs-trace-log@2014-06-06.yang"
352    module i2rs-trace-log {
353            yang-version 1;
354            namespace "urn:TBD:params:xml:ns:yang:i2rs:trace-log";
355            // This namespace should be considered with other I2RS YANG
356            // models.
357            prefix i2rslog;
358    
359            import ietf-yang-types {
360                    prefix "yang";
361            }
362    
363            import ietf-inet-types {
364                    prefix "inet";
365            }
366    
367            organization "TBD";
368    
369            contact
370               "Joe Clarke jclarke@cisco.com
371               Gonzalo Salgueiro gsalguei@cisco.com
372               Carlos Pignataro cpignata@cisco.com";
373    
374            description
375                "This module defines the model for I2RS traceability
376            based on the I2RS architecture as defined in
377            draft-ietf-i2rs-architecture.";
378    
379            reference
380                "draft-ietf-i2rs-architecture: An Architecture for the
381            Interface to the Routing System";
382    
383            revision "2014-06-03" {
384                    description "Initial revision";
385                    reference "TBD";
386            }
387    
388            typedef log-entry-id {
389                    type uint64;
390                    description
391                        "A unique identifier for I2RS log entries.";
392            }
393    
394            typedef timestamp {
395                    type yang:date-and-time;
396                    description
397                        "Timestamp for I2RS transactions.";
398            }
399    
400            typedef client-id {
401                    type yang:uuid;
402                    description
403                        "The I2RS Client identifier used to authenticate
404                    the Client to the I2RS Agent.";
405            }
406    
407            typedef actor-id {
408                    type union {
409                            type string {
410                                    pattern "[^\r\n]+";
411                            }
412                            type enumeration {
413                                    enum UNAVAILABLE {
414                                            description
415                                                "The Actor ID was not
416                                            specified by the Client.";
417                                    }
418                            }
419                    }
420                    description
421                        "Identifier used to trace the northbound actor
422                    driving the actions of the Client.";
423            }
424    
425            typedef client-addr {
426                    type inet:ip-address;
427                    description
428                        "IP address of the client that connected to the
429                    Agent.";
430            }
431    
432            typedef operation {
433                    type string {
434                            pattern "[a-zA-Z] [a-zA-Z_\-\(\)]*";
435                        }
436                    description
437                        "This is the I2RS operation performed.";
438            }
439    
440            typedef operation-data {
441                    type union {
442                            type string;
443                            type enumeration {
444                                    enum NULL {
445                                            description
446                                                "No additional operation
447                                            data was required.";
448                                    }
449                            }
450                    }
451                    description
452                        "Data passed to the Agent to complete the desired
453                    operation.";
454            }
455    
456            typedef result-code {
457                    type string {
458                            pattern "[a-zA-Z0-9_\-\(\)]+";
459                    }
460                    description
461                        "Result code for the operation.";
462            }
463    
464            container i2rs-trace-log {
465                    description
466                        "This is the model for I2RS traceability.  An
467                    I2RS log is comprised of the following mandatory
468                    fields.  Each field MUST be identified by a unique
469                    log-entry-id.";
470                    leaf log-enable {
471                            type boolean;
472                            default "true";
473                            description
474                                "Enable/Disable I2RS logging.";
475                    }
476                    list log-entry {
477                            key "log-entry-id";
478                            config false;
479                            description
480                                "Each element in an I2RS trace log is
481                            discrete and identified by its unique log
482                            entry ID.";
483                            leaf log-entry-id {
484                                    type log-entry-id;
485                                    config false;
486                                    description
487                                        "This is a unique identifier for
488                                    each entry in the I2RS trace log.
489                                    Since multiple operations can occur
490                                    from the same client at the same
491                                    time, it is important to have an
492                                    identifier that can be unambiguously
493                                    associated to a specific entry.";
494                            }
495                            leaf timestamp {
496                                    type timestamp;
497                                    config false;
498                                    mandatory true;
499                                    description
500                                        "The specific time, adhering to
501                                    RFC3339 format, at which the I2RS
502                                    transaction occurred. Given that
503                                    many I2RS transactions can occur in
504                                    rapid succession, the use of
505                                    fractional seconds MUST be used to
506                                    provide adequate granularity.";
507                                    reference
508                                        "RFC 3339: Date and Time on the
509                                    Internet: Timestamps";
510                            }
511                            leaf client-id {
512                                    type client-id;
513                                    config false;
514                                    mandatory true;
515                                    description
516                                        "The I2RS Client identifier used
517                                    to authenticate the Client to the
518                                    I2RS Agent.";
519                            }
520                            leaf actor-id {
521                                    type actor-id;
522                                    config false;
523                                    mandatory true;
524                                    description
525                                        "This is an opaque identifier
526                                     that may be known to the Client
527                                     from a northbound controlling
528                                     application. This is used to
529                                     trace the northbound actor
530                                     driving the actions of the
531                                     Client. The Client may not
532                                     provide this identifier to the
533                                     Agent if there is no external
534                                     actor driving the Client. In
535                                     that case, the special value,
536                                     UNAVAILABLE is used to denote no
537                                     Actor ID.";
538                            }
539                            leaf client-addr {
540                                    type client-addr;
541                                    config false;
542                                    mandatory true;
543                                    description
544                                        "This is the IP address of the
545                                    client that connected to the Agent.";
546                            }
547                            leaf operation {
548                                    type operation;
549                                    config false;
550                                    mandatory true;
551                                    description
552                                        "This is the I2RS operation
553                                    performed.";
554                            }
555                            leaf operation-data {
556                                    type operation-data;
557                                    config false;
558                                    mandatory true;
559                                    description
560                                        "This field comprises the data
561                                    passed to the Agent to complete the
562                                    desired operation.  If no additional
563                                    operation data is required, then this
564                                    field should be set to the special
565                                    value, NULL.";
566                            }
567                            leaf result-code {
568                                    type result-code;
569                                    config false;
570                                    mandatory true;
571                                    description
572                                        "This field holds the result of
573                                    the operation. In the case of RIB
574                                    operations, this MUST be the return
575                                    code as specified in Section 4 of
576                                    draft-nitinb-i2rs-rib-info-model.
577                                    The operation may not complete with
578                                    a result code in the case of a
579                                    timeout. If the operation fails to
580                                    complete, it MUST still log the
581                                    attempted operation with an
582                                    appropriate result code (e.g., a
583                                    result code indicating a timeout).";
584                                    reference
585                                    "draft-nitinb-i2rs-rib-info-model:
586                                    Routing Information Base Info Model";
587                            }
588                    }
589            }
590    }
591    &lt;CODE ENDS&gt;
592                  </artwork>
593                </figure>
594                  </t>
595            </section>
596        </section>        </section>
597      </section>      </section>
598      <section title="Examples">      <section title="Examples">
# Line 351  result-code    = 1*( ALPHA / DIGIT / "-" Line 602  result-code    = 1*( ALPHA / DIGIT / "-"
602        <vspace blankLines="1"/></t>        <vspace blankLines="1"/></t>
603        <figure>        <figure>
604          <artwork><![CDATA[          <artwork><![CDATA[
605    Entry ID:       1
606  Timestamp:      2013-09-03T12:00:01.21+00:00  Timestamp:      2013-09-03T12:00:01.21+00:00
607  Client ID:      5CEF1870-0326-11E2-A21F-0800200C9A66  Client ID:      5CEF1870-0326-11E2-A21F-0800200C9A66
608  Actor ID:       com.example.RoutingApp  Actor ID:       com.example.RoutingApp
# Line 506  Result Code:    SUCCESS(0) Line 758  Result Code:    SUCCESS(0)
758    
759        &I2RS-PROBLEM-STATEMENT;        &I2RS-PROBLEM-STATEMENT;
760    
761        &RFC3986;        &RFC6020;
   
       &RFC4122;  
   
       &RFC5234;  
762      </references>      </references>
763      <references title="Informative References">      <references title="Informative References">
764        &I2RS-RIB-INFO-MODEL;        &I2RS-RIB-INFO-MODEL;

Legend:
Removed from v.19720  
changed lines
  Added in v.19721

  ViewVC Help
Powered by ViewVC 1.1.27