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,

<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:

yumaworks-system.yang

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:

ietf-netconf.yang

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:

ietf-netconf.yang

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:

yumaworks-event-stream.yang

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:

ietf-netconf.yang

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:

ietf-netconf.yang

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:

ietf-netconf.yang

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

      • 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

      • 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 (uint32, ‘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:

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:

notifications.yang

Capabilities needed:

:notification

Capabilities optional:

:interleave

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:

yumaworks-system.yang

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:

ietf-netconf.yang

Capabilities needed:

:startup

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:

ietf-subscribed-notifications.yang

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:

  • access-denied

  • All error-tags and error-app-tags defined in RFC 8639 and RFC 8641 are supported

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:

ietf-netconf.yang

Capabilities needed:

:candidate

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:

ietf-netconf.yang

Capabilities needed:

:candidate or :writable-running

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:

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-filter list

    • 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-filter list

    • 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:

ietf-netconf.yang

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 (uint32, ‘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.

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).

+---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:

yumaworks-getbulk.yang

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: candidate

    • enum : running

      • capabilities needed: none

    • enum: 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: config

        • Include only config=true descendant data nodes

      • enum: nonconfig

        • include only config=false descendant data nodes

      • enum: all

        • include all descendant data nodes

  • depth

    • type: uint32

    • 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

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/module</list-target>
    <count>2</count>
  </get-bulk>
</rpc>

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>
      <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>

The client can then save the <last-keys> container to continue the retrieval with entry #3 and #4

<?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/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>

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>
      <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-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:

ietf-netconf.yang

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

      • 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 (uint32, ‘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:

ietf-netconf-nmda.yang

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

      • 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:

yumaworks-system.yang

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 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-module-tags>

The <get-module-tags> operation is used to retrieve the installed module-tag configuration.

The module-tag and module names associated with each tag, are returned in the output.

+---x get-module-tags
   +--ro output
      +--ro module-tag* [tag]
         +--ro tag       string
         +--ro module*   string

YANG Definition

rpc get-module-tags {
   description
     "Get the list of configured module-tags.
      The --module-tagmap parameter is used to configure
      a module-tag.";
   output {
     list module-tag {
       key tag;
       leaf tag {
         type string;
         description "The module-tag value";
       }
       leaf-list module {
         type string;
         description "A module-name mapped to this module-tag";
       }
     }
   }
 }

<get-module-tags> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

data

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • <module-tag>

    • type: list

    • Refer to the YANG definition for details

Possible Operation Errors:

  • access-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-module-tags xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</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">
  <module-tag xmlns="http://yumaworks.com/ns/yumaworks-system">
    <tag>netconf</tag>
    <module>ietf-netconf-monitoring</module>
  </module-tag>
  <module-tag xmlns="http://yumaworks.com/ns/yumaworks-system">
    <tag>restconf</tag>
    <module>ietf-restconf-monitoring</module>
  </module-tag>
</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:

yuma-mysession.yang

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:

ietf-netconf-monitoring.yang

Capabilities needed:

:schema-retrieval

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

    • type: enumeration (XSD YANG YIN RNG)

    • This parameter specifies the format of the module to be retrieved. Only the YANG format is supported.

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> datadtore 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:

yumaworks-system.yang

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:

yumaworks-sm-yanglib.yang

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:

yumaworks-support-save.yang

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.

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:

yumaworks-yang-cbor.yang

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:

ietf-netconf.yang

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:

ietf-subscribed-notifications.yang

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:

  • access-denied

  • All error-tags and error-app-tags defined in RFC 8639 and RFC 8641 are supported

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:

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:

yumaworks-system.yang

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:

yuma-netconf.yang

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-filter list

    • 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-filter list

    • 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>

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.

+---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:

ietf-netconf.yang

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

      • 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>

<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:

yuma-system.yang

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:

ietf-netconf-partial-lock.yang

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:

ietf-netconf-partial-lock.yang

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>

<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:

yumaworks-system.yang

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:

yumaworks-internal.yang

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:

yuma-system.yang

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:

yumaworks-system.yang

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:

  • access-denied

  • All error-tags and error-app-tags defined in RFC 8639 and RFC 8641 are supported

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:

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:

yuma-mysession.yang

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:

yuma-system.yang

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:

yumaworks-system.yang

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:

yumaworks-system.yang

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.

+---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:

ietf-netconf.yang

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

      • 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>

<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:

ietf-netconf.yang

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

      • 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>