In NETCONF, what does a <lock> on a configuration datastore prevent, how long does it last, and what does a competing session get back?

## Why NETCONF has a lock Picture one router managed by two automation systems: a **CI pipeline** that pushes reviewed changes, and an **operator's script** that adjusts interface settings during an incident. Each sends a sequence of remote procedure calls - several `<edit-config>` requests, a check, perhaps a `<commit>`. Without coordination the two sequences interleave: the pipeline checks a configuration that the script changes a moment later, and the router ends up in a state that neither of them built or tested. The `<lock>` operation of **RFC 6241 §7.5** (NETCONF 1.1, which obsoletes RFC 4741) exists to stop that interleaving. A session takes the lock, makes its change and releases it. The RFC calls such locks **short-lived**: they protect one change, not a working day. ## What the lock covers `<lock>` has one mandatory parameter, `<target>`, which names a **configuration datastore**: `<running/>`, `<candidate/>` or `<startup/>`, each where the server supports it. The base lock is **global** to that datastore - it covers all of it, never a subtree. Locking only part of `running` is a separate extension, `<partial-lock>` from RFC 5717. On servers that implement the NMDA operations of RFC 8526, `<lock>` and `<unlock>` gain a `datastore` leaf, and only writable datastores can be locked. While the lock is held, the server must prevent any change to the datastore other than those the owning session requests: | Request from anyone other than the holder | Result while the lock is held | |---|---| | `<edit-config>` targeting the locked datastore | refused | | `<copy-config>` with the locked datastore as its target | refused | | An SNMP or CLI write to the locked configuration | MUST fail | | `<commit>` while `running` or `candidate` is locked by another session | fails with `in-use` | | A read such as `<get-config>` | allowed - the lock guards changes | | Another `<lock>` on the same datastore | fails with `lock-denied` | The SNMP and CLI row matters: a NETCONF lock is not just a courtesy between NETCONF clients. The RFC requires the device to enforce it against its other management interfaces too. ## How long a lock lasts The protocol has **no lock timer**. A lock begins when it is granted and ends in one of three ways: 1. The owner sends `<unlock>` for the same target. Only the session that obtained the lock may do this; an `<unlock>` from another session, or for a lock that is not active, fails. 2. The owning session ends. `<close-session>` releases its locks, and so does any other termination - the server may also close a session when the transport fails, after an inactivity timeout or on abusive behaviour, criteria RFC 6241 leaves to the implementation. 3. Another session ends the owner with `<kill-session>`, which releases every lock the killed session held. Because the end of a session is the only automatic release, a lock can outlive the work it protected for as long as the server still believes the dead client's session is alive. One datastore behaves specially: when a lock on `candidate` is released - explicitly or because the session failed - the **outstanding changes in the candidate are discarded** (RFC 6241 §8.3.5.2). A crashed client therefore does not leave half-made edits for the next committer. ## When the server refuses a lock A `<lock>` MUST NOT be granted when: - a lock on that datastore is already held by any NETCONF session or by another entity, such as a CLI user; - the target is `candidate` and it has been modified with changes that have been neither committed nor discarded; - the target is `running` and another NETCONF session has a **confirmed commit** still awaiting its confirmation; - on a server with RFC 5717, any partial lock exists on `running` - even one held by the requesting session itself. ## Reading lock-denied When the pipeline asks for the lock while the script holds it, the reply carries the holder's identity: ```xml <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <rpc-error> <error-type>protocol</error-type> <error-tag>lock-denied</error-tag> <error-severity>error</error-severity> <error-info> <session-id>454</session-id> </error-info> </rpc-error> </rpc-reply> ``` - `error-tag` **`lock-denied`** is the one RFC 6241 Appendix A defines for this case, with `error-type` `protocol`. - `<session-id>` is the NETCONF session that holds the lock - the same number that session received in its server `<hello>`. - A `<session-id>` of **0** means a **non-NETCONF entity** holds the lock, such as a CLI session. RFC 6241 defines no NETCONF way to break that lock and leaves it to the device's own interface. ## Operating notes - Take the lock **before the first edit**, not just before the commit; the point is that nobody changes the datastore between your first read and your last write. - On `lock-denied`, back off and retry, or investigate the holder; never fall back to editing unlocked. - Hold the lock for one change. A pipeline that keeps a lock across a slow approval step locks every operator out of the router. - A RESTCONF edit to a datastore that a NETCONF session has locked fails too, with `409 Conflict` and `in-use` (RFC 8040 §1.4).