[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

NETMOD Working Group                                              Q. Sun
Internet-Draft                                                 I. Farrer
Intended status: Standards Track                     Deutsche Telekom AG
Expires: September 10, 2015                                March 9, 2015


                A YANG Data Model for Transferring Files
                 draft-sf-netmod-file-transfer-yang-00

Abstract

   This document defines a YANG data model for the transfer of files
   between devices.  The data model includes operation data and state
   data.

Requirements Language

   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].

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 September 10, 2015.

Copyright Notice

   Copyright (c) 2015 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



Sun & Farrer           Expires September 10, 2015               [Page 1]


Internet-Draft             File Transfer YANG                 March 2015


   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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   2
       1.1.1.  Requirements Notations  . . . . . . . . . . . . . . .   2
       1.1.2.  NETCONF Terms . . . . . . . . . . . . . . . . . . . .   3
       1.1.3.  YANG Terms  . . . . . . . . . . . . . . . . . . . . .   3
       1.1.4.  Tree Diagrams . . . . . . . . . . . . . . . . . . . .   3
   2.  Objectives  . . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  File Transfer YANG Tree Diagrams  . . . . . . . . . . . . . .   4
     3.1.  File Transfer State subtree . . . . . . . . . . . . . . .   4
     3.2.  File Transfer RPCs  . . . . . . . . . . . . . . . . . . .   5
   4.  File Transfer YANG Model  . . . . . . . . . . . . . . . . . .   6
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  11
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  12
   7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  12
   8.  Normative References  . . . . . . . . . . . . . . . . . . . .  12
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  13

1.  Introduction

   This document defines a YANG [RFC6020] data model for the transfer of
   files between devices.

   The model augments the state YANG model for System Management
   [RFC7317] to query the status of the file transfer process and the
   downloaded files.  It defines new RPCs, enabling the NETCONF client
   to instruct the NETCONF server to tranfer a file.

   This YANG model can be used to configure a device, to upload or
   download files to a remote host.  The model enables the operator to
   easily manage the content on a device via Netconf.

1.1.  Terminology

1.1.1.  Requirements Notations

   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].






Sun & Farrer           Expires September 10, 2015               [Page 2]


Internet-Draft             File Transfer YANG                 March 2015


1.1.2.  NETCONF Terms

   The following terms are defined in [RFC6241] and are not redefined
   here:

   o  Client

   o  Server

   o  Remote Procedure Call (RPC)

   o  Operation

1.1.3.  YANG Terms

   The following terms are defined in [RFC6020] and are not redefined
   here:

   o  Data node

   o  Module

   o  Namespace

   o  YANG

