Device Management

8. Device Management#

8.1. How to rename a managed device?#

Warning

This section is describing how to change the device name used by FortiManager.

Changing the device’s hostname is a different topic (even though most of the time, for ease of operations, both are identical).

You can use two endpoints:

/dvmdb/device/<device>
/dvmdb/adom/<adom>/device/<device>

8.1.1. Using /dvmdb/device/<device>#

To rename the fgt-741-001 device to fgt-742-001 in the dc_emea ADOM:

REQUEST

{
  "id": 3,
  "method": "set",
  "params": [
    {
      "data": {
        "name": "fgt-742-001"
      },
      "url": "/dvmdb/device/fgt-741-001"
    }
  ],
  "session": "{{session}}"
}

RESPONSE

{
  "id": 3,
  "result": [
    {
      "data": {
        "name": "fgt-742-001"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device/foobar"
    }
  ]
}

8.1.2. Using /dvmdb/adom/<adom>/device/<device>#

To rename the fgt-741-001 device to fgt-742-001 in the dc_emea ADOM:

REQUEST

{
  "id": 3,
  "method": "update",
  "params": [
    {
      "data": {
        "name": "fgt-742-001"
      },
      "url": "/dvmdb/adom/dc_emea/device/fgt-741-001"
    }
  ],
  "session": "{{session}}"
}

Note

You can also use the set method

RESPONSE

{
  "id": 3,
  "result": [
    {
      "data": {
        "name": "fgt-742-001"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/dc_emea/device/fgt-741-001"
    }
  ]
}

8.2. Device status#

This section is about getting the Config Status, Policy Package Status, Provisioning Templates status, ADOM membership, cluster member status, etc. for the managed devices.

This is more or less the information showing up int the Device Manager > Device & Groups page of the FortiManager GUI:

To get those status for a specific device:

REQUEST:

{
  "id": 3,
  "method": "get",
  "params": [
    {
      "option": [
        "extra info",
        "assignment info"
      ],
      "url": "/dvmdb/device/cluster_site_1"
    }
  ],
  "session": "POAGtBw1yyb4wvLO6SNpVkQwzVtKFFQaER/I3B/BRZkJj7RkFjfBuhJdFHmP2ShOtr7SDOw1EyJuG+BwCPDOiA==",
  "verbose": 1
}

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": {
        "adm_pass": [
          "ENC",
          "g9ZrdUj7gIqEKVU6aI9Azk8+hXo8BUUpRXFzN++KBvjfXH+dcK90agrchqFtsr2WH/nkbeLDxeS/jhmlnXKAg5/q+D6nYsrMDudW1SHLBWLgYzJccx9ja5tZOOwvYoYm1ac+txELl+U/XCIarQHlRB0AEO5syVKzfWAye8akyCNqVwGs"
        ],
        "adm_usr": "admin",
        "app_ver": "",
        "assignment info": [
          {
            "name": "branches",
            "status": "installed",
            "type": "devprof"
          }
        ],
        "...": "...",
        "conf_status": "insync",
        "conn_mode": "passive",
        "conn_status": "up",
        "db_status": "nomod",
        "dev_status": "auto_updated",
        "extra info": {
          "adom": "production"
        },
        "ha_slave": [
          {
            "did": "cluster_site_1",
            "flags": null,
            "idx": 0,
            "name": "i_04_fgt_11",
            "obj ver": -1,
            "oid": 1463,
            "prio": 200,
            "role": "master",
            "sn": "FGVMULTM22000561",
            "status": 1
          },
          {
            "did": "cluster_site_1",
            "flags": null,
            "idx": 2147483647,
            "name": "i_05_fgt_12",
            "obj ver": -1,
            "oid": 1464,
            "prio": 100,
            "role": "slave",
            "sn": "FGVMULTM22000560",
            "status": 2
          }
        ],
        "...": "...",
        "hostname": "i_04_fgt_11",
        "...": "..."
        "vdom": [
          {
            "assignment info": [
              {
                "name": "branches",
                "status": "installed",
                "type": "policy"
              },
              {
                "name": "1375-3",
                "status": "installed",
                "type": "wtp"
              },
              {
                "name": "branches",
                "status": "installed",
                "type": "wanprof"
              },
              {
                "name": "1375-3",
                "status": "installed",
                "type": "fsp"
              },
              {
                "name": "1375-3",
                "status": "imported",
                "type": "fext"
              },
              {
                "name": "branches",
                "status": "installed",
                "type": "cli"
              },
              {
                "name": "branches",
                "status": "installed",
                "stype": "_ipsec",
                "type": "template"
              },
              {
                "name": "branches",
                "status": "installed",
                "stype": "_router_static",
                "type": "template"
              },
              {
                "name": "branches",
                "status": "installed",
                "stype": "unkown",
                "type": "template"
              }
            ],
            "...": "...",
            "extra info": {
              "adom": "production"
            },
            "...": "..."
            "name": "root",
            "...": "..."
          }
        ],
        "...": "..."
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device/cluster_site_1"
    }
  ]
}

This output is showing a lot of information:

Lines 12-18: This is showing that the device (global scope) is assigned to a system template (devprof) named branches and that it is in sync (installed). It means the content of the system template has been applied to real managed device.
Lines 20-24: Those are the device status.
Lines 25-27: The device (global scope) belongs to ADOM production. One of its VDOMs could belong to another ADOM…
Lines 28-53: It indicates this is a cluster and here are the members. The status indicates the status of the member. 1 means the member is up while 2 means it is down.
Lines 57-117: The vdom block gives the status information for all VDOMs. Lines 60-64 gives the policy package name (branches) and status (installed), lines 70-74 gives the SD-WAN Template name (branches) and status (installed), etc.
Lines 110-114: It gives the VDOM name (root) along with the ADOM it belongs to (production).

This FortiManager JSON RPC API request is very powerful: it can return the status information for all devices of all ADOMs!:

REQUEST:

{
  "id": 3,
  "method": "get",
  "params": [
    {
      "option": [
        "extra info",
        "assignment info"
      ],
      "url": "/dvmdb/device"
    }
  ],
  "session": "uN1mD86SolLxF7dwUZKLZcRh3doHd3ELSX0oxZjwA6El33hcGn9Xl8ImM2Th7v/lmIn825z4OqaN2EpbBazPFw==",
  "verbose": 1
}

8.3. How to refresh a device?#

It’s about using API to reproduce the GUI Refresh Device action available when you right click a managed device from the Device Manager > Device & Groups page.

8.3.1. Refresh one device#

REQUEST:

{
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "{{adom}}",
        "device": "fgt_1",
        "flags": [
          "create_task",
          "nonblocking"
        ]
      },
      "url": "/dvm/cmd/update/device"
    }
  ],
  "session": "{{session_id}}",
  "id": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "pid": 6665,
        "taskid": 4
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/update/device"
    }
  ]
}

8.3.2. Refresh multiple devices#

REQUEST:

{
  "id": 1,
  "session": "{{session_id}}",
  "params": [
    {
      "url": "/dvm/cmd/update/dev-list",
      "data": {
        "adom": "{{adom}}",
        "flags": [
          "create_task",
          "nonblocking"
        ],
        "update-dev-member-list": [
          {
            "name": "fgt_1"
          },
          {
            "name": "hub_1"
          },
          {
            "name": "hub_2"
          }
        ]
      }
    }
  ]
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "taskid": 100
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/update/dev-list"
    }
  ]
}

8.4. Device coordinates#

You can configure the device coordinates in the device CMDB using the FMG JSON RPC API url:

/pm/config/device/<device>/global/system/global

by touching the gui-device-latitude and gui-device-longitude attributes.

You can also set the coordinates in the device’s metadata using the FMG JSON RPC API url:

/dvmdb/device/<device>

by touching the latidude and longitude attributes.

According to #0708937, FMG is saving the method used to change the coordinates in the attribute location_from from device’s metadata.

This attribute could have value like gui, json, config or unset. It helps FMG to figure out how to set the coordinates. It helps to figure out how the coordinates synchronization is performed between device configuration and metadata…

In the below example, we can see that the coordinates were existing in devices configuration before their on-boarding in FMG:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "get",
  "params": [
    {
      "fields": [
        "name",
        "location_from"
      ],
      "loadsub": 0,
      "url": "/dvmdb/device"
    }
  ],
  "session": "9US6WwzjEQ/ktSRPInyURpuhjleLsrLvAk/kPo8rgFTAo/AAoLFTNywA666X7j65u1UoKd1EBDu0TdA8plmCyA==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": [
        {
          "location_from": "config",
          "name": "fgt_00_1",
          "oid": 161
        },
        {
          "location_from": "config",
          "name": "fgt_01_1",
          "oid": 170
        },
        {
          "location_from": "config",
          "name": "fgt_02_1",
          "oid": 174
        },
        {
          "location_from": "config",
          "name": "fgt_03_1",
          "oid": 172
        },
        {
          "location_from": "config",
          "name": "fgt_04_1",
          "oid": 176
        },
        {
          "location_from": "config",
          "name": "fgt_05_1",
          "oid": 182
        },
        {
          "location_from": "config",
          "name": "fgt_06_1",
          "oid": 184
        },
        {
          "location_from": "config",
          "name": "fgt_07_1",
          "oid": 186
        },
        {
          "location_from": "config",
          "name": "fgt_08_1",
          "oid": 189
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device"
    }
  ]
}

8.5. How to get the full device database syntax?#

Caught in #0607071.

REQUEST:

{
  "id": 1,
  "method": "get",
  "params": [
    {
      "url": "pm/config/device/d1/global/_syntax/cli_only"
      "option": "syntax"
    }
  ]
}

8.6. How to add a real device?#

The following example shows how to add the dev_001 in the demo ADOM:

REQUEST

{
  "id": 3,
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "demo",
        "device": {
          "adm_pass": "fortinet",
          "adm_usr": "admin",
          "ip": "10.210.34.51",
          "mgmt_mode": "fmg",
          "name": "dev_001"
        },
        "flags": [
          "create_task"
        ]
      },
      "url": "/dvm/cmd/add/device"
    }
  ],
  "session": "{{session}}"
}

Note

This API request will be blocking
You will get a response only once the device will be added within FortiManager
The create_task flag is a good practice; FortiManager creates a task that you can refer to in case the add device operation fails
To get a non-blocking operation, you can add the nonblocking flag:
```
"flags": [
  "create_task",
  "nonblocking"
]
```
In that case, FortiManager will return immediately while still creating a task that this time you should monitor to follow its progress
The none flag will just do the add device operation, without creating a task; task will be blocking

Warning

If you use the nonblocking flag, then you have to keep the API session up till the end of the add device operation
The add device operation takes time; if your program logs out right after the API call, but while the add device operation is still in progress, then FortiManager will return a message (visible in the task, provided you used the create_task flag) similar to:
```
Failed to update device information.
```
It is recommended to combine the nonblocking with the create_task flag in order to monitor the task progress and logs out from the API session only once the add operation is successfully completed

RESPONSE

{
  "id": 3,
  "result": [
    {
      "data": {
        "device": {
          "adm_pass": "fortinet",
          "adm_usr": "admin",
          "av_ver": "1.00000(2018-04-09 18:07)",
          "beta": -1,
          "branch_pt": 523,
          "build": 523,
          "conn_mode": 1,
          "conn_status": 1,
          "dev_status": 1,
          "flags": 2097169,
          "hostname": "dev_001",
          "ip": "10.210.34.51",
          "ips_ver": "6.00741(2015-12-01 02:30)",
          "last_checked": 1711025724,
          "maxvdom": 11,
          "mgmt.__data[0]": 3870643,
          "mgmt.__data[4]": 2105184256,
          "mgmt.__data[6]": 1,
          "mgmt_mode": 3,
          "mgmt_uuid": "1981351328",
          "mr": 0,
          "name": "dev_111",
          "oid": 34835,
          "opts": 256,
          "os_type": 0,
          "os_ver": 7,
          "patch": 12,
          "platform_id": 159,
          "platform_str": "FortiGate-VM64",
          "relver_info": "GA",
          "sn": "FGVMMLREDACTED33",
          "source": 1,
          "tab_status": "<unknown>",
          "version": 700,
          "vm_cpu": 1,
          "vm_cpu_limit": 1,
          "vm_mem": 2007,
          "vm_mem_limit": 2147483647,
          "vm_status": 3
        },
        "taskid": 752
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/add/device"
    }
  ]
}

Note

If you’re using the following list of flags:

"flags": [
  "create_task",
  "nonblocking"
]

You will get this shorter response:

{
  "id": 3,
  "result": [
    {
      "data": {
        "pid": 31637,
        "taskid": 754
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/add/device"
    }
  ]
}

8.7. How to change the serial number of a managed device?#

This is for the case where the former device failed and a new one was shipped to replace it.

FortiManager is still having the configuration of the failed device linked to a managed device whose serial number doesn’t correspond to the new shipped device.

It is possible to fix the wrong serial number maintained by FortiManager using the following FortiManager JSON RPC API request:

REQUEST:

{
  "id": 3,
  "method": "exec",
  "params": [
    {
      "data": {
        "sn": "FGVMULTM21001111"
      },
      "url": "/dvmdb/device/replace/sn/fgt"
    }
  ],
  "session": "GD9Ce1EbGr+b1ebMUxC1PY4wPlgpQGu9y3vlyLCtrH7AE+wg9uXvENAKcIhbK86r2DpxngsZewLlokDZ2Av3uQ=="
}

This request is replacing the serial number of device named fgt with new serial number FGVMULTM21001111.

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device/replace/sn/fgt"
    }
  ]
}

Warning

Once the FortiManager will have a matching serial number, it will be able to reconnect to the new device.
However, if FortiManager is in auto-update mode, it will just retrieve a blank configuration: the one from the new device!
You will lose the production configuration which was maintained by FortiManager for the failed device.
So better to implement this when FortiManager isn’t in auto-update mode:
```
config system admin setting
set auto-update disable
end
```

8.8. How to get unauthorized devices?#

An unauthorized or unregistered device is a device which managed to acquire its FortiManager details which started its FGFM tunnel.

However, on the FortiManager side, such device has been accepted but not yet authorized; it has been moved in the root ADOM and placed in the special Unauthorized Devices device group.

Note

the Unauthorized Devices device group is only visible when there are unauthorized devices

The following example shows how to get the list of unregistered or unauthorized devices:

REQUEST

{
  "id": 3,
  "method": "get",
  "params": [
    {
      "fields": [
        "name",
        "mgmt_mode"
      ],
      "filter": [
        "mgmt_mode",
        "==",
        "unreg"
      ],
      "loadsub": 0,
      "url": "/dvmdb/device"
    }
  ],
  "session": "{{session}}",
  "verbose": 1
}

Note

As you can see, to get the unauthorized devices, you have to filter based on the mgmt_mode attribute and the unreg (i. e., unregistered) value

RESPONSE

{
  "id": 3,
  "result": [
    {
      "data": [
        {
          "mgmt_mode": "unreg",
          "name": "dev_001",
          "oid": 34749
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device"
    }
  ]
}

Note

That response shows there’s a single unauthorized device named dev_001

8.9. How to promote/authorize a real device?#

Note

authorize is a new wording introduced with recent FMG versions
With older FMG versions, the ADOM root’s left tree for not yet managed devices was named Unregistered Devices and the right-click action was Promote
Now left tree name is Unauthorized Devices, hence the new Authorize right-click action
Promote could be consider the same as Authorize!

The main FMG JSON RPC URL is:

/dvm/cmd/add/device

This URL can be used to:

Add a Model Device
Add a real device (but not yet connected to FMG)
Promote/Authorize a real device (already connected to FMG)

You’re now able to Authorize one of your unauthorized device using the following request.

It shows how to on-board the dev_001 unauthorized device in the demo ADOM:

REQUEST

{
  "id": 1,
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "demo",
        "device": {
          "adm_pass": "fortinet",
          "adm_usr": "admin",
          "device action": "promote_unreg",
          "name": "dev_001"
        },
        "flags": [
          "create_task"
        ]
      },
      "url": "/dvm/cmd/add/device"
    }
  ],
  "session": "{{session}}"
}

