Tech-invite   World Map
3GPPspecs     Glossaries     IETF     RFCs     Groups     SIP     ABNFs

RFC 8194

 
 
 

A YANG Data Model for LMAP Measurement Agents

Part 3 of 3, p. 45 to 59
Prev Section

 


prevText      Top      ToC       Page 45 
5.  Security Considerations

   The YANG module defined in this document is designed to be accessed
   via network management protocols such as NETCONF [RFC6241] or
   RESTCONF [RFC8040].  The lowest NETCONF layer is the secure transport
   layer, and the mandatory-to-implement secure transport is Secure
   Shell (SSH) [RFC6242].  The lowest RESTCONF layer is HTTPS, and the
   mandatory-to-implement secure transport is Transport Layer Security
   (TLS) [RFC5246].

   The NETCONF access control model [RFC6536] provides the means to
   restrict access for particular NETCONF or RESTCONF users to a
   preconfigured subset of all available NETCONF or RESTCONF protocol
   operations and content.

   There are a number of data nodes defined in this YANG module that are
   writable/creatable/deletable (i.e., config true, which is the
   default).  These data nodes may be considered sensitive or vulnerable
   in some network environments.  Write operations (e.g., edit-config)
   to these data nodes without proper protection can have a negative
   effect on network operations.  These are the subtrees and data nodes
   and their sensitivity/vulnerability:

   /lmap/agent           This subtree configures general properties of
                         the Measurement Agent such as its identity,
                         measurement point, or Controller timeout.  This
                         subtree should only have write access for the
                         system responsible for configuring the
                         Measurement Agent.

   /lmap/tasks           This subtree configures the Tasks that can be
                         invoked by a Controller.  This subtree should
                         only have write access for the system
                         responsible for configuring the Measurement
                         Agent.  Care must be taken to not expose Tasks
                         to a Controller that can cause damage to the
                         system or the network.

Top      Up      ToC       Page 46 
   /lmap/schedules       This subtree is used by a Controller to define
                         the Schedules and Actions that are executed
                         when certain events occur.  Unauthorized access
                         can cause unwanted load on the device or
                         network, or it might direct measurement traffic
                         to targets that become victims of an attack.

   /lmap/suppressions    This subtree is used by a Controller to define
                         Suppressions that can temporarily disable the
                         execution of Schedules or Actions.
                         Unauthorized access can either disable
                         measurements that should normally take place or
                         cause measurements to take place during times
                         when normally no measurements should take
                         place.

   /lmap/events          This subtree is used by a Controller to define
                         events that trigger the execution of Schedules
                         and Actions.  Unauthorized access can either
                         disable measurements that should normally take
                         place or cause measurements to take place
                         during times when normally no measurements
                         should take place or at a frequency that is
                         higher than normally expected.

   Some of the readable data nodes in this YANG module may be considered
   sensitive or vulnerable in some network environments.  It is thus
   important to control read access (e.g., via get, get-config, or
   notification) to these data nodes.  These are the subtrees and data
   nodes and their sensitivity/vulnerability:

   /lmap/agent           This subtree provides information about the
                         Measurement Agent.  This information may be
                         used to select specific targets for attacks.

   /lmap/capabilities    This subtree provides information about the
                         capabilities of the Measurement Agent,
                         including its software version number and the
                         Tasks that it supports.  This information may
                         be used to execute targeted attacks against
                         specific implementations.

   /lmap/schedules       This subtree provides information about the
                         Schedules and their associated Actions executed
                         on the Measurement Agent.  This information may
                         be used to check whether attacks against the
                         implementation are effective.

Top      Up      ToC       Page 47 
   /lmap/suppressions    This subtree provides information about the
                         Suppressions that can be active on the
                         Measurement Agent.  This information may be
                         used to predict time periods where measurements
                         take place (or do not take place).

   Some of the RPC operations in this YANG module may be considered
   sensitive or vulnerable in some network environments.  It is thus
   important to control access to these operations.  These are the
   operations and their sensitivity/vulnerability:

   /report   The report operation is used to send locally collected
             measurement results to a remote Collector.  Unauthorized
             access may leak measurement results, including those from
             passive measurements.

   The data model uses a number of identifiers that are set by the
   Controller.  Implementors may find these identifiers useful for the
   identification of resources, e.g., to identify objects in a file
   system providing temporary storage.  Since the identifiers used by
   the YANG data model may allow characters that may be given special
   interpretation in a specific context, implementations must ensure
   that identifiers are properly mapped into safe identifiers.

   The data model allows specifying options in the form of name/value
   pairs that are passed to programs.  Implementors ought to take care
   that option names and values are passed literally to programs.  In
   particular, shell expansions that may alter option names and values
   must not be performed.

