Subject: Re: [Netconf] evaluation of the partial-lock document

From: Balazs Lengyel <[email-masked]>
Date: Mon, 08 Sep 2008 17:04:12 +0200

Hello Wes, Bert,
Thanks for the review. Please see the answers for Wes below!

If you have a look of the attached version, you can see that I also included Bert's comments. I 
basically accepted them all e.g. I added a list of locked-nodes to the rpc-reply.

Please indicate if you still have problems with some of the issues.
Balazs

Wes Hardaker wrote:
> * My final thoughts and concerns on the partial-lock feature as
>   a whole are in the last section of this...
> 
> 
>              Netconf WG last call report on partial lock
>              ===========================================
> 
> Author: Wes Hardaker <[email-masked]>
> Date: 2008-08-26 16:50:09 PDT
> 
>From [email-masked]  Mon Sep  8 08:04:18 2008
Date: Mon, 08 Sep 2008 17:04:12 +0200
From: Balazs Lengyel <[email-masked]>
To: Wes Hardaker <[email-masked]>, 
	Bert Wijnen - IETF <[email-masked]>,
	netconf mailing list <[email-masked]>
Subject: Re: [Netconf] evaluation of the partial-lock document
Sender: [email-masked]

This is a multi-part message in MIME format.

Hello Wes, Bert,
Thanks for the review. Please see the answers for Wes below!

If you have a look of the attached version, you can see that I also included Bert's comments. I 
basically accepted them all e.g. I added a list of locked-nodes to the rpc-reply.

Please indicate if you still have problems with some of the issues.
Balazs

Wes Hardaker wrote:
> * My final thoughts and concerns on the partial-lock feature as
>   a whole are in the last section of this...
> 
> 
>              Netconf WG last call report on partial lock
>              ===========================================
> 
> Author: Wes Hardaker <[email-masked]>
> Date: 2008-08-26 16:50:09 PDT
> 
> Table Table of Contents
> =================
> 1 General Notes
> 2 Thoughts on: Partial locks don't cover non-existing nodes
> 3 section 2.1: "Note:" wording
> 4 section 2.1, starting with "As with most locking..."
> 5 Question about multiple locks from the same session...
> 6 Section 2.4.1.1: target:
> 7 Section 2.4.1.1: text change
> 8 Section 2.4.1.1: first example
> 9 Side thought: netconf documents all assume a particular data model
> 10 Section 2.4.1.1: 2nd to last paragraph:
> 11 Section 2.4.2:
> 12 Section 2.4.2, negative response:
> 13 Section 2.5
> 14 Section 3, second paragraph: first sentence needs ()s or commas
> 15 Comparison of xpath evaluated partial lock vs locked nodes
> 
> 
> 
> 1 General Notes
> ---------------
> * Document is very well layed out and easy to understand.
>   It flows well and is easy to read.
> * But...  The English grammar could use some polishing in a few
>   more places than I've listed here.
>   + I'd recommend the authors hand it to someone that hasn't
>     been involved in editing for a simple polishing pass.
[BALAZS]: Will try.
> * My final thoughts and concerns on the partial-lock feature as
>   a whole are in the last section of this...
> 
> 2 Thoughts on: Partial locks don't cover non-existing nodes
> -----------------------------------------------------------
>       * (Section 2.4.1-ish)
> * note: can't lock a tree part that doesn't exist yet
> * There exists odd an usage case when a tree doesn't yet exist
>   (empty configuration). E.G., I can't lock the users tree until
>   at least 1 users/user exists.  If I try to lock <users> when
>   no subelement exists then I believe I get an error back (I'm
>   not even positive about this).  Section 2.4.1 seems to
>   indicate that it'll fail since at least one of the select sets
>   MUST be non-empty.
>   + The result is that you *must* create a single <user> before
>     you can lock the <users> table, for example.  IE a manager
>     is expected to be able to perform and understand why it's
>     doing the following odd sequence:
>     - partial-lock <users>   => failure because it's empty.
>     - create a <users><user><name>joe</name></user></users>
>     - partial-lock <users>   => success
>     - Edit users
>     - unlock
>   + This is just an odd error handling case that manegers will
>     have to cope with and it only exists because of the
>     inability to lock an empty tree.
> * Section 2.4.1.2 discusses this aspect of partial-locking, but
>   the security implications may be that you don't have
>   permission to lock a parent node of <users> for exmaple.  IE,
>   You shouldn't have to take out lock on <top> just because you
>   want to lock <users> (and you shouldn't have to create a user
>   before you can lock the table).
[BALAZS]:
I am not sure I fully understand your comment, but here is what I think is the answer (in YANG
to makes think simpler :-)

If you have a data model:

container USERS {
    list user {
       ...
    }
}

Here you CAN lock the container USERS even if there are no user nodes below it. The select will
return the USERS node, so it will not be empty. In this case no one else can touch any of the
user nodes or create a new user.
> 
> 3 section 2.1: "Note:" wording
> ------------------------------
> * First sentence isn't a complete sentence
> * I'd argue this isn't just a "Note" but an interaction with
>   another capability and probably should be spelled out more
>   importantly than just as a "Note:" that implies it's just
>   additional information.
[BALAZS]: OK, moved it to 2.6.2 Interactions with Other Capabilities / Candidate Configuration
Capability
> 
> 4 section 2.1, starting with "As with most locking..."
> ------------------------------------------------------
> * Change:
> * "parts of the configuration become dead-locked" =>
> * "parts of the configuration *could* become dead-locked"
[BALAZS]: OK
> 
> 5 Question about multiple locks from the same session...
> --------------------------------------------------------
> * Is it allowed?  Doesn't say one way or another... 
> * Consider:
>   of Contents
> =================
> 1 General Notes
> 2 Thoughts on: Partial locks don't cover non-existing nodes
> 3 section 2.1: "Note:" wording
> 4 section 2.1, starting with "As with most locking..."
> 5 Question about multiple locks from the same session...
> 6 Section 2.4.1.1: target:
> 7 Section 2.4.1.1: text change
> 8 Section 2.4.1.1: first example
> 9 Side thought: netconf documents all assume a particular data model
> 10 Section 2.4.1.1: 2nd to last paragraph:
> 11 Section 2.4.2:
> 12 Section 2.4.2, negative response:
> 13 Section 2.5
> 14 Section 3, second paragraph: first sentence needs ()s or commas
> 15 Comparison of xpath evaluated partial lock vs locked nodes
> 
> 
> 
> 1 General Notes
> ---------------
> * Document is very well layed out and easy to understand.
>   It flows well and is easy to read.
> * But...  The English grammar could use some polishing in a few
>   more places than I've listed here.
>   + I'd recommend the authors hand it to someone that hasn't
>     been involved in editing for a simple polishing pass.
[BALAZS]: Will try.
> * My final thoughts and concerns on the partial-lock feature as
>   a whole are in the last section of this...
> 
> 2 Thoughts on: Partial locks don't cover non-existing nodes
> -----------------------------------------------------------
>       * (Section 2.4.1-ish)
> * note: can't lock a tree part that doesn't exist yet
> * There exists odd an usage case when a tree doesn't yet exist
>   (empty configuration). E.G., I can't lock the users tree until
>   at least 1 users/user exists.  If I try to lock <users> when
>   no subelement exists then I believe I get an error back (I'm
>   not even positive about this).  Section 2.4.1 seems to
>   indicate that it'll fail since at least one of the select sets
>   MUST be non-empty.
>   + The result is that you *must* create a single <user> before
>     you can lock the <users> table, for example.  IE a manager
>     is expected to be able to perform and understand why it's
>     doing the following odd sequence:
>     - partial-lock <users>   => failure because it's empty.
>     - create a <users><user><name>joe</name></user></users>
>     - partial-lock <users>   => success
>     - Edit users
>     - unlock
>   + This is just an odd error handling case that manegers will
>     have to cope with and it only exists because of the
>     inability to lock an empty tree.
> * Section 2.4.1.2 discusses this aspect of partial-locking, but
>   the security implications may be that you don't have
>   permission to lock a parent node of <users> for exmaple.  IE,
>   You shouldn't have to take out lock on <top> just because you
>   want to lock <users> (and you shouldn't have to create a user
>   before you can lock the table).
[BALAZS]:
I am not sure I fully understand your comment, but here is what I think is the answer (in YANG
to makes think simpler :-)

If you have a data model:

container USERS {
    list user {
       ...
    }
}

Here you CAN lock the container USERS even if there are no user nodes below it. The select will
return the USERS node, so it will not be empty. In this case no one else can touch any of the
user nodes or create a new user.
> 
> 3 section 2.1: "Note:" wording
> ------------------------------
> * First sentence isn't a complete sentence
> * I'd argue this isn't just a "Note" but an interaction with
>   another capability and probably should be spelled out more
>   importantly than just as a "Note:" that implies it's just
>   additional information.
[BALAZS]: OK, moved it to 2.6.2 Interactions with Other Capabilities / Candidate Configuration
Capability
> 
> 4 section 2.1, starting with "As with most locking..."
> ------------------------------------------------------
> * Change:
> * "parts of the configuration become dead-locked" =>
> * "parts of the configuration *could* become dead-locked"
[BALAZS]: OK
> 
> 5 Question about multiple locks from the same session...
> --------------------------------------------------------
> * Is it allowed?  Doesn't say one way or another... 
> * Consider:
>   1. lo 1. lock with one partial nodes A and B
>   2. and then with another try to lock B and C
>   3. Do I get an error because B is locked (by me in this session)?
>   4. or now do I have multiple locks covering A, B and C?
> * I *think* I get an error?
> * If I do have A, B and C locked:
>   + and then I release the lock
>   + do I still have B and C locked with the second or just C
>     (I'd assume B and C)?
> * The document discusses this ramification for <lock> but not
>   really well for <partial-lock>
> * It sort of implies an error further in 2.4.1.1 "If a lock is
>   already held on any node..."
[BALAZS]: It is allowed to have multiple locks from the same session. In 2.4.1.1 will be
reworded to indicate this. In 2.1 it is stated that:
"A NETCONF session MAY have multiple parts of one or more datastores
     (running, candidate,startup) locked using partial lock operations.
     The <partial-lock> operation returns a lock-id to identify each
     successfully acquired lock."
Indicating that a session might have multiple locks.
I will also add to 2.4.1:
A NETCONF server MUST be able to grant multiple simultaneous partial locks to a single NETCONF
session. If the scope of the individual locks overlap, nodes in the common area MUST be locked
until all of the locks are released.
> 
> 6 Section 2.4.1.1: target:
> --------------------------
> * Wouldn't it be best to state directly: "a <partial-lock> may
>   only have one <target> parameter?"
[BALAZS]: OK
> 
> 7 Section 2.4.1.1: text change
> ------------------------------
> * "If the device supports the :xpath capability as well any valid" =>
> * "If the device supports the :xpath capability *then* any valid"
[BALAZS]: OK
> 
> 8 Section 2.4.1.1: first example
> --------------------------------
> * Shouldn't <nt:running/> be within a <target> scope?
> * The schema seems to indicate no
> * But it should (IMHO) if nothing else to match <lock> usage
>   which does have a <target> parameter.
>   + (if memory serves this was discussed early on in netconf and
>     it was agreed that all targets should be directly specified
>     inside a named <target> or similar parameter tag)
[BALAZS]: OK
> 
> 9 Side thought: netconf documents all assume a particular data model
> --------------------------------------------------------------------
> * Is it just me, or should all the netconf documents be replaced
>   once a real data model exists with real example nodes to use?
> * Right now all the examples give the impression that the example
>   RPCs will work, when in actuality they won't match the real
>   world data models.
>   + EG: /interfaces/interface[Id='eth1']
[BALAZS]: This is just an example no more. IMHO we simply can not avoid assuming some data
model for now. I agree, it would be nice to later include real examples from standard modules;
   whether we will have the time for that?
> 
> 10 Section 2.4.1.1: 2nd to last paragraph:
> ------------------------------------------
> * Explicitly spelling out an xpath failure is nice to
>   understand.  But in reality this should be more generic in
>   order to handle failing on future select type expressions
>   (xpath2) or other syntax errors.  Maybe something like "search
>   expression type not supported"?
[BALAZS]: I would like to be explicit here. If we introduce Xpath2 later we will anyway have to
update the RFC, and I don't see how that update would cause problems for a management system.
Once it gets the error it will anyway know it failed.
>   + What type of error do I get back for /users/user[name='Joe
[BALAZS]: Tag: invalid-value
> 
> 11 Section 2.4.2:
> -----------------
> * Nit: Replace "Example: Unlock" with "Example: Unlock a
>   previously created lock"
>   + or just remove: "Unlock"
>   + The title just looks a touch odd as is (incomplete).
[BALAZS]: OK
> 
> 12 Section 2.4.2, negative response:
> ------------------------------------
> * So there is no way to break a lock from a different session?
>   Then what happens if a TCP connection drops according to the
>   client (or is forced to drop) but the server hasn't realck with one partial nodes A and B
>   2. and then with another try to lock B and C
>   3. Do I get an error because B is locked (by me in this session)?
>   4. or now do I have multiple locks covering A, B and C?
> * I *think* I get an error?
> * If I do have A, B and C locked:
>   + and then I release the lock
>   + do I still have B and C locked with the second or just C
>     (I'd assume B and C)?
> * The document discusses this ramification for <lock> but not
>   really well for <partial-lock>
> * It sort of implies an error further in 2.4.1.1 "If a lock is
>   already held on any node..."
[BALAZS]: It is allowed to have multiple locks from the same session. In 2.4.1.1 will be
reworded to indicate this. In 2.1 it is stated that:
"A NETCONF session MAY have multiple parts of one or more datastores
     (running, candidate,startup) locked using partial lock operations.
     The <partial-lock> operation returns a lock-id to identify each
     successfully acquired lock."
Indicating that a session might have multiple locks.
I will also add to 2.4.1:
A NETCONF server MUST be able to grant multiple simultaneous partial locks to a single NETCONF
session. If the scope of the individual locks overlap, nodes in the common area MUST be locked
until all of the locks are released.
> 
> 6 Section 2.4.1.1: target:
> --------------------------
> * Wouldn't it be best to state directly: "a <partial-lock> may
>   only have one <target> parameter?"
[BALAZS]: OK
> 
> 7 Section 2.4.1.1: text change
> ------------------------------
> * "If the device supports the :xpath capability as well any valid" =>
> * "If the device supports the :xpath capability *then* any valid"
[BALAZS]: OK
> 
> 8 Section 2.4.1.1: first example
> --------------------------------
> * Shouldn't <nt:running/> be within a <target> scope?
> * The schema seems to indicate no
> * But it should (IMHO) if nothing else to match <lock> usage
>   which does have a <target> parameter.
>   + (if memory serves this was discussed early on in netconf and
>     it was agreed that all targets should be directly specified
>     inside a named <target> or similar parameter tag)
[BALAZS]: OK
> 
> 9 Side thought: netconf documents all assume a particular data model
> --------------------------------------------------------------------
> * Is it just me, or should all the netconf documents be replaced
>   once a real data model exists with real example nodes to use?
> * Right now all the examples give the impression that the example
>   RPCs will work, when in actuality they won't match the real
>   world data models.
>   + EG: /interfaces/interface[Id='eth1']
[BALAZS]: This is just an example no more. IMHO we simply can not avoid assuming some data
model for now. I agree, it would be nice to later include real examples from standard modules;
   whether we will have the time for that?
> 
> 10 Section 2.4.1.1: 2nd to last paragraph:
> ------------------------------------------
> * Explicitly spelling out an xpath failure is nice to
>   understand.  But in reality this should be more generic in
>   order to handle failing on future select type expressions
>   (xpath2) or other syntax errors.  Maybe something like "search
>   expression type not supported"?
[BALAZS]: I would like to be explicit here. If we introduce Xpath2 later we will anyway have to
update the RFC, and I don't see how that update would cause problems for a management system.
Once it gets the error it will anyway know it failed.
>   + What type of error do I get back for /users/user[name='Joe
[BALAZS]: Tag: invalid-value
> 
> 11 Section 2.4.2:
> -----------------
> * Nit: Replace "Example: Unlock" with "Example: Unlock a
>   previously created lock"
>   + or just remove: "Unlock"
>   + The title just looks a touch odd as is (incomplete).
[BALAZS]: OK
> 
> 12 Section 2.4.2, negative response:
> ------------------------------------
> * So there is no way to break a lock from a different session?
>   Then what happens if a TCP connection drops according to the
>   client (or is forced to drop) but the server hasn't realized
>ized
>   it's closed?
>   + Looks like kill-session is the solution based on later reading,
>     but I'd suggest spelling it out here.
>   + Requires access to the kill-session command to release a
>     hung-lock.  Possibly worth mentioning in the security
>     expectations.
[BALAZS}: OK
> 
> 13 Section 2.5
> --------------
> * I'd spell out in no uncertain terms that any command that
>   modifies a datastore will be blocked, and that "includes" the
>   current list.  The wording as is could be easily
>   misinterpreted to read that the current list is all you need
>   to worry about (which I know wasn't the intent).
[BALAZS}: OK
> 
> 14 Section 3, second paragraph: first sentence needs ()s or commas
> ------------------------------------------------------------------
>       around the lock types.
[BALAZS}: OK
> 
> 15 Comparison of xpath evaluated partial lock vs locked nodes
> -------------------------------------------------------------
> * I'm not personally convienced still that locking existing
>   nodes only is the best solution for partial locking.  I know
>   it's been debated a bunch in the past but I'm not even
>   convienced there is consusus on the subject.  I suspect that
>   if you counted the number of folks that started an argument
>   about it the numbers wouldn't point clearly to a consensus.
>   Many of the arguments came at different times, which makes it
>   hard to count.
>   + That being said, letting this one go forward doesn't
>     prohibit a different later solution.
[BALAZS}: IMHO we did reach consensus on the issue, but anyway I am glad to see that you can
still live with this solution.
>   + I'm not convienced that locking nodes is cheaper to
>     implement or execute than evaluating edits based on a
>     memorized xpath solution.
> * Comparison:
>   * XPATH eval:
>     + easier to list in a "list of outstanding locks" table
>     + storage cost is very small (a list of xpaths)
>     + CPU usage is higher (An eval on every command is required)
>     + I think it's more intuitive...  There isn't an unknown "it's
>     no longer locked because you deleted it" sudden surprise.
>   * locking a list of nodes with a eval-once:
>     + Lower CPU usage since it's a single xpath eval
>     - Higher memory cost (need to memorize every locked node
>       either through a list or a flag)
>     - Usage complexity is much higher
>       - Can't lock empty parent nodes
>       - security ramifications require parent nodes for *everything*
>       - deleted nodes can be recreated
>         * This is most critical when manipulating ordered lists of
>           things like access rules (eg, firewall rules)
> * I've seen real-world current discussions surrounding the need
>   to put in a parent tree for all nodes *just* because of the
>   partial-lock inability to lock a common set of nodes.  The
>   result of this type of partical lock means either:
>   + data models will add extra tree nodes everywhere
>   + Or they wont' and it'll turn out later they should have
>     because of opreational needs for locking all the subnodes
>     and it can't be done.
>     - IE, it becomes critical to create a <rules> node to
>       surround a list of firewall <rule> nodes.
>    + I think it's worth spelling out this issue in the security
>      considerations so that every data model ever created gets a
>      otherwise-empty top node added above it so that it can be locked.
[BALAZS}: In my eyes the deciding factor is avoiding surprises.
XPATH surprise 1:
I have a user: John OConnor. I lock him based on his name. Later I correct his name to John
O'Connor. Whoops suddenly he is not locked. (The name might not even be the key attribute/leaf).
XPATH surprise 2:
We use XPATH:   and "preceding-sibling::*". I modify some data in my locked nodes. The order of
the nodes might be modified by the modifying their content in the datastore (e.g. modifying a
leaf called "priority"). Due to the change in priority some nodes that were previously locked
suddenly become unlocked.
XPATH surprise 3:
I know I have 3 users: Jack and J   it's closed?
>   + Looks like kill-session is the solution based on later reading,
>     but I'd suggest spelling it out here.
>   + Requires access to the kill-session command to release a
>     hung-lock.  Possibly worth mentioning in the security
>     expectations.
[BALAZS}: OK
> 
> 13 Section 2.5
> --------------
> * I'd spell out in no uncertain terms that any command that
>   modifies a datastore will be blocked, and that "includes" the
>   current list.  The wording as is could be easily
>   misinterpreted to read that the current list is all you need
>   to worry about (which I know wasn't the intent).
[BALAZS}: OK
> 
> 14 Section 3, second paragraph: first sentence needs ()s or commas
> ------------------------------------------------------------------
>       around the lock types.
[BALAZS}: OK
> 
> 15 Comparison of xpath evaluated partial lock vs locked nodes
> -------------------------------------------------------------
> * I'm not personally convienced still that locking existing
>   nodes only is the best solution for partial locking.  I know
>   it's been debated a bunch in the past but I'm not even
>   convienced there is consusus on the subject.  I suspect that
>   if you counted the number of folks that started an argument
>   about it the numbers wouldn't point clearly to a consensus.
>   Many of the arguments came at different times, which makes it
>   hard to count.
>   + That being said, letting this one go forward doesn't
>     prohibit a different later solution.
[BALAZS}: IMHO we did reach consensus on the issue, but anyway I am glad to see that you can
still live with this solution.
>   + I'm not convienced that locking nodes is cheaper to
>     implement or execute than evaluating edits based on a
>     memorized xpath solution.
> * Comparison:
>   * XPATH eval:
>     + easier to list in a "list of outstanding locks" table
>     + storage cost is very small (a list of xpaths)
>     + CPU usage is higher (An eval on every command is required)
>     + I think it's more intuitive...  There isn't an unknown "it's
>     no longer locked because you deleted it" sudden surprise.
>   * locking a list of nodes with a eval-once:
>     + Lower CPU usage since it's a single xpath eval
>     - Higher memory cost (need to memorize every locked node
>       either through a list or a flag)
>     - Usage complexity is much higher
>       - Can't lock empty parent nodes
>       - security ramifications require parent nodes for *everything*
>       - deleted nodes can be recreated
>         * This is most critical when manipulating ordered lists of
>           things like access rules (eg, firewall rules)
> * I've seen real-world current discussions surrounding the need
>   to put in a parent tree for all nodes *just* because of the
>   partial-lock inability to lock a common set of nodes.  The
>   result of this type of partical lock means either:
>   + data models will add extra tree nodes everywhere
>   + Or they wont' and it'll turn out later they should have
>     because of opreational needs for locking all the subnodes
>     and it can't be done.
>     - IE, it becomes critical to create a <rules> node to
>       surround a list of firewall <rule> nodes.
>    + I think it's worth spelling out this issue in the security
>      considerations so that every data model ever created gets a
>      otherwise-empty top node added above it so that it can be locked.
[BALAZS}: In my eyes the deciding factor is avoiding surprises.
XPATH surprise 1:
I have a user: John OConnor. I lock him based on his name. Later I correct his name to John
O'Connor. Whoops suddenly he is not locked. (The name might not even be the key attribute/leaf).
XPATH surprise 2:
We use XPATH:   and "preceding-sibling::*". I modify some data in my locked nodes. The order of
the nodes might be modified by the modifying their content in the datastore (e.g. modifying a
leaf called "priority"). Due to the change in priority some nodes that were previously locked
suddenly become unlocked.
XPATH surprise 3:
I know I have 3 users: Jack and Jill anill and John. I store my users in alphabetical order. I want
to lock John so I use from XPATH: "position() = 3" Now another operator comes and adds user
Blaise. Suddenly I am locking  Jill instead of John.
XPATH surprise 4:
Using an XPATH that includes state data or any configuration data that is not itself locked is
just asking for disaster.

Probably a many more strange XPATH expressions could be designed.

regards Balazs

NETCONF                                                       B. Lengyel
Internet-Draft                                          Ericsson Hungary
Intended status: Standards Track                            M. Bjorklund
Expires: March 12, 2009                                   Tail-f Systems
                                                      September 08, 2008

                      Partial Lock RPC for NETCONF
                   draft-ietf-netconf-partial-lock-04

Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.

   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 March 12, 2009.

Copyright Notice

   Copyright (C) The IETF Trust (2008).

Abstract

   The NETCONF protocol defines the lock and unlock RPCs that lock
   entire configuration datastores.  In some situations, a way to lock
   only parts of a configuration datastore is required.  This document
   defines a capability-based extension to the NETCONF protocol for
   locking portions of a configuration datastore.

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 1]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Definition of Terms  . . . . . . . . . . . . . . . . . . .  3
   2.  Partial Locking Capability . . . . . . . . . . . . . . . . . .  3
     2.1.  Overview . . . . . . . . . . . . . . . . . . . . . . . . .  3
     2.2.  Dependencies . . . . . . . . . . . . . . . . . . . . . . .  4
     2.3.  Capability Identifier  . . . . . . . . . . . . . . . . . .  4
     2.4.  New Operations . . . . . . . . . . . . . . . . . . . . . .  4
       2.4.1.  <partial-lock> . . . . . . . . . . . . . . . . . . . .  4
       2.4.2.  <partial-unlock> . . . . . . . . . . . . . . . . . . .  8
     2.5.  Modifications to Existing Operations . . . . . . . . . . .  9
     2.6.  Interactions with Other Capabilities . . . . . . . . . . .  9
       2.6.1.  Writable-Running Capability  . . . . . . . . . . . . .  9
       2.6.2.  Candidate Configuration Capability . . . . . . . . . .  9
       2.6.3.  Distinct Startup Capability  . . . . . . . . . . . . . 10
   3.  Security Considerations  . . . . . . . . . . . . . . . . . . . 10
   4.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 11
   5.  Appendix A  -  XML Schema for Partial Locking  (normative) . . 12
   6.  Appendix B  - YANG Module for Partial Locking
       (non-normative)  . . . . . . . . . .d John. I store my users in alphabetical order. I want
to lock John so I use from XPATH: "position() = 3" Now another operator comes and adds user
Blaise. Suddenly I am locking  Jill instead of John.
XPATH surprise 4:
Using an XPATH that includes state data or any configuration data that is not itself locked is
just asking for disaster.

Probably a many more strange XPATH expressions could be designed.

regards Balazs

NETCONF                                                       B. Lengyel
Internet-Draft                                          Ericsson Hungary
Intended status: Standards Track                            M. Bjorklund
Expires: March 12, 2009                                   Tail-f Systems
                                                      September 08, 2008

                      Partial Lock RPC for NETCONF
                   draft-ietf-netconf-partial-lock-04

Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.

   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 March 12, 2009.

Copyright Notice

   Copyright (C) The IETF Trust (2008).

Abstract

   The NETCONF protocol defines the lock and unlock RPCs that lock
   entire configuration datastores.  In some situations, a way to lock
   only parts of a configuration datastore is required.  This document
   defines a capability-based extension to the NETCONF protocol for
   locking portions of a configuration datastore.

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 1]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Definition of Terms  . . . . . . . . . . . . . . . . . . .  3
   2.  Partial Locking Capability . . . . . . . . . . . . . . . . . .  3
     2.1.  Overview . . . . . . . . . . . . . . . . . . . . . . . . .  3
     2.2.  Dependencies . . . . . . . . . . . . . . . . . . . . . . .  4
     2.3.  Capability Identifier  . . . . . . . . . . . . . . . . . .  4
     2.4.  New Operations . . . . . . . . . . . . . . . . . . . . . .  4
       2.4.1.  <partial-lock> . . . . . . . . . . . . . . . . . . . .  4
       2.4.2.  <partial-unlock> . . . . . . . . . . . . . . . . . . .  8
     2.5.  Modifications to Existing Operations . . . . . . . . . . .  9
     2.6.  Interactions with Other Capabilities . . . . . . . . . . .  9
       2.6.1.  Writable-Running Capability  . . . . . . . . . . . . .  9
       2.6.2.  Candidate Configuration Capability . . . . . . . . . .  9
       2.6.3.  Distinct Startup Capability  . . . . . . . . . . . . . 10
   3.  Security Considerations  . . . . . . . . . . . . . . . . . . . 10
   4.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 11
   5.  Appendix A  -  XML Schema for Partial Locking  (normative) . . 12
   6.  Appendix B  - YANG Module for Partial Locking
       (non-normative)  . . . . . . . . . . . . . . . . . . . . . . . . . . 14
   7.  Appendix C  -  Change Log  . . . . . . . . . . . . . . . . . . 16
     7.1.  03-04  . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     7.2.  02-03  . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     7.3.  01-02  . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     7.4.  00-01  . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     7.5.  -00  . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
   8.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17
   9.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 18
     9.1.  Normative References . . . . . . . . . . . . . . . . . . . 18
     9.2.  Informative References . . . . . . . . . . . . . . . . . . 18
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19
   Intellectual Property and Copyright Statements . . . . . . . . . . 20

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 2]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

1.  Introduction

   The NETCONF protocol [NETCONF] describes the lock and unlock RPCs
   that operate on entire configuration datastores.  Often, multiple
   management sessions need to be able to modify the configuration of a
   managed device in parallel.  In these cases, locking only parts of a
   configuration datastore is needed.  This document defines an
   extension to the NETCONF protocol to allow this.

   The mechanism for partial locking is based on the existing XPath
   filtering mechanisms.

   Partial locking is defined as a capability to NETCONF.

1.1.  Definition of Terms

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14, [RFC2119].

2.  Partial Locking Capability

2.1.  Overview

   The :partial-lock capability indicates that the device supports the
   locking of its configuration with a scope smaller then a complete
   configuration datastore.  The scope to be locked is specified by
   using restricted or full XPath expressions.  Partial locking covers
   configuration data, but not state data.

   The system MUST ensure that configuration resources covered by the
   lock are not modified by other NETCONF or non-NETCONF management
   operations such as SNMP and the CLI.

   The duration of the partial lock is defined as beginning when the
   partial lock is granted.  The partial lock lasts until either the
   corresponding <partial-unlock> operation succeeds or the NETCONF
   session terminates.

   A NETCONF session MAY have multiple parts of one or more datastores
   (running, candidate,startup) locked using partial lock operations.
   The <partial-lock> operation returns a lock-id to identify each
   successfully acquired lock.

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 3]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

2.2.  Dependencies

   The device MUST support the restricted XPath expressions in the
   select element, as described in Section 2.4.1.  If optionally the
   :xpath capability is also supported, the device MUST also support the
   usage of any XPath 1.0 expression in the select element.

2.3.  Capability Identifier

   urn:ietf:params:netconf:capability:partial-lock:1.0

2.4.  New Operations

2.4.1.  <partial-lock>

   The <partial-lock> operation allows the client to lock a portion of a
   data store.  The portion to lock is specified by using XPath
   expressions in the select elements of the <partial-lock> operation.
   Each XPath expression MUST return a node set.  Locking a node
   protects the complete subtree under it from modification by others.

   The select XPath expressions are evaluated only once at lock time,
   thereafter the scope of the lock is maintained as a set of nodes.  If
   the configuration data is later altered in a way that would make the
   original select XPath expressi . . . . . . . . . . 14
   7.  Appendix C  -  Change Log  . . . . . . . . . . . . . . . . . . 16
     7.1.  03-04  . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     7.2.  02-03  . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     7.3.  01-02  . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     7.4.  00-01  . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     7.5.  -00  . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
   8.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17
   9.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 18
     9.1.  Normative References . . . . . . . . . . . . . . . . . . . 18
     9.2.  Informative References . . . . . . . . . . . . . . . . . . 18
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19
   Intellectual Property and Copyright Statements . . . . . . . . . . 20

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 2]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

1.  Introduction

   The NETCONF protocol [NETCONF] describes the lock and unlock RPCs
   that operate on entire configuration datastores.  Often, multiple
   management sessions need to be able to modify the configuration of a
   managed device in parallel.  In these cases, locking only parts of a
   configuration datastore is needed.  This document defines an
   extension to the NETCONF protocol to allow this.

   The mechanism for partial locking is based on the existing XPath
   filtering mechanisms.

   Partial locking is defined as a capability to NETCONF.

1.1.  Definition of Terms

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14, [RFC2119].

2.  Partial Locking Capability

2.1.  Overview

   The :partial-lock capability indicates that the device supports the
   locking of its configuration with a scope smaller then a complete
   configuration datastore.  The scope to be locked is specified by
   using restricted or full XPath expressions.  Partial locking covers
   configuration data, but not state data.

   The system MUST ensure that configuration resources covered by the
   lock are not modified by other NETCONF or non-NETCONF management
   operations such as SNMP and the CLI.

   The duration of the partial lock is defined as beginning when the
   partial lock is granted.  The partial lock lasts until either the
   corresponding <partial-unlock> operation succeeds or the NETCONF
   session terminates.

   A NETCONF session MAY have multiple parts of one or more datastores
   (running, candidate,startup) locked using partial lock operations.
   The <partial-lock> operation returns a lock-id to identify each
   successfully acquired lock.

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 3]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