Note

name has to be the device name as show in the GUI (not the hostname, the device name)
adm_usr/ adm_pass has to be similar to what’s is currently set on your real device

If device is from factory default configuration (and it retrieved its FMG IP via some external mechanisms like FortiDeploy/ortiCloud), it is admin and no password respectively.

If you already set a password to the admin’s account, then you have to reflect this password here.

If the authorize process gets stuck at 20% it’s probably due to an authentication error.
device action is quite meaningful
It’s always a good practise to create a task; in any cases, the operation will return only when the device authorization will be completed

REQUEST

{
  "id": 1,
  "result": [
    {
      "data": {
        "device": {
          "adm_pass": "fortinet",
          "adm_usr": "admin",
          "av_ver": "89.01100(2021-09-14 12:26)",
          "beta": -1,
          "branch_pt": 157,
          "build": 157,
          "conf_status": 2,
          "conn_mode": 1,
          "conn_status": 1,
          "dev_status": 0,
          "faz.perm": 15,
          "flags": 2163073,
          "hostname": "fgt_dut1",
          "ip": "10.210.35.101",
          "ips_ver": "6.00741(2015-12-01 02:30)",
          "last_checked": 1631652502,
          "maxvdom": 1,
          "mgmt_id": 810637395,
          "mgmt_if": "port1",
          "mgmt_mode": 3,
          "mr": 0,
          "name": "dev_001",
          "oid": 1638,
          "os_type": 0,
          "os_ver": 7,
          "patch": 1,
          "platform_id": 133,
          "platform_str": "FortiGate-VM64-KVM",
          "sn": "FGVMSLREDACTED54",
          "source": 1,
          "tab_status": "<unknown>",
          "tunnel_ip": "169.254.0.2",
          "vdom": [
            {
              "devid": 1638,
              "ext_flags": 1,
              "name": "root",
              "oid": 3,
              "opmode": 1,
              "status": "<unknown>",
              "tab_status": "<unknown>"
            }
          ],
          "version": 700,
          "vm.lic_type": 17,
          "vm_cpu": 4,
          "vm_cpu_limit": 32767,
          "vm_lic_expire": 0,
          "vm_mem": 3962,
          "vm_mem_limit": 2147483647,
          "vm_status": 3
        },
        "taskid": 3315
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/add/device"
    }
  ]
}

8.11. How to get the ADOM a device belongs to?#

Caught in #0414003.

There are two methods:

Combine object master with filter
Use the extra info option

8.11.1. How to get the ADOM a device belongs to using object master with filter?#

You can append the object master to the /dvmdb/device/<device>/ endpoint.

But in this case, you also have to use the filter in an unusual as shown below.

To get the ADOM details the fgt-742-001 belongs to:

REQUEST

{
  "id": 3,
  "method": "get",
  "params": [
    {
      "filter": [
        "adom"
      ],
      "url": "/dvmdb/device/fgt-742-001/object master"
    }
  ],
  "session": "{{session}}",
  "verbose": 1
}

RESPONSE

{
  "id": 3,
  "result": [
    {
      "data": [
        {
          "create_time": 1700207435,
          "desc": "",
          "flags": "no_vpn_console",
          "lock_override": 0,
          "log_db_retention_hours": 1440,
          "log_disk_quota": 0,
          "log_disk_quota_alert_thres": 90,
          "log_disk_quota_split_ratio": 70,
          "log_file_retention_hours": 8760,
          "logview_customize": "",
          "mig_mr": 0,
          "mig_os_ver": "0.0",
          "mode": "gms",
          "mr": 4,
          "name": "dc_emea",
          "obj_customize": "",
          "oid": 165,
          "os_ver": "7.0",
          "restricted_prds": "fos",
          "state": 1,
          "tab_status": "",
          "tz": 2,
          "uuid": "210ecfa4-baed-51ee-a551-2efcb4f9a788",
          "workspace_mode": 0
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device/fgt-742-001/object master"
    }
  ]
}

Note

The fgt-742-001 device belongs to the dc_emea ADOM

8.11.2. How to get the ADOM a device belongs to using the extra info option?#

Since #0462768, we can use just the option extra info as shown below.

To get the ADOM details the fgt-742-001 belongs to:

REQUEST

{
  "id": 4,
  "method": "get",
  "params": [
    {
      "fields": [
        "name",
        "extra info"
      ],
      "option": [
        "extra info",
        "no loadsub"
      ],
      "url": "/dvmdb/device/fgt-742-001"
    }
  ],
  "session": "{{session}}",
  "verbose": 1
}

RESPONSE

{
  "id": 4,
  "result": [
    {
      "data": {
        "extra info": {
          "adom": "dc_emea"
        },
        "name": "fgt-742-001",
        "obj ver": -1,
        "oid": 596
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device/fgt-742-001"
    }
  ]
}

Note

The fgt-742-001 device belongs to the dc_emea ADOM

8.12. How to install device settings against devices?#

To install Device Settings againt devices branch1 and branch2 from the demo ADOM:

REQUEST

{
  "id": 1,
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "demo",
        "dev_rev_comments": "sr_01233",
        "flags": [
          "none"
        ],
        "scope": [
          {
            "name": "branch1",
            "vdom": "root"
          },
          {
            "name": "branch2",
            "vdom": "root"
          }
        ]
      },
      "url": "/securityconsole/install/device"
    }
  ],
  "session": "{{session}}"
}

Note

dev_rev_comments will be used as the comment for the created Device Revision (see section Device revisions)

RESPONSE

{
  "id": 1,
  "result": [
    {
      "data": {
        "task": 462
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/securityconsole/install/device"
    }
  ]
}

8.13. Device Groups#

8.13.1. How to install device settings against a device group?#

We have device group france. Goal is to install device settings against device group france.

REQUEST:

TODO

RESPONSE:

TODO

For the moment, it is not supported (#0617705).

8.13.2. How to create a device group?#

To add group Spokes in ADOM DEMO:

REQUEST

{
  "id": 1,
  "method": "add",
  "params": [
    {
      "data": {
        "name": "Spokes",
        "os_type": "fos",
        "type": "normal"
      },
      "url": "/dvmdb/adom/DEMO/group"
    }
  ],
  "session": "{{session}}"
}

RESPONSE

{
  "id": 1,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/DEMO/group"
    }
  ]
}

8.13.3. How to add a device in a device group?#

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "add",
  "params": [
    {
      "data": {
        "name": "branch2_fgt",
        "vdom": "root"
      },
      "url": "/dvmdb/adom/DEMO/group/branches/object member"
    }
  ],
  "session": "KOxfoeLVHkkmSwbyuAQ7pDU8uU5WoCFJH0k3p2WlFCU0jlaBMpd0zvzN69P31WBDy1vMNWHJpZed71xkce6edw==",
  "verbose": 1
}

RESPONSE

{
  "id": 1,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/DEMO/group/branches/object member"
    }
  ]
}

8.13.4. How to add multiple devices in a device group?#

We can also add multiple devices at once.

To add devices peer22 and peer23 in device group Spokes from ADOM DEMO:

REQUEST

{
  "id": 1,
  "method": "add",
  "params": [
    {
      "data": [
        {
          "name": "peer22",
          "vdom": "root"
        },
        {
          "name": "peer23",
          "vdom": "root"
        }
      ],
      "url": "/dvmdb/adom/DEMO/group/Spokes/object member"
    }
  ],
  "session": "{{session}}"
}

RESPONSE

{
  "id": 1,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/DEMO/group/Spokes/object member"
    }
  ]
}

8.13.5. How to add a device group into a device group?#

To add the brasil device group into the amer device group, the tenant_01 ADOM:

REQUEST

{
  "id": 36,
  "method": "add",
  "params": [
    {
      "data": {
        "name": "brasil"
      },
      "url": "/dvmdb/adom/tenant_01/group/amer/object member"
    }
  ],
  "session": "{{session}}"
}

Note

If you don’t specify the vdom attribute, FortiManager will consider the name attribute as the name of a device group

RESPONSE

{
  "id": 36,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/tenant_01/group/amer/object member"
    }
  ]
}

8.13.6. How to get the device group members?#

To get the list of devices belonging to device group foobar from ADOM DEMO_008:

REQUEST:

{
"id": 1,
"jsonrpc": "1.0",
"method": "get",
"params": [
    {
    "option": [
        "object member"
    ],
    "url": "/dvmdb/adom/DEMO_008/group/foobar"
    }
],
"session": "JMss+Pu+jvJFzYXde99qPibZk2qS1bJfyRP9tEjg3HtSVFHe1Gb0vqEFWhoP91vgmZKIrLuCwK6hQsw0cSkdHw==",
"verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "desc": "",
        "name": "foobar",
        "object member": [
          {
            "name": "demo_008_device_002",
            "oid": 1483,
            "vdom": "root",
            "vdom_oid": 3
          },
          {
            "name": "demo_008_device_003",
            "oid": 1506,
            "vdom": "root",
            "vdom_oid": 3
          },
          {
            "name": "foobar_001",
            "oid": 1552,
            "vdom": "root",
            "vdom_oid": 3
          }
        ],
        "oid": 1743,
        "os_type": "fos",
        "type": "normal"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/DEMO_008/group/foobar"
    }
  ]
}

8.13.7. How to delete a device from a device group?#

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "delete",
  "params": [
    {
      "data": {
        "name": "branch2_fgt",
        "vdom": "root"
      },
      "url": "/dvmdb/adom/DEMO/group/branches/object member"
    }
  ],
  "session": "v8scVv8nccmO0JNHIIj1KTMtorqsxXDwYf4BrdWac9syWHDH4zQaLuYhOZKWaPtwWKZKM3IEVaBBOwz9RPMHmg==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/DEMO/group/branches/object member"
    }
  ]
}

8.13.8. How to delete multiple devices from a device group?#

We can also delete multiple devices at once.

To delete devices peer22 and peer23 from device group Spokes from ADOM DEMO:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "delete",
  "params": [
    {
      "data": [
        {
          "name": "peer21",
          "vdom": "root"
        },
        {
          "name": "peer22",
          "vdom": "root"
        }
      ],
      "url": "/dvmdb/adom/DEMO/group/Spokes/object member"
    }
  ],
  "session": "OozQ3Nuj4p2VTmivkfSlsgLrWZmCT3SwRPMpujFV7DE1aaVLhn+jpcJhecsPKNmulfkX4b0d557iIBW7sRANzg==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/DEMO/group/Spokes/object member"
    }
  ]
}

8.13.9. How to delete a device group?#

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "delete",
  "params": [
    {
      "url": "/dvmdb/adom/DEMO/group/Spokes"
    }
  ],
  "session": "OSz5aOlsNe10S5Op5i4J3Wu1dR7BCe+V+06Ktthtl3JOh82oyFTdAvOG8b0JRLZd26oHpO5w1X+1/165QMjZ5g==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/DEMO/group/Spokes"
    }
  ]
}

8.14. How to delete a device?#

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "root",
        "device": "FGVMUL0000138718",
        "flags": [
          "none"
        ]
      },
      "url": "/dvm/cmd/del/device"
    }
  ],
  "session": "HDUilklPi9ik9UlI3ViL7CviROjqqNyF21PaaYRIfrIsiYwNYVzkzWKIE/bX0Pkj+ejQVE2Il7TMi/XrVxqGwA==",
  "verbose": 1
}

RESPONSE:

{
"id": 1,
"result": [
        {
        "status": {
                "code": 0,
                "message": "OK"
        },
        "url": "/dvm/cmd/del/device"
        }
]
}

You might face situations where some devices don’t belong to any ADOMs (which isn’t normal). Following FortiManager CLI command output illustrates this behavior:

fmg_720_interim # diagnose dvm device list
--- There are currently 2 devices/vdoms managed ---
--- There are currently 1 devices/vdoms count for license ---

TYPE            OID    SN               HA      IP              NAME                                             ADOM                                             IPS                FIRMWARE
unregistered    3853   FGVMULTM21001357 -       10.210.35.102   FGVMULTM21001357                                 root                                             N/A                7.0 MR0 (157)
                |- STATUS: dev-db: unknown; conf: unknown; cond: unregistered; dm: none; conn: unknown; FMGC
                |- vdom:[3]root flags:0 adom:root pkg:[never-installed]
fmgfaz-model    3795                    -                       root_dev_005                                     ???                                              N/A                7.0 MR0 (296)
                |- STATUS: dev-db: unknown; conf: unknown; cond: unknown; dm: unknown; conn: unknown
                |---- warning: device is not assigned to an adom, please delete and add this device again
[...]

You can see that device root_dev_005 is missing its ADOM information.

To delete such a device, just use an empty adom value:

REQUEST:

{
  "id": 3,
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "",
        "device": "root_dev_005",
        "flags": [
          "create_task"
        ]
      },
      "url": "/dvm/cmd/del/device"
    }
  ],
  "session": "DHfvd10txF6O7Uwciw+6Q4dOm6OQb3E5IukQV/eNVI+uGVK3j3Guqi523eViEkZpgbJ8vgjXBHCajESRmn7XBQ=="
}

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": {
        "taskid": 4476
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/del/device"
    }
  ]
}

8.15. How to get device’s meta fields?#

Meta fields are not returned when getting the list of devices or when getting the properties of a specific device.

We have to add the option get meta. We can also use the fields parameter to only return the now exposed meta fields (and other fields we would like to be in the output).

The option works when getting list of devices:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "get",
  "params": [
    {
      "fields": [
        "name",
        "meta fields"
      ],
      "loadsub": 0,
      "option": [
        "get meta"
      ],
      "url": "/dvmdb/adom/SDWAN/device"
    }
  ],
  "session": "WWea7FR1N3iXssdeNZdUO/6m2AR1LmEaz8jaJmBwTm8BhmiySKNylqqsc2vrDNP1TMruRxX1fC6E4DxuFJTXKg==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": [
        {
          "meta fields": {
            "Address": "",
            "Company/Organization": "",
            "Contact Email": "",
            "Contact Phone Number": "",
            "branch_id": "",
            "branch_latitude": "",
            "branch_longitude": "",
            "branch_timezone": "",
            "lan_netmask": "",
            "lan_network": ""
          },
          "name": "device-001",
          "oid": 1152
        },
        {
          "meta fields": {
            "Address": "",
            "Company/Organization": "",
            "Contact Email": "",
            "Contact Phone Number": "",
            "branch_id": "1",
            "branch_latitude": "48.85",
            "branch_longitude": "2.34",
            "branch_timezone": "28",
            "lan_netmask": "",
            "lan_network": ""
          },
          "name": "fgt-branch1",
          "oid": 1117
        },
        {
          "meta fields": {
            "Address": "",
            "Company/Organization": "",
            "Contact Email": "",
            "Contact Phone Number": "",
            "branch_id": "2",
            "branch_latitude": "40.71",
            "branch_longitude": "-74.00",
            "branch_timezone": "12",
            "lan_netmask": "",
            "lan_network": ""
          },
          "name": "fgt-branch2",
          "oid": 1144
        },
        {
          "meta fields": {
            "Address": "",
            "Company/Organization": "",
            "Contact Email": "",
            "Contact Phone Number": "",
            "branch_id": "",
            "branch_latitude": "",
            "branch_longitude": "",
            "branch_timezone": "",
            "lan_netmask": "",
            "lan_network": ""
          },
          "name": "fgt-hub",
          "oid": 1111
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/SDWAN/device"
    }
  ]
}

