When would a NETCONF client use RFC 5717's <partial-lock> instead of <lock>, and what does a partial lock fail to protect?
answer
- lock a slice, not everything
- running datastore only
- XPath evaluated once
- new nodes are not covered
- global and partial exclude each other
basics
~20 sA <partial-lock> locks selected nodes of running so two managers can edit different sections at once; it protects only the nodes its XPath matched at lock time, plus their subtrees, never later-created siblings, reads, or the rest of the configuration.
solid answer
~50 sRFC 5717's `:partial-lock` capability lets a session lock part of `running` - never the candidate or startup - with one or more `select` XPath expressions, restricted to instance identifiers unless `:xpath` is supported. The reply returns a `lock-id` and the `locked-node` list. It suits devices edited through `:writable-running` where, say, a CI pipeline owns routing and an operator's script owns interface descriptions. The lock is atomic: all requested parts or none. Its limits are the point of the question: the XPath is evaluated **once**, so a list entry created afterwards is unlocked; reads are unaffected; and data outside the protected area stays editable, so the client must lock whatever its change depends on. A global `<lock>` and any partial lock on `running` exclude each other, even within one session, and a pending confirmed commit blocks new partial locks.
code
xml · 18 lines<nc:rpc message-id="135"
xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<partial-lock>
<select xmlns:if="http://example.com/ns/interface">
/if:interfaces/if:interface[if:id='eth1']
</select>
</partial-lock>
</nc:rpc>
<nc:rpc-reply message-id="135"
xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock-id>127</lock-id>
<locked-node xmlns:if="http://example.com/ns/interface">
/if:interfaces/if:interface[if:id='eth1']
</locked-node>
</nc:rpc-reply>go deeper
Recall that the base NETCONF lock covers a whole datastore, and RFC 5717 adds a partial lock for running only.
Explain select expressions, the lock-id reply, the protected subtree and why the lock is all-or-nothing.
Name what slips through: nodes created after the lock, dependencies outside it, and the mutual exclusion with the global lock and a pending confirmed commit.
Judge whether partitioning a device's configuration between automation systems is worth the extra failure modes, or whether serialising on one lock is simpler.
## Why a partial lock exists The base NETCONF `<lock>` (RFC 6241) is global: it locks a whole datastore. That is safe but coarse. On a router where a **CI pipeline** manages routing and an **operator's script** manages interface descriptions, a global lock makes each wait for the other although their changes never touch the same data. **RFC 5717** (Standards Track) adds the `:partial-lock` capability, `urn:ietf:params:netconf:capability:partial-lock:1.0`, with two operations: `<partial-lock>` and `<partial-unlock>`. Its two worked usage scenarios match this split: managers editing overlapping sections, who lock briefly, and managers with distinct areas, who may hold their locks for longer. ## How it works - **Datastore:** `running` only. RFC 5717 §2.6 says the candidate and startup cannot be partial-locked, so the extension fits devices edited through `:writable-running`, not the candidate-and-commit workflow. - **Scope:** one or more `select` elements, each an XPath expression that MUST return a node set; at least one must be non-empty. Without the `:xpath` capability, each must be an **instance identifier** - an absolute path whose predicates only pick list keys. - **Atomic:** the server locks all requested parts or none; if one part fails, it unlocks what it already took. - **Reply:** a `lock-id`, unique on the server at that time, and the `locked-node` list in instance-identifier form. - **Protected area:** each locked node **and the whole subtree under it**. Nobody else - no other NETCONF session, no SNMP, no CLI - can change it. - **Release:** `<partial-unlock>` with the `lock-id`, from the same session, or the session ending. A session may hold several partial locks. Another session's edit into a protected area fails with `error-tag` `in-use` and `error-app-tag` `locked`. With `continue-on-error`, the unprotected parts of the same `<edit-config>` may still be applied. ## What a partial lock does not protect RFC 5717 is blunt that "you get what you asked for", and the gaps are where real mistakes happen: 1. **Nodes created later.** The XPath is evaluated only at lock time; afterwards the scope is the node set it returned. Lock every entry of the interface list, and an interface someone creates a minute later is unlocked. 2. **Reads.** Locking does not affect read operations. 3. **Everything outside the protected area.** If the change depends on data elsewhere - a prefix list the routing policy references - that data can change underneath. The client SHOULD include it in the lock. 4. **Deleted nodes.** If the owner deletes a node in its scope, the node leaves the scope, and anyone can recreate it. ## Interactions with other locks and confirmed commit | Situation | Outcome | |---|---| | Any session holds the global lock on `running` | `<partial-lock>` fails, even for the global lock's owner | | Any partial lock exists on `running` | a global `<lock>` fails with `lock-denied`, even for the partial lock's owner | | Requested area overlaps another session's partial lock | `lock-denied`, holder's `session-id` in `error-info` (0 for non-NETCONF) | | A confirmed commit awaits confirmation | `in-use`, `error-app-tag` `outstanding-confirmed-commit` | | No node matches any `select` | `operation-failed`, `error-app-tag` `no-matches` | | A non-instance-identifier XPath without `:xpath` | `invalid-value`, `error-app-tag` `invalid-lock-specification` | The confirmed-commit row exists because an unconfirmed commit may still have to be rolled back, and the server must be free to rewrite `running` to do it. ## Deadlock Two sessions each locking part of what the other needs can deadlock. RFC 5717 §2.4.1.2 says clients SHOULD lock everything they need in one `<partial-lock>`, and if locking fails they MUST back off and release what they hold, then SHOULD retry after a **randomised** wait. Because the operation is atomic, one request for every area is the simplest defence. ## When to choose it over the global lock - **Choose `<partial-lock>`** when the device is edited through `:writable-running`, several automation systems own clearly separate areas, and serialising them on one global lock would make each wait for no reason. - **Choose the global `<lock>`** when the workflow goes through the candidate, when a change touches many areas, or when its dependencies are hard to enumerate - a missed dependency is an unprotected one. - **Never mix them casually** on one device: each blocks the other, so a system that expects the global lock will see `lock-denied` whenever any partial lock is held. ## Seeing partial locks The monitoring module of RFC 6022 lists each partial lock under its datastore's `locks`, with its `lock-id`, `locked-by-session`, `locked-time`, the original `select` expressions and the current `locked-node` list.
- Can a session hold a partial lock on running and then take the global lock to finish its change?No. RFC 5717 says a global lock on running MUST fail while any partial lock exists, even when the requester owns that partial lock; the reply is lock-denied. The session must release its partial locks first, which reopens a window for others.
- Why does a partial lock not help on a device that is edited only through the candidate?RFC 5717 allows partial locks on running only; the candidate and startup cannot be partial-locked. On a candidate workflow, the shared candidate and the commit that publishes all of it still need the global locks on candidate and running.
- A NETCONF partial lock can be taken on the candidate datastore.
- The partial lock's XPath is re-evaluated on every edit, covering new nodes.
- A partial lock also blocks other sessions from reading the locked nodes.
- A session that holds a partial lock can always upgrade to the global lock.
- If one select cannot be locked, the server keeps the parts it did lock.