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).

To move rules between a test and a production instance on a regular basis, Rules in Git pushes selected rule types into a Git repository and pulls them on the other side.

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. Since version 4.5 the first line of the file names the rule type as well: {"rule_type": "cmk_export_rules"}.

Do not rename an older export

A GUI export from before version 4.5 has no such line. For these files 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 such a file, keep the model class name as the first token, for example CheckmkRule_backup.syncer_json still works, but my_backup.syncer_json does not.

GUI Import

Since 4.5

Every rule list with an Export also has an Import next to it, for example at Modules → Checkmk → Manage Service Labels, and Lookup Tables have both. It needs the same permission as editing that rule type and is not offered to read-only users. Hosts, objects and CMDB templates have no import here.

Paste the rules or give the path of a file, then choose:

  • Check shows per record what would happen and writes nothing.
  • Import does the same check and then writes.

The page takes what the Export writes, unchanged, as well as line-delimited JSON, a JSON list, a single rule and the bundle of the REST API. It knows the rule type from the page, so an older export works under any file name, and also when pasted. A rule written by hand needs no _id, it gets a new one.

{"name": "Port role", "enabled": true, "condition_typ": "anyway", "outcomes": [{"service_pattern": "^Port", "label_name": "role", "label_value": "{{ HOSTNAME }}"}]}

Good to know:

  • Existing rules stay. A rule exists if it has the same _id or the same name. Its record is skipped and listed as skipped, as on the command line. With Replace existing rules the record replaces it, and the page names every rule it replaced or would replace.
  • All or nothing. One bad record, like broken JSON, an unknown field or a value the rule type refuses, means nothing is imported, and the page gives the reason per record. If the database fails during the write, the result lists exactly which rules got in.
  • Only this rule type. A file which names another rule type, in a {"rule_type": "..."} line or in its file name, is refused, also when it holds several types like an export_all_rules file: use import_rules for these. Some rule types have the same fields, so a text without any of these hints can't be told apart from them and the page says so.
  • The same checks as the form, where a rule type has them: for example a Service Label rule with a broken regular expression or Jinja is refused. Other Jinja which does not compile is shown as a warning. Rules are not run during the import.
  • Like a save: the import counts as a change for Commit, drops the rule outcomes cached on the hosts, and is written to the log with the user and the rule names.

Path of a file

The path is read on the server. So it needs the permission for Files on top, and without that permission the field is not shown:

  • The file must be in the Files folder (FILEADMIN_PATH). A relative path starts there, every other location is refused.
  • It must end in .syncer_json, .jsonl or .json and be at most 5 MB of UTF-8 text.
  • A symbolic link anywhere below the Files folder is refused.
  • Messages about such a file name positions and fields only, never its content.

Pasting is limited by the form size of the web server, by default 500 kB. Use a path for larger files.

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.

With --zip the export is written compressed into a zip archive, for example to send a complete configuration including the hosts for analysis. Without a path the archive is named like syncer_rules_export_20260413_145521.zip:

./cmdbsyncer rules export_all_rules --zip --include-hosts

import_rules reads such an archive directly, there is no need to unpack it.

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 Secret Store (formerly 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. Users restricted to accounts or templates can neither export nor import this type.
./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 from before version 4.5), 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.