Use CMDBsyncer as a Simple CMDB

CMDBsyncer can be used as a lightweight CMDB, even without a full external source system. In this mode, you create and maintain objects and hosts directly in the UI.

What CMDB mode does

If CMDB_MODE is enabled, you can manage CMDB-like data directly inside CMDBsyncer:

Create Objects (for example application, network, contact, group)
Create Templates and assign them to hosts/objects
Maintain custom fields (cmdb_fields) with your Data

Enable CMDB mode

In your local_config.py, enable CMDB mode:

config = {
  "CMDB_MODE": True,
}

Thats default enabled with Syncer Version 3.12.4.

Create hosts

Open Hosts.
Click Create.
Fill basic data:
hostname
object_type
available
optional cmdb_templates
Add or update CMDB fields in the form.
Save.

Hosts created this way are treated as CMDB-managed entries inside the syncer.

Import CSV / YAML and Manual add

Since 4.3, extended in 4.5

In CMDB mode the host list has two more buttons next to Export CSV:

Add hosts manually (until 4.4 called Bulk add hosts): paste hosts into a text field.
Import CSV / YAML (until 4.4 Import CSV): upload files.

Both open the same import preview before anything is created.

Renamed in 4.5: Bulk add is now Manual add

The Bulk add hosts button is now Add hosts manually, its dialog is called Manual add. It does what Bulk add did and understands more formats.

Import CSV / YAML

Upload either one CSV file or one or more YAML files (.yml, .yaml) at once. A CSV holds one host per row and needs a header row. Mixing CSV and YAML, or several CSV files, is refused.

A YAML file can hold one or several hosts:

a mapping of key: value pairs is one host,
a list of such mappings is one host per entry,
several documents separated by --- are one host (or list of hosts) each.

Every key becomes a column. Nested values (lists, mappings) are kept as JSON text.

hostname: srv01.example.com
location: dc1
api: https://api.example.com:6443
---
hostname: srv02.example.com
location: dc2
api: https://api2.example.com:6443

YAML that is not strictly valid is read once more by a tolerant parser for flat key: value files, which is the usual case for files carrying certificates: in a key: | block every following line belongs to the block, whatever its indentation, up to the next key: line at the start of a line. A PEM chain whose lines start at column 0 therefore comes out clean:

hostname: srv03.example.com
ca_certificate: |
  -----BEGIN CERTIFICATE-----
MIIBszCCAVmgAwIBAgIUexample
  -----END CERTIFICATE-----

If neither works, the error names the file and the first line that is not a key: value line.

Manual add

Paste the hosts into Hostnames, CSV, YAML or key/value list, optionally pick a template for all of them, and choose the Format:

Format	Content
Auto detect	Default. Text starting like YAML (`key: value`, `---` or `- key: value`) is read as YAML, text that looks like CSV as CSV, anything else as a host list
Host list	One hostname per line
CSV	CSV with a header row
YAML	As in the file import, hosts separated by `---`
Key/value list	One `key: value` per line, see below

A key/value list is meant for data copied out of a mail, a ticket or a spreadsheet:

a line is key: value, key=value or key<TAB>value,
it is split at the first separator, so api: https://api.example.com:6443 keeps its port,
an empty line or --- starts the next host,
key: | starts a block that runs to the next key: line; inside a block a line ending in = stays part of the value, so base64 certificate lines are kept.

hostname: srv01.example.com
api: https://api.example.com:6443
api_token=0123456789abcdef

hostname: srv02.example.com
api: https://api2.example.com:6443
api_token=fedcba9876543210

Auto detect never picks the key/value list, choose it explicitly.

The import preview

Every import and every manual add opens the preview first. It shows:

First row contains column names: for a CSV, untick it if the header is missing, the columns are numbered then.
Hostname column: which column holds the hostname (any header works, not just hostname). It is marked in the table.
Columns for the Secret Store (with the Secret Store role only): ticked columns do not become labels, their values are stored in the Secret Store, bound to the imported host, and rules reach them with {{ secret('column') }}. Columns whose name contains token, password, secret, certificate or cert are ticked for you.
Account: the account every host of this import (and with it its secrets) belongs to. Users restricted to accounts are only offered, and only allowed, their own accounts.
Assign template: optional, for every host without its own.

Up to 500 hosts the table is editable: change any value, add a column with Add column, and give single hosts their own template in the Template column ((as above) keeps the one picked above). Multi-line values such as certificates get a text area. A bigger import shows the first rows read only.

Every column other than the hostname, folder, lifecycle_state, inventory_<name> and the Secret Store columns becomes a host label (a label_<name> prefix is stripped for the Export CSV round-trip); inventory_<name> columns go to the inventory.

Start import creates or updates the hosts. The result names how many hosts were created and updated and how many secrets were stored. A restricted user cannot overwrite or take over an existing host outside their scope, and only assigns templates they are allowed to.

Secrets on the host overview

The overview of a host has a Secrets row with the Secret Store entries bound to it: key, kind, the reference for rules (e.g. {{ secret('api_token') }}), the value masked as ****** and links to the entry and, with the role to show values, to the value itself. See Secret Store.

Create objects

Open the admin UI.
Go to Objects → All Objects.
Click Create.
Fill:
Object Name
Object Type
CMDB Fields (key/value pairs)
Save.

Objects are stored as internal CMDB entries and can be used by rules, filters, but not host exports.

Use Account object mode (`cmdb_object`) for external imports

You can also import objects from external sources and still treat them as CMDB-managed entries in CMDBsyncer.

In the related account, enable object mode and set cmdb_object:

Enable cmdb_object
Ifis_object is enabled, the data can be used in rules, but will not exportet to systems like Checkmk
Set the matching object_type

Create and use templates (`cmdb_match`)

Templates are special CMDB objects used to standardize fields.

Open Objects → Templates.
Create or edit a template with:
template name
Add CMDB Fields
optional cmdb_match
Save.

cmdb_match is used for automatic assignment of templates to objects/hosts.

Format: label_key:label_value
Matching is exact (label key and value)
Example: site:dc1

When an object/host is created or processed and its labels match the expression, the template is added automatically to cmdb_templates.

Editing a template never re-assigns it on its own — which hosts carry a template stays as it is until you say otherwise.

To re-apply the matching after you changed a cmdb_match, select the template in Objects → Templates and run one of the two actions:

Re-apply to matching hosts: every object/host matching the pattern gets the template. Existing assignments are kept.
Re-apply and remove from non-matching hosts: the pattern becomes authoritative — every object/host that does not match loses the template. Use this to clean up after a changed cmdb_match, but keep in mind that it also removes templates that were assigned by hand.

A template without a cmdb_match is only ever assigned by hand and is skipped by both actions.

Assign or remove a template on selected hosts

In the Hosts list, select the hosts and pick an action from With selected:

Set Template: adds the template to every selected host. Templates the host already carries stay.
Remove Template: takes the template off every selected host. Its other templates stay, and hosts without the template are left alone.

A removed template whose cmdb_match still matches the host is added again the next time the host is imported or saved. To keep it off, change the cmdb_match or the host's labels.

The page size of the list goes up to 500 hosts, so larger groups can be selected in one go.

Archived templates

If you delete a template it is archived (soft-deleted) and stops taking effect: it no longer contributes any field to the hosts that carry it, it is not assigned to new objects/hosts and it cannot be picked in a form. The existing assignments are kept, so restoring the template from Archive brings its fields back. In the host list such a template is shown as (archived).

On the command line the same re-matching is available for all templates at once:

./cmdbsyncer sys update_cmdb

The command only adds templates to matching hosts, it never removes an assignment — use the Re-sync assignments on hosts action for that.

Merged attributes

By default a field only fills a gap: a value the host carries itself wins, and if several templates provide the same field the first one wins and the others are dropped.