1.1.4.  Tree Diagrams

   A simplified graphical representation of the data model is provided
   in this document.  The meaning of the symbols in these diagrams are
   as follows:

   o  Brackets "[" and "]" enclose list keys.

   o  Abbreviations before data node names: "rw" means configuration
      data (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.






Sun & Farrer           Expires September 10, 2015               [Page 3]


Internet-Draft             File Transfer YANG                 March 2015


2.  Objectives

   This document defines a YANG data model that can be used to manage
   file transfer between devices.  In order to collect and store the
   status of the transfer process and files, the model augments the
   state subtree of the System Management YANG model [RFC7317].

   The model defines a new RPC, "transfer".  The RPC provides the server
   with the action (upload/download), the URI of the target file, the
   credentials parameters and some other information about failover.
   The server will respond to the RPC with the index to find the file.

   The basic procedure is that the client instructs the server to
   transfer a specific file to/from the provided destination.  The
   client can then retrieve the state of the transfer operation.

3.  File Transfer YANG Tree Diagrams

3.1.  File Transfer State subtree

   This section describes the state data model for file transfer, which
   augments the system-state subtree:


   augment /sys:system-state:
      +--ro file-transfer-state
         +--ro file-transfered*
            +--ro index                uint32
            +--ro file-name            string
            +--ro remote-file-path     inet:uri
            +--ro local-file-path      inet:uri
            +--ro credential-method?   enumeration
            +--ro transfer-status
            |  +--ro status            enumeration
            |  +--ro status-msg?       string
            |  +--ro progress          percent
            +--ro retried-times?       uint8


                    Figure 1: File Transfer State Tree

   o  remote-file-path: a URI for the remote file path.  This can be a
      URI of type HTTP/HTTPS/FTP/SCP, depending on the protocol which is
      being used for the transfer.

   o  local-file-path: A URI for the local file path.  This is a URI of
      type file.




Sun & Farrer           Expires September 10, 2015               [Page 4]


Internet-Draft             File Transfer YANG                 March 2015


   o  credential-method: indicates the method used for supplying
      credentials for the transfer.

   o  transfer-status: The status for the downloading/uploading.

3.2.  File Transfer RPCs

   This section describes the Remote Procedure Call data model, which is
   used to instruct the server to transfer a specific file:

   rpcs:
      +---x transfer
         +---w input
         |  +---w action                      enumeration
         |  +---w file-name?                  string
         |  +---w local-file-path             inet:uri
         |  +---w remote-file-path            inet:uri
         |  +---w (trans-method)
         |  |  +--:(scp)
         |  |  |  +---w scp! {transfer-scp}?
         |  |  +--:(ftp)
         |  |  |  +---w ftp! {transfer-ftp}?
         |  |  +--:(http)
         |  |  |  +---w http! {transfer-http}?
         |  |  +--:(https)
         |  |     +---w https! {transfer-https}?
         |  +---w (credentials)?
         |  |  +--:(password)
         |  |  |  +---w password!
         |  |  |     +---w password           string
         |  |  +--:(certificate)
         |  |  |  +---w certificate!
         |  |  |     +---w local-path         inet:uri
         |  |  +--:(ssh-key)
         |  |     +---w ssh-key!
         |  |        +---w local-path         inet:uri
         |  +---w credential-valid-time?      lifetime
         |  +---w md5-checksum?               string
         |  +---w timeframe?                  uint32
         |  +---w retry-times?                uint8
         |  +---w retry-interval?             uint32
         |  +---w retry-interval-increment?   percent
         +--ro output
            +--ro index    uint32


                     Figure 2: File Transfer RPC Tree




Sun & Farrer           Expires September 10, 2015               [Page 5]


Internet-Draft             File Transfer YANG                 March 2015


   o  action: Specifies the transfer is "upload" or "download".

   o  remote-file-path: A URI for the remote file path.  This can be a
      URI of type HTTP/HTTPS/FTP/SCP, depending on the protocol which is
      being used for the transfer.  The transfer protocol is specified
      in the choice of 'trans-method'.

   o  local-file-path: a URI for the local file path.  This MUST be a
      URI of type file.

   o  trans-method: Specifies the method used for file transfer.  This
      is necessary as different transfer methods require different
      formats of URI.

   o  credential: Specifies the credentials method used for the
      transfer.

   o  credential-valid-time: Indicates the valid time for authentication
      of the current connection.

   o  output: The server sends back the index of the current transfer
      process, which can be used by the client to collect information of
      that transferring procedure.

4.  File Transfer YANG Model

   This module imports typedefs from [RFC6991] and augments to the
   system-state in [RFC7317].

<CODE BEGINS> file "ietf-file-transfer@2015-03-09.yang"
module "file-transfer" {

        namespace "urn:ietf:params:xml:ns:yang:file-trans";
        prefix "ft";

        import "ietf-system" {
                prefix "sys";
        }
        import "ietf-inet-types" {
                prefix "inet";
        }
        description "File transfer YANG model";
        organization "NETMOD Working Group";
        contact
        "qui.sun@external.telekom.de
         ian.farrer@telekom.de
        ";
    revision "2015-03-09" {



Sun & Farrer           Expires September 10, 2015               [Page 6]


Internet-Draft             File Transfer YANG                 March 2015


        description
            "Initial version for file transfer YANG model.
             This model can be used for file transfering and uploading.
            ";
    }

        feature "transfer-scp" {
                description "Indicate the transfer is through scp";
        }
        feature "transfer-ftp" {
                description "Indicate the transfer is through ftp";
        }
        feature "transfer-http" {
                description "Indicate the transfer is through http";
        }
        feature "transfer-https" {
                description "Indicate the transfer is through https";
        }

    /* typedefs */
        typedef "percent" {
                type "uint8" {
                        range "0 .. 100";
                }
        }
    typedef "lifetime" {
        type uint32;
        units seconds;
    }

    /* augments */
        augment "/sys:system-state" {
                container "file-transfer-state" {
            config false;
                        list "file-transfered" {
                                leaf "index" {
                                        type "uint32";
                    mandatory true;
                                }
                                leaf "file-name" {
                                        type "string";
                    mandatory true;
                                }
                                leaf "remote-file-path" {
                                        type "inet:uri";
                    mandatory true;
                    description
                      "A URI for the remote file path. This can be a URI of



Sun & Farrer           Expires September 10, 2015               [Page 7]


Internet-Draft             File Transfer YANG                 March 2015


                       type HTTP/HTTPS/FTP/SCP, depending on the protocol
                       which is being used for the transfer.  The transfer protocol
                       is indicated through the URI. ";
                                }
                                leaf "local-file-path" {
                                        type "inet:uri";
                    mandatory true;
                    description
                      "A URI for the local file path. This is a URI of type file. ";
                                }
                                leaf "credential-method" {
                    type enumeration {
                        enum password;
                        enum certificate;
                        enum ssh-key;
                    }
                                }
                container "transfer-status" {
                    config false;
                    leaf status {
                        type enumeration {
                            enum planned;
                            enum in-progress;
                            enum transfer-failed;
                            enum md5check-failed;
                            enum verification-failed;
                            enum done;
                        }
                    mandatory true;
                    }
                    leaf status-msg {
                        type string;
                        description "Additional system messages.";
                    }
                    leaf progress {
                        when "../status = 'in-progress'";
                        type percent;
                        mandatory true;
                    }
                }
                leaf retried-times {
                    type uint8;
                }
                        }
                }
        }
    rpc transfer {
        input {



Sun & Farrer           Expires September 10, 2015               [Page 8]


Internet-Draft             File Transfer YANG                 March 2015


            leaf action {
                mandatory true;
                type enumeration {
                    enum upload {
                        description
                            "Specify the upload action. The server sends
                             the file identified by the local-file-path
                             to the URI identified by the remote-file-path.";
                    }
                    enum download {
                        description
                            "Specify the download action. The server retrives
                            the file identified by the remote-file-path
                            to the URI identified by the local-file-path.";
                    }
                }
            }
            leaf file-name {
                type string;
            }
            leaf local-file-path {
                type inet:uri;
                mandatory true;
                description
                    "A URI for the local file path. This MUST be a URI
                    of type file.
                    ";
            }
            leaf remote-file-path {
                type inet:uri;
                mandatory true;
                description
                  "A URI for the remote file path. This can be a URI of
                   type HTTP/HTTPS/FTP/SCP, depending on the protocol
                   which is being used for the transfer. The transfer
                   protocol is specified in the choice of 'trans-method'.";
            }
                        choice "trans-method" {
                mandatory true;
                case "scp" {
                                    container "scp" {
                                        presence "true";
                        if-feature "transfer-scp";
                                    }
                }
                case "ftp" {
                                    container "ftp" {
                                            presence "true";



Sun & Farrer           Expires September 10, 2015               [Page 9]


Internet-Draft             File Transfer YANG                 March 2015


                        if-feature "transfer-ftp";
                                    }
                }
                                case "http" {
                    container "http" {
                                            presence "true";
                        if-feature "transfer-http";
                    }
                }
                case "https" {
                                    container "https" {
                                            presence "true";
                        if-feature "transfer-https";
                                    }
                }
            }
                        choice "credentials" {
                                case "password" {
                    container "password" {
                        presence true;
                        leaf password {
                            type string;
                            mandatory true;
                        }
                    }
                }
                case "certificate" {
                    container "certificate" {
                        presence "true";
                        leaf local-path {
                            type inet:uri;
                            mandatory true;
                        }
                    }
                }
                case "ssh-key" {
                    container "ssh-key" {
                        presence "true";
                        leaf local-path {
                            type inet:uri;
                            mandatory true;
                        }
                    }
                }
                        }
            leaf credential-valid-time {
                type lifetime;
                description



Sun & Farrer           Expires September 10, 2015              [Page 10]


Internet-Draft             File Transfer YANG                 March 2015


                    "The valid duration for the credential method
                     above.";
            }
            leaf md5-checksum {
                type string;
                description
                    "MD5 checking is optional.";
            }
            leaf timeframe {
                type uint32;
            }
            leaf retry-times {
                type uint8;
            }
            leaf retry-interval {
                type uint32;
            }
            leaf retry-interval-increment {
                type percent;
            }
        }
        output {
            leaf index {
                type uint32;
                mandatory true;
            }
            description
                " When the server receives the RPC request of
                  'transfer', if the transfering process starts
                  successfully, the server MUST assign an index
                  to that process and reply it to the client as
                  an output parameter.
                ";
        }
    }
}



<CODE ENDS>

5.  Security Considerations

   The YANG module defined in this memo is designed to be accessed via
   the NETCONF protocol [RFC6241].  The lowest NETCONF layer is the
   secure transport layer and the mandatory to implement secure
   transport is SSH [RFC6242].  The NETCONF access control model
   [RFC6536] provides the means to restrict access for particular



Sun & Farrer           Expires September 10, 2015              [Page 11]


Internet-Draft             File Transfer YANG                 March 2015


   NETCONF users to a pre-configured subset of all available NETCONF
   protocol operations and content.

   There are a number of data nodes defined in this YANG module which
   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:

      subtrees and data nodes and state why they are sensitive

   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:

      subtrees and data nodes and state why they are sensitive

   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:

      subtrees and data nodes and state why they are sensitive

6.  IANA Considerations

   TBD

7.  Acknowledgements

   The authors would like to thank Calvin Cheng for his valuable inputs.

8.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC6020]  Bjorklund, M., "YANG - A Data Modeling Language for the
              Network Configuration Protocol (NETCONF)", RFC 6020,
              October 2010.

   [RFC6021]  Schoenwaelder, J., "Common YANG Data Types", RFC 6021,
              October 2010.




