API support to manage firmware for FortiGate extended devices

Firmware upgrades for extended FortiGate devices (FortiSwitch, FortiAP, FortiExtender) can now be controlled using several new REST APIs on the FortiGate from a RESTful API Client, such as FortiManager.

[POST] /api/v2/monitor/firmware/extension-device/upload-image

[POST] /api/v2/monitor/firmware/extension-device/download-image

[GET] /api/v2/monitor/firmware/extension-device/image-list

[DELETE] /api/v2/monitor/firmware/extension-device/image

[POST] /api/v2/monitor/firmware/extension-device/trigger-update

[GET] /api/v2/monitor/firmware/extension-device/update-status

Example

Upload a firmware image for an extended device using FortiManager or a RESTful API client, and the FortiGate will store the image locally and return an image_id. The FortiManager or RESTful API client can then retrieve the status of the stored firmware image, download or delete the image, and trigger an update for the extended device.

To use the API to manage firmware for extended devices:

1. Upload an extended device image to get an image_id:

   Required parameters	Description
   type	Extension device type: fortiap, fortiswitch, or fortiextender.
   upload_file	The image .out file to be uploaded In this example, the FortiAP image file will be sent to FortiGate by the Client in the following Content-Type: Content-Type: multipart/form-data; boundary=--------------------------139324056057982302494471 Content-Length: 47943224

   Returns an object with the following fields:

   Field	Description
   major	Parsed major version of the firmware file.
   minor	Parsed minor version of the firmware file.
   patch	Parsed patch version of the firmware file.
   build	Parsed build number of the firmware file.
   type	Type of extension-device.
   platform	Platform that the firmware file is for.
   image_id	The firmware file identifier.

   Example

   POST /api/v2/monitor/firmware/extension-device/upload-image

   Form-data

   {
   "type": "fortiap",
   "upload_file": "FAP_831F-v7-build1032-FORTINET.out"
   }

   Returns 200 OK with the specific image_id.

   {
       "http_method": "POST",
       "results": {
           "image_id": "EXTDEV_IMG_lhYx96",
           "major": 7,
           "minor": 6,
           "patch": 3,
           "build": 1032,
           "platform": "FP831F",
           "type": "fortiap"
       },
       "path": "firmware",
       "name": "extension-device",
       "action": "upload-image",
   ...
   }

2. Download the image by specifying the image_id:

   Required parameters	Description
   type	Extension device type: fortiap, fortiswitch, or fortiextender.
   image_id	Image ID to download.

   Returns the same thing as /api/v2/monitor/firmware/extension-device/upload-image.

   Example

   POST /api/v2/monitor/firmware/extension-device/download-image

   Payload

   {
   "type": "fortiap",
   "image_id": "EXTDEV_IMG_lhYx96"
   }

   Returns 200 OK with the downloaded image.

3. Get a list of uploaded extension-device firmware files:

   Returns an array of objects with fields that correspond to the returned object of the upload-image endpoint.

   Example

   GET /api/v2/monitor/firmware/extension-device/image-list

   Returns 200 OK with image_ids of uploaded images

   {
       "http_method": "GET",
       "results": [
           {
               "image_id": "EXTDEV_IMG_lhYx96",
               "type": "fortiap",
              ...
           }
       ],
       "path": "firmware",
       "name": "extension-device",
       "action": "image-list",
   ...
   }

4. Delete an uploaded firmware file using its image ID:

   Required parameters	Description
   image_id	Image ID of the firmware file to be deleted. It can be multiple IDs, such as ?image_id=image_id1&image_id=image_id2&image_id=image_id3.

   Example

   DELETE /api/v2/monitor/firmware/extension-device/image?image-id=EXTDEV_IMG_lhYx96

   Returns 200 OK

   {
       "http_method": "DELETE",
       "status": "success",
       "http_status": 200,
      ...
   }

5. Trigger update for the uploaded extension-device with image_id, serial, and type:

   Required parameters	Description
   image_id	The image ID to use for upgrading.
   serial	Serial number of the extension device to be upgraded. It can be multiple values, either by specifying query parameters, ?serial=serial1&serial=serial2&serial=serial3, or by creating a POST body, { serial: ['serial1', 'serial2', 'serial'] }.
   type	Type of extension-device.

   Returns an object where the key is the serial number, and the value is any of the following:

   Value	Description
   device not found	Extension device not found.
   success	Successfully added an entry to the system.device-upgrade table. Upgrade should be on the way.
   failed	Encountered an issue adding a new entry to the system.device-upgrade table. Will not be upgraded.
   device already upgrading	An entry already exists in the system.device-upgrade table that is not in the End state (upgrade pending).
   platform mismatch	If the firmware referenced by the specified image ID does not match the platform of the extension device.
   wrong device type	If triggering the update for the wrong device type.

   Example

   POST /api/v2/monitor/firmware/extension-device/trigger-update

   Payload

   {
   "image_id": "EXTDEV_IMG_lhYx96",
   "serial": "FP831FTF23006968",
   "type": "fortiap"
   }

   Returns 200 OK

   {
       "http_method": "POST",
       "results": {
           "FP831FTF23006968": "success"
       },
       "vdom": "vdom1",
       "path": "firmware",
       "name": "extension-device",
       "action": "trigger-update",
       "status": "success",
       "serial": "FG4H1FT922902448",
   ...
   }

6. Get update status, returns the status of the upgrades:

   Optional parameter	Description
   serial	Serial number of the extension device whose status will be returned. It can be multiple values, such as ?serial=serial1&serial=serial2 If not defined, it will return the status of all extension-device upgrades.

   A list of devices and other information is returned.

   Returned parameters	Description
   serial	Serial number of the extension device.
   image_id	The image ID that was used in the upgrade.
   status	The status of the upgrade; similar to the status defined in the system.device-upgrade.

   Example

   GET /api/v2/monitor/firmware/extension-device/update-status

   Returns 200 OK

   {
       "http_method": "GET",
       "results": [
           {
               "image_id": "EXTDEV_IMG_lhYx96",
               "serial": "FP831FTF23006968",
               "status": "success"
           }
   ,
       "path": "firmware",
       "name": "extension-device",
       "action": "update-status",
       "status": "success",
       ...
   }