2.2.  Dependencies

   The device MUST support the restricted XPath expressions in the
   select element, as described in Section 2.4.1.  If optionally the
   :xpath capability is also supported, the device MUST also support the
   usage of any XPath 1.0 expression in the select element.

2.3.  Capability Identifier

   urn:ietf:params:netconf:capability:partial-lock:1.0

2.4.  New Operations

2.4.1.  <partial-lock>

   The <partial-lock> operation allows the client to lock a portion of a
   data store.  The portion to lock is specified by using XPath
   expressions in the select elements of the <partial-lock> operation.
   Each XPath expression MUST return a node set.  Locking a node
   protects the complete subtree under it from modification by others.

   The select XPath expressions are evaluated only once at lock time,
   thereafter the scope of the lock is maintained as a set of nodes.  If
   the configuration data is later altered in a way that would make the
   original select XPath expressions evons evaluate to a different set of
   nodes, this does not affect the scope of the partial lock.

   XPath is only used for the creation of the partial lock.
   Conceptually the scope of the lock is defined by the returned node
   set and not by the XPath expression.

   A <partial-lock> operation MUST be handled atomically by the NETCONF
   server.  The server either locks all requested parts of the data
   store or none; I.e. if during the operation one of the requested
   parts cannot be locked the server MUST unlock all parts that have
   been already locked during that operation.

   If a node is locked by a session, only that same session is able to
   modify that node or any node in the subtree underneath it.

   If a top level node of a locked subtree is deleted, any other session
   can recreate it, as it is not covered by the lock anymore.  If all
   top level nodes are deleted, the lock will still be present, however
   it's scope will become nil i.e. it will not cover any nodes.

   A NETCONF server MUST be able to grant multiple simultaneous partial
   locks to a single NETCONF session.  If the scope of the individual
   locks overlap, nodes in the common area MUST be locked until all of

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 4]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   the locks are released.

   A partial lock operation MUST fail if:

   o  Any NETCONF session (including the current session) owns the
      global lock on the datastore.

   o  Any part of the scope to be locked is already locked by another
      management session/protocol, including other NETCONF sessions
      using the <partial-lock> or any other non-NETCONF management
      method.

   o  The NETCONF server implements access control and the locking user
      does not have sufficient privileges, to all parts of the datastore
      section to be locked.  The exact handling of access rights is
      outside the scope of this document, but it is assumed that there
      is an access control system that MAY deny or allow the partial
      lock operation.

   Note: If partial lock is requested for the running datastore, and the
   NETCONF server implements the :confirmed-commit capability, and there
   was a recent confirmed <commit> operation, where the confirming
   <commit> operation has not been received.  In this case the lock MUST
   be denied, because if the confirmation does not arrive, the running
   datastore MUST be rolled back to its state before the commit, thus
   the NETCONF server might need to modify the configuration.

   As with most locking systems, there is a possibility that two
   management sessions trying to lock different parts of the
   configuration could become dead-locked.  To avoid this situation,
   clients SHOULD lock everything they need in one operation.  If that
   operation still fails, the client SHOULD back down, release any
   already acquired locks, and retry the procedure after some time
   interval.  The length of the interval should preferably be random to
   avoid repeated dead-locks when both (or all) clients back down and
   then repeat locking.

   It is the intention to keep partial-locking simple, so when a partial
   lock is executed you get what you asked for: a set of nodes that are
   locked for writing.  There are some other issues that are
   intentionally not addressed for the sake of simplicity:

   o  Locking does not affect read operations.

   o  If a part of a datastore is locked, this has no effect on any
      unlocked parts of the datastore.  If this is a problem e.g. the
      operator's changes depend on data values in the unlocked part of
      the datastore, the operator should include these values in the

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 5]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

      scope of the lock.

   o  An operator is allowed to edit the configuration both inside and
      outside the scope of a lock.  It is the operatoaluate to a different set of
   nodes, this does not affect the scope of the partial lock.

   XPath is only used for the creation of the partial lock.
   Conceptually the scope of the lock is defined by the returned node
   set and not by the XPath expression.

   A <partial-lock> operation MUST be handled atomically by the NETCONF
   server.  The server either locks all requested parts of the data
   store or none; I.e. if during the operation one of the requested
   parts cannot be locked the server MUST unlock all parts that have
   been already locked during that operation.

   If a node is locked by a session, only that same session is able to
   modify that node or any node in the subtree underneath it.

   If a top level node of a locked subtree is deleted, any other session
   can recreate it, as it is not covered by the lock anymore.  If all
   top level nodes are deleted, the lock will still be present, however
   it's scope will become nil i.e. it will not cover any nodes.

   A NETCONF server MUST be able to grant multiple simultaneous partial
   locks to a single NETCONF session.  If the scope of the individual
   locks overlap, nodes in the common area MUST be locked until all of

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 4]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   the locks are released.

   A partial lock operation MUST fail if:

   o  Any NETCONF session (including the current session) owns the
      global lock on the datastore.

   o  Any part of the scope to be locked is already locked by another
      management session/protocol, including other NETCONF sessions
      using the <partial-lock> or any other non-NETCONF management
      method.

   o  The NETCONF server implements access control and the locking user
      does not have sufficient privileges, to all parts of the datastore
      section to be locked.  The exact handling of access rights is
      outside the scope of this document, but it is assumed that there
      is an access control system that MAY deny or allow the partial
      lock operation.

   Note: If partial lock is requested for the running datastore, and the
   NETCONF server implements the :confirmed-commit capability, and there
   was a recent confirmed <commit> operation, where the confirming
   <commit> operation has not been received.  In this case the lock MUST
   be denied, because if the confirmation does not arrive, the running
   datastore MUST be rolled back to its state before the commit, thus
   the NETCONF server might need to modify the configuration.

   As with most locking systems, there is a possibility that two
   management sessions trying to lock different parts of the
   configuration could become dead-locked.  To avoid this situation,
   clients SHOULD lock everything they need in one operation.  If that
   operation still fails, the client SHOULD back down, release any
   already acquired locks, and retry the procedure after some time
   interval.  The length of the interval should preferably be random to
   avoid repeated dead-locks when both (or all) clients back down and
   then repeat locking.

   It is the intention to keep partial-locking simple, so when a partial
   lock is executed you get what you asked for: a set of nodes that are
   locked for writing.  There are some other issues that are
   intentionally not addressed for the sake of simplicity:

   o  Locking does not affect read operations.

   o  If a part of a datastore is locked, this has no effect on any
      unlocked parts of the datastore.  If this is a problem e.g. the
      operator's changes depend on data values in the unlocked part of
      the datastore, the operator should include these values in the

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 5]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

      scope of the lock.

   o  An operator is allowed to edit the configuration both inside and
      outside the scope of a lock.  It is the operator's rer's responsibility
      to lock all parts of the datastore that are crucial for a specific
      management action.

   Note: The <partial-lock> operation does not modify the global <lock>
   operation defined in the base NETCONF Protocol [NETCONF].  If part of
   a datastore is already locked by <partial-lock>, then a global lock
   for that datastore fails even if the global lock is attempted by the
   same NETCONF session which owns the partial-lock.

