Network Working Group                                    R. Enns, Editor
Internet-Draft                                          Juniper Networks
Expires: August 13, 2003                               February 12, 2003


                     XMLCONF Configuration Protocol
                       draft-enns-xmlconf-spec-00

Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as
   Internet-Drafts.

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

   The list of current Internet-Drafts can be accessed at http://
   www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on August 13, 2003.

Copyright Notice

   Copyright (C) The Internet Society (2003).  All Rights Reserved.

Abstract

   There is a need for standardized mechanisms to manipulate, install,
   edit, and delete the configuration of a network device.  In addition,
   there is a need to retrieve device state information and receive
   asynchronous device state messages in a manner consistent with the
   configuration mechanisms.  There is great interest in using an XML
   based data encoding because a significant set of tools for
   manipulating ASCII text and XML encoded data already exists.








Enns, Editor            Expires August 13, 2003                 [Page 1]

Internet-Draft              XMLCONF Protocol               February 2003


Table of Contents

   1.    Introduction . . . . . . . . . . . . . . . . . . . . . . . .  5
   1.1   Protocol Overview  . . . . . . . . . . . . . . . . . . . . .  6
   1.1.1 Capabilities . . . . . . . . . . . . . . . . . . . . . . . .  7
   1.2   Separation of Configuration and State Data . . . . . . . . .  7
   1.3   Executive Commands . . . . . . . . . . . . . . . . . . . . .  8
   1.4   Terminology  . . . . . . . . . . . . . . . . . . . . . . . .  8
   1.4.1 Configuration Session  . . . . . . . . . . . . . . . . . . .  8
   2.    Transport Protocol Requirements  . . . . . . . . . . . . . .  9
   2.1   Connection-based . . . . . . . . . . . . . . . . . . . . . .  9
   2.2   Security and Privacy . . . . . . . . . . . . . . . . . . . .  9
   2.3   Authentication . . . . . . . . . . . . . . . . . . . . . . .  9
   2.4   Channels . . . . . . . . . . . . . . . . . . . . . . . . . . 10
   2.4.1 Management Channel . . . . . . . . . . . . . . . . . . . . . 10
   2.4.2 Operation Channel  . . . . . . . . . . . . . . . . . . . . . 11
   2.4.3 Notification Channel . . . . . . . . . . . . . . . . . . . . 11
   3.    RPC Model  . . . . . . . . . . . . . . . . . . . . . . . . . 12
   3.1   Namespace  . . . . . . . . . . . . . . . . . . . . . . . . . 12
   3.2   <rpc>  . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
   3.3   <rpc-reply>  . . . . . . . . . . . . . . . . . . . . . . . . 13
   3.4   <rpc-abort>  . . . . . . . . . . . . . . . . . . . . . . . . 14
   3.5   <rpc-abort-reply>  . . . . . . . . . . . . . . . . . . . . . 14
   3.6   <rpc-error>  . . . . . . . . . . . . . . . . . . . . . . . . 14
   3.7   <ok> . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
   3.8   <rpc-progress> . . . . . . . . . . . . . . . . . . . . . . . 15
   3.9   Pipelining . . . . . . . . . . . . . . . . . . . . . . . . . 16
   4.    Configuration Model  . . . . . . . . . . . . . . . . . . . . 17
   4.1   Configuration Datastores . . . . . . . . . . . . . . . . . . 17
   5.    Protocol Operations  . . . . . . . . . . . . . . . . . . . . 18
   5.1   <get-config> . . . . . . . . . . . . . . . . . . . . . . . . 18
   5.2   <edit-config>  . . . . . . . . . . . . . . . . . . . . . . . 21
   5.3   <copy-config>  . . . . . . . . . . . . . . . . . . . . . . . 23
   5.4   <delete-config>  . . . . . . . . . . . . . . . . . . . . . . 25
   5.5   <get-state>  . . . . . . . . . . . . . . . . . . . . . . . . 26
   5.6   <kill-session> . . . . . . . . . . . . . . . . . . . . . . . 27
   6.    Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 29
   6.1   Capabilities Exchange  . . . . . . . . . . . . . . . . . . . 29
   6.2   Writable Running . . . . . . . . . . . . . . . . . . . . . . 30
   6.2.1 Description  . . . . . . . . . . . . . . . . . . . . . . . . 30
   6.2.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 30
   6.2.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 30
   6.2.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 30
   6.2.5 Modifications to Existing Operations . . . . . . . . . . . . 30
   6.3   Candidate Configuration  . . . . . . . . . . . . . . . . . . 31
   6.3.1 Description  . . . . . . . . . . . . . . . . . . . . . . . . 31
   6.3.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 31
   6.3.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 32



Enns, Editor            Expires August 13, 2003                 [Page 2]

Internet-Draft              XMLCONF Protocol               February 2003


   6.3.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 32
   6.3.5 Modifications to Existing Operations . . . . . . . . . . . . 33
   6.4   Validate Capability  . . . . . . . . . . . . . . . . . . . . 35
   6.4.1 Description  . . . . . . . . . . . . . . . . . . . . . . . . 35
   6.4.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 35
   6.4.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 35
   6.4.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 35
   6.5   Distinct Startup . . . . . . . . . . . . . . . . . . . . . . 36
   6.5.1 Description  . . . . . . . . . . . . . . . . . . . . . . . . 36
   6.5.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 36
   6.5.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 36
   6.5.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 37
   6.5.5 Modifications to Existing Operations . . . . . . . . . . . . 37
   6.6   Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
   6.6.1 Description  . . . . . . . . . . . . . . . . . . . . . . . . 37
   6.6.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 38
   6.6.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 38
   6.6.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 38
   6.7   Notifications  . . . . . . . . . . . . . . . . . . . . . . . 40
   6.7.1 Description  . . . . . . . . . . . . . . . . . . . . . . . . 41
   6.7.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 41
   6.7.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 41
   6.7.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 41
   6.8   URL  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
   6.8.1 Description  . . . . . . . . . . . . . . . . . . . . . . . . 43
   6.8.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 43
   6.8.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 43
   6.8.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 43
   6.8.5 Modifications to Existing Operations . . . . . . . . . . . . 43
   7.    XML Usage Guidelines for XMLCONF . . . . . . . . . . . . . . 45
   7.1   Canonical XML  . . . . . . . . . . . . . . . . . . . . . . . 45
   7.2   Additional Restrictions  . . . . . . . . . . . . . . . . . . 46
   7.2.1 Avoid mixed content  . . . . . . . . . . . . . . . . . . . . 46
   7.2.2 No attributes in the default namespace . . . . . . . . . . . 46
   7.2.3 Use container elements for lists . . . . . . . . . . . . . . 47
   7.2.4 Elements and Attributes  . . . . . . . . . . . . . . . . . . 47
   7.2.5 Proper Tag Names . . . . . . . . . . . . . . . . . . . . . . 47
   7.2.6 Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . 48
   8.    BEEP Mapping . . . . . . . . . . . . . . . . . . . . . . . . 50
   8.1   XMLCONF Session Initiation . . . . . . . . . . . . . . . . . 50
   8.2   XMLCONF RPC Execution  . . . . . . . . . . . . . . . . . . . 50
   8.3   XMLCONF <rpc-abort> and <rpc-progress> . . . . . . . . . . . 51
   8.4   XMLCONF Session Teardown . . . . . . . . . . . . . . . . . . 51
   8.5   BEEP Profiles for XMLCONF Channels . . . . . . . . . . . . . 51
   8.5.1 Management Channel Profile . . . . . . . . . . . . . . . . . 51
   8.5.2 Operations Channel Profile . . . . . . . . . . . . . . . . . 53
   8.5.3 Notification Channel Profile . . . . . . . . . . . . . . . . 55
   9.    XML Schema for XMLCONF RPC and Protocol Operations . . . . . 56



Enns, Editor            Expires August 13, 2003                 [Page 3]

Internet-Draft              XMLCONF Protocol               February 2003


   10.   XML Schema for XMLCONF State Data  . . . . . . . . . . . . . 62
   11.   Security Considerations  . . . . . . . . . . . . . . . . . . 65
   12.   Authors and Acknowledgements . . . . . . . . . . . . . . . . 66
         Normative References . . . . . . . . . . . . . . . . . . . . 67
         Informative References . . . . . . . . . . . . . . . . . . . 68
         Author's Address . . . . . . . . . . . . . . . . . . . . . . 68
   A.    Capability Template  . . . . . . . . . . . . . . . . . . . . 69
   A.1   capability-name (template) . . . . . . . . . . . . . . . . . 69
   A.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 69
   A.1.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 69
   A.1.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 69
   A.1.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 69
   A.1.5 Modifications to Existing Operations . . . . . . . . . . . . 69
   A.1.6 Interactions with Other Capabilities . . . . . . . . . . . . 69
   B.    Configuring Multiple Devices with XMLCONF  . . . . . . . . . 70
   B.1   Operations Against Individual Devices  . . . . . . . . . . . 70
   B.1.1 Acquiring the Configuration Lock . . . . . . . . . . . . . . 70
   B.1.2 Loading the Update . . . . . . . . . . . . . . . . . . . . . 71
   B.1.3 Validating the Incoming Configuration  . . . . . . . . . . . 72
   B.1.4 Checkpointing the Running Configuration  . . . . . . . . . . 73
   B.1.5 Changing the Running Configuration . . . . . . . . . . . . . 73
   B.1.6 Testing the New Configuration  . . . . . . . . . . . . . . . 74
   B.1.7 Making the Change Permanent  . . . . . . . . . . . . . . . . 74
   B.1.8 Releasing the Configuration Lock . . . . . . . . . . . . . . 75
   B.2   Operations Against Multiple Devices  . . . . . . . . . . . . 75
         Intellectual Property and Copyright Statements . . . . . . . 77

























Enns, Editor            Expires August 13, 2003                 [Page 4]

Internet-Draft              XMLCONF Protocol               February 2003


1. Introduction

   The XMLCONF protocol defines a simple mechanism through which a
   network device can be managed.  Configuration data, state
   information, and system notifications can be retrieved.  New
   configuration data can be uploaded and manipulated.  The protocol
   allows the device to expose a full, formal, application programming
   interface (API).  Applications can use this simple interface to send
   and receive full and partial configuration data sets.

   This mechanism uses a remote procedure call (RPC) paradigm to define
   a formal API for the device.  A client encodes an RPC in XML [1] and
   sends it to a server using secure, connection-oriented session.  The
   server responds with a reply encoded in XML.  The contents of both
   the request and the response are fully described in XML DTDs and/or
   XML Schemas, allowing both parties to be cognizant of the syntax
   constraints imposed on the exchange.

   One of the key aspects of XMLCONF is an attempt to allow the
   functionality of the API to closely mirror the native functionality
   of the device.  This will reduce implementation costs and allow
   timely access to new features.  In addition, applications will be
   able to access the syntactic and semantic content of the device's
   native user interface.

   XMLCONF allows a client to discover the set of protocol extensions
   supported by the server.  These "capabilities" permit the client to
   adjust its behavior to take advantage of the features exposed by the
   device.  The capability definitions can be easily extended in a
   non-centralized manner.  Standard and vendor-specific capabilities
   can be defined with semantic and syntactic rigor.

   The XMLCONF protocol is a building block in a system of automated
   configuration.  XML is the lingua franca of interchange, providing a
   flexible but fully specified encoding mechanism for hierarchical
   content.  XMLCONF can be used in concert with XML-based
   transformation technologies like XSLT to provide a system for
   automated generation of full and partial configurations.

   The system can query one or more databases for data on networking
   topologies, links, policies, customers, and services.  This data can
   be transformed from a vendor independent data schema into a form that
   is specific to the vendor, product, operating system, and software
   release using one or more XSLT [9] scripts.  The resulting data can
   be passed to the device using the XMLCONF protocol.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this



Enns, Editor            Expires August 13, 2003                 [Page 5]

Internet-Draft              XMLCONF Protocol               February 2003


   document are to be interpreted as described in RFC 2119 [2].

