How to use zencatalogscan to scan/fix broken catalog references

Applies To

  • Zenoss 5.x
  • Zenoss 4.x


The zencatalogscan python script (available as part of the zenoss.toolbox project on Github - scans Zenoss catalogs for references to missing objects/unresolvable paths.

Zencatalogscan processes the catalog(s) as specified via the command line and will create summary events in the Zenoss event console that summarize the execution results.

WARNING: If any catalog issues are detected, before you re-run with the --fix flag, first confirm that zodbscan, findposkeyerror, and zenrelationscan all return with no issues found.


Zenoss uses catalogs to speed up different user interface (UI) operations that would otherwise require large database queries. Therefore, when these catalogs fall out of sync with their databases, administrators are likely to encounter symptoms when using the UI. These symptoms may cause administrators to find that:

  • they cannot view devices known to be monitored by Zenoss
  • they encounter yellow banner ("flare") error messages
  • they cannot load certain pages in the web interface
  • they cannot view/delete certain devices/device components
  • they cannot run certain reports

Using the zencatalogscan Script

usage: [-h] [-v] [-v10] [--tmpdir TMPDIR] [-s] [-f] [-n CYCLES] [-l] [-c CATALOG]

zencatalogscan - scans catalogs for broken references -
WARNING: Before using with --fix you MUST confirm zodbscan, findposkeyerror, and zenrelationscan
return no errors.

optional arguments:

-h, --help show this help message and exit
-v, --version show program's version number and exit
-v10, --debug debug verbose log output (debug logging)
--tmpdir TMPDIR override the TMPDIR setti
-s, --skipEvents skip creating summary events
-f, --fix attempt to remove any invalid references
-n CYCLES, --cycles CYCLES maximum times to cycle (with --fix, ≤12)
-l, --list output all supported catalogs
-c CATALOG, --catalog CATALOG only scan/fix specified catalog

Example Script Output

[2016-02-18 13:00:15] Initializing zencatalogscan v2.0.0 (detailed log at /opt/zenoss/log/toolbox/zencatalogscan.log)
[2016-02-18 13:00:19] Examining Devices.deviceSearch                (1 Objects)
[2016-02-18 13:00:19]  Verified  [==================================================] 100%
[2016-02-18 13:00:19] Examining Devices.searchRRDTemplates          (311 Objects)
[2016-02-18 13:00:19]  Verified  [==================================================] 100%
[2016-02-18 13:00:19] Examining Events.eventClassSearch             (512 Objects)
[2016-02-18 13:00:20]  Verified  [==================================================] 100%
[2016-02-18 13:00:20] Examining global_catalog 'paths to uids'      (25601 Objects)
[2016-02-18 13:00:21]  Verified  [==================================================] 100%
[2016-02-18 13:00:21] Examining global_catalog                      (25601 Objects)
[2016-02-18 13:00:41]  Verified  [==================================================] 100%
[2016-02-18 13:00:41] Examining Manufacturers.productSearch         (3331 Objects)
[2016-02-18 13:00:42]  Verified  [==================================================] 100%
[2016-02-18 13:00:42] Examining Mibs.mibSearch                      (9893 Objects)
[2016-02-18 13:00:46]  Verified  [==================================================] 100%
[2016-02-18 13:00:46] Examining Services.serviceSearch              (3886 Objects)
[2016-02-18 13:00:48]  Verified  [==================================================] 100%
[2016-02-18 13:00:48] Examining zenPackPersistence                  (643 Objects)
[2016-02-18 13:00:49]  Verified  [==================================================] 100%

[2016-02-18 13:00:49] Execution finished in 0:00:33
Was this article helpful?
2 out of 4 found this helpful


Powered by Zendesk