2.4.1.1.  Parameters, Result, Examples

   Parameters:

   target:  Name of the configuration datastore of which a part shall be
       locked.  One <partial-lock> operation can affect only one of the
       datastores, so only one <target> parameter is allowed.  URLs are
       not accepted.

   select:  One or more 'select' elements each containing an XPath
       expression.  The XPath expression is evaluated in a context where
       the context node is the root of the server's conceptual data
       model, and the set of namespace declarations are those in scope
       on the select element.

       The select expressions MUST each return a node set, and at least
       one of the node sets must be non-empty.

       If the device supports the :xpath capability then any valid XPath
       1.0 expression can be used, if not, the XPath expression MUST be
       limited to an Instance Identifier expression.  An Instance
       Identifier is an absolute path expression in abbreviated syntax,
       where predicates are used only to specify values for nodes
       defined as keys to distinguish multiple instances.

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 6]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   Example: Lock virtual router 1 and interface eth1

       <nc:rpc
         xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
         xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
         nc:message-id="135">
           <partial-lock>
               <nc:target>
                   <nc:running/>
               </nc:target>
               <select xmlns="http://example.com/ns/route">
                   /routing/virtualRouter[routerName='router1']
               </select>
               <select xmlns="http://example.com/ns/interface">
                   /interfaces/interface[id='eth1']
                </select>
            </partial-lock>
       </nc:rpc>

       <nc:rpc-reply
         xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
         xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
         nc:message-id="135">
           <nc:data>
               <lock-id>127</lock-id>
               <locked-node xmlns="http://example.com/ns/route">
                   /routing/virtualRouter[routerName='router1']
               </locked-node>
               <locked-node xmlns="http://example.com/ns/interface">
                   /interfaces/interface[id='eth1']
               </locked-node>
           </nc:data>
       </nc:rpc-reply>

   Positive Response:

   If the device was able to satisfy the request, an <rpc-reply> is sent
   with a <lock-id> element (lock identifier) in the <data> element.  A
   list of locked-nodes is also returned.

   Negative Response:

   If a lock is already held by another session on any node within the
   subtrees to be locked, the <error-tag> element is 'lock-denied' and
   the <error-info> element includes the <session-id> of the lock owner.
   If the lock is held by a non-NETCONF session, a <session-id> of 0

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 7]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   (zero) is included.  If needed the returned session-id may be used to
   <kill> the NETCONF session holding the lock.  The same error response
   is returned if the requesting session already holds the (global) lock
   for the same datastore.

   If the select expressions return an empty node set, the <error-tag>
   is 'operation-failed', and the <error-app-tag> is 'no-matches'.

   If any selecsponsibility
      to lock all parts of the datastore that are crucial for a specific
      management action.

   Note: The <partial-lock> operation does not modify the global <lock>
   operation defined in the base NETCONF Protocol [NETCONF].  If part of
   a datastore is already locked by <partial-lock>, then a global lock
   for that datastore fails even if the global lock is attempted by the
   same NETCONF session which owns the partial-lock.