1.1 Protocol Overview

   XMLCONF uses a simple RPC-based mechanism to facilitate communication
   between a client and a server.  The client will be a script or
   application typically running as part of a network manager.  The
   server will be a network device.  The terms device and server are
   used interchangeably in this document, as are client and application.

   XMLCONF can be conceptually partitioned into four layers:

              Layer                      Example
         +-------------+      +-----------------------------+
         |   Content   |      |     Configuration data      |
         +-------------+      +-----------------------------+
                |                           |
         +-------------+      +-----------------------------+
         | Operations  |      | <get-config>, <edit-config> |
         +-------------+      +-----------------------------+
                |                           |
         +-------------+      +-----------------------------+
         |     RPC     |      |    <rpc>, <rpc-reply>       |
         +-------------+      +-----------------------------+
                |                           |
         +-------------+      +-----------------------------+
         |  Transport  |      |   BEEP, SSH, SSL, Console   |
         +-------------+      +-----------------------------+

   The transport layer provides a communication path between client and
   server.  XMLCONF can be layered over any transport that provides a
   set of basic requirements.  Section 2 discusses these requirements
   and Section 8 defines a transport mapping for running XMLCONF over
   BEEP.

   The RPC layer provides a simple, transport-independent framing
   mechanism for encoding RPCs.  Section 3 documents this protocol.

   The operations layer defines a set of base operations invoked as RPC
   methods with XML-encoded parameters.  Section 5 details the list of
   base operations.

   The content layer is outside the scope of this document.  Given the
   current proprietary nature of the configuration data being
   manipulated, the specification of this content will depend on the
   device vendor.  It is expected that a separate effort to specify a
   standard data definition language and standard content will be
   undertaken, independent of this effort.



Enns, Editor            Expires August 13, 2003                 [Page 6]

Internet-Draft              XMLCONF Protocol               February 2003


1.1.1 Capabilities

   An XMLCONF capability is a set of additional functionality
   implemented on top of the base XMLCONF specification.  The capability
   is identified by a URI.  These URIs should follow the guidelines as
   described in Section 6.

   Capabilities augment the base operations of the device, describing
   both additional operations and the content allowed inside operations.
   The client can discover the server's capabilities and use any
   additional operations, parameters, and content defined by those
   capabilities.

   The capability definition may name one or more dependent
   capabilities.  These capabilities must be implemented before the
   first capability can function properly.  To support a capability, the
   server MUST support any capabilities upon which it depends.

   Section 6 defines the capabilities exchange which allows the client
   to discover the server's capabilities.  Section 6 also lists the set
   of capabilities defined in this document.

   Additional capabilities can be defined at any time in external
   documents, allowing the set of capabilities to grow over time.
   Standards bodies may define standardized capabilities and vendors may
   define proprietary ones.  The URI MUST sufficiently distinguish the
   naming authority in order to avoid a naming collision.

1.2 Separation of Configuration and State Data

   The information that can be retrieved from a running system is
   separated into two classes, configuration data and state data.
   Configuration data is the set of writable data that is required to
   get a system from its initial default state into its current state.
   State data is the additional data on a system that isn't
   configuration data such as read-only status information and collected
   statistics.  When performing configuration operations there are a
   number of problems that would arise if state data was included:

   o  Diffs of configuration files would be dominated by irrelevant
      entries such as different statistics.

   o  A command to load the file would contain nonsensical commands such
      as commands to write read-only data.

   o  The configuration file would be too large.

   As a consequence, the XMLCONF protocol recognizes the difference



Enns, Editor            Expires August 13, 2003                 [Page 7]

Internet-Draft              XMLCONF Protocol               February 2003


   between configuration data and state data and provides commands that
   operate on each independently.  For example, the <get-config> command
   will only retrieve configuration data while the <get-state> command
   is used to retrieve state data.

   Note that the XMLCONF protocol is only concerned with information
   required to get the system software into its desired running state.
   Other important persistent data such as user files and databases are
   not treated as configuration data by the XMLCONF protocol.
   Similarly, the collection of configuration files stored on a system
   is not itself included in configuration data (e.g., a directory
   listing of the available configuration files).

   If a local database of user authentication data is stored on the box,
   it is an implementation dependent matter as to whether that is
   included in configuration data.

1.3 Executive Commands

   The XMLCONF protocol also provides for executive commands that
   perform other functions on the system that ease the process of
   configuring the system.  Examples include resetting a line card,
   ping, traceroute, and debugging.

1.4 Terminology

1.4.1 Configuration Session

   The logical connection between a network administrator or network
   configuration application and a network device.  A device will
   support one or more concurrent sessions.  Global configuration
   attributes can potentially be changed during any session, and the
   affects are visible in all sessions.  Session specific attributes
   only affect the session in which they are changed.

















Enns, Editor            Expires August 13, 2003                 [Page 8]

Internet-Draft              XMLCONF Protocol               February 2003


2. Transport Protocol Requirements

   XMLCONF uses an RPC-based communication paradigm.  A client sends a
   series of zero or more RPC request operations, which causes the
   server to respond with a corresponding series of RPC replies.

   The XMLCONF protocol can be layered upon any transport that provides
   the required set of functionality.  It is not bound to any particular
   protocol, but allows a mapping to define how it can be implemented
   over any specific protocol.  This document provides the mapping of
   XMLCONF to the BEEP protocol [7] in Section 8.  Other mappings are
   outside the scope of this document and will be specified in
   associated protocol-mapping documents.

   This section details the characteristics that XMLCONF requires from
   the underlying protocol.

2.1 Connection-based

   XMLCONF is connection-oriented, requiring a persistent connection
   between peers.  This connection must provide reliable, sequenced
   delivery of data.

   XMLCONF connections are long-lived, persisting between protocol
   operations.  This allows the client to make changes to the state of
   the connection that will persist for the lifetime of the connection.
   For example, authentication information specified for a connection
   will remain in effect until the connection is closed.

   In addition, resources requested from the server for a particular
   connection can be automatically released when the connection closes,
   making failure recovery simpler and more robust.  For example, when a
   lock is acquired by a peer, the lock persists until either explicitly
   released or the server is informed that the connection has been
   terminated.  If a connection is terminated while the client holds a
   lock, the server can perform any appropriate recovery.

2.2 Security and Privacy

   XMLCONF connections must provide security and privacy.  XMLCONF
   depends on the underlying protocol for this capability.  An XMLCONF
   peer assumes that an appropriate level of security and privacy are
   provided independent of this document.  For example, connections may
   be encrypted in TLS [4] (or SSH [11]) depending on the underlying
   protocol.

2.3 Authentication




Enns, Editor            Expires August 13, 2003                 [Page 9]

Internet-Draft              XMLCONF Protocol               February 2003


   XMLCONF connections must be authenticated.  The underlying protocol
   is responsible for this authentication.  The peer assumes that the
   connection's authentication information has been validated by the
   underlying protocol using sufficiently trustworthy mechanisms and
   that the peer's entity can be trusted.

   One of the goals of XMLCONF is to provide a programmatic interface to
   the device which closely follows the functionality of the device's
   native interface.  Therefore it is expected that the underlying
   protocol will use existing authentication mechanisms defined by the
   device.  For example, a device that supports RADIUS [5] should use
   RADIUS to authenticate XMLCONF sessions.

   The authentication process should result in an entity whose
   permissions and capabilities are known to the device.  These
   permissions must be enforced during the XMLCONF session.  For
   example, if the native user interface restricts the users from
   changing the network interface configuration, the user should not be
   able to change this configuration data using XMLCONF.

2.4 Channels

   XMLCONF requires two distinct communication channels and an optional
   third channel.

   One channel, called the 'management channel', carries information for
   managing the XMLCONF session.

   The second channel, called the 'operation channel' carries a series
   of RPCs that constitute the real content of the XMLCONF session.

   The third channel, called the 'notification channel' is optional, and
   carries asynchronous notifications.  This channel is only established
   if both parties request it during the initial capabilities exchange
   (see Section 6 for more information).

2.4.1 Management Channel

   The XMLCONF session is considered to start when the management
   channel is opened and ends when this channel is closed.  If the
   operation channel is open when the management channel is closed, it
   should be closed immediately.  Only one management channel can exist
   inside a particular session, although multiple sessions can be opened
   simultaneously.

   The management channel serves three main purposes:

   o  Advertising the capabilities supported by each peer



Enns, Editor            Expires August 13, 2003                [Page 10]

Internet-Draft              XMLCONF Protocol               February 2003


   o  Managing outstanding RPCs on operation channels (aborting them)

   o  Sending progress reports


2.4.1.1 Managing Operation Channel

   Creation of the operation channel is a transport-specific matter.

2.4.1.2 Managing Outstanding RPCs

   The nature of XML data streams prohibits unrelated data from being
   intermingled with normal content.  This implies that an operation
   must be managed by an external data path, to avoid intermixing the
   true content data from the management data.  This is the origin of
   the requirement for multiple channels.

2.4.2 Operation Channel

   The operation channel is used to perform XMLCONF protocol operations
   using the <rpc> and <rpc-reply> tags.  The RPC Model is discussed in
   Section 3.

   The bulk of the work of XMLCONF is performed as RPCs over the
   operation channel.

2.4.3 Notification Channel

   The XMLCONF protocol allows for different notification profiles to be
   used.  A specific profile must be supported by both peers in order
   for the notification mechanism defined in that profile to be used.
   This document specifies a mapping to the Reliable Delivery for Syslog
   messages.

   See Section 6 and RFC 3195 [8] for complete information.
















Enns, Editor            Expires August 13, 2003                [Page 11]

Internet-Draft              XMLCONF Protocol               February 2003


3. RPC Model

   The XMLCONF protocol uses an RPC-based communication model.  XMLCONF
   peers use <rpc> and <rpc-reply> elements to frame protocol requests
   and responses.

   The XMLCONF RPC model requires the use of <rpc> and <rpc-reply>
   elements to provide transport-independent framing of protocol
   messages.

3.1 Namespace

   The <rpc>, <rpc-reply>, <rpc-progress> elements are defined in the
   following namespace:

      http://ietf.org/xmlconf/1.0/base


3.2 <rpc>

   The <rpc> operation is used in both the management and operation
   channels.

   The <rpc> operation has an optional attribute "id".  The "id"
   attribute is an arbitrary string chosen by the sender of the RPC.
   This will commonly encode a monotonically increasing integer.  The
   receiver of the RPC doesn't decode or interpret this string but
   simply saves it to use as an "id" attribute in any resulting
   <rpc-reply>, <rpc-abort-reply> or <rpc-progress> messages.

   For example:

       <rpc id="101">
           <some-content>
               ...
           </some-content>
       </rpc>

   The name and parameters for an RPC are encoded as the contents of the
   <rpc> operation.  The name of the RPC is an element directly inside
   the <rpc> element and any parameters are encoded inside this element.

   This example invokes a method called 'my-own-method' with two
   parameters, "my-first-parameter" with a value of "14" and
   "another-parameter" with a value of "fred":






Enns, Editor            Expires August 13, 2003                [Page 12]

Internet-Draft              XMLCONF Protocol               February 2003


     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <my-own-method xmlns="http://example.net/me/1.0/my-own">
         <my-first-parameter>14</my-first-parameter>
         <another-parameter>fred</another-parameter>
       </my-own-method>
     </rpc>

   This example invokes a "rock-the-house" method with a "zip-code" of
   "27606-0100":

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <rock-the-house xmlns="http://example.net/house/1.0/rock">
         <zip-code>27606-0100</zip-code>
       </rock-the-house>
     </rpc>

   This example invokes the "rock-the-world" method with no parameters:

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <rock-the-world xmlns="http://example.net/house/1.0/rock">
       </rock-the-world>
     </rpc>


3.3 <rpc-reply>

   The <rpc-reply> message is sent on the operations channel in response
   to a <rpc> operation.

   The <rpc-reply> message has an optional attribute "id".  The "id"
   attribute is equal to the "id" attribute of the <rpc> for which this
   is a response.

   The response name and response data are encoded as the contents of
   the <rpc-reply> element.  The name of the reply is an element
   directly inside the <rpc-reply> element and any data is encoded
   inside this element.

   For example:

       <rpc-reply id="101">
           <some-content>
               ...
           </some-content>
       </rpc-reply>






Enns, Editor            Expires August 13, 2003                [Page 13]

Internet-Draft              XMLCONF Protocol               February 2003


3.4 <rpc-abort>

   The <rpc-abort> operation is sent on the management channel by the
   sender of an <rpc> who desires to terminate an operation before
   completion.  The <rpc-abort> operation includes a required attribute
   "id".  The "id" attribute shall be equal to the "id" attribute of the
   <rpc> that should be terminated.

   The <rpc-abort> operation is encoded as an element with no
   subelements or data.  For example:

       <rpc-abort id="102"></rpc-abort>

   An <rpc-abort-reply> message will be immediately sent on the
   management channel.  If the indicated <rpc-reply> was in progress on
   the operations channel, it shall be terminated cleanly by closing all
   open elements.  An <rpc-error> element (see Section 3.6) should be
   added to the <rpc-reply> indicating the operation being aborted.  If
   the <rpc-reply> has not yet begun, it should be sent containing an
   <rpc-error> element.  This must be sent in the proper order if
   multiple <rpc> requests are pending.

   If there is no pending operation matching the "id" attribute, then
   the abort operation completes without error.  The <rpc-abort> message
   can only be generated for <rpc> requests which contain an "id"
   attribute.  If multiple <rpc> requests with the same "id" are
   present, then only the request which was received first by the peer
   will be aborted.