8.16. How to set device’s meta fields?#

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "set",
  "params": [
    {
      "data": {
        "meta fields": {
          "branch_id": "2",
          "branch_latitude": "48.892449",
          "branch_longitude": "2.240228",
          "branch_mgmt_ip": "192.168.0.120",
          "branch_tz": "28",
          "region_id": "18"
        }
      },
      "url": "/dvmdb/device/branch2_fgt"
    }
  ],
  "session": "jykn9N/VfDy1fvapET/zbqByuThTpyFQAsqpfD3ViXf93fabHKZpxiRjfcY8jL07eYpTkoyZuc6TVMgfCy/L9g==",
  "verbose": 1
}

Note

Don’t use integer for the metafield.

For instance, for the branch_id meta field we have used a string "2" instead of an integer 2.

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "name": "branch2_fgt"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device/branch2_fgt"
    }
  ]
}

8.18. How to get default settings for a particular type of device?#

Caught in #0613941 & #0953698.

Few FMG JSON API URLs are given:

"url": "pm/config/devicetemplate/FortiGate-1000D/version/600/mr/2/global/system/interface"
"url": "pm/config/devicetemplate/FortiGate-1000D/version/600/mr/2/vdom/root/firewall/address"

Note

Note the distinction between global and per-vdom settings.

Another simpler example to get the system.global default settings:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "get",
  "params": [
    {
      "url": "/pm/config/devicetemplate/FortiGate-1000D/version/600/mr/2/global/system/global"
    }
  ],
  "session": "96aYn/jiPj0YdYoJP6oKzgM5/ChcffAfCvX4q5A3nTpNGXJF33tOkXH8oeWQgmQuyFsZiZdMx3SSg7tDceYDTw==",
  "verbose": 1
}

RESPONSE:

          {
            "id": 1,
            "result": [
              {
                "data": {
                  "admin-concurrent": "enable",
                        "admin-console-timeout": 0,
                        "admin-hsts-max-age": 15552000,
                        "admin-https-pki-required": "disable",
                        "admin-https-redirect": "enable",
                  "admin-https-ssl-versions": [
                          "tlsv1-1",
                          "tlsv1-2",
                          "tlsv1-3"
                        ],
                  "admin-lockout-duration": 60,
                  "admin-lockout-threshold": 3,
                  "admin-login-max": 100,
                  [...]
              }
]
          }

8.19. How to get the policy package status when getting list of devices?#

Starting with #462768 it is now possible to get the policy package status directly when getting the list of devices with FMG API URL /dvmdb/device[/<device>].

We just have to pass the two options extra info and assignment info as shown below:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "get",
  "params": [
    {
      "option": [
        "extra info",
        "assignment info"
      ],
      "url": "/dvmdb/device"
    }
  ],
  "session": "Xcm+v7DP6nhpMFuSPwvuiTl3yrR2sx8uEpwTyAWfc4U+aI5hUngzwRJ/PgwDWzSmRoXWkEmlQ9F2SnsEaXhUZ/CjTlc0JIZO"
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": [
        […]
        "os_ver": 5,
        "patch": 5,
        "platform_str": "FortiGate-7000E",
        "psk": "",
        "sn": "FG73ES3E16000106",
        "source": 1,
        "tab_status": "",
        "tunnel_cookie": "",
        "tunnel_ip": "169.254.0.6",
        "vdom": [
          {
            "assignment info": [
              {
                "name": "DMZF7030_FWM01_FAT_001",
                "status": "imported",
                "type": "policy"
              },
              {
                "name": "3697-102",
                "status": "imported",
                "type": "wtp"
              }
            ],
            "comments": "",
            "devid": "DMZF7030_FWM01",
            "ext_flags": 3,
            "extra info": {
               "adom": "GRAMEEN"
            },
            "flags": 0,
            "name": "FAT",
            "node_flags": 0,
            "obj ver": -1,
            "oid": 102,
            "opmode": 1,
            "rtm_prof_id": 0,
            "status": null,
            "tab_status": null
          },
          […]
        ],
        "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device"
    }
  ]
}

It also works for a VDOM:

REQUEST:

{
"id": 1,
               "jsonrpc": "1.0",
               "method": "get",
               "params": [
                 {
                   "option": [
                     "extra info",
                     "assignment info"
                   ],
                   "url": "/dvmdb/device/peer6/vdom/root"
                 }
               ],
               "session": "PbJC6DrGjngxAk4Ep80yyBLCl3zUxUeGl2wZ8+xvxDPAQdm2PnLGcpb91PMGQg/3QxmEjHsg47akwZ2hC9RwLhDWDTT52VCE"
             }

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "assignment info": [
          {
            "name": "default",
            "status": "installed",
            "type": "policy"
          },
          {
            "name": "3565-3",
            "status": "installed",
            "type": "wtp"
          }
        ],
        "comments": "",
        "devid": "peer6",
        "ext_flags": 1,
        "extra info": {
          "adom": "CM-LAB-001"
        },
        "flags": 0,
        "name": "root",
        "node_flags": 4,
        "obj ver": -1,
        "oid": 3,
        "opmode": 1,
        "rtm_prof_id": 0
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device/peer6/vdom/root"
    }
  ]
}

8.20. How to get the status of a policy package assigned to a specific device?#

Goal is to get the policy package status of a specific device or vdom.

The output should return the policy package status (installed for instance) along with the name of the corresponding policy package.

If the policy package isn’t the the root folder, then the complete or absolute path should be returned.

We need to use the following method and url:

Method	`get`
URL	`/pm/config/adom/<adom>/_package/status/<device>/<vdom>`

The FortiManager JSON API request/response:

To get the status of the policy package assigned to the managed device sp_device_001 and its VDOM root in ADOM TEST:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "get",
  "params": [
    {
      "url": "/pm/config/adom/TEST/_package/status/sp_device_001/root"
    }
  ],
  "session": "nr/snvgTdCwN15fNK1kcdjGQG8QwvUhtVfYaVN4kA2rbNL5fum2QiokmeESHqZFxPH68n/VTYjMFjEvdhQifg+IOWT1udfwv",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "dev": "sp_device_001",
        "pkg": "emea/spain/pp.fw",
        "status": "installed",
        "vdom": "root"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/pm/config/adom/TEST/_package/status/sp_device_001/root"
    }
  ]
}

In the above output, we can see that the status of policy package pp.fw is installed. Furthermore, we can see it is not in the root folder but in emea/spain folder.

8.21. Device revisions#

8.21.1. How to get the list of device revisions for a particular device?#

Caught in #0392486.

To get the list of device revision for the hub2 managed device:

REQUEST

{
  "id": 1,
  "method": "exec",
  "params": [
    {
      "data": {
        "device": "hub2"
      },
      "url": "/deployment/get/device/revision"
    }
  ],
  "session": "{{session}}"
}

RESPONSE

{
  "id": 1,
  "result": [
    {
      "data": {
        "base_ver": 8,
        "revinfo": [
          {
            "comments": "",
            "error": "",
            "extra_info": "From package(default), Install to vdom(root)",
            "instime": "2020-03-13 10:49:41",
            "instusr": "admin",
            "modtime": "2020-03-13 10:49:41",
            "modusr": "admin",
            "revision": 8,
            "status": 4,
            "tag": "default"
          },
          {
            "comments": "objects",
            "error": "",
            "extra_info": "No package related, Install to vdom(root)",
            "instime": "2020-03-13 10:46:57",
            "instusr": "ips-admin-001",
            "modtime": "2020-03-13 10:46:57",
            "modusr": "ips-admin-001",
            "revision": 7,
            "status": 4,
            "tag": "objects"
          },
        ]
      }
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/deployment/get/device/revision"
    }
  ]
}

Note

The attribute base_ver indicate the revision ID of the device revision (or backup) created at the last installation, auto-update, retrieve or revert operation
We know that after such operation, device db is assumed in sync with real device configuration
It is possible to set the comments attribute when installing a Policy Package (see section How to install a Policy Package?) or triggering an Install Device Settings only (see section How to install device settings against devices?)

8.21.2. How to get a specific device revision for a particular device?#

Caught in #0392486.

To get the revision number 8 for the hub2 managed devices:

REQUEST

{
  "id": 1,
  "method": "exec",
  "params": [
    {
      "data": {
        "device": "hub2",
        "revision": 8
      },
      "url": "/deployment/checkout/revision"
    }
  ],
  "session": "{{session}}"
}

Warning

The attribute revision should hold an integer and not string.

Tip

Set the attribute revision with -1 if you just want to retrieve the latest device revision

RESPONSE

{
  "id": 1,
  "result": [
    {
      "data": {
        "content": "<device configuration here>",
        "revision": 8
      },
      "status": {
        "code": 0,
            "message": "OK"
      },
      "url": "/deployment/checkout/revision"
    }
  ]
}

8.21.3. How to get the current device database configuration for a particular device?#

Caught in #0392486.

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "device": "hub2"
      },
      "url": "/deployment/export/config"
    }
  ],
  "session": "NLMdLZCfYS2JP7nVov25EpJXDqcUMNdfG9TAWVq9kGjg7cTsrw+VtT9DHgNd/FQeDAiVf8Lq7D6DQZN18OQ+mw==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "content": "<device database configuration here>"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/deployment/export/config"
    }
  ]
}

8.21.4. How to revert to a specific device revision?#

Caught in #0563988.

We want to revert device foobar to its device revision #2:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "device": "foobar",
        "revision": 2
      },
      "url": "/deployment/revert"
    }
  ],
  "session": "1M8bMiXLk1er7XZWPuMq8sr95FNDYSR0gdfXI1px5tYMJ9nhKMf3AOQURl2orAVKqtopxLu4vA8SxR/5JSrlJFduakw984Kb",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/deployment/revert"
    }
  ]
}

8.21.5. How to import a device revision?#

Starting with FMG 7.0.3 (#0451960), it is possible to import a device revision.

REQUEST:

{
  "id": 3,
  "method": "exec",
  "params": [
    {
      "data": {
        "config": "#config-version=FGVMK6-7.00-FW-build157-000000:opm[...]",
        "device": "dut_fgt_02"
      },
      "url": "deployment/import/config"
    }
  ],
  "session": "SGiB3LWthXfVT3uCwWUZ4nlzfUaWoBiEJFnVlIvMKTQzU6DjK91jAnI1BXWwwRwBGrbyYWc0s+t8dUprk252jeX6p6RHLSKz"
}

Note

The config attribute is taking the cleartext version of the device revision file (no need to base64 encode it)

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": {
        "task": 3661
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "deployment/import/config"
    }
  ]
}

8.22. How to trigger a retrieve operation?#

8.22.1. Against a single device#

We trigger a retrieve operation for device fgt_dut in ADOM adom_dut:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "adom_dut",
        "flags": [
          "none"
        ],
        "reload-dev-member-list": [
          {
            "name": "fgt_dut"
          }
        ]
      },
      "url": "/dvm/cmd/reload/dev-list"
    }
  ],
  "session": "P5Yk9twDAS+yPdcC0gkDu+Rk1q3LpNzAQ5Bg4UsvcpbjdQLl2EuBETew1iuqOSncJufexxD69KyaWwP/gCZ8Gg==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/reload/dev-list"
    }
  ]
}

8.22.2. Against multiple devices#

We retrieve from device apac-12-fgt-01 to apac-24-fgt-01 in ADOM demo:

REQUEST:

{
  "id": 3,
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "demo",
        "flags": [
          "create_task",
          "nonblocking"
        ],
        "reload-dev-member-list": [
          {
            "name": "apac-12-fgt-01"
          },
          {
            "name": "apac-13-fgt-01"
          },
          {
            "name": "apac-14-fgt-01"
          },
          {
            "name": "apac-15-fgt-01"
          },
          {
            "name": "apac-16-fgt-01"
          },
          {
            "name": "apac-17-fgt-01"
          },
          {
            "name": "apac-18-fgt-01"
          },
          {
            "name": "apac-19-fgt-01"
          },
          {
            "name": "apac-20-fgt-01"
          },
          {
            "name": "apac-21-fgt-01"
          },
          {
            "name": "apac-22-fgt-01"
          },
          {
            "name": "apac-23-fgt-01"
          },
          {
            "name": "apac-24-fgt-01"
          }
        ]
      },
      "url": "/dvm/cmd/reload/dev-list"
    }
  ],
  "session": "nv7+Daewp8QrUEIqPGfS3HXL/j4pWYwJNnOHHfh8Z1yd9VeNv1gwIybuqwls9XGRSrybgP2l+i6tu5iWOrYpbw=="
}

Note

The create_task flag will create a task that will allow you to follow the progress of the operation from FortiManager GUI (under System Settings > Task Monitor)
The nonblocking flag will make this API call to return immediately. But you still have to maintain the API session alive otherwise you won’t be able to review the task information.

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": {
        "pid": 23223,
        "taskid": 600
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/reload/dev-list"
    }
  ]
}

8.23. Firmware upgrade#

Most of the information are available in #0375414.

To debug the upgrade firmware operations we can use following FortiManager CLI commands:

# diagnose debug application fdssvrd 255
# diagnose debug enable
# diagnose debug timestamp enable

8.23.1. How to get the upgrade path?#

This request gives the upgrade path for device hub1 in ADOM DEMO_008 for an upgrade to fortios firmware 6.4.1:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "DEMO_008",
        "device": [
          {
            "name": "hub1"
          }
        ],
        "flags": "f_preview",
        "image": {
          "release": "6.4.1"
        }
      },
      "url": "/um/image/upgrade"
    }
  ],
  "session": "OrsMw6koz4lftKerRBVgTNaRS4LpgckYTDPRLB75UNZ0MJgeakk0Toax6nvKSJYIRTyX2o3m9dTL52cxD487aA==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "upgrade_path": [
          {
            "name": "hub1",
            "oid": 662,
            "path": [
              "6.0.8-303",
              "6.2.4-1112",
              "6.4.1-1637"
            ]
          }
        ]
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/um/image/upgrade"
    }
  ]
}

With the introduction of the new Firmware Template (starting with FortiManager 7.0.0), we’re seeing this form of request for getting the upgrade path:

REQUEST:

{
  "id": 1,
  "method": "exec",
  "params": [
    {
      "data": {
        "devices": [
          {
            "image": "7.2.2",
            "name": "dut_fgt_02"
          }
        ],
        "flags": 16
      },
      "url": "/um/image/upgrade/ext"
    }
  ],
  "session": "ygNdJpGehf2e7W8RD4\/dYtUoGRHK5+vEwXBQ+GuyvSDvZXOYK1Loj6mkNTDzbHD35urOu0FKOy\/ThfYHPe4e4g=="
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "upgrade_path": [
          {
            "name": "dut_fgt_02",
            "oid": 183,
            "path": [
              "7.2.2-b1255-F"
            ]
          }
        ]
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "\/um\/image\/upgrade\/ext"
    }
  ]
}

Warning

Don’t use:
```
"flags": "f_preview"
```
but:
```
"flags": 16
```
when using the /um/image/upgrade/ext url.

Otherwise, it will trigger an upgrade instead of returning the upgrade path!

8.23.2. How to get list of available firmware for a specific platform?#

Caught in #0645390.

The FortiManager JSON RPC API URL /um/image/version/list will return all the available versions of firmwares for a certain platform.

It includes all the version in our FortiGuard servers (FDS servers) and all the versions from firmware files imported by FortiManager administrators.

REQUEST:

{
  "id": 1,
  "method": "exec",
  "params": [
    {
      "data": {
        "platform": "FortiGate-VM64-KVM",
        "product": "FGT"
      },
      "url": "um/image/version/list"
    }
  ],
  "session": "<session_id>"
}