2.4.1.1.  Parameters, Result, Examples

   Parameters:

   target:  Name of the configuration datastore of which a part shall be
       locked.  One <partial-lock> operation can affect only one of the
       datastores, so only one <target> parameter is allowed.  URLs are
       not accepted.

   select:  One or more 'select' elements each containing an XPath
       expression.  The XPath expression is evaluated in a context where
       the context node is the root of the server's conceptual data
       model, and the set of namespace declarations are those in scope
       on the select element.

       The select expressions MUST each return a node set, and at least
       one of the node sets must be non-empty.

       If the device supports the :xpath capability then any valid XPath
       1.0 expression can be used, if not, the XPath expression MUST be
       limited to an Instance Identifier expression.  An Instance
       Identifier is an absolute path expression in abbreviated syntax,
       where predicates are used only to specify values for nodes
       defined as keys to distinguish multiple instances.

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 6]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   Example: Lock virtual router 1 and interface eth1

       <nc:rpc
         xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
         xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
         nc:message-id="135">
           <partial-lock>
               <nc:target>
                   <nc:running/>
               </nc:target>
               <select xmlns="http://example.com/ns/route">
                   /routing/virtualRouter[routerName='router1']
               </select>
               <select xmlns="http://example.com/ns/interface">
                   /interfaces/interface[id='eth1']
                </select>
            </partial-lock>
       </nc:rpc>

       <nc:rpc-reply
         xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
         xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
         nc:message-id="135">
           <nc:data>
               <lock-id>127</lock-id>
               <locked-node xmlns="http://example.com/ns/route">
                   /routing/virtualRouter[routerName='router1']
               </locked-node>
               <locked-node xmlns="http://example.com/ns/interface">
                   /interfaces/interface[id='eth1']
               </locked-node>
           </nc:data>
       </nc:rpc-reply>

   Positive Response:

   If the device was able to satisfy the request, an <rpc-reply> is sent
   with a <lock-id> element (lock identifier) in the <data> element.  A
   list of locked-nodes is also returned.

   Negative Response:

   If a lock is already held by another session on any node within the
   subtrees to be locked, the <error-tag> element is 'lock-denied' and
   the <error-info> element includes the <session-id> of the lock owner.
   If the lock is held by a non-NETCONF session, a <session-id> of 0

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 7]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   (zero) is included.  If needed the returned session-id may be used to
   <kill> the NETCONF session holding the lock.  The same error response
   is returned if the requesting session already holds the (global) lock
   for the same datastore.

   If the select expressions return an empty node set, the <error-tag>
   is 'operation-failed', and the <error-app-tag> is 'no-matches'.

   If any select exprt expression returns anything but a node set, the <error-
   tag> is 'invalid-value', the <error-app-tag> is 'XPath does not
   return a node set'.

   If the :xpath capability is not supported and the XPath expression is
   not an Instance Identifier, the <error-tag> is 'invalid-value', the
   <error-app-tag> is ':xpath capability not supported'.

   If access control denies the partial lock, the <error-tag> is
   'access-denied'.

2.4.1.2.  Reserving model sections for future work

   Partial lock can not be used to lock non-existing nodes, effectively
   reserving them for future use.  To make sure that a node cannot be
   created by some other session, the parent node should be locked, the
   top level node of the new section created, and then locked with
   another <partial-lock> operation.  After this the lock on the parent
   node should be removed.

2.4.2.  <partial-unlock>

   The operation unlocks a part of a datastore that was previously
   locked using <partial-lock> during the same session.

   Parameters:

   lock-id:  Lock identifier to unlock; taken from a reply to a previous
       <partial-lock> operation.

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 8]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   Example: Unlock a previously created lock

   <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
       xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
       nc:message-id="136">
       <partial-unlock>
           <lock-id>127</lock-id>
       </partial-unlock>
   </nc:rpc>

   Positive Response:

   If the device was able to satisfy the request, an <rpc-reply> is sent
   that contains an <ok> element.  A positive response MUST be sent even
   if all of the locked part of the datastore has already been deleted.

   Negative Response:

   If the <lock-id> parameter does not identify a lock which is owned by
   the session, an 'invalid-value' error is returned.

2.5.  Modifications to Existing Operations

   A granted partial-lock will cause another operation to fail, if it
   tries to modify the locked area and is executed in a NETCONF session
   other then the one that owns the lock.  All operations that modify
   the datastore are affected including: <edit-config>, <copy-config>,
   <delete-config>, <commit> and <discard-changes>.  A granted partial-
   lock will also cause the (global) <lock> operation to fail.  All of
   these operations are affected only if they are for the same
   datastore.

2.6.  Interactions with Other Capabilities

2.6.1.  Writable-Running Capability

   Partial locking of the running datastore can only be done if the
   :writable-running capability is supported by the device.

2.6.2.  Candidate Configuration Capability

   Partial locking of the candidate datastore can only be done if the
   :candidate capability is supported by the device.  The partial
   locking of the candidate datastore does not depend on whether the
   datastore was modified or not.

   If partial lock is requested for the running datastore, and the

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 9]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   NETCONF server implements the :confirmed-commit capability, and there
   was a recent confirmed <commit> operation, where the confirming
   <commit> operation has not been received, in this case the lock MUST
   be denied, because if the confirmation does not arrive, the running
   datastore MUST be rolled back to its state before the commit, thus
   the NETCONF server might need to modify the configuration.

2.6.3.  Distinct Startup Capability

   Partial locking of the startup datastore can only be done if the
   :startup capability is supported by the device.

3.  Security Considerations

   The same considerations as for the base NETCONF Protocol [NETCONF]
   are valid.  It is assumed that the <partial-lock> and <partial-
   unlock> RPCs are only allowed for an authenticated user after passing
   some access control meession returns anything but a node set, the <error-
   tag> is 'invalid-value', the <error-app-tag> is 'XPath does not
   return a node set'.

   If the :xpath capability is not supported and the XPath expression is
   not an Instance Identifier, the <error-tag> is 'invalid-value', the
   <error-app-tag> is ':xpath capability not supported'.

   If access control denies the partial lock, the <error-tag> is
   'access-denied'.

