Cisco Nexus 3000 and 9000 Series NX-API REST SDK User Guide and API Reference, Release 10.5(x)

Cisco Nexus 3000 and 9000 Series NX-API REST Documentation

Triggering a checkpoint

DME

Copy
POST http://<IP_Address>/api/mo/sys/action.json
{
  "actionLSubj": {
    "attributes": {
      "dn": "sys/action/lsubj-[sys]"
    },
    "children": [
      {
        "topSystemCreateCheckpointLTask": {
          "attributes": {
            "adminSt": "start",
            "name": "checkpt-20160930",
            "description": "End of quarter before upgrade",
            "filename": "",
            "delete": "no",
            "dn": "sys/action/lsubj-[sys]/topSystemCreateCheckpointLTask",
            "freq": "one-shot"
          }
        }
      }
    ]
  }
}

Configuring Checkpoints and Rollback

The rollback feature allows you to take a snapshot, or user checkpoint, of the Cisco NX-OS configuration and then reapply that configuration to your device at any point without having to reload the device. A rollback allows any authorized administrator to apply this checkpoint configuration without requiring expert knowledge of the features configured in the checkpoint.

You can create a checkpoint copy of the current running configuration at any time. Cisco NX-OS saves this checkpoint as an ASCII file which you can use to roll back the running configuration to the checkpoint configuration at a future time. You can create multiple checkpoints to save different versions of your running configuration.

This section contains payload examples to demonstrate how to use the NX-API REST API to configure checkpoints and rollback on the Cisco Nexus 3000 and 9000 Series switches.

Triggering a checkpoint

This example creates a checkpoint with a name and description.

actionLSubj Properties

The following table contains information about the actionLSubj properties in the DME payload. For more information about the properties and MOs, see the NX-API DME Model Reference linked in the Related Documentation section below.

Property Name	Data Type	Description	Values
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.

topSystemCreateCheckpointLTask Properties

The following table contains information about the topSystemCreateCheckpointLTask properties in the DME payload. For more information about the properties and MOs, see the NX-API DME Model Reference linked in the Related Documentation section below.

Property Name	Data Type	Description	Values
adminSt	action:AdminSt scalar:Enum8	The administrative state of the object or policy.	SELECTION: 0 - unknown 1 - start 2 - stop 3 - suspend DEFAULT: unknown(0)
name	infra:checkpointStr string:Basic	The name of the object.	RANGE: Min: "0" Max: "79"
description	infra:checkpointStr string:Basic	The description of this configuration item.	RANGE: Min: "0" Max: "79"
filename	string:Basic	NO COMMENTS	RANGE: Min: "0" Max: "512"
delete	infra:deletemode scalar:Enum8	NO COMMENTS	SELECTION: 1 - yes 2 - no DEFAULT: no(2)
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.
freq	action:Freq scalar:Time	Frequency at which tasks are executed	SELECTION: 0ull - one-shot DEFAULT: 0

Related Documentation

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

For information about using the payloads, see the Cisco Nexus 9000 Series NX-OS Programmability Guide https://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-programming-reference-guides-list.html

Triggering a checkpoint (with file name)

This example creates a checkpoint with a file name.

No information is present in the immediate JSON response. To verify success or failure and to view reasons for a failure, query the response object described below.

CLI Command

The CLI command below is the equivalent to the payload example displayed in the pane on the right.

checkpoint {[<name>] [description <descr>] | file <file_uri>}

actionLSubj Properties

Property Name	Data Type	Description	Values
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.

topSystemCreateCheckpointLTask Properties

Property Name	Data Type	Description	Values
adminSt	action:AdminSt scalar:Enum8	The administrative state of the object or policy.	SELECTION: 0 - unknown 1 - start 2 - stop 3 - suspend DEFAULT: unknown(0)
name	infra:checkpointStr string:Basic	The name of the object.	RANGE: Min: "0" Max: "79"
description	infra:checkpointStr string:Basic	The description of this configuration item.	RANGE: Min: "0" Max: "79"
filename	string:Basic	NO COMMENTS	RANGE: Min: "0" Max: "512"
delete	infra:deletemode scalar:Enum8	NO COMMENTS	SELECTION: 1 - yes 2 - no DEFAULT: no(2)
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.
freq	action:Freq scalar:Time	Frequency at which tasks are executed	SELECTION: 0ull - one-shot DEFAULT: 0