Note

We can omit the attribute platform; in that case FortiManager will return FortiGate firmwares for all platforms!

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "status": "success",
        "version_list": [
          {
            "platform": "FortiGate-VM64-KVM",
            "product": "FGT",
            "versions": [
              {
                "type": "GA",
                "version": "5.6.2-b1486"
              },
              {
                "type": "GA",
                "version": "5.6.9-b1673"
              },
[...]
              {
                "image_path": "/var/fwm/image/FGVMK6_6.4.6_b1852_FORTINET.out",
                "type": "SPECIAL",
                "version": "6.4.6-b1852"
              },
              {
                "image_path": "/var/fwm/image/FGVMK6_6.4.6_b1851_FORTINET.out",
                "type": "SPECIAL",
                "version": "6.4.6-b1851"
              }
            ]
          }
        ]
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "um/image/version/list"
    }
  ]
}

8.23.3. How to get list of firmwares available on FortiManager drive?#

Caught in #0645390.

FortiManager JSON RPC API URL /um/image/list, will return all the firmware files present on FortiManager local disk.

Those firmware files could be the ones imported by the FortiManager administrators and or the ones downloaded from FortiGuard servers (FDS servers).

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
      },
      "url": "/um/image/list"
    }
  ],
  "session": "hMgb/g807bB+Oy94gxC4X2hjbGN+eug9wNFsik9fvgnPjNhvMlcsFoJWaRZ1dA6RC4xUDLwCoDKcCClxzF2Efg==",
  "verbose": 1
}

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": {
        "image_list": [
          {
            "build": "b0180",
            "date": "211019",
            "image_path": "/var/fwm/image/FMVM64_7.0.2_b180_FORTINET.out",
            "image_size": 239100126,
            "platform": "FortiManager-VM64",
            "product": "FMG",
            "version": "7.0.2-b0180"
          }
        ],
        "status": "success"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/um/image/list"
    }
  ]
}

Note

In the above case, FortiManager is only having a single firmware file on its local disk.

8.23.4. How to get list of firmwares available on FortiManager drive for a specific product?#

We can add the attribute system set with a product code like FMG or FGT.

REQUEST:

{
  "id": 3,
  "method": "exec",
  "params": [
    {
      "data": {
        "system": "FMG"
      },
      "url": "/um/image/list"
    }
  ],
  "session": "8/QnXQAREvjPWNqVEv2Qq/cvkLhpdZko8B14EYxTD/MMs8A3a66IFX6qTojKY9ojtPjOXBHIXv1pABZFHZ+zUQ=="
}

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": {
        "image_list": [
          {
            "build": "b0180",
            "date": "211019",
            "image_path": "/var/fwm/image/FMVM64_7.0.2_b180_FORTINET.out",
            "image_size": 239100126,
            "platform": "FortiManager-VM64",
            "product": "FMG",
            "version": "7.0.2-b0180"
          }
        ],
        "status": "success"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/um/image/list"
    }
  ]
}

When there’s no match, FortiManager returns all available firmwares:

REQUEST:

{
  "id": 3,
  "method": "exec",
  "params": [
    {
      "data": {
        "system": "FGT"
      },
      "url": "/um/image/list"
    }
  ],
  "session": "8/QnXQAREvjPWNqVEv2Qq/cvkLhpdZko8B14EYxTD/MMs8A3a66IFX6qTojKY9ojtPjOXBHIXv1pABZFHZ+zUQ=="
}

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": {
        "image_list": [
          {
            "build": "b0180",
            "date": "211019",
            "image_path": "/var/fwm/image/FMVM64_7.0.2_b180_FORTINET.out",
            "image_size": 239100126,
            "platform": "FortiManager-VM64",
            "product": "FMG",
            "version": "7.0.2-b0180"
          }
        ],
        "status": "success"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/um/image/list"
    }
  ]
}

8.23.5. How to upgrade a device?#

We upgrade device fgt_dut2, from ADOM adom_dut, to firmware 6.4.3:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "adom_dut",
        "create_task": "enable",
        "device": [
          {
            "name": "fgt_dut2"
          }
        ],
        "flags": [
          "none"
        ],
        "image": {
          "release": "6.4.3"
        }
      },
      "url": "/um/image/upgrade"
    }
  ],
  "session": "eTSSVMLIMkgNaAcCDWj4ah6oQPEYOvtZ3YB4Rz+0ZiI5L0dGfWt9uo+qB7rAmTmO5Ch1Ulstb4haJYc/Nn7hdA==",
  "verbose": 1
}

Note

flags attribute could be a combination (hence a list) of the following flags:

none
No specific action required. This is the default value if flags attribute is omitted.

f_boot_alt_partition
Boot from alternate partition after upgrade

f_skip_retrieve
FMG won’t retrieve the device configuration after upgrade

f_skip_multi_steps
FMG will skip the multi-step upgrade process

f_skip_fortiguard_img
FMG will let the device downloading the firmware from FortiGuard

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "taskid": 869
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/um/image/upgrade"
    }
  ]
}

With the introduction of the new Firmware Template (starting with FortiManager 7.0.0), we’re seeing this form of device upgrade:

REQUEST:

{
  "id": "6d87500b-2e7e-4a50-bd86-101f12842bb3",
  "method": "exec",
  "params": [
    {
      "data": {
        "create_task": "enable",
        "adom": "demo",
        "flags": 0,
        "devices": [
          {
            "name": "dut_fgt_2",
            "image":"7.0.1-b0157"
          }
        ]
      },
      "url": "um/image/upgrade/ext"
    }
  ]
}

Note

The attribute create_task will help in creating a task that could be used to monitor the progress of the upgrade process
The FortiManager JSON RPC API url attribute is different than the previous example.

RESPONSE:

{
  "id": "6d87500b-2e7e-4a50-bd86-101f12842bb3",
  "data": {
    "key": "adom3706_1648191562-670139803",
    "status": "success",
    "taskid": 4427
  },
  "status": {
    "code": 0,
    "message": "OK"
  },
  "url":"/um/image/upgrade/ext"
}

8.23.6. How to get the upgrade history?#

Caught in #0919855.

TBD: It should be possible to get upgrade history by using URL um/image/upgrade/report

8.23.7. How to get the Upgrade Report for managed devices?#

Caught in #0919211.

To get the upgrade reports for the fgt-741-001 in the dc_emea ADOM:

REQUEST

{
  "id": 3,
  "method": "get",
  "params": [
    {
      "data": {
        "adom": "dc_emea",
        "devices": [
          {
            "name": "fgt-741-001"
          }
        ],
        "flags": 0,
        "name": "fgt_to_740"
      },
      "url": "um/image/upgrade/report"
    }
  ],
  "session": "{{session}}",
  "verbose": 1
}

RESPONSE

{
  "id": 3,
  "result": [
    {
      "data": {
        "report": [
          [
            {
              "end-time": 1700776054,
              "name": "fgt-741-001",
              "oid": 175,
              "package-status": 0,
              "skip-path": 1,
              "start-time": 1700775638,
              "taskid": 9,
              "tasks": [
                {
                  "current_version": "7.4.1-b2463",
                  "health_check": [
                    {
                      "command": "get system status",
                      "result": "fgt-741-001 $  get system status\nVersion: FortiGate-VM64 v7.4.0,build2360,230509 (GA.F)\nSecurity Level: 1\nFirmware Signature: certified\nVirus-DB: 1.00000(2018-04-09 18:07)\nExtended DB: 1.00000(2018-04-09 18:07)\nExtreme DB: 1.00000(2018-04-09 18:07)\nAV AI/ML Model: 0.00000(2001-01-01 00:00)\nIPS-DB: 6.00741(2015-12-01 02:30)\nIPS-ETDB: 6.00741(2015-12-01 02:30)\nAPP-DB: 6.00741(2015-12-01 02:30)\nINDUSTRIAL-DB: 6.00741(2015-12-01 02:30)\nIPS Malicious URL Database: 1.00001(2015-01-01 01:01)\nIoT-Detect: 0.00000(2022-08-17 17:31)\nSerial-Number: FGVMMLTM22002647\nLicense Status: Valid\nLicense Expiration Date: 2026-05-25\nVM Resources: 1 CPU/4 allowed, 1994 MB RAM\nLog hard disk: Available\nHostname: jpforcioli-fgt-741-001\nPrivate Encryption: Disable\nOperation Mode: NAT\nCurrent virtual domain: root\nMax number of virtual domains: 7\nVirtual domains status: 1 in NAT mode, 0 in TP mode\nVirtual domain configuration: disable\nFIPS-CC mode: disable\nCurrent HA mode: standalone\nBranch point: 2360\nRelease Version Information: GA\nFortiOS x86-64: Yes\nSystem time: Thu Nov 23 22:46:55 2023\nLast reboot reason: warm reboot\n"
                    },
                    {
                      "command": "diagnose sys flash list",
                      "result": "fgt-741-001 $  diagnose sys flash list\nPartition  Image                                     TotalSize(KB)  Used(KB)  Use%  Active\n1          FGVM64-7.04-FW-build2360-230509                  237536    119052   50%  Yes   \n2          EXDB-1.00000                                    1707856    163436   10%  No    \nImage was built at May  9 2023 17:10:46 for b2360\n"
                    },
                    {
                      "command": "diagnose debug config-error-log read",
                      "result": "fgt-741-001 $  diagnose debug config-error-log read\n>>>  \"set\" \"gui-auto-upgrade-setup-warning\" \"disable\" @ global.system.global:command parse error (error -61)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-invalid-cert:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-empty-cert:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-manageable-empty-cert:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-no-api-gwy-matched:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-cant-find-real-srv:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-fqdn-dns-failed:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-ssl-bookmark-failed:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-no-policy-matched:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-matched-deny-policy:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-client-cert-revoked:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-denied-by-matched-tags:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-denied-no-matched-tags:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-no-dev-info:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.ztna-dev-is-offline:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.webproxy.casb-block:failed command (error -56)\n>>>  \"end\" @ global.system.replacemsg.utm.virpatchblk-html:failed command (error -56)\n>>>  \"set\" \"protocol\" \"https\" @ root.system.sdwan.health-check.Default_Office_365:failed command (error -160)\n>>>  \"set\" \"protocol\" \"https\" @ root.system.sdwan.health-check.Default_Google Search:failed command (error -160)\n>>>  \"set\" \"protocol\" \"https\" @ root.system.sdwan.health-check.Default_FortiGuard:failed command (error -160)\n>>>  \"config\" \"virtual-patch\" \"profile\" @ root:command parse error (error -61)\n>>>  \"set\" \"quic\" \"disable\" @ root.firewall.ssl-ssh-profile.deep-inspection.https:command parse error (error -61)\n>>>  \"set\" \"quic\" \"disable\" @ root.firewall.ssl-ssh-profile.deep-inspection.dot:command parse error (error -61)\n>>>  \"set\" \"quic\" \"disable\" @ root.firewall.ssl-ssh-profile.custom-deep-inspection.https:command parse error (error -61)\n>>>  \"set\" \"quic\" \"disable\" @ root.firewall.ssl-ssh-profile.custom-deep-inspection.dot:command parse error (error -61)\n>>>  \"set\" \"quic\" \"disable\" @ root.firewall.ssl-ssh-profile.no-inspection.https:command parse error (error -61)\n>>>  \"set\" \"quic\" \"disable\" @ root.firewall.ssl-ssh-profile.no-inspection.dot:command parse error (error -61)\n>>>  \"set\" \"quic\" \"disable\" @ root.firewall.ssl-ssh-profile.certificate-inspection.https:command parse error (error -61)\n>>>  \"set\" \"quic\" \"disable\" @ root.firewall.ssl-ssh-profile.certificate-inspection.dot:command parse error (error -61)\n>>>  \"config\" \"casb\" \"saas-application\" @ root:command parse error (error -61)\n>>>  \"config\" \"casb\" \"user-activity\" @ root:command parse error (error -61)\n>>>  \"config\" \"switch-controller\" \"ptp\" \"profile\" @ root:command parse error (error -61)\n>>>  \"config\" \"switch-controller\" \"ptp\" \"interface-policy\" @ root:command parse error (error -61)\n"
                    },
                    {
                      "command": "diagnose hardware sysinfo memory",
                      "result": "fgt-741-001 $  diagnose hardware sysinfo memory\nMemTotal:        2042176 kB\nMemFree:         1066608 kB\nMemAvailable:    1047988 kB\nBuffers:             160 kB\nCached:           388312 kB\nSwapCached:            0 kB\nActive:           359264 kB\nInactive:          60800 kB\nActive(anon):     352908 kB\nInactive(anon):    45304 kB\nActive(file):       6356 kB\nInactive(file):    15496 kB\nUnevictable:      194172 kB\nMlocked:               0 kB\nSwapTotal:             0 kB\nSwapFree:              0 kB\nDirty:                 0 kB\nWriteback:             0 kB\nAnonPages:        225808 kB\nMapped:           125624 kB\nShmem:            177536 kB\nSlab:             136612 kB\nSReclaimable:       8460 kB\nSUnreclaim:       128152 kB\nKernelStack:        3340 kB\nPageTables:        20560 kB\nNFS_Unstable:          0 kB\nBounce:                0 kB\nWritebackTmp:          0 kB\nCommitLimit:     1021088 kB\nCommitted_AS:   15306520 kB\nVmallocTotal:   34359738367 kB\nVmallocUsed:           0 kB\nVmallocChunk:          0 kB\nPercpu:              312 kB\nAnonHugePages:         0 kB\nShmemHugePages:        0 kB\nShmemPmdMapped:        0 kB\nCmaTotal:              0 kB\nCmaFree:               0 kB\nHugePages_Total:       0\nHugePages_Free:        0\nHugePages_Rsvd:        0\nHugePages_Surp:        0\nHugepagesize:       2048 kB\nHugetlb:               0 kB\nDirectMap4k:       22400 kB\nDirectMap2M:     2074624 kB\nDirectMap1G:           0 kB\n"
                    },
                    {
                      "command": "diagnose debug crash read",
                      "result": "fgt-741-001 $  diagnose debug crash read\n1: 2023-11-02 14:54:37 from=license sn=FGVMEVETVZR-YYF2 msg=Server replied error code:0\n2: 2023-11-02 14:54:41 the killed daemon is /bin/sflowd: status=0x0\n3: 2023-11-20 22:09:23 the killed daemon is /bin/sflowd: status=0x0\n4: 2023-11-20 22:11:14 the killed daemon is /bin/dhcpcd: status=0x0\n5: 2023-11-20 22:11:24 the killed daemon is /bin/sshd: status=0x100\n6: 2023-11-20 22:14:13 Interface port1 is brought down. process_id=2776, process_name=\"newcli\"\n7: 2023-11-20 22:14:13 Interface port2 is brought down. process_id=2776, process_name=\"newcli\"\n8: 2023-11-20 22:14:13 Interface port3 is brought down. process_id=2776, process_name=\"newcli\"\n9: 2023-11-20 22:14:13 Interface port4 is brought down. process_id=2776, process_name=\"newcli\"\n10: 2023-11-20 22:14:13 Interface port5 is brought down. process_id=2776, process_name=\"newcli\"\n11: 2023-11-20 22:14:13 Interface port6 is brought down. process_id=2776, process_name=\"newcli\"\n12: 2023-11-20 22:14:13 Interface port7 is brought down. process_id=2776, process_name=\"newcli\"\n13: 2023-11-20 22:14:13 Interface port8 is brought down. process_id=2776, process_name=\"newcli\"\n14: 2023-11-20 22:14:13 Interface port9 is brought down. process_id=2776, process_name=\"newcli\"\n15: 2023-11-20 22:14:13 Interface port10 is brought down. process_id=2776, process_name=\"newcli\"\n16: 2023-11-20 22:15:46 from=license sn=FGVMMLTM22002647 msg=License is in grace period\n17: 2023-11-20 22:15:46 the killed daemon is /bin/sflowd: status=0x0\n18: 2023-11-20 22:15:46 the killed daemon is /bin/sshd: status=0x100\n19: 2023-11-20 22:16:24 from=license sn=FGVMMLTM22002647 msg=License status changed to VALID\n20: 2023-11-21 07:21:51 the killed daemon is /bin/sflowd: status=0x0\n21: 2023-11-21 07:44:07 the killed daemon is /bin/csfd: status=0x0\n22: 2023-11-21 07:44:07 the killed daemon is /bin/eap_proxy: status=0x0\n23: 2023-11-23 17:46:53 Interface port1 is brought down. process_id=8008, process_name=\"smit\"\n24: 2023-11-23 17:46:53 Interface port2 is brought down. process_id=8008, process_name=\"smit\"\n25: 2023-11-23 17:46:53 Interface port3 is brought down. process_id=8008, process_name=\"smit\"\n26: 2023-11-23 17:46:53 Interface port4 is brought down. process_id=8008, process_name=\"smit\"\n27: 2023-11-23 17:46:53 Interface port5 is brought down. process_id=8008, process_name=\"smit\"\n28: 2023-11-23 17:46:53 Interface port6 is brought down. process_id=8008, process_name=\"smit\"\n29: 2023-11-23 17:46:53 Interface port7 is brought down. process_id=8008, process_name=\"smit\"\n30: 2023-11-23 17:46:53 Interface port8 is brought down. process_id=8008, process_name=\"smit\"\n31: 2023-11-23 17:46:53 Interface port9 is brought down. process_id=8008, process_name=\"smit\"\n32: 2023-11-23 17:46:53 Interface port10 is brought down. process_id=8008, process_name=\"smit\"\n33: 2023-11-23 18:19:25 the killed daemon is /bin/sflowd: status=0x0\n34: 2023-11-23 19:21:07 the killed daemon is /bin/sflowd: status=0x0\n35: 2023-11-23 22:41:12 Interface port1 is brought down. process_id=3071, process_name=\"httpsd\"\n36: 2023-11-23 22:41:12 Interface port2 is brought down. process_id=3071, process_name=\"httpsd\"\n37: 2023-11-23 22:41:12 Interface port3 is brought down. process_id=3071, process_name=\"httpsd\"\n38: 2023-11-23 22:41:12 Interface port4 is brought down. process_id=3071, process_name=\"httpsd\"\n39: 2023-11-23 22:41:12 Interface port5 is brought down. process_id=3071, process_name=\"httpsd\"\n40: 2023-11-23 22:41:12 Interface port6 is brought down. process_id=3071, process_name=\"httpsd\"\n41: 2023-11-23 22:41:12 Interface port7 is brought down. process_id=3071, process_name=\"httpsd\"\n42: 2023-11-23 22:41:12 Interface port8 is brought down. process_id=3071, process_name=\"httpsd\"\n43: 2023-11-23 22:41:12 Interface port9 is brought down. process_id=3071, process_name=\"httpsd\"\n44: 2023-11-23 22:41:12 Interface port10 is brought down. process_id=3071, process_name=\"httpsd\"\n45: 2023-11-23 22:42:28 the killed daemon is /bin/telnetd: status=0xf\n46: 2023-11-23 22:42:28 the killed daemon is /bin/sflowd: status=0x0\n47: 2023-11-23 22:44:14 the killed daemon is /bin/csfd: status=0x0\n48: 2023-11-23 22:44:14 the killed daemon is /bin/cloudapid: status=0x0\n49: 2023-11-23 22:44:14 the killed daemon is /bin/fsvrd: status=0x0\n50: 2023-11-23 22:44:14 the killed daemon is /bin/uploadd: status=0x0\n51: 2023-11-23 22:44:14 the killed daemon is /bin/fnbamd: status=0x0\n52: 2023-11-23 22:44:14 the killed daemon is /bin/forticron: status=0x0\n53: 2023-11-23 22:44:14 the killed daemon is /bin/snmpd: status=0x0\n54: 2023-11-23 22:44:14 the killed daemon is /bin/eap_proxy: status=0x0\n55: 2023-11-23 22:44:14 the killed daemon is /bin/quard: status=0xf\n56: 2023-11-23 22:44:14 the killed daemon is /bin/autod: status=0x0\n57: 2023-11-23 22:44:14 the killed daemon is /bin/authd: status=0x0\n58: 2023-11-23 22:44:14 the killed daemon is /bin/radvd: status=0x0\n59: 2023-11-23 22:44:14 the killed daemon is /bin/merged_daemons: status=0x0\n60: 2023-11-23 22:44:14 the killed daemon is /bin/clearpass: status=0x0\n61: 2023-11-23 22:44:14 the killed daemon is /bin/ipsmonitor: status=0x0\n62: 2023-11-23 22:44:14 the killed daemon is /bin/foauthd: status=0x0\n63: 2023-11-23 22:44:14 the killed daemon is /bin/fas: status=0x0\n64: 2023-11-23 22:44:14 the killed daemon is /bin/updated: status=0x0\n65: 2023-11-23 22:44:14 the killed daemon is /bin/lldptx: status=0xf\n66: 2023-11-23 22:44:14 the killed daemon is /bin/ntpd: status=0xf\n67: 2023-11-23 22:44:14 the killed daemon is /bin/wad: status=0x0\n68: 2023-11-23 22:44:17 the killed daemon is /bin/fgfmd: status=0x0\n69: 2023-11-23 22:45:51 the killed daemon is /bin/sflowd: status=0x0\nCrash log interval is 3600 seconds\nMax crash log line number: 16384\n"
                    }
                  ],
                  "package-status": 0,
                  "platform": "FortiGate-VM64",
                  "product": 1,
                  "profile_name": "fgt_to_740",
                  "result": 0,
                  "serial": "FGVMMLTM22002647",
                  "sub_tasks": [
                    {
                      "config": {
                        "change": 1,
                        "diff": "config system global\nunset gui-auto-upgrade-setup-warning\nend\nconfig firewall ssl-ssh-profile\nedit \"custom-deep-inspection\"\nconfig https\nunset quic\nend\nconfig dot\nunset quic\nend\nnext\nend\nconfig system sdwan\nconfig health-check\nedit \"Default_FortiGuard\"\nunset protocol\nnext\nedit \"Default_Google Search\"\nunset protocol\nnext\nedit \"Default_Office_365\"\nunset protocol\nnext\nend\nend\n"
                      },
                      "end_revision": 2,
                      "end_time": 1700775993,
                      "end_version": "7.4.0-b2360",
                      "result": 0,
                      "retrieve_end_time": 1700775993,
                      "retrieve_start_time": 1700775952,
                      "start_revision": 1,
                      "start_time": 1700775669,
                      "start_version": "7.4.1-b2463",
                      "task_line": "fgt-741-001(7.4.1-b2463->7.4.0-b2360)"
                    }
                  ],
                  "target_version": "7.4.0-b2360",
                  "upgrade_path": [
                    "7.4.0-b2360"
                  ]
                }
              ]
            }
          ]
        ]
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "um/image/upgrade/report"
    }
  ]
}

8.24. Certificates#

8.24.1. How to upload a certificate?#

We need:

A certificate file in PEM format

It should look something like:

A password protected key file in PEM format

It should look something like:

The password used to encrypt the key file

We can now upload those element in a managed device branch11 using the following FMG JSON RPC API call:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "add",
  "params": [
    {
      "data": {
        "certificate": "-----BEGIN CERTIFICATE-----\nMIIDRjCCA[...]",
        "name": "aforcioli_crt",
        "password": "fortinet",
        "private-key": "-----BEGIN ENCRYPTED PRIVATE KEY-----\[...]"
      },
      "url": "/pm/config/device/branch11/vdom/root/vpn/certificate/local"
    }
  ],
  "session": "V2BYiSk9ErysCNisPGozVwtO/8Olp72vvnTcUIs5zHlydxKIioFC3tUs6KqyLBZ30pFShPfCXBBvhGg6POPCGKJtpEQyEjuD",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "name": "aforcioli_crt"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/pm/config/device/branch11/vdom/root/vpn/certificate/local"
    }
  ]
}