3.5 <rpc-abort-reply>

   The <rpc-abort-reply> message is sent on the management channel in
   response to an <rpc-abort> operation.

   The <rpc-abort-reply> message has a required attribute "id".  The
   "id" attribute is equal to the "id" attribute of the <rpc-abort> for
   which this is a response.

   The <rpc-abort-reply> operation is encoded as an empty element.  For
   example:

       <rpc-abort-reply id="102"></rpc-abort-reply>


3.6 <rpc-error>

   The <rpc-error> element is emitted in <rpc-reply> messages if an
   error occurred during the processing of an <rpc> request.



Enns, Editor            Expires August 13, 2003                [Page 14]

Internet-Draft              XMLCONF Protocol               February 2003


   The <rpc-error> element includes the following information:

   o  tag: The string identifying the error condition.

   o  error-code: The integer identifying the error condition.

   o  severity: The string identifying the error severity, as determined
      by the device.

   o  edit-path: The configuration data that provides the context for
      the command that caused the error.  This may be the empty string
      if the command causing the error is located at the top level of
      the command hierarchy.

   o  statement: The command that caused the error.

   o  message: A string describing the error condition.

   o  action: The action taken by the device in response to this error.


3.7 <ok>

   The <ok> element is emitted in <rpc-reply> messages if no error
   occurred during the processing of an <rpc> request.  For example:

     <rpc-reply xmlns="http://ietf.org/xmlconf/1.0/base">
       <ok></ok>
     </rpc-reply>


3.8 <rpc-progress>

   Some operations may take a long time to process before an <rpc-reply>
   can be generated or may generate an <rpc-reply> that takes a long
   time to transmit.  If the recipient of an <rpc> determines that the
   <rpc-reply> will not be generated and transmitted in less than N
   seconds, then it can send a progress report with the <rpc-progress>
   message.  The number of seconds, N, is implementation-dependent.

   The <rpc-progress> message is sent on the management channel.  It has
   an mandatory attribute "id".  The "id" attribute is equal to the "id"
   attribute of the associated <rpc> on which progress is being
   reported.  The <rpc-progress> message can only be generated for <rpc>
   requests which contain an "id" attribute.

   The <rpc-progress> contains one or more of the optional elements
   <percent-done>, <amount>, and <message>.



Enns, Editor            Expires August 13, 2003                [Page 15]

Internet-Draft              XMLCONF Protocol               February 2003


   The <percent-done> element contains an estimate of the percentage of
   the operation that is complete in terms of real time (i.e., wall
   clock time).

   For example:

       <rpc-progress id="103">
           <percent-done>45</percent-done>
       </rpc-progress>

   The <amount> element contains an absolute quantity indicating an
   amount of work completed.

   For example:

       <rpc-progress id="103">
           <amount>45Kb</amount>
       </rpc-progress>

   The <message> element contains a text message indicating progress on
   the associated <rpc>.

   For example:

       <rpc-progress id="103">
           <message>Connecting...</message>
       </rpc-progress>
       <rpc-progress id="103">
           <message>Connected.</message>
       </rpc-progress>

   Multiple <rpc-progress> messages may be sent for a particular <rpc>.

3.9 Pipelining

   The operations channel is processed serially by the managed device.
   Additional <rpc> requests may be sent before previous ones have been
   completed but they will just be added to the queue for that channel.
   On any given operations channel, the managed device may only send
   responses in the order the requests were received.

   Messages may be received asynchronously on the notification channel.









Enns, Editor            Expires August 13, 2003                [Page 16]

Internet-Draft              XMLCONF Protocol               February 2003


4. Configuration Model

   XMLCONF provides an initial set of operations and a number of
   capabilities that can be used to extend the base.  XMLCONF peers
   exchange device capabilities at session initiation as described in
   Section 6.1.

4.1 Configuration Datastores

   XMLCONF defines the existence of one or more configuration datastores
   and allows configuration operations on these datastores.  A
   configuration datastore is defined as the complete set of
   configuration data that is required to get a device from its initial
   default state into a desired operational state.  The configuration
   datastore does not include state data or executive commands.

   The following configuration datastores are present in the base model.
   Capabilities may define additional configuration datastores.  These
   datastores are only available on devices that advertise the
   capabilities that define them.

   Running: The complete configuration currently active on the network
      device.  There is only one configuration datastore of this type on
      the device, and it is always present.  XMLCONF protocol operations
      refer to this datastore using the <running> element.


























Enns, Editor            Expires August 13, 2003                [Page 17]

Internet-Draft              XMLCONF Protocol               February 2003


5. Protocol Operations

   The XMLCONF protocol provides a small set of low level operations to
   manage device configurations and retrieve device state information.
   The base protocol provides operations to retrieve, configure, copy,
   and delete configuration datastores.  Additional operations are
   provided, based on the capabilities advertised by the device.

   The base protocol includes the following protocol operations:

   o  get-config

   o  edit-config

   o  copy-config

   o  delete-config

   o  get-state

   o  kill-session

   A protocol operation may fail for various reasons, including
   'operation not supported'.  An initiator should not assume that any
   operation will always succeed.  The return values in any RPC reply
   should be checked for error responses.

   The syntax and XML encoding of the protocol operations are formally
   defined in the XML schema in Section 9.  The following sections
   describe the semantics of each protocol operation.

5.1 <get-config>

   Description:

      Retrieve all or part of a specified configuration

   Parameters:

      source: @config-name

         Name of the configuration datastore being queried such as
         <running> or <startup>.

      config: @element-subtree






Enns, Editor            Expires August 13, 2003                [Page 18]

Internet-Draft              XMLCONF Protocol               February 2003


         Specifies the portion(s) of the configuration command subtree
         to retrieve.  The namespace of this configuration should be
         specified as an attribute of this parameter.  If this parameter
         is empty, then the entire configuration will be returned.  If
         the format parameter is equal to 'text' then the contents of
         this parameter are proprietary.

      format: (xml | text)

         Specifies the format of the return text, either 'xml' or
         'text'.  If this parameter contains the value 'xml', then the
         contents of the 'config' parameter are expected to conform to
         the XML Namespace(s) specified in that parameter.  If the value
         is 'text', then the contents of the 'config' parameter are
         proprietary.

   Positive Response:

      If the device is able to satisfy the request, the server emits an
      <rpc-reply> containing a <config> with the results of the query.

   Negative Response:

      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:
























Enns, Editor            Expires August 13, 2003                [Page 19]

Internet-Draft              XMLCONF Protocol               February 2003


       <rpc id="101" xmlns="http://ietf.org/xmlconf/1.0/base">
         <get-config>
           <source>
             <running></running>
           </source>
           <config xmlns="http://example.com/schema/1.2/config">
             <users></users>
           </config>
           <format>xml</format>
         </get-config>
       </rpc>

       <rpc-reply id="101" xmlns="http://ietf.org/xmlconf/1.0/base">
         <config xmlns="http://example.com/schema/1.2/config">
           <users>
             <user>
               <name>root</name>
               <type>superuser</type>
             </user>
             <user>
               <name>fred</name>
               <type>admin</type>
             </user>
             <user>
               <name>barney</name>
               <type>admin</type>
             </user>
           </users>
         </config>
       </rpc-reply>

       The following example shows how additional nesting within the
      <config> parameter can be used to filter more of the output in the
      response:

















Enns, Editor            Expires August 13, 2003                [Page 20]

Internet-Draft              XMLCONF Protocol               February 2003


       <rpc id="101-a" xmlns="http://ietf.org/xmlconf/1.0/base">
         <get-config>
           <source>
             <running></running>
           </source>
           <config xmlns="http://example.com/schema/1.2/config">
             <users>
               <user>
                 <name>fred</name>
               </user>
             </users>
           </config>
           <format>xml</format>
         </get-config>
       </rpc>

       <rpc-reply id="101-a" xmlns="http://ietf.org/xmlconf/1.0/base">
         <config xmlns="http://example.com/schema/1.2/config">
           <users>
             <user>
               <name>fred</name>
               <type>admin</type>
             </user>
           </users>
         </config>
       </rpc-reply>


5.2 <edit-config>

   Description:

      Load all or part of a specified configuration to the specified
      target configuration.  This operation allows the new configuration
      to be expressed in several ways, such as via a local file, a
      remote file, or inline.  If the target configuration does not
      exist, then it will be created.

      The device will analyze the source and target configurations and
      perform the requested changes.  The target configuration is not
      simply replaced, as with the <copy-config> command.

   Parameters:

      target: @config-name






Enns, Editor            Expires August 13, 2003                [Page 21]

Internet-Draft              XMLCONF Protocol               February 2003


         The configuration datastore being set, such as <running>.

      test-option: (test-then-set | set) [default: set]

         test-then-set: perform a validation test before attempting to
         set; skip set if any errors

         set: perform a set without a validation test first

         This option may only be specified if the device advertises the
         #validate capability (Section 6.4).

      write-option: (merge | replace | overwrite) [default: merge]

         merge: The configuration data identified by the config
         parameter will be merged with the configuration identified by
         the target parameter.

         replace: The configuration data identified by the config
         parameter will replace any related commands in the
         configuration identified by the target parameter.  Unlike a
         <copy-config> operation, which replaces the entire target
         configuration, only the commands actually present via the
         config parameter will be affected.

         overwrite: The configuration data identified by the config
         parameter will replace all configuration in the configuration
         datastore identified by the target parameter.

      error-option: (stop-on-error | ignore-error) [default:
      stop-on-error]

         stop-on-error: abort the rpc request on first error

         ignore-error: continue to process configuration data on error;
         error will be recorded and negative response will be generated
         if any errors

      config: @element-tree

         Specifies the portion(s) of the configuration subtree to set.
         The namespace of this configuration should be specified as an
         attribute of this parameter.

   Positive Response:






Enns, Editor            Expires August 13, 2003                [Page 22]

Internet-Draft              XMLCONF Protocol               February 2003


      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted containing an <ok> element.

   Negative Response:

      An <rpc-error> response is emitted if the request cannot be
      completed for any reason.

   Example:

       <rpc id="102" xmlns="http://ietf.org/xmlconf/1.0/base">
         <edit-config>
           <target>
             <running></running>
           </target>
           <test-option>test-then-set</test-option>
           <write-option>replace</write-option>
           <error-option>stop-on-error</error-option>
           <config xmlns="http://example.com/schema/1.2/config">
             <interface name="Ethernet0/0">
                <address>
                   <ipv4>1.2.3.4</ipv4>
                   <ipv4-mask>255.0.0.0</ipv4-mask>
                </address>
             </interface>
           </config>
         </edit-config>
       </rpc>

       <rpc-reply id="102" xmlns="http://ietf.org/xmlconf/1.0/base">
         <ok></ok>
       </rpc-reply>


5.3 <copy-config>

   Description:

      This operation is used to create or replace an entire
      configuration file with the contents of another complete
      configuration file.  If the target file exists, then it will be
      overwritten, otherwise a new file will be created.

      A device may choose not to support the <running> configuration
      datastore as the <target> parameter of a <copy-config> operation.
      A device may choose not to support remote to remote copy
      operations.  The source and target parameters cannot identify the
      same file.



Enns, Editor            Expires August 13, 2003                [Page 23]

Internet-Draft              XMLCONF Protocol               February 2003


      The device may choose not to support format conversions with this
      operation.  The running and startup configurations are considered
      to be format-neutral, but all other configuration files are
      created in a specific format (text or XML).  A copy operation on
      any these format-specific files may fail if the format parameter
      specifies a value different than the source file format.  It is
      suggested that the format parameter be omitted in this type of
      operation, in order to select the source file format.

   Parameters:

      source: @config-name | config

         Name of the configuration datastore to use as the source of the
         copy operation, or the <config> element containing the
         configuration subtree to copy.

      target: @config-name

         Name of the configuration datastore to use as the destination
         of the copy operation

      format: (xml | text) [Default: xml]

         Specifies the format of the configuration file, either 'xml' or
         'text'.  The format of the source and target configurations
         must match.  The configuration datastores (e.g., <running>)
         will match either format.

   Positive Response:

      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted containing an <ok> element.

   Negative Response:

      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:











Enns, Editor            Expires August 13, 2003                [Page 24]

Internet-Draft              XMLCONF Protocol               February 2003


       <rpc id="103" xmlns="http://ietf.org/xmlconf/1.0/base">
         <copy-config>
           <source>
             <running></running>
           </source>
           <target>
             <url>ftp://example.com/configs/testbed-dec10.txt</url>
           </target>
           <format>text</format>
         </copy-config>
       </rpc>

       <rpc-reply id="103" xmlns="http://ietf.org/xmlconf/1.0/base">
         <ok></ok>
       </rpc-reply>