2.4.1.2.  Reserving model sections for future work

   Partial lock can not be used to lock non-existing nodes, effectively
   reserving them for future use.  To make sure that a node cannot be
   created by some other session, the parent node should be locked, the
   top level node of the new section created, and then locked with
   another <partial-lock> operation.  After this the lock on the parent
   node should be removed.

2.4.2.  <partial-unlock>

   The operation unlocks a part of a datastore that was previously
   locked using <partial-lock> during the same session.

   Parameters:

   lock-id:  Lock identifier to unlock; taken from a reply to a previous
       <partial-lock> operation.

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 8]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   Example: Unlock a previously created lock

   <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
       xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
       nc:message-id="136">
       <partial-unlock>
           <lock-id>127</lock-id>
       </partial-unlock>
   </nc:rpc>

   Positive Response:

   If the device was able to satisfy the request, an <rpc-reply> is sent
   that contains an <ok> element.  A positive response MUST be sent even
   if all of the locked part of the datastore has already been deleted.

   Negative Response:

   If the <lock-id> parameter does not identify a lock which is owned by
   the session, an 'invalid-value' error is returned.

2.5.  Modifications to Existing Operations

   A granted partial-lock will cause another operation to fail, if it
   tries to modify the locked area and is executed in a NETCONF session
   other then the one that owns the lock.  All operations that modify
   the datastore are affected including: <edit-config>, <copy-config>,
   <delete-config>, <commit> and <discard-changes>.  A granted partial-
   lock will also cause the (global) <lock> operation to fail.  All of
   these operations are affected only if they are for the same
   datastore.

2.6.  Interactions with Other Capabilities

2.6.1.  Writable-Running Capability

   Partial locking of the running datastore can only be done if the
   :writable-running capability is supported by the device.

2.6.2.  Candidate Configuration Capability

   Partial locking of the candidate datastore can only be done if the
   :candidate capability is supported by the device.  The partial
   locking of the candidate datastore does not depend on whether the
   datastore was modified or not.

   If partial lock is requested for the running datastore, and the

Lengyel & Bjorklund      Expires March 12, 2009                 [Page 9]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   NETCONF server implements the :confirmed-commit capability, and there
   was a recent confirmed <commit> operation, where the confirming
   <commit> operation has not been received, in this case the lock MUST
   be denied, because if the confirmation does not arrive, the running
   datastore MUST be rolled back to its state before the commit, thus
   the NETCONF server might need to modify the configuration.

2.6.3.  Distinct Startup Capability

   Partial locking of the startup datastore can only be done if the
   :startup capability is supported by the device.

3.  Security Considerations

   The same considerations as for the base NETCONF Protocol [NETCONF]
   are valid.  It is assumed that the <partial-lock> and <partial-
   unlock> RPCs are only allowed for an authenticated user after passing
   some access control mechanischanism.

   A lock (a partial-lock or a global lock) might prevent other users
   from configuring the system.  The following mechanisms are in place
   to prevent the misuse of this possibility:

      Only an authenticated user after passing access control can
      request a partial-lock.

      The partial-lock is automatically released when a session is
      terminated irrespective of the manner the session ends.

      The <kill-session> operation allows terminating other users
      sessions.

      The NETCONF server may log partial-lock requests in an audit
      trail.

   A lock that is hanging for any reason, e.g. a broken TCP connection
   that the server has not yet recognised, can be released from another
   NETCONF session by explicitly killing the session owning that lock
   using the <kill> operation.

   Partial locking is NOT an authorization mechanism, it should not be
   used to provide security or access control.  Partial locking should
   only be used as a mechanism to provide consistency in case of
   multiple managers trying to configure the node.  It is vital that the
   operator can easily understand the exact scope of a lock, for this

Lengyel & Bjorklund      Expires March 12, 2009                [Page 10]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   reason the scope is determined when granting a lock and is not
   modified dynamically later.

4.  IANA Considerations

   This document registers two URIs for the NETCONF XML namespace in the
   IETF XML registry [RFC3688].  Note that the capability URN is
   compliant to [NETCONF] section 10.3.

   +---------------+---------------------------------------------------+
   | Index         | Capability Identifier                             |
   +---------------+---------------------------------------------------+
   | :partial-lock | urn:ietf:params:netconf:capability:partial-lock:1 |
   |               | .0                                                |
   +---------------+---------------------------------------------------+

   URI: urn:ietf:params:xml:ns:netconf:partial-lock:1.0

   Registrant Contact: The IESG.

   XML: N/A, the requested URI is an XML namespace.

Lengyel & Bjorklund      Expires March 12, 2009                [Page 11]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

5.  Appendix A  -  XML Schema for Partial Locking  (normative)

   The following XML Schema defines the <partial-lock> and <partial-
   unlock> operations:

 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
   xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
   targetNamespace="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
   elementFormDefault="qualified" attributeFormDefault="unqualified">

   <xs:annotation>
     <xs:documentation>
         Schema defining the partial-lock and unlock operations.
         organization "IETF NETCONF Working Group"
         contact
             "Balazs Lengyel
              Ericsson Hungary, Inc.
              [email-masked]"
      </xs:documentation>
   </xs:annotation>

   <xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
     schemaLocation="netconf.xsd"/>

   <xs:complexType name="partialLockType">
     <xs:annotation>
       <xs:documentation>
         A NETCONF operation that locks part of a datastore.
       </xs:documentation>
     </xs:annotation>
     <xs:complexContent>
       <xs:extension base="nc:rpcOperationType">
         <xs:sequence>
           <xs:element ref="nc:rpcOperationTargetType"/>
           <xs:element name="select" type="xs:string"
             maxOccurs="unbounded">
             <xs:annotation>
               <xs:documentation>
                 XPath expression that specifies the scope of the lock.
                 An Instance Identifier expression must be used unless
                 the :xpath capability is supported in which case any
                 XPath 1.0 exprem.

   A lock (a partial-lock or a global lock) might prevent other users
   from configuring the system.  The following mechanisms are in place
   to prevent the misuse of this possibility:

      Only an authenticated user after passing access control can
      request a partial-lock.

      The partial-lock is automatically released when a session is
      terminated irrespective of the manner the session ends.

      The <kill-session> operation allows terminating other users
      sessions.

      The NETCONF server may log partial-lock requests in an audit
      trail.

   A lock that is hanging for any reason, e.g. a broken TCP connection
   that the server has not yet recognised, can be released from another
   NETCONF session by explicitly killing the session owning that lock
   using the <kill> operation.

   Partial locking is NOT an authorization mechanism, it should not be
   used to provide security or access control.  Partial locking should
   only be used as a mechanism to provide consistency in case of
   multiple managers trying to configure the node.  It is vital that the
   operator can easily understand the exact scope of a lock, for this

Lengyel & Bjorklund      Expires March 12, 2009                [Page 10]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

   reason the scope is determined when granting a lock and is not
   modified dynamically later.

4.  IANA Considerations

   This document registers two URIs for the NETCONF XML namespace in the
   IETF XML registry [RFC3688].  Note that the capability URN is
   compliant to [NETCONF] section 10.3.

   +---------------+---------------------------------------------------+
   | Index         | Capability Identifier                             |
   +---------------+---------------------------------------------------+
   | :partial-lock | urn:ietf:params:netconf:capability:partial-lock:1 |
   |               | .0                                                |
   +---------------+---------------------------------------------------+

   URI: urn:ietf:params:xml:ns:netconf:partial-lock:1.0

   Registrant Contact: The IESG.

   XML: N/A, the requested URI is an XML namespace.

Lengyel & Bjorklund      Expires March 12, 2009                [Page 11]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

5.  Appendix A  -  XML Schema for Partial Locking  (normative)

   The following XML Schema defines the <partial-lock> and <partial-
   unlock> operations:

 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
   xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
   targetNamespace="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
   elementFormDefault="qualified" attributeFormDefault="unqualified">

   <xs:annotation>
     <xs:documentation>
         Schema defining the partial-lock and unlock operations.
         organization "IETF NETCONF Working Group"
         contact
             "Balazs Lengyel
              Ericsson Hungary, Inc.
              [email-masked]"
      </xs:documentation>
   </xs:annotation>

   <xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
     schemaLocation="netconf.xsd"/>

   <xs:complexType name="partialLockType">
     <xs:annotation>
       <xs:documentation>
         A NETCONF operation that locks part of a datastore.
       </xs:documentation>
     </xs:annotation>
     <xs:complexContent>
       <xs:extension base="nc:rpcOperationType">
         <xs:sequence>
           <xs:element ref="nc:rpcOperationTargetType"/>
           <xs:element name="select" type="xs:string"
             maxOccurs="unbounded">
             <xs:annotation>
               <xs:documentation>
                 XPath expression that specifies the scope of the lock.
                 An Instance Identifier expression must be used unless
                 the :xpath capability is supported in which case any
                 XPath 1.0 expression ssion is allowed.
               </xs:documentation>
             </xs:annotation>
           </xs:element>
         </xs:sequence>

Lengyel & Bjorklund      Expires March 12, 2009                [Page 12]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

       </xs:extension>
     </xs:complexContent>
   </xs:complexType>

   <xs:complexType name="partialUnLockType">
     <xs:annotation>
       <xs:documentation>
         A NETCONF operation that releases a previously acquired
         partial-lock.
       </xs:documentation>
     </xs:annotation>
     <xs:complexContent>
       <xs:extension base="nc:rpcOperationType">
         <xs:sequence>
           <xs:element name="lock-id" type="xs:unsignedInt">
             <xs:annotation>
               <xs:documentation>
                 Identifies the lock to be released. Must be the value
                 received in the response to the partial-lock operation.
               </xs:documentation>
             </xs:annotation>
           </xs:element>
         </xs:sequence>
       </xs:extension>
     </xs:complexContent>
   </xs:complexType>

   <!-- <partial-lock> operation -->
   <xs:element name="partial-lock" type="partialLockType"
               substitutionGroup="nc:rpcOperation"/>

   <!-- <partial-unlock> operation -->
   <xs:element name="partial-unlock" type="partialUnLockType"
               substitutionGroup="nc:rpcOperation"/>

   <!-- reply to <partial-lock> -->
   <xs:element name="lock-id" type="xs:unsignedInt"/>

 </xs:schema>

