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]