6.  IANA Considerations

   This document registers three URIs in the "IETF XML Registry"
   [RFC3688].  Following the format in RFC 3688, the following
   registrations have been made.

         URI: urn:ietf:params:xml:ns:yang:ietf-lmap-common
         Registrant Contact: The IESG.
         XML: N/A; the requested URI is an XML namespace.

         URI: urn:ietf:params:xml:ns:yang:ietf-lmap-control
         Registrant Contact: The IESG.
         XML: N/A; the requested URI is an XML namespace.

         URI: urn:ietf:params:xml:ns:yang:ietf-lmap-report
         Registrant Contact: The IESG.
         XML: N/A; the requested URI is an XML namespace.

Top      Up      ToC       Page 48 
   This document registers three YANG modules in the "YANG Module Names"
   registry [RFC6020].

         Name: ietf-lmap-common
         Namespace: urn:ietf:params:xml:ns:yang:ietf-lmap-common
         Prefix: lmap
         Reference: RFC 8194

         Name: ietf-lmap-control
         Namespace: urn:ietf:params:xml:ns:yang:ietf-lmap-control
         Prefix: lmapc
         Reference: RFC 8194

         Name: ietf-lmap-report
         Namespace: urn:ietf:params:xml:ns:yang:ietf-lmap-report
         Prefix: lmapr
         Reference: RFC 8194

7.  References

7.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246,
              DOI 10.17487/RFC5246, August 2008,
              <https://www.rfc-editor.org/info/rfc5246>.

   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
              the Network Configuration Protocol (NETCONF)", RFC 6020,
              DOI 10.17487/RFC6020, October 2010,
              <https://www.rfc-editor.org/info/rfc6020>.

   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
              and A. Bierman, Ed., "Network Configuration Protocol
              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
              <https://www.rfc-editor.org/info/rfc6241>.

   [RFC6242]  Wasserman, M., "Using the NETCONF Protocol over Secure
              Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
              <https://www.rfc-editor.org/info/rfc6242>.

Top      Up      ToC       Page 49 
   [RFC6536]  Bierman, A. and M. Bjorklund, "Network Configuration
              Protocol (NETCONF) Access Control Model", RFC 6536,
              DOI 10.17487/RFC6536, March 2012,
              <https://www.rfc-editor.org/info/rfc6536>.

   [RFC6991]  Schoenwaelder, J., Ed., "Common YANG Data Types",
              RFC 6991, DOI 10.17487/RFC6991, July 2013,
              <https://www.rfc-editor.org/info/rfc6991>.

   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
              RFC 7950, DOI 10.17487/RFC7950, August 2016,
              <https://www.rfc-editor.org/info/rfc7950>.

   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
              <https://www.rfc-editor.org/info/rfc8040>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8193]  Burbridge, T., Eardley, P., Bagnulo, M., and J.
              Schoenwaelder, "Information Model for Large-Scale
              Measurement Platforms (LMAPs)", DOI 10.17487/RFC8193,
              RFC 8193, August 2017,
              <http://www.rfc-editor.org/info/rfc8193>.

7.2.  Informative References

   [ISO-8601]
              International Organization for Standardization, "Data
              elements and interchange formats -- Information
              interchange -- Representation of dates and times", ISO
              Standard 8601:2004, December 2004.

   [NETCONF-CLIENT-SERVER]
              Watsen, K., Wu, G., and J. Schoenwaelder, "NETCONF Client
              and Server Models", Work in Progress, draft-ietf-netconf-
              netconf-client-server-04, July 2017.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [RFC5424]  Gerhards, R., "The Syslog Protocol", RFC 5424,
              DOI 10.17487/RFC5424, March 2009,
              <https://www.rfc-editor.org/info/rfc5424>.

