Welcome! This post is probably going to be the last one in the RESTCONF series. This time, we are going to explore some operations that can be executed on IOS-XE powered devices. This includes tasks such as saving the device configuration or working with the configuration archive. These commands are basically the ones that can be executed in the “Privileged Exec” operation mode, with the exception of the “show” command.
Tools needed
To work with RESTCONF, my tools are:
- Postman, to make HTTP requests to the boxes without having to write any script.
- Python3.6 with the “requests” library.
- Pyang, to explore YANG models
- A code editor, like Visual Studio Code for example.
- A lab with at least one device running IOS-XE. There are CSRv available on DevNet that can be used for this purpose.
Foreword: About IOS-XE configuration archive
IOS-XE has a configuration storage mode where multiple config files can be stored and thus simplify rollback operations. IOS-XE refers to “rollback” as completely replacing the running-config with another previously saved configuration file.
In order to use these capabilities, we need to create a configuration archive first in the global configuration mode of the device. For example:
archive
path flash:config-archive
maximum 10
time-period 1440These are the commands that were used:
- archive: Enters the archive configuration mode.
- path: Indicates where to store the configuration archive files.
- maximum: Max amount of files stored in the configuration archive.
- time-period: Time period (in minutes) to automatically save the running-config in the configuration archive.
After creating a configuration archive, we are now able to operate with it using RESTCONF.
URI and supported operations
In the previous posts the URI always follow this format:
https://<IP:Port>/<root>/data/<module:container>/<leaf>?<options>We had the possibility to make requests with different methods (GET, PUT, POST, DELETE, …). With operations there are two big changes. First, we can only use POST method, as described in the following table:
Second change is the URI. It is now different:
https://<IP:Port>/<root>/operations/<module:rpc>Where <root> is “restconf” (as saw in previous posts) and RPC indicates the operation to execute. To know what operations are available (varies with the different IOS versions) the following request can be made:
GET https://<IP:Port>/restconf/operations/Note: The operations showed on the previous example are the ones available on IOS-XE 17.3. New operations are being added with every software release.
During this post I will briefly describe all these operations (most of them are obvious to anyone that is knowledgeable of IOS CLI). Then we will look into some practical examples that use some of these operations. Some other requests may be required in order to get some information before actually executing the operation. Information about these requests can be found in previous posts about RESTCONF.
- Cisco-IOS-XE-cts-rpc: Cisco TrustSec exec commands.
- Cisco-IOS-XE-install-rpc: Operations in this module allows the user to make software upgrades.
- Cisco-IOS-XE-rpc:default: Set the default configuration for an interface.
- Cisco-IOS-XE-rpc:clear: Clear some counter (“clear” command on IOS-XE CLI).
- Cisco-IOS-XE-rpc:crypto: Crypto operations (“crypto” command on IOS-XE privileged exec mode).
- Cisco-IOS-XE-rpc:release: DHCP release for the IP address of an interface (“release” command on IOS-XE CLI).
- Cisco-IOS-XE-rpc:reload: Reboots the system.
- Cisco-IOS-XE-rpc:factory-reset: Factory reset the device (or a stack member).
- Cisco-IOS-XE-rpc:license: Operations with Smart Licensing (“license” command on IOS-XE CLI).
- Cisco-IOS-XE-rpc:service: Services integrated into IOS-XE (like WAAS or SD-AVC).
- Cisco-IOS-XE-rpc:virtual-service: Operations with Virtual Services Container, if supported by the platform.
- Cisco-IOS-XE-rpc:copy: Copy a file.
- Cisco-IOS-XE-rpc:delete: Delete a file.
- Cisco-IOS-XE-rpc:app-hosting: App hosting management (IOx).
- Cisco-IOS-XE-rpc:guestshell: IOS-XE guestshell configurations.
- Cisco-IOS-XE-rpc:start y Cisco-IOS-XE-rpc:stop: Start/stop maintenance mode (Graceful Insertion and Removal).
- Cisco-IOS-XE-rpc:hw-module: Tasks related with switch modules (like toggling blue beacon on/off). “hw-module” command on IOS-XE CLI.
- Cisco-IOS-XE-rpc:debug: System debugs (“debug” command on IOS-XE CLI, although not every option seem to be implemented yet).
- Cisco-IOS-XE-rpc:monitor: Packet capture related operations.
- Cisco-IOS-XE-rpc:pnpa: PnP service Troubleshooting.
- Cisco-IOS-XE-rpc:test: “test” command on IOS-XE CLI.
- Cisco-IOS-XE-switch-rpc: Switch stack related operations.
- cisco-ia: Configuration related operations (save and rollback, for example). This module needs a configuration archive created for most operations.
- cisco-smart-license: Similar to Cisco-IOS-XE-rpc:license. Module with Smart License RPCs, but here operations are different.
- ietf-event-notifications: Standard module for NETCONF Event Notifications. Has some operations on it.
- ietf-routing: Standard module to obtain device’s FIB.
I haven’t tried every module and operation that appears above, so I don’t know the limitations that they may have. I encourage you to give them a try to those you need and share your experience 😀.
How to build the body of the POST request?
Once we have defined what operation to execute, we need to build the request. When we wanted to configure devices using RESTCONF, we were able to use some GET requests to find out how to build the body of the POST request that was going to configure the device. For operations, GET method are not available, and it will return code 405 (Method Not Allowed) as a result.
We are then force to do things right. We need to interpret the corresponding RPC and translate the data into JSON format. But I’m confident that if you have been following this blog’s series of posts the task is not going to be that hard.
An RPC may need inputs in order to run. Let’s use the “reload” RPC as an example, and try to bbuild the operation using RESTCONF. First, the YANG model that describes this RPC (Cisco-IOS-XE-rpc) show the following:
There are two inputs: “force” and “reason”. RFC 8040 indicates how to map an input into JSON inside the request’s body. Inputs have to be present inside a key with name “<module>:input” (<module> has to be replaced with the module’s name). In this example, the URI and the body would be:
POST https://<IP:Port>/netconf/operations/Cisco-IOS-XE-rpc:reloadNote: Do not forget to use headers correctly in the POST request. “Content-Type” needs to have the value “application/yang-data+json” in order for the device to understand the body correctly.
That’s all! If the operation was successfully we will get status code 200 in the response. Now let’s take a look at some other examples…
Example: Working with configuration files
We are going to use cisco-ia module for all this operations.
save-config
Saving the configuration is the simplest operation. This time we can use the “save-config” RPC. This operations requires no inputs so the body of the request will be blank. This is the equivalent of doing a “copy running-config startup-config” in the device CLI.
POST https://<IP:Port>/netconf/operations/cisco-ia:save-configcheckpoint
A more interesting example is to use the configuration archive that was created in the first part of this post.
To save the running configuration into the archive instead of the startup-config file, we can use the “checkpoint” RPC. It doesn’t need any input, but it does require to have the configuration archive created as a prerequisite (via CLI or via NETCONF/RESTCONF using a configuration module).
POST https://<IP:Port>/netconf/operations/cisco-ia:checkpointNote: If the configuration archive is not enabled on the device, the operation runs and returns status code 200. It is important to parse the response body. The “result” key has the actual result of the operation. If it was successful, it shows the following:
rollback
If we are looking to restore the configuration from a previous file in the archive, we have to use the “rollback” RPC. This one has several inputs:
Notice that there is a mandatory input, “target-url”. This is the name of the configuration file that we want to apply. To obtain this name, we can build a GET request to the Cisco-IOS-XE-checkpoint-archive-oper model. Here is an example:
GET https://<IP:Port>/restconf/data/Cisco-IOS-XE-checkpoint-archive-oper:checkpoint-archivesOnce we obtained the file name, we can build the rollback operation. A basic one has the following format:
POST https://<IP:Port>/netconf/operations/cisco-ia:rollbackExample: Software upgrade
We can run a software upgrade on a device using RESTCONF operations. The Cisco-IOS-XE-install-rpc model is used to do this. The prerequisite is that the devices has to be working on IOS-XE “Install Mode”.
The process can be done with three steps, or with a single step (same as if we were using the CLI). However, the three step process is more difficult because we have to identify when the “install add” process finished. Because of the stateless nature of REST, achieving this is not trivial (at least with the operations available today, I couldn’t find an easy way).
Therefore, while sacrificing the rollback capability, I’m going to proceed with the single step upgrade only.
Single-step upgrade
“install” RPC is used for this. For example,
POST https://<IP:Port>/restconf/operations/Cisco-IOS-XE-install-rpc:installHere is important to include, beyond the path where the software image is located, the “one-shot” key with “true” as the value. This is what forces IOS-XE to do the upgrade process in a single step. If the operation was successful, we just need to sit and wait until the device comes back up..
We have reached the end of this post. Keep exploring the available operations to automate your work with the devices. Glad to hear any suggestions or experiences from your side on the comments or via any social network.
Hello,
I’m trying to complete a one-shot install (or any install for that matter), and I get this response when I try to make the request:
{
“errors”: {
“error”: [
{
“error-message”: “application error”,
“error-path”: “/Cisco-IOS-XE-install-rpc:install”,
“error-tag”: “malformed-message”,
“error-type”: “application”
}
]
}
}
Any idea why that may be happening?
Hi Robert, I’ll test it again on my lab just to make sure the example is still working. Which IOS-XE version do you have on your device?
Can you share the payload you’ve used for the upgrade?
Hi André, the payload used is the one that is shown in the Gist snippet. Is it not working for you? I don’t have Cisco gear anymore around, but let me know if I need to fix it.