Sun & Farrer           Expires September 10, 2015              [Page 12]


Internet-Draft             File Transfer YANG                 March 2015


   [RFC6087]  Bierman, A., "Guidelines for Authors and Reviewers of YANG
              Data Model Documents", RFC 6087, January 2011.

   [RFC6241]  Enns, R., Bjorklund, M., Schoenwaelder, J., and A.
              Bierman, "Network Configuration Protocol (NETCONF)", RFC
              6241, June 2011.

   [RFC6242]  Wasserman, M., "Using the NETCONF Protocol over Secure
              Shell (SSH)", RFC 6242, June 2011.

   [RFC6536]  Bierman, A. and M. Bjorklund, "Network Configuration
              Protocol (NETCONF) Access Control Model", RFC 6536, March
              2012.

   [RFC6991]  Schoenwaelder, J., "Common YANG Data Types", RFC 6991,
              July 2013.

   [RFC7317]  Bierman, A. and M. Bjorklund, "A YANG Data Model for
              System Management", RFC 7317, August 2014.

Authors' Addresses

   Qi Sun
   Deutsche Telekom AG
   CTO-ATI,Landgrabenweg 151
   Bonn, NRW  53227
   Germany

   Email: qui.sun@external.telekom.de


   Ian Farrer
   Deutsche Telekom AG
   CTO-ATI,Landgrabenweg 151
   Bonn, NRW  53227
   Germany

   Email: ian.farrer@telekom.de













Sun & Farrer           Expires September 10, 2015              [Page 13]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/