Partial Lock Remote Procedure Call (RPC) for NETCONF
Extracted elements (26)
Partial locking applies only to the running datastore; the candidate and startup datastores cannot be locked with <partial-lock>. This simplifies the locking model and avoids complex interactions with commit workflows.
The scope of a lock is determined at grant time and is not modified thereafter (except when nodes are deleted by the lock owner). This is explicitly chosen so that users can easily understand the exact scope of a lock, which is why partial locking should not be used as an authorization mechanism.
To avoid deadlocks, clients SHOULD lock everything they need in one <partial-lock> operation. If locking fails, the client MUST back off, release any previously acquired locks, and SHOULD retry after a randomized time interval.
XPath expressions are evaluated only once at lock time; the scope is maintained as a static set of nodes. If configuration changes would cause the XPath to return a different set, the lock scope is unaffected. This ensures the lock scope is deterministic and easily understood.
A successful partial lock causes <edit-config>, <copy-config>, <delete-config>, <commit>, and <discard-changes> to return error-tag 'in-use' with error-app-tag 'locked' when another session attempts to modify nodes in the protected area.
If a node in the scope of a partial lock is deleted by the session owning the lock, it is removed from the lock scope, allowing other sessions to recreate it. If all nodes in scope are deleted, the lock persists but with an empty scope.
The XML Schema in RFC 4741 (base NETCONF) has a known bug requiring a <data> XML element in an <rpc-reply>; the partial-lock reply examples will not validate against that schema.
A NETCONF server that supports partial locking MUST be able to grant multiple simultaneous partial locks to a single NETCONF session. Nodes in overlapping protected areas MUST be protected until all overlapping locks are released.
A <partial-lock> operation MUST be handled atomically by the NETCONF server: either all requested parts are locked or none. If any part cannot be locked, the server MUST unlock all parts already locked during that operation.
A <partial-lock> operation MUST fail if any NETCONF session owns the global lock on the running datastore, if any part of the area to be protected is already locked by another session, if the requesting user is not authenticated, or if access control denies it.
Access control SHOULD be checked before checking for conflicting locks to avoid giving out information about other sessions to an unauthorized client.
Each XPath expression in <partial-lock> MUST return a node set, and at least one of the node sets MUST be non-empty. If all select expressions return an empty node set, the error-tag is 'operation-failed' with error-app-tag 'no-matches'.
If a lock is already held on any node within the subtrees to be locked, the error-tag is 'lock-denied' and error-info 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.
If a partial lock is requested for the running datastore while the :confirmed-commit capability is active and a confirming commit has not yet been received, the lock MUST be denied with error-tag 'in-use' and error-app-tag 'outstanding-confirmed-commit'.
If part of the running datastore is already locked by <partial-lock>, then a global <lock> for the running datastore MUST fail even if requested by the session that owns the partial lock.
The device MUST support restricted XPath (Instance Identifier) expressions in the select element. If the :xpath capability is also supported, the device MUST also support any XPath 1.0 expression in the select element.
The system MUST ensure that configuration resources covered by the partial lock are not modified by other NETCONF or non-NETCONF management operations such as SNMP and CLI.
The lock-id is an unsigned 32-bit integer allocated by the server to uniquely identify a partial lock. It is unique across all partial locks on a server at any given time, covering both NETCONF and non-NETCONF sessions.
The :partial-lock capability allows a NETCONF client to lock portions of the running datastore using XPath expressions. The capability identifier is urn:ietf:params:netconf:capability:partial-lock:1.0.
The <partial-lock> RPC takes one or more 'select' elements containing XPath expressions evaluated against the server's conceptual data model root. It returns a lock-id (unsigned integer) and a list of locked-node Instance Identifiers.
The <partial-unlock> RPC takes a single lock-id parameter identifying the previously granted partial lock to release. It returns <ok> on success, including when all locked nodes have been deleted.
This document registers capability identifier URN ':partial-lock' (urn:ietf:params:netconf:capability:partial-lock:1.0) in the 'Network Configuration Protocol (NETCONF) Capability URNs' registry, and registers URI urn:ietf:params:xml:ns:netconf:partial-lock:1.0 in the IETF XML registry.
A hung lock (e.g., from a broken TCP connection) can be released by killing the owning session via <kill-session> from another NETCONF session. The NETCONF server MAY log partial lock requests in an audit trail.
<partial-lock> and <partial-unlock> RPCs MUST only be allowed for authenticated users and SHOULD only be allowed for authorized users. Partial locking is not an authorization mechanism and SHOULD NOT be used to provide security or access control.
A partial lock transitions from ungranted to active when <partial-lock> succeeds, and from active to released when either (1) <partial-unlock> is called with the correct lock-id in the same session, or (2) the NETCONF session terminates for any reason.
The <partial-lock> reply contains a <lock-id> element (xs:unsignedInt, 32-bit) and one or more <locked-node> elements (xs:string, Instance Identifier format) listing each locked node's absolute XPath path expression.