Technical Tip: How to upgrade an ADOM on FortiManager
Description
This article describes how to upgrade an ADOM on FortiManager and how to perform basic troubleshooting in case of an ADOM upgrade failure.
Scope
FortiManager versions between v5.4.x and v7.6.x.
Note: ADOM upgrade behavior may vary depending on the FortiManager version, the source ADOM version, the target ADOM version, and the FortiOS versions of the managed devices. Always verify the supported ADOM and FortiOS version matrix for the specific FortiManager release before proceeding.
Solution
Prerequisites and notes:
ADOM upgrade requires system-level administrator permissions and access to the respective ADOMs (e.g., Super_User admin profile). Before upgrading an ADOM, it is recommended to take a FortiManager configuration backup. For FortiManager VM deployments, it is also recommended to take a VM snapshot so that the system can be restored if required.
If it is available in the FortiManager version, use the ADOM Upgrade Readiness tool before upgrading the ADOM. This tool can help identify potential invalid or missing configurations that may prevent the ADOM upgrade. The readiness tool does not automatically fix invalid values; any detected issue should be reviewed and corrected before proceeding.
In the firmware versions within the scope of this article (v5.4.x to v7.6.x), an ADOM can only be upgraded after all the devices within this ADOM have been upgraded.
Starting in v7.0.1, the ADOM version can be upgraded without first updating all devices and the ADOM can manage N+1 devices during migration. This is something called mixed mode or migration mode.
Starting in v7.4.2, it is possible to have one ADOM in v7.4 (ADOM versions) that can manage FortiOS in v7.0, v7.2, and v7.4.
Starting in v7.4.6, managing any FortiGate version in any ADOM is now possible (ADOM versions). Even when mixed FortiOS versions are supported in the same ADOM, it is generally recommended to minimize ADOM/FortiOS version differences where possible. When the ADOM manages devices running earlier or later FortiOS versions, FortiManager uses upgrade/downgrade logic on a best-effort basis to adapt CLI syntax. Some new FortiOS syntax or features may not be available in an older ADOM version, and this may affect import, install, or policy verification behavior.
Before upgrading FortiManager firmware, check whether all existing ADOM versions are supported by the target FortiManager version. If any ADOM version is not supported by the target FortiManager version, upgrade the unsupported ADOMs to a supported version before upgrading FortiManager firmware. Unsupported ADOM versions may become unavailable after the FortiManager firmware upgrade, and they may not be upgradeable after the FortiManager unit has already been upgraded to the target version.
Although it is possible to manage FortiGates with different versions within the same ADOM, there are a few limitations:
'Import Policy' could be limited if the FortiGate version is different than the ADOM version:
The logic before FortiManager v7.4.6 is explained in ADOM versions.
After the FortiManager v7.4.6 version, the logic is explained in ADOM versions.
Configuration features implemented in the newer FortiGate version may not be available in the older ADOM version.
There might be a mismatch in the CLI syntax of some ADOM objects, causing installation or verification errors (e.g., new syntax implemented in FortiOS that is not available in the database of older ADOM versions).
Â
To upgrade an ADOM:
Go to System Settings -> All ADOMs.
Â
Â
The same view in the CLI:
Â
Note:
It is not possible to upgrade an ADOM using the CLI. This operation has to be completed in the GUI.
Â
Select an ADOM and select 'Upgrade', or select an ADOM, select 'More', and then 'Upgrade' from the toolbar.
If the ADOM has already been upgraded to the latest version, this option will not be available.Â
Select 'OK' in the confirmation dialog box to upgrade the device.
Â
Â
In the above/below image, the ADOM has been successfully upgraded. The new ADOM version is then displayed in the 'Firmware Version' column.
Â
In versions under v6.4, select the ADOM that will be upgraded and go to More -> Upgrade.
Â
Synthetic diagram when ADOM upgrade is successful.
If one or more devices in the ADOM are not running a firmware version supported by the target ADOM version, the ADOM upgrade may be stopped and an error message may be shown.Â
Â
The example below illustrates the failed ADOM upgrade: 'Please upgrade all devices to 5.6 before upgrading the ADOM'.Â
Â
In such a case, upgrade the remaining devices within the ADOM, then return to step 1 to try upgrading the ADOM again.
Â
Synthetic diagram of a scenario where an ADOM upgrade fails:
Troubleshooting ADOM upgrade:
In some cases (if all the FortiGates in the ADOM are upgraded), the ADOM procedure may fail for many reasons. See the different reasons that may prevent a customer from upgrading an ADOM below (this is a non-exhaustive list):
Â
Name conflicts in wildcard FQDN addresses on SSL/SSH profiles (for ADOM v5.6, v6.0, and v6.2).
Different CLI syntax on objects/profiles.
Miscellaneous inconsistencies on firewall objects.
FortiGate object table size limitation changes.
All of these errors mentioned above are known fixed bugs and still exist in the customer environment because the ADOM has never been upgraded in the past, even though the FortiManager is using the latest firmware version. Different firmware versions have different features and, therefore, different CLI syntax. This is the reason why the ADOM upgrade might not be successful.
FortiManager debug commands:
In cases like the ones mentioned above, Fortinet recommends using the following CLI troubleshooting commands for FortiManager versions before v7.4.x:
diagnose debug enable
diagnose debug service cdb 255
For FortiManager v7.4 and above, use the following troubleshooting commands:
diagnose debug enable
diagnose debug service dvmdb 255Â
These CLI commands will help to localize and identify the root cause of the problem that prevents the upgrade of the ADOM. In most cases, removing the concerned object/profile/interface allows one to fix the issue and successfully upgrade the ADOM. Another scenario may occur: many errors prevent the upgrade of the ADOM.
Â
Find the first error, then fix it and try to upgrade the ADOM without success. In that case, use the same method and CLI commands to identify the object/profile/interface causing the problem.
Â
If the concerned object is used and/or important in the configuration (cannot be modified), contact Fortinet support for further assistance. The ADOM upgrade debugging will always stop on the concerned error.
Below are some examples of FortiManager debugging after a failed ADOM upgrade:
Example 1:Â
--> commit copy firewall address.autoupdate.opera.com(soid=149) to dparent=1227, fail: err=-2, Name conflicts with an entry in wildcard FQDN address
name: autoupdate.opera.com ---> autoupdate.opera.com
subnet: 0.0.0.0 0.0.0.0 ---> 0.0.0.0 0.0.0.0
type: fqdn ---> fqdn
start-ip: 0.0.0.0 ---> 0.0.0.0
end-ip: 0.0.0.0 ---> 0.0.0.0
fqdn: autoupdate.opera.com ---> autoupdate.opera.com
associated-interface: any ---> any
wildcard: 0.0.0.0 0.0.0.0 ---> 0.0.0.0 0.0.0.0
cache-ttl: 0 ---> 0
color: 0 ---> 0
visibility: enable ---> enable
uuid: 2fe03af0-43b8-51ea-1233-d6844b291acd ---> 2fe03af0-43b8-51ea-1233-d6844b291acd
allow-routing: disable ---> disable
obj-id: 0 --->Â
Explanations of the previous error: By default, in 6.0 ADOM some firewall addresses have the same name as wildcard FQDN i.e.: 'autoupdate.opera.com', 'google-play', etc.
When upgrading to v6.2, it will hit the newly added check of not allowing the firewall address to have the same name as a wildcard FQDN.
Â