Lengyel & Bjorklund      Expires March 12, 2009                [Page 13]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

6.  Appendix B  - YANG Module for Partial Locking (non-normative)

   The following YANG module defines the <partial-lock> and <partial-
   unlock> operations.  The YANG language is defined in
   [I-D.ietf-netmod-yang].

  module netconf-partial-lock {

    namespace urn:ietf:params:xml:ns:netconf:partial-lock:1.0;
    prefix pl;

    organization "IETF NETCONF Working Group";

    contact
      "Balazs Lengyel
       Ericsson Hungary, Inc.
       [email-masked]";

    description
      "This YANG module defines the <partial-lock> and
       <partial-unlock> operations.";

    revision 2008-06-06 {
      description "Initial version.";
    }

    grouping configName {
      container target {
          description
              "A choice to list the datastore names for NETCONF.";
          choice configNameType {
            leaf running   { type empty; }
            leaf candidate { type empty; }
            leaf startup   { type empty; }
          }
       }
    }

    rpc partial-lock {
      description "A NETCONF operation that locks part of a datastore.";
      input {
        uses configName;
        leaf-list select {
          description
            "XPath expression that specifies the scope of the lock.
            An Instance Identifier expression must be used unless the
            :xpath capability is supported in which case any XPath 1.0
            expression is allowed.";

Lengyel & Bjorklund      Expires March 12, 2009                [Page 14]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

          type string;
          min-elements 1;
        }
      }
      output {
        leaf lock-id {
          description
            "Identifies the lock, if granted. The lock-id must be
             used in the partial-unlock rpc.";
          type uint32;
        }
        leaf-list locked-node {
            description "List of locked-nodes";
            type instance-identifier;
        }
      }
    }

    rpc partial-unlock {
      description
        "A NETCONF operation that releases a previously acquired
        partial-lock.";
      input {
        leaf lock-id {
          description
            "Identifies the lock to be released. Must be the value
            received in the response to the partial-lock operation.";
          type uint32;
        }
      }
    }
  }

is allowed.
               </xs:documentation>
             </xs:annotation>
           </xs:element>
         </xs:sequence>

Lengyel & Bjorklund      Expires March 12, 2009                [Page 12]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

       </xs:extension>
     </xs:complexContent>
   </xs:complexType>

   <xs:complexType name="partialUnLockType">
     <xs:annotation>
       <xs:documentation>
         A NETCONF operation that releases a previously acquired
         partial-lock.
       </xs:documentation>
     </xs:annotation>
     <xs:complexContent>
       <xs:extension base="nc:rpcOperationType">
         <xs:sequence>
           <xs:element name="lock-id" type="xs:unsignedInt">
             <xs:annotation>
               <xs:documentation>
                 Identifies the lock to be released. Must be the value
                 received in the response to the partial-lock operation.
               </xs:documentation>
             </xs:annotation>
           </xs:element>
         </xs:sequence>
       </xs:extension>
     </xs:complexContent>
   </xs:complexType>

   <!-- <partial-lock> operation -->
   <xs:element name="partial-lock" type="partialLockType"
               substitutionGroup="nc:rpcOperation"/>

   <!-- <partial-unlock> operation -->
   <xs:element name="partial-unlock" type="partialUnLockType"
               substitutionGroup="nc:rpcOperation"/>

   <!-- reply to <partial-lock> -->
   <xs:element name="lock-id" type="xs:unsignedInt"/>

 </xs:schema>

Lengyel & Bjorklund      Expires March 12, 2009                [Page 13]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

6.  Appendix B  - YANG Module for Partial Locking (non-normative)

   The following YANG module defines the <partial-lock> and <partial-
   unlock> operations.  The YANG language is defined in
   [I-D.ietf-netmod-yang].

  module netconf-partial-lock {

    namespace urn:ietf:params:xml:ns:netconf:partial-lock:1.0;
    prefix pl;

    organization "IETF NETCONF Working Group";

    contact
      "Balazs Lengyel
       Ericsson Hungary, Inc.
       [email-masked]";

    description
      "This YANG module defines the <partial-lock> and
       <partial-unlock> operations.";

    revision 2008-06-06 {
      description "Initial version.";
    }

    grouping configName {
      container target {
          description
              "A choice to list the datastore names for NETCONF.";
          choice configNameType {
            leaf running   { type empty; }
            leaf candidate { type empty; }
            leaf startup   { type empty; }
          }
       }
    }

    rpc partial-lock {
      description "A NETCONF operation that locks part of a datastore.";
      input {
        uses configName;
        leaf-list select {
          description
            "XPath expression that specifies the scope of the lock.
            An Instance Identifier expression must be used unless the
            :xpath capability is supported in which case any XPath 1.0
            expression is allowed.";

Lengyel & Bjorklund      Expires March 12, 2009                [Page 14]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

          type string;
          min-elements 1;
        }
      }
      output {
        leaf lock-id {
          description
            "Identifies the lock, if granted. The lock-id must be
             used in the partial-unlock rpc.";
          type uint32;
        }
        leaf-list locked-node {
            description "List of locked-nodes";
            type instance-identifier;
        }
      }
    }

    rpc partial-unlock {
      description
        "A NETCONF operation that releases a previously acquired
        partial-lock.";
      input {
        leaf lock-id {
          description
            "Identifies the lock to be released. Must be the value
            received in the response to the partial-lock operation.";
          type uint32;
        }
      }
    }
  }

Leng

Lengyel & Bjorklund      Expires March 12, 2009                [Page 15]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

7.  Appendix C  -  Change Log

7.1.  03-04

   Minor clarifications

   Added list of locked-nodes to the output of partial-lock.

   Added <target> wrapper around datastore name.

7.2.  02-03

   Minor clarifications

   Same descriptions in XSD and YANG.

7.3.  01-02

   Made XSD normative

   Clarified that no specific access control is assumed.

   Clarified that non-existing nodes are NOT covered by the lock, even
   if they where existing and covered by the lock when it was originally
   granted.

   Some rewording

   Added app-tags for two of the error cases.

   Made YANG an informative reference

   Enhanced security considerations.

7.4.  00-01

   Added YANG module.

7.5.  -00

   Created from draft-lengyel-ngo-partial-lock-01.txt

Lengyel & Bjorklund      Expires March 12, 2009                [Page 16]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

8.  Acknowledgements

   Thanks to Andy Bierman, Sharon Chisholm, Phil Shafer , David
   Harrington, Mehmet Ersue and many other members of the NETCONF WG for
   providing important input to this document.

Lengyel & Bjorklund      Expires March 12, 2009                [Page 17]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

9.  References

9.1.  Normative References

   [NETCONF]  Enns, R., "NETCONF Configuration Protocol", RFC 4741,
              December 2006.

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

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              January 2004.

9.2.  Informative References

   [I-D.ietf-netmod-yang]
              Bjorklund, M., "YANG - A data modeling language for
              NETCONF", draft-ietf-netmod-yang-00 (work in progress),
              May 2008.

Lengyel & Bjorklund      Expires March 12, 2009                [Page 18]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

Authors' Addresses

   Balazs Lengyel
   Ericsson Hungary

   Email: [email-masked]

   Martin Bjorklund
   Tail-f Systems

   Email: [email-masked]

Lengyel & Bjorklund      Expires March 12, 2009                [Page 19]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

Full Copyright Statement

   Copyright (C) The IETF Trust (2008).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights 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; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat 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 pyel & Bjorklund      Expires March 12, 2009                [Page 15]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

7.  Appendix C  -  Change Log

7.1.  03-04

   Minor clarifications

   Added list of locked-nodes to the output of partial-lock.

   Added <target> wrapper around datastore name.

7.2.  02-03

   Minor clarifications

   Same descriptions in XSD and YANG.

7.3.  01-02

   Made XSD normative

   Clarified that no specific access control is assumed.

   Clarified that non-existing nodes are NOT covered by the lock, even
   if they where existing and covered by the lock when it was originally
   granted.

   Some rewording

   Added app-tags for two of the error cases.

   Made YANG an informative reference

   Enhanced security considerations.

7.4.  00-01

   Added YANG module.

7.5.  -00

   Created from draft-lengyel-ngo-partial-lock-01.txt

Lengyel & Bjorklund      Expires March 12, 2009                [Page 16]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

8.  Acknowledgements

   Thanks to Andy Bierman, Sharon Chisholm, Phil Shafer , David
   Harrington, Mehmet Ersue and many other members of the NETCONF WG for
   providing important input to this document.

Lengyel & Bjorklund      Expires March 12, 2009                [Page 17]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

9.  References

9.1.  Normative References

   [NETCONF]  Enns, R., "NETCONF Configuration Protocol", RFC 4741,
              December 2006.

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

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              January 2004.

9.2.  Informative References

   [I-D.ietf-netmod-yang]
              Bjorklund, M., "YANG - A data modeling language for
              NETCONF", draft-ietf-netmod-yang-00 (work in progress),
              May 2008.

Lengyel & Bjorklund      Expires March 12, 2009                [Page 18]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

Authors' Addresses

   Balazs Lengyel
   Ericsson Hungary

   Email: [email-masked]

   Martin Bjorklund
   Tail-f Systems

   Email: [email-masked]

Lengyel & Bjorklund      Expires March 12, 2009                [Page 19]

Internet-Draft        Partial Lock RPC for NETCONF        September 2008

Full Copyright Statement

   Copyright (C) The IETF Trust (2008).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights 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; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat 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 proprieroprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   [email-masked].

Acknowledgment

   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).