For attributes that are really lists — contact groups, tags, service lists — that is the wrong rule. List them under Configuration → System Config → Merged attributes, one attribute key per entry. Such an attribute is then collected from every template the host carries, comma separated, and appended to the host's own value.

Example with contact_groups listed as merged: a host carries the templates base (contact_groups = ops), db (contact_groups = dba) and net (contact_groups = net) and exports contact_groups = ops,dba,net. Without the entry it exports contact_groups = ops.

The list is kept centrally on purpose: whether an attribute is a list is a property of the attribute, so no template edit can change how another template behaves. Values that are already comma-separated lists keep their order and duplicates are dropped, so the same entry in two templates does not show up twice. Changing the list clears the host attribute caches.

Jinja in template values

Field values on a template can use Jinja and reference the host's labels, inventory and HOSTNAME. Rendering happens when the template is merged into the host's attributes (i.e. at sync / debug time), so the template itself stores the raw expression.

Example field on a template:

description = Server {{ HOSTNAME }} for {{ environment }}

Applied to a host with label environment: prod, the resulting attribute is description = Server web01 for prod. Values without {{ ... }} are passed through unchanged. Missing variables render as empty strings (the syncer's default ignore mode).

Define default CMDB fields in local_config.py

You can predefine CMDB fields globally and per object type via CMDB_MODELS. Use application/config.py as the structure reference, then override it in local_config.py.

Example

config = {
  "CMDB_MODE": True,
  "CMDB_MODELS": {
    "host": {
      "ipaddress": {"type": "string"},
      "environment": {"type": "string"}
    },
    "network": {
      "cidr": {"type": "string"}
    },
    "all": {
      "owner": {"type": "string"},
      "managed": {"type": "boolean"}
    }
  }
}

How it works

all: fields added for every object/host type
<object_type> (for example host, network): fields only for that type
supported field types in forms:
string
boolean

When you save a host/object, missing configured fields are added automatically to cmdb_fields.

Approval workflow for critical labels

Operators can opt into four-eyes review for selected labels. List the label keys you want gated in local_config.py:

config = {
  "APPROVAL_REQUIRED_LABELS": ["criticality", "environment"],
}

Whenever a user without the Skip the approval queue when editing critical fields role saves a host with a change to one of those labels, the new value is queued in Approvals rather than written. Users with the Approve or reject pending field changes role decide on each entry; an approve applies the change to the host, a reject keeps the old value. The navbar shows a "N waiting" badge while the queue is non-empty.

Empty list (default) disables the workflow — every change goes straight to the host as before.

Saved Searches (filter presets)

The Hosts list shows a Saved Searches bar above the table. Apply your filters / search / sort, click Save current filter and pick a name — the URL fragment is captured as a named preset that re-opens the same view with one click. Presets are private to the operator that created them; ticking Share with other operators broadcasts them without giving away ownership (only the owner can delete a preset).

Manage all your presets from Settings → Saved Searches.

Data Quality dashboard

The Data Quality menu item opens a single read-only page that summarises the state of your fleet without scrolling through Hosts:

KPI scorecard at the top — live, stale (with %), hosts missing CMDB fields (with %), duplicate clusters and silent sources, each colour-coded so problems stand out at a glance.
Per-source breakdown — live count, stale count, archived count and the most recent last_import_seen per source account. Sources whose last delivery is older than 24 hours get an orange badge, older than 7 days a red one.
Per-object-type breakdown — same totals split by object_type, including the share of hosts with empty CMDB fields per type.
Most-missed CMDB fields — every configured field, sorted by how many hosts are missing it. Lets you fix the biggest gap first instead of working through a host-by-host list.
Lifecycle distribution across the live fleet.
Configured accounts with no live hosts — enabled, non-CMDB-store accounts that haven't delivered anything. Catches forgotten imports and silently broken auth.
Possible duplicate hostnames — hostnames normalised to lowercase alphanumerics so web01, WEB01.dc1 and web-01 all collide.
Hosts with empty CMDB fields — sample of hosts whose CMDB_MODELS[<type>] declares a field that is still blank.

Every table has a small ⬇ CSV link that streams that section as a CSV file, so findings can be handed off to ticketing without copy-pasting. The page exposes counts only — fixes happen on the regular Hosts list, the Archive view or via the sys mark_stale cron.

First-class CI types

Beyond Hosts, the syncer ships with three opinionated CI types you can create from Objects → All Objects:

Object Type	Default fields (override in `local_config.py`)
Service	`owner`, `criticality`, `sla`, `description`
Application	`owner`, `criticality`, `repo_url`, `description`
Location	`address`, `city`, `country`, `room`

Selecting one of these object types when creating an object pre-populates cmdb_fields from CMDB_MODELS[<type>], plus anything you put under CMDB_MODELS['all']. Empty defaults are added on save so the form stays predictable across upgrades.

The relation system above pairs naturally with these CI types — for example a Service runs_on an Application, an Application runs_on a Host, and the Host is member_of a Location.

Host relations (Impact Chain)

Hosts can carry typed links to other hosts. Open a host's Detail page to see the Relations block with all outgoing edges plus an Inbound (Impact Chain) section that lists every host pointing back at this one.

Available relation types:

Type	Inverse label	Use it for
`depends_on`	Required by	Service / app dependencies
`runs_on`	Hosts	VM/container → physical host
`member_of`	Contains	Host group / cluster / pool membership
`parent_of`	Child of	Logical parent / child hierarchy
`connects_to`	Reachable from	Network / replication links

Edges are stored on the outgoing side only — the inbound view is computed at render time, so renaming a relation type stays consistent without a second write.

Each entry tracks a source field (manual by default, plugins can set their own value) so manual links can be told apart from imported ones.

Stale data detection per account

Each account exposes two custom fields driven by the maintenance plugin:

stale_after_days — number of days without an import after which a host counts as Stale. 0 (default) disables the check.
auto_archive_when_stale — when True, stale hosts are soft-deleted automatically; when False (default) they only get a Stale badge and a stale_since timestamp.

The check runs from cron (Syncer: Mark Stale Hosts) or manually with:

./cmdbsyncer sys mark_stale <account>

A fresh import on a previously stale host clears the badge automatically.

Soft delete and Archive

Hosts that disappear from a source system are no longer hard-deleted. Instead they are archived: lifecycle state moves to Archived and a deleted_at timestamp is recorded. The same applies to the sys maintenance cleanup of stale hosts.

The Objects → Archive menu lists every archived host with the deletion timestamp and reason. From there you can:

Restore — bring a host back to lifecycle state Active. Use the per-row Since 4.3 Restore button for a single host, or the bulk Restore action for several at once.
Hard Delete — irreversible removal; admin role required.

Archived hosts are excluded from the regular Hosts list, exports and sync runs, but they still show up in the API for tooling that wants to audit removals.

Assigning the account of a host

Since 4.3

Every host is bound to a source account. You can set it in two places:

On the host edit form — the Account field is a dropdown. Saving a host no longer forces it to the internal CMDB account; you pick the account explicitly.
In bulk — select hosts in the list and use the Set Account action to reassign many at once.

Users that are restricted to accounts only ever see and can pick their own accounts here.

Lifecycle states

Every host carries a Lifecycle state independent of available:

Planned — the host is on the roadmap but not yet built.
Staged — built but not yet in production.
Active — in productive use (default for new and legacy hosts).
Decommissioned — taken out of service, kept for reporting.
Archived — read-only record, scheduled for eventual cleanup.

The state shows as a badge in the host list, can be filtered, and can be changed for many hosts at once via the Lifecycle: … bulk actions. Lifecycle changes are stamped with a timestamp and written into the host log.

Notes

Keep CMDB_MODE enabled if you want to maintain CMDB data in the UI.
After changing local_config.py, restart the application.
Start with a small set of required fields in CMDB_MODELS and extend gradually.