5.4 <delete-config>

   Description:

      This operation is used to delete a specified configuration
      datastore.  The <running> configuration file cannot be deleted.

   Parameters:

      target: @config-name

         Name of the configuration datastore to delete

   Positive Response:

      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted containing an <ok> element.

   Negative Response:

      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:










Enns, Editor            Expires August 13, 2003                [Page 25]

Internet-Draft              XMLCONF Protocol               February 2003


       <rpc id="104" xmlns="http://ietf.org/xmlconf/1.0/base">
         <delete-config>
           <target>
             <startup></startup>
           </target>
         </delete-config>
       </rpc>

       <rpc-reply id="104" xmlns="http://ietf.org/xmlconf/1.0/base">
         <ok></ok>
       </rpc-reply>


5.5 <get-state>

   Description:

      This protocol operation is used to retrieve device state
      information.  Section 10 contains the XML schema for XMLCONF state
      data.

   Parameters:

      state: (@element-subtree | text)

         If the <format> parameter is equal to 'xml', then this
         parameter specifies the portion(s) of the system state subtree
         to retrieve.  The namespace of this configuration should be
         specified as an attribute of this parameter.  If the <format>
         parameter is equal to 'text', then the contents of this
         parameter are proprietary.  If this parameter is empty, then
         all the device state information will be returned.

      format: (xml | text)

         Specifies the format of the <state> parameter and the return
         text, either 'xml' or 'text'.

   Positive Response:

      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted.  The <state> section will be filled in with the
      appropriate subset(s).

   Negative Response:






Enns, Editor            Expires August 13, 2003                [Page 26]

Internet-Draft              XMLCONF Protocol               February 2003


      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

       <rpc id="105" xmlns="http://ietf.org/xmlconf/1.0/base">
         <get-state>
           <state xmlns="http://example.com/schema/1.2/int-stats">
             <interface name="ethernet0/1">
                <intstats></intstats>
             </interface>
           </state>
           <format>xml</format>
         </get-state>
       </rpc>

       <rpc-reply id="105" xmlns="http://ietf.org/xmlconf/1.0/base">
          <state xmlns="http://example.com/schema/1.2/int-stats">
            <interface name="ethernet0/1">
               <intstats>
                  <inPkts>9456823</inPkts>
                  <inOctets>1228484566</inOctets>
                  <inErrors>4326</inErrors>
                  <outPkts>4821050</outPkts>
                  <outOctets>634712154</outOctets>
                  <outErrors>2096</outErrors>
               </intstats>
            </interface>
          </state>
       </rpc-reply>


5.6 <kill-session>

   Description:

      Force the termination of an XMLCONF session.

   Parameters:

      session-id: (Positive Integer)

         Session identifier of the XMLCONF session to be terminated.  If
         this value is equal to the current session ID, then a 'Bad
         Value' error will be emitted.






Enns, Editor            Expires August 13, 2003                [Page 27]

Internet-Draft              XMLCONF Protocol               February 2003


   Positive Response:

      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted, containing an <ok> element.

   Negative Response:

      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

          <rpc id="105">
            <kill-session>
              <session-id>4</session-id>
            </kill-session>
          </rpc>

          <rpc-reply id="105">
            <ok></ok>
          </rpc-reply>






























Enns, Editor            Expires August 13, 2003                [Page 28]

Internet-Draft              XMLCONF Protocol               February 2003


6. Capabilities

   This section defines a set of capabilities which a client or a server
   MAY implement.  Each peer advertises its capabilities by sending them
   during an initial capabilities exchange.  Each peer only needs to
   understand capabilities that it might use and must be able to process
   and ignore any capability received from the other peer that it does
   not require or does not understand.

   Additional capabilities can be defined using the template in Appendix
   A.  Future capability definitions may be published as standards by
   standards bodies or published as propriety by vendors.

   A capability is identified with a URI, in the form:

      http://{naming authority}/{protocol}/{version}/{category}#{name}

   Capabilities defined in this document have the following format:

      http://ietf.org/xmlconf/1.0/base#{name}

   where {name} is the name of the capability.  These are often
   referenced in discussions and email using the shorthand #{name}.  For
   example, the foo capability would have the formal name "http://
   ietf.org/xmlconf/1.0/base#foo" and be called "#foo".  The shorthand
   form MUST NOT be used inside the protocol.

6.1 Capabilities Exchange

   An XMLCONF capability is a set of additional functionality
   implemented on top of the base XMLCONF specification.  The capability
   is distinguished by a URI.  These URIs should follow the guidelines
   as described in Section 7.2.6.

   Capabilities are advertised in messages sent on the management
   channel at startup.  When the management channel is opened, each peer
   sends a <hello> element containing a list of that peer's
   capabilities.

   This example has the peer advertising the base XMLCONF capability,
   one XMLCONF capability defined in the base XMLCONF document, and one
   vendor-specific capability.









Enns, Editor            Expires August 13, 2003                [Page 29]

Internet-Draft              XMLCONF Protocol               February 2003


   <hello>
     <capabilities>
       <capability>http://ietf.org/xmlconf/1.0/base</capability>
       <capability>http://ietf.org/xmlconf/1.0/base#lock</capability>
       <capability>http:/example.net/router/2.3/core#cool-feature</capability>
     </capabilities>
   </hello>

   Each peer sends their <hello> element simultaneously as soon as the
   connection is open.  A peer may not wait to receive the capability
   set from the other side before sending their own set.

6.2 Writable Running

6.2.1 Description

   The #writable-running capability indicates that the device supports
   writes directly to the <running> configuration datastore.  In other
   words, if present it means that the device supports edit-config and
   copy-config operations where the <running> configuration is the
   target.

6.2.2 Dependencies

   None.

6.2.3 Capability and Namespace

   The #writable-running capability is distinguished by the following
   capability string:

      http://ietf.org/xmlconf/1.0/base#writable-running

   The #writable-running capability uses the base XMLCONF namespace URI.

6.2.4 New Operations

   None.

6.2.5 Modifications to Existing Operations

6.2.5.1 <edit-config>

   The #writable-running capability modifies the <edit-config> operation
   to accept the <running> element as a <target>.

6.2.5.2 <copy-config>




Enns, Editor            Expires August 13, 2003                [Page 30]

Internet-Draft              XMLCONF Protocol               February 2003


   The #writable-running capability modifies the <copy-config> operation
   to accept the <running> element as a <target>.

6.3 Candidate Configuration

