NETCONF Configuration Protocol
obsoleted by
- rfc-6241 — Network Configuration Protocol (NETCONF)
Extracted elements (28)
Configuration data and state data are strictly separated because mixing them would cause comparison noise from statistics, allow nonsensical writes to read-only data, inflate data set sizes, and complicate restoration from archived configurations. <get-config> returns only configuration; <get> returns both.
NETCONF uses a URI-based capability system rather than a fixed feature set so that standard and proprietary extensions can be defined by any naming authority without central coordination, allowing the protocol to evolve incrementally.
Subtree filtering was designed so the server does not need data-model-specific semantics during processing, enabling simple, centralized implementation; the trade-off is that only exact-match content filtering and explicit selection are supported, not arbitrary query expressions.
The <get-config> operation retrieves configuration data only, while <get> retrieves both configuration and state data; implementations that conflate the two will produce incorrect results when applications attempt to archive and restore configurations.
When a NETCONF <lock> is active, SNMP and CLI requests to modify the locked configuration MUST also fail with an appropriate error, ensuring that non-NETCONF management interfaces respect the lock; conversely, a non-NETCONF entity holding even a partial lock prevents NETCONF from acquiring a global lock.
A capability URI MUST sufficiently distinguish the naming authority to avoid naming collisions; NETCONF capability names MUST be URIs.
A lock MUST NOT be granted if a lock is already held by any NETCONF session or another entity, or if the <candidate> target has uncommitted modifications. An attempt to lock MUST fail in these cases.
A NETCONF implementation MUST support the SSH transport protocol mapping. SSH is the sole mandatory transport; other transports are optional.
A server MUST NOT return application-level or data-model-specific error information in an <rpc-error> element for which the client does not have sufficient access rights.
Document type declarations MUST NOT appear in NETCONF content, preventing XML DTD injection attacks and simplifying parsing.
If the source and target parameters of a <copy-config> operation identify the same URL or configuration datastore, an error MUST be returned with an error-tag of 'invalid-value'.
NETCONF <rpc> requests MUST be processed serially by the managed device, and the device MUST send responses only in the order the requests were received, even if additional requests are pipelined before previous ones complete.
Resources requested from the server for a particular connection MUST be automatically released when the connection closes, enabling failure recovery; for example, locks held by a terminated session are automatically freed.
The authentication process MUST result in an identity whose permissions are known to the device, and those permissions MUST be enforced during the remainder of the NETCONF session.
The <rpc> element has a mandatory 'message-id' attribute; if additional attributes are present in an <rpc> element, a NETCONF peer MUST return them unmodified in the corresponding <rpc-reply> element.
NETCONF defines three configuration datastores: <running> (always present, currently active configuration), <candidate> (optional, staging area for changes before commit), and <startup> (optional, configuration loaded at boot).
NETCONF is conceptually partitioned into four layers: (1) Transport Protocol, (2) RPC, (3) Operations (e.g., <get-config>, <edit-config>), and (4) Content. The content layer is outside the scope of this document.
Subtree filters consist of five component types: namespace selection, attribute match expressions, containment nodes, selection nodes (empty leaf = explicit selection), and content match nodes (leaf with text = exact-match filter with AND semantics across siblings).
The base protocol operations are: get, get-config, edit-config, copy-config, delete-config, lock, unlock, close-session, and kill-session. Additional operations may be defined by capabilities.
The <edit-config> operation supports four per-element 'operation' attribute values: merge (default), replace, create (fails with data-exists if present), and delete. The 'default-operation' parameter sets the operation for elements without an explicit attribute.
The <kill-session> operation allows an authorized client to terminate another NETCONF session and force release of any locks held by that session; it cannot be used to kill the current session.
The <lock> operation acquires an exclusive configuration lock on a named datastore; it fails with error-tag 'lock-denied' and includes the holding session-id (or 0 for non-NETCONF entities) in error-info. The lock is automatically released when the session terminates.
The <rpc-error> element carries structured error information including: error-type (transport/rpc/protocol/application), error-tag, error-severity (error/warning), error-app-tag, error-path (XPath), error-message, and error-info for protocol- or data-model-specific content.
Section 10.3 defines NETCONF capability URNs registered with IANA, including: :writable-running:1.0, :candidate:1.0, :confirmed-commit:1.0, :rollback-on-error:1.0, :validate:1.0, :startup:1.0, :url:1.0, and :xpath:1.0, all under the 'urn:ietf:params:netconf:capability:' prefix.
NETCONF connections must provide authentication, data integrity, and confidentiality, delegated entirely to the transport layer (e.g., SSH or TLS). The protocol itself provides no built-in security mechanisms.
The <kill-session> and <lock> operations allow one authorized session to affect another; implementations must carefully enforce access controls to prevent privilege escalation or denial of service through lock starvation.
A configuration datastore lock transitions from Unlocked to Locked on a successful <lock> operation and returns to Unlocked on <unlock>, <close-session>, <kill-session>, or transport failure. Lock acquisition fails if the datastore is already locked by any session or non-NETCONF entity.
All NETCONF protocol elements are defined in the XML namespace 'urn:ietf:params:xml:ns:netconf:base:1.0'. The 'message-id' attribute is an arbitrary string (typically a monotonically increasing integer) echoed verbatim from <rpc> to <rpc-reply>.