This article was created with the AI assistant Claude and published by Peter Hoenig.

A configuration database is only as good as the care it receives. For the CMDB in the MC4Y Suite you can import existing lists – from Excel, Active Directory, the DHCP server or Wireshark. It gets even easier when the inventory keeps itself up to date. For that there are two small helpers: an agent that runs on a device and reports its inventory, and a crawler that scans a network for reachable devices. Both only take stock.
One thing up front, because it matters to me: you – or the people responsible for IT in your organisation – set up agents and crawler in your own network and under your own responsibility. The programs send only to your own suite. The data stays in your network. Neither I nor any outside server ever gets to see any of it.
The agent – one device's inventory
An agent runs on a single device and reports its inventory: the system itself (manufacturer, model, serial number), the processor, the memory, the disks and their partitions with size and free space, the operating system and version, the installed software, running services and network cards – on Windows the shares as well. It sends this to the suite, which turns it into a component in the CMDB or updates an existing one. Fields you maintain by hand are left untouched – the agent only adds.
On Linux, since agent version 1.1, the CMDB keeps only explicitly installed packages as software of their own (on Ubuntu, roughly what apt-mark showmanual lists). The remaining dependencies are listed collapsed as “System packages” on the device – otherwise one computer would produce hundreds of software entries. An older suite does not know this distinction, so update the suite first and the agents afterwards.
The agent comes as a Python program for Windows, Linux, Raspberry Pi and macOS, for Android through the Termux app and as an integration for Home Assistant. On Home Assistant it additionally reports the names, manufacturers and models of the managed smart-home devices – but no states or readings.
The crawler – reachable devices on the network
The crawler runs on a single computer and scans the networks you enter in the suite – as an IPv4 or IPv6 network with its mask. It determines which devices are reachable, reads the name and MAC address from the operating system's neighbour table, derives the manufacturer from the MAC address (from a list held in the suite – without any lookup on the internet) and roughly guesses the category from the open services, a printer for instance. Nothing more: the crawler reports an inventory, it attacks nothing and attempts no login. It queries SNMP read-only and only with the credential (community) you store. On request it runs to a schedule, otherwise at the press of a button.
In your network, under your responsibility
Agents and crawler are meant for the IT staff of an organisation to install and operate in their network. They set everything organisation-specific themselves: the address of their own suite, the setup key, the networks to scan, the schedule and – if used – the SNMP credential. If someone downloads the package from my website, no address is preset; you enter the address of your own suite during setup.
That keeps the data where it belongs: agents and crawler send only to the one suite entered during setup. There is no telemetry, no “check for updates” call to my website and no connection to any other outside server. Whoever downloads and installs the programs runs them under their own responsibility – I receive nothing from other people's installations.
Setup – visible and with a key
Everything is set up in plain sight; nothing hides. In the suite you create a setup key and a small setup file under Business Support Tools › CMDB › 📡 Discovery, enter the networks and the schedule, download the matching package and run the installer. For the key, you choose under “For” whether it applies to “Agents and crawlers”, “agents only” or “crawlers only”, and click “Create setup key”. The key appears only once under “Setup key (visible only now)”; with “⬇ Setup file (mc4y-erkennung.json)” you download it right away as a file, together with the address. The installer registers a service (Linux/macOS) or a scheduled task (Windows) and places settings and a log in plain text. On first start the agent enrols with the key and receives its own identity; the key itself is stored by the suite only as a check value. In the same view you see which agents are connected, when they last reported and what they found – and you can request a report at once or remove an agent again. When creating it, you also set how long the key is valid (“Valid for (days, 0 = no expiry)”) and for how many devices (“At most … devices (0 = any)”). For each network you decide whether the crawler may “Create unknown devices” and which “Category for discovered devices” applies. You import a complete IEEE manufacturer list under “🏷 Manufacturer list (OUI)”; only common identifiers are built in.
The easiest way for a single computer is the suite’s graphical installer (the package you set the suite up with): on Windows with no terminal at all, by double-clicking Installer-starten.bat. There you choose the tile “Report this device to the CMDB (agent/crawler)”, enter the address and setup key – or place the setup file next to it, then both are already filled in – and tick the boxes for agent and/or crawler.
Several devices at once: “Connect devices”
Instead of setting up each computer individually, the IT team can roll out the agent – or the crawler – to several devices at once, from the suite under Business Support Tools › CMDB › 📡 Discovery › “Connect devices”, from a Windows workstation: Windows computers over WinRM, Linux, Raspberry Pi and macOS devices over SSH. You download a small deploy helper, start it, choose the operating system, enter the devices (one per line) and the account (for Windows an administrator account with password, for SSH the user and an SSH key), check the connection and roll out – with progress per device. Prerequisites: the file “verteiler.json” from the same view (button “⬇ Setup file (verteiler.json)”) has to lie next to “Verteiler-starten.bat”. On Windows targets WinRM has to be running – in a domain it usually is; otherwise run winrm quickconfig once in an administrator PowerShell on the target. For SSH targets you need the OpenSSH client on your workstation, and python3 and root rights on the targets (signed in as root, with NOPASSWD sudo or with a sudo password in the form). Any password you enter stays only in memory and is not stored.
Home Assistant is deliberately not set up remotely: if you choose it as the operating system, the view shows a step-by-step guide and the download instead of the rollout form. You then set up the integration once on the device itself, as described below.
Virus scanners and firewalls
A program that reads a computer's installed software and reports it over the network behaves rather like spyware – even though it is not. This is where I learned something: on Windows the agent first ran as a PowerShell program, and a PowerShell program that regularly reads the installed software as the system account and sends it is practically indistinguishable from spyware for a virus scanner with behaviour monitoring. Splitting the files did not help – at run time both parts ended up in one process anyway.
Since October 2026 the agent and the crawler therefore run with Python on Windows, exactly as on Linux and macOS. That removes the pattern: readable program files, no hidden process start, no hidden window, no downloading of code, no autostart entry. Only the installation script is still PowerShell – it sets things up and collects nothing itself. If Python is missing, the installer sets it up via winget, machine-wide, without asking.
If a virus scanner still steps in:
- Look in its quarantine to see which file is affected and restore it.
- Add the folders
C:\Program Files\MC4Y-CMDB-Agentand…-Crawleras an exception. - A file that was in quarantine can sometimes only be overwritten after a restart; the installation says so when that is the case.
- Security settings should be changed by your IT staff only – the packages do not touch them.
Firewall and built-in check
For the firewall: the agents need only outbound HTTPS (port 443) to your suite – no port needs to be opened on the devices. The crawler needs outbound ping (ICMP), the few TCP ports it checks and, where used, SNMP (UDP 161) into the networks you entered – and mind IPv6 here too. On the server where the suite runs, only inbound HTTPS is required.
A blocked ping is no obstacle, by the way: the Windows firewall drops ping requests by default, so the crawler always checks the usual TCP ports as well and still finds such devices. The CMDB records how each device was found. And because a network-wide scan can resemble an attack, network protection systems (IDS/IPS) may flag the crawler as suspicious: agree the crawler with those responsible for the network beforehand, place the schedule outside working hours where possible and let it run throttled.
So that nobody has to guess, every program has a built-in check: --pruefen says in plain words whether the name resolves, whether the connection is open or dropped by a firewall, whether the certificate is trusted, whether a proxy sits in between and whether the suite answers – and it names what needs to be allowed. If the connection fails during operation, the program does not keep knocking every minute but extends the interval (1, 2, 5, 10, 20, 30, 60 minutes) and writes the same reason to the log the first time and after that only on every tenth attempt.
If the suite rejects the enrolment, the program names the reason in one line – for instance that the setup key has expired, has been used up or is valid for crawlers only. Then create a new key in the suite. You can check beforehand whether a key fits, without using it up: … mc4y_agent.py --adresse https://suite.company.example/ --schluessel <key> --pruefen.
The certificate of your own suite
The certificate is the second common stumbling block: if you run the suite in your own network with a self-issued certificate, a freshly set up computer does not know it yet – and every program rightly refuses the connection. The cleanest way is to add the certificate once to the computer’s certificate store. You fetch the file at https://suite.company.example/zertifikat/mc4y-suite.cer:
- Windows (PowerShell as administrator; for many computers better via group policy):
Import-Certificate -FilePath .\mc4y-suite.cer -CertStoreLocation Cert:\LocalMachine\Root - Linux (Debian, Ubuntu): the
.cerfile is binary, butupdate-ca-certificatesexpects text (PEM) with the ending.crt. So convert it while storing it:sudo openssl x509 -inform DER -in mc4y-suite.cer -out /usr/local/share/ca-certificates/mc4y-suite.crt, thensudo update-ca-certificates. On Fedora and RHEL the file belongs in/etc/pki/ca-trust/source/anchors/(thensudo update-ca-trust), on openSUSE in/etc/pki/trust/anchors/(thensudo update-ca-certificates). - macOS:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain mc4y-suite.cer
After that the browser, the taskbar, the agent and the crawler need no file of their own. Where that is not possible, every program accepts the file individually – as --cafile, with the Windows installer as -Zertifikat .\mc4y-suite.cer, and in the graphical installer in the field “Certificate of the suite (optional)”. Since November 2026 it is even simpler: the setup file from the suite contains the public part of the certificate, and the agent and crawler take it over by themselves.
Without the setup file, --zertifikat-holen fetches the certificate and stores it only once its fingerprint matches the one the suite shows under Business Support Tools › CMDB › 📡 Discovery. If the connection still fails, the message names the reason together with a link to the certificate file. Verification is never switched off; the certificate is only added as a further trusted root.
The individual systems
The packages are available – as a trial version – under Experimental – to try out. Here are the direct links:
- Agents and crawlers for all systems: mc4y-erkennung.zip
- Home Assistant integration: mc4y-cmdb-homeassistant.zip
- Many devices at once (Windows over WinRM, Linux, Raspberry Pi and macOS over SSH): mc4y-verteiler.zip
In your own suite the download is right in the discovery view – there it already knows the suite address and includes it in the package. The package contains a step-by-step guide (README.txt, German LIESMICH.txt) with the prerequisites for each system. Every installer understands German and English (on Windows -Sprache de or -Sprache en, otherwise --lang de or --lang en).
Windows, Linux and Raspberry Pi
- Windows 10/11 and Windows Server 2016 and newer: agent and crawler as a Python program, set up as a scheduled task under the system account. The easiest way is a double-click on
Agent-installieren.batorCrawler-installieren.batin the package's “windows” folder: if the setup filemc4y-erkennung.jsonis next to it, you need not type anything; otherwise you give the suite address and the key at setup. On serverswingetis often absent – install Python from python.org beforehand (“Install for all users”) or point the installer to it with-Python <path>. - Linux: the Python agent, set up as a systemd service – for example
sudo sh installieren.sh --adresse https://suite.company.example/ --schluessel <key>. If Python is missing, the script names the right command for the system at hand and installs it on request:apt(Debian, Ubuntu, Mint, Raspberry Pi OS),dnf(Fedora, RHEL, Rocky, AlmaLinux),zypper(openSUSE, SLES),pacman(Arch, Manjaro) orapk(Alpine). Without systemd a cron entry is created. You set up the crawler with the same script and the switch--crawler, for examplesudo sh installieren.sh --crawler --adresse https://suite.company.example/ --schluessel <key>. - Raspberry Pi 4 and 5: as Linux, nothing to prepare – Python is pre-installed. A Pi is a good place for the crawler: it runs around the clock and uses little power.
- Raspberry Pi 3: a current Ubuntu no longer runs properly on a Pi 3 – the machine is too weak for it. Use Raspberry Pi OS there; if pi-hole runs on the device, everything needed is already present and the agent or crawler can simply be installed alongside it. They open no ports and do not listen on port 53 or 80, so they do not get in pi-hole's way.
macOS, Android and Home Assistant
- macOS from version 12: the Python agent, set up as a launchd service. Install Python 3.8 or later from python.org beforehand. macOS blocks downloaded scripts, so unpack the package in Terminal:
ditto -x -k ~/Downloads/mc4y-erkennung.zip ~/mc4y-erkennung, thenxattr -dr com.apple.quarantine ~/mc4y-erkennungandcd ~/mc4y-erkennung/MC4Y-CMDB-Erkennung/python. After that,bash installieren-macos.command --adresse …(crawler: with--crawler) – always withbashin front, never by double-clicking. - Android phones and tablets: through the Termux app (a Linux-like window on Android) together with Termux:API – both from F-Droid, not from the Play Store, whose version is outdated. In Termux, first run
pkg install python termux-api unzip, then, in the package’spythonfolder,bash installieren-termux.sh --adresse https://suite.company.example/ --schluessel <key>. Reporting runs on Termux’s own schedule; no separate background app is needed. On Android there is only the agent, no crawler. - Home Assistant (Raspberry Pi or Windows): as a dedicated integration, “MC4Y CMDB”. You enter the suite address and key in the Home Assistant interface – or place the setup file
mc4y-erkennung.jsonin the integration's folder, and both are already filled in. Amelden_jetztservice reports at the press of a button.
Removing agents and crawlers
On Windows, in the package’s “windows” folder, run powershell -ExecutionPolicy RemoteSigned -File .\deinstallieren.ps1 (crawler: with -Crawler); on Linux and the Raspberry Pi sudo sh deinstallieren.sh (or with --crawler); on the Mac bash deinstallieren-macos.command (or with --crawler); on Android bash deinstallieren-termux.sh. On Home Assistant, delete the “MC4Y CMDB” integration under “Devices & services” and then the folder custom_components/mc4y_cmdb. The device deregisters from the suite in the process; whatever is in the CMDB remains. The settings are kept for a later reinstallation – to remove them as well, add -EinstellungenLoeschen (Windows) or --einstellungen-loeschen (Linux).
What happens after an update or with a new agent?
Agent and crawler include their program version in every report, so the discovery view shows where an older one is still running. A new version reports at once during installation and replaces the entries an earlier version left on the same device – likewise for a renamed computer or a new agent on a known device. That way no duplicate programs appear; whatever came by hand, by import or from the crawler remains.
If a device in the CMDB’s recycle bin reports again, no new component is created: the CMDB skips the report and states the reason. An agent deregistered on deletion is turned away.
For a new agent on a computer running an older version, there are two ways:
- Start afresh: move the computer to the recycle bin in the CMDB, deleting the software installed only there and deregistering the agent; then uninstall the old agent and install it again with a new setup key. It enrols as a new component, and the addresses move across.
- Install over it: the agent keeps its identity and thus the same component. Software it now only reports as a system package is orphaned; “Clean up” in the CMDB moves it to the recycle bin, and a trial run shows the extent beforehand.
Here too: the suite first, then the agent. I have tested both ways on Ubuntu; Windows and macOS are still to come. Details on deletion and clean-up are in the post on the CMDB.
What the agents do not do
The boundary matters to me: the agents provide only the device's inventory data – no user names, no logins, no file contents, no keystrokes, nothing from the browser. The programs are open to read, obfuscate nothing and download nothing. They start on their own only through the service or task that the visible installer sets up. What they collect and where they send it is written in their settings file, which you can inspect at any time.
Where this leads
Discovery is part of the CMDB in the MC4Y productivity suite. What lands there automatically can be linked with the ITSM tool to incidents, problems and changes, and placed into the organisation's 8-level model with the 8EM modeller. I have tested the agent on Windows 11 against a real suite, and the agent, the crawler and the uninstallation on Ubuntu in the Windows Subsystem for Linux (WSL). Windows 10, Windows Server, the Home Assistant integration and the rollout over SSH are not tested; for the other systems the test on real devices is still to come. I welcome feedback from real networks.
Would you like to put your IT landscape in order and keep it up to date automatically? Get in touch – more on this under IT-supported organisational consulting.
Trademark note: Windows, Windows Server and Active Directory are trademarks of Microsoft Corporation; macOS is a trademark of Apple Inc.; Linux is a registered trademark of Linus Torvalds; Raspberry Pi is a trademark of Raspberry Pi Ltd; Android and Google Play are trademarks of Google LLC; Ubuntu is a trademark of Canonical Ltd; Home Assistant is a project of the Open Home Foundation; Termux and Wireshark are trademarks of their respective owners. The names are used descriptively only; there is no connection with the trademark owners.
Open or download the tools
- MC4Y CMDB: agents and crawlers (installation package)Download (93 KB)
- MC4Y CMDB: Home Assistant integration (installation package)Download (17 KB)
- MC4Y CMDB: connect devices (roll-out helper, installation package)Download (86 KB)
Thinking further
You can find more on this topic under resources and downloads – or talk to me directly in a free initial consultation.