Top      Up      ToC       Page 50 
   [RFC7223]  Bjorklund, M., "A YANG Data Model for Interface
              Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
              <https://www.rfc-editor.org/info/rfc7223>.

   [RFC7317]  Bierman, A. and M. Bjorklund, "A YANG Data Model for
              System Management", RFC 7317, DOI 10.17487/RFC7317, August
              2014, <https://www.rfc-editor.org/info/rfc7317>.

   [RFC7398]  Bagnulo, M., Burbridge, T., Crawford, S., Eardley, P., and
              A. Morton, "A Reference Path and Measurement Points for
              Large-Scale Measurement of Broadband Performance",
              RFC 7398, DOI 10.17487/RFC7398, February 2015,
              <https://www.rfc-editor.org/info/rfc7398>.

   [RFC7594]  Eardley, P., Morton, A., Bagnulo, M., Burbridge, T.,
              Aitken, P., and A. Akhter, "A Framework for Large-Scale
              Measurement of Broadband Performance (LMAP)", RFC 7594,
              DOI 10.17487/RFC7594, September 2015,
              <https://www.rfc-editor.org/info/rfc7594>.

   [W3C.REC-xml-20081126]
              Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
              F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
              Edition)", World Wide Web Consortium Recommendation REC-
              xml-20081126, November 2008,
              <http://www.w3.org/TR/2008/REC-xml-20081126>.

   [YANG-HARDWARE]
              Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A
              YANG Data Model for Hardware Management", Work in
              Progress, draft-ietf-netmod-entity-03, March 2017.

Top      Up      ToC       Page 51 
Appendix A.  Example Parameter Extension Module

   Sometimes Tasks may require complicated parameters that cannot easily
   be fit into options, i.e., a list of name/value pairs.  In such a
   situation, it is possible to augment the ietf-lmap-control.yang and
   ietf-lmap-report.yang data models with definitions for more complex
   parameters.  The following example module demonstrates this idea
   using the parameters of UDP latency metrics as an example (although
   UDP latency metric parameters do not really need such an extension
   module).

  module example-ietf-ippm-udp-latency {

    namespace "urn:example:ietf-ippm-udp-latency";
    prefix "ippm-udp-latency";

    import ietf-inet-types {
      prefix inet;
    }
    import ietf-lmap-control {
      prefix "lmapc";
    }
    import ietf-lmap-report {
      prefix "lmapr";
    }

    grouping ippm-udp-latency-parameter-grouping {
      leaf src-ip {
        type inet:ip-address;
        description
          "The source IP address of the UDP measurement traffic.";
      }

      leaf src-port {
        type inet:port-number;
        description
          "The source port number of the UDP measurement traffic.";
      }

      leaf dst-ip {
        type inet:ip-address;
        description
          "The destination IP address of the UDP measurement traffic.";
      }

Top      Up      ToC       Page 52 
      leaf dst-port {
        type inet:port-number;
        description
          "The destination port number of the UDP measurement traffic.";
      }

      leaf poisson-lambda {
        type decimal64 {
          fraction-digits 4;
        }
        units "seconds";
        default 1.0000;
        description
          "The average interval for the poisson stream with a resolution
           of 0.0001 seconds (0.1 ms).";
      }

      leaf poisson-limit {
        type decimal64 {
          fraction-digits 4;
        }
        units "seconds";
        default 30.0000;
        description
          "The upper limit on the poisson distribution with a resolution
           of 0.0001 seconds (0.1 ms).";
      }
    }

    augment "/lmapc:lmap/lmapc:schedules/lmapc:schedule/lmapc:action"
          + "/lmapc:parameters/lmapc:extension" {
      description
        "This augmentation adds parameters specific to IP Performance
          Metrics (IPPM) and UDP latency metrics to Actions.";

      case "ietf-ippm-udp-latency" {
        uses ippm-udp-latency-parameter-grouping;
      }
    }

Top      Up      ToC       Page 53 
    augment "/lmapr:report/lmapr:input/lmapr:result"
          + "/lmapr:parameters/lmapr:extension" {
      description
        "This augmentation adds parameters specific to IPPM and
         UDP latency metrics to reports.";

      case "ietf-ippm-udp-latency" {
        uses ippm-udp-latency-parameter-grouping;
      }
    }

  }