Lengyel & Bjorklund      Expires March 12, 2009                [Page 20]


_______________________________________________
Netconf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netconf

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Mon, 8 Sep 2008 23:07:43 +0200

Inline

----- Original Message ----- 
From: "Balazs Lengyel" <[email-masked]>
To: "Wes Hardaker" <[email-masked]>; "Bert Wijnen - IETF" 
<[email-masked]>; "netconf mailing list" <[email-masked]>
Sent: Monday, September 08, 2008 5:04 PM
Subject: Re: [Netconf] evaluation of the partial-lock document

> basically accepted them all e.g. I added a list of locked-nodes to the 

Thanks. AS a result I can see that in the example and also in the YANG
definition. But I do not see that the list of locked nodes is returned
according to the XSD schema? It looks the same as in revision 3.
It is quite possible I don't understand XSD well enough.

I need to review your responses to Wes in more detail before I can respond.
I would encourage other WG members to also read those responses and
speak up if they see issues.!!! PLEASE.

> Please indicate if you still have problems with some of the issues.

My own issues have been addressed, thanks

Bert

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Mon, 8 Sep 2008 23:07:43 +0200

Inline

----- Original Message ----- 
From: "Balazs Lengyel" <[email-masked]>
To: "Wes Hardaker" <[email-masked]>; "Bert Wijnen - IETF" 

Bert

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Mon, 8 Sep 2008 23:16:09 +0200

For example, in the below there is this discussion and a
question is "do we have consensus" :

> [BALAZS}: IMHO we did reach consensus on the issue,
> but anyway I am glad to see that you can still live with this solution.

Part of any WG Last Call is to make sure that what is the the document
being Last Called is indeed consensus of the WG. Unless multiple
people speak up, the WG chairs will assume that the document does
indeed represent WG consensus.

So pls do reveiw the document, Pls do review the responses being
posted to Wes's review comments, and DO SPEAK UP if you have
concerns or issues.

Bert (speaking as co-chair)

----- Original Message ----- 
From: "Balazs Lengyel" <[email-masked]>
To: "Wes Hardaker" <[email-masked]>; "Bert Wijnen - IETF" 

>>   1. lock with one partial nodes A and B
> I know I have 3 users: Jack and Jill and John. I store my users in 
> alphabetical order. I want

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Mon, 8 Sep 2008 23:16:09 +0200

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 09 Sep 2008 11:17:14 +0200

Hello Bert,
AFAIK we have newer done an XSD about an rpc-reply till now. We could start now but:

We want to change the content of <data> from anyXML to something more specific. However as 
<data> is not a top level element in the Netconf XSD I don know how we could do that. 
rpcResponse is defined as a grouping, so I cant substitute that either.

So I found no way to include this information in XSD, that's why I did not include details in 
the XSD.

Balazs

Bert Wijnen (IETF) wrote:
> ----- Original Message ----- From: "Balazs Lengyel" 
> according to the XFrom [email-masked]  Tue Sep  9 02:17:11 2008
Date: Tue, 09 Sep 2008 11:17:14 +0200
From: Balazs Lengyel <[email-masked]>
To: "Bert Wijnen (IETF)" <[email-masked]>
Cc: netconf mailing list <[email-masked]>
Subject: Re: [Netconf] evaluation of the partial-lock document
Sender: [email-masked]

Hello Bert,
AFAIK we have newer done an XSD about an rpc-reply till now. We could start now but:

We want to change the content of <data> from anyXML to something more specific. However as 
<data> is not a top level element in the Netconf XSD I don know how we could do that. 
rpcResponse is defined as a grouping, so I cant substitute that either.

So I found no way to include this information in XSD, that's why I did not include details in 
the XSD.

Balazs

Bert Wijnen (IETF) wrote:
> ----- Original Message ----- From: "Balazs Lengyel" 
> according toSD schema? It looks the same as in revision 3.

 the XSD schema? It looks the same as in revision 3.

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Tue, 9 Sep 2008 12:23:11 +0200

The reason I am/was confused is because in the XSD that you have now,
it looks to me as if only a lockID gets returned.
In YANG I can see it is a lockID plus a list of locked nodes.

Bert

----- Original Message ----- 
From: "Balazs Lengyel" <[email-masked]>
To: "Bert Wijnen (IETF)" <[email-masked]>
Cc: "Wes Hardaker" <[email-masked]>; "netconf mailing list" 
<[email-masked]>; "Martin Bjorklund" <[email-masked]>
Sent: Tuesday, September 09, 2008 11:17 AM
Subject: Re: [Netconf] evaluation of the partial-lock document

> We want to change the content of <data> from anyXML to something more 
> specific. However as <data> is not a top level element in the Netconf XSD 
> I don know how we could do that. rpcResponse is defined as a grouping, so 
> I cant substitute that either.
>
> So I found no way to include this information in XSD, that's why I did not 
> include details in the XSD.
>
> Balazs
>
>

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Tue, 9 Sep 2008 12:23:11 +0200

Bert

---

From: Balazs Lengyel <[email-masked]>
Date: Tue, 09 Sep 2008 12:51:12 +0200

Hello Bert,
I could add something like:

Existing:
<!-- reply to <partial-lock> -->
<xs:element name="lock-id" type="xs:unsignedInt"/>
NEW:
<xs:element name="locked-node" type="xs:string"/>

but locked-node will not appear anywhere else in the XSD (lock-id does). This would not even 
show that lock-id is included once while locked-node can be included multiple times.
(I am not in love with XSD anyway :-(

Opinion?

Balazs

Bert Wijnen (IETF) wrote:
> ----- Original Message ---From [email-masked]  Tue Sep  9 03:51:04 2008
Date: Tue, 09 Sep 2008 12:51:12 +0200
From: Balazs Lengyel <[email-masked]>
To: "Bert Wijnen (IETF)" <[email-masked]>, 
	Martin Bjorklund <[email-masked]>
Cc: netconf mailing list <[email-masked]>
Subject: Re: [Netconf] evaluation of the partial-lock document
Sender: [email-masked]

Hello Bert,
I could add something like:

Existing:
<!-- reply to <partial-lock> -->
<xs:element name="lock-id" type="xs:unsignedInt"/>
NEW:
<xs:element name="locked-node" type="xs:string"/>

but locked-node will not appear anywhere else in the XSD (lock-id does). This would not even 
show that lock-id is included once while locked-node can be included multiple times.
(I am not in love with XSD anyway :-(

Opinion?

Balazs

Bert Wijnen (IETF) wrote:
> <[email-masked]>
>> specific. However as <data> is not a top level element in the Netconf 
>> XSD I don know how we could do that. rpcResponse is defined as a 
>> grouping, so I cant substitute that either.
>>
>> So I found no way to include this information in XSD, that's why I did 
>> not include details in the XSD.
>>
>> Balazs
>>
>>

-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
TSP System Manager
ECN: 831 7320                        Fax: +36 1 4377792
Tel: +36-1-437-7320     email: [email-masked]
_______________________________________________
Netconf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netconf

-- From: "Balazs Lengyel" 
> <[email-masked]>
>> specific. However as <data> is not a top level element in the Netconf 
>> XSD I don know how we could do that. rpcResponse is defined as a 
>> grouping, so I cant substitute that either.
>>
>> So I found no way to include this information in XSD, that's why I did 
>> not include details in the XSD.
>>
>> Balazs
>>
>>

-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
TSP System Manager
ECN: 831 7320                        Fax: +36 1 4377792
Tel: +36-1-437-7320     email: [email-masked]
_______________________________________________
Netconf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netconf

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 09 Sep 2008 13:18:25 +0200 (CEST)

> <xs:element name="locked-node" type="xs:string"/>

Or rather NEW:

Maybe that's what you meant.

> but locked-node will not appear anywhere else in the XSD (lock-id
> does). This would not even show that lock-id is included once while
> locked-node can be included multiple times. 

This is just how XSD works (you could argue that rfc4741 should have
used a substitutionGroup for the reply as well.  but it didn't).

/martin

---

From: Martin Bjorklund <[email-masked]>
Date: Tue, 09 Sep 2008 13:18:25 +0200 (CEST)

Or rather NEW:

/martin

---

From: "Bert Wijnen \(IETF\)" <[email-masked]>
Date: Tue, 9 Sep 2008 15:29:04 +0200

Inline

----- Original Message ----- 
From: "Martin Bjorklund" <[email-masked]>
To: <[email-masked]>
Cc: <[email-masked]>; <[email-masked]>
Sent: Tuesday, September 09, 2008 1:18 PM
Subject: Re: [Netconf] evaluation of the partial-lock document

> Maybe that's what you meant.

More somtething like that, indeed. That still does not show that
there could be multiple nodes though

> used a substitutionGroup for the reply as well.  but it didn't).

:-)

Bert

_______________________________________________
Netconf mailing list
[email-masked]
https://www.ietf.org/mailmaFrom [email-masked]  Tue Sep  9 06:29:44 2008
From: "Bert Wijnen \(IETF\)" <[email-masked]>
To: <[email-masked]>,
	"Martin Bjorklund" <[email-masked]>
Date: Tue, 9 Sep 2008 15:29:04 +0200
Organization: Consultant
Cc: [email-masked]
Subject: Re: [Netconf] evaluation of the partial-lock document
Sender: [email-masked]

Inline

----- Original Message ----- 
From: "Martin Bjorklund" <[email-masked]>
To: <[email-masked]>
Cc: <[email-masked]>; <[email-masked]>
Sent: Tuesday, September 09, 2008 1:18 PM
Subject: Re: [Netconf] evaluation of the partial-lock document

> Maybe that's what you meant.

More somtething like that, indeed. That still does not show that
there could be multiple nodes though

> used a substitutionGroup for the reply as well.  but it didn't).

:-)

Bert

_______________________________________________
Netconf mailing list
[email-masked]
https://www.ietf.org/n/listinfo/netconf

mailman/listinfo/netconf