8.24.2. How to show certificate details?#

It’s a new feature from FMG 6.2.4/6.4.1 (#629877).

Now we can get either in the normal or global ADOM the following certificate types:

pm/config/device/<device>/vdom/<vdom>/vpn/certificate/ca
pm/config/device/<device>/vdom/<vdom>/vpn/certificate/local
pm/config/device/<device>/vdom/<vdom>/vpn/certificate/remote
pm/config/device/<device>/global/vpn/certificate/ca
pm/config/device/<device>/global/vpn/certificate/local
pm/config/device/<device>/global/vpn/certificate/remote

And FMG will return something like:

[...]
"_certinfo": {

  "is_ca": 1,
  "issuer": "O = Fortinet Ltd., CN = Fortinet",
  "negsn": 0,
  "serial": "37:38:42:39:38:38:39:37:44:34:39:33:45:31:42:43:44:30:31:31:32:34:38:37:31:42:41:37:46:41:32:39",
  "subject": "O = Fortinet Ltd., CN = Fortinet",
  "validfrom": "2020-04-20 23:09:46  GMT",
  "validto": "2030-04-25 23:09:46  GMT",
  "version": 3
},
[...]

8.25. Device Monitoring#

8.25.1. Generate an IP Pool Mapping#

Caught in #0604135.

To get the IP Pool Mapping for some devices:

REQUEST:

{
  "id": 1,
  "method": "exec",
  "params": [
    {
      "url": "dvmdb/get/ippool-mapping",
      "data": {
        "time": "2019-12-30 01:01:01",
        "devices": [
          {
            "name": "FGT1",
            "vdom": "test2",
          },
          {
            "name": "FGT2",
            "vdom": "",
          },
        ]
      }
    }
  ]
}

If no devices are specified then mapping for all devices will be generated

REQUEST:

{
  "id": 1,
  "method": "exec",
  "params": [
    {
      "url":"dvmdb/get/ippool-mapping",
      "data": {
        "time": "2019-12-30 01:01:01",
        "devices": []
      }
    }
  ]
}

Time must be in the YYYY-MM-DD HH:MM:SS format, and all generated files will be placed in /var/tmp/port_mapping/ and each file will follow the format:

If VDOM specified: <device name>_<vdom name>_mapping.txt

No VDOM specified: <device name>_mapping.txt

8.25.2. How to get kernel routes from a managed fortigate device?#

Following request will encapsulate the FOS REST API call:

GET https://hub1/api/v2/monitor/router/ipv4/select?&vdom=root&count=-1

in a FMG JSON API request using the sys/proxy/json url:

REQUEST:

{
  "id": "10032dca-4fb3-4f29-bd73-308220e1e75f",
  "method": "exec",
  "params": [
    {
      "data": {
        "action": "get",
        "resource":
        "/api/v2/monitor/router/ipv4/select?&vdom=root&count=-1",
        "target": [
          "adom/DEMO/device/hub1"
        ]
      },
      "url": "sys/proxy/json"
    }
  ],
  "session": 55422
}

Note

Note about the HTTP parameters passed in the FOS REST API call:

vdom=root: we want the kernel routes from VDOM root
count=-1: we want all kernel routes

We will get the following response:

{
  "id": "10032dca-4fb3-4f29-bd73-308220e1e75f",
  "result": [
    {
      "data": [
        {
          "response": {
            "action": "select",
            "build": 1579,
            "http_method": "GET",
            "name": "ipv4",
            "path": "router",
            "results": [
              {
                "distance": 10,
                "gateway": "10.210.35.254",
                "interface": "port1",
                "ip_mask": "0.0.0.0/0",
                "ip_version": 4,
                "metric": 0,
                "type": "static"
              },
              {
                "distance": 0,
                "gateway": "0.0.0.0",
                "interface": "port2",
                "ip_mask": "10.101.0.0/24",
                "ip_version": 4,
                "metric": 0,
                "type": "connect"
              },
              {
                "distance": 0,
                "gateway": "0.0.0.0",
                "interface": "port1",
                "ip_mask": "10.210.34.0/23",
                "ip_version": 4,
                "metric": 0,
                "type": "connect"
              }
            ],
            "serial": "FGVMULREDACTED09",
            "status": "success",
            "vdom": "root",
            "version": "v6.4.0"
          },
          "status": {
            "code": 0,
            "message": "OK"
          },
          "target": "hub1"
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "sys/proxy/json"
    }
  ]
}

Even if this is not the case in this output, you will get all kind of kernel routes here (static, connected, bgp, ospf, etc.).

8.25.3. How to get IPSEC tunnel statistics?#

REQUEST:

{
  "id": "4150e0fd-456b-45a0-8fcf-2a52e532dd5a",
  "method": "exec",
  "params": [
    {
      "data": {
        "action": "get",
        "resource": "/api/v2/monitor/vpn/ipsec/select?&global=1",
        "target": [
          "adom/demo/device/fgt_01_1"
        ],
        "timeout": 20
      },
      "url": "sys/proxy/json"
    }
  ],
  "session": 49128
}

It is possible to target multiple device or device groups from different ADOMs:

"target": [
  "adom/demo1/group/emea_branches",
  "adom/demo2/group/mssp_pool"
  "adom/demo3/device/device_001,"
  "adom/demo4/device/device_002,"
  "adom/demo5/group/All_FortiGate"
]

8.26. How to get an install preview?#

It’s a two steps process:

We have to ask for the preview generation
We need to collect the preview output
We have to ask for the preview generation

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "customer_001",
        "device": "dut_fgt2",
        "flags": [
          "none"
        ],
        "vdoms": [
          "root"
        ]
      },
      "url": "/securityconsole/install/preview"
    }
  ],
  "session": "F2CA7K6wHYbQngcYWruI1xrAPBMWWdK2V9BgQ1F4eGPyfhscBuFtSLs+wVxNF5Rnbg4B2D37KpJ3mEXVhfn3+A==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "task": 71
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/securityconsole/install/preview"
    }
  ]
}

Here you have to track the progress of the returned task id 71 (you can get /task/task/71).

Once the task is completed, you can proceed with step 2.

We need to collect the preview output

Note

Here FortiManager will report pending changes coming from corresponding device’s Device DB. If we want to get all pending changes (ie. the ones from the device’s Device DB along with the ones in the ADOM DB like the objects & policies) we need to trigger a policy package install preview (See How to trigger an install preview?).

REQUEST

{
  "id": 1,
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "customer_001",
        "device": "dut_fgt2"
      },
      "url": "/securityconsole/preview/result"
    }
  ],
  "session": "{{session}}"
}

RESPONSE

{
  "id": 1,
  "result": [
    {
      "data": {
        "message": "config system dhcp server\n    edit 1\n        set status disable\n        set dns-service default\n        set ntp-service default\n        set default-gateway 172.16.2.102\n        set netmask 255.255.255.0\n        set interface \"port3\"\n        config ip-range\n            edit 1\n                set start-ip 172.16.2.1\n                set end-ip 172.16.2.101\n            next\n            edit 2\n                set start-ip 172.16.2.103\n                set end-ip 172.16.2.254\n            next\n        end\n        set timezone-option default\n    next\nend\n"
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/securityconsole/preview/result"
    }
  ]
}

8.27. How to get the platform_id, the platform_name and the ostype from a Serial Number?#

Caught in #0310534 & #0380729.

The get the platform_id, the platform_name and the ostype information for serial number FGT60F0000000001:

REQUEST:

{
  "id": 1,
  "method": "get",
  "params": [
    {
      "url": "/pm/config/adom/root/_data/dvm/device/abbrev/FGT60F000000001"
    }
  ],
  "session": "NjrWJdyknKad+lyg22972u4hQqQLdoo5tqckwtvTFOhg8hyyx2Nmn+1JK0LxfSlRuvyH5gksFqOmmZo5iP61YYy6zamVQ7bQ",
  "verbose": 1
}

Note

You could use any ADOM names.

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": [
        {
          "ostype": "FortiGate",
          "platform_id": 19,
          "platform_name": "FortiGate-60F"
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/pm/config/adom/root/_data/dvm/device/abbrev/FGT60F000000001"
    }
  ]
}