Appendix B.  Example Configuration

   The configuration below is in XML [W3C.REC-xml-20081126].

   <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
     <lmap xmlns="urn:ietf:params:xml:ns:yang:ietf-lmap-control">

       <agent>
         <agent-id>550e8400-e29b-41d4-a716-446655440000</agent-id>
         <report-agent-id>true</report-agent-id>
       </agent>

       <schedules>
         <!-- The Schedule S1 first updates a list of ping targets
              and subsequently sends a ping to all targets. -->
         <schedule>
           <name>S1</name>
           <start>E1</start>
           <execution-mode>sequential</execution-mode>
           <action>
             <name>A1</name>
             <task>update-ping-targets</task>
           </action>
           <action>
             <name>A2</name>
             <task>ping-all-targets</task>
             <destination>S3</destination>
           </action>
           <suppression-tag>measurement:ping</suppression-tag>
         </schedule>
         <!-- The Schedule S2 executes two traceroutes concurrently. -->
         <schedule>
           <name>S2</name>
           <start>E1</start>
           <execution-mode>parallel</execution-mode>

Top      Up      ToC       Page 54 
           <action>
             <name>A1</name>
             <task>traceroute</task>
             <option>
               <id>target</id>
               <name>target</name>
               <value>2001:db8::1</value>
             </option>
             <destination>S3</destination>
           </action>
           <action>
             <name>A2</name>
             <task>traceroute</task>
             <option>
               <id>target</id>
               <name>target</name>
               <value>2001:db8::2</value>
             </option>
             <destination>S3</destination>
           </action>
           <suppression-tag>measurement:traceroute</suppression-tag>
         </schedule>
         <!-- The Schedule S3 sends measurement data to a Collector. -->
         <schedule>
           <name>S3</name>
           <start>E2</start>
           <action>
             <name>A1</name>
             <task>report</task>
             <option>
               <id>collector</id>
               <name>collector</name>
               <value>https://collector.example.com/</value>
             </option>
           </action>
         </schedule>
       </schedules>

       <suppressions>
         <!-- Stop all measurements if we got orphaned. -->
         <suppression>
           <name>orphaned</name>
           <start>controller-lost</start>
           <end>controller-connected</end>
           <match>measurement:*</match>
         </suppression>
       </suppressions>

Top      Up      ToC       Page 55 
       <tasks>
         <!-- configuration of an update-ping-targets task -->
         <task>
           <name>update-ping-targets</name>
           <program>fping-update-targets</program>
         </task>
         <!-- configuration of a ping-all-targets task -->
         <task>
           <name>ping-all-targets</name>
           <program>fping</program>
         </task>
         <!-- configuration of a traceroute task -->
         <task>
           <name>traceroute</name>
           <program>mtr</program>
           <option>
             <id>csv</id>
             <name>--csv</name>
           </option>
         </task>
         <!-- configuration of a reporter task -->
         <task>
           <name>report</name>
           <program>lmap-report</program>
         </task>

         <task>
           <name>ippm-udp-latency-client</name>
           <program>ippm-udp-latency</program>
           <function>
             <uri>urn:example:tbd</uri>
             <role>client</role>
           </function>
           <tag>active</tag>
         </task>
       </tasks>

       <events>
         <!-- The event E1 triggers every hour during September 2016
              with a random spread of one minute. -->
         <event>
           <name>E1</name>
           <random-spread>60</random-spread>   <!-- seconds -->
           <periodic>
             <interval>3600000</interval>
             <start>2016-09-01T00:00:00+00:00</start>
             <end>2016-11-01T00:00:00+00:00</end>
           </periodic>

Top      Up      ToC       Page 56 
         </event>
         <!-- The event E2 triggers on Mondays at 4am UTC -->
         <event>
           <name>E2</name>
           <calendar>
             <month>*</month>
             <day-of-week>monday</day-of-week>
             <day-of-month>*</day-of-month>
             <hour>4</hour>
             <minute>0</minute>
             <second>0</second>
             <timezone-offset>+00:00</timezone-offset>
           </calendar>
         </event>
         <!-- The event controller-lost triggers when we lost
              connectivity with the Controller. -->
         <event>
           <name>controller-lost</name>
           <controller-lost/>
         </event>
         <!-- The event contoller-connected triggers when we
              established or re-established connectivity with
              the Controller. -->
         <event>
           <name>controller-connected</name>
           <controller-connected/>
         </event>
       </events>
     </lmap>
   </config>

