Checkmk Netbox Integration

Hi everyone,

Many years ago, I used i-doit (https://www.i-doit.com/) as a CMDB. Today, I use Netbox (https://netboxlabs.com/).

Back then, there was a way to integrate a CheckMK instance and thus display monitoring data directly on the object in the CMDB.

I’ve now built that for Netbox.

This solution is a first draft. It’s possible to connect one or more Checkmk instances.

Instructions on how to install and use the extension are available on my GitLab page and on PyPI.

I hope you find the extension helpful and that you’ll support me in its development by sharing your experiences.

Disclaimer

I did not develop these MKPs officially as an employee of Checkmk GmbH, but rather as a private individual.

Best regards,

Christian

3 Likes

I have to say that this changes the way I work a bit. Now I mainly have the CMDB open and jump to monitoring from there.
Configuration is still done in Checkmk. Analyses, too.
The whole thing is surprisingly fast.

Is anyone here in the community already using this?

netbox-checkmk-sync 0.1.0 (beta): NetBox as the source of truth for your Checkmk hosts – testers wanted!

Tired of keeping hosts in NetBox and Checkmk in sync by hand? netbox-checkmk-sync is a NetBox plugin that creates, changes and removes Checkmk hosts straight from NetBox – folders, labels, tags, parents, clusters, contact groups and downtimes included.

Nothing is written blindly: you see the pending changes, get an exact preview of every operation, and large changes need an approval (four-eyes principle optional). Every deploy is a revision you can compare and roll back, with an optional Git audit trail. It runs alongside your existing configuration and only touches hosts it owns; foreign hosts can be adopted, and leaving hosts can be handed back to manual configuration instead of being deleted.

Tested with Checkmk 2.5 and the 3.0 dailies (Pro/Ultimate) on NetBox 4.6 and 4.7, including distributed setups and a 1000-device scale test.

I’m looking for testers with real-world setups: installation, first deploy, daily use – anything that breaks or feels clumsy. Feedback and issues are very welcome!

:backhand_index_pointing_right: Checkmk extensions (public) / netbox_checkmk_sync · GitLab (mirror: Checkmk extensions (public) / netbox_checkmk_sync · GitLab )

A private project, not an official Checkmk product.

Hi Christian,

i try the first deployment now inside an existing system with CheckMK and Netbox already running :smiley:
Some small problems already solved^^

1 Like

Hi Andreas,

if you find any issues, please message them to me :wink:

I’m on vacation over the weekend and will have a look at Monday.

I will also try the first two deployments next week.

I’m thinking about an import feature for an existing Checkmk site. The present tags and lables could be challanging.

Best

Chris

I would not say that a complete import is needed, but a type of sync would be fine.
At the moment i cannot start as 95% of all objects already existing in booth systems.
Now i need to find a way to say - hey look for objects in CMK that have the same name and save these as managed.
One other point i would need i big systems is the possibility to switch of the folder sync.
Structure inside monitoring systems is completely different from structure inside Netbox.
Without folder sync it would work for my systems after the manual/automatic link of the existing objects.

For new objects i would configure some type of incoming folder inside CMK from where objects go to the correct folders. The direct folder sync will work good for new systems but not for the existing ones.

The adopt feature. Please check if the handbook is sufficient.

A bulk adopt feature is already on the roadmap.

There is also a training available. That might help.

:+1:

I will try to solve that folder thing. Or find a good solution.

netbox-checkmk-sync – roadmap

0.2.0 – coming in the next days

  • The mapping profile “Default” comes with the installation: you can create
    your first Checkmk instance right away.
  • Every form explains itself: a short introduction and a help text on every field.
  • Preview, deploy and report are much faster (a preview on a small site takes
    about 2 s instead of 7 s).
  • Fixes: placeholders in help texts, the order of the first setup steps.

0.2.1 – safer “Adopt”

  • Taking over an existing host no longer removes values that NetBox does not
    know: the monitoring site, the alias and the IPv6 address stay as they are.

0.3.0 – taking over an existing Checkmk site
Thanks to the feedback from Andreas: when most objects already exist in both
NetBox and Checkmk, you need more than adopting hosts one by one.

  • When you create an instance, you choose how you start:
    a) a new or empty site, or a site you build up in parallel (as today:
    NetBox creates its own folders, with occasional adoptions), or
    b) take over an existing site.
  • For b) there is a new takeover area:
    • an analysis first: hosts that match by name (and IP), hosts that exist only
      in Checkmk, objects that exist only in NetBox
    • adopt matching hosts in bulk, in stages, with progress
    • existing hosts stay in their folders; only new hosts go to a folder you
      choose (e.g. an “incoming” folder)
    • removing the integration hands the hosts back to manual configuration
      instead of deleting them
    • you will see up front what changes in Checkmk: every adopted host gets the
      integration’s label and lock
  • Smaller things: a new notification channel has all triggers preselected, and
    after creating an instance you land directly in the setup wizard.

Later

  • Faster previews for large sites (several thousand hosts).

Feedback is welcome!

1 Like

Sounds very promising :+1:

1 Like

0.2.0 is ready for testing

https://pypi.org/project/netbox-checkmk-sync/

0.2.1 released

Changelog

[0.2.1] - 2026-11-11

Fixed

  • Adopt no longer removes what NetBox does not know. A foreign host taken over with Adopt host lost its alias when the object had no description in NetBox, lost an IPv4 or IPv6 address NetBox does not have, and moved to the central site when NetBox named no monitoring site (in distributed monitoring: away from the remote site that monitored it). These values now stay as they are in Checkmk, unlocked, until NetBox has a value of its own; the preview names them. Hosts NetBox created itself behave as before.

[0.2.0] - 2026-11-10

Added

  • The mapping profile Default comes with the installation, so the first instance can be created right away; its defaults work for a start. It is created only when no profile exists: an update keeps its profiles, and a deleted or renamed Default does not come back.
  • Every form explains itself: the instance, tag group, notification channel and Git audit forms start with a short introduction (what it is, what you need, what happens on saving), and every field has a help text, e.g. Timeout (seconds), Batch size, Operating mode, Reservations, the webhook URL and the Git branch.

Changed

  • First setup in the right order. The menu lists Mapping profiles before Instances. Without a mapping profile the instance form says so at the top and links to a new profile; after saving it the browser comes back to the instance form. With exactly one profile the instance form preselects it. Before, the missing default profile only showed up as an error when saving the filled-in instance form.
  • The mapping profile form explains itself: a short introduction at the top, sections (folder, site and address; NetBox status; optional monitoring details) and a help text with an example on every field.
  • Faster preview, deploy and report. They read Checkmk with one client and ask for each collection only once: the setup check before every preview and deploy and the plan read the same ones. The independent reads go out three at a time: each request costs Checkmk 0.3-0.5 s of work, whatever it returns. The setup check no longer recomputes the pending changes of the whole instance when nothing they depend on (central site, version, monitoring sites) changed. A deploy without operations on tag groups, contact groups, memberships or rules no longer reads them back for the revision; they are as the plan read them.

Fixed

  • Help texts lost their placeholders: text in angle brackets such as <prefix> was taken for HTML and not shown (services as labels, tag group name and values, known hosts and commit authors of a Git remote); they now read {prefix}, {host} and so on.

netbox-checkmk-sync 0.3.0: take over an existing Checkmk site

What’s new in 0.3.0:

  • Take over an existing site: choose the starting point “Take over an existing site”
    when you create an instance. A new Takeover page analyses the site without changing
    anything: it matches NetBox objects and Checkmk hosts by name and address and shows what
    adopting changes on each host. You then adopt the matches in stages of 10 to 1000 hosts,
    with preview, the usual limits and approvals, and a progress bar. The analysis can be
    downloaded as CSV.
  • Folders only for new hosts: existing and adopted hosts stay in their folders, even
    after you move them in Checkmk; only new hosts follow the folder template. Switching back
    lists the hosts that would move and needs approval.
  • Safe defaults for a takeover: hosts are handed back to manual configuration instead of
    deleted when their object leaves NetBox.
  • Hint for duplicates: if a new host has the address of an existing Checkmk host under
    another name, the preview says so.
  • Smaller: new notification channels have all triggers preselected, a new instance opens
    the setup wizard, and some page layout fixes.

Requirements: NetBox 4.6 or 4.7; Checkmk 2.5 or 3.0, Pro or Ultimate (the Community
Edition is not supported)

Install: pip install netbox-checkmk-sync, setup steps in the README.
Upgrade: pip install --upgrade netbox-checkmk-sync, then manage.py migrate.

It is a beta: well covered by tests, but it has not run on a production installation yet,
so please try it on a test site first. Feedback and bug reports are very welcome, here in
this thread or as issues in the repository.

@andreas-doehler - let’s go :wink: I’m also testing at home. DON’T FORGET THE BACKUP!!!

1 Like

Earliest time to test is Friday - tomorrow offline at customer :rofl:

“at customer” - please not! This is in alpha state.

:rofl: not the testing, but I’m offline tomorrow

Andi… my heart! Don’t do this to me! :rofl:

There is another useful plugin to monitor netbox available:

published also on Checkmk Exchange

Ok first test with version 0.3.0 looks good. Onboarding is way easier with the default profile already existing. One thing i have a problem is the following.

  • inside CMK and Netbox i have the same hosts
  • i start the takeover and the analyse runs without error but shows 0 hosts inside NetBox
  • only the hosts existing inside CMK are found.

The created CSV file only shows the host objects from CMK but nothing from NetBox.
Where should i search for the problem?

Hi @andreas-doehler ,

the analysis only compares the NetBox objects that are assigned to the takeover instance.
It does not scan all of NetBox. If the NetBox side is empty, it is almost always one of these:

  1. The objects are not assigned to the instance yet. Set the custom field “Checkmk instance”
    to your takeover instance: device list > filter > select all > Edit Selected >
    Checkmk instance (the same for virtual machines and clusters).
  2. The instance’s filter (Roles, Platforms, Tags on the instance) leaves them out.
  3. Their NetBox status does not create a host. With the Default profile only “active”
    (monitored) and “offline”/“failed” (monitored in a downtime) count; “planned”, “staged”
    and “inventory” are “keep” and are skipped.

Please check: the instance’s “Changes” page lists every object the instance would manage.
If it is empty, the analysis has nothing to compare either. After assigning, click
“Analyse again” on the Takeover page. I hope that’s it.

You are right that the page should say this instead of just showing 0.
I take that into the next version.

Unfortunately, I won’t be able to test it until next weekend.

Chris