In fact, it even works when using the 6 chars serial number prefix. For instance to get the same information for a FortiWifi-60F whose serial number prefix is FWF60F:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "get",
  "params": [
    {
      "url": "/pm/config/adom/root/_data/dvm/device/abbrev/FWF60F"
    }
  ],
  "session": "9SN/bVFfPl4/1osdflZBcCDS36GchGMXPsip75oPlPBYLJoXzcpAWSzu6ENSTD1t/uj6qdtTJrut7HiTmdJlM0oeYAg+sVAv",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": [
        {
          "ostype": "FortiGate",
          "platform_id": 165,
          "platform_name": "FortiWiFi-60F"
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/pm/config/adom/root/_data/dvm/device/abbrev/FWF60F"
    }
  ]
}

And it works for any supported products. For instance to get the same information for a FortiADC-200D with serial number prefix FAD2HD:

REQUEST:

{
  "id": 3,
  "method": "get",
  "params": [
    {
      "url": "/pm/config/adom/root/_data/dvm/device/abbrev/FAD2HD"
    }
  ],
  "session": "tktYWsKRLlFju8ELx/wIaiY+/f6ZIvZrbNcb3HogTtXQWYCq361STNmIr+s2pkRhu4/u5tNK1bXatrDjVlrQafr5RvN3us9U",
  "verbose": 1
}

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": [
        {
          "ostype": "FortiADC",
          "platform_id": 2,
          "platform_name": "FortiADC-200D"
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/pm/config/adom/root/_data/dvm/device/abbrev/FAD2HD"
    }
  ]
}

8.28. How to get all supported devices?#

Caught in #0310534 & #0380729.

To get all supported FortiADC models (along with their platform_id, platform_name and ostype):

REQUEST:

{
  "id": 3,
  "method": "get",
  "params": [
    {
      "ostype": "FortiADC",
      "url": "/pm/config/adom/root/_data/dvm/device/model"
    }
  ],
  "session": "3fqUh3NhPfG19woQsrjOq29iIikXMrrSd6PjLMGukjdGZTOln5ZZL+e0KW7mtVBEsGrA3R31/9L5Bm4id/qdZ7UuI9BZdGN8",
  "verbose": 1
}

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": [
        {
          "ostype": "FortiADC",
          "platform_id": 0,
          "platform_name": "FortiADC-100F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 1,
          "platform_name": "FortiADC-120F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 2,
          "platform_name": "FortiADC-200D"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 3,
          "platform_name": "FortiADC-200F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 4,
          "platform_name": "FortiADC-220F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 5,
          "platform_name": "FortiADC-300D"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 6,
          "platform_name": "FortiADC-300F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 7,
          "platform_name": "FortiADC-400D"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 8,
          "platform_name": "FortiADC-400F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 9,
          "platform_name": "FortiADC-700D"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 10,
          "platform_name": "FortiADC-1000F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 11,
          "platform_name": "FortiADC-1200F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 12,
          "platform_name": "FortiADC-1500D"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 13,
          "platform_name": "FortiADC-2000D"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 14,
          "platform_name": "FortiADC-2000F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 15,
          "platform_name": "FortiADC-2200F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 16,
          "platform_name": "FortiADC-4000D"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 17,
          "platform_name": "FortiADC-4000F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 18,
          "platform_name": "FortiADC-4200F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 19,
          "platform_name": "FortiADC-5000F"
        },
        {
          "ostype": "FortiADC",
          "platform_id": 20,
          "platform_name": "FortiADC-VM"
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/pm/config/adom/root/_data/dvm/device/model"
    }
  ]
}

Note

supported devices means: FortiManager can managed them (like a FortiGate, FortiSwitch, FortiAP, FortiExtender, FortiProxy, etc.) and/or serve them updates (like a FortiIsolator)
If you don’t know which value to use for the ostype parameter, just omit it; FortiManager will return the complete list of supported devices.

8.29. Cluster#

8.29.1. Model HA Cluster#

8.29.1.1. How to create a model ha cluster?#

We add a model ha cluster site_0502 in adom demo.

It is composed of two FortiGate-60E devices: FGT60E0000005021 and FGT60E0000005022.

REQUEST

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "demo",
        "device": {
          "adm_pass": "m",
          "adm_usr": "admin",
          "desc": "Remote site #502",
          "device action": "add_model",
          "extra commands": [
            {
              "method": "update",
              "params": [
                {
                  "data": {
                    "hbdev": [
                      "dmz",
                      0
                    ],
                    "monitor": [
                      "wan1",
                      "wan2"
                    ],
                    "password": "site_0502"
                  },
                  "url": "/pm/config/device/%s/global/system/ha"
                }
              ]
            }
          ],
          "ha_group_name": "site_0502",
          "ha_group_id": 1,
          "ha_mode": "AP",
          "ha_slave": [
            {
              "idx": 0,
              "name": "site_0502",
              "prio": 200,
              "role": "master",
              "sn": "FGT60E0000005021"
            },
            {
              "idx": 1,
              "name": "site_0502-1",
              "prio": 100,
              "role": "slave",
              "sn": "FGT60E0000005022"
            }
          ],
          "ip": "172.11.2.253",
          "mgmt_mode": "fmgfaz",
          "mr": 4,
          "name": "site_0502",
          "os_type": "fos",
          "os_ver": "6.0",
          "platform_str": "FortiGate-60E",
          "sn": "FGT60E0000005021"
        },
        "flags": [
          "create_task"
        ]
      },
      "url": "/dvm/cmd/add/device"
    }
  ],
  "session": "r4ran218Tl/Jh94Q5L/aqCGJxuXUyaw0mODv7tCNdNrr3CR2qPwVGm5cvgiznmsJptm1QQ5SLoMAhNDKKqR2pMP2yDvuIM1z",
  "verbose": 1
}

Note

Prior to FMG 6.4.11, 7.0.7 and 7.2.2, naming convention used in the ha_slave list was flexible: For instance, FortiManager GUI was using the following naming convention: if main device name was foo then the cluster member names in the ha_slave list were foo-0 (for the primary) and foo-1, foo-2, etc. for the secondary members.
Starting with FMG 6.4.11, 7.0.7 and 7.2.2 (see #0800191), device name has to be equal to the primary member name in the ha_slave list (see the above example)

Warning

The prio attribute in the ha_slave list has to be set With an integer!

RESPONSE

{
  "id": 1,
  "result": [
    {
      "data": {
        "device": {
          "adm_pass": "m",
          "adm_usr": "admin",
          "beta": -1,
          "branch_pt": 1768,
          "build": 1768,
          "conn_mode": 1,
          "desc": "Remote site #502",
          "dev_status": 1,
          "flags": 262144,
          "ha_group_name": "site_0502",
          "ha_mode": 1,
          "hostname": "FGT60E0000005021",
          "ip": "172.11.2.253",
          "maxvdom": 10,
          "mgmt_id": 1720333531,
          "mgmt_mode": 3,
          "mr": 4,
          "name": "site_0502",
          "oid": 4562,
          "os_type": 0,
          "os_ver": 6,
          "patch": -1,
          "platform_id": 15,
          "platform_str": "FortiGate-60E",
          "sn": "FGT60E0000005021",
          "source": 1,
          "tab_status": "<unknown>",
          "version": 600
        },
        "taskid": 2528
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/add/device"
    }
  ]
}

8.29.1.2. How to create a Model HA Cluster with new interfaces?#

This is for this special case where the cluster we want to declare is made of FortiGate VMs: FortiManager is creating by default a model ha cluster with a single port1 interface. It means we have to create the missing interfaces and complete the HA setting (like heartbeat & monitored interfaces) in a second stage.

The following request is creating a model ha cluster with the missing interfaces and heartbeat/monitored interfaces:

REQUEST:

{
  "id": 10,
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "demo",
        "device": {
          "adm_usr": "admin",
          "desc": "Added with fortinet.fortimanager ansible collection",
          "device action": "add_model",
          "extra commands": [
            {
              "method": "add",
              "params": [
                {
                  "data": [
                    {
                      "name": "port2",
                      "type": "physical",
                      "vdom": "root"
                    },
                    {
                      "name": "port3",
                      "type": "physical",
                      "vdom": "root"
                    },
                    {
                      "name": "port4",
                      "type": "physical",
                      "vdom": "root"
                    }
                  ],
                  "url": "pm/config/device/%s/global/system/interface"
                }
              ]
            },
            {
              "method": "update",
              "params": [
                {
                  "data": {
                    "hbdev": [
                      "port3",
                      0
                    ],
                    "monitor": [
                      "port1",
                      "port2"
                    ],
                    "password": "fortinet"
                  },
                  "url": "/pm/config/device/%s/global/system/ha"
                }
              ]
            }
          ],
          "ha_group_name": "fgt_cluster_03",
          "ha_group_id": 3,
          "ha_mode": "AP",
          "ha_slave": [
            {
              "idx": 0,
              "name": "fgt_cluster_03-1",
              "prio": "200",
              "role": "master",
              "sn": "FGVMUL3000000001"
            },
            {
              "idx": 1,
              "name": "fgt_cluster_03-2",
              "prio": "100",
              "role": "slave",
              "sn": "FGVMUL3000000002"
            }
          ],
          "meta fields": {
            "site_id": "3"
          },
          "mgmt_mode": "fmg",
          "mr": 0,
          "name": "fgt_cluster_03",
          "os_type": "fos",
          "os_ver": "7.0",
          "platform_str": "FortiGate-VM64-KVM",
          "prefer_img_ver": "7.0.2-b234",
          "sn": "FGVMUL3000000001"
        },
        "flags": [
          "create_task"
        ],
        "groups": [
          {
            "name": "branches"
          }
        ]
      },
      "target start": 2,
      "url": "/dvm/cmd/add/device"
    }
  ],
  "session": "unYzYo11OjVnSxSSr+kZXgKLh2ix+ky2lLG4bw6s0XKdBvY+nZDR+ofO6I/jBEM9mswt4p1/nXtHVS2Rp3N+xw==",
  "src": "192.168.244.1",
  "verbose": 1
}

8.29.1.3. How to add a Model HA Cluster with `session-pick` up and `override` enabled?#

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "{{adom}}",
        "device": {
          "adm_pass": "fortinet",
          "adm_usr": "admin",
          "desc": "Remote site #502",
          "device action": "add_model",
          "extra commands": [
            {
              "method": "update",
              "params": [
                {
                  "data": {
                    "session-pickup": "enable",
                    "override": "enable",
                    "hbdev": [
                      "dmz",
                      0
                    ],
                    "monitor": [
                      "wan1",
                      "wan2"
                    ],
                    "password": "site_0502"
                  },
                  "url": "/pm/config/device/%s/global/system/ha"
                }
              ]
            }
          ],
          "ha_group_name": "site_0502",
          "ha_group_id": 1,
          "ha_mode": "AP",
          "ha_slave": [
            {
              "idx": 0,
              "name": "site_0502-0",
              "prio": 200,
              "role": "master",
              "sn": "FGT60F0000005021"
            },
            {
              "idx": 1,
              "name": "site_0502-1",
              "prio": 100,
              "role": "slave",
              "sn": "FGT60F0000005022"
            }
          ],
          "ip": "172.11.2.253",
          "mgmt_mode": "fmgfaz",
          "mr": 0,
          "name": "site_0502",
          "os_type": "fos",
          "os_ver": "7.0",
          "platform_str": "FortiGate-60F",
          "sn": "FGT60F0000005021"
        },
        "flags": [
          "create_task"
        ]
      },
      "url": "/dvm/cmd/add/device"
    }
  ],
  "session": "{{session_id}}",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "device": {
          "adm_pass": "fortinet",
          "adm_usr": "admin",
          "beta": -1,
          "branch_pt": 231,
          "build": 231,
          "conn_mode": 1,
          "desc": "Remote site #502",
          "dev_status": 1,
          "flags": 262144,
          "ha_group_name": "site_0502",
          "ha_mode": 1,
          "hostname": "FGT60F0000005021",
          "ip": "172.11.2.253",
          "maxvdom": 10,
          "mgmt_id": 129296930,
          "mgmt_mode": 3,
          "mr": 0,
          "name": "site_0502",
          "oid": 300,
          "os_type": 0,
          "os_ver": 7,
          "patch": -1,
          "platform_id": 19,
          "platform_str": "FortiGate-60F",
          "sn": "FGT60F0000005021",
          "source": 1,
          "tab_status": "<unknown>",
          "version": 700
        },
        "taskid": 9
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/add/device"
    }
  ]
}

8.29.1.4. How to add a Model HA Cluster with Device Blueprint and Metadata?#

REQUEST

Click to see the request

{
    "method": "exec",
    "params": [
        {
            "url": "/dvm/cmd/add/device",
            "data": {
                "adom": "production",
                "flags": [
                    "create_task"
                ],
                "device": {
                    "name": "site_2",
                    "device action": "add_model",
                    "device blueprint": "sites_BRANCH_DBP",
                    "sn": "FGVM01TM23005395",
                    "adm_usr": "admin",
                    "desc": "Touched by fortinet.fortimanager galaxy collection",
                    "mgmt_mode": "fmg",
                    "os_ver": "7.0",
                    "mr": 4,
                    "os_type": "fos",
                    "platform_str": "FortiGate-VM64-KVM",
                    "ha_group_name": "site_2",
                    "ha_group_id": 2,
                    "ha_mode": "AP",
                    "ha_slave": [
                        {
                            "idx": 0,
                            "name": "site_2",
                            "prio": 200,
                            "role": "master",
                            "sn": "FGVM01TM23005395"
                        },
                        {
                            "idx": 1,
                            "name": "site_2-1",
                            "prio": 100,
                            "role": "slave",
                            "sn": "FGVM01TM23005396"
                        }
                    ],
                    "extra commands": [
                        {
                            "method": "set",
                            "params": [
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2",
                                            "vdom": "global"
                                        },
                                        "value": "2"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/branch_id/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2",
                                            "vdom": "global"
                                        },
                                        "value": "branch"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/device_type/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2",
                                            "vdom": "global"
                                        },
                                        "value": "12"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/fpoc_instance_id/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2",
                                            "vdom": "global"
                                        },
                                        "value": "40.416775"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/latitude/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2",
                                            "vdom": "global"
                                        },
                                        "value": "-3.703790"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/longitude/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2",
                                            "vdom": "global"
                                        },
                                        "value": "1"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/member_id/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2",
                                            "vdom": "global"
                                        },
                                        "value": "28"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/timezone/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2",
                                            "vdom": "global"
                                        },
                                        "value": "6"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/vm_interface_number/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2-1",
                                            "vdom": "global"
                                        },
                                        "value": "2"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/branch_id/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2-1",
                                            "vdom": "global"
                                        },
                                        "value": "branch"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/device_type/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2-1",
                                            "vdom": "global"
                                        },
                                        "value": "13"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/fpoc_instance_id/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2-1",
                                            "vdom": "global"
                                        },
                                        "value": "40.416775"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/latitude/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2-1",
                                            "vdom": "global"
                                        },
                                        "value": "-3.703790"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/longitude/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2-1",
                                            "vdom": "global"
                                        },
                                        "value": "2"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/member_id/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2-1",
                                            "vdom": "global"
                                        },
                                        "value": "28"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/timezone/dynamic_mapping"
                                },
                                {
                                    "data": {
                                        "_scope": {
                                            "name": "site_2-1",
                                            "vdom": "global"
                                        },
                                        "value": "6"
                                    },
                                    "url": "/pm/config/adom/production/obj/fmg/variable/vm_interface_number/dynamic_mapping"
                                }
                            ]
                        },
                        {
                            "method": "set",
                            "params": [
                                {
                                    "data": [
                                        {
                                            "name": "port1",
                                            "type": "physical",
                                            "vdom": "root",
                                            "mode": "dhcp"
                                        },
                                        {
                                            "name": "port2",
                                            "type": "physical",
                                            "vdom": "root",
                                            "mode": "dhcp"
                                        },
                                        {
                                            "name": "port3",
                                            "type": "physical",
                                            "vdom": "root"
                                        },
                                        {
                                            "name": "port4",
                                            "type": "physical",
                                            "vdom": "root"
                                        },
                                        {
                                            "name": "port5",
                                            "type": "physical",
                                            "vdom": "root"
                                        },
                                        {
                                            "name": "port6",
                                            "type": "physical",
                                            "vdom": "root"
                                        }
                                    ],
                                    "url": "pm/config/device/%s/global/system/interface"
                                }
                            ]
                        },
                        {
                            "method": "set",
                            "params": [
                                {
                                    "data": {
                                        "member": [
                                            "port5",
                                            "port6"
                                        ]
                                    },
                                    "url": "pm/config/device/%s/global/system/interface/fortilink"
                                }
                            ]
                        },
                        {
                            "method": "set",
                            "params": [
                                {
                                    "data": {
                                        "session-pickup": "enable",
                                        "password": "fortinet"
                                    },
                                    "url": "/pm/config/device/%s/global/system/ha"
                                }
                            ]
                        }
                    ]
                }
            }
        }
    ],
    "session": "{{session}}",
    "id": 8,
    "verbose": 1
}