Appendix C.  Example Report

   The report below is in XML [W3C.REC-xml-20081126].

   <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
        message-id="1">
     <report xmlns="urn:ietf:params:xml:ns:yang:ietf-lmap-report">
       <date>2015-10-28T13:27:42+02:00</date>
       <agent-id>550e8400-e29b-41d4-a716-446655440000</agent-id>
       <result>
         <schedule>S1</schedule>
         <action>A1</action>
         <task>update-ping-targets</task>
         <start>2016-03-21T10:48:55+01:00</start>
         <end>2016-03-21T10:48:57+01:00</end>
         <status>0</status>
       </result>

Top      Up      ToC       Page 57 
       <result>
         <schedule>S1</schedule>
         <action>A2</action>
         <task>ping-all-targets</task>
         <start>2016-03-21T10:48:55+01:00</start>
         <end>2016-03-21T10:48:57+01:00</end>
         <status>0</status>
         <table>
           <column>target</column>
           <column>rtt</column>
           <row>
             <value>2001:db8::1</value>
             <value>42</value>
           </row>
           <row>
             <value>2001:db8::2</value>
             <value>24</value>
           </row>
         </table>
       </result>
       <result>
         <schedule>S2</schedule>
         <action>A1</action>
         <task>traceroute</task>
         <option>
           <id>target</id>
           <name>target</name>
           <value>2001:db8::1</value>
         </option>
         <option>
           <id>csv</id>
           <name>--csv</name>
         </option>
         <start>2016-03-21T10:48:55+01:00</start>
         <end>2016-03-21T10:48:57+01:00</end>
         <status>1</status>
         <table>
           <column>hop</column>
           <column>ip</column>
           <column>rtt</column>
           <row>
             <value>1</value>
             <value>2001:638:709:5::1</value>
             <value>10.5</value>
           </row>
           <row>
             <value>2</value>
             <value>?</value>

Top      Up      ToC       Page 58 
             <value></value>
           </row>
         </table>
       </result>
       <result>
         <schedule>S2</schedule>
         <action>A2</action>
         <task>traceroute</task>
         <option>
           <id>target</id>
           <name>target</name>
           <value>2001:db8::2</value>
         </option>
         <option>
           <id>csv</id>
           <name>--csv</name>
         </option>
         <start>2016-03-21T10:48:55+01:00</start>
         <end>2016-03-21T10:48:57+01:00</end>
         <status>1</status>
         <table>
           <column>hop</column>
           <column>ip</column>
           <column>rtt</column>
           <row>
             <value>1</value>
             <value>2001:638:709:5::1</value>
             <value>11.8</value>
           </row>
           <row>
             <value>2</value>
             <value>?</value>
             <value></value>
           </row>
         </table>
       </result>
     </report>
   </rpc>

Top      Up      ToC       Page 59 
Acknowledgements

   Several people contributed to this specification by reviewing early
   draft versions and actively participating in the LMAP Working Group
   (apologies to those unintentionally omitted): Marcelo Bagnulo, Martin
   Bjorklund, Trevor Burbridge, Timothy Carey, Alissa Cooper, Philip
   Eardley, Al Morton, Dan Romascanu, Andrea Soppera, Barbara Stark, and
   Qin Wu.

   Juergen Schoenwaelder and Vaibhav Bajpai worked in part on the Leone
   research project, which received funding from the European Union
   Seventh Framework Programme [FP7/2007-2013] under grant agreement
   number 317647.

   Juergen Schoenwaelder and Vaibhav Bajpai were partly funded by
   Flamingo, a Network of Excellence project (ICT-318488) supported by
   the European Commission under its Seventh Framework Programme.

Authors' Addresses

   Juergen Schoenwaelder
   Jacobs University Bremen

   Email: j.schoenwaelder@jacobs-university.de


   Vaibhav Bajpai
   Technical University of Munich

   Email: bajpaiv@in.tum.de