Protocol Operations
This section describes the netconfd-pro implementation details that may affect usage of the NETCONF protocol operations.
Every protocol operation is defined with a YANG rpc statement.
All NETCONF operations and several proprietary operations are supported,
<action>
The <action> operation is not not defined in a YANG module. The XML mapping rules are defined in RFC 7950 Section 7.15.2.
An action must be defined within a container or list. The XML encoding of an action has 3 layers:
action element representing the NETCONF RPC operation
ancestor nodes representing the exact data node containing the action
action invocation representing the action node. Any input parameters are encoded as child nodes of this action node.
<action> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status or data |
YANG file: |
none |
Capabilities needed: |
none |
Mandatory Parameters:
ancestor nodes containing one action invocation
The ancestor nodes and any key leafs needed to identify the action that is being invoked.
Exactly one top-level ancestor node is expected. This must be a container or a list. It can have as many descendant nodes as needed, but no sibling nodes.
The desired YANG action must be encoded within the ancestor nodes.
Only one action can be specified. An error is returned unless exactly one action invocation is found.
Optional Parameters:
none
Returns:
status or data
If the action statement definition for the action invocation contains any 'output' parameters (direct or via augment) then the 'rpc-reply' element should contain these child nodes.
If the action statement does not define any 'output' parameters then "<ok/>" or "<rpc-error>" will be returned
Possible Operation Errors:
access-denied
missing or invalid input parameters
missing or multiple action invocations
Example Request from RFC 7950 Section 7.15.3.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<action xmlns="urn:ietf:params:xml:ns:yang:1">
<server xmlns="urn:example:server-farm">
<name>apache-1</name>
<reset>
<reset-at>2014-07-29T13:42:00Z</reset-at>
</reset>
</server>
</action>
</rpc>
Example Reply from RFC 7950 Section 7.15.3.
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<reset-finished-at xmlns="urn:example:server-farm">
2014-07-29T13:42:12Z
</reset-finished-at>
</rpc-reply>
<backup>
The <backup> operation is used to create a named configuration backup file on the server. This operation is used with the <restore> operation.
Only local files are supported.
The --with-yumaworks-system CLI parameter must be set to 'true' in the server configuration.
The agt_backup_dir path string must be set to a valid directory in the agt_profile struct.
By default, only a superuser account is allowed to invoke this operation.
+---x backup
+---w input
+---w filename ywt:NcxFileName
+---w overwrite? boolean
<backup> Operation Usage
Min parameters: |
1 |
Max parameters: |
2 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
filename:
The file name with extension for the backup. The directory is determined by the agt_backup_dir profile variable. The file name string is specified by the NcxFileName typedef in yumaworks-types.yang.
Optional Parameters:
overwrite:
TRUE if it is OK to overwrite a backup with the same name, if it exists. FALSE if an error should be returned if the backup named 'filename' already exists. The default is FALSE.
Returns:
<ok/>
Possible Operation Errors:
none
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2" trace-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<backup xmlns="http://yumaworks.com/ns/yumaworks-system">
<filename>foo.xml</filename>
</backup>
</rpc>
Example Reply:
<rpc-reply message-id="2" trace-id="2" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<cancel-commit>
The <cancel-commit> operation is used to cancel a confirmed commit procedure in progress.
The :candidate capability .. code-block:: text
- +---x cancel-commit {confirmed-commit}?
- +---w input
+---w persist-id? string
<cancel-commit> Operation Usage
Min parameters: |
0 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
Mandatory Parameters:
none
Optional Parameters:
persist: If the 'persist' string was provided in the <commit> operation, then this parameter must be present, and the value must match. Only the session that started the confirmed commit can use this operation without providing a 'persist' parameter.
Returns:
<ok/>
Possible Operation Errors:
none
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<nc:cancel-commit>
<nc:persist>mycommit</nc:persist>
</nc:cancel-commit>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<nc:ok/>
</nc:rpc-reply>
<cancel-subscription>
The <cancel-subscription> operation is used to cancel a notification subscription.
If the calling session has a subscription previously created with <create-subscription>, then the subscription will be canceled and removed from memory. If no subscription is active the server will simply return <ok/>.
This operation will only be present if the --with-notifications parameter is set to 'true'.
+---x cancel-subscription
<cancel-subscription> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
none
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3" trace-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<cancel-subscription xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3" trace-id="3" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<clear-eventlog>
Delete any events stored in the eventlog for the specified event stream. This operation has no affect if the event stream does not have any stored events or its eventlog is not enabled.
By default, only a superuser session can invoke this operation.
+---x clear-eventlog
+---w input
+---w stream-name ywt:NcxNumName
<clear-eventlog> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
stream-name
type: string
default: none
capabilities needed: none
The name of the event-stream to clear
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
access-denied
invalid-value
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<clear-eventlog xmlns="http://yumaworks.com/ns/yumaworks-event-stream">
<stream-name>NETCONF</stream-name>
</clear-eventlog>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<close-session>
The <close-session> operation is always allowed, even if access control rules exist which somehow disallow 'exec' privileges to a session for this operation.
A <netconf-session-end> Event notification with a <termination-reason> field set to
closed will be generated when this operation is invoked.
+---x close-session
<close-session> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
<ok/>; an <rpc-reply> will be sent to the session before terminating the session.
Possible Operation Errors:
none
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<nc:close-session/>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<nc:ok/>
</nc:rpc-reply>
<commit>
The <commit> operation is only available when the :candidate capability is supported.
The input parameters are only supported if the :confirmed-commit capability is supported.
This operation causes all the edits in the <candidate> configuration to be applied to the <running> configuration. If there are no edits, then this operation has no affect.
If multiple sessions have made edits to the <candidate> configuration (because locking was not used), then all these edits will be applied at once, not just the edits from the current session.
It the <candidate> or <running> configurations are locked by another session, then this operation will fail with an 'in-use' error.
Normally, if there have been no changes made to the <candidate> configuration, then this operation has no effect. An <ok/> response will be returned without altering the <running> configuration.
However, if the <running> configuration encountered any errors during the initial load from NV-storage (such as startup-cfg.xml), then the current contents of the <running> configuration will be written to NV-storage, even if there are no changes to the <candidate> configuration.
The :confirmed-commit capability is fully supported:
confirmed-commit:1.0
confirmed-commit:1.1
+---x commit {candidate}?
+---w input
+---w confirmed? empty {confirmed-commit}?
+---w confirm-timeout? uint32 {confirmed-commit}?
+---w persist? string {confirmed-commit}?
+---w persist-id? string {confirmed-commit}?
<commit> Operation Usage
Min parameters: |
0 |
Max parameters: |
4 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
Mandatory Parameters:
none
Optional Parameters:
confirmed:
type: empty
default: none
capabilities needed: confirmed-commit
This parameter indicates that a confirmed commit operation should be started or extended.
confirm-timeout:
type: number
default: 600
capabilities needed: confirmed-commit
This parameter indicates the number of seconds to wait before canceling the confirmed commit automatically.
persist:
type: string
default: none
capabilities needed: confirmed-commit and base:1.1
This parameter sets the string that all sessions can use to access this confirmed commit procedure.
persist-id:
type: string
default: none
capabilities needed: confirmed-commit and base:1.1
This parameter changes the 'persist' string that all sessions can use to access this confirmed commit procedure. It is used to allow access to the confirmed commit operation, if the 'persist' parameter is not present.
Returns:
<ok/>
Possible Operation Errors:
access-denied: access control configured to deny access to this operation
in-use: the <candidate> or <running> configuration is locked by another session.
operation-failed
must-violation: must statement is false
too-few-elements: min-elements expression is false
too-many-elements: max-elements expression is false
data-not-unique: unique statement violation
data-missing: mandatory statement violation or missing leafref path object
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="5">
<nc:commit/>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="5">
<nc:ok/>
</nc:rpc-reply>
<copy-config>
The <copy-config> operation is used to transfer entire configuration databases in one operation.
The <source> and <target> parameters are simple to understand, but there are many interactions and some complexity, due to so many combinations of optional capabilities that are possible.
When in-line configuration data is used in the <source> parameter, it is applied to the <target> differently, depending on the database.
If the <target> is the <startup> configuration, then the new configuration simply overwrites the old one, and no validation is done at all.
If the <target> is the <candidate> or <running> configuration, then the new configuration overwrites the old one, but validation is done similar to the <edit-config> operation. All validation and access control procedures are followed.
The <with-defaults> parameter is also available for filtering the output as it is copied to the target.
+---x copy-config
+---w input
+---w target
| +---w (config-target)
| +--:(candidate)
| | +---w candidate? empty {candidate}?
| +--:(running)
| | +---w running? empty {writable-running}?
| +--:(startup)
| | +---w startup? empty {startup}?
| +--:(url)
| +---w url? inet:uri {url}?
+---w source
+---w (config-source)
+--:(candidate)
| +---w candidate? empty {candidate}?
+--:(running)
| +---w running? empty
+--:(startup)
| +---w startup? empty {startup}?
+--:(url)
| +---w url? inet:uri {url}?
+--:(config)
+---w config? <anyxml>
<copy-config> Operation Usage
Min parameters: |
2 |
Max parameters: |
3 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Capabilities optional: |
Mandatory Parameters:
source
type: container with 1 of N choice of leafs
usage: mandatory
default: none
This parameter specifies the name of the source database for the copy operation.
container contents: 1 of N:
candidate
type: empty
capabilities needed::candidate
running
type: empty
capabilities needed: none
startup
type: empty
capabilities needed: :startup
config:
type: container (in-line configuration data)
capabilities needed: none
Access to the entire database is required for this operational mode.
url:
type: inet:uri
capabilities need: :url
The scheme ‘file’ is supported if the :url capability is supported
The scheme ‘ftp’ is supported if the :url capability is supported and the --with-url-ftp parameter is set to ‘true’
The scheme ‘tftp’ is supported if the :url capability is supported and the --with-url-ftp parameter is set to ‘true’
target
type: container with 1 of N choice of leafs
usage: mandatory
default: none
This parameter specifies the name of the target database for the copy operation.
container contents: 1 of N:
candidate
type: empty
capabilities needed::candidate
startup
type: empty
capabilities needed: :startup
url:
type: inet:uri
capabilities need: :url
The scheme ‘file’ is supported if the :url capability is supported
The scheme ‘ftp’ is supported if the :url capability is supported and the --with-url-ftp parameter is set to ‘true’
The scheme ‘tftp’ is supported if the :url capability is supported and the --with-url-ftp parameter is set to ‘true’
Optional Parameters:
with-defaults
type: enumeration (none report-all report-all-tagged trim explicit)
default: none
capabilities needed: :with-defaults
This parameter controls how nodes containing only default values are copied to the target database. If the <target> parameter is <candidate>, then this parameter will be ignored.
with-owners
type: empty
default: not present (false)
capabilities needed: none
This parameter specifies that the owner metadata should be returned in the configuration (if applicable).
The --save-owners CLI parameter must be 'true' in order for any owner string attributes to be returned
depth:
type: union (uint16, ‘unbounded’)
default: unbounded
capabilities needed: none
The --with-yumaworks-system CLI parameter must be set to 'true' for this parameter to be present
This parameter controls the depth of subtrees copied to the target. It is the same as the RESTCONF protocol “depth” query parameter.
Returns:
<ok/> or <rp-error>
Possible Operation Errors:
access-denied : access control configured to deny access to this operation
in-use: the configuration indicated by the <target> parameter is locked by another session.
<commit> errors, if the <target> parameter is the <running> configuration
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="7">
<nc:copy-config>
<nc:source>
<nc:running/>
</nc:source>
<nc:target>
<nc:startup/>
</nc:target>
</nc:copy-config>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="7">
<nc:ok/>
</nc:rpc-reply>
<create-subscription>
The <create-subscription> operation is used to start a NETCONF notifications subscription.
The mandatory 'NETCONF' stream is supported by netconfd-pro. Event streams are created 2 ways:
the --event-stream and --event-stream-map CLI parameters
the yumaworks-event-stream.yang module
A replay subscription is created by including the <startTime> parameter.
The subscription will continue until the session is closed, unless the <stopTime> parameter is present. In that case, the subscription will terminate at that time (if in the future) or when all replay notifications with a lower <eventTime> value have been delivered.
This operation will only be present if the --with-notifications parameter is set to 'true'.
The replay notification feature can be controlled with the --eventlog-size configuration parameter. If this is set to '0', then no stored notifications will be available for replay. The default is store the most recent 1000 system notification events.
An entry will be created in the 'subscriptions' data structure in the ietf-netconf-monitoring module, when the subscription is successfully started.
+---x create-subscription
+---w input
+---w stream? streamNameType
+---w filter? <anyxml>
+---w startTime? yang:date-and-time
+---w stopTime? yang:date-and-time
<create-subscription> Operation Usage
Min parameters: |
0 |
Max parameters: |
4 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
|
Capabilities optional: |
Mandatory Parameters:
none
Optional Parameters:
stream
type: string
default: 'NETCONF'
This parameter specifies the name of the notification stream for this subscription request.
filter
type: anyxml (same as the <get> or <get-config> filter parameter)
default: none
This parameter specifies a boolean filter that should be applied to the stream. This is the same format as the standard <filter> element in RFC 4741, except that instead of creating a subset of the database for an <rpc-reply> PDU, the filter is used as a boolean test to send or drop each notification delivered from the server.
If any nodes are left in the 'test response', the server will send the entire notification.
If the result is empty after the filter is applied to the “test response”, then the server will not send the notification at all.
It is possible that access control will either cause the a notification to be dropped entirely, or may be pruned and still delivered. The standard is not clear on this topic. The netconfd-pro server will prune any unauthorized payload from an eventType, but if the <eventType> itself is unauthorized, the entire notification will be dropped.
startTime
type: yang:date-and-time
This parameter causes any matching replay notifications to be delivered by the server, if notification replay is supported by the server. A notification will match if its <eventTime> value is greater or equal to the value of this parameter.
stopTime
type: yang:date-and-time
usage: not allowed unless startTime is also present
This parameter causes any matching replay notifications to be delivered by the server, if notification replay is supported by the server. A notification will match if its <eventTime> value is less than the value of this parameter.
This parameter must be greater than the <startTime> parameter, or an error will be returned by the server.
Returns:
<ok/>
Possible Operation Errors:
access-denied
subscription already active
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<ncEvent:create-subscription xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
<ncEvent:startTime>2009-01-01T00:00:00Z</ncEvent:startTime>
</ncEvent:create-subscription>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<nc:ok/>
</nc:rpc-reply>
<delete-backup>
The <delete-backup> operation is used to delete a backup configuration file previously created with the <backup> operation.
The --with-yumaworks-system CLI parameter must be set to 'true' in the for this operation to be present.
The agt_backup_dir path string must be set to a valid directory in the agt_profile struct.
By default, only users designated as 'superuser' accounts are allowed to invoke this operation.
+---x delete-backup
+---w input
+---w filename ywt:NcxFileName
<delete-backup> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
filename:
The file name with extension for the backup. The directory is determined by the agt_backup_dir profile variable. The file name string is specified by the NcxFileName typedef in yumaworks-types.yang.
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
none
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="5" trace-id="5" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<delete-backup xmlns="http://yumaworks.com/ns/yumaworks-system">
<filename>foo.xml</filename>
</delete-backup>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="5" trace-id="5" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<delete-config>
The <delete-config> operation is used to delete the entire contents of a NETCONF database.
By default, only users designated as 'superuser' accounts are allowed to invoke this operation.
If the :startup capability is supported, then the <startup> configuration can be cleared. This will affect the startup file that was actually loaded into the server, or the default file if the --no-startup configuration parameter was used.
If the --no-nvstore parameter is used, then there will not be any startup configuration file to delete.
Note
The <running> and <candidate> configurations cannot be deleted.
The <startup> configuration can be repopulated with the <copy-config> or <commit> operations.
+---x delete-config
+---w input
+---w target
+---w (config-target)
+--:(startup)
| +---w startup? empty {startup}?
+--:(url)
+---w url? inet:uri {url}?
<delete-config> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
Mandatory Parameters:
target
type: container with 1 of N choice of leafs
This parameter specifies the name of the target database for the <delete-config> operation.
container contents: 1 empty leaf value supported:
startup
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
access-denied
in-use: <startup> database is locked
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<nc:delete-config>
<nc:target>
<nc:startup/>
</nc:target>
</nc:delete-config>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<nc:ok/>
</nc:rpc-reply>
<delete-subscription>
The <delete-subscription> operation is used to delete a notification subscription, using RFC 8639 subscriptions. This is required to used YANG Push. Only the session that started the subscription can delete a subscription on that session.
Note
This operation is not present unless the server is built with the WITH_YANG_PUSH=1 or EVERYTHING=1 option and the “yang-push” bundle is loaded.
+---x delete-subscription
+---w input
+---w id subscription-id
<delete-subscription> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none (--bundle=yang-push required) |
Capabilities optional: |
none |
Mandatory Parameters:
id
type: subscription-id
This parameter specifies the subscription ID of the subscription to delete.
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<delete-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>1</id>
</delete-subscription>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
When a subscription is terminated, a notification is sent to the subscription before it is deleted:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2020-09-07T00:44:39Z</eventTime>
<subscription-terminated xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>1</id>
<reason xmlns:sn="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">sn:no-such-subscription</reason>
</subscription-terminated>
</notification>
<discard-changes>
The <discard-changes> operation is used to remove any edits from the <candidate> configuration. This is done by deleting the contents of the <candidate> and re-filling it with the contents of the <running> configuration.
If the <candidate> configuration is locked by another session, this operation will fail.
+---x discard-changes {candidate}?
<discard-changes> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
access-denied
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
<nc:discard-changes/>
</nc:rpc>
Example Reply:
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
<nc:ok/>
</nc:rpc-reply>
<edit-config>
The <edit-config> operation is used to alter the target database.
The target database is the <candidate> configuration if the --target configuration parameter is set to 'candidate', and the <running> configuration if it is set to 'running'.
The 'nc:operation' attribute must appear within the inline <config> parameter contents if the <default-operation> parameter is set to 'none', or the <edit-config> operation will have no affect. This is not an error condition.
This attribute may appear any number of times, and be arbitrarily nested within the <config> parameter contents. Certain combinations will cause errors, however, so this must be done carefully.
For example, a 'delete' operation nested within a 'create' operation is an error, because the conditions for both operations cannot possibly be satisfied at once.
Other combinations, such as 'merge' within 'create' are not an error because there are no conflicting conditions present for either operation.
+---x edit-config
+---w input
+---w target
| +---w (config-target)
| +--:(candidate)
| | +---w candidate? empty {candidate}?
| +--:(running)
| +---w running? empty {writable-running}?
+---w default-operation? enumeration
+---w test-option? enumeration {validate}?
+---w error-option? enumeration
+---w (edit-content)
+--:(config)
| +---w config? <anyxml>
+--:(url)
+---w url? inet:uri {url}?
<edit-config> Operation Usage
Min parameters: |
2 |
Max parameters: |
5 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
|
Capabilities optional: |
Mandatory Parameters:
config
type: anyxml
This parameter specifies the subset of the database that should be changed.
target
type: container with 1 of N choice of leafs
This parameter specifies the name of the target database for the edit operation.
container contents: choice: 1 of N:
candidate
type: empty
capabilities needed::candidate
running
type: empty
capabilities needed: :writable-running
Optional Parameters:
default-operation
type: enumeration (merge replace none)
default: merge
This parameter specifies which edit operation will be in effect at the start of the operation, before any 'nc:operation' attribute is found.
error-option
type: enumeration (stop-on-error continue-on-error rollback-on-error
default: stop-on-error
This parameter specifies what the server should do when an error is encountered.
test-option
type: enumeration (test-then-set set test-only)
default: 'test-then-set' if :validate capability is supported and 'set' otherwise
Returns:
<ok/>
Possible Operation Errors:
access-denied
in-use (target database is locked by another session)
<commit> validation errors: if test-then-set is used or the target is the <running> configuration.
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="12">
<nc:edit-config>
<nc:target>
<nc:candidate/>
</nc:target>
<nc:default-operation>merge</nc:default-operation>
<nc:test-option>set</nc:test-option>
<nc:error-option>rollback-on-error</nc:error-option>
<nc:config>
<t:musttest xmlns:t="http://netconfcentral.org/ns/test">
<t:A nc:operation="create">'testing one two'</t:A>
</t:musttest>
</nc:config>
</nc:edit-config>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="12">
<nc:ok/>
</nc:rpc-reply>
<establish-subscription>
The <establish-subscription> operation is used to start a notification subscription, using RFC 8639 subscriptions. This is required to used YANG Push.
This operation is not present unless the server is build with the WITH_YANG_PUSH=1 or EVERYTHING=1 make flag and the “yang-push” bundle is loaded.
Refer to the YANG Push section for complete usage information for this feature.
This operation has two usage modes, using a YANG choice for this purpose:
event stream subscriptions: similar to using the <create-subscription> operation except RFC 8639 subscriptions are used.
Multiple subscriptions per session are allowed.
There is no way to tell which event stream subscription caused an event to be included.
This feature allows a session to subscribe to multiple event streams at once, or the same event stream (hopefully with different, non-overlapping filters).
It is possible for a client session to receive the same notification more than once if a session subscribes to the same event stream multiple times.
Each client subscribing to an event-stream has access to the same set notification events (assuming NACM rights are the same). In this way, event stream subscriptions are shared subscriptions.
datastore subscriptions: YANG Push subscriptions to a specific datastore.
These are not shared subscriptions.
There is no event stream or replay buffer
Each subscription gets its own updates and other notifications.
There are 2 types of dynamic subscription defined in RFC 8641, which are periodic and on-change subscriptions. There are different sets of parameters for each type.
+---x establish-subscription
+---w input
| +---w (target)
| | +--:(stream)
| | | +---w (stream-filter)?
| | | | +--:(by-reference)
| | | | | +---w stream-filter-name stream-filter-ref
| | | | +--:(within-subscription)
| | | | +---w (filter-spec)?
| | | | +--:(stream-subtree-filter)
| | | | | +---w stream-subtree-filter? <anydata> {subtree}?
| | | | +--:(stream-xpath-filter)
| | | | +---w stream-xpath-filter? yang:xpath1.0 {xpath}?
| | | +---w stream stream-ref
| | | +---w replay-start-time? yang:date-and-time {replay}?
| | +--:(yp:datastore)
| | +---w yp:datastore identityref
| | +---w (yp:selection-filter)?
| | +--:(yp:by-reference)
| | | +---w yp:selection-filter-ref selection-filter-ref
| | +--:(yp:within-subscription)
| | +---w (yp:filter-spec)?
| | +--:(yp:datastore-subtree-filter)
| | | +---w yp:datastore-subtree-filter? <anydata> {sn:subtree}?
| | +--:(yp:datastore-xpath-filter)
| | +---w yp:datastore-xpath-filter? yang:xpath1.0 {sn:xpath}?
| +---w stop-time? yang:date-and-time
| +---w dscp? inet:dscp {dscp}?
| +---w weighting? uint8 {qos}?
| +---w dependency? subscription-id {qos}?
| +---w encoding? encoding
| +---w (yp:update-trigger)?
| +--:(yp:periodic)
| | +---w yp:periodic!
| | +---w yp:period centiseconds
| | +---w yp:anchor-time? yang:date-and-time
| +--:(yp:on-change) {on-change}?
| +---w yp:on-change!
| +---w yp:dampening-period? centiseconds
| +---w yp:sync-on-start? boolean
| +---w yp:excluded-change* change-type
+--ro output
+--ro id subscription-id
+--ro replay-start-time-revision? yang:date-and-time {replay}?
<establish-subscription> Operation Usage
Min parameters: |
2 |
Max parameters: |
variable |
Return type: |
data (id) |
YANG file: |
|
Capabilities needed: |
none (--bundle=yang-push required) |
Capabilities optional: |
none |
Event Stream Subscription
Mandatory Parameters:
stream
type: stream-ref
This parameter specifies the name of the event stream to use. The NETCONF event stream should always be present. Other values are derived from the event stream configuration on the server.
Optional Parameters:
stream-filter: choice of 3 options
stream-filter-name:
type: stream-filter-ref
default: none
This parameter specifies the name of a stream filter to use in the
/filters/stream-filterlist
stream-subtree-filter:
type: anydata
default: none
This parameter specifies the inline subtree filter to use
stream-xpath-filter:
type: xpath1.0
default: none
This parameter specifies the inline XPath filter to use. Prefixes are not required but if they are provided then an “xmlns” attribute defining each prefix to namespace mapping must be present in the XML.
replay-start-time
type: date-and-time
default: none
This parameter specifies that replay mode is desired and the replay should include notifications with timestamps greater than the specified value. The replay-start-time-revision leaf is returned if the actual value used is greater than the value requested.
stop-time
type: date-and-time
default: none
This parameter specifies that replay mode is desired and the replay should stop including notifications with timestamps less than the specified value.
encoding
type: identityref
default: none
This parameter specifies the notification message encoding that is desired. The only value supported at this time is
encoding-xml.
Datastore Subscription
Mandatory Parameters:
datastore
type: identityref
This parameter specifies the datastore that will be used for the subscription; One of:
candidate
running
operational
update-trigger: choice of 2 options
periodic
type: presence container
default: none
This parameter specifies that a periodic subscription is desired. These subscriptions are controlled by the --push-max-periodic parameter. A new subscription will only be established if the limit has not already been reached.
child period (mandatory)
type: centiseconds
default: none
This parameter specifies the period to wait between updates. The --push-min-period parameter is used to enforce restrictions beyond the standard.
child anchor-time
type: date-and-time
default: none
This parameter is not yet supported.
on-change
type: presence container
default: none
This parameter specifies that an on-change subscription is desired. These subscriptions are controlled by the --push-max-operational parameter, if the datastore parameter is ‘operational’. A new subscription will only be established if the limit has not already been reached.
child dampening-period (usually mandatory)
type: centiseconds
default: none
This parameter specifies the dampening period to wait between on-change updates. The --push-min-dampening parameter is used to enforce restrictions beyond the standard.
This parameter can be left out for a simulated operational on-change subscription. In that case, the --push-simop-period parameter will be used instead.
If both parameters apply, then the maximum value of both of them will be used as the dampening period value.
child sync-on-start (optional)
type: boolean
default: true
This parameter specifies that the first update should be a push-update instead of a push-change-update.
child excluded-change (leaf-list of change-type) (optional)
type: enumeration (create, delete, insert, move, replace)
default: none (do not exclude any events
This parameter specifies that the event types that should be excluded from the subscription. At least one event type must be included or a ‘cant-exclude’ error-app-tag will be returned. If the subscription is for simulated operational on-change events, then the “replace” event cannot be excluded.
Optional Parameters:
selection-filter: choice of 3 options
selection-filter-ref:
type: selection-filter-ref
default: none
This parameter specifies the name of a selection filter to use in the
/filters/selection-filterlist
datastore-subtree-filter:
type: anydata
default: none
This parameter specifies the inline subtree filter to use
datastore-xpath-filter:
type: xpath1.0
default: none
This parameter specifies the inline XPath filter to use. Prefixes are not required but if they are provided then an “xmlns” attribute defining each prefix to namespace mapping must be present in the XML.
stop-time
type: date-and-time
default: none
This parameter specifies that replay mode is desired and the replay should stop including notifications with timestamps less than the specified value.
encoding
type: identityref
default: none
This parameter specifies the notification message encoding that is desired. The only value supported at this time is “encoding-xml”.
Returns:
data
id: subscription-id
replay-start-time-revision
Possible Operation Errors:
access-denied
in-use (target database is locked by another session)
All error-tags and error-app-tags defined in RFC 8639 and RFC 8641 are supported
Example Request for a stream subscription for the NETCONF stream with an XPath filter for the <netconf-config-change> Event.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="15" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<stream-xpath-filter>/netconf-config-change</stream-xpath-filter>
<stream>NETCONF</stream>
</establish-subscription>
</rpc>
Example Reply: contains the subscription ID (1)
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="15" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<id xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">1</id>
</rpc-reply>
Example Datastore Request for the periodic subscription on the operational datastore, with an XPath filter for the /netconf-state/sessions object
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="16" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<datastore xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"
xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:operational</datastore>
<datastore-xpath-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">/netconf-state/sessions</datastore-xpath-filter>
<periodic xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<period>1000</period>
</periodic>
</establish-subscription>
</rpc>
Example Reply: contains the subscription ID (2)
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="16" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<id xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">2</id>
</rpc-reply>
<get>
The <get> operation is used to retrieve data from the <running> configuration, or non-configuration data available on the server.
Warning
Using this operation without any filter will return all data nodes available on the server. This may be generate a large response and waste resources.
A filter parameter (e.g., subtree or XPath) should always be used with this operation.
To select only specific subsets of all available data, use subtree or XPath filtering by providing a <filter> parameter. Namespace prefixes are optional to use in XPath expressions. The netconfd-pro will figure out the proper namespace, if possible. If prefixes are used, then they must be valid XML prefixes with a namespace properly declared in the PDU.
The retrieval of leaf or leaf-list nodes with default values is controlled with the <with-defaults> parameter.
If a portion of the requested data is not available due to access control restrictions, then that data is silently dropped from the <rpc-reply> message. It is implicitly understood that the client is only requesting data for which it is authorized to receive, in the event such data is selected in the request.
+---x get
+---w input
| +---w filter? <anyxml>
| +---w ysys:with-owners? empty
| +---w ysys:depth? union
| +---w ysys:module-tag* string
| +---w timefilter:if-modified-since? yang:date-and-time
+--ro output
+--ro data? <anyxml>
<get> Operation Usage
Min parameters: |
0 |
Max parameters: |
6 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
none |
Capabilities optional: |
Mandatory Parameters:
none
Optional Parameters:
filter
type='subtree'
type: anyxml
This parameter specifies the subset of the database that should be retrieved.
type='xpath' select='expr'
type: empty
The unqualified 'select' attribute is used to specify an XPath filter.
with-defaults
type: enumeration (none report-all report-all-tagged trim explicit)
The --default-style parameter used as the default if no value is provided
This parameter controls how default leaf and leaf-list nodes are returned by the server.
if-modified-since
type: date-and-time
usage: optional
pre-requisites: --with-yuma-time-filter=true
This parameter requests that configuration data only be returned if any of the running datastore contents have been modified since this value.
Monitoring data (config = false) does not affect the datastore timestamp.
If the running datastore has not been modified since this timestamp, then an empty <data> element will be returned, and the request will not be processed.
with-owners
type: empty
default: not present (false)
pre-requisites: --with-yumaworks-system=true
This parameter specifies that the owner metadata should be returned in the configuration (if applicable).
No owner attributes will be returned unless the --save-owners parameter is set to 'true'.
depth:
type: union (uint16, ‘unbounded’)
default: unbounded
pre-requisites: --with-yumaworks-system=true
This parameter controls the depth of subtrees copied to the target. It is the same as the RESTCONF protocol “depth” query parameter.
module-tag:
type: string
default: none
pre-requisites: --with-yumaworks-system=true
This parameter is used as a filter to include only data nodes from modules that match the module-tag value.
Multiple module-tag parameters can be used, combined to form a logical OR expression.
At least one module-tag must match or no data will be returned.
This filter is combined with the XPath or subtree filter, if present.
Returns:
<data> element
Possible Operation Errors:
access-denied
invalid-value
Example subtree Filter Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="4">
<nc:get>
<nc:filter type="subtree">
<proc:proc xmlns:proc="http://netconfcentral.org/ns/proc">
<proc:cpuinfo>
<proc:cpu>
<proc:cpu_MHz/>
</proc:cpu>
</proc:cpuinfo>
</proc:proc>
</nc:filter>
</nc:get>
</nc:rpc>
Equivalent XPath Filter Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="4">
<nc:get>
<nc:filter type="xpath" select="/proc/cpuinfo/cpu/cpu_MHz"/>
</nc:get>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
last-modified="2011-08-21T17:51:46Z" message-id="4">
<nc:data>
<proc:proc xmlns:proc="http://netconfcentral.org/ns/proc">
<proc:cpuinfo>
<proc:cpu>
<proc:cpu_MHz>1600.000</proc:cpu_MHz>
<proc:processor>0</proc:processor>
</proc:cpu>
<proc:cpu>
<proc:cpu_MHz>2667.000</proc:cpu_MHz>
<proc:processor>1</proc:processor>
</proc:cpu>
</proc:cpuinfo>
</proc:proc>
</nc:data>
</nc:rpc-reply>
<get-bulk>
The <get-bulk> operation is used to iterate through the entries of a YANG list from the NETCONF server. It is defined in the yumaworks-getbulk.yang module.
This operation requires that WITH_RESTCONF=1 or EVERYTHING=1 is used to build the server image, even though this is a NETCONF operation.
This operation will only be present if the --with-yumaworks-getbulk parameter is set to 'true' (the default value).
The list-target parameter is used to specify the YANG list object that will be retrieved. If this YANG list is nested within other lists then all corresponding ancestor keys for those lists are expected in the path string. Only one list can be iterated at a time.
The list-test parameter allows an XPath boolean expression to be used to test each list-target entry. It is used to select only a subset of the list entries to reduce the number of entries returned.
If a portion of the requested data is not available due to access control restrictions, then that data is silently dropped from the <rpc-reply> message. It is implicitly understood that the client is only requesting data for which it is authorized to receive, in the event such data is selected in the request.
Handling the 'count' parameter
Specifies the maximum number of list entries to return, in the range '1 .. --max-getbulk' (or '1 .. 512' if --max-getbulk is set to 0).
If the client's 'count' exceeds the value specified by --max-getbulk, the server returns an error with the message "too many entries".
Example error response:
<error> <error-type>protocol</error-type> <error-tag>resource-denied</error-tag> <error-app-tag>limit-reached</error-app-tag> <error-path>/nc:rpc/ybulk:get-bulk/ybulk:count</error-path> <error-message xml:lang="en">too many entries</error-message> <error-info> <error-number>12</error-number> </error-info> </error>
The 'max_entries' field in the GET2 Control Block (see GETBULK Support) is set to the client's requested count, as long as it is within the allowed range.
Iterator Usage
Some important application design considerations:
This operation is designed to be completely stateless for the server.
There are no reserved resources used for a client "walk" through the list entries.
The list may change between invocations of this operation.
The 'last-keys' subtree is used to prevent entries from being missed or duplicated.
Note
This operation does not take a "snapshot" of server data.
No extra memory is used in the server for this operation.
There is no setup or cleanup needed.
The client is expected to start the iteration through the YANG list by providing the target and filtering parameters. The 'last-keys' parameter is not expected in the first invocation.
The client will expect the 'last-keys' output parameter to be returned in the response. This data can then be used directly as the 'last-keys' input parameter for the next iteration.
For faster performance, set the count parameter to a value other than the default '1'. This parameter is not the same as the --max-getbulk CLI parameter, used by the server instrumentation to limit the maximum entries per callback.
For a list with multiple keys, it is possible to fix 1 or more key values and only iterate through the remaining key leafs for the list.
If a key value is provided in the fixed-keys input parameter then the corresponding last-keys value (if any) will be ignored.
If all key values are provided in the fixed-keys input parameter then only one list entry will be returned (if found).
<get-bulk> Output
The output of this operation returns two components:
data: anydata container with zero or more instaces of the list-target as child nodes,
last-keys: anydata container that will have the key leaf nodes from the last list entry returned in the 'data' container
Note that the output is different than normal NETCONF retrieval operations:
The output data will only contain instances of the requested list-target.
The ancestor nodes will not be present, like a <get> operation.
The client should remember the list-target, since it is not returned in the response.
Note
Starting in release 22.10-14:
The ywx:datapath attribute is used in the output "<data>" node to allow the list data nodes to be properly identified.
Example: <data> Element Prior to 22.10-14
Note that since the 'data' node is 'anydata', the actual schema object for the 'module' list is not used on the yangcli-pro or yp-shell client.
<rpc-reply message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<data>
<!-- module elements removed -->
</data>
</bulk>
</rpc-reply>
Example: <data> Element Starting in 22.10-14
Note that the ywx:datapath attribute identifies the parent node of the list-target object.
This will cause yangcli-pro and yp-shell to treat the 'data' container as the 'modules-state' parent node.
This allows the XML to be properly parsed, the same way as data returned from a data retrieval command such as sget.
This format is not XPath.
The first node will contain a module prefix (not module name like RFC 7951)
Descendant nodes will not have a prefix unless the module prefix changes due to an augment from an external module.
<rpc-reply message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<data xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
ya:datapath="/yanglib:modules-state">
<!-- module elements removed -->
</data>
</bulk>
</rpc-reply>
<get-bulk> Parameters
+---x get-bulk
+---w input
| +---w datastore? enumeration
| +---w list-target string
| +---w count? uint32
| +---w depth? union
| +---w with-defaults? with-defaults-mode
| +---w last-keys
| +---w list-test yang:xpath1.0
| +---w fixed-keys
+--ro output
+--ro bulk
+--ro data
+--ro last-keys
<get-bulk> Operation Usage
Min parameters: |
1 |
Max parameters: |
8 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
none |
Capabilities optional: |
Mandatory Parameters:
list-target
type: string (RESTCONF path URI)
usage: mandatory
This parameter identifies the list object that is being retrieved. This must be a path expression used to represent a list data node. It is formatted like a RESTCONF path expression, except module names are not mandatory if they are unique.
Optional Parameters:
datastore
type: enumeration (candidate running startup)
usage: optional
default: running
This parameter specifies the name of the source database for the retrieval operation. It is ignored if the 'list-target' specifies a non-configuration data node.
enum:
candidatecapabilities needed::candidate
enum :
runningcapabilities needed: none
enum:
startupcapabilities needed: :startup
count
type: unint32
usage: optional
default: 1
The maximum number of list entries to return.
content
type: enumeration
usage: optional
default: all
This parameter specifies which type of content to include, exactly the same as the RESTCONF “content” query parameter
enum:
configInclude only config=true descendant data nodes
enum:
nonconfiginclude only config=false descendant data nodes
enum:
allinclude all descendant data nodes
depth
type: union (uint16, ‘unbounded’)
usage: optional
default: unbounded
This parameter is used as defined in the RESTCONF protocol. The value '1' is associated with the list-object node itself. This value can be used to simply test for the existence of any instances of the list-object.
with-defaults
type: enumeration (none report-all report-all-tagged trim explicit)
usage: --default-style configuration parameter used as the default if no value is provided
This parameter controls how default leaf and leaf-list nodes are returned by the server.
last-keys
type: container of leafs
usage: optional
default: start with the first list entry if this parameter not present
This parameter contains the key values of a list entry to start the search from.
Usually this is the same as the <last-keys> container returned from the previous call to <get-bulk>.
Any last-keys values can be sent, not just the previous value returned by the server. The lexi-next entry for each provided key will be checked.
All key leafs must be in the same order as defined in the YANG list, and all key leafs must be present.
The 'fixed-keys' parameter values may override values in this parameter.
list-test
type: leaf containing an XPath expression
usage: optional
default: return all selected list-target entries
This parameter contains an XPath expression. The document root and the context node are set to the list instance being tested. The expression can only reference descendant-or-self nodes The XPath result will be converted with the boolean() function if needed 'true' boolean result : include list instance 'false' boolean result: exclude list instance
fixed-keys
type: container of leafs
usage: optional
default: none
This parameter contains the key values of a target list entry that should not be changed. These keys will be fixed instead of iterating through all possible values of that key.
Each key value overrides any 'last-keys' corresponding 'last-keys' value
Returns:
<bulk> element
<data> element
Contains the requested list entries. Each child element in this container will represent one instance of the list object requested by the 'list-target' parameter.
<last-keys> element
Contains the key leafs from the last list entry in the <data> element. This container can be passed back to the server as the <last-keys> parameter to continue the retrieval at the entry after the one specified by the key leafs in this container.
Possible Operation Errors:
access-denied
invalid-value
<get-bulk> Simple Example
Simple Iterator: First Request
In this example, the non-NMDA YANG library is retrieved. There are no ancestor list keys to specify in this example.
list-target:
/modules-state/modulecount:
2last-keys: not present
Example get-bulk Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<list-target>/modules-state/module</list-target>
<count>2</count>
</get-bulk>
</rpc>
Simple Iterator: First Response
Note that 2 'module' list entries are returned and the 'last-keys' container has the keys of the second 'module' list entry.
Example Reply:
<rpc-reply message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<data xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
ya:datapath="/yanglib:modules-state">
<module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<name>ietf-netconf</name>
<revision>2011-06-01</revision>
<namespace>urn:ietf:params:xml:ns:netconf:base:1.0</namespace>
<feature>candidate</feature>
<feature>confirmed-commit</feature>
<feature>rollback-on-error</feature>
<feature>validate</feature>
<feature>url</feature>
<feature>xpath</feature>
<conformance>true</conformance>
</module>
<module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<name>iana-crypt-hash</name>
<revision>2014-08-06</revision>
<schema>http://localhost/restconf/yang/iana-crypt-hash/2014-08-06</schema>
<namespace>urn:ietf:params:xml:ns:yang:iana-crypt-hash</namespace>
<feature>crypt-hash-md5</feature>
<feature>crypt-hash-sha-256</feature>
<feature>crypt-hash-sha-512</feature>
<conformance>true</conformance>
</module>
</data>
<last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<name xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">iana-crypt-hash</name>
<revision xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">2014-08-06</revision>
</last-keys>
</bulk>
</rpc-reply>
Simple Iterator: Second Request
The client can then save the "<last-keys>" container to continue the retrieval with the next two entries.
list-target:
/modules-state/modulecount:
2last-keys: present, containing values returned in last 'rpc-reply'
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<list-target>/modules-state/module</list-target>
<count>2</count>
<last-keys>
<name xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">iana-crypt-hash</name>
<revision xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">2014-08-06</revision>
</last-keys>
</get-bulk>
</rpc>
Simple Iterator: Second Response
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<data xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
ya:datapath="/yanglib:modules-state">
<module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<name>ietf-inet-types</name>
<revision>2013-07-15</revision>
<schema>http://localhost/restconf/yang/ietf-inet-types/2013-07-15</schema>
<namespace>urn:ietf:params:xml:ns:yang:ietf-inet-types</namespace>
<conformance>false</conformance>
</module>
<module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<name>ietf-netconf-acm</name>
<revision>2012-02-22</revision>
<schema>http://localhost/restconf/yang/ietf-netconf-acm/2012-02-22</schema>
<namespace>urn:ietf:params:xml:ns:yang:ietf-netconf-acm</namespace>
<conformance>true</conformance>
</module>
</data>
<last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<name xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">ietf-netconf-acm</name>
<revision xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">2012-02-22</revision>
</last-keys>
</bulk>
</rpc-reply>
<get-bulk> Nested List Example
In this example, the following made-up complex YANG data structure is used:
container top-one-a {
container top-one {
list second-one {
key "index direction";
leaf index { type string; }
leaf direction { type int8; }
list LIST2 {
key name;
leaf name { type string; }
leaf-list resource2 { type string; }
}
}
}
}
Nested Iterator: First Request
In this example, the nested list 'LIST2' is retrieved.
The parent is also list called 'second-one'
The ancestor keys for this list are for the following entry:
index:
test1direction:
5
list-target:
/top-one-a/top-one/second-one=test1,5/LIST2count:
2last-keys: not present
Note that RESTCONF key value encoding format is used. This is defined in the RESTCONF specification in RFC 8040 Section 3.5.3.
Example get-bulk Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="6"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<list-target>/top-one-a/top-one/second-one=test1,5/LIST2</list-target>
<count>2</count>
</get-bulk>
</rpc>
Nested Iterator: First Response
Note that 2 'LIST2' list entries are returned and the 'last-keys' container has the keys of the second 'LIST2' list entry.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="6"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<data
xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
ya:datapath="/one_list:top-one-a/top-one/second-one">
<LIST2 xmlns="http://ciena.com/ns/yang/one_list">
<name>first</name>
<resource2>aaa</resource2>
<resource2>bbb</resource2>
<resource2>ccc</resource2>
</LIST2>
<LIST2 xmlns="http://ciena.com/ns/yang/one_list">
<name>second</name>
<resource2>xxx</resource2>
</LIST2>
</data>
<last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<name xmlns="http://ciena.com/ns/yang/one_list">second</name>
</last-keys>
</bulk>
</rpc-reply>
The yangcli-pro JSON output for this data will be correct (starting in 22.10-14) because the actual objects are used to parse the data, instead of 'anydata' nodes.
Note that this is most visible on list and leaf-list nodes, which were not rendered as arrays (e.g., list 'LIST2' and leaf-list 'resource2`):
{
"yuma-netconf:rpc-reply": {
"bulk": {
"data": {
"LIST2": [
{
"name":"first",
"resource2": [
"aaa",
"bbb",
"ccc"
]
},
{
"name":"second",
"resource2": [
"xxx"
]
}
]
},
"last-keys": {
"one_list:name":"second"
}
}
}
}
Nested Iterator: Second Request
The client can then save the "<last-keys>" container to continue the retrieval with the next two entries.
list-target:
/top-one-a/top-one/second-one=test1,5/LIST2count:
2last-keys: present, containing values returned in last 'rpc-reply'
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="7"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<list-target>/top-one-a/top-one/second-one=test1,5/LIST2</list-target>
<count>2</count>
<last-keys>
<name xmlns="http://ciena.com/ns/yang/one_list">second</name>
</last-keys>
</get-bulk>
</rpc>
Nested Iterator: Second Response
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="7"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<data
xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
ya:datapath="/one_list:top-one-a/top-one/second-one">
<LIST2 xmlns="http://ciena.com/ns/yang/one_list">
<name>third</name>
<resource2>f-xxx</resource2>
</LIST2>
<LIST2 xmlns="http://ciena.com/ns/yang/one_list">
<name>fourth</name>
<resource2>g-xxx</resource2>
<resource2>h-xxx</resource2>
</LIST2>
</data>
<last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<name xmlns="http://ciena.com/ns/yang/one_list">fourth</name>
</last-keys>
</bulk>
</rpc-reply>
<get-config>
The <get-config> operation is used to retrieve data from a NETCONF configuration database.
To select only specific subsets of all available data, use subtree or XPath filtering by providing a <filter> parameter. Namespace prefixes are optional to use in XPath expressions. The netconfd-pro will figure out the proper namespace, if possible. If prefixes are used, then they must be valid XML prefixes with a namespace properly declared in the PDU.
The retrieval of leaf or leaf-list nodes with default values is controlled with the <with-defaults> parameter.
If a portion of the requested data is not available due to access control restrictions, then that data is silently dropped from the <rpc-reply> message. It is implicitly understood that the client is only requesting data for which it is authorized to receive, in the event such data is selected in the request.
+---x get-config
+---w input
| +---w source
| | +---w (config-source)
| | +--:(candidate)
| | | +---w candidate? empty {candidate}?
| | +--:(running)
| | | +---w running? empty
| | +--:(startup)
| | +---w startup? empty {startup}?
| +---w filter? <anyxml>
| +---w ysys:with-owners? empty
| +---w ysys:depth? union
| +---w ysys:module-tag* string
| +---w timefilter:if-modified-since? yang:date-and-time
+--ro output
+--ro data? <anyxml>
<get-config> Operation Usage
Min parameters: |
1 |
Max parameters: |
7 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
none |
Capabilities optional: |
Mandatory Parameters:
source
type: container with 1 of N choice of leafs
usage: mandatory
This parameter specifies the name of the source database for the retrieval operation.
container contents: 1 of N:
candidate
type: empty
capabilities needed::candidate
running
type: empty
capabilities needed: none
startup
type: empty
capabilities needed: startup
Optional Parameters:
filter
type='subtree'
type: anyxml
This parameter specifies the subset of the database that should be retrieved.
type='xpath' select='expr'
type: empty
The unqualified select attribute is used to specify an XPath filter.
with-defaults
type: enumeration (none report-all report-all-tagged trim explicit)
The --default-style parameter used as the default if no value is provided
This parameter controls how default leaf and leaf-list nodes are returned by the server.
if-modified-since
type: date-and-time
usage: optional
pre-requisites: --with-yuma-time-filter=true
This parameter requests that configuration data only be returned if any of the running datastore contents have been modified since this value.
Monitoring data (config = false) does not affect the datastore timestamp.
If the running datastore has not been modified since this timestamp, then an empty <data> element will be returned, and the request will not be processed.
with-owners
type: empty
default: not present (false)
pre-requisites: --with-yumaworks-system=true
This parameter specifies that the owner metadata should be returned in the configuration (if applicable).
No owner attributes will be returned unless the --save-owners parameter is set to 'true'.
depth:
type: union (uint16, ‘unbounded’)
default: unbounded
pre-requisites: --with-yumaworks-system=true
This parameter controls the depth of subtrees copied to the target. It is the same as the RESTCONF protocol “depth” query parameter.
module-tag:
type: string
default: none
pre-requisites: --with-yumaworks-system=true
This parameter is used as a filter to include only data nodes from modules that match the module-tag value.
Multiple module-tag parameters can be used, combined to form a logical OR expression.
At least one module-tag must match or no data will be returned.
This filter is combined with the XPath or subtree filter, if present.
Returns:
<data> element
Possible Operation Errors:
access-denied
invalid-value
Example subtree Filter Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
<nc:get-config>
<nc:source>
<nc:candidate/>
</nc:source>
<nc:filter type="subtree">
<nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm">
<nacm:rules>
<nacm:moduleRule/>
</nacm:rules>
</nacm:nacm>
</nc:filter>
</nc:get-config>
</nc:rpc>
Equivalent XPath Filter Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
<nc:get-config>
<nc:source>
<nc:candidate/>
</nc:source>
<nc:filter type="xpath" select="/nacm/rules/moduleRule"/>
</nc:get-config>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
last-modified="2011-08-21T17:51:46Z" message-id="3">
<nc:data>
<nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm">
<nacm:rules>
<nacm:moduleRule>
<nacm:moduleName>netconf</nacm:moduleName>
<nacm:allowed-rights>read exec</nacm:allowed-rights>
<nacm:allowed-group>nacm:guest</nacm:allowed-group>
</nacm:moduleRule>
<nacm:moduleRule>
<nacm:moduleName>netconfd-pro</nacm:moduleName>
<nacm:allowed-rights>read write exec</nacm:allowed-rights>
<nacm:allowed-group>nacm:admin</nacm:allowed-group>
<nacm:comment>access to shutdown and restart rpcs</nacm:comment>
</nacm:moduleRule>
<nacm:moduleRule>
<nacm:moduleName>netconf</nacm:moduleName>
<nacm:allowed-rights>read write exec</nacm:allowed-rights>
<nacm:allowed-group>nacm:admin</nacm:allowed-group>
<nacm:allowed-group>nacm:monitor</nacm:allowed-group>
</nacm:moduleRule>
</nacm:rules>
</nacm:nacm>
</nc:data>
</nc:rpc-reply>
<get-data>
The <get-data> operation is used to retrieve data from a NMDA datastore.
The --with-nmda parameter must be set to 'true' for this operation to be present.
To select only specific subsets of all available data, use subtree or XPath filtering by providing a <subtree-filter> or <xpath-filter> parameter. Namespace prefixes are optional to use in XPath expressions. The netconfd-pro will figure out the proper namespace, if possible. If prefixes are used, then they must be valid XML prefixes with a namespace properly declared in the PDU.
The retrieval of leaf or leaf-list nodes with default values is controlled with the <with-defaults> parameter.
If a portion of the requested data is not available due to access control restrictions, then that data is silently dropped from the <rpc-reply> message. It is implicitly understood that the client is only requesting data for which it is authorized to receive, in the event such data is selected in the request.
+---x get-data
+---w input
| +---w datastore ds:datastore-ref
| +---w (filter-spec)?
| | +--:(subtree-filter)
| | | +---w subtree-filter? <anydata>
| | +--:(xpath-filter)
| | +---w xpath-filter? yang:xpath1.0 {nc:xpath}?
| +---w config-filter? boolean
| +---w (origin-filters)? {origin}?
| | +--:(origin-filter)
| | | +---w origin-filter* or:origin-ref
| | +--:(negated-origin-filter)
| | +---w negated-origin-filter* or:origin-ref
| +---w max-depth? union
| +---w with-origin? empty {origin}?
| +---w with-defaults? with-defaults-mode {with-defaults}?
+--ro output
+--ro data? <anydata>
<get-data> Operation Usage
Min parameters: |
1 |
Max parameters: |
7 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
none |
Capabilities optional: |
Mandatory Parameters:
datastore
type: leaf containing a datastore-ref
usage: mandatory
This parameter specifies the name of the source NMDA datastore for the retrieval operation.
enumeration:
candidate
capabilities needed::candidate
running
capabilities needed: none
startup
capabilities needed: startup
operational
capabilities needed: none
Optional Parameters:
subtree-filter
type: anydata
This parameter specifies the subset of the database that should be retrieved.
Cannot be used if xpath-filter present
xpath-filter
type: XPath 1.0 string
This parameter specifies the subset of the database that should be retrieved.
Cannot be used if subtree-filter present
config-filter:
type boolean
Specifies the type of data based on config-stmt. Retrieve all data if this parameter is not present. This is a top-down filter. It will not select nodes within a subtree if the ancestor nodes do not match the filter.
Only relevant if the datastore parameter is ‘operational’.
If set to ‘false’ for any datastore other than ‘operational’ then an empty <data> element will be returned.
origin-filter:
type: leaf-list of type origin-ref..
This parameter will select data nodes with the specified origin. This is a top-down filter. It will not select nodes within a subtree if the ancestor nodes do not match the filter.
Cannot be used if negated-origin-filter present
Can only be used if the datastore parameter is ‘operational’
negated-origin-filter:
type: leaf-list of type origin-ref..
This parameter will select data nodes if they do not have the specified origin. This is a top-down filter. It will not select nodes within a subtree if the ancestor nodes do not match the filter.
Cannot be used if origin-filter present
Can only be used if the datastore parameter is ‘operational’
max-depth:
type: union (uint32, ‘unbounded’)
default: unbounded
capabilities needed: none
This parameter controls the depth of subtrees copied to the target. It is the same as the RESTCONF protocol “depth” query parameter.
with-origin
type: empty
This parameter will cause the origin attribute to be added to data nodes returned by the server.
Can only be used if the datastore parameter is ‘operational’
with-defaults
type: enumeration (none report-all report-all-tagged trim explicit)
usage: --default-style configuration parameter used as the default if no value is provided
This parameter controls how default leaf and leaf-list nodes are returned by the server.
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda">
<datastore xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:operational</datastore>
<subtree-filter>
<addresses xmlns="http://www.yumaworks.com/ns/taddress">
<address/>
</addresses>
</subtree-filter>
<with-origin/>
</get-data>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3" xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda">
<addresses xmlns="http://www.yumaworks.com/ns/taddress">
<address or:origin="or:system">
<last-name>adams</last-name>
<first-name>fred</first-name>
<street>123 elm st.</street>
<city>anytown</city>
<zipcode or:origin="or:learned">90024</zipcode>
<counter>
<i>1</i>
<c1>41</c1>
<c2>42</c2>
</counter>
<counter>
<i>2</i>
<c1>43</c1>
<c2>44</c2>
</counter>
</address>
<address or:origin="or:system">
<last-name>adams</last-name>
<first-name>zed</first-name>
<street>900 first st.</street>
<city>anytown</city>
<zipcode or:origin="or:learned">90024</zipcode>
<counter>
<i>1</i>
<c1>45</c1>
<c2>46</c2>
</counter>
<counter>
<i>2</i>
<c1>47</c1>
<c2>48</c2>
</counter>
</address>
<address or:origin="or:system">
<last-name>flintstone</last-name>
<first-name>fred</first-name>
<street>1200 bc drive</street>
<city>bedrock</city>
<zipcode or:origin="or:learned">10204</zipcode>
<counter>
<i>1</i>
<c1>49</c1>
<c2>50</c2>
</counter>
<counter>
<i>2</i>
<c1>51</c1>
<c2>52</c2>
</counter>
</address>
</addresses>
</data>
</rpc-reply>
<get-ha-status>
The <get-ha-status> operation is used to retrieve status information about the YP-HA service.
+---x get-ha-status
+--ro output
+--ro ha-status
+--ro ha-built? boolean
+--ro ha-role-state? HaRoleState
+--ro ha-role-state-time? yang:date-and-time
+--ro ha-enabled? boolean
+--ro ha-sil-standby? boolean
+--ro ha-server* string
+--ro ha-server-key? string
+--ro ha-initial-active? string
+--ro socket-type? enumeration
+--ro socket-address? inet:ip-address
+--ro socket-port? inet:port-number
+--ro server-id? yt:NcxName
+--ro config-id? uint64
+--ro config-stamp? yang:date-and-time
+--ro config-updates? yang:counter64
+--ro config-failures? yang:counter64
+--ro active-server? yt:NcxName
+--ro last-error-time? yang:date-and-time
+--ro last-error-msg? string
HA Role State
The following typedef is used to convey the current HA role state of a server
typedef HaRoleState {
type enumeration {
enum none {
description HA_STATE_NONE;
}
enum disabled {
description HA_STATE_DISABLED;
}
enum error {
description HA_STATE_ERROR;
}
enum wait-role {
description HA_STATE_WAIT_ROLE;
}
enum be-active {
description HA_STATE_BE_ACTIVE;
}
enum active {
description HA_STATE_ACTIVE;
}
enum be-standby {
description HA_STATE_BE_STANDBY;
}
enum standby {
description HA_STATE_STANDBY;
}
enum shutting-down {
description HA_STATE_SHUTTING_DOWN;
}
}
description "YP-HA role state enumerations";
}
The role states that are considered “stable” are:
none: no HA state assigned. If ha-enabled=true then this will block all management sessions (except DB-API subrpc requests will be processed)
active: this is the HA active server. Only one per HA pool should exist in an HA pool.
standby: this is an HA standby server. One or more of these servers should exist in an HA pool.
HA Status Grouping
The following grouping is defined so the HA status information can be reused in different contexts.
It is currently used for the contents of the ha-status container in the RPC output for the <get-ha-status> operations.
grouping HaStatusParms {
leaf ha-built {
type boolean;
description
"Set to true if the WITH_YP_HA=1 parameter used to build
the server code. Set to false otherwise. If false then no
other parameters are actually active. Only the HA related CLI
parameter values will be reported.
This must be set to 'true' for a working YP-HA configuration.";
}
leaf ha-role-state {
type HaRoleState;
description
"Set to the current YP-HA role state enumeration.
A 'correct' value depends on the configuration and the
timing of the request returning the status.
A stable YP-HA system will have one server with the ha-role-state
value of 'active' and one or more servers with the value
'standby'.";
}
leaf ha-enabled {
type boolean;
description
"Set to the value of the --ha-enabled parameter.
This must be set to 'true' for a working YP-HA configuration.";
}
leaf ha-sil-standby {
type boolean;
description
"Set to the value of the --ha-sil-standby parameter.
Either value can be used without affect on a working
YP-HA configuration.";
}
leaf-list ha-server {
type string;
description
"Set to the value of a --ha-server parameter.
There will be one entry for each instance of
the ha-server leaf-list, or no nodes present
if there are none.
There must be at least two entries for a working YP-HA
configuration.";
}
leaf ha-server-key {
type string;
description
"Set to the value of the --ha-server-key parameter.
This node will not be present unless this parameter is set.
This parameter must be set. A working YP-HA configuration
requires this parameter to be set to the same value for
all servers in the same HA pool.";
}
leaf ha-initial-active {
type string;
description
"Set to the value of the --ha-initial-active parameter.
This leaf will not be present unless it is set.
This parameter is not required for a working YP-HA configuration.
It will impact YP-HA behavior if it is present. In normal
operation it should not be used.";
}
leaf socket-type {
type enumeration {
enum aflocal {
description
"An AF_LOCAL socket will be used for incoming sessions.";
}
enum tcp {
description
"An AF_INET socket will be used for incoming sessions.";
}
}
description
"Specifies the --socket-type parameter.
This parameter must be set to 'tcp' in a working YP-HA configuration.";
}
leaf socket-address {
when "../socket-type = 'tcp'";
type inet:ip-address;
description
"Specifies the --socket-address parameter. This leaf is only relevant
if the socket-type is set to 'tcp'. The value must match the
address field in the ha-server entry for this server, or be set to
the default '0.0.0.0'. The parameter actually means all IP addresses,
not just IPv4 addresses.
Examples:
# if socket-address present it must match the ha-server for this server
ha-server [email protected]:8989
ha-server [email protected]
socket-type tcp
socket-address 192.168.0.20
socket-port 8989
# socket-address not present is OK
ha-server [email protected]
socket-type tcp
socket-port 8088
";
}
leaf socket-port {
when "../socket-type = 'tcp'";
type inet:port-number;
description
"Specifies the --socket-port parameter. This leaf is only relevant
if the socket-type is set to 'tcp'. The value must match the
port field in the ha-server entry for this server. If that is
not present then this leaf must be set to 8088 (the default)
for a working YP-HA configuration.
Examples:
# if port in the ha-server then socket-port must match
ha-server [email protected]:8989
ha-server [email protected]
socket-address 192.168.0.20
socket-type tcp
socket-port 8989
# port must be 8088 if default used in ha-server
ha-server [email protected]
socket-type tcp
socket-port 8088
";
}
leaf server-id {
type yt:NcxName;
description
"The --server-id parameter.
The default is 'server1' if this parameter is not set.
This parameter must match the ha-server entry name for
the server in a working YP-HA configuration.
Example:
# this ha-server is ha1
ha-server [email protected]:8989
ha-server [email protected]
server-id ha1
";
}
leaf config-id {
type uint64;
description
"The config-id ETag of the running datastore that is the current ID
for YP-HA purposes. This leaf will only be present if the ha-role-state
leaf is 'active' or 'standby'.
This leaf should get updated to match the config-id of the
<running> datastore if the configuration changes on the active HA server.
It should be present on a working YP-HA configuration that has finished
its initialization phase.";
}
leaf config-stamp {
type yang:date-and-time;
description
"The config-id Last-Modified timestamp value for the running datastore
for YP-HA purposes. This leaf is only present if the ha-role-state
is set to 'active'. It is not maintained on a standby server.
This leaf should get updated to match the last-modified attribute of the
<running> datastore if the configuration changes on the active HA server.
It should be present on a working YP-HA configuration that has finished
its initialization phase.";
}
}
<get-ha-status> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
ha-status container (See YANG definition above)
Possible Operation Errors:
access-denied
Example db-api-app Command:
> db-api-app --subrpc=get-ha-status --filespec=output1.xml
Example Reply for a server Waiting For HA Role
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="http://yumaworks.com/ns/yumaworks-system">
<ha-status>
<ha-built>true</ha-built>
<ha-role-state>wait-role</ha-role-state>
<ha-enabled>true</ha-enabled>
<ha-sil-standby>false</ha-sil-standby>
<ha-server>[email protected]</ha-server>
<ha-server>[email protected]</ha-server>
<ha-server-key>ha-andy-pool1</ha-server-key>
<socket-type>tcp</socket-type>
<socket-address>0.0.0.0</socket-address>
<socket-port>8088</socket-port>
<server-id>ha1</server-id>
</ha-status>
</rpc-reply>
Example Reply for a server in Active HA Role
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="http://yumaworks.com/ns/yumaworks-system">
<ha-status>
<ha-built>true</ha-built>
<ha-role-state>active</ha-role-state>
<ha-enabled>true</ha-enabled>
<ha-sil-standby>false</ha-sil-standby>
<ha-server>[email protected]</ha-server>
<ha-server>[email protected]</ha-server>
<ha-server-key>ha-andy-pool1</ha-server-key>
<socket-type>tcp</socket-type>
<socket-address>0.0.0.0</socket-address>
<socket-port>8088</socket-port>
<server-id>ha1</server-id>
<config-id>7693</config-id>
<config-stamp>2021-08-30T20:00:44Z</config-stamp>
</ha-status>
</rpc-reply>
Example Reply for a server in Standby HA Role
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="http://yumaworks.com/ns/yumaworks-system">
<ha-status>
<ha-built>true</ha-built>
<ha-role-state>standby</ha-role-state>
<ha-enabled>true</ha-enabled>
<ha-sil-standby>false</ha-sil-standby>
<ha-server>[email protected]</ha-server>
<ha-server>[email protected]</ha-server>
<ha-server-key>ha-andy-pool1</ha-server-key>
<socket-type>tcp</socket-type>
<socket-address>0.0.0.0</socket-address>
<socket-port>8088</socket-port>
<server-id>ha2</server-id>
</ha-status>
</rpc-reply>
Example Reply for a server in stuck in be-active state.
This can happen if the --go-standby operation specifies an HA server that is not really the HA active server.
In this case the standby server needs to reset its HA state (using the --go-none option).
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="http://yumaworks.com/ns/yumaworks-system">
<ha-status>
<ha-built>true</ha-built>
<ha-role-state>be-standby</ha-role-state>
<ha-enabled>true</ha-enabled>
<ha-sil-standby>false</ha-sil-standby>
<ha-server>[email protected]</ha-server>
<ha-server>[email protected]</ha-server>
<ha-server-key>ha-andy-pool1</ha-server-key>
<socket-type>tcp</socket-type>
<socket-address>0.0.0.0</socket-address>
<socket-port>8088</socket-port>
<server-id>ha2</server-id>
</ha-status>
</rpc-reply>
<get-my-session>
The <get-my-session> operation is used to retrieve session customization data for the current session.
The session indent amount, line size, and default behavior for the with-defaults parameter can be controlled at this time.
The module yuma-mysession.yang must be enabled in the server configuration file or CLI parameters for this operation to be available.
+---x get-my-session
+--ro output
+--ro indent? yt:IndentType
+--ro linesize? uint32
+--ro with-defaults? wd:with-defaults-mode
+--ro message-indent? int8
<get-my-session> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
indent
type: int8 (range 0 .. 9)
This parameter specifies the desired logging indent amount for the session.
default: 2
linesize
type: uint32 (range 40 .. 1024)
This parameter specifies the desired line length for the session.
default: 72
with-defaults
type: enumeration (report-all report-all-tagged trim explicit)
This parameter specifies the desired default with-defaults behavior for the session. The server-wide default value is set with the --default-style configuration parameter.
default: none
message-indent
type: int8 (range -1 .. 9)
This parameter specifies the desired message indent amount for the session.
default: -1
Possible Operation Errors:
access-denied
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<myses:get-my-session xmlns:myses="http://netconfcentral.org/ns/mysession"/>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<myses:indent xmlns:myses="http://netconfcentral.org/ns/mysession">3</myses:indent>
<myses:linesize xmlns:myses="http://netconfcentral.org/ns/mysession">72</myses:linesize>
<myses:with-defaults xmlns:myses="http://netconfcentral.org/ns/mysession">report-all</myses:with-defaults>
<myses:message-indent xmlns:myses="http://netconfcentral.org/ns/mysession">-1</myses:message-indent>
</nc:rpc-reply>
<get-schema>
The <get-schema> operation is used to retrieve YANG modules and submodules from the server.
The 'YANG' and 'YIN' formats are supported for all YANG files loaded into the server.
If the <version> parameter is set to the empty string, then the server will return whichever version it supports. If multiple versions are supported, then the server will pick a canonical version, which may not be the most recent version.
The <identifier> parameter must contain the name of the YANG file without any path or file extension specification.
+---x get-schema
+---w input
| +---w identifier string
| +---w version? string
| +---w format? identityref
+--ro output
+--ro data? <anyxml>
<get-schema> Operation Usage
Min parameters: |
3 |
Max parameters: |
3 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
Mandatory Parameters:
identifier
type: string
This parameter specifies the name of the module to retrieve.
Do not use any path specification of file extension; just the module name is entered.
The name is case-sensitive, and must be specified exactly as defined.
version
type: string
This parameter specifies the version of the module to retrieve.
This will be the most recent YANG revision date string defined in a module revision statement.
If any version is acceptable, or if the specific version is not known, then use the empty string.
format
Returns:
<data> element (contents of the YANG file)
Possible Operation Errors:
access-denied
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="55">
<ns:get-schema xmlns:ns="urn:ietf:params:xml:ns:netconf:state">
<ns:identifier>ietf-with-defaults</ns:identifier>
<ns:format>YANG</ns:format>
<ns:version/>
</ns:get-schema>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="55">
<ns:data xmlns:ns="urn:ietf:params:xml:ns:netconf:state">
<!-- entire contents of YANG module would be here, no extra indenting -->
</ns:data>
</nc:rpc-reply>
<get-server-version>
The <get-server-version> operation is used to retrieve the server version and build-date strings.
This information is provided in an RPC operation instead of the <operational> datastore so it is available even if the datastores are not ready to use.
+---x get-server-version
+--ro output
+--ro version? string
+--ro build-date? string
<get-server-version> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
none |
Returns:
<version> element
The version string returned by the ncx_get_version API.
<build-date> element
The build-date string returned by the ncx_get_build_date API.
Possible Operation Errors:
operation-failed
Can occur if version string longer than 512 bytes.
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-server-version xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<version xmlns="http://yumaworks.com/ns/yumaworks-system">21.10-5.1</version>
<build-date xmlns="http://yumaworks.com/ns/yumaworks-system">Mar 9 2022</build-date>
</rpc-reply>
<get-sm-yanglib>
The <get-sm-yanglib> operation is used to retrieve YANG Library information for a Schema Mount Point Identifier. he operation returns the YANG library contents for the specified mount point label.
The standard mechanism is not robust or efficient for several reasons:
The YANG library is duplicated for every mount point instance.
The client does not know the ancestor keys for any mount point instance so must retrieve all instances which is very inefficient since they are the same in each instance.
The YANG library does not exist until the mount point exists. This creates an ordering problem so a client must first create the mount point, get the YANG library, and then start using the mounted modules.
Access control issues can make it difficult to read the YANG module inventory, depending on the mount point instance and the NACM configuration.
Support for '/modules-state' is provided only. The NMDA YANG library is only available via a normal 'get' or 'get-data' operation on the '/yang-library' subtree.
+---x get-sm-yanglib
+---w input
| +---w module yang:yang-identifier
| +---w label yang:yang-identifier
+--ro output
+--ro modules-state
+--ro module-set-id string
x--ro module* [name revision]
x--ro name yang:yang-identifier
x--ro revision union
+--ro schema? inet:uri
x--ro namespace inet:uri
x--ro feature* yang:yang-identifier
x--ro deviation* [name revision]
| x--ro name yang:yang-identifier
| x--ro revision union
x--ro conformance-type enumeration
x--ro submodule* [name revision]
x--ro name yang:yang-identifier
x--ro revision union
+--ro schema? inet:uri
<get-sm-yanglib> Operation Usage
Min parameters: |
2 |
Max parameters: |
2 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
module
type: yang-identifier
This parameter specifies the name of the module containing the mount point label to use.
label
type: yang-identifier
This parameter specifies the mount point label to use.
Returns:
<modules-state> element (contents of the YANG Library for the mount point)
Possible Operation Errors:
access-denied
invalid-value
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="4"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-sm-yanglib xmlns="urn:yumaworks:params:xml:ns:yang:yumaworks-sm-yanglib">
<module>sm-test2</module>
<label>mp1</label>
</get-sm-yanglib>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="4"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<modules-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<module-set-id>583</module-set-id>
<module>
<name>ietf-inet-types</name>
<revision>2013-07-15</revision>
<schema>http://localhost/restconf/yang/ietf-inet-types/2013-07-15</schema>
<namespace>urn:ietf:params:xml:ns:yang:ietf-inet-types</namespace>
<conformance-type>import</conformance-type>
</module>
<module>
<name>ietf-yang-library</name>
<revision>2016-06-21</revision>
<schema>http://localhost/restconf/yang/ietf-yang-library/2016-06-21</schema>
<namespace>urn:ietf:params:xml:ns:yang:ietf-yang-library</namespace>
<conformance-type>implement</conformance-type>
</module>
<module>
<name>ietf-yang-types</name>
<revision>2013-07-15</revision>
<schema>http://localhost/restconf/yang/ietf-yang-types/2013-07-15</schema>
<namespace>urn:ietf:params:xml:ns:yang:ietf-yang-types</namespace>
<conformance-type>import</conformance-type>
</module>
<module>
<name>t301</name>
<revision>2012-02-04</revision>
<schema>http://localhost/restconf/yang/t301/2012-02-04</schema>
<namespace>http://netconfcentral.org/ns/t301</namespace>
<conformance-type>implement</conformance-type>
</module>
<module>
<name>t301get</name>
<revision>2012-02-04</revision>
<schema>http://localhost/restconf/yang/t301get/2012-02-04</schema>
<namespace>http://netconfcentral.org/ns/t301get</namespace>
<conformance-type>implement</conformance-type>
</module>
</modules-state>
</rpc-reply>
<get-support-save>
The <get-support-save> operation is used to retrieve technical support information from the server.
The XML data that is returned can be saved in a file and used by the support-save-app program to extract some data to help reproduce software issues.
This operation is tagged as nacm:default-deny-all, so normal users cannot invoke this operation.
The yumaworks-support-save.yang module must be loaded for this operation to be present.
If NACM is enabled then an explicit NACM rule must be used or a superuser session must be used. Otherwise the server will return an access-denied error.
Only one support-save operation can be in progress at once. A ‘resource-denied’ error is returned if another support-save operation is already in progress.
No duplicate local-names are allowed in the top-level child nodes of the support-save-data anydata container.
<support-save-data> Contents
container support-save-data {
container bundles {
list bundle {
leaf name { type string; }
leaf-list deviation { type string; }
leaf-list module { type string; }
}
}
container capabilities ->
/ietf-netconf-monitoring:netconf-state/capabilities
container config-data {
container *name* (e.g. candidate) {
anydata config;
}
}
container datastores ->
/ietf-netconf-monitoring:netconf-state/datastores
container modules-state -> /ietf-yang-library:modules-state
container modules-text {
list module {
leaf name { type string; }
leaf revision { type string; }
leaf source { type string; }
leaf submodule { type empty; }
leaf text { type string; }
}
}
container program {
leaf name { type string; }
leaf version { type string; }
}
container sessions ->
/ietf-netconf-monitoring:netconf-state/sessions
container sils {
list sil {
leaf name { type string; }
leaf revision { type string; }
leaf bundle { type empty; }
leaf sil-sa { type empty; }
}
}
container system -> /yuma-system:system container
}
+---x get-support-save
+--ro output
+--ro support-save-data? <anydata>
<get-support-save> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
None |
Returns:
<support-save-data> element
Possible Operation Errors:
access-denied
resource-denied
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-support-save xmlns="urn:ietf:params:xml:ns:yang:yumaworks-support-save"/>
</rpc>
Example Reply:
<rpc-reply message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<support-save-data xmlns="urn:ietf:params:xml:ns:yang:yumaworks-support-save">
<program>
<name>netconfd-pro</name>
<version>tiger-andy-supportsave-2017-08-07.14.26</version>
</program>
<system xmlns="http://netconfcentral.org/ns/yuma-system">
<!-- contents removed for example -->
</system>
<!-- … contents removed for example -->
</support-save-data>
</rpc-reply>
<get-yang-sid-data>
The <get-yang-sid-data> operation is used to retrieve the Schema Item Identifier values in use by the server for the Binary Push feature. The client can use this information to support the "LSID" mode of Binary Push.
This operation is only present if the feature is properly enabled. as described in the :re:Using Binary Push` section.
image built with the WITH_YANG_CBOR=1 and WITH_YANG_PUSH=1 flags
server started with the following parameters:
A range of SID values can be requested or all SID values can be requested by omitted both input parameters.
+---x get-yang-sid-data
+---w input
| +---w lower-bound? sid:sid
| +---w upper-bound? sid:sid
+--ro output
+--ro current-set-id? sid-set-id
+--ro data
+--ro sid-item* [sid]
+--ro sid sid:sid
+--ro namespace? enumeration
+--ro module-name? string
+--ro identifier? union
<get-yang-sid-data> Operation Usage
Min parameters: |
0 |
Max parameters: |
2 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
None |
Mandatory Parameters: none
Optional Parameters:
lower-bound
type: sid (uint64)
This parameter specifies the lowest requested SID value that should be returned. The default is '1' if no value is provided.
upper-bound
type: sid (uint64)
This parameter specifies the highest requested SID value that should be returned. The default is no upper bound.
Returns:
<current-set> element identifies server SID mapping set
<data> element contains the requested sid-item mapping information
Possible Operation Errors:
access-denied
resource-denied
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-yang-sid-data xmlns="urn:yumaworks:params:xml:ns:yang:yumaworks-yang-cbor"/>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<current-set-id xmlns="urn:yumaworks:params:xml:ns:yang:yumaworks-yang-cbor">server1.5505</current-set-id>
<data xmlns="urn:yumaworks:params:xml:ns:yang:yumaworks-yang-cbor">
<sid-item>
<sid>256</sid>
<namespace>module</namespace>
<identifier>iana-crypt-hash</identifier>
</sid-item>
<sid-item>
<sid>257</sid>
<namespace>feature</namespace>
<module-name>iana-crypt-hash</module-name>
<identifier>crypt-hash-md5</identifier>
</sid-item>
<sid-item>
<sid>258</sid>
<namespace>feature</namespace>
<module-name>iana-crypt-hash</module-name>
<identifier>crypt-hash-sha-256</identifier>
</sid-item>
<sid-item>
<sid>259</sid>
<namespace>feature</namespace>
<module-name>iana-crypt-hash</module-name>
<identifier>crypt-hash-sha-512</identifier>
</sid-item>
<!-- many more sid-item entries skipped -->
</data>
</rpc-reply>
<kill-session>
The <kill-session> operation is used to force the termination of another NETCONF session. This is sometimes needed if an idle session which is holding one or more locks was abandoned. It may also be needed for security reasons. In any case, this operation should be used with extreme caution.
+---x kill-session
+---w input
+---w session-id session-id-type
<kill-session> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
session-id
type: uint32 (range: 1.. max)
default: none
This parameter specifies the session number of the currently active NETCONF session that should be terminated.
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
access-denied
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="42">
<nc:kill-session>
<nc:session-id>1</nc:session-id>
</nc:kill-session>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="42">
<nc:ok/>
</nc:rpc-reply>
<kill-subscription>
The <kill-subscription> operation is used to delete a notification subscription, using RFC 8639 subscriptions. This is required to used YANG Push. Any session can delete a subscription on any session, using this operation. NACM permissions are required to use this operation. By default is is not permitted.
This operation is not present unless the server is build with the WITH_YANG_PUSH=1 or EVERYTHING=1 make option and the “yang-push” bundle is loaded.
+---x kill-subscription
+---w input
+---w id subscription-id
<kill-subscription> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none (bundle yang-push required) |
Capabilities optional: |
none |
Mandatory Parameters:
id
type: subscription-id
This parameter specifies the subscription ID of the subscription to delete.
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<kill-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>2</id>
</kill-subscription>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
When a subscription is terminated, a notification is sent to the subscription before it is deleted:
<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2020-09-07T00:51:08Z</eventTime>
<subscription-terminated xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>2</id>
<reason xmlns:sn="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">sn:no-such-subscription</reason>
</subscription-terminated>
</notification>
<load>
The <load> operation is used to load new YANG modules at run-time.
The module file must already be present in the module search path of the server.
There must not be any version of the module already loaded.
This operation is tagged as nacm:default-deny-all, so by default, only a superuser account is allowed to use it.
This operation appears in 2 YANG modules:
yuma-system.yang: deprecated and enabled if --with-yuma-system is set to ‘true’
yumaworks-system.yang: current and enabled if --with-yumaworks-system is set to ‘true’
Note
If both yuma-system and yumaworks-system modules are loaded then the proper namespace must be used in any XML messages for these modules.
+---x load
+---w input
| +---w module nt:NcxName
| +---w revision? nt:Date
| +---w deviation* yt:NcModuleSpec
| +---w save-config? boolean
+--ro output
+--ro mod-revision? nt:Date
<load> Operation Usage
Min parameters: |
1 |
Max parameters: |
3 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
module
The name of the YANG module to load
Optional Parameters:
revision
The revision date of the module to load. If missing, then server can select the version to use.
deviation
The name of a deviation module to load before loading this module. Zero or more instances of this parameter can be entered. Duplicates will be ignored.
save-config:
Save a module configuration file this module so it will be loaded after a server reboot. The default is 'false'.
Returns:
<mod-revision>
The revision date of the module that was already loaded, or was just loaded.
Possible Operation Errors:
access-denied
module not found
version not found
different version already loaded
module parsing errors
resource errors
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="52">
<nd:load xmlns:nd="http://netconfcentral.org/ns/netconfd">
<nd:module>test2</nd:module>
</nd:load>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="52">
<nd:mod-revision xmlns:nd="http://netconfcentral.org/ns/netconfd">2008-10-15</nd:mod-revision>
</nc:rpc-reply>
<load-bundle>
The <load-bundle> operation is used to load new YANG modules at run-time, which are compiled together as a SIL bundle.
All modules in the SIL bundle must already be present in the module search path of the server.
There must not be any version of any modules in the bundle already loaded.
This operation is tagged as nacm:default-deny-all, so by default, only a super user account is allowed to use it.
+---x load-bundle
+---w input
+---w bundle nt:NcxName
+---w deviation* yt:NcModuleSpec
+---w save-config? boolean
<load> Operation Usage
Min parameters: |
1 |
Max parameters: |
3 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
bundle
The name of the SIL bundle to load
Optional Parameters:
deviation
The name of a deviation module to load before loading this bundle. Zero or more instances of this parameter can be entered. Duplicates will be ignored.
save-config
Save a module configuration file this bundle so it will be loaded after a server reboot. The default is 'false'.
Returns:
status
Possible Operation Errors:
access-denied
module not found
SIL library not found
module parsing errors
resource errors
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="166" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<load-bundle xmlns="http://yumaworks.com/ns/yumaworks-system">
<bundle>interface-bundle</bundle>
</load-bundle>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="166">
<nc:ok/>
</nc:rpc-reply>
<load-config>
The <load-config> operation is used internally to load the <running> datastore with the NV-stored configuration data.
Note
This is an internal API that is not accessible to any client protocols.
+---x load-config
+---w input
+---w config
<load-config> operation
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
config
The <config> element representing the datastore contents
Optional Parameters: none
Returns:
status
Possible Operation Errors:
YANG validation errors
file not found
resource errors
Example Request:
Internal RPC so not shown
Example Reply:
Internal RPC so not shown
<modify-subscription>
The <modify-subscription> operation is used to modify a notification subscription, using RFC 8639 subscriptions.
This operation is not present unless the server is build with the WITH_YANG_PUSH=1 or EVERYTHING=1 option and the “yang-push” bundle is loaded.
Refer to the <establish-subscription> operation for an introduction to the usage modes for this operation. Refer to the YANG Push section for complete usage information for this feature.
Usage Restrictions:
The type of subscription cannot be changed. An on-change push subscription cannot be changed to a periodic subscription and vice versa.
+---x modify-subscription
+---w input
+---w id subscription-id
+---w (target)
| +--:(stream)
| | +---w (stream-filter)?
| | +--:(by-reference)
| | | +---w stream-filter-name stream-filter-ref
| | +--:(within-subscription)
| | +---w (filter-spec)?
| | +--:(stream-subtree-filter)
| | | +---w stream-subtree-filter? <anydata> {subtree}?
| | +--:(stream-xpath-filter)
| | +---w stream-xpath-filter? yang:xpath1.0 {xpath}?
| +--:(yp:datastore)
| +---w yp:datastore identityref
| +---w (yp:selection-filter)?
| +--:(yp:by-reference)
| | +---w yp:selection-filter-ref selection-filter-ref
| +--:(yp:within-subscription)
| +---w (yp:filter-spec)?
| +--:(yp:datastore-subtree-filter)
| | +---w yp:datastore-subtree-filter? <anydata> {sn:subtree}?
| +--:(yp:datastore-xpath-filter)
| +---w yp:datastore-xpath-filter? yang:xpath1.0 {sn:xpath}?
+---w stop-time? yang:date-and-time
+---w (yp:update-trigger)?
+--:(yp:periodic)
| +---w yp:periodic!
| +---w yp:period centiseconds
| +---w yp:anchor-time? yang:date-and-time
+--:(yp:on-change) {on-change}?
+---w yp:on-change!
+---w yp:dampening-period? centiseconds
<modify-subscription> Operation Usage
Min parameters: |
2 |
Max parameters: |
|
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none (bundle yang-push required) |
Capabilities optional: |
none |
Event Stream Subscription
Mandatory Parameters:
id
type: subscription-id
This parameter specifies the subscription ID of the subscription to modify.
Optional Parameters:
stream-filter: choice of 3 options
stream-filter-name:
type: stream-filter-ref
default: none
This parameter specifies the name of a stream filter to use in the
/filters/stream-filterlist
stream-subtree-filter:
type: anydata
default: none
This parameter specifies the inline subtree filter to use
stream-xpath-filter:
type: xpath1.0
default: none
This parameter specifies the inline XPath filter to use. Prefixes are not required but if they are provided then an “xmlns” attribute defining each prefix to namespace mapping must be present in the XML.
stop-time
type: date-and-time
default: none
This parameter specifies that replay mode is desired and the replay should stop including notifications with timestamps less than the specified value.
Datastore Subscription
Mandatory Parameters:
id
type: subscription-id
This parameter specifies the subscription ID of the subscription to modify.
Optional Parameters:
update-trigger: choice of 2 options
periodic
type: presence container
default: none
This parameter specifies that a periodic subscription is desired. These subscriptions are controlled by the --push-max-periodic parameter. A new subscription will only be established if the limit has not already been reached.
child period
type: centiseconds
default: none
This parameter specifies the period to wait between updates. The --push-min-period parameter is used to enforce restrictions beyond the standard.
child anchor-time
type: date-and-time
default: none
This parameter is not yet supported.
on-change
type: presence container
default: none
This parameter specifies that an on-change subscription is desired. These subscriptions are controlled by the --push-max-operational parameter, if the datastore parameter is ‘operational’. A new subscription will only be established if the limit has not already been reached.
child dampening-period
type: centiseconds
default: none
This parameter specifies the dampening period to wait between on-change updates. The --push-min-dampening parameter is used to enforce restrictions beyond the standard.
This parameter can be left out for a simulated operational on-change subscription. In that case, the --push-simop-period parameter will be used instead. If both parameters apply, then the maximum value of both of them will be used as the dampening period value.
selection-filter: choice of 3 options
selection-filter-ref:
type: selection-filter-ref
default: none
This parameter specifies the name of a selection filter to use in the
/filters/selection-filterlist
datastore-subtree-filter:
type: anydata
default: none
This parameter specifies the inline subtree filter to use
datastore-xpath-filter:
type: xpath1.0
default: none
This parameter specifies the inline XPath filter to use. Prefixes are not required but if they are provided then an “xmlns” attribute defining each prefix to namespace mapping must be present in the XML.
stop-time
type: date-and-time
default: none
This parameter specifies that replay mode is desired and the replay should stop including notifications with timestamps less than the specified value.
Returns:
status
Possible Operation Errors:
access-denied
in-use (target database is locked by another session)
All error-tags and error-app-tags defined in RFC 8639 and RFC 8641 are supported
Example Usage:
The following example shows a request to start a get-bulk operation on the "interface" list:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="6"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<list-target>/interfaces-state/interface</list-target>
</get-bulk>
</rpc>
The server might respond with the first list entry:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="6"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<data>
<interface xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<name>lo</name>
<type
xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:softwareLoopback</type>
<admin-status>up</admin-status>
<oper-status>up</oper-status>
<if-index>1</if-index>
<phys-address>00:00:00:00:00:00</phys-address>
<speed>0</speed>
<statistics>
<in-octets>8001114</in-octets>
<in-unicast-pkts>78785</in-unicast-pkts>
<in-multicast-pkts>0</in-multicast-pkts>
<in-discards>0</in-discards>
<in-errors>0</in-errors>
<out-octets>8001114</out-octets>
<out-unicast-pkts>78785</out-unicast-pkts>
<out-discards>0</out-discards>
<out-errors>0</out-errors>
</statistics>
</interface>
</data>
<last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
<name xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">lo</name>
</last-keys>
</bulk>
</rpc-reply>
<lock>
Note
Datastore locking should be used for all configuration datastores on the server.
Multiple <lock> operations are required if more than one datastore is used (e.g., --target='candidate').
If more than one client is trying to lock datastores at the same time, a 'stalemate' can occur where each client has one datastore lock and waiting for another one.
Use the <lock-all> operation to simplify datastore locking and prevent the problems causes by the <lock> operation.
The <lock> operation is used to insure exclusive write access to an entire configuration database.
The <running> configuration can be locked at any time, if it is currently unlocked.
If the :startup capability is supported, the <startup> configuration can be locked at any time, if it is currently unlocked.
If the :candidate capability is supported, and it is not already locked, then it may usually be locked. However, the <candidate> configuration can only be locked if there are no edits already contained within it. A <discard-changes> operation may be needed to clear any leftover edits, if this operation fails with a 'resource-denied' error instead of a 'lock-denied' error.
If the session holding the lock is terminated for any reason, the lock will be released, as if the <unlock> operation was invoked.
Automatic Lock Release
The server will automatically release a global configuration lock in some cases:
The session holding the lock is closed with the <close-session> operation.
The session holding the lock is killed with the <kill-session> operation.
The session holding the lock is closed because the transport layer connection is terminated.
The session holding the lock is closed because the --idle-timeout parameter was enforced for the session.
The session holding the lock is closed because the --idle-timeout parameter was enforced for the session.
The session holding the lock is not closed, but the --max-lock-hold-time parameter was enforced for the session.
+---x lock
+---w input
+---w target
+---w (config-target)
+--:(candidate)
| +---w candidate? empty {candidate}?
+--:(running)
| +---w running? empty
+--:(startup)
+---w startup? empty {startup}?
<lock> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Capabilities optional: |
Mandatory Parameters:
target
type: container with 1 of N choice of leafs
This parameter specifies the name of the target database to be locked.
container contents: 1 of N:
candidate
type: empty
capabilities needed::candidate
running
type: empty
capabilities needed: none
startup
type: empty
capabilities needed: startup
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
access-denied
lock-denied (lock already held by <session-id> in the <error-info>)
resource-denied (candidate is dirty; <discard-changes> needed)
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="62">
<nc:lock>
<nc:target>
<nc:candidate/>
</nc:target>
</nc:lock>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="62">
<nc:ok/>
</nc:rpc-reply>
<lock-all>
The <lock-all> operation is used to insure exclusive write access to all the configuration datastores at once. It is only present if the --with-yumaworks-lock parameter is set to 'true'.
Lock all global configuration datastores:
This always includes the <running> datastore.
If the :candidate capability is supported then it also includes the <candidate> datastore.
If the :startup capability is supported then it also includes the <startup> datastore.
The server will attempt to obtain 1 to 3 global datastore locks:
If all datastores are ok to lock by this session then the server will lock all-or-none configuration datastores and return 'ok'.
If this operation is used to lock datastores then the <unlock-all> operation must be used to unlock all the datastores at once. The <unlock> operation will be rejected if the <lock>' operation was not used to obtain the datastore lock.
If any datastore is not ok to lock, e.g. already locked by any session, then the server will return 'in-use' and not lock any datastores.
All Automatic Lock Release procedures followed for apply to all locks obtained with this operation.
All datastore restrictions for the <lock> operation apply to this operation as well.
First release: 22.10-8
+---x lock-all
<lock-all> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Capabilities optional: |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
If any datastores locked by another session:
error-tag: no-access
error-message: config locked
If <candidate> datastore is dirty:
error-tag: resource-denied
error-message: candidate cannot be locked, discard-changes needed
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock-all xmlns="urn:ietf:params:xml:ns:yang:yumaworks-lock"/>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<no-op>
The <no-op> operation is used for debugging and performance testing purposes.
This operation does not do anything. It simply returns <ok/>. It will be present in the system if --with-yuma-system=true.
+---x no-op
<no-op> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
access-denied
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="63">
<nd:no-op xmlns:nd="http://netconfcentral.org/ns/netconfd"/>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="63">
<nc:ok/>
</nc:rpc-reply>
<partial-lock>
The <partial-lock> operation is used to lock part of the <running> database. The --target=running setting must be used for this operation to be available. Refer to RFC 5717 or the ietf-netconf-partial-lock.yang module for details on this operation.
+---x partial-lock
+---w input
| +---w select* yang:xpath1.0
+--ro output
+--ro lock-id lock-id-type
+--ro locked-node* instance-identifier
<partial-lock> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
data |
YANG file: |
|
Capabilities needed: |
Mandatory Parameters:
<select>
type: XPath 1.0 string
This parameter contains an XPath expression for a node-set result, identifying the database nodes to lock.
One of more instances of this parameter is required.
The server allows relaxed XPath syntax. If prefixes are used, then a proper namespace declaration must be present in the request. If prefixes are not used, then any available namespace that matches the local name will be used.
Optional Parameters:
none
Returns:
<lock-id>
type: uint32 (range 1 .. MAX_UINT)
This data identifies the lock ID to use when releasing the lock with the <partial-unlock> operation.
There will be one of these elements in the reply.
<locked-node>
type: instance-identifier
This data identifies a locked node as a result of the request.
There will be one or more of these elements in the reply.
Possible Operation Errors:
access denied, in-use, resource-denied
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="260">
<pl:partial-lock xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">
<pl:select>//interface</pl:select>
</pl:partial-lock>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="260"
xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">
<pl:lock-id xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">1</pl:lock-id>
<pl:locked-node
xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='virbr0']</pl:locked-node>
<pl:locked-node
xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='eth0']</pl:locked-node>
<pl:locked-node
xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='lo']</pl:locked-node>
</nc:rpc-reply>
<partial-unlock>
The <partial-unlock> operation is used to unlock part of the <running> database that was previously locked with the <partial-lock> operation. Only the session that called <partial-lock> can release the lock with this operation.
The --target=running setting must be used for this operation to be available. Refer to RFC 5717 or the ietf-netconf-partial-lock.yang module for details on this operation.
+---x partial-unlock
+---w input
+---w lock-id lock-id-type
<partial-unlock> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
Mandatory Parameters:
<lock-id>
type: unit32 (1 .. MAX_UINT)
This parameter contains the lock ID of the partial lock to release.
One of more instances of this parameter is required.
The server allows relaxed XPath syntax. If prefixes are used, then a proper namespace declaration must be present in the request. If prefixes are not used, then any available namespace that matches the local name will be used.
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
access denied, invalid-value
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="263">
<pl:partial-unlock xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">
<pl:lock-id>1</pl:lock-id>
</pl:partial-unlock>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="263">
<nc:ok/>
</nc:rpc-reply>
<protocol-control>
The <protocol-control> operation is used to enable or disable northbound protocols at run-time.
Enable or disable new sessions for the specified protocol
Affects new sessions not any sessions in progress.
Affects only the current state.
The --disabled-protocols CLI parameter value will be used after a reboot.
Warning
Disabling protocol session access can cause the server to become unreachable.
Use this operation with extreme caution.
Superuser or explicit NACM access is required for this operation
Do not use unless multiple northbound protocols are enabled.
This operation is only present if the --with-yumaworks-system=true setting is used.
+---x protocol-control
+---w input
+---w action enumeration
+---w protocol string
<protocol-control> Operation Usage
Min parameters: |
2 |
Max parameters: |
2 |
Return type: |
ok |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
action
type: enumeration
This parameter specifies the protocol action that is requested
enable: Enable sessions for the named protocoldisable: Disable sessions for the named protocolstatus: Get the status for the the named protocolreturn <ok/> if protocol is enabled
return error-tag
operation-failedif protocol is not enabled
protocol
type: string
This parameter specifies the name of the protocol for the action that is requested.
netconf: NETCONF protocol (SSH or TLS)restconf: RESTCONF protocolcli: yp-shell protocolgnmi: gNMI protocolgrpc: gRPC protocol
Optional Parameters:
none
Returns:
<ok>
Possible Operation Errors:
access denied, operation-failed
Example: Enable action that succeeds
Example Request:
?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<protocol-control xmlns="http://yumaworks.com/ns/yumaworks-system">
<action>disable</action>
<protocol>restconf</protocol>
</protocol-control>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
Example: Status action for disabled protocol
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="4"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<protocol-control xmlns="http://yumaworks.com/ns/yumaworks-system">
<action>status</action>
<protocol>restconf</protocol>
</protocol-control>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="4" xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>protocol</error-type>
<error-tag>operation-failed</error-tag>
<error-severity>error</error-severity>
<error-app-tag>general-error</error-app-tag>
<error-message xml:lang="en">operation failed</error-message>
<error-info>
<error-number>274</error-number>
</error-info>
</rpc-error>
</rpc-reply>
<refresh-backup-dir>
The <refresh-backup-dir> operation is used to refresh the
/netconf-state/backup-files subtree. This operation allows the backup
file directory contents to be altered at run-time outside the control of
the server. The 'backup-file' list entries within the 'backup-files'
container will be refreshed.
This operation is only present if the --with-yumaworks-system=true setting is used.
+---x refresh-backup-dir
<refresh-backup-dir> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
ok |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
<ok>
Possible Operation Errors:
access denied, operation-failed
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<refresh-backup-dir xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<replay-config>
The <replay-config> operation is used internally to replay the <running> datastore contents to the internal SIL and SIL-SA callbacks. This is needed when the server instrumentation (e.g., SIL-SA subsystem) has reset and needs to be re-synched with the <running> datastore.
Note
This is an internal API that is not accessible to any client protocols.
+---x replay-config
<replay-config> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters: none
Optional Parameters: none
Returns:
status
Possible Operation Errors:
YANG validation errors
resource errors
Example Request:
Internal RPC so not shown
Example Reply:
Internal RPC so not shown
<restart>
The <restart> operation is used to restart the netconfd-pro server. This operation does not restart the entire operating system. The --with-yuma-system parameter must be set to 'true' for this operation to be present.
By default, only a 'superuser' account is allowed to invoke this operation. If permission is granted, then the current NETCONF session will dropped, during the server restart.
+---x restart
<restart> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
none |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
none; session will be dropped upon success
Possible Operation Errors:
access denied
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="63">
<nd:restart xmlns:nd="http://netconfcentral.org/ns/netconfd"/>
</nc:rpc>
Example Reply: (none – server may send <ok/> before system shuts down.)
<restore>
The <restore> operation is used to load the running database from a named configuration backup file on the server. This operation is used with the <backup> operation.
Only local files are supported.
The --with-yumaworks-system parameter must be set to true for this operation to be present.
The 'agt_backup_dir' path string must be set to a valid directory.
By default, only a superuser account is allowed to invoke this operation.
+---x restore
+---w input
+---w filename ywt:NcxFileName
<restore> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
filename:
The file name with extension for the backup. The directory is determined by the agt_backup_dir profile variable. The file name string is specified by the NcxFileName typedef in yumaworks-types.yang.
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
none
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="6" trace-id="6"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<restore xmlns="http://yumaworks.com/ns/yumaworks-system">
<filename>foo.xml</filename>
</restore>
</rpc>
Example Reply:
<rpc-reply message-id="6" trace-id="6"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<resync-subscription>
The <resync-subscription> operation is used to re-synchronize a push notification subscription, using RFC 8639 subscriptions. Only the session that started the subscription can use this operation on that session. The subscription must be for an on-change datastore type.
This operation is not present unless the server is build with the WITH_YANG_PUSH=1 or EVERYTHING=1 make flag and the “yang-push” bundle is loaded.
For YANG Push, a "resynch" means a full update is sent by the server, and further "patch" messages are updates to that full update.
+---x resync-subscription {on-change}?
+---w input
+---w id sn:subscription-id
<resync-subscription> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none (bundle yang-push required) |
Capabilities optional: |
none |
Mandatory Parameters:
id
type: subscription-id
This parameter specifies the subscription ID of the subscription to resynch.
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<resync-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<id>1</id>
</resync-subscription>
</rpc>
Example Reply:
<rpc-reply message-id="2" xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<set-log-level>
The <set-log-level> operation is used to configure the server logging verbosity level.
This operation is tagged as nacm:default-deny-all, so by default, only a superuser account is allowed to use it.
This operation appears in 2 YANG modules:
yuma-system.yang: deprecated and enabled if --with-yuma-system is set to ‘true’
yumaworks-system.yang: current and enabled if --with-yumaworks-system is set to ‘true’
Note
If both yuma-system and yumaworks-system modules are loaded then the proper namespace must be used in any XML messages for these modules.
+---x set-log-level
+---w input
+---w log-level nt:NcDebugType
+---w log-stream? enumeration
<set-log-level> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
log-level
type: enumeration (off, error, warn, info, debug, debug2, debug3, debug4)
default: none
This parameter specifies the server logging verbosity level.
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
access-denied
Example Request:
<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<set-log-level xmlns="http://netconfcentral.org/ns/yuma-system">
<log-level>debug2</log-level>
</set-log-level>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
<nc:ok/>
</nc:rpc-reply>
<set-my-session>
The <set-my-session> operation is used to configure the session customization data for the current session.
The yuma-mysession.yang module must be enabled in the server configuration file or CLI parameters for this operation to be available.
Example:
module yuma-mysession
The following parameters can be set:
session indent amount for logging
line size for logging
with-defaults default behavior for this session
session indent amount for NETCONF XML protocol messages
+---x set-my-session
+---w input
+---w indent? yt:IndentType
+---w linesize? uint32
+---w with-defaults? wd:with-defaults-mode
+---w message-indent? int8
<set-my-session> Operation Usage
Min parameters: |
0 |
Max parameters: |
4 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
none
Optional Parameters:
indent
type: uint32 (range 0 .. 9)
default: 3 (can be changed with the --indent configuration parameter)
This parameter specifies the desired indent amount for the session.
linesize
type: uint32 (range 40 .. 1024)
default: 72
This parameter specifies the desired line length for the session.
<with-defaults>
type: enumeration (report-all report-all-tagged trim explicit)
default: report-all
This parameter specifies the desired default with-defaults behavior for the session. This value will override the server-wide default value set with the --default-style configuration parameter.
message-indent
type: int8 (range -1 .. 9)
This parameter specifies the desired NETCONF XML message indent amount for the session.
default: -1
Returns:
<ok/>
Possible Operation Errors:
access-denied
invalid-value
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
<myses:set-my-session xmlns:myses="http://netconfcentral.org/ns/mysession">
<myses:indent>4</myses:indent>
<myses:linesize>64</myses:linesize>
<myses:with-defaults>trim</myses:with-defaults>
<myses:message-indent>1</myses:message-indent>
</myses:set-my-session>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
<nc:ok/>
</nc:rpc-reply>
<shutdown>
The <shutdown> operation is used to shut down the netconfd-pro server.
The <shutdown> operation is used to restart the netconfd-pro server. This operation does not restart the entire operating system. The --with-yuma-system parameter must be set to 'true' for this operation to be present.
By default, only a 'superuser' account is allowed to invoke this operation. If permission is granted, then the current NETCONF session will dropped, during the server restart.
+---x shutdown
<shutdown> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
none |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
none; session will be dropped upon success
Possible Operation Errors:
access denied
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
<nd:shutdown xmlns:nd="http://netconfcentral.org/ns/netconfd"/>
</nc:rpc>
Example Reply:
[no reply will be sent; session will be dropped instead.]
<unload>
The <unload> operation is used to remove a YANG module from the system:
The YANG module and all its SIL code (if any) will be removed from the running server. They will not be deleted from disk.
Remove any data nodes in the system from the module.
Remove the module from the server capabilities and NETCONF monitoring data.
Remove the module namespace from the system.
Note: this operation does not remove the --module parameter from the server configuration file if it exists.
The following conditions must be true for the unload to be attempted by the server:
The module is allowed to be unloaded. It is data-model and vendor specific whether a module can be removed at run-time.
There are no dependencies on the module being removed. No modules that import this module are also loaded.
The module was loaded into the server, either via the <load> operation or the --module configuration parameter.
No datastores are currently locked. The server will attempt to lock all datastores on behalf of the client
for the entire unload operation.
The candidate datastore does not contain any edits that have not been committed.
No confirmed-commit operation is in progress.
If all these conditions are met then the server will attempt to unload the specified module. The unload operation can fail for various reasons:
The client does not have write privileges for all data being deleted. This includes any top-level data nodes and any nested augment nodes in other modules.
The deletion of one or more nodes would cause the running datastore to fail any YANG validation tests in RFC 6020, sec. 8.3.3.
Server resource errors occur
The --with-yumaworks-system parameter must be set to 'true' for this operation to be present.
+---x unload
+---w input
+---w module nt:NcxName
+---w delete-config? boolean
<unload> Operation Usage
Min parameters: |
1 |
Max parameters: |
2 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
module
type: string
This parameter specifies the name of the YANG module to be unloaded.
Optional Parameters:
delete-config
type: boolean
Delete the module configuration file for this module so it will not be loaded after a server reboot.
The default is 'false'.
Returns:
<ok/>
Possible Operation Errors:
access denied
validation errors
resource errors
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="66" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unload xmlns="http://yumaworks.com/ns/yumaworks-system">
<module>test</module>
</unload>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="66">
<nc:ok/>
</nc:rpc-reply>
<unload-bundle>
The <unload-bundle> operation is used to remove a SIL bundle (multiple YANG modules at once) from the system:
All the YANG modules in the bundle and all their SIL code (if any) will be removed from the running server. They will not be deleted from disk.
Remove any data nodes in the system from all the modules in the bundle.
Remove all the modules from the server capabilities and NETCONF monitoring data.
Remove all the module namespaces from the system.
Note: this operation does not remove the --bundle parameter from the server configuration file if it exists.
The following conditions must be true for the unload-bundle to be attempted by the server:
The bundle is allowed to be unloaded. It is data-model and vendor specific whether a bundle can be removed at run-time.
There are no dependencies on the modules being removed, from outside the bundle. No modules that import this module can be loaded after the bundle is unloaded.
The bundle was loaded into the server, either via the <load-bundle> operation or the --bundle configuration parameter.
No datastores are currently locked. The server will attempt to lock all datastores on behalf of the client for the entire unload-bundle operation.
The candidate datastore does not contain any edits that have not been committed.
No confirmed-commit operation is in progress.
If all these conditions are met then the server will attempt to unload-bundle the specified modules. The unload-bundle operation can fail for various reasons:
The client does not have write privileges for all data being deleted. This includes any top-level data nodes and any nested augment nodes in other modules.
The deletion of one or more nodes would cause the running datastore to fail any YANG validation tests in RFC 6020, sec. 8.3.3.
Server resource errors occur
The --with-yumaworks-system parameter must be set to 'true' for this operation to be present.
+---x unload-bundle
+---w input
+---w bundle nt:NcxName
+---w delete-config? boolean
<unload-bundle> Operation Usage
Min parameters: |
1 |
Max parameters: |
2 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Mandatory Parameters:
bundle
type: string
This parameter specifies the name of the YANG module to be unloaded.
Optional Parameters:
delete-config
type: boolean
Delete the module configuration file for this bundle so it will not be loaded after a server reboot.
The default is 'false'.
Returns:
<ok/>
Possible Operation Errors:
access denied
validation errors
resource errors
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="69" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unload-bundle xmlns="http://yumaworks.com/ns/yumaworks-system">
<bundle>bundle1</bundle>
</unload-bundle>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="69">
<nc:ok/>
</nc:rpc-reply>
<unlock>
The <unlock> operation is used to release a global lock held by the current session.
The specified configuration database must be locked, or a 'no-access' <error-app-tag> and an <error-message> of 'wrong-config-state' will be returned.
If the <candidate> configuration contains any edits that have not been committed, then these edits will all be lost if the <unlock> operation is invoked. A <discard-changes> operation is performed automatically by the server when the <candidate> database is unlocked.
This operation cannot be used with the <lock-all> operation. The datastore lock must be obtained with the <lock> operation in order for this operation to succeed.
+---x unlock
+---w input
+---w target
+---w (config-target)
+--:(candidate)
| +---w candidate? empty {candidate}?
+--:(running)
| +---w running? empty
+--:(startup)
+---w startup? empty {startup}?
<unlock> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Capabilities optional: |
Mandatory Parameters:
target
type: container with 1 of N choice of leafs
This parameter specifies the name of the target database to be unlocked.
container contents: 1 of N:
candidate
type: empty
capabilities needed::candidate
running
type: empty
capabilities needed: none
startup
type: empty
capabilities needed: startup
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
access denied
no-access (database not locked)
invalid-value (database not supported)
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="65">
<nc:unlock>
<nc:target>
<nc:candidate/>
</nc:target>
</nc:unlock>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="65">
<nc:ok/>
</nc:rpc-reply>
<unlock-all>
The <unlock-all> operation is used to unlock all datastores that are currently locked using the <lock-all> operation. It is only present if the --with-yumaworks-lock parameter is set to 'true'.
This always includes the <running> datastore.
If the :candidate capability is supported then it also includes the <candidate> datastore.
If the :startup capability is supported then it also includes the <startup> datastore.
The server will attempt to release all global locks that were previously locked:
If all datastores are ok to unlock by this session then the server will unlock all the datastores and return 'ok'.
If the event any datastore is not ok to unlock the server will return the appropriate error.
All Automatic Lock Release procedures followed for the <unlock> operation apply to all locks obtained with this operation.
All datastore restrictions for the <unlock> operation apply to this operation as well.
First release: 22.10-8
+---x unlock-all
<unlock-all> Operation Usage
Min parameters: |
0 |
Max parameters: |
0 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
none |
Capabilities optional: |
Mandatory Parameters:
none
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
If no datastores locked with the <lock-all> t locked:
error-tag: no-access
error-message: wrong config state
If any datastores are locked by another session:
error-tag: no-access
error-message: config locked
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="7"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unlock-all xmlns="urn:ietf:params:xml:ns:yang:yumaworks-lock"/>
</rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="7"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<validate>
The <validate> operation is used to perform the <commit> validation tests against a database or some in-line configuration data. Refer to RFC 7950 for YANG validation details and RFC 6241 for details on this operation.
The --with-validate parameter must be set to 'true' for this operation to be present.
Note
This server may report multiple YANG validation issues for this operation and only one report error during an actual edit operation.
An edit operation is automatically terminated on the first error so the write lock can be released as quickly as possible.
+---x validate {validate}?
+---w input
+---w source
+---w (config-source)
+--:(candidate)
| +---w candidate? empty {candidate}?
+--:(running)
| +---w running? empty
+--:(startup)
| +---w startup? empty {startup}?
+--:(url)
| +---w url? inet:uri {url}?
+--:(config)
+---w config? <anyxml>
<validate> Operation Usage
Min parameters: |
1 |
Max parameters: |
1 |
Return type: |
status |
YANG file: |
|
Capabilities needed: |
:validate |
Capabilities optional: |
Mandatory Parameters:
target
type: container with 1 of N choice of leafs
This parameter specifies the name of the target database, or the in-line configuration data, that should be validated.
container contents: 1 of N:
candidate
type: empty
capabilities needed::candidate
running
type: empty
capabilities needed: none
startup
type: empty
capabilities needed: startup
config
type anyxml
capabilities needed: none
Optional Parameters:
none
Returns:
<ok/>
Possible Operation Errors:
access denied
YANG validation errors
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="76">
<nc:validate>
<nc:source>
<nc:candidate/>
</nc:source>
</nc:validate>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="76">
<nc:ok/>
</nc:rpc-reply>