Note

This request is showing multiple things:

Multiplexing several data block for setting the metadata
Setting metadata for both HA members of the cluster being created
Using the Device Blueprint

RESPONSE

{
    "result": [
        {
            "data": {
                "device": {
                    "adm_usr": "admin",
                    "beta": -1,
                    "branch_pt": 2451,
                    "build": 2451,
                    "conn_mode": 1,
                    "desc": "Touched by fortinet.fortimanager galaxy collection",
                    "dev_status": 1,
                    "faz.perm": 0,
                    "flags": 1143209984,
                    "fsw_cnt": 2,
                    "ha_group_id": 2,
                    "ha_group_name": "site_2",
                    "ha_mode": 1,
                    "hostname": "FGVM01TM23005395",
                    "location_from": "unset",
                    "maxvdom": 10,
                    "mgmt_mode": 3,
                    "mgmt_uuid": "d49ed100-8a1d-51ee-405c-3bb47665b888",
                    "mgt_vdom": "root",
                    "mr": 4,
                    "name": "site_2",
                    "node_flags": 4,
                    "oid": 764,
                    "os_type": 0,
                    "os_ver": 7,
                    "patch": -1,
                    "platform_id": 157,
                    "platform_str": "FortiGate-VM64-KVM",
                    "prio": 200,
                    "sn": "FGVM01TM23005395",
                    "source": 1,
                    "tab_status": "<unknown>",
                    "version": 700,
                    "vm.lic_type": 2,
                    "vm_cpu": 1,
                    "vm_cpu_limit": 1,
                    "vm_lic_overdue_since": 0,
                    "vm_mem": 1024,
                    "vm_mem_limit": 1024,
                    "vm_status": 3
                },
                "taskid": 392
            },
            "status": {
                "code": 0,
                "message": "OK"
            },
            "url": "/dvm/cmd/add/device"
        }
    ],
    "id": 8
}

8.29.2. How to get the cluster members?#

We want to retrieve the cluster members for device fgt-cluster in ADOM DEMO:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "get",
  "params": [
    {
      "url": "/dvmdb/adom/DEMO/device/fgt-cluster/ha_slave"
    }
  ],
  "session": "<session_id>",
  "verbose": 1
}

{
  "id": 1,
  "result": [
    {
      "data": [
        {
          "did": "fgt-cluster",
          "flags": null,
          "idx": 1,
          "name": "fgt-002",
          "oid": 855,
          "prio": 130,
          "role": "master",
          "sn": "FGVMULTM20001440",
          "status": 1
        },
        {
          "did": "fgt-cluster",
          "flags": null,
          "idx": 0,
          "name": "fgt-001",
          "oid": 854,
          "prio": 129,
          "role": "slave",
          "sn": "FGVMULTM20001441",
          "status": 1
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/DEMO/device/fgt-cluster/ha_slave"
    }
  ]
}

Note

The response is containing the oid of each cluster member. This attribute is important for some operations like when we want to fail-over the cluster: in the JSON RPC API request, we have to specify the oid of the new master.

8.29.3. How to fail-over a cluster?#

First we need to retrieve the oid of the cluster and its members

To get the oid of the cluster:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "get",
  "params": [
    {
      "fields": [
        "name"
      ],
      "loadsub": 0,
      "url": "/dvmdb/device/fgt_00_1"
    }
  ],
  "session": "C/1aUce9QuEPobvjXVzwXhp2NHSq6B9CuxxHEBwjd7Vy4A95+CSg9Z/LHRAR9OB7fnPJihZ/Zi00BfAgc+V44A==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "name": "fgt_00_1",
        "oid": 161
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device/fgt_00_1"
    }
  ]
}

To get the oid of each cluster member:

We can get the /dvmdb/device/<device_name> and parse the whole output to get the details of the sub table ha_slave or we can just retrieve that sub-table:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "get",
  "params": [
    {
      "url": "/dvmdb/device/fgt_00_1/ha_slave"
    }
  ],
  "session": "xgvC+QqL8XWT2Qzuwh/22SEobOSQbJQ+Rcw/ln5YuOw/+9JCXhb7gH6dWiNmEDMaE4951vayER1eF9MwbnnOiw==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": [
        {
          "did": "fgt_00_1",
          "flags": null,
          "idx": 0,
          "name": "fgt_00_1",
          "oid": 162,
          "prio": 200,
          "role": "master",
          "sn": "FGVMSLTM21000506",
          "status": 1
        },
        {
          "did": "fgt_00_1",
          "flags": null,
          "idx": 1,
          "name": "fgt_00_2",
          "oid": 163,
          "prio": 100,
          "role": "slave",
          "sn": "FGVMSLTM21000505",
          "status": 1
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device/fgt_00_1/ha_slave"
    }
  ]
}

With the above requests, we managed to get the cluster oid (161) and its members oids (162 and 163).

Then we can trigger the failover by specifying the cluster oid and the oid of the new primary member

Member with oid 162 is the primary; let’s failover to the secondary member (163):

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "demo",
        "device": {
          "oid": 161,
          "os_type": "fos"
        },
        "flags": [
          "create_task",
          "nonblocking"
        ],
        "new_master": 163
      },
      "url": "/dvm/cmd/change-ha-seq"
    }
  ],
  "session": "WX99rwDP47CV51g1U/BoySxzfVvqOKjfa/lyGt+/UCgX59XZUsFn0AGh5cboVrFoeMm5DAsDqAFbYoM5Q0BD3A==",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "pid": 17440,
        "taskid": 66
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/change-ha-seq"
    }
  ]
}

8.29.4. How to update the serial numbers of a cluster?#

This is for when you’re not OK with the serial numbers showing up in the FortiManager GUI for a particular cluster.

Sometimes for instance, you have three serial numbers: 2 are OK but the last one is from a RMA-ed device.

So the very first things to do are to identify what are the valid serial numbers and the role of each member, then to update the cluster’s serial numbers using this request.

Following example shows how to update the serial number of the HUB1 cluster and its HUB1 and HUB1-2 members:

REQUEST:

{
  "id": 1,
  "jsonrpc": "1.0",
  "method": "exec",
  "params": [
    {
      "data": {
        "ha_group_name": "hub1-cluster",
        "ha_mode": "AP",
        "ha_slave": [
          {
            "idx": 0,
            "name": "HUB1",
            "role": "master",
            "sn": "FGVM02TM20009482"
          },
          {
            "idx": 1,
            "name": "HUB1-2",
            "role": "slave",
            "sn": "FGVM02TM20009158"
          }
        ],
        "name": "HUB1"
      },
      "url": "/dvm/cmd/update/ha"
    }
  ],
  "session": "jFNr7wJS9ohIf53pk/aA3G4mQjWoRCrbVJBAVdN4uK8omsjH65AoztFzHKlHc84EkknxlFi/+lNSTFU7gOjwBfhPaj/dQze8",
  "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvm/cmd/update/ha"
    }
  ]
}

Note

You can also use the Refresh operation
See section How to refresh a device?

8.29.5. How to get cluster members status?#

To get the status of the site_1’s cluster members in the production ADOM:

REQUEST

{
  "id": 3,
  "method": "get",
  "params": [
    {
      "url": "/dvmdb/adom/production/device/site_1/ha_slave"
    }
  ],
  "session": "{{session}}",
  "verbose": 1
}

RESPONSE

{
  "id": 3,
  "result": [
    {
      "data": [
        {
          "conf_status": 1,
          "did": "site_1",
          "flags": null,
          "idx": 1,
          "name": "i-06-fgt-11",
          "oid": 1421,
          "prio": 200,
          "role": "master",
          "sn": "FGVM01TM23005111",
          "status": 1
        },
        {
          "conf_status": 1,
          "did": "site_1",
          "flags": null,
          "idx": 0,
          "name": "i-07-fgt-12",
          "oid": 1422,
          "prio": 100,
          "role": "slave",
          "sn": "FGVM01TM23005112",
          "status": 1
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/adom/production/device/site_1/ha_slave"
    }
  ]
}

Note

Returned conf_status could had following values:
- 0 for unknown
- 1 for insync
- 2 for outofsync
In this case, both cluster members are in sync
Returned status indicates whether the cluster member is online (1) or offline (0)

In this case, both cluster members are up.

8.30. Private Data Encryption#

Note

There are multiple wordings for the private data encryption key. It could also be refered as referred master encryption key or master encryption password.

8.30.1. How to get the private data encryption status of one device?#

It is as simple as getting the device’s metadata from FortiManager.

We’re getting the device’s metadata of the device fgt_dc2:

8REQUEST:

{
    "id": 1,
    "method": "get",
    "params": [
        {
            "fields": ["name", "private_key", "private_key_status"],
            "loadsub": 0,
            "url": "/dvmdb/device/fgt_dc2"
        }
    ],
    "session": "{{session}}",
    "verbose": 1
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "data": {
        "name": "fgt_dc2",
        "oid": 333,
        "private_key": "DBhqwTiSCyhlSPjNh8HdivubClBU4Nytr9BziI3gyCMtSKSvDNLweBMTwJVqcYc1Kz4xTc/5aaNjv0aKeToJCX/G19vC12lVqBDjA90LNXzeNG7Ld2ZUJH512I1NE5y1soFuUCSHBGaHwZr+yz08lICf0EBbEvwYTKK+aQJzchr5lYj+",
        "private_key_status": 2
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/dvmdb/device/fgt_dc2"
    }
  ]
}

If private_key is returned as en empty string and private_key_status is equal to 0, then the master encryption password is not set for this device in FortiManager.

Warning

If private_key and private_key_status are not set, it doesn’t mean that on the real device the private data encryption isn’t set as well.
Both private_key and private_key_status are settings applicable to FortiManager only.

8.30.2. How to verify a private data encryption key?#

Starting with FMG 7.0.5/7.2.1, it is possible to set the master encryption key using the FortiManager JSON RPC API.

Warning

This is not setting the master encryption key on the real device!
This is to set the master encryption key on the device’s metadata in FortiManager in order to make sure it is aligned with the one set on the real device.

We set the private data encryption key for managed device with device OID 333:

REQUEST:

{
  "id" : 1,
  "method" : "exec",
  "params" : [
    {
      "data" : {
        "key" : "0123456789ABCDEF0123456789ABCDEF",
        "device" : 333
      },
      "url" : "/deployment/verify/private/key"
    }
  ],
  "session" : "{{session}}"
}

RESPONSE:

{
  "id": 1,
  "result": [
    {
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/deployment/verify/private/key"
    }
  ]
}

Note

Interesting to note that the above FortiManager JSON RPC API request will produce the following FortiGate CLI execution on the real device:

diagnose debug cli 8
diagnose debug duration 0
diagnose debug enable
diagnose debug console timestamp enable
2022-06-15 09:02:45 0: get system status
2022-06-15 09:02:47 0: execute private-encryption-key verify GFBkGzA5VC6fBgh7eLK9PL/Ntgv5tJlG0toWUQEAay4= vAfV3s3a2X+81SegD8YGlWHiRFU=

8.31. FortiGate-VM#

8.31.1. How to upload a FortiGate-VM license?#

To be tested.

This API call was captured with following FortiManager debug command:

diagnose debug service main 255
diagnose debug timestamp enable
diagnose debug enable

Then by using the FortiManager GUI and right-clicking a managed device under Device Manager and selecting Install VM License:abbr:

{
  "client": "/usr/local/apache2/bin/httpd:22646",
  "id": 1,
  "method": "exec",
  "params": [
    {
      "data": {
        "device": 1241,
        "license": "[.lic license file content]",
        "task": 309,
        "type": 0
      },
      "url": "dmworker/install/license"
    }
  ],
  "session": 13786,
  "src": "127.0.0.1"
}

8.32. Single Pane of Glass#

This is for when FortiManager is managing a FortiAnalyzer.

8.32.1. How to sync a FortiManager ADOM?#

8.32.1.1. When a device is added#

To sync FortiManager ADOM test_002 with managed FortiAnalyzer prod-faz-721-001:

REQUEST:

{
  "id": 3,
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "test_002",
        "confirm": 1,
        "device": "prod-faz-721-001"
      },
      "url": "/faz/cmd/sync/dvmdb"
    }
  ],
  "session": "VXEUONHY6O2yOlXhm4QWvqxXDDS9uzHC13bh8cWXUh/3zWKg6eUi+h67NCB2erEYFgmdw8LShKN0jX8X0W7KYBW4ZViWHTTQ"
}

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": {
        "taskid": 118
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/faz/cmd/sync/dvmdb"
    }
  ]
}

Note

It is important to wait for the task completion before ending the FortiManager JSON RPC API session

8.32.1.2. When a device is deleted#

To sync FortiManager ADOM test_002 with managed FortiAnalyzer prod-faz-721-001:

REQUEST:

{
  "id": 3,
  "method": "exec",
  "params": [
    {
      "data": {
        "adom": "test_002",
        "confirm": 1,
        "device": "prod-faz-721-001",
        "option": [
          "delete device"
        ]
      },
      "url": "/faz/cmd/sync/dvmdb"
    }
  ],
  "session": "OxsmQoqrXFwcBnhPwvSZ25DIZqGhfUtrf46g+6jU10f08+D23ZDoGOhvJBFpu3ltxIJ0er+KpdbS8FYKyL052lGP+49nIe9O"
}

RESPONSE:

{
  "id": 3,
  "result": [
    {
      "data": {
        "taskid": 119
      },
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/faz/cmd/sync/dvmdb"
    }
  ]
}

Note

It is important to wait for the task completion before ending the FortiManager JSON RPC API session

8.33. How to operate a Where Used?#

Some elements of the Device DB are elligible to a Where Used operation.

How to figure out which one?

By trying with the FortiManager GUI.

For instance, it is possible to Where Used a system interface.