6.3.1 Description

   The candidate configuration capability (#candidate) indicates that
   the device supports a candidate configuration datastore, which is
   used to hold configuration data that can manipulated without
   impacting the device's current configuration.  The candidate
   configuration is a full configuration data set which serves as a work
   place for creating a manipulating configuration data.  Additions,
   deletions, and changes may be made to this data to construct the
   desired configuration data.  A <commit> operation may be performed at
   any time which causes the device's running configuration to be set to
   the value of the candidate configuration.

   The candidate configuration can be used as a source or target of any
   operation with a <source> or <target> parameter.  The <candidate>
   element is used to indicate that candidate configuration:

        <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
          <operation>
            <source>
              <candidate></candidate>
            </source>
          </operation>
        </rpc>

    The candidate configuration may be shared amongst multiple sessions.
   Unless a client has specific information that the candidate
   configuration is not shared (e.g.  via another capability), it must
   assume that other sessions may be able to modify the candidate
   configuration at the same time.  It is therefore prudent for a client
   to lock the candidate configuration before modifying it.

   The client can discard any changes since the last <commit> operation
   by executing the <discard-changes> operation.  The candidate
   configuration's content will revert to the current committed
   configuration.

6.3.2 Dependencies

   The #candidate capability requires the #lock capability be
   implemented.  Manipulation of a candidate configuration without a
   locking mechanism is considered dangerous.




Enns, Editor            Expires August 13, 2003                [Page 31]

Internet-Draft              XMLCONF Protocol               February 2003


6.3.3 Capability and Namespace

   The #candidate capability is distinguished by the following
   capability string:

      http://ietf.org/xmlconf/1.0/base#candidate

   The #candidate capability uses the base XMLCONF namespace URI.

6.3.4 New Operations

6.3.4.1 <commit>

   Description:

      When a candidate configuration's content is complete, the
      configuration data can be committed, publishing the data set to
      the rest of the device and requesting the device to conform to the
      behavior described in the new configuration.

      To commit the candidate configuration as the device's new current
      configuration use the <commit> operation.

      The <commit> operation instructs the device to implement the
      configuration data contained in the candidate configuration.

      If the system does not have the #candidate capability, then this
      operation will not be available.

   Parameters:

      confirmed:

         The <confirmed> element indicates that the <commit> operation
         MUST be reverted if a confirming commit is not issued within
         ten (10) minutes.  The timeout period can be adjusted with the
         <confirm-timeout> element.

      confirmed-timeout: Timeout period for confirmed commit, in
         minutes.

   Positive Response:

      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted containing the <ok> element.






Enns, Editor            Expires August 13, 2003                [Page 32]

Internet-Draft              XMLCONF Protocol               February 2003


   Negative Response:

      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

       <rpc id="113" xmlns="http://ietf.org/xmlconf/1.0/base">
         <commit></commit>
       </rpc>

       <rpc-reply id="113" xmlns="http://ietf.org/xmlconf/1.0/base">
         <ok></ok>
       </rpc-reply>


       <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
         <commit>
           <confirmed></confirmed>
           <confirm-timeout>20</confirmed-timeout>
         </commit>
       </rpc>

       <rpc-reply xmlns="http://ietf.org/xmlconf/1.0/base">
         <ok></ok>
       </rpc-reply>


6.3.4.2 <discard-changes>

   If the client decides that the candidate configuration should not be
   committed, the <discard-changes> operation can be used to revert the
   candidate configuration back to the current committed configuration.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <discard-changes></discard-changes>
     </rpc>

    This operation will discard any uncommitted changes.

6.3.5 Modifications to Existing Operations

6.3.5.1 <lock> and <unlock>

   The candidate configuration can be locked by using the <lock>
   operation with the <candidate> element at the <source> parameter:





Enns, Editor            Expires August 13, 2003                [Page 33]

Internet-Draft              XMLCONF Protocol               February 2003


     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <lock>
         <source>
           <candidate></candidate>
         </source>
       </lock>
     </rpc>

   Devices implementing the #candidate capability WILL NOT allow a
   configuration lock to be acquired when there are outstanding changes
   to the candidate configuration.  An error WILL be returned and that
   status of the lock will remain unchanged.

   When a client fails with outstanding changes to the candidate
   configuration, recovery can be painful.  To facility easy recovery,
   the #candidate capability adds a <discard-changes> element to the
   <lock> operation.  If this element contains the value "automatic",
   any outstanding changes will be discarded when the lock is released,
   whether explicitly with the <unlock> operation or implicitly from
   session failure.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <lock>
         <source>
           <candidate></candidate>
         </source>
         <discard-changes>automatic</discard-changes>
       </lock>
     </rpc>


6.3.5.2 <get-config> and <edit-config>

   The candidate configuration is the default target for the
   <edit-config> and <get-config> operations.  It may be explicitly
   named via the <candidate> element:

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <get-config>
         <source>
           <candidate></candidate>
         </source>
       </get-config>
     </rpc>







Enns, Editor            Expires August 13, 2003                [Page 34]

Internet-Draft              XMLCONF Protocol               February 2003


6.4 Validate Capability

6.4.1 Description

   Validation consists of checking a candidate configuration for syntax
   or semantic errors before applying the configuration to the device.

   If this capability is advertised, the device supports the <validate>
   protocol operation and will check (at least) for syntax errors.  In
   addition, it supports the validate parameter to the <edit-config>
   operation and when it is provided will check (at least) for syntax
   errors.

6.4.2 Dependencies

   None.

6.4.3 Capability and Namespace

   The #validate capability is distinguished by the following capability
   string:

      http://ietf.org/xmlconf/1.0/base#validate

   The #validate capability uses the base XMLCONF namespace URI.

6.4.4 New Operations

6.4.4.1 <validate>

   Description:

      This protocol operation is used to validate the contents of the
      specified configuration.

   Parameters:

      source: @config-name

         Name of the configuration datastore being validated, such as
         <candidate>.

   Positive Response:

      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted containing an <ok> element.





Enns, Editor            Expires August 13, 2003                [Page 35]

Internet-Draft              XMLCONF Protocol               February 2003


   Negative Response:

      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.

      A validate operation can fail for any of the following reasons:

      *  syntax errors

      *  missing parameters

      *  references to undefined configuration data

   Example:

       <rpc id="112" xmlns="http://ietf.org/xmlconf/1.0/base">
         <validate>
           <candidate></candidate>
         </validate>
       </rpc>

       <rpc-reply id="112" xmlns="http://ietf.org/xmlconf/1.0/base">
         <ok></ok>
       </rpc-reply>


6.5 Distinct Startup

6.5.1 Description

   The device supports separate running and startup configuration
   datastores.  Operations which affect the running configuration will
   not be automatically copied to the startup configuration.  An
   explicit <copy-config> operation from the <running> to the <startup>
   must be invoked to update the startup configuration to the current
   contents of the running configuration.  XMLCONF protocol operations
   refer to the startup datastore using the <startup> element.

6.5.2 Dependencies

   None.

6.5.3 Capability and Namespace

   The #startup capability is distinguished by the following capability
   string:

      http://ietf.org/xmlconf/1.0/base#startup



Enns, Editor            Expires August 13, 2003                [Page 36]

Internet-Draft              XMLCONF Protocol               February 2003


   The #startup capability uses the base XMLCONF namespace URI.

6.5.4 New Operations

   None.

6.5.5 Modifications to Existing Operations

6.5.5.1 <copy-config>

   To save the startup configuration, use the copy-config command to
   copy the <running> configuration datastore to the  <startup>
   configuration datastore.

          <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
            <copy-config>
              <source>
                <running></running>
              </source>
              <target>
                <startup></startup>
              </target>
              <format>text</format>
            </copy-config>
          </rpc>


6.6 Lock

6.6.1 Description

   The #lock capability allows the client to lock the configuration
   system of a device.  Such locks are intended to be short-lived and
   allow a client to make a change without fear of interaction with
   other XMLCONF clients, non-XMLCONF clients (SNMP and Expect scripts)
   and human users.

   An attempt to lock the configuration MUST fail if an existing session
   currently holds the lock.

   When the lock is acquired, the server MUST prevent any changes to the
   locked resource other than those requested by this session.  SNMP and
   CLI requests to modify the resource MUST fail with an appropriate
   error.

   The duration of the lock is defined as beginning when the lock is
   acquired and lasting until either the lock is released or the XMLCONF
   session closes.  The session closure may be explicitly performed by



Enns, Editor            Expires August 13, 2003                [Page 37]

Internet-Draft              XMLCONF Protocol               February 2003


   the client, or implicitly performed by the server based on criteria
   such as lack of network connectivity, failure of the underlying
   transport, or simple inactivity timeout.  This criteria is dependent
   on the vendor's implementation and the underlying transport.

   The lock operation takes an optional parameter, target.  If the
   target parameter is specified, it names the configuration that will
   be locked.  If the target parameter is not specified, then all
   configurations will be locked.  When a lock is active, <edit-config>
   and <copy-config> operations will be disallowed on the locked
   configuration(s) by any other session.  Additionally, the system will
   ensure that these locked configuration resources will not be modified
   by other non-XMLCONF management operations such as SNMP and CLI.  The
   <kill-session> command (at the RPC layer) can be used to force the
   release of a lock.

6.6.2 Dependencies

   None.

6.6.3 Capability and Namespace

   The #lock capability is distinguished by the following capability
   string:

      http://ietf.org/xmlconf/1.0/base#lock

   The #lock capability uses the base XMLCONF namespace URI.

6.6.4 New Operations

6.6.4.1 <lock>

   Description:

      A configuration source can be locked by using the <lock>
      operation.  A lock will not be granted if any of the following
      conditions are true:

      *  a lock is already held by another session

      *  the target configuration has already been modified and these
         changes have not been committed

      *  lock capability not supported






Enns, Editor            Expires August 13, 2003                [Page 38]

Internet-Draft              XMLCONF Protocol               February 2003


      The server MUST respond with either an <ok> element or an
      <rpc-error>.

      A lock will be released by the system if the session holding the
      lock is terminated for any reason.

   Parameters:

      target: @config-name [Optional]

         Name of the configuration datastore to lock.  If this parameter
         is not present, than all configuration datastores will be
         locked.

   Positive Response:

      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted containing an <ok> element.

   Negative Response:

      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.  This error response
      will include the session number of the lock owner (if failure due
      to lock already held).

   Example:

       <rpc id="106" xmlns="http://ietf.org/xmlconf/1.0/base">
         <lock>
            <running></running>
         </lock>
       </rpc>

       <rpc-reply id="106" xmlns="http://ietf.org/xmlconf/1.0/base">
         <ok></ok>
       </rpc-reply>


6.6.4.2 <unlock>

   Description:

      The unlock operation is used to release a configuration lock,
      previously obtained with the <lock> operation.






Enns, Editor            Expires August 13, 2003                [Page 39]

Internet-Draft              XMLCONF Protocol               February 2003


      An unlock operation will not succeed if any of the following
      conditions are true:

      *  the specified lock is not currently active

      *  the session issuing the <unlock> operation is not the same
         session that obtained the lock

      The server MUST respond with either an <ok> element or an <error>.

   Parameters:

      target: @config-name [Optional]

         Name of the configuration datastore to unlock.  If this
         parameter is not present, than all configuration datastores
         will be unlocked.

         An XMLCONF client is not permitted to unlock a configuration
         datastore that it did not lock.

   Positive Response:

      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted containing an <ok> element.

   Negative Response:

      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

       <rpc id="107" xmlns="http://ietf.org/xmlconf/1.0/base">
         <unlock>
            <running></running>
         </unlock>
       </rpc>

       <rpc-reply id="107" xmlns="http://ietf.org/xmlconf/1.0/base">
         <ok></ok>
       </rpc-reply>


6.7 Notifications






Enns, Editor            Expires August 13, 2003                [Page 40]

Internet-Draft              XMLCONF Protocol               February 2003


6.7.1 Description

   The #notifications capability indicates that the server supports the
   notification channel.  This channel provides a mechanism for sending
   asynchronous notifications within the XMLCONF session.  This channel
   can be used for events and system logging.

6.7.2 Dependencies

   None.

6.7.3 Capability and Namespace

   The #notifications capability is distinguished by the following
   capability string:

      http://ietf.org/xmlconf/1.0/base#notifications

   The #notifications capability uses the base XMLCONF namespace URI.

6.7.4 New Operations

6.7.4.1 <open-notifications>

   Description:

      Use the <open-notifications> operation to request the notification
      channel with a specific set of parameters.  If successful, the
      underlying protocol will open the notification channel with the
      appropriate parameters.

   Parameters:

      format: format

         Indicates the format of the notification channel.  The only
         legal value is "rfc3195".

      matching: match-expression [Optional]

         An optional parameter that limits notifications sent on the
         channel to those matching the match-expression.

   Positive Response:

      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted containing an <ok> element.




Enns, Editor            Expires August 13, 2003                [Page 41]

Internet-Draft              XMLCONF Protocol               February 2003


   Negative Response:

      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

     <rpc id="108" xmlns="http://ietf.org/xmlconf/1.0/base">
       <open-notifications>
         <format>rfc3195</format>
         <matching>match-expression</matching>
       </open-notifications>
     </rpc>

     <rpc-reply id="108" xmlns="http://ietf.org/xmlconf/1.0/base">
       <ok></ok>
     </rpc-reply>


6.7.4.2 <close-notifications>

   Description:

      Use the <close-notifications> operation to close the notification
      channel.  If successful, the underlying protocol will close the
      notification channel.

   Positive Response:

      If the device was able to satisfy the request, then an <rpc-reply>
      is emitted containing an <ok> element.

   Negative Response:

      An <rpc-error> element is emitted within the <rpc-reply> if the
      request cannot be completed for any reason.

   Example:

     <rpc id="109" xmlns="http://ietf.org/xmlconf/1.0/base">
       <close-notifications/>
     </rpc>

     <rpc-reply id="109" xmlns="http://ietf.org/xmlconf/1.0/base">
       <ok></ok>
     </rpc-reply>





Enns, Editor            Expires August 13, 2003                [Page 42]

Internet-Draft              XMLCONF Protocol               February 2003


6.8 URL

6.8.1 Description

   The XMLCONF peer has the ability to accept the <url> element in
   <source> and <target> parameters.  The capability is further
   distinguished by URL arguments indicating the protocols supported.

6.8.2 Dependencies

   None.

6.8.3 Capability and Namespace

   The #url capability is distinguished by the following capability
   string:

      http://ietf.org/xmlconf/1.0/base#url?protocol={protocol-name,...}

   The #url capability uses the base XMLCONF namespace URI.

   The #url capability URI MUST contain a "protocol" argument assigned a
   comma-separated list of protocol names indicating which protocols the
   XMLCONF peer supports.  For example:

      http://ietf.org/xmlconf/1.0/base#url?protocol=http,ftp,file

   The #url capability uses the base XMLCONF namespace URI.

6.8.4 New Operations

   None.

6.8.5 Modifications to Existing Operations

6.8.5.1 <edit-config>

   The #url capability modifies the <edit-config> operation to accept
   the <url> element as the <config> parameter.

6.8.5.2 <copy-config>

   The #url capability modifies the <copy-config> operation to accept
   the <url> element as the value of the the <source> and the <target>
   parameters.

6.8.5.3 <delete-config>




Enns, Editor            Expires August 13, 2003                [Page 43]

Internet-Draft              XMLCONF Protocol               February 2003


   The #url capability modifies the <delete-config> operation to accept
   the <url> element as the value of the the <target> parameters.  If
   this parameter contains a URL, then it should identify a local
   configuration file.

6.8.5.4 <validate>

   The #url capability modifies the <validate> operation to accept the
   <url> element as the value of the the <source> parameter.










































Enns, Editor            Expires August 13, 2003                [Page 44]

Internet-Draft              XMLCONF Protocol               February 2003


7. XML Usage Guidelines for XMLCONF

   XML serves as an encoding format for XMLCONF, allowing complex
   hierarchical data to be expressed in a text format that can be read,
   saved, and manipulated with both traditional text tools and tools
   specific to XML.

   In order to simplify manipulation of XMLCONF content, use of XML is
   restricted to a simple subset described in this section.

7.1 Canonical XML

   XMLCONF's use of XML follows the rules specified by Canonical XML
   (RFC 3076 [6]).  These rules were meant to make XML appear in a
   consistent form, suitable for string comparison.  Many of XML's more
   marginal constructs are excluded, allowing simple parsers to avoid
   implementation issues for rarely-used features.

   RFC 3076 summarizes the changes required by Canonical XML as follows:

      The canonical form of an XML document is physical representation
      of the document produced by the method described in this
      specification.  The changes are summarized in the following list:

      *  The document is encoded in UTF-8

      *  Line breaks normalized to #xA on input, before parsing

      *  Attribute values are normalized, as if by a validating
         processor

      *  Character and parsed entity references are replaced

      *  CDATA sections are replaced with their character content

      *  The XML declaration and document type declaration (DTD) are
         removed

      *  Empty elements are converted to start-end tag pairs

      *  Whitespace outside of the document element and within start and
         end tags is normalized

      *  All whitespace in character content is retained (excluding
         characters removed during line feed normalization)

      *  Attribute value delimiters are set to quotation marks (double
         quotes)



Enns, Editor            Expires August 13, 2003                [Page 45]

Internet-Draft              XMLCONF Protocol               February 2003


      *  Special characters in attribute values and character content
         are replaced by character references

      *  Superfluous namespace declarations are removed from each
         element

      *  Default attributes are added to each element

      *  Lexicographic order is imposed on the namespace declarations
         and attributes of each element

   See [RFC 3076 [6]] for complete information.

7.2 Additional Restrictions

   In addition to the restrictions placed by canonical XML encoding,
   XMLCONF content is constrained by the following rules:

7.2.1 Avoid mixed content

   Mixed content is defined as elements which can contain both data and
   other elements.  Elements in XMLCONF can only contain either data or
   additional elements.

      <valid>
        <element>data</element>
        <more>data</more>
      </valid>

      <not-valid>
        <element>data<more>data</more>maybe some</element>
      </not-valid>

   This greatly simplifies the complexity of parsing XML, especially in
   the area of significant whitespace.  Whitespace inside data elements
   is significant.  Whitespace outside data elements is not.

7.2.2 No attributes in the default namespace

   Do not use attributes in the default namespace.  All attributes
   should be qualified.

     <valid xmlns="http://valid/" xmlns:v="http://valid/" v:foo="cool"></valid>

     <not-valid xmlns="http://not-valid/" foo="not-cool"></not-valid>

   Unqualified attributes belong to the default namespace, and their use
   will pollute this namespace.  Restricting them to the current



Enns, Editor            Expires August 13, 2003                [Page 46]

Internet-Draft              XMLCONF Protocol               February 2003


   namespace encourages meaningful definitions that are free of
   collisions.

7.2.3 Use container elements for lists

   When encoding lists with multiple instances, use a distinct container
   element, preferable the plural form of the instance element.

   In this example, the element 'gromit' is contained within the
   'gromits' element.

      <valid>
        <gromits>
          <gromit>....</gromit>
          <gromit>....</gromit>
          <gromit>....</gromit>
        </gromits>
      </valid>

   Use of container elements is meant to allow simpler manipulation of
   lists and list members.

7.2.4 Elements and Attributes

   The choice of elements and attributes has been widely discussed, but
   no absolute guidelines exist.  When designing encoding rules for
   XMLCONF content, the following guidelines should be used:

7.2.4.1 Consider attributes as meta-data

   Attributes should contain meta-data about the element, not true data.
   By extension, vital information should not be encoded in attributes.

7.2.4.2 Consider the lack of extensibility of attributes

   Attributes are unordered, can only appear once, and can have no
   children.  Data scenarios which must leave room for future expansion
   (in future specifications or future software releases) should avoid
   attributes.

7.2.5 Proper Tag Names

   When choosing element names, consider the following guidelines:

   o  Prefer ASCII (7-bit).

   o  Prefer lower case.




Enns, Editor            Expires August 13, 2003                [Page 47]

Internet-Draft              XMLCONF Protocol               February 2003


   o  Prefer dashes to underscores.

   o  Prefer full words.  Note that 'config' is considered a full word.

   These are only guidelines and should be considered secondary to the
   need for consistency with existing vocabularies.  For example, when
   encoding MIB variables names in XMLCONF, use the existing names
   (ifAddr) instead of shifting to these guidelines (if-address).  These
   guidelines are valuable when no common vocabulary exists, since they
   help to avoid the scenario where a dozen developers choose a dozen
   names that differ in ways that lead to homicidal rage (ifaddr,
   if-addr, if-address, interface-address, intf-addr, iaddr, iface-addr,
   etc).

7.2.6 Namespaces

   A namespace URI uniquely identifies the content and meaning of an XML
   element.  When designing XML namespaces for XMLCONF content, the
   following guidelines should be used:

   o  prefer domain name in URIs.  Use the domain name of the
      organization that controls the content of the scheme.

   o  prefer version numbers in namespaces.  Use dates when version
      numbers are not appropriate.  Versions should be formatted in
      strings that are consistent with the software being referenced.
      Dates should be formatted as "YYYY-MM-DD".

   o  prefer URLish URIs, but don't expect them all to be reachable or
      meaningful.  While URIs are not URLs and required to reference any
      resource, using non-URL syntax is needlessly confusing.  For
      example, the following URI looks like a programmer mistake:

         ietf.org:/rfc/rfc1234.txt

   The model namespace looks like:

      http://${naming-authority}/${topic}/${version}/${area}

   For example:

      http://ietf.org/xmlconf/1.0/base-config

   In this usage, 'topic' might be the product name, 'version' might be
   the software version, and 'area' might be the portion of that
   software documented in this particular namespace.

      http://example.net/magic-os/84.1.3/bgp



Enns, Editor            Expires August 13, 2003                [Page 48]

Internet-Draft              XMLCONF Protocol               February 2003


   The ${topic} segment might contain a qualifying hierarchy.  For
   example, if the Puff Router Company has a large set of operating
   systems targeted at differing market segments, it may express this
   relationship in the ${topic}:

      http://example.net/embedded/magic-os/84.1.3/bgp













































Enns, Editor            Expires August 13, 2003                [Page 49]

Internet-Draft              XMLCONF Protocol               February 2003


8. BEEP Mapping

   All XMLCONF implementations MUST implement the profile and functional
   mapping between XMLCONF and BEEP as described below.

8.1 XMLCONF Session Initiation

   Managers may be either BEEP listeners or initiators.  Similarly,
   agents may be either listeners or initiators.  Thus the initial
   exchange takes place without regard to whether a manager is the
   initiator or the agent is the initiator.  After the transport
   connection is established, as greetings are exchanged, they should
   each announce their support for TLS [4] and optionally SASL [3] (see
   below), as well as for the SYSLOG profile [8].  Once greetings are
   exchanged, if TLS is to be used and available by both parties, the
   listener will START a channel with the TLS profile.

   Once TLS has been started, a new greeting is sent by both initiator
   and listener, as required by the BEEP RFC.

   At this point, if SASL is desired, the initiator will start BEEP
   channel 1 to perform a SASL exchange to authenticate itself.  When
   SASL is completed, the channel MUST be closed.

   Once authentication has occurred, there is no need to distinguish
   between initiator and listener.  We now distinguish between manager
   and agent.

   The manager now establishes an XMLCONF management channel for the
   purpose of exchanging capabilities, monitoring progress, and aborting
   remote procedure calls.  As initiators assign odd channels and
   listeners assign even channels, the management channel will be BEEP
   channel 1 or 2, depending on whether the manager is the initiator or
   the listener.

   The manager next establishes the XMLCONF operational channel for the
   purpose of issuing RPC requests.  This channel will be BEEP channel 3
   or 4.

   Finally, if either manager or agent wishes to send or receive
   notifications, it may issue a start on the next available channel if
   the other side has sent the send or receive XMLCONF capability.

   At this point, the XMLCONF session is established.

8.2 XMLCONF RPC Execution

   To issue an RPC, the manager transmits on the operational channel a



Enns, Editor            Expires August 13, 2003                [Page 50]

Internet-Draft              XMLCONF Protocol               February 2003


   BEEP MSG containing the RPC and its arguments.  In accordance with
   the BEEP standard, RPC requests may be split across multiple BEEP
   frames.

   Once received and processed, the agent responds with BEEP RPYs on the
   same channel with the response to the RPC.  In accordance with the
   BEEP standard, responses may be split across multiple BEEP frames.

8.3 XMLCONF <rpc-abort> and <rpc-progress>

   <rpc-abort> and <rpc-progress> requests are issued by the manager on
   the XMLCONF management channel, and the agent responds with BEEP RPYs
   on that same channel.

8.4 XMLCONF Session Teardown

   Either side may initiate the termination of an XMLCONF session.  In
   This is done by issuing a BEEP close on the operational channel after
   the current RPC has completed.  The same is done with any
   notification channels by the end that transmits notifications.
   Finally, BEEP channel 0 is closed.

8.5 BEEP Profiles for XMLCONF Channels

   There are two profiles, the management channel profile and the
   operations channel profile.  These are not to be confused with the
   BEEP control channel.

   The operations channel will have two commands, <rpc> and <rpc-reply>.
   The management channel will have one additional operation with
   <rpc-progress>.

8.5.1 Management Channel Profile

      <!-- DTD for xmlconf management over BEEP

        Refer to this DTD as:

          <!ENTITY % XMLCONF PUBLIC "xmlconf/management/1.0" "">
          %XMLCONF;
        -->

      <!--   Contents

          Overview

          Includes
          Profile Summaries



Enns, Editor            Expires August 13, 2003                [Page 51]

Internet-Draft              XMLCONF Protocol               February 2003


          Entity Definitions

          Operations
   	   rpc
   	   rpc-reply
    	   rpc-progress
        -->

      <!--  Overview   XMLCONF Management channel  -->

      <!-- Includes -->

             <!ENTITY % BEEP PUBLIC "-//Blocks//DTD BEEP//EN"
                        "">
             %BEEP;

      <!--  Profile summaries


          BEEP profile XMLCONF-MANAGEMENT

          role        MSG        		RPY        ERR
          ====        ===        		===        ===
          I or L      rpc			ok         error
          I or L      rpc-reply		ok         error
          I or L      rpc-progress		ok         error

      -->

      <!--
        Entity Definitions

              entity        syntax/reference     example
              ======        ================     =======

   	a PRC
   	   RPC-DATA	  Alpha
   	a RPC reply number
              RPC-REPLY      1*3DIGIT
   	a RPC progress number
              RPC-PROGRESS   1*3DIGIT

      -->

      <!ENTITY % RPC-REPLY    "CDATA">
      <!ENTITY % RPC-DATA     "CDATA">
      <!ENTITY % RPC-PROGRESS "CDATA">
       -->



Enns, Editor            Expires August 13, 2003                [Page 52]

Internet-Draft              XMLCONF Protocol               February 2003


      <!--
        RPC command
        -->

      <!ELEMENT rpc        (#ELEMENTDATA)>
      <!ATTLIST rpc
                rpc-data	%RPC_DATA;	           #REQUIRED>


   <!--
        Result of RPC.
        -->

      <!ELEMENT rpc-reply    (#ELEMENTDATA)>
      <!ATTLIST rpc-reply
                rpc-reply	%RPC-REPLY;	           #REQUIRED
   	     rpc-data    %rpc-data		   #REQUIRED>

   <!--
        Progress of RPC operation.
        -->

      <!ELEMENT rpc-progress   (#ELEMENTDATA)>
      <!ATTLIST rpc-progress
                rpc-progress %RPC-PROGRESS;	           #REQUIRED>

      <!-- End of DTD -->


8.5.2 Operations Channel Profile

      <!-- DTD for xmlconf operations over BEEP

        Refer to this DTD as:

          <!ENTITY % XMLCONF PUBLIC "xmlconf/Operation/1.0" "">
          %XMLCONF;
        -->

      <!--   Contents

          Overview

          Includes
          Profile Summaries
          Entity Definitions

          Operations



Enns, Editor            Expires August 13, 2003                [Page 53]

Internet-Draft              XMLCONF Protocol               February 2003


   	   rpc
   	   rpc-reply
        -->

      <!--  Overview   XMLCONF operation channel  -->

      <!-- Includes -->

             <!ENTITY % BEEP PUBLIC "-//Blocks//DTD BEEP//EN"
                        "">
             %BEEP;

      <!--  Profile summaries


          BEEP profile XMLCONF-MANAGEMENT

          role        MSG        		RPY        ERR
          ====        ===        		===        ===
          I or L      rpc				ok         error
          I or L      rpc-reply			ok         error

      -->

      <!--
        Entity Definitions

              entity        syntax/reference     example
              ======        ================     =======

   	a PRC
   	   RPC-DATA	  Alpha
   	a RPC reply number
              RPC-REPLY      1*3DIGIT

      -->

      <!ENTITY % RPC-REPLY    "CDATA">
      <!ENTITY % RPC-DATA     "CDATA">

       -->

      <!--
        RPC command
        -->

      <!ELEMENT RPC        (#ELEMENTDATA)>
      <!ATTLIST RPC



Enns, Editor            Expires August 13, 2003                [Page 54]

Internet-Draft              XMLCONF Protocol               February 2003


                RPC-DATA	%RPC_DATA;	           #REQUIRED>


   <!--
        Result of RPC.
        -->

      <!ELEMENT RPC-REPLY    (#ELEMENTDATA)>
      <!ATTLIST RPC-REPLY
                RPC-REPLY	%RPC-REPLY;	           #REQUIRED
   	     	RPC-DATA    %RPC-DATA		   #REQUIRED>


      <!-- End of DTD -->


8.5.3 Notification Channel Profile

   The XMLCONF notification channel profile is defined in RFC 3195 [8].
































Enns, Editor            Expires August 13, 2003                [Page 55]

Internet-Draft              XMLCONF Protocol               February 2003


9. XML Schema for XMLCONF RPC and Protocol Operations


   <?xml version="1.0" encoding="UTF-8"?>
   <xsd:schema targetNamespace="http://ietf.org/xmlconf/1.0/base"
               xmlns:xc="http://ietf.org/xmlconf/1.0/base"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               elementFormDefault="unqualified">
     <xsd:complexType name="rpcType">
       <xsd:sequence>
         <xsd:element ref="xc:rpcOperation"/>
       </xsd:sequence>
       <xsd:attribute name="id" type="xsd:string" use="optional"/>
     </xsd:complexType>
     <xsd:element name="rpc" type="xc:rpcType"/>
     <xsd:complexType name="rpc-errorType">
       <xsd:sequence>
         <xsd:element name="tag" type="xsd:string" minOccurs="0"/>
         <xsd:element name="errno" type="xsd:integer" minOccurs="0"/>
         <xsd:element name="severity" type="xsd:string" minOccurs="0"/>
         <xsd:element name="edit-path" type="xsd:string" minOccurs="0"/>
         <xsd:element name="statement" type="xsd:string" minOccurs="0"/>
         <xsd:element name="message" type="xsd:string" minOccurs="0"/>
         <xsd:element name="action" type="xsd:string" minOccurs="0"/>
       </xsd:sequence>
     </xsd:complexType>
     <xsd:complexType name="rpc-replyType">
       <xsd:choice>
         <xsd:element name="ok" minOccurs="0"/>
         <xsd:element name="rpc-error"
                      type="xc:rpc-errorType" minOccurs="0"/>
         <xsd:element ref="xc:config" minOccurs="0"/>
         <xsd:element ref="xc:state" minOccurs="0"/>
       </xsd:choice>
       <xsd:attribute name="id" type="xsd:string" use="optional"/>
     </xsd:complexType>
     <xsd:element name="rpc-reply" type="xc:rpc-replyType"/>
     <xsd:element name="percent-done" type="xsd:string"/>
     <xsd:element name="amount" type="xsd:string"/>
     <xsd:element name="message" type="xsd:string"/>
     <xsd:complexType name="rpc-progressType">
       <xsd:choice>
         <xsd:element ref="xc:percent-done"/>
         <xsd:element ref="xc:amount"/>
         <xsd:element ref="xc:message"/>
       </xsd:choice>
       <xsd:attribute name="id" type="xsd:string" use="required"/>
     </xsd:complexType>



Enns, Editor            Expires August 13, 2003                [Page 56]

Internet-Draft              XMLCONF Protocol               February 2003


     <xsd:element name="rpc-progress" type="xc:rpc-progressType"/>
     <xsd:complexType name="rpc-abortType">
       <xsd:attribute name="id" type="xsd:string" use="required"/>
     </xsd:complexType>
     <xsd:element name="rpc-abort" type="xc:rpc-abortType"/>
     <xsd:complexType name="rpc-abort-replyType">
       <xsd:attribute name="id" type="xsd:string" use="required"/>
     </xsd:complexType>
     <xsd:element name="rpc-abort-reply" type="xc:rpc-abort-replyType"/>
     <xsd:simpleType name="responseAttributeType">
       <xsd:restriction base="xsd:string">
         <xsd:enumeration value="terse"/>
         <xsd:enumeration value="full"/>
       </xsd:restriction>
     </xsd:simpleType>
     <xsd:simpleType name="test-optionType">
       <xsd:restriction base="xsd:string">
         <xsd:enumeration value="test"/>
         <xsd:enumeration value="test-then-set"/>
         <xsd:enumeration value="set"/>
       </xsd:restriction>
     </xsd:simpleType>
     <xsd:element name="test-option" type="xc:test-optionType"/>
     <xsd:simpleType name="write-optionType">
       <xsd:restriction base="xsd:string">
         <xsd:enumeration value="merge"/>
         <xsd:enumeration value="replace"/>
         <xsd:enumeration value="overwrite"/>
       </xsd:restriction>
     </xsd:simpleType>
     <xsd:element name="write-option" type="xc:write-optionType"/>
     <xsd:simpleType name="error-optionType">
       <xsd:restriction base="xsd:string">
         <xsd:enumeration value="stop-on-error"/>
         <xsd:enumeration value="ignore-error"/>
       </xsd:restriction>
     </xsd:simpleType>
     <xsd:element name="error-option" type="xc:error-optionType"/>
     <xsd:complexType name="rpcOperationType">
       <xsd:attribute name="response" type="xc:responseAttributeType"
                      default="terse"/>
     </xsd:complexType>
     <xsd:element name="rpcOperation" type="xc:rpcOperationType"
                  abstract="true"/>
     <xsd:simpleType name="configFormatType">
       <xsd:restriction base="xsd:string">
         <xsd:enumeration value="xml"/>
         <xsd:enumeration value="text"/>



Enns, Editor            Expires August 13, 2003                [Page 57]

Internet-Draft              XMLCONF Protocol               February 2003


       </xsd:restriction>
     </xsd:simpleType>
     <xsd:element name="format" type="xc:configFormatType"/>
     <xsd:complexType name="config-inlineType">
       <xsd:complexContent>
         <xsd:extension base="xsd:anyType">
           <xsd:attribute name="format" type="xc:configFormatType"/>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="config" type="xc:config-inlineType"/>
     <xsd:element name="state" type="xc:config-inlineType"/>
     <xsd:complexType name="config-nameType"/>
     <xsd:element name="config-name" type="xc:config-nameType"
                  abstract="true"/>
     <xsd:element name="startup" type="xc:config-nameType"
               substitutionGroup="xc:config-name"/>
     <xsd:element name="candidate" type="xc:config-nameType"
               substitutionGroup="xc:config-name"/>
     <xsd:element name="running" type="xc:config-nameType"
               substitutionGroup="xc:config-name"/>
     <xsd:complexType name="config-uriType">
       <xsd:simpleContent>
         <xsd:extension base="xsd:anyURI">
           <xsd:attribute name="format" type="xc:configFormatType"/>
         </xsd:extension>
       </xsd:simpleContent>
     </xsd:complexType>
     <xsd:element name="url" type="xc:config-uriType"/>
     <xsd:complexType name="rpcOperationSourceType">
       <xsd:choice>
         <xsd:element ref="xc:config"/>
         <xsd:element ref="xc:config-name"/>
         <xsd:element ref="xc:url"/>
       </xsd:choice>
     </xsd:complexType>
     <xsd:element name="source" type="xc:rpcOperationSourceType"/>
     <xsd:complexType name="rpcOperationTargetType">
       <xsd:choice>
         <xsd:element ref="xc:config-name"/>
         <xsd:element ref="xc:url"/>
       </xsd:choice>
     </xsd:complexType>
     <xsd:element name="target" type="xc:rpcOperationTargetType"/>
     <xsd:complexType name="get-configType">
       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType">
           <xsd:sequence>



Enns, Editor            Expires August 13, 2003                [Page 58]

Internet-Draft              XMLCONF Protocol               February 2003


             <xsd:element ref="xc:source"/>
             <xsd:element ref="xc:config" minOccurs="0"/>
             <xsd:element ref="xc:format" minOccurs="0"/>
           </xsd:sequence>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="get-config" type="xc:get-configType"
               substitutionGroup="xc:rpcOperation"/>
     <xsd:complexType name="edit-configType">
       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType">
           <xsd:sequence>
             <xsd:element ref="xc:source" minOccurs="0"/>
             <xsd:element ref="xc:target"/>
             <xsd:element ref="xc:test-option" minOccurs="0"/>
             <xsd:element ref="xc:write-option" minOccurs="0"/>
             <xsd:element ref="xc:error-option" minOccurs="0"/>
             <xsd:element ref="xc:config" minOccurs="0"/>
           </xsd:sequence>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="edit-config" type="xc:edit-configType"
               substitutionGroup="xc:rpcOperation"/>
     <xsd:complexType name="copy-configType">
       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType">
           <xsd:sequence>
             <xsd:element ref="xc:source"/>
             <xsd:element ref="xc:target"/>
             <xsd:element ref="xc:format"/>
           </xsd:sequence>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="copy-config" type="xc:copy-configType"
               substitutionGroup="xc:rpcOperation"/>
     <xsd:complexType name="delete-configType">
       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType">
           <xsd:sequence>
             <xsd:element ref="xc:target"/>
           </xsd:sequence>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="delete-config" type="xc:delete-configType"



Enns, Editor            Expires August 13, 2003                [Page 59]

Internet-Draft              XMLCONF Protocol               February 2003


               substitutionGroup="xc:rpcOperation"/>
     <xsd:complexType name="get-stateType">
       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType">
           <xsd:sequence>
             <xsd:element ref="xc:state"/>
             <xsd:element ref="xc:format" minOccurs="0"/>
           </xsd:sequence>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="get-state" type="xc:get-stateType"
               substitutionGroup="xc:rpcOperation"/>
     <xsd:complexType name="lockType">
       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType">
           <xsd:sequence>
             <xsd:element ref="xc:target"/>
           </xsd:sequence>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="lock" type="xc:lockType"
               substitutionGroup="xc:rpcOperation"/>
     <xsd:complexType name="unlockType">
       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType">
           <xsd:sequence>
             <xsd:element ref="xc:target"/>
             <xsd:element name="discard-changes" minOccurs="0"/>
           </xsd:sequence>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="unlock" type="xc:unlockType"
               substitutionGroup="xc:rpcOperation"/>
     <xsd:complexType name="validateType">
       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType">
           <xsd:sequence>
             <xsd:element ref="xc:source"/>
           </xsd:sequence>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="validate" type="xc:validateType"
               substitutionGroup="xc:rpcOperation"/>
     <xsd:complexType name="commitType">



Enns, Editor            Expires August 13, 2003                [Page 60]

Internet-Draft              XMLCONF Protocol               February 2003


       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType">
           <xsd:sequence>
             <xsd:element name="confirmed" minOccurs="0"/>
             <xsd:element name="confirmed-timeout" minOccurs="0"/>
           </xsd:sequence>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="commit" type="xc:commitType"
               substitutionGroup="xc:rpcOperation"/>
     <xsd:complexType name="discard-changesType">
       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType"/>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="discard-changes" type="xc:discard-changesType"
               substitutionGroup="xc:rpcOperation"/>
     <xsd:complexType name="kill-sessionType">
       <xsd:complexContent>
         <xsd:extension base="xc:rpcOperationType">
           <xsd:sequence>
             <xsd:element name="session-id" type="xsd:string" minOccurs="0"/>
           </xsd:sequence>
         </xsd:extension>
       </xsd:complexContent>
     </xsd:complexType>
     <xsd:element name="kill-session" type="xc:kill-sessionType"
               substitutionGroup="xc:rpcOperation"/>
   </xsd:schema>





















Enns, Editor            Expires August 13, 2003                [Page 61]

Internet-Draft              XMLCONF Protocol               February 2003


10. XML Schema for XMLCONF State Data


   <schema
       targetNamespace="http://ietf.org/xmlconf/1.0/state"
       xmlns="http://www.w3.org/2001/XMLSchema"
       xmlns:xc="http://ietf.org/xmlconf/1.0/state"
       elementFormDefault="unqualified">

    <annotation>
     <documentation xml:lang="en">
      Initial schema for XMLCONF state information.
     </documentation>
    </annotation>

    <element name="xmlconf-state">
     <complexType>
      <sequence>

       <element name="capabilities">
        <annotation>
         <documentation xml:lang="en">
          List of XMLCONF capabilities supported by this device.
         </documentation>
        </annotation>
        <complexType>
         <sequence>
          <element name="capability" type="anyURI"
           minOccurs="0" maxOccurs="unbounded"/>
         </sequence>
        </complexType>
       </element>

       <element name="sessions">
        <annotation>
         <documentation xml:lang="en">
          List of XMLCONF sessions currently active on this device.
         </documentation>
        </annotation>
        <complexType>
         <sequence>
          <element name="my-session-id" type="positiveInteger"/>
          <element name="session" type="xc:XmlconfSessionInfo"
           minOccurs="0" maxOccurs="unbounded"/>
         </sequence>
        </complexType>
       </element>




Enns, Editor            Expires August 13, 2003                [Page 62]

Internet-Draft              XMLCONF Protocol               February 2003


       <element name="configs">
        <annotation>
         <documentation xml:lang="en">
          List of XMLCONF configuration databases supported on this device.
         </documentation>
        </annotation>
        <complexType>
         <sequence>
          <element name="config" type="xc:XmlconfConfigInfo"
           minOccurs="0" maxOccurs="unbounded"/>
         </sequence>
        </complexType>
       </element>

      </sequence>
     </complexType>
    </element>

    <complexType name="XmlconfSessionInfo">
     <sequence>
      <element name="session-id" type="positiveInteger"/>
      <element name="username" type="string"/>
      <element name="login-time" type="dateTime"/>
     </sequence>
    </complexType>

    <complexType name="XmlconfConfigInfo">
     <sequence>
      <element name="config-name" type="xc:ConfigName"/>
      <element name="lock-status" type="xc:LockStatus"/>
     </sequence>
    </complexType>

    <complexType name="ConfigName">
     <choice>
      <element name="candidate"/>
      <element name="running"/>
      <element name="startup"/>
     </choice>
    </complexType>

    <complexType name="LockStatus">
     <sequence>
      <element name="lock-state">
       <simpleType>
        <restriction base="string">
         <enumeration value="locked"/>
         <enumeration value="unlocked"/>



Enns, Editor            Expires August 13, 2003                [Page 63]

Internet-Draft              XMLCONF Protocol               February 2003


        </restriction>
       </simpleType>
      </element>
      <element name="locked-by" type="positiveInteger"
       minOccurs="0"/>
     </sequence>
    </complexType>

   </schema>










































Enns, Editor            Expires August 13, 2003                [Page 64]

Internet-Draft              XMLCONF Protocol               February 2003


11. Security Considerations

   Configuration information is by its very nature sensitive.  Its
   transmission in the clear without integrity checking leaves devices
   open to classic so-called "Man in the middle" attacks.  Configuration
   information often times contains passwords, user names, service
   descriptions, and topological information, all of which is sensitive.

   The protocol, therefore, must minimally support options for both
   confidentiality and authentication.  The initial transport mapping
   makes use of BEEP.  BEEP itself makes use of both transport layer
   security and SASL.  We require that TLS be used in BEEP as described
   by the BEEP standard.  Client side certificates are strongly
   desirable, but a SASL authentication is the bare minimum.  SASL
   allows for the use of protocols such as radius, so that
   authentication can occur off the box.

   In the case of SASL authentication, this will occur on the first
   channel creation.  No further authentication may occur during the
   same session.  This avoids a situation where rights are different
   between different channels.  If an implementation wishes to support
   multiple accesses by different individuals with different rights,
   then multiple sessions are required.

   Different environments may well allow different rights prior to and
   then after authentication.  Thus, an authorization model is not
   specified in this document.  When an operation is not properly
   authorized then a simple "permission denied" is sufficient.  N.B.
   authorization information may be exchanged in the form of
   configuration information.  This is all the more reason to ensure the
   security of the connection.




















Enns, Editor            Expires August 13, 2003                [Page 65]

Internet-Draft              XMLCONF Protocol               February 2003


12. Authors and Acknowledgements

   This document was written by:

      Andy Bierman, Cisco Systems

      Ken Crozier, Cisco Systems

      Rob Enns, Juniper Networks

      Ted Goddard, Wind River

      Eliot Lear, Cisco Systems

      David Perkins, Riverstone Networks

      Phil Shafer, Juniper Networks

      Steve Waldbusser

      Margaret Wasserman, Wind River






























Enns, Editor            Expires August 13, 2003                [Page 66]

Internet-Draft              XMLCONF Protocol               February 2003


Normative References

   [1]  Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler,
        "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C REC
        REC-xml-20001006, October 2000.

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

   [3]  Myers, J., "Simple Authentication and Security Layer (SASL)",
        RFC 2222, October 1997.

   [4]  Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
        P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
        1999.

   [5]  Rigney, C., Willens, S., Rubens, A. and W. Simpson, "Remote
        Authentication Dial In User Service (RADIUS)", RFC 2865, June
        2000.

   [6]  Boyer, J., "Canonical XML Version 1.0", RFC 3076, March 2001.

   [7]  Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC
        3080, March 2001.

   [8]  New, D. and M. Rose, "Reliable Delivery for syslog", RFC 3195,
        November 2001.
























Enns, Editor            Expires August 13, 2003                [Page 67]

Internet-Draft              XMLCONF Protocol               February 2003


Informative References

   [9]   Clark, J., "XSL Transformations (XSLT) Version 1.0", W3C REC
         REC-xslt-19991116, November 1999.

   [10]  T. Rose, M., Masinter, L. and S. Hollenbeck, "Guidelines for
         The Use of XML within IETF Protocols",
         draft-hollenbeck-ietf-xml-guidelines-07 (work in progress),
         November 2002.

   [11]  Rinne, T., Ylonen, T., Kivinen, T. and S. Lehtinen, "SSH
         Protocol Architecture", draft-ietf-secsh-architecture-13 (work
         in progress), September 2002.


Author's Address

   Rob Enns
   Juniper Networks
   1194 North Mathilda Ave
   Sunnyvale, CA  94089
   US

   EMail: rpe@juniper.net



























Enns, Editor            Expires August 13, 2003                [Page 68]

Internet-Draft              XMLCONF Protocol               February 2003


Appendix A. Capability Template

A.1 capability-name (template)

A.1.1 Overview

A.1.2 Dependencies

A.1.3 Capability and Namespace

   The {name} is distinguished by following capability string:

      http://ietf.org/xmlconf/1.0/base#{name}

   The {name} capability uses the base XMLCONF namespace URI.

A.1.4 New Operations

A.1.4.1 <op-name>

A.1.5 Modifications to Existing Operations

A.1.5.1 <op-name>

   If existing operations are not modified by this capability, this
   section may be omitted.

A.1.6 Interactions with Other Capabilities

   If this capability does not interact with other capabilities, this
   section may be omitted.




















Enns, Editor            Expires August 13, 2003                [Page 69]

Internet-Draft              XMLCONF Protocol               February 2003


Appendix B. Configuring Multiple Devices with XMLCONF

B.1 Operations Against Individual Devices

   Consider the work involved in performing a configuration update
   against a single individual device.  In making a change to the
   configuration, the application needs to build trust that its change
   has been made correctly and that it has not impacted the operation of
   the device.  The application (and the application user) should feel
   confident that their change has not damaged the network.

   Protecting each individual device consists of a number of steps:

   o  acquiring the configuration lock

   o  loading the update

   o  validating the incoming configuration

   o  checkpointing the running configuration

   o  changing the running configuration

   o  testing the new configuration

   o  making the change permanent (if desired)

   o  releasing the configuration lock

   Let's look at the details of each of these steps.

B.1.1 Acquiring the Configuration Lock

   A lock should be acquired to prevent simultaneous updates from
   multiple sources.  If multiple sources are affecting the device, the
   application is hampered in both testing of its change to the
   configuration and in recovery should the update fail.  Acquiring a
   short-lived lock is a simple defense to prevent other parties from
   introducing unrelated changes while.

   The lock can only be acquired if the device supports the #lock
   capability.  The lock can be acquired using the <lock> operation.









Enns, Editor            Expires August 13, 2003                [Page 70]

Internet-Draft              XMLCONF Protocol               February 2003


     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <lock>
         <source>
           <running></running>
         </source>
       </lock>
     </rpc>

   If the #candidate capability is also supported, failure recovery can
   be simplified by using the <discard-changes> parameter.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <lock>
         <discard-changes>automatic</discard-changes>
         <source>
           <candidate></candidate>
         </source>
       </lock>
     </rpc>


B.1.2 Loading the Update

   The configuration can be loaded onto the device without impacting the
   running system.  If the #url capability is supported, incoming
   changes can be placed in a local file.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <copy-config>
         <source>
           <config>
             <!-- place incoming configuration here -->
           </config>
         </source>
         <target>
           <url>file://incoming.conf</url>
         </target>
         <format>text</format>
       </copy-config>
     </rpc>

   If the #candidate capability is supported, the candidate
   configuration can be used.








Enns, Editor            Expires August 13, 2003                [Page 71]

Internet-Draft              XMLCONF Protocol               February 2003


     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <edit-config>
         <source>
           <config>
             <!-- place incoming configuration here -->
           </config>
         </source>
         <target>
           <candidate></candidate>
         </target>
       </edit-config>
     </rpc>

   If the update fails, the user file can be deleted using the
   <delete-config> operation or the candidate configuration reverted
   using the <discard-changes> operation.

B.1.3 Validating the Incoming Configuration

   Before applying the incoming configuration, it is often useful to
   validate it.  Validation allows the application to gain confidence
   that the change will succeed and simplifies recovery if it does not.

   If the device supports the #url capability, use the <validate>
   operation with the <source> parameter set to the proper user file:

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <validate>
         <source>
           <url>file://incoming.conf</url>
         </source>
       </validate>
     </rpc>

   If the device supports the #candidate capability, some validation
   will be performed as part of loading the incoming configuration into
   the candidate.  For full validation, either pass the <validate>
   parameter during the <edit-config> step given above, or use the
   <validate> operation with the <source> parameter set to <candidate>.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <validate>
         <source>
           <candidate></candidate>
         </source>
       </validate>
     </rpc>




Enns, Editor            Expires August 13, 2003                [Page 72]

Internet-Draft              XMLCONF Protocol               February 2003


B.1.4 Checkpointing the Running Configuration

   The running configuration can be saved into a local file as a
   checkpoint before loading the new configuration.  If the update
   fails, the configuration can be restored by reloading the checkpoint
   file.

   The checkpoint file can be created using the <copy-config> operation.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <copy-config>
         <source>
           <running></running>
         </source>
         <target>
           <url>file://checkpoint.conf</url>
         </target>
         <format>text</format>
       </copy-config>
     </rpc>

   To restore the checkpoint file, reverse the source and target
   parameters.

B.1.5 Changing the Running Configuration

   When the incoming configuration has been safely loaded onto the
   device and validated, it is ready to impact the running system.

   If the device supports the #url capability, use the <edit-config>
   operation to merge the incoming configuration into the running
   configuration.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <edit-config>
         <source>
           <url>file://incoming.conf</url>
         </source>
         <target>
           <running></running>
         </target>
       </edit-config>
     </rpc>

   If the device supports the #candidate capability, use the <commit>
   operation to set the running configuration to the candidate
   configuration.  Use the <confirm> parameter to allow automatic
   reverting to the original configuration if connectivity to the device



Enns, Editor            Expires August 13, 2003                [Page 73]

Internet-Draft              XMLCONF Protocol               February 2003


   fails.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <commit>
         <confirm/>
         <confirm-timeout>15</confirm-timeout>
       </commit>
     </rpc>


B.1.6 Testing the New Configuration

   Now that the incoming configuration has been integrated into the
   running configuration, the application needs to gain trust that the
   change has affected the device in the way intended without affecting
   it negatively.

   To gain this confidence, the application can run tests of the
   operational state of the device.  The nature of the test is dependent
   on the nature of the change and is outside the scope of this
   document.  Such tests may include reachability from the system
   running the application (using ping), changes in reachability to the
   rest of the network (by comparing the device's routing table), or
   inspection of the particular change (looking for operational evidence
   of the BGP peer that was just added).

B.1.7 Making the Change Permanent

   When the configuration change is in place and the application has
   sufficient faith in the proper function of this change, the
   application should make the change permanent.

   If the device supports the #startup capability, the current
   configuration can be saved to the startup configuration by using the
   startup configuration as the target of the <copy-config> operation.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <copy-config>
         <source>
           <running></running>
         </source>
         <target>
           <startup></startup>
         </target>
         <format>text</format>
       </copy-config>
     </rpc>




Enns, Editor            Expires August 13, 2003                [Page 74]

Internet-Draft              XMLCONF Protocol               February 2003


   If the device supports the #candidate capability and a confirmed
   commit was requested, the confirming commit must be send before the
   timeout expires.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <commit></commit>
     </rpc>


B.1.8 Releasing the Configuration Lock

   When the configuration update is complete, the lock must be released,
   allowing other applications access to the configuration.

   Use the <unlock> operation to release the configuration lock.

     <rpc xmlns="http://ietf.org/xmlconf/1.0/base">
       <unlock></unlock>
     </rpc>


B.2 Operations Against Multiple Devices

   When a configuration change requires updates across a number of
   devices, care should be taken to provide the required transaction
   semantics.  The XMLCONF protocol contains sufficient primitives upon
   which transaction-oriented operations can be built.  Providing
   complete transactional semantics across multiple devices is
   prohibitively expensive, but the size and number of windows for
   failure scenarios can be reduced.

   There are two classes of multi-device operations.  The first class of
   multi-device operations allows the operation to fail on individual
   devices without requiring all devices to revert to their original
   state.  The operation can be retried at a later time, or its failure
   simply reported to the user.  A example of this class might be adding
   an NTP server.  For this class of operations, failure avoidance and
   recovery are focused on the individual device.  This means recovery
   of the device, reporting the failure, and perhaps rescheduling
   another attempt.

   The second class is more interesting.  This class requires that the
   operation should complete on all devices or be fully reversed.  The
   network should either be transformed into a new state or be reset to
   its original state.  For example, a change to a VPN may require
   updates to a number of devices.  Another example of this might be
   adding a Class Of Service (COS) definition.  Leaving the network in a
   state where only a portion of the devices have been updated with the



Enns, Editor            Expires August 13, 2003                [Page 75]

Internet-Draft              XMLCONF Protocol               February 2003


   new definition will lead to future failures when the definition is
   referenced.

   To give transactional semantics, the same steps used in single device
   operations listed above are used, but are performed in parallel
   across all devices.  Configuration locks should be acquired on all
   target devices and kept until all devices are updated and the changes
   made permanent.  Configuration changes should be uploaded and
   validation performed across all devices.  Checkpoints should be made
   on each device.  Then the running configuration can be changed,
   tested, and made permanent.  If any of these steps fail, the previous
   configurations can be restored on any devices upon which it was
   changed.  After the changes have been completely implemented or
   completely discarded, the locks on each device can be released.





































Enns, Editor            Expires August 13, 2003                [Page 76]

Internet-Draft              XMLCONF Protocol               February 2003


Intellectual Property Statement

   The IETF takes no position regarding the validity or scope of any
   intellectual property or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; neither does it represent that it
   has made any effort to identify any such rights.  Information on the
   IETF's procedures with respect to rights in standards-track and
   standards-related documentation can be found in BCP-11.  Copies of
   claims of rights made available for publication and any assurances of
   licenses to be made available, or the result of an attempt made to
   obtain a general license or permission for the use of such
   proprietary rights by implementors or users of this specification can
   be obtained from the IETF Secretariat.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights which may cover technology that may be required to practice
   this standard.  Please address the information to the IETF Executive
   Director.


Full Copyright Statement

   Copyright (C) The Internet Society (2003).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assignees.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION



Enns, Editor            Expires August 13, 2003                [Page 77]

Internet-Draft              XMLCONF Protocol               February 2003


   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.


Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.











































Enns, Editor            Expires August 13, 2003                [Page 78]