RFC 5717
Partial Lock Remote Procedure Call (RPC) for NETCONF
RFC 5717: Partial Lock Remote Procedure Call (RPC) for NETCONF 🎀
The vibe check: this is the Network Working Group, 💅 Standards Track, December 2009. Authors: B. Lengyel (Ericsson) and M. Bjorklund (Tail-f Systems). Obsoletes / Updates: the title block doesn't list anything in either column. 🦋
Abstract ✨
Okay so NETCONF already has lock and unlock RPCs, and they lock the entire configuration datastore. That's great until you only need a piece of it. This doc adds a capability-based extension that lets you lock just portions of a configuration datastore. Main character energy 👑
Status of This Memo 📮
This document is an Internet standards track protocol for the Internet community, and the authors want your discussion and suggestions for improvements 🫶 For the current standardization state and status, check the current edition of "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited, so share away 🌸
Copyright Notice 🌈
Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved. 🔒
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info), as they stand on the publication date. Please read those carefully, because they spell out your rights and restrictions for this document. Any Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as the BSD License describes.
This document may contain material from IETF Documents or IETF Contributions that were published or made publicly available before November 10, 2008. The people who control the copyright in some of that material may not have given the IETF Trust permission to allow modifications outside the IETF Standards Process. Unless you get an adequate license from those copyright holders, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process. The one exceptions are formatting it for publication as an RFC and translating it into languages other than English 🌍
Table of Contents 🧚
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 3
2. Partial Locking Capability . . . . . . . . . . . . . . . . . . 3
2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.1. Usage Scenarios . . . . . . . . . . . . . . . . . . . 4
2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 5
2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 5
2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 5
2.4.1. <partial-lock> . . . . . . . . . . . . . . . . . . . . 5
2.4.2. <partial-unlock> . . . . . . . . . . . . . . . . . . . 10
2.5. Modifications to Existing Operations . . . . . . . . . . . 10
2.6. Interactions with Other Capabilities . . . . . . . . . . . 11
2.6.1. Candidate Configuration Capability . . . . . . . . . . 11
2.6.2. Confirmed Commit Capability . . . . . . . . . . . . . 11
2.6.3. Distinct Startup Capability . . . . . . . . . . . . . 11
3. Security Considerations . . . . . . . . . . . . . . . . . . . 12
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1. Normative References . . . . . . . . . . . . . . . . . . . 13
6.2. Informative References . . . . . . . . . . . . . . . . . . 13
Appendix A. XML Schema for Partial Locking (Normative) . . . . . 14
Appendix B. YANG Module for Partial Locking (Non-Normative) . . . 17
Appendix C. Usage Example - Reserving Nodes for Future
Editing (Non-Normative) . . . . . . . . . . . . . . . 191. Introduction 💖
Okay so the [NETCONF] protocol describes lock and unlock operations that work on entire configuration datastores. But honestly, lots of times multiple management sessions need to change the configuration of one managed device at the same time. In those cases you only need to lock parts of a configuration datastore 🙈 This document adds a capability-based extension to NETCONF so you can partially lock the NETCONF running datastore, using a mechanism built on the XPath filtering stuff that already exists ✨
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]. 🫶
Additionally, here are the terms defined in this doc:
- Instance Identifier: an XPath expression that identifies one specific node in the conceptual XML datastore 🧩 It contains an absolute path expression in abbreviated syntax, and predicates are only used to give values for nodes that are defined as keys, so you can tell multiple instances apart.
- Scope of the lock: at first, this is the set of nodes returned by the XPath expressions in a successful partial-lock operation. The set might change if the session that owns the lock deletes some of those nodes.
- Protected area: the set of nodes that the lock protects from modification. This set includes the nodes in the scope of the lock and the nodes in subtrees under them 🔐
2. Partial Locking Capability 🍓
2.1. Overview 🌸
The :partial-lock capability says the device can lock its configuration with a narrower scope than a complete configuration datastore. You pick the scope you want to lock by using restricted or full XPath expressions. Partial locking only touches configuration data, and only the running datastore. The candidate datastore and the start-up datastore aren't affected at all 🙅♀️
The system MUST ensure that configuration resources covered by the lock are not modified by other NETCONF or non-NETCONF management operations, such as Simple Network Management Protocol (SNMP) and the Command Line Interface (CLI). This one is non-negotiable bestie 🔥
The partial lock lasts from the moment it's granted until one of two things happens: (1) the matching <partial-unlock> operation succeeds, or (2) the NETCONF session terminates 🕰️
A NETCONF session MAY have multiple parts of the running datastore locked using partial lock operations. Multiple locks, no problem 💜
The <partial-lock> operation returns a lock-id to identify each lock it successfully gets. The lock-id is unique at any given time for a NETCONF server, across all partial-locks granted to any NETCONF or non-NETCONF session. No duplicates, ever 🦋
2.1.1. Usage Scenarios 🎬
Here are a few scenarios for partial locking. There are a bunch of other usage scenarios possible too, but these two are the ones described here 💅
2.1.1.1. Multiple Managers Handling the Writable Running Datastore with Overlapping Sections 😭
Multiple managers are handling the same NETCONF agent at the same time. The agent is handled through the writable running datastore. Each manager has their own task, and those tasks might involve changing overlapping sections of the datastore. Chaos energy 🌀
After collecting and analyzing input and preparing the NETCONF operations offline, the manager locks the areas that matter for their task, using one single <partial-lock> operation. Then they run a bunch of <edit-config> operations to change the configuration, and finally release the partial lock. The lock should be held for the shortest possible time (e.g., seconds rather than minutes). The manager should collect all human input before locking anything, lowkey the golden rule ⏱️ Since each manager only locks part of the data model, usually multiple operators can run <edit-config> operations at the same time 🙌
2.1.1.2. Multiple Managers Handling the Writable Running Datastore, Distinct Management Areas 🧁
Multiple managers are handling the same NETCONF agent at the same time, again through the writable running datastore. The agent's data model has a number of well-defined, separate areas that can be configured without affecting other areas. One example is a server with multiple applications running on it. Another is a bunch of network elements sharing one NETCONF agent for management 🖥️
Each manager has their own task, and none of those tasks involve changing overlapping sections of the datastore.
The manager locks their area with a <partial-lock> operation, uses a number of <edit-config> commands to change it, and releases the lock later. Each manager has their own functional area assigned to them, and they only lock that area, so multiple managers can edit the configuration at the same time 🌈 Locks can be held for longer stretches (e.g., minutes, hours), since they won't get in the way of other managers ⭐
This scenario assumes that the global lock operation from [NETCONF] is not used. 🚫
2.2. Dependencies 🔗
The device MUST support restricted XPath expressions in the select element, as described in Section 2.4.1. Optionally, if the :xpath capability is also supported (as defined in [NETCONF], Section 8.9. "XPath Capability"), the device MUST also support using any XPath 1.0 expression in the select element. So if you've got :xpath, the device has to handle the full XPath 1.0 expressions too 🧠
2.3. Capability Identifier 🪪
urn:ietf:params:netconf:capability:partial-lock:1.02.4. New Operations ✨
2.4.1. <partial-lock> 🔒
Okay bestie, the <partial-lock> operation lets a client lock just a slice of the running datastore 💅. You pick that slice with XPath expressions in the "select" elements. Each XPath expression MUST return a node set. 🎀
When a NETCONF session holds a lock on a node, no other session or non-NETCONF mechanism in the system can change that node or any node in the hierarchy beneath it. 🔐
Locking a node protects the node itself plus its entire subtree from being modified by others 🫶. The set of locked nodes is called the scope of the lock. All the locked nodes together with the nodes in the subtrees under them make up the protected area ✨.
The XPath expressions are evaluated only once, at lock time ⏰. After that, the scope of the lock is kept as a set of nodes, meaning the nodeset that came back, and NOT as the XPath expression itself. So if the configuration data changes later in a way that would make the original XPath expressions match a different set of nodes, the scope of the partial lock stays the same 🦋.
Imagine the agent's data model has a list of interface nodes. If the XPath expression in the partial-lock operation covers all of the interface nodes when the lock is taken, the scope of the lock is kept as the list of interface nodes that existed at the moment the lock was granted. If someone creates a new interface later, that interface is not in the locked-nodes list from before, so it is not locked 🙈.
A <partial-lock> operation MUST be handled atomically by the NETCONF server. The server either locks all of the requested parts of the datastore or none of them 🌸. If one of the requested parts cannot be locked during that operation, the server MUST unlock all of the parts that were already locked during that operation.
If the session that owns the lock deletes a node in the scope of the lock, that node is removed from the scope, so any other session or non-NETCONF mechanism can recreate it 🧚. If every node in the scope of the lock gets deleted, the lock is still there, but its scope becomes empty (since the lock doesn't cover any nodes) 💀.
A NETCONF server that supports partial locking MUST be able to grant multiple simultaneous partial locks to a single NETCONF session. If the protected areas of the individual locks overlap, the nodes in the common area MUST stay protected until ALL of the overlapping locks are released 👑.
A <partial-lock> operation MUST fail if:
- Any NETCONF session (including the current session) owns the global lock on the running datastore.
- Any part of the area to be protected is already locked (or protected by partial locking) by another management session, including other NETCONF sessions using <partial-lock> or any other non-NETCONF management method.
- The requesting user is not successfully authenticated.
- The NETCONF server implements access control and the locking user does not have sufficient access rights. 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 🍓.
The <partial-lock> operation is designed to be simple, so when a partial lock runs, you get exactly what you asked for: a set of nodes that are locked for writing 💖.
Because of that, users need to keep the following in mind:
- Locking does not affect read operations 👀.
- If part of the running datastore is locked, that has no effect on the unlocked parts of the datastore. If this becomes a problem (for example, changes depend on data values or nodes outside the protected part of the datastore), these nodes SHOULD be included in the protected area of the lock ⭐.
- Configuration data can be edited both inside and outside the protected area of a lock. It is the responsibility of the NETCONF client application to lock all of the relevant parts of the datastore that are crucial for a specific management action 🧁.
Note: The <partial-lock> operation does not change the global <lock> operation defined in the base NETCONF protocol [NETCONF]. If part of the running datastore is already locked by <partial-lock>, then a global lock for the running datastore MUST fail, even if the global lock is requested by the NETCONF session that owns the partial lock 🚫.
2.4.1.1. Parameters, Results, Examples 📋
Parameters:
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 nodes returned from the select expressions are reported in the rpc-reply message.
Each select expression MUST return a node set, and at least one of the node sets MUST be non-empty.
If the device supports the :xpath capability, any valid XPath 1.0 expression can be used. If the device does not support the :xpath capability, 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 🔑.
Example: Lock virtual router 1 and interface eth1
<nc:rpc
xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="135">
<partial-lock>
<select xmlns:rte="http://example.com/ns/route">
/rte:routing/rte:virtualRouter[rte:routerName='router1']
</select>
<select xmlns:if="http://example.com/ns/interface">
/if:interfaces/if:interface[if: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"
message-id="135">
<lock-id>127</lock-id>
<locked-node xmlns:rte="http://example.com/ns/route">
/rte:routing/rte:virtualRouter[rte:routerName='router1']
</locked-node>
<locked-node xmlns:if="http://example.com/ns/interface">
/if:interfaces/if:interface[if:id='eth1']
</locked-node>
</nc:rpc-reply>Note: The XML Schema in [NETCONF] has a known bug that requires the <data> XML element in a <rpc-reply>. This means that the above examples will not validate using the XML Schema found in [NETCONF] 🙃.
Positive Response:
If the device is able to satisfy the request, an <rpc-reply> is sent with a <lock-id> element (lock identifier) in the <rpc-reply> element. A list of locked nodes is also returned in Instance Identifier format ✅.
Negative Response:
- If any select expression is an invalid XPath expression, the
<error-tag>is 'invalid-value'. - If any select expression returns something other than a node set, the
<error-tag>is 'invalid-value', and the<error-app-tag>is 'not-a-node-set'. - If all the select expressions return an empty node set, the
<error-tag>is 'operation-failed', and the<error-app-tag>is 'no-matches'. - If the :xpath capability is not supported and the XPath expression is not an Instance Identifier, the
<error-tag>is 'invalid-value', and the<error-app-tag>is 'invalid-lock-specification'. - If access control denies the partial lock, the
<error-tag>is 'access-denied'. Access control SHOULD be checked before checking for conflicting locks, so the server doesn't give out information about other sessions to an unauthorized client 🕵️♀️. - 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 (zero) SHOULD be included. The same error response is returned if the requesting session already holds the (global) lock for the running datastore 😬.
If needed, the returned session-id may be used to <kill-session> the NETCONF session holding the lock 💅.
2.4.1.2. Deadlock Avoidance 🥺
As with most locking systems, it is possible that two management sessions trying to lock different parts of the configuration could become deadlocked. To avoid this situation, clients SHOULD lock everything they need in one operation. If locking fails, the client MUST back-off, release any previously acquired locks, and SHOULD retry the procedure after waiting some randomized time interval 🎲.
2.4.2. <partial-unlock> 🔓
This operation unlocks the parts of the running datastore that were previously locked using <partial-lock> during the same session. It unlocks the parts that are covered by the lock identified by the lock-id parameter. If there are multiple potentially overlapping locks, only the lock identified by the lock-id is removed ✨.
Parameters:
lock-id: Identity of the lock to be unlocked. This lock-id MUST have been received as a response to a lock request by the manager during the current session, and MUST NOT have been sent in a previous unlock request.
Example: Unlock a previously created lock
<nc:rpc xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="136">
<partial-unlock>
<lock-id>127</lock-id>
</partial-unlock>
</nc:rpc>Positive Response:
If the device is 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 parts of the datastore have already been deleted 🎉.
Negative Response:
If the <lock-id> parameter does not identify a lock that is owned by the session, an 'invalid-value' error is returned 🙅♀️.
2.5. Modifications to Existing Operations 🛠️
A successful partial lock will cause a subsequent operation to fail if that operation attempts to modify nodes in the protected area of the lock and is executed in a NETCONF session other than the session that has been granted the lock. The <error-tag> 'in-use' and the <error-app-tag> 'locked' are returned. All operations that modify the running datastore are affected, including: <edit-config>, <copy-config>, <delete-config>, <commit>, and <discard-changes>. If partial lock prevents <edit-config> from modifying some data, but the operation includes the continue-on-error option, modification of other parts of the datastore, which are not protected by partial locking, might still succeed 🌈.
If the datastore contains nodes locked by partial lock, this will cause the (global) <lock> operation to fail. The <error-tag> element 'lock-denied' and an <error-info> element including the <session-id> of the lock owner will be returned. If the lock is held by a non-NETCONF session, a <session-id> of 0 (zero) is returned 🚧.
All of these operations are affected only if they are targeting the running datastore 🎯.
2.6. Interactions with Other Capabilities 🤝
2.6.1. Candidate Configuration Capability 🧩
The candidate datastore cannot be locked using the <partial-lock> operation 💜.
2.6.2. Confirmed Commit Capability ✨
okay so this one's a lil spicy 🌶️ if ALL of these are true:
- a partial lock is requested for the running datastore, and
- the NETCONF server implements the
:confirmed-commitcapability, and - there was a recent confirmed
<commit>operation where the confirming<commit>operation has not been received
then the lock MUST be denied 🙅♀️ bc if the confirmation never shows up, the running datastore MUST be rolled back to how it was before the commit. so the NETCONF server might need to change the configuration again 😭
in this case the <error-tag> 'in-use' and the <error-app-tag> 'outstanding-confirmed-commit' get returned 💅
2.6.3. Distinct Startup Capability 🧚
the startup datastore cannot be locked using the <partial-lock> operation. no exceptions, bestie 🙅♀️
3. Security Considerations 🔒
the same considerations that apply to the base NETCONF protocol [NETCONF] are relevant here too 🫶. <partial-lock> and <partial-unlock> RPCs MUST only be allowed for an authenticated user. <partial-lock> and <partial-unlock> RPCs SHOULD only be allowed for an authorized user. however, access control isn't standardized and isn't a mandatory part of a NETCONF implementation, so it's strongly recommended but OPTIONAL (though nearly all implementations include some kind of access control 💀).
a lock (either a partial lock or a global lock) might stop other users from configuring the system 😤. these are the safeguards in place to stop people misusing that power:
- A user, that is not successfully authenticated, MUST NOT be granted a partial lock.
- Only an authorized user SHOULD be able to request a partial lock.
- The partial lock is automatically released when a session is terminated regardless of how the session ends.
- The
<kill-session>operation makes it possible to terminate other users' sessions. - The NETCONF server MAY log partial lock requests in an audit trail.
a lock that's hung for some reason (e.g., a broken TCP connection that the server hasn't noticed yet) can be released from another NETCONF session by explicitly killing the session that owns the lock with the <kill-session> operation 🧹.
partial locking is NOT an authorization mechanism, so it SHOULD NOT be used to provide security or access control 🚫. it SHOULD only be used as a way to keep things consistent when multiple managers are trying to configure the node 🎀. it is vital that users easily understand the exact scope of a lock, which is why the scope gets decided when the lock is granted and doesn't change after that ✨.
4. IANA Considerations 🦋
this document registers one capability identifier URN from the "Network Configuration Protocol (NETCONF) Capability URNs" registry, and one URI for the NETCONF XML namespace in the "IETF XML registry" [RFC3688]. fyi the capability URN is compliant with [NETCONF], Section 10.3.
Index Capability Identifier
------------- ---------------------------------------------------
:partial-lock urn:ietf:params:netconf:capability:partial-lock:1.0URI: urn:ietf:params:xml:ns:netconf:partial-lock:1.0
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
5. Acknowledgements 💜
thank you to Andy Bierman, Sharon Chisholm, Phil Shafer, David Harrington, Mehmet Ersue, Wes Hardaker, Juergen Schoenwaelder, Washam Fan, and the many other members of the NETCONF WG who gave important input to this document 🌸.
6. References 📚
6.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.
6.2. Informative References
- [YANG] Bjorklund, M., "YANG - A data modeling language for NETCONF", Work in Progress, December 2009.
Appendix A. XML Schema for Partial Locking (Normative) 📜
the following XML Schema defines the <partial-lock> and <partial-unlock> operations:
<CODE BEGINS>
<?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
Netconf Working Group
Mailing list: netconf@ietf.org
Web: http://www.ietf.org/html.charters/netconf-charter.html
Balazs Lengyel
balazs.lengyel@ericsson.com
revision 2009-10-19
description Initial version, published as RFC 5717.
</xs:documentation>
</xs:annotation>
<xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
schemaLocation="urn:ietf:params:xml:ns:netconf:base:1.0"/>
<xs:simpleType name="lock-id-type">
<xs:annotation>
<xs:documentation>
A number identifying a specific
partial-lock granted to a session.
It is allocated by the system, and SHOULD
be used in the unlock operation.
</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:unsignedInt"/>
</xs:simpleType>
<xs:complexType name="partialLockType">
<xs:annotation>
<xs:documentation>
A NETCONF operation that locks parts of
the running datastore.
</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="nc:rpcOperationType">
<xs:sequence>
<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 is allowed.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</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="lock-id-type">
<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:complexType name="contentPartInPartialLockReplyType">
<xs:annotation>
<xs:documentation>
The content of the reply to a successful
partial-lock request MUST conform to this complex type.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="lock-id" type="lock-id-type">
<xs:annotation>
<xs:documentation>
Identifies the lock to be released. Must be the value
received in the response to a partial-lock operation.
</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="locked-node" type="xs:string"
maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
List of locked nodes in the running datastore.
</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:schema>
<CODE ENDS>Appendix B. YANG Module for Partial Locking (Non-Normative) 🌈
the following YANG module defines the <partial-lock> and <partial-unlock> operations. the YANG language itself is defined in [YANG].
<CODE BEGINS>
module ietf-netconf-partial-lock {
namespace urn:ietf:params:xml:ns:netconf:partial-lock:1.0;
prefix pl;
organization "IETF Network Configuration (netconf) Working Group";
contact
"Netconf Working Group
Mailing list: netconf@ietf.org
Web: http://www.ietf.org/html.charters/netconf-charter.html
Balazs Lengyel
Ericsson
balazs.lengyel@ericsson.com";
description
"This YANG module defines the <partial-lock> and
<partial-unlock> operations.";
revision 2009-10-19 {
description
"Initial version, published as RFC 5717.";
}
typedef lock-id-type {
type uint32;
description
"A number identifying a specific partial-lock granted to a session.
It is allocated by the system, and SHOULD be used in the
partial-unlock operation.";
}
rpc partial-lock {
description
"A NETCONF operation that locks parts of the running datastore.";
input {
leaf-list select {
type string;
min-elements 1;
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.";
}
}
output {
leaf lock-id {
type lock-id-type;
description
"Identifies the lock, if granted. The lock-id SHOULD be
used in the partial-unlock rpc.";
}
leaf-list locked-node {
type instance-identifier;
min-elements 1;
description
"List of locked nodes in the running datastore";
}
}
}
rpc partial-unlock {
description
"A NETCONF operation that releases a previously acquired
partial-lock.";
input {
leaf lock-id {
type lock-id-type;
description
"Identifies the lock to be released. MUST be the value
received in the response to a partial-lock operation.";
}
}
}
}
<CODE ENDS>Appendix C. Usage Example - Reserving Nodes for Future Editing (Non-Normative) 🦋
Okay so, partial lock can't lock nodes that don't exist yet 🙈 It can't reserve a spot for something that's coming later. To make sure no other session can create a node, the parent node should be locked first. Then you create the top-level node of the new subtree and lock it with another <partial-lock> operation. After that, the lock on the parent can be removed. 💅
Let's walk through an example! ✨
We want to create the <user> Joe under <users> and start editing him. Editing might take a few minutes, so we want to lock Joe right away so nobody touches him while we're working on him. 🫶
We also don't want to lock more of the running datastore than we need to, since multiple managers might be adding users at around the same time. 😭
First, we check which users already exist.
Step 1 - Read existing users
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter type="subtree">
<top xmlns="http://example.com/users">
<users/>
</top>
</filter>
</get-config>
</rpc>The NETCONF server sends back this reply. 🌸
Step 2 - Receiving existing data
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/users">
<users>
<user>
<name>fred</name>
<phone>8327</phone>
</user>
</users>
</top>
</data>
</rpc-reply>We want to add the new user Joe and lock him right away using partial locking. To do that, we first lock all the <user> nodes by locking the <users> node. 🎀
Heads up, though! If we locked all the <user> nodes using the select expression '/usr:top/usr:users/usr:user', that would NOT lock the new user Joe, because we haven't created him yet. So we have to lock the <users> node instead. 👑
Step 3 - Lock users
<nc:rpc
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
message-id="102">
<partial-lock>
<select xmlns:usr="http://example.com/users">
/usr:top/usr:users
</select>
</partial-lock>
</nc:rpc>The NETCONF server grants the partial lock. The scope of the lock includes only the <users> node. The lock protects the <users> node and all <user> nodes below it from modification by other sessions. 🔒✨
Step 4 - Receive lock
<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"
message-id="102">
<lock-id>1</lock-id>
<locked-node xmlns:usr="http://example.com/users">
/usr:top/usr:users
</locked-node>
</nc:rpc-reply>Next, we create user Joe. He's protected by the lock we just got, since he sits under the subtree rooted at the <users> node. 🧚
Step 5 - Create user Joe
<rpc message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<top xmlns:usr="http://example.com/users">
<users>
<user>
<name>Joe</name>
</user>
</users>
</top>
</config>
</edit-config>
</rpc>We get a positive reply to the <edit-config> (not shown). Next, we request a lock that covers only the <user> Joe, and then release the lock on the <users> node. That way, other managers can keep creating new users. 💖
Step 6 - Lock user Joe
<nc:rpc
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
message-id="104">
<partial-lock>
<select xmlns:usr="http://example.com/users">
/usr:top/usr:users/user[usr:name="Joe"]"
</select>
</partial-lock>
</nc:rpc>The NETCONF server grants the partial lock. The scope of this second lock includes only the <user> node with the name Joe. The lock protects all data below that particular <user> node. 🌈
Step 7 - Receive lock
<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"
message-id="104">
<lock-id>2</lock-id>
<locked-node xmlns:usr="http://example.com/users">
/usr:top/usr:users/user[usr:name="Joe"]"
</locked-node>
</nc:rpc-reply>The scope of the second lock is the <user> node Joe. It protects that <user> node and any data below it, like the phone number. Right now, those nodes are protected by both the first and second locks. 🫧
Next, we unlock the other <user>s and the <users> node so other managers can work on them. We still keep the second lock, so the <user> node Joe and its subtree stay protected. 💜
Step 8 - Release lock on <users>
<nc:rpc xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="105">
<partial-unlock>
<lock-id>1</lock-id>
</partial-unlock>
</nc:rpc>Authors' Addresses ✨
Balazs Lengyel Ericsson
EMail: balazs.lengyel@ericsson.com
Martin Bjorklund Tail-f Systems
EMail: mbj@tail-f.com
📦 where this page comes from
- ietf: rfc5717 2009-12
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms