Firmware¶
The firmware API provides an interface to download, remove and list firmware images which later can be used on managed devices.
Instead of uploading a file somewhere, you will have to tell this API where to download the file from. The API will then schedule a job and fetch the file and validate it towards the supplied SHA1 checksum.
When upgrading devices we can chose to either work on a single device or a group of devices, this is described in more detailed further down in this document.
Download firmware¶
To download firmware from a URL, the following method can be used:
curl https://hostname/api/v1.0/firmware -X POST -H "Content-Type: application/json" -d '{"url": "http://remote_host/firmware.bin", "sha1": "e0537400b5f134aa960603c9b715a8ce30306071", "verify_tls": false}'
The method will accept three attributes: url, sha1 and verify_tls:
url: The URL to the file we should download.
sha1: The checksum of the file.
verify_tls: Should we validate SSL certificates or not?
That will schedule a new job which will report back the outcome of the download. The job status can be seen using the jobs API:
curl https://hostname/api/v1.0/jobs?limit=1
{
"status": "success",
"data": {
"jobs": [
{
"id": "5d848e7cdd428720db72c686",
"start_time": "2019-09-20 08:31:57.073000",
"finish_time": "2019-09-20 08:31:58.585000",
"status": "FINISHED",
"function_name": "get_firmware",
"result": "\"File downloaded from: https://remote_host/firmware.bin\"",
"exception": null,
"traceback": null,
"next_job_id": null,
"finished_devices": []
}
]
}
}
List firmware¶
The same procedure as above can be used when listing the available firmwares. The only difference is that when listing all available firmware images no job is scheuled.
To list a single firmware image:
curl https://hostname/api/v1.0/firmware/firmware.bin
{
"status": "success",
"data": "Scheduled job get firmware information",
"job_id": "5d848f87dd428720db72c68d"
}
And the reponse when getting job information. Note that the result will contain the checksum of the images if it exists, otherwise an error will be given back.
{
"status": "success",
"data": {
"jobs": [
{
"id": "5d848f87dd428720db72c68d",
"start_time": "2019-09-20 08:36:24.078000",
"finish_time": "2019-09-20 08:36:24.110000",
"status": "FINISHED",
"function_name": "get_firmware_chksum",
"result": "\"e0537400b5f134aa960603c9b715a8ce30306071\"",
"exception": null,
"traceback": null,
"next_job_id": null,
"finished_devices": []
}
]
}
}
We can also list all available firmwares. Please note that here we don’t create a job. Here we don’t get the checksum for all images, since we don’t want to waste cycles on computing that checksum for each and every firmware.
curl https://hostname/api/v1.0/firmware
{
"status": "success",
"data": {
"status": "success",
"data": {
"files": [
"firmware.bin",
"firmware2.bin"
]
}
}
}
Remove firmware¶
To remove a firmware image:
curl -X DELETE https://hostname/api/v1.0/firmware/firmware.bin
{
"status": "success",
"data": "Scheduled job to remove firmware",
"job_id": "5d849177dd428720db72c693"
}
Upgrade firmware on device(s)¶
As of today we support upgrading firmware on Arista EOS acces switches. The upgrade procedure can do a ‘pre-flight check’ which will make sure there is enough disk space before attempting to download the firmware.
The API method will accept a few parameters:
group: Optional. The name of a group, all devices in that group will be upgraded.
hostname: Optional. If a hostname is specified, this single device will be upgraded.
filename: Mandatory. Name of the new firmware, for example “test.swi”.
url: Optional, can also be configured as an environment variable, FIRMQRE_URL. URL to the firmware storage, for example “http://hostname/firmware/”. This should typically point to the CNaaS NMS server and files will be downloaded from the CNaaS HTTP server.
download: Optional, default is false. Only download the firmware.
pre_flight: Optional, default is false. If true, check disk-space etc before downloading the firmware.
post_flight: Optional, default is false. If true, update OS version after the upgrade have been finished.
post_waittime: Optional, default is 0. Defines the time we should wait before trying to connect to an updated device.
activate: Optional, default is false. Control whether we should install the new firmware or not.
reboot: Optional, default is false. When the firmware is downloaded, reboot the switch.
start_at: Schedule a firmware upgrade to be started sometime in the future.
An example CURL command can look like this:
curl -k -s -H "Content-Type: application/json" -X POST https://hostname/api/v1.0/firmware/upgrade -d '{"group": "ACCESS", "filename": "test_firmware.swi", "url": "http://hostname/", "pre-flight": true, "download": true, "activate": true, "reboot": true, "start_at": "2019-12-24 00:00:00", "post_flight": true, "post_waittime": 600'}
The output from the job will look like this:
{
"status": "success",
"data": {
"jobs": [
{
"id": "5dcd110a5670fd67a615b089",
"start_time": "2019-11-14 08:32:11.135000",
"finish_time": "2019-11-14 08:34:50.352000",
"status": "FINISHED",
"function_name": "device_upgrade",
"result": {
"eoaccess": [
{
"name": "device_upgrade_task",
"result": "",
"diff": "",
"failed": false
},
{
"name": "arista_pre_flight_check",
"result": "Pre-flight check done.",
"diff": "",
"failed": false
},
{
"name": "arista_firmware_download",
"result": "Firmware download done."
"diff": "",
"failed": false
},
{
"name": "arista_firmware_activate",
"result": "Firmware activate done.",
"diff": "",
"failed": false
},
{
"name": "arista_device_reboot",
"result": "Device reboot done.",
"diff": "",
"failed": false
},
{
"result": "Post-flight, OS version updated for device eosaccess, now 4.23.2F-15405360.4232F.",
"task_name": "arista_post_flight_check",
"diff": "",
"failed": false
}
],
"_totals": {
"selected_devices": 1
}
},
"exception": null,
"traceback": null,
"next_job_id": null,
"finished_devices": [\"eosaccess\"]
}
]
}
}