Related Documentation

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Deleting a checkpoint

Deletes the checkpoint named "checkpt-20160930"

By including "delete": "yes" in the payload, this example deletes the checkpoint.

CLI Command

The CLI command below is the equivalent to the payload example displayed in the pane on the right.

no checkpoint {[<name>] [description <descr>] | file <file_uri>}

actionLSubj Properties

Property Name	Data Type	Description	Values
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.

topSystemCreateCheckpointLTask Properties

Property Name	Data Type	Description	Values
adminSt	action:AdminSt scalar:Enum8	The administrative state of the object or policy.	SELECTION: 0 - unknown 1 - start 2 - stop 3 - suspend DEFAULT: unknown(0)
name	infra:checkpointStr string:Basic	The name of the object.	RANGE: Min: "0" Max: "79"
description	infra:checkpointStr string:Basic	The description of this configuration item.	RANGE: Min: "0" Max: "79"
filename	string:Basic	NO COMMENTS	RANGE: Min: "0" Max: "512"
delete	infra:deletemode scalar:Enum8	NO COMMENTS	SELECTION: 1 - yes 2 - no DEFAULT: no(2)
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.
freq	action:Freq scalar:Time	Frequency at which tasks are executed	SELECTION: 0ull - one-shot DEFAULT: 0

Related Documentation

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Clearing groups of checkpoints

Deletes the checkpoint named "checkpt-20160930"

This example clears all checkpoints in the system.

No information is present in the immediate JSON response. To verify success or failure and to view reasons for a failure, query the response object described below.

CLI Command

The CLI command below is the equivalent to the payload example displayed in the pane on the right.

clear checkpoint database [user|system]

actionLSubj Properties

Property Name	Data Type	Description	Values
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.

topSystemClearCheckpointDBLTask Properties

The following table contains information about the topSystemClearCheckpointDBLTask properties in the DME payload. For more information about the properties and MOs, see the NX-API DME Model Reference linked in the Related Documentation section below.

Property Name	Data Type	Description	Values
adminSt	action:AdminSt scalar:Enum8	The administrative state of the object or policy.	SELECTION: 0 - unknown 1 - start 2 - stop 3 - suspend DEFAULT: unknown(0)
mode	infra:clearmode scalar:Enum8	The BGP Domain mode.	SELECTION: 1 - all 2 - user 3 - system DEFAULT: all(1)
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.
freq	action:Freq scalar:Time	Frequency at which tasks are executed	SELECTION: 0ull - one-shot DEFAULT: 0

Related Documentation

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Clearing groups of checkpoints

Deletes the checkpoint named "checkpt-20160930"

This example clears all checkpoints in the system.

No information is present in the immediate JSON response. To verify success or failure and to view reasons for a failure, query the response object described below.

CLI Command

The CLI command below is the equivalent to the payload example displayed in the pane on the right.

clear checkpoint database [user|system]

actionLSubj Properties

Property Name	Data Type	Description	Values
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.

topSystemClearCheckpointDBLTask Properties

Property Name	Data Type	Description	Values
adminSt	action:AdminSt scalar:Enum8	The administrative state of the object or policy.	SELECTION: 0 - unknown 1 - start 2 - stop 3 - suspend DEFAULT: unknown(0)
mode	infra:clearmode scalar:Enum8	The BGP Domain mode.	SELECTION: 1 - all 2 - user 3 - system DEFAULT: all(1)
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.
freq	action:Freq scalar:Time	Frequency at which tasks are executed	SELECTION: 0ull - one-shot DEFAULT: 0

Related Documentation

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Triggering a rollback

This example rolls back to a checkpoint with a name.

actionLSubj Properties

Property Name	Data Type	Description	Values
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.

topSystemRollbackLTask Properties

The following table contains information about the topSystemRollbackLTask properties in the DME payload. For more information about the properties and MOs, see the NX-API DME Model Reference linked in the Related Documentation section below.

