Skip to content

Rule Import and Export

The Syncer can export and import its Syncer Rules. This is useful for backups, for transferring rules between environments (e.g. test → production), or for sharing a rule set with colleagues.

There are two ways to export rules: from the GUI (per rule type) and from the CLI (single type or all types at once).

GUI Export

Every Syncer Rule list in the web interface supports exporting. To export rules from the GUI:

  1. Open the rule list you want to export (e.g. Modules → Checkmk → Export Rules).
  2. Select the rules you want to export using the checkboxes on the left. Use the header checkbox to select all rules on the current page.
  3. Choose Export → JSON from the actions menu above the list.

The browser downloads a file named like CheckmkRule_202604131530.syncer_json. The first token before the underscore is the model class name of the exported rule type; the rest is a timestamp.

Do not rename the exported file

The import command uses the filename to determine which rule type the file belongs to. It parses the part before the first underscore and matches it against the known rule models. If you rename the file, the import will fail with "Ruletype not supported".

If you really need to rename a GUI export, keep the model class name as the first token — for example CheckmkRule_backup.syncer_json still works, but my_backup.syncer_json does not.

CLI Export

The CLI provides two variants: export of a single rule type and export of all rule types at once.

Export a Single Rule Type

./cmdbsyncer rules export_rules <rule_type>

The command prints line-delimited JSON to stdout, starting with a header line {"rule_type": "..."} followed by one JSON object per rule. Redirect the output to a file to save it:

./cmdbsyncer rules export_rules cmk_rules > cmk_rules_backup.jsonl

Run the command without an argument to list all supported rule types.

Export All Rules at Once

Since version 3.12.5, you can export all Syncer rules of every type into a single file:

./cmdbsyncer rules export_all_rules

Without an argument, the Syncer writes to a timestamped file such as syncer_rules_export_20260413_145521.jsonl in the current directory. You can also specify an explicit path:

./cmdbsyncer rules export_all_rules /path/to/backup.jsonl

The output is line-delimited JSON. Each rule type is introduced by a header line {"rule_type": "..."}, followed by one JSON object per rule of that type. All known rule types are written into the same file in one pass.

Since version 4.3, everything you configure in the web interface is part of the export: all rules of every module, plus site and folder pools, Checkmk notification rules, projects, cron groups, notification channels and rules, saved searches and the system config. Restoring such a file into an empty Syncer rebuilds the configuration as it was.

Hosts, objects, accounts, users and passwords are skipped by default

Four rule types are excluded from export_all_rules unless explicitly requested, because they are either bulk data or sensitive:

  • host_objects — hosts and objects stored in the shared Host collection. Enable with --include-hosts.
  • accounts — account definitions (including encrypted credentials). Enable with --include-accounts.
  • users — user accounts including hashed passwords and roles. Enable with --include-users, and treat the resulting file as secret.
  • cmk_passwords — the Checkmk password store. The entries stay encrypted with the key of the Syncer that wrote them, so they can only be read back by an instance using the same CRYPTOGRAPHY_KEY. Enable with --include-passwords, and treat the resulting file as secret.
./cmdbsyncer rules export_all_rules --include-hosts --include-accounts

What is never exported

Runtime data is left out on purpose: the syncer log, cronjob and playbook run statistics, caches (Checkmk objects, Jira schema), host inventory data, label history and the field approval queue. All of it is rebuilt by the syncer itself.

CMDB templates are exported separately

Since version 4.3, CMDB templates have their own rule type cmdb_templates. They are configuration rather than data and are therefore part of every export_all_rules run — no flag needed. host_objects in turn never contains templates, so a backup taken with --include-hosts holds each document exactly once.

Use ./cmdbsyncer rules export_rules cmdb_templates to export only the templates, for example to move a template set from test to production without carrying the hosts along.

CLI Import

A single import command handles all export formats — GUI exports, single-type CLI exports, and combined multi-type exports from export_all_rules:

./cmdbsyncer rules import_rules /path/to/file

The import auto-detects the format:

  • If the file starts with a {"rule_type": "..."} header, the import uses that rule type. Multiple header blocks in the same file are supported — the importer switches rule type whenever a new header appears.
  • If the file has no header (GUI export), the import falls back to guessing the rule type from the filename, as described above.

Rules that already exist in the database (same _id) are skipped with an "Already existed" message, so re-running the import is safe and idempotent.

To update rules instead of skipping them, use --override:

./cmdbsyncer rules import_rules /path/to/file --override

With --override every rule from the file replaces the one already in the database — matched either by its _id or by its name, so an export from another instance updates the existing rule instead of being refused as duplicate. Rules which are not part of the file stay untouched.