RESTCONF: Operaciones

Tabla de Contenidos

Bienvenidos a lo que probablemente sea el último post dentro de la serie de RESTCONF. En este caso, vamos a explorar algunas operaciones que pueden realizarse sobre equipos con IOS-XE. Esto incluye tareas como guardar la configuración o trabajar con el archivo de configuraciones. Son básicamente todos los comandos distintos a “show” que se pueden realizar dentro del modo “Privileged Exec” de IOS-XE.

Herramientas Utilizadas

Para trabajar con RESTCONF, mis herramientas de trabajo son:

Postman, para realizar peticiones a los equipos sin tener que escribir scripts.
Python3.6 con la librería “requests”.
Pyang, para explorar los modelos de YANG
Un editor de código, Visual Studio Code por ejemplo.
Un laboratorio con al menos un equipo con IOS-XE. Se puede utilizar los CSRv disponibles en DevNet con este fin.

Prólogo: Sobre el archivo de configuración en IOS-XE

IOS-XE tiene un modo de guardado de configuraciones donde se pueden almacenar múltiples archivos de configuración y de esta forma simplificar operaciones de rollback. En el caso de IOS-XE, rollback hace referencia a reemplazar completamente la running-config con otro archivo de configuración guardado previamente.
Para poder usar estas características hay que crear primero un configuration archive, en el modo de configuración global. Por ejemplo:

archive
path flash:config-archive
maximum 10
time-period 1440

Aquí aparecen los siguientes comandos:

archive: Entrar a la configuración del archive.
path: Ruta para almacenar el configuration archive.
maximum: Cantidad máxima de archivos de configuración almacenados.
time-period: Período (minutos) en el cual se guardan la running-config de forma automática en el archive.

Con un archive creado luego podremos realizar operaciones sobre el equipo mediante RESTCONF.

URI y operaciones soportadas

En las guías anteriores la URI siempre seguía un formato como el siguiente:

https://<IP:Puerto>/<root>/data/<modulo:container>/<leaf>?<opciones>

Aquí teníamos posibilidad de realizar peticiones con varios métodos (GET, PUT, POST, DELETE, …). En el caso de las operaciones hay dos cambios importantes. En primer lugar sólo se utiliza el método POST, como se especifica en la siguiente figura:

Use POST para operaciones — Para Operaciones se utiliza el método POST

El segundo cambio es la URI. Ahora es diferente:

https://<IP:Puerto>/<root>/operations/<modulo:rpc>

Como se vió en posts anteriores, <root> en IOS-XE es “restconf”, y RPC indica la operación a realizar. Para conocer las operaciones disponibles en el equipo (varían según la versión de IOS) hacemos la siguiente consulta:

GET https://<IP:Puerto>/restconf/operations/

Nota: Estas son las operaciones disponibles en IOS-XE 17.3. Con las nuevas releases de software se van agregando nuevas operaciones.

Durante el resto del post vamos a describir brevemente todas estas operaciones (muchas son evidentes para cualquiera que maneje el sistema operativo) y luego ver algunos ejemplos prácticos del uso de las mismas. Para traer información y luego poder entender la operación a utilizar puede ser necesario aplicar algunas consultas adicionales. Usamos para esto la información de las entradas anteriores del blog sobre RESTCONF.