Property Name	Data Type	Description	Values
adminSt	action:AdminSt scalar:Enum8	The administrative state of the object or policy.	SELECTION: 0 - unknown 1 - start 2 - stop 3 - suspend DEFAULT: unknown(0)
name	string:Basic	The name of the object.	RANGE: Min: "0" Max: "512"
uri	string:Basic	The generated path for the data export destination.	RANGE: Min: "0" Max: "512"
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.
freq	action:Freq scalar:Time	Frequency at which tasks are executed	SELECTION: 0ull - one-shot DEFAULT: 0

Related Documentation

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Triggering a rollback (bootflash)

This example rolls back to a checkpoint file in bootflash.

No information is present in the immediate JSON response. To verify success or failure and to view reasons for a failure, query the response object described below.

CLI Command

The CLI command below is the equivalent to the payload example displayed in the pane on the right.

rollback running-config {checkpoint <checkpoint_name> | file <file_uri>} [best-effort | stop-at-first-failure | atomic] [verbose]

actionLSubj Properties

Property Name	Data Type	Description	Values
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.

topSystemRollbackLTask Properties

Property Name	Data Type	Description	Values
adminSt	action:AdminSt scalar:Enum8	The administrative state of the object or policy.	SELECTION: 0 - unknown 1 - start 2 - stop 3 - suspend DEFAULT: unknown(0)
name	string:Basic	The name of the object.	RANGE: Min: "0" Max: "512"
uri	string:Basic	The generated path for the data export destination.	RANGE: Min: "0" Max: "512"
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.
freq	action:Freq scalar:Time	Frequency at which tasks are executed	SELECTION: 0ull - one-shot DEFAULT: 0

Related Documentation

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Triggering a rollback (bootflash)

This example rolls back to a checkpoint file in bootflash.

No information is present in the immediate JSON response. To verify success or failure and to view reasons for a failure, query the response object described below.

CLI Command

The CLI command below is the equivalent to the payload example displayed in the pane on the right.

rollback running-config {checkpoint <checkpoint_name> | file <file_uri>} [best-effort | stop-at-first-failure | atomic] [verbose]

actionLSubj Properties

Property Name	Data Type	Description	Values
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.

topSystemRollbackLTask Properties

Property Name	Data Type	Description	Values
adminSt	action:AdminSt scalar:Enum8	The administrative state of the object or policy.	SELECTION: 0 - unknown 1 - start 2 - stop 3 - suspend DEFAULT: unknown(0)
name	string:Basic	The name of the object.	RANGE: Min: "0" Max: "512"
uri	string:Basic	The generated path for the data export destination.	RANGE: Min: "0" Max: "512"
dn	reference:BinRef	A tag or metadata is a non-hierarchical keyword or term assigned to the fabric module.
freq	action:Freq scalar:Time	Frequency at which tasks are executed	SELECTION: 0ull - one-shot DEFAULT: 0

Related Documentation

For other CLI options, see the Cisco Nexus 9000 Series NX-OS Command Reference: http://www.cisco.com/c/en/us/support/switches/nexus-9000-series-switches/products-command-reference-list.html

See the NX-API DME Model Reference for detailed information about classes and attributes described in the payload: https://developer.cisco.com/site/nx-os/docs/nexus-model-reference/

Limitations on Configuring Checkpoints and Rollbacks with NX-API

When sending a checkpoint payload, provide the complete attribute list. Any attribute that is not required should be sent empty.
When posting a task for creating a checkpoint to a name, the “file” attribute must be empty in the payload.
When posting a task for creating a checkpoint to a file, only the “file” attribute should contain text, except for the “delete” attribute, which must contain “no”. The remaining attributes must be empty.
When deleting a checkpoint, the payload must contain only the “name” attribute with the checkpoint name to be deleted, except for the “delete” attribute, which must contain “yes”. The remaining attributes must be empty.
A payload must be provided as described above for all tasks.
A maximum of 10 user-triggered checkpoints can be created on the device. Any user command to create an additional checkpoint is ignored. To add a new checkpoint when the limit has been reached, you must first delete one of the existing checkpoints.
You can modify the "description" attribute with a new checkpoint request whose payload contains the same “name” attribute. Because you cannot overwrite a previously saved checkpoint, only the description will be changed.
You must allow 5 to 10 seconds between consecutive REST requests.
You cannot start a checkpoint filename with the word system.