Network Working Group A. Oslebo Internet-Draft UNINETT Intended status: Standards Track October 27, 2014 Expires: April 30, 2015 A YANG based Data Model for the LMAP Controller draft-oslebo-lmap-control-yang-01.txt Abstract This document defines a YANG data model for the LMAP controller. The measurement agents can poll configuration data from the controller using RESTCONF. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on April 30, 2015. Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://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. Oslebo Expires April 30, 2015 [Page 1] Internet-Draft LMAP Control Data Model October 2014 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements notation . . . . . . . . . . . . . . . . . . 3 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 2. Data Model Overview . . . . . . . . . . . . . . . . . . . . . 3 3. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Security Considerations . . . . . . . . . . . . . . . . . . . 22 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 6. Normative References . . . . . . . . . . . . . . . . . . . . 22 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 22 Appendix B. Example configuration . . . . . . . . . . . . . . . 22 Appendix C. RESTCONF queries . . . . . . . . . . . . . . . . . . 25 C.1. Get configuration - XML format . . . . . . . . . . . . . 25 C.2. Get schedules - JSON format . . . . . . . . . . . . . . . 26 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26 1. Introduction The LMAP framework[I-D.ietf-lmap-framework] defines three main components: o Measurement Agents (MAs) - initiates the actual measurements. o Controller - controls one or more MAs. It instructs them when to do measurements and when and how to report the results. o Collector - accepts measurement results from MAs This document defines a YANG data model for the LMAP controller. The model can be used by operators to configure all the MAs that are controlled by the controller and by MAs to retrieve the configuration data. The MAs will poll the information stored on the controller using the RESTCONF protocol[I-D.ietf-netconf-restconf]. A future draft will define a YANG model for the collector that can be used by the MAs to report the results. RESTCONF is a protocol currently being standardized in the NETCONF working group. It is a HTTP based protocol that defines a standard mechansism for accessing data defined in YANG, using datastores defined in NETCONF. All the basic features needed for the LMAP control protocol is covered by RESTCONF: o Full support for Create, Retrieve, Update and Delete (CRUD) operations. o Support for both XML and JSON format. Oslebo Expires April 30, 2015 [Page 2] Internet-Draft LMAP Control Data Model October 2014 o Formal validation based on YANG model. o Filter mechanisms to request a subset of the target resource contents. o Notification support for controller initiated messages 1.1. Requirements notation The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 1.2. Tree Diagrams A simplified graphical representation of the data model is used in this document. The meaning of the symbols in these diagrams is as follows: o Brackets "[" and "]" enclose list keys. o Abbreviations before data node names: "rw" means configuration (read-write), and "ro" means state data (read-only). o Symbols after data node names: "?" means an optional node, "!" means a presence container, and "*" denotes a list and leaf-list. o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":"). o Ellipsis ("...") stands for contents of subtrees that are not shown. 2. Data Model Overview The data model first defines a set of common objects for tasks, channels, schedules, and timing definitions that are shared among all the MAs that are controlled by the controller. It then defines a list of MA objects that contains configuration specific for each MA. In the MA object there is a list of references to the common schedules and each reference represents an active schedule for this specific MA. The model also contains a notification that tells the MA to contact the controller and download new configuration. module: lmap-control +--rw lmap-control Oslebo Expires April 30, 2015 [Page 3] Internet-Draft LMAP Control Data Model October 2014 +--rw tasks | +--rw task* [name] | +--rw name string | +--rw registry-entry inet:uri | +--rw role? string | +--rw options | | +--rw option* [name] | | +--rw name string | | +--rw value* string | +--rw suppress-by-default? boolean | +--rw cycle-id? string +--rw channels | +--rw channel* [name] | +--rw name string | +--rw target inet:uri | +--rw credentials string | +--rw interface? leafref +--rw schedules | +--rw schedule* [name] | +--rw name string | +--rw tasks | | +--rw task* [name] | | +--rw name leafref | | +--rw channels | | | +--rw channel* leafref | | +--rw downstream-tasks | | +--rw downstream-task* [schedule] | | +--rw schedule leafref | | +--rw task? leafref | | +--rw outputs | | +--rw output* int32 | +--rw timing? leafref +--rw timings | +--rw timing* [name] | +--rw name string | +--rw (timing-type) | | +--:(periodic) | | | +--rw periodic | | | +--rw interval uint32 | | | +--rw start? yang:date-and-time | | | +--rw end? yang:date-and-time | | +--:(calendar) | | | +--rw calendar | | | +--rw month* month | | | +--rw weekday* weekday | | | +--rw day-of-months* int8 | | | +--rw hour* int8 | | | +--rw minute* int8 Oslebo Expires April 30, 2015 [Page 4] Internet-Draft LMAP Control Data Model October 2014 | | | +--rw second* int8 | | | +--rw timezone-offset? timezone-offset | | | +--rw start? yang:date-and-time | | | +--rw end? yang:date-and-time | | +--:(one-off) | | | +--rw one-off-time yang:date-and-time | | +--:(immediate) | | | +--rw immediate empty | | +--:(startup) | | +--rw startup empty | +--rw random-spread? int32 +--rw log | +--rw log-entry* [agent-id event-time] | +--rw agent-id leafref | +--rw event-time int64 | +--rw code int32 | +--rw description string +--rw measurement-agents +--rw ma* [agent-id] +--rw agent-id yang:uuid +--rw config | +--rw device-id? inet:uri | +--rw credentials string | +--rw group-id? string | +--rw report-id-flag? boolean | +--rw control-channel-failure-threshold? int32 +--rw schedules | +--rw schedule* leafref +--rw suppressions | +--rw enabled? boolean | +--rw stop-ongoing-tasks? boolean | +--rw start? yang:date-and-time | +--rw stop? yang:date-and-time | +--rw tasks | | +--rw task* leafref | +--rw schedules | +--rw schedule* leafref +--rw status-and-capabilities +--rw hardware? string +--rw firmware? string +--rw version? string +--rw interfaces | +--rw interface* leafref +--rw last-measurement? yang:date-and-time +--rw last-report? yang:date-and-time +--rw last-instruction? yang:date-and-time +--rw last-configuration? yang:date-and-time +--rw supported-tasks Oslebo Expires April 30, 2015 [Page 5] Internet-Draft LMAP Control Data Model October 2014 | +--rw supported-task* [name] | +--rw name string | +--rw registry inet:uri | +--rw role? string +--rw conditions +--rw condition* [code] +--rw code string +--rw text? string notifications: +---n update-config 3. YANG module file "lmap-control@2014-10-27.yang module lmap-control { namespace "urn:ietf:params:xml:ns:yang:lmap-control"; prefix "lmap-control"; import ietf-yang-types { prefix "yang"; } import ietf-inet-types { prefix "inet"; } import ietf-interfaces { prefix "if"; } organization "IETF Large-Scale Measurement Platforms Working Group"; contact "WG Web: WG List: Editor: Arne Oslebo "; description "This YANG module defines a data model for the control protocol for Large-Scale Measurement Platforms (LMAP). The information is stored on a LMAP controller and Measurement Agents will pull this information from the controller at predefined intervals."; Oslebo Expires April 30, 2015 [Page 6] Internet-Draft LMAP Control Data Model October 2014 revision 2014-09-09 { description "Initial revision."; reference "RFC XXX: A YANG Data Model for the LMAP control protocol"; } typedef weekday { type enumeration { enum sunday { description "Sunday of the week"; } enum monday { description "Monday of the week"; } enum tuesday { description "Tuesday of the week"; } enum wednesday { description "Wednesday of the week"; } enum thursday { description "Thursday of the week"; } enum friday { description "Friday of the week"; } enum saturdary { description "Saturday of the week"; } } description "A type modeling the weekdays in the Greco-Roman tradition."; } typedef month { type enumeration { enum january { description "January of the Julian and Gregorian calendar"; } Oslebo Expires April 30, 2015 [Page 7] Internet-Draft LMAP Control Data Model October 2014 enum february { description "February of the Julian and Gregorian calendar"; } enum march { description "March of the Julian and Gregorian calendar"; } enum april { description "April of the Julian and Gregorian calendar"; } enum may { description "May of the Julian and Gregorian calendar"; } enum june { description "June of the Julian and Gregorian calendar"; } enum july { description "July of the Julian and Gregorian calendar"; } enum august { description "August of the Julian and Gregorian calendar"; } enum september { description "September of the Julian and Gregorian calendar"; } enum october { description "October of the Julian and Gregorian calendar"; } enum november { description "November of the Julian and Gregorian calendar"; } enum december { description "December of the Julian and Gregorian calendar"; } } description "A type modeling the month in the Julian and Gregorian tradition."; Oslebo Expires April 30, 2015 [Page 8] Internet-Draft LMAP Control Data Model October 2014 } typedef timezone-offset { type string { pattern "Z|[\+\-]\d{2}:\d{2}"; } description "A timezone-offset as it is use in the yang:date-and-time type. The value Z is equivalent to +00:00. The value -00:00 indicates and unknown time-offset."; } grouping timing-start-end-grouping { description "A grouping that provides start and end times for timing objects."; leaf start { type yang:date-and-time; description "The date and time when the timing object starts to create triggers."; } leaf end { type yang:date-and-time; description "The date and time when the timing object stops to create triggers. It is generally a good idea to always configure an end time and to refresh the configuration of timing object as needed to ensure that agents that loose connectivity to their controller do not continue their tasks forever."; } } container lmap-control { description "LMAP Control configuration"; container tasks { description "Task configuration"; list task { key "name"; description "List of available tasks."; leaf name { type string; mandatory "true"; description "The unique name of the task."; Oslebo Expires April 30, 2015 [Page 9] Internet-Draft LMAP Control Data Model October 2014 } leaf registry-entry { type inet:uri; mandatory "true"; description "Registry URI identifying the task."; } leaf role { type string; description "Measurement Agent role."; } container options { description "Configuration of options passed to the task."; list option { key "name"; description "List of options."; leaf name { type string; description "Option name."; } leaf-list value { type string; description "Option value."; } } } leaf suppress-by-default { type boolean; default "true"; description "Indicates the behavior of the default suppress instruction for this task. If FALSE then the Task will not be suppressed."; } leaf cycle-id { type string; description "Measurement Cycle ID that can be used to easily identify a set of measurement results. The ID should be incremented or changed when a task option is changed so that two sets of results can no longer be directly compared."; } Oslebo Expires April 30, 2015 [Page 10] Internet-Draft LMAP Control Data Model October 2014 } } container channels { description "Channel configuration"; list channel { key "name"; description "The list of available channels"; leaf name { type string; description "The unique name of the channel"; } leaf target { type inet:uri; mandatory "true"; description "The remote endpoint of the channel."; } leaf credentials { type string; mandatory "true"; description "The security credentials to establish a secure channel."; } leaf interface { type leafref { path "/if:interfaces/if:interface/if:name"; } description "Name of interface to use when MA has multiple interfaces."; } } } container schedules { description "Schedules configuration"; list schedule { key "name"; description "The list of available schedules."; leaf name { type string; description "The unique name of the schedule."; Oslebo Expires April 30, 2015 [Page 11] Internet-Draft LMAP Control Data Model October 2014 } container tasks { description "The configuration of tasks that are executed as part of this schedule."; list task { key "name"; description "The list of the tasks."; leaf name { type leafref { path "/lmap-control/tasks/task/name"; } description "The reference to a named task that will be executed"; } container channels { description "Configuration of channels used by the task."; leaf-list channel { type leafref { path "/lmap-control/channels/channel/name"; } description "List of channels used by the task."; } } container downstream-tasks { description "Configuration of downstream tasks. The output from this task is sendt to the selected task."; list downstream-task { key "schedule"; description ""; leaf schedule { type leafref { path "/lmap-control/schedules/schedule/name"; } description "Name of downstream schedule."; } leaf task { type leafref { path "/lmap-control/schedules/" + "schedule[name=current()/../schedule]/" + "tasks/task/name"; Oslebo Expires April 30, 2015 [Page 12] Internet-Draft LMAP Control Data Model October 2014 } description "Name of downstream task that is part of the above downstream schedule."; } container outputs { description "Configuration of task outputs"; leaf-list output { type int32; description "List of task outputs that will be sendt to this downstream task."; } } } } } } leaf timing { type leafref { path "/lmap-control/timings/timing/name"; } description "The timing of the schedule."; } } } container timings { description "Configuration of LMAP timings. Implementations may be forced to delay acting upon triggers in the face of local constraints. A task triggered therefore not rely on the accuracy provided by the scheduler implementation."; list timing { key "name"; description "The list of timings configured on the LMAP agent."; leaf name { type string; description "The unique name of a timing."; } choice timing-type { mandatory "true"; description "Different types of timing objects are handled by different branches of this choices."; Oslebo Expires April 30, 2015 [Page 13] Internet-Draft LMAP Control Data Model October 2014 case periodic { container periodic { description "A periodic timing object triggers periodically driven by a regular interval."; leaf interval { type uint32; units "milliseconds"; mandatory "true"; description "The number of milliseconds between two triggers generated by this periodic timing object. The execution system must not generate triggers for periodic timing objects that have a interval value of 0. A timing object with an interval of 0 milliseconds will therefore never trigger."; } uses timing-start-end-grouping; } } case calendar { container calendar { description "A calendar timing object trigger based on the current calendar date and time."; leaf-list month { type month; description "A month at which this calendar timing will trigger."; } leaf-list weekday { type weekday; description "A weekday at which this calendar timing will trigger."; } leaf-list day-of-months { type int8 { range "-31..-1 | 1..31"; } description "A day in the months at which this calendar timing will trigger. Negative numbers indicate days counted backwards from the end of the months."; } leaf-list hour { type int8 { Oslebo Expires April 30, 2015 [Page 14] Internet-Draft LMAP Control Data Model October 2014 range "0..23"; } description "An hour at which this calendar timing will trigger."; } leaf-list minute { type int8 { range "0..59"; } description "A minute at which this calendar timing will trigger."; } leaf-list second { type int8 { range "0..59"; } description "A second at which this calendar timing will trigger."; } leaf timezone-offset { type timezone-offset; description "The timezone in which this calendar timing object will be evaluated."; } uses timing-start-end-grouping; } } case one-off { leaf one-off-time { type yang:date-and-time; mandatory "true"; description "This one-off timing object triggers once at the configured one-off-time."; } } case immediate { leaf immediate { type empty; mandatory "true"; description "This immediate timing object triggers immediately when it is configured."; } Oslebo Expires April 30, 2015 [Page 15] Internet-Draft LMAP Control Data Model October 2014 } case startup { leaf startup { type empty; mandatory "true"; description "This startup timing object triggers whenever the LMAP agent (re)starts."; } } } leaf random-spread { type int32; units "milliseconds"; description "This optional leaf adds a random spread to the computation of the trigger."; } } } container log { description ""; list log-entry { key "agent-id event-time"; description ""; leaf agent-id { type leafref { path "/lmap-control/measurement-agents/ma/agent-id"; } description ""; } leaf event-time { type int64; description "Timestamp (number of ms since January 1, 1970, 00:00:00 GMT) of the log event"; } leaf code { type int32; mandatory "true"; description ""; } leaf description { type string; Oslebo Expires April 30, 2015 [Page 16] Internet-Draft LMAP Control Data Model October 2014 mandatory "true"; description ""; } } } container measurement-agents { description "Configuration of Measurement Agents."; list ma { key "agent-id"; description "List of Mesurement Agents that are controlled by a controller."; leaf agent-id { type yang:uuid; mandatory "true"; description "The unique ID of the MA"; } container config { description "Configuration of a Measurement Agent."; leaf device-id { type inet:uri; description "Optional device ID that can be used to identify the MA before an agent ID is assigned."; } leaf credentials { type string; mandatory "true"; description "The credentials of the agent."; } leaf group-id { type string; description "Optional group ID of the agent"; } leaf report-id-flag { type boolean; default "false"; description "If true then the agent ID will be reported to the collectors."; } leaf control-channel-failure-threshold { Oslebo Expires April 30, 2015 [Page 17] Internet-Draft LMAP Control Data Model October 2014 type int32; description ""; } } container schedules { description "Configuration of active schedules for this MA."; leaf-list schedule { type leafref { path "/lmap-control/schedules/schedule/name"; } description "List of active schedules."; } } container suppressions { description "Configuration of suppressions"; leaf enabled { type boolean; default "false"; description "Setting this to true will suppress all tasks where suppress-by-default is true."; } leaf stop-ongoing-tasks { type boolean; default "false"; description "Setting this to true will terminate all running tasks when enabled is also set to true."; } leaf start { type yang:date-and-time; description "The date and time when suppression should start. If not present then suppression will start immediately."; } leaf stop { type yang:date-and-time; description "The date and time when suppression should stop. If not present the suppression will continue until 'enabled' is set to false."; } container tasks { Oslebo Expires April 30, 2015 [Page 18] Internet-Draft LMAP Control Data Model October 2014 description "Configuration of tasks that will be suppressed."; leaf-list task { type leafref { path "/lmap-control/tasks/task/name"; } description "The list of tasks that will be suppressed. If the list is empty, then all tasks will be suppressed."; } } container schedules { description "Configuration of schedules that will be suppressed."; leaf-list schedule { type leafref { path "/lmap-control/schedules/schedule/name"; } description "The list of schedules that will be suppressed. If the list is empyt, then all schedules will be suppressed."; } } } container status-and-capabilities { description "Operational status and capabilities of the measurement agent."; leaf hardware { type string; default "true"; description "A short description of the hardware that the measurement agent is running on."; } leaf firmware { type string; description "The firmware version that the measurement agent is running on"; } leaf version { type string; description "The version number of the measurement agent software."; } Oslebo Expires April 30, 2015 [Page 19] Internet-Draft LMAP Control Data Model October 2014 container interfaces { description "Interfaces available for measurements."; leaf-list interface { type leafref { path "/if:interfaces/if:interface/if:name"; } description "List of interfaces"; } } leaf last-measurement { type yang:date-and-time; description "The date and time of the last performed measurement task."; } leaf last-report { type yang:date-and-time; description "The date and time of the last reporting task."; } leaf last-instruction { type yang:date-and-time; description "The date and time for when the measurement agent last received new instructions."; } leaf last-configuration { type yang:date-and-time; description "The date and time for when the measurement agent last received new configuration data."; } container supported-tasks { description "Supported tasks."; list supported-task { key "name"; description "The list of tasks supported by the measurement agent."; leaf name { type string; description "The name of the supported task."; } leaf registry { Oslebo Expires April 30, 2015 [Page 20] Internet-Draft LMAP Control Data Model October 2014 type inet:uri; mandatory "true"; description "The registry entry of the supported task."; } leaf role { type string; description "The role of the measurement agent in the in the supported task."; } } } container conditions { description ""; list condition { key "code"; description ""; leaf code { type string; description ""; } leaf text { type string; description ""; } } } } } } } notification update-config { description "Notification telling the MA to contact the controller and download new configuration."; } } Oslebo Expires April 30, 2015 [Page 21] Internet-Draft LMAP Control Data Model October 2014 4. Security Considerations TBD 5. Acknowledgements Some parts of the YANG model was copied from [I-D.schoenw-lmap-yang]. 6. Normative References [I-D.ietf-lmap-framework] Eardley, P., Morton, A., Bagnulo, M., Burbridge, T., Aitken, P., and A. Akhter, "A framework for large-scale measurement platforms (LMAP)", draft-ietf-lmap- framework-08 (work in progress), August 2014. [I-D.ietf-netconf-restconf] Bierman, A., Bjorklund, M., Watsen, K., and R. Fernando, "RESTCONF Protocol", draft-ietf-netconf-restconf-01 (work in progress), July 2014. [I-D.schoenw-lmap-yang] Schoenwaelder, J. and V. Bajpai, "A YANG Data Model for LMAP Measurement Agents", draft-schoenw-lmap-yang-01 (work in progress), September 2014. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Appendix A. Open issues The traditional usage of both NETCONF and RESTCONF is to push configuration to the managed agents. Using the proposal described in this draft the operator will push the configuration to the LMAP controller, but the MAs will pull the configuration from the controller. At the interim meeting in Dublin September 15 some concern was raised for using RESTCONF in a scenario like this. The question was posted to the NETCONF mailing list and one answer said that the preferred way would be to use the call-home strategy of TLS. The reason for this is to preserve the direction of the authentication mechanisms. So far it has been decided not to include any call-home functionality in RESTCONF, only in NETCONF. Appendix B. Example configuration Oslebo Expires April 30, 2015 [Page 22] Internet-Draft LMAP Control Data Model October 2014 Configuration urn:..:configuration Report urn:..:report Ping urn:ping Control channel http://www.example.com:5000 Report channel http://www.example.com:5001 Configuration Configuration Control channel Hourly Ping Ping Oslebo Expires April 30, 2015 [Page 23] Internet-Draft LMAP Control Data Model October 2014 Report daily Report 1 Hourly Report daily Report Report channel Daily Hourly 60000 Daily 1440000 00000000-0000-0000-0000-000000000001 Device ID 1 Oslebo Expires April 30, 2015 [Page 24] Internet-Draft LMAP Control Data Model October 2014 1 5 Configuration 00000000-0000-0000-0000-000000000002 Device ID 2 1 5 Configuration Ping Appendix C. RESTCONF queries C.1. Get configuration - XML format This example shows how a MA can retrieve the configuration information from the controller in XML format. Note that some lines are wrapped for display purposes only. GET /restconf/data/lmap-control:lmap-control/measurement-agents/ ma=00000000-0000-0000-0000-000000000001/config HTTP/1.1 Host: 127.0.0.1:5000 Accept: application/yang.data+xml, application/yang.errors+xml The server might respond as follows. Oslebo Expires April 30, 2015 [Page 25] Internet-Draft LMAP Control Data Model October 2014 HTTP/1.0 200 OK Content-Type: application/yang.data+xml Server: example-server Date: Fri, 12 Sep 2014 11:56:42 GMT 1 C.2. Get schedules - JSON format This example shows how a MA can retrieve a list of active schedules from the controller in JSON format. GET /restconf/data/lmap-control:lmap-control/measurement-agents/ ma=00000000-0000-0000-0000-000000000002/schedules HTTP/1.1 Host: 127.0.0.1:5000 Accept: application/yang.data+json, application/yang.errors+json The server might respond as follows. HTTP/1.0 200 OK Content-Type: application/yang.data+json Server: example-server Date: Fri, 12 Sep 2014 12:14:15 GMT { "schedules": { "schedule": [ "Configuration", "Ping" ] } } Author's Address Arne Oslebo UNINETT Email: arne.oslebo@uninett.no Oslebo Expires April 30, 2015 [Page 26]