The following example describes how to where used the port2.1001 system interface from the dut_fgt_03 managed device:

It is still a three steps process:

Start the Where Used operation to get a token

REQUEST

{
    "id": "1",
    "method": "exec",
    "params": [
        {
            "url": "cache/search/where/used/start",
            "data": {
                "obj": "device/dut_fgt_03/global/system/interface",
                "mkey": "port2.1001"
            }
        }
    ]
    "session": "{{session}}"
}

RESPONSE

{
    "code": 0,
    "data": {
        "result": [
            {
                "data": {
                    "token": "TedkwWWwgWQh0gdmGI81lw=="
                },
                "id": "f24acb25-a6a0-417d-8765-8c75c647e2f7",
                "status": {
                    "code": 0,
                    "message": "OK"
                },
                "url": "/cache/search/where/used/start"
            }
        ]
    },
    "errors": "",
    "message": ""
}

Ask for a summary for the returned token

It will give you the process of the Where Used operation:

REQUEST

{
    "id": "1",
    "method": "exec",
    "params": [
        {
            "url": "cache/search/where/used/get/summary",
            "token": "TedkwWWwgWQh0gdmGI81lw=="
        }
    ],
    "session": "{{session}}"
}

RESPONSE

{
    "code": 0,
    "data": {
        "result": [
            {
                "data": {
                    "percent": 100
                },
                "id": "3a0c5969-2303-4440-8537-630422262e47",
                "status": {
                    "code": 0,
                    "message": "OK"
                },
                "url": "/cache/search/where/used/get/summary"
            }
        ]
    },
    "errors": "",
    "message": ""
}

Once the percent is 100 you can consider the Where Used operation as completed

If percent is different than 100 you have to keep asking for a summary

You can now get the Where Used detail

REQUEST

{
    "id": "0476b81d-f61c-4a55-a5a6-8acc0346fbd1",
    "method": "exec",
    "params": [
        {
            "url": "cache/search/where/used/get/detail",
            "token": "TedkwWWwgWQh0gdmGI81lw=="
        }
    ]
}

RESPONSE

{
    "code": 0,
    "data": {
        "result": [
            {
                "data": {
                    "percent": 100,
                    "total_num": 1,
                    "where_used": [
                        {
                            "data": [
                                {
                                    "attr": "interface",
                                    "category": 140,
                                    "last use": 1,
                                    "mapping_name": "firewall address",
                                    "mattr": "name",
                                    "mkey": "port2.1001 address",
                                    "vdom": {
                                        "name": "root",
                                        "oid": 3,
                                        "type": "unknown type"
                                    }
                                }
                            ],
                            "root": {
                                "name": "dut_fgt_03",
                                "oid": 296
                            }
                        }
                    ]
                },
                "id": "0476b81d-f61c-4a55-a5a6-8acc0346fbd1",
                "status": {
                    "code": 0,
                    "message": "OK"
                },
                "url": "/cache/search/where/used/get/detail"
            }
        ]
    },
    "errors": "",
    "message": ""
}

You can see that port2.1001 system interface is referenced by port2.1001 address firewall address

The above example was for a system interface and because of that, the obj attribute in the very first request (the one starting the Where Used process) was referering to the device’s global scope.

Should you want to Where Used something else like the phase1-interface, you can use a VDOM scope obj as shown below:

{
    "id": "1",
    "method": "exec",
    "params": [
        {
            "url": "cache/search/where/used/start",
            "data": {
                "obj": "device/dut_fgt_03/vdom/root/vpn/ipsec/phase1-interface",
                "mkey": "ol_isp1"
            }
        }
    ],
    "session": "{{session}}"
}

8.34. Device Blueprint#

8.34.1. How to get the list of metadata used by a Device Blueprint?#

Caught in #0947563.

OPTION #1

{
    "method": "get",
    "params": [
        {
            "url": "/pm/config/adom/TestBlueprint/_meta/reference",
            "data": {
                "pkg list": [
                    {
                        "oid": 5201
                    }
                ]
            }
        }
    ]
}

OPTION #2 (Recommended)

REQUEST

{
  "id": 3,
  "method": "get",
  "params": [
    {
      "data": {
        "name": [
          "sites_test",
          "test_remy"
        ]
      },
      "url": "/pm/config/adom/dc_emea/_blueprint/info"
    }
  ],
  "session": "{{session}}",
  "verbose": 1
}

RESPONSE

{
  "id": 3,
  "result": [
    {
      "data": [
        {
          "name": "sites_test",
          "platform": "FortiGate-40F",
          "variables": [
            "hostname"
          ]
        },
        {
          "name": "test_remy",
          "platform": "FortiGate-40F",
          "variables": [
            "ul_isp1",
            "ul_isp2"
          ]
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/pm/config/adom/dc_emea/_blueprint/info"
    }
  ]
}

8.35. VPN Monitor#

How to get VPN tunnel details as exposed in the Device Manager > Monitors > VPN Monitor page when you toggle on the Show Table:abbr:

To get the VPN tunnel details for the i-04-hub-02 device in the production ADOM:

REQUEST

{
  "id": 3,
  "method": "exec",
  "params": [
    {
      "data": {
        "action": "get",
        "resource": "/api/v2/monitor/vpn/ipsec?vdom=root",
        "target": [
          "adom/dc_emea/device/i-04-hub-02"
        ]
      },
      "url": "/sys/proxy/json"
    }
  ],
  "session": "{{session}}"
}

Note

Review section How to encapsulate FOS REST API call within FMG JSON RPC API? for how to play with the target attribute if you want to make a single API call targeting multiple managed devices or device groups

REQUEST

{
  "id": 3,
  "result": [
    {
      "data": [
        {
          "response": {
            "action": "",
            "build": 2463,
            "http_method": "GET",
            "name": "ipsec",
            "path": "vpn",
            "results": [
              {
                "comments": "VPN: VPN2 [Created by IPSEC Template]",
                "incoming_bytes": 665578973,
                "name": "VPN2",
                "outgoing_bytes": 616068531,
                "proxyid": [],
                "rgwy": "0.0.0.0",
                "tun_id": "10.0.0.2",
                "tun_id6": "::10.0.0.2",
                "type": "",
                "wizard-type": "custom"
              },
              {
                "comments": "VPN: VPN1 [Created by IPSEC Template]",
                "connection_count": 35,
                "creation_time": 2999411,
                "dialup_index": 0,
                "incoming_bytes": 271578165,
                "name": "VPN1_0",
                "outgoing_bytes": 246820096,
                "parent": "VPN1",
                "proxyid": [
                  {
                    "expire": 3995,
                    "incoming_bytes": 3225536,
                    "outgoing_bytes": 8658008,
                    "p2name": "VPN1",
                    "p2serial": 1,
                    "proxy_dst": [
                      {
                        "port": 0,
                        "protocol": 0,
                        "protocol_name": "",
                        "subnet": "0.0.0.0-255.255.255.255"
                      }
                    ],
                    "proxy_src": [
                      {
                        "port": 0,
                        "protocol": 0,
                        "protocol_name": "",
                        "subnet": "0.0.0.0-255.255.255.255"
                      }
                    ],
                    "status": "up"
                  }
                ],
                "rgwy": "198.18.21.3",
                "tun_id": "10.10.0.1",
                "tun_id6": "::10.0.0.22",
                "type": "dialup",
                "username": "Branch1",
                "wizard-type": "custom"
              },
              {
                "comments": "VPN: VPN1 [Created by IPSEC Template]",
                "connection_count": 35,
                "creation_time": 2999411,
                "dialup_index": 1,
                "incoming_bytes": 271585191,
                "name": "VPN1_1",
                "outgoing_bytes": 246816303,
                "parent": "VPN1",
                "proxyid": [
                  {
                    "expire": 4004,
                    "incoming_bytes": 3224420,
                    "outgoing_bytes": 8654996,
                    "p2name": "VPN1",
                    "p2serial": 1,
                    "proxy_dst": [
                      {
                        "port": 0,
                        "protocol": 0,
                        "protocol_name": "",
                        "subnet": "0.0.0.0-255.255.255.255"
                      }
                    ],
                    "proxy_src": [
                      {
                        "port": 0,
                        "protocol": 0,
                        "protocol_name": "",
                        "subnet": "0.0.0.0-255.255.255.255"
                      }
                    ],
                    "status": "up"
                  }
                ],
                "rgwy": "198.18.11.3",
                "tun_id": "10.10.0.2",
                "tun_id6": "::10.0.0.24",
                "type": "dialup",
                "username": "Branch2",
                "wizard-type": "custom"
              },
              {
                "comments": "VPN: VPN2 [Created by IPSEC Template]",
                "connection_count": 35,
                "creation_time": 2999411,
                "dialup_index": 0,
                "incoming_bytes": 271580039,
                "name": "VPN2_0",
                "outgoing_bytes": 246818469,
                "parent": "VPN2",
                "proxyid": [
                  {
                    "expire": 3991,
                    "incoming_bytes": 3225730,
                    "outgoing_bytes": 8658396,
                    "p2name": "VPN2",
                    "p2serial": 1,
                    "proxy_dst": [
                      {
                        "port": 0,
                        "protocol": 0,
                        "protocol_name": "",
                        "subnet": "0.0.0.0-255.255.255.255"
                      }
                    ],
                    "proxy_src": [
                      {
                        "port": 0,
                        "protocol": 0,
                        "protocol_name": "",
                        "subnet": "0.0.0.0-255.255.255.255"
                      }
                    ],
                    "status": "up"
                  }
                ],
                "rgwy": "198.18.22.2",
                "tun_id": "10.10.64.1",
                "tun_id6": "::10.0.0.23",
                "type": "dialup",
                "username": "Branch1",
                "wizard-type": "custom"
              },
              {
                "comments": "VPN: VPN2 [Created by IPSEC Template]",
                "connection_count": 35,
                "creation_time": 2999411,
                "dialup_index": 1,
                "incoming_bytes": 271580984,
                "name": "VPN2_1",
                "outgoing_bytes": 246816536,
                "parent": "VPN2",
                "proxyid": [
                  {
                    "expire": 3976,
                    "incoming_bytes": 3227004,
                    "outgoing_bytes": 8661972,
                    "p2name": "VPN2",
                    "p2serial": 1,
                    "proxy_dst": [
                      {
                        "port": 0,
                        "protocol": 0,
                        "protocol_name": "",
                        "subnet": "0.0.0.0-255.255.255.255"
                      }
                    ],
                    "proxy_src": [
                      {
                        "port": 0,
                        "protocol": 0,
                        "protocol_name": "",
                        "subnet": "0.0.0.0-255.255.255.255"
                      }
                    ],
                    "status": "up"
                  }
                ],
                "rgwy": "198.18.12.1",
                "tun_id": "10.10.64.2",
                "tun_id6": "::10.0.0.25",
                "type": "dialup",
                "username": "Branch2",
                "wizard-type": "custom"
              },
              {
                "comments": "VPN: VPN1 [Created by IPSEC Template]",
                "incoming_bytes": 658419394,
                "name": "VPN1",
                "outgoing_bytes": 608907495,
                "proxyid": [],
                "rgwy": "0.0.0.0",
                "tun_id": "10.0.0.1",
                "tun_id6": "::10.0.0.1",
                "type": "",
                "wizard-type": "custom"
              }
            ],
            "serial": "FGVM01TM23005392",
            "status": "success",
            "vdom": "root",
            "version": "v7.4.1"
          },
          "status": {
            "code": 0,
            "message": "OK"
          },
          "target": "i-04-hub-02"
        }
      ],
      "status": {
        "code": 0,
        "message": "OK"
      },
      "url": "/sys/proxy/json"
    }
  ]
}

Device Management

Contents

8. Device Management#

8.1. How to rename a managed device?#

8.1.1. Using /dvmdb/device/<device>#

8.1.2. Using /dvmdb/adom/<adom>/device/<device>#

8.2. Device status#

8.3. How to refresh a device?#

8.3.1. Refresh one device#

8.3.2. Refresh multiple devices#

8.4. Device coordinates#

8.5. How to get the full device database syntax?#

8.6. How to add a real device?#

8.7. How to change the serial number of a managed device?#

8.8. How to get unauthorized devices?#

8.9. How to promote/authorize a real device?#

8.10. Model Device#

8.10.1. How to obtain the list of supported Model Device?#

8.10.2. How to create a Model Device?#

8.10.2.1. For a virtual appliance#

8.10.2.2. For a hardware appliance#

8.10.3. How to create a model device and add in in a group with a single request?#

8.10.4. How to enable the auto-link flag on a model device?#

8.10.4.1. Multiplexing example#

8.10.5. How to enable VDOM on a Model Device?#

8.10.6. How to enable the need_reset flag on a model device?#

8.10.7. How to add a model device linked to a pre-Run CLI Template?#

8.10.8. How to get the list of Model Devices?#

8.11. How to get the ADOM a device belongs to?#

8.11.1. How to get the ADOM a device belongs to using object master with filter?#

8.11.2. How to get the ADOM a device belongs to using the extra info option?#

8.12. How to install device settings against devices?#

8.13. Device Groups#

8.13.1. How to install device settings against a device group?#

8.13.2. How to create a device group?#

8.13.3. How to add a device in a device group?#

8.13.4. How to add multiple devices in a device group?#

8.13.5. How to add a device group into a device group?#

8.13.6. How to get the device group members?#

8.13.7. How to delete a device from a device group?#

8.13.8. How to delete multiple devices from a device group?#

8.13.9. How to delete a device group?#

8.14. How to delete a device?#

8.15. How to get device’s meta fields?#

8.16. How to set device’s meta fields?#

8.17. VDOM operations#

8.17.1. How to enable VDOM?#

8.17.2. How to add a NAT VDOM?#

8.17.2.1. Using /dvmdb/device endpoint#

8.17.2.2. Using /dvmdb/adom endpoint#

8.17.3. How to assign a VDOM to an ADOM?#

8.17.4. How to create a transparent VDOM?#

8.17.5. How to get the interfaces assigned to a VDOM?#

8.17.6. How to create a VDOM link?#

8.17.6.1. Create the VDOM link object#

8.17.6.2. Set the first auto-generated system interface#

8.17.6.3. Set the second auto-generated system interface#

8.17.7. How to delete a VDOM?#

8.17.8. How to get the Device VDOM metafields for all VDOMs of a device?#

8.17.9. How to get the Device VDOM metafields for a single VDOM?#

8.17.10. How to set the Device VDOM metafields for multiple VDOMs of a same device?#

8.17.11. How to set the Device VDOM metafields for a single VDOM?#

8.18. How to get default settings for a particular type of device?#

8.19. How to get the policy package status when getting list of devices?#

8.20. How to get the status of a policy package assigned to a specific device?#

8.21. Device revisions#

8.21.1. How to get the list of device revisions for a particular device?#

8.21.2. How to get a specific device revision for a particular device?#

8.21.3. How to get the current device database configuration for a particular device?#

8.21.4. How to revert to a specific device revision?#

8.21.5. How to import a device revision?#

8.22. How to trigger a retrieve operation?#

8.22.1. Against a single device#

8.22.2. Against multiple devices#

8.23. Firmware upgrade#

8.23.1. How to get the upgrade path?#

8.23.2. How to get list of available firmware for a specific platform?#

8.23.3. How to get list of firmwares available on FortiManager drive?#

8.23.4. How to get list of firmwares available on FortiManager drive for a specific product?#

8.23.5. How to upgrade a device?#

8.10.6. How to enable the `need_reset` flag on a model device?#

8.17.2.1. Using `/dvmdb/device` endpoint#

8.17.2.2. Using `/dvmdb/adom` endpoint#

8.29.1.3. How to add a Model HA Cluster with `session-pick` up and `override` enabled?#