Cisco-IOS-XE-cts-rpc: Estos son comandos de ejecución para Cisco Trustsec.
Cisco-IOS-XE-install-rpc: Las operaciones de este módulo funcionan en conjunto para el upgrade de imágenes de IOS.
Cisco-IOS-XE-rpc:default: Setear a su configuración por defecto una interfaz.
Cisco-IOS-XE-rpc:clear: Limpiar algún contador (equivalente al comando “clear” en IOS-XE).
Cisco-IOS-XE-rpc:crypto: Como indica el nombre, operaciones sobre encriptación (equivalente al comando “crypto” en IOS-XE).
Cisco-IOS-XE-rpc:release: DHCP release para la dirección IP de alguna interfaz (equivalente al comando “release” en IOS-XE).
Cisco-IOS-XE-rpc:reload: Reinicia el equipo.
Cisco-IOS-XE-rpc:factory-reset: Volver a configuración de fábrica el equipo (o un miembro del stack).
Cisco-IOS-XE-rpc:license: Operaciones sobre el Smart Licensing (equivalente al comando “license” en IOS-XE).
Cisco-IOS-XE-rpc:service: Servicios integrados en IOS-XE – WAAS o SD-AVC.
Cisco-IOS-XE-rpc:virtual-service: Operaciones sobre Virtual Services Container, si la plataforma lo soporta.
Cisco-IOS-XE-rpc:copy: Copiar un archivo.
Cisco-IOS-XE-rpc:delete: Eliminar un archivo.
Cisco-IOS-XE-rpc:app-hosting: Management de las aplicaciones corriendo sobre IOS-XE (IOx).
Cisco-IOS-XE-rpc:guestshell: Configuración de Guestshell en IOS-XE.
Cisco-IOS-XE-rpc:start y Cisco-IOS-XE-rpc:stop: Activar/desactivar modo de mantenimiento del equipo (Graceful Insertion and Removal).
Cisco-IOS-XE-rpc:hw-module: Tareas sobre módulos del switch (por ejemplo, encender/apagar blue beacon). Es equivalente al comando “hw-module” en IOS-XE.
Cisco-IOS-XE-rpc:debug: Activar/desactivar debugs en el sistema (equivalente al comando “debug” en IOS-XE, pero no parecen estar implementadas todas las opciones).
Cisco-IOS-XE-rpc:monitor: Operaciones de captura de paquetes.
Cisco-IOS-XE-rpc:pnpa: Troubleshooting de servicio PnP.
Cisco-IOS-XE-rpc:test: Equivalente al comando “test” en IOS-XE.
Cisco-IOS-XE-switch-rpc: Operaciones sobre el stack de switches.
cisco-ia: Operaciones sobre las configuraciones del equipo (guardado y rollback, por ejemplo). Para esto se necesita tener creado el archivo de configuración.
cisco-smart-license: Similar a Cisco-IOS-XE-rpc:license. Para trabajo sobre Smart Licensing pero con operaciones separadas.
ietf-event-notifications: Módulo estándar para NETCONF Event Notifications.
ietf-routing: Módulo estándar para obtener la FIB del equipo.

Quiero aclarar antes de continuar que no he probado todos los módulos y no sé en detalle si tiene alguna limitación. Los invito a probar el que necesiten y comentar los resultados 😀.

¿Cómo armar el cuerpo de la operación POST?

Una vez definida la operación que se desea realizar, hay que terminar de construir la solicitud. Al realizar configuraciones, sucedía que el método GET estaba disponible para que se pueda ver el formato del cuerpo de alguna solicitud concreta. Para una operación si queremos realizar esto mismo nos encontraremos con un código 405 (Method Not Allowed).
Por lo tanto, no hay otra opción que interpretar los RPC a utilizar. Sin embargo, confío en que si llegaron a esta entrada del blog siguiendo toda la serie, esta tarea no va a resultar tan difícil.

Un RPC puede necesitar que se especifiquen “inputs” para poder ejecutarse. Tomemos por ejemplo el RPC “reload”, e intentemos construir la operación en RESTCONF. En primer lugar, el modelo YANG que describe esta RPC (Cisco-IOS-XE-rpc) muestra lo siguiente:

Hay dos inputs: “force” y “reason”. El RFC 8040 indica cómo se debe mapear esto a JSON dentro del cuerpo de la operación. En resumen, los inputs se indican dentro de una key con el nombre “<module>:input” (donde se reemplaza <module> por el nombre del módulo). En el caso del ejemplo, la operación (URI y cuerpo del mensaje) quedaría como se muestra a continuación:

POST https://<IP:Puerto>/netconf/operations/Cisco-IOS-XE-rpc:reload

Nota: No olvidar utilizar correctamente los headers en la operación POST. “Content-Type” debe tener el valor “application/yang-data+json” para interpretar el cuerpo del mensaje en formato JSON.

Eso es todo! Si la operación se realizó correctamente obtendremos como respuesta el código 200. Ahora a ver algunos ejemplos más…

Ejemplo: Cambios en los archivos de configuración

Para todas estas operaciones vamos a usar el módulo cisco-ia.

save-config

La operación más sencilla es guardar la configuración. En este caso, podemos usar el RPC “save-config”. Esta operación no tiene inputs por lo que debemos dejar el cuerpo del mensaje en blanco. Es un simple equivalente al comando “copy running-config startup-config”.

POST https://<IP:Puerto>/netconf/operations/cisco-ia:save-config

checkpoint

Veamos un caso más interesante mediante el uso del archive que se creó en el prólogo.
Para guardar la configuración actual del equipo en el archive en lugar de la running config, existe la RPC “checkpoint”. Tampoco requiere ningún input, el pre-requisito es haber configurado el archive (vía CLI o via NETCONF/RESTCONF usando algún módulo de configuración).

POST https://<IP:Puerto>/netconf/operations/cisco-ia:checkpoint

Nota: Si no hay archive configurado en el equipo, la operación sigue devolviendo el código 200. Es importante en este caso analizar el cuerpo de la respuesta. La key “result” tiene el verdadero resultado de la operación.
El resultado correcto devuelve lo siguiente:

rollback

Si lo que se desea es restaurar un punto anterior dentro del archive, hay que usar el RPC “rollback”. Aquí si hay varios inputs sobre los cuales se puede trabajar.

Prestar especial atención en que hay un input mandatorio, “target-url”, que es el nombre del archivo que contiene la configuración que queremos aplicar en el equipo. Para obtener el nombre de estos archivos, podemos utilizar una consulta al modelo Cisco-IOS-XE-checkpoint-archive-oper. La llamada y una respuesta como ejemplo se muestran a continuación:

GET https://<IP:Puerto>/restconf/data/Cisco-IOS-XE-checkpoint-archive-oper:checkpoint-archives

Una vez obtenido el nombre del archivo que se quiere utilizar para reemplazar la configuración actual del equipo, se puede hacer la operación de rollback. En su mínima expresión, tiene un formato como el siguiente (operación y cuerpo del mensaje):

POST https://<IP:Puerto>/netconf/operations/cisco-ia:rollback

Ejemplo: Software upgrade

Podemos dar instrucciones usando RESTCONF para realizar un upgrade de software del equipo. Se usa para esto el módulo Cisco-IOS-XE-install-rpc. Para esto es necesario que el equipo se encuentre en “Install Mode”.
El proceso se puede realizar en tres pasos o en un único paso (tal como ocurre vía CLI). Sin embargo, en el proceso de tres pasos se vuelve complejo identificar cuándo se termina de agregar la imagen al equipo, debido a la naturaleza sin estado de REST.
Por lo tanto, a costa de perder la posibilidad de hacer rollback, voy a mostrar únicamente la actualización en un único paso

Upgrade un paso

Se utiliza el RPC “install” para esto. A modo de ejemplo se usa la siguiente operación:

POST https://<IP:Puerto>/restconf/operations/Cisco-IOS-XE-install-rpc:install

Lo importante, además del path donde se encuentra la nueva imagen de software, es colocar la key “one-shot” con el valor “true” para que se realice todo el proceso. Si la operación funciona de forma correcta, solo hay que esperar que se reinicie el equipo.

Con esto concluimos este post. Sigan explorando las operaciones disponibles para automatizar el trabajo sobre los equipos de red. Escucho sus sugerencias o información en los comentarios o en las diferentes redes.