MC4Y CMDB: installing agents and crawlers
=========================================

This guide takes you through the installation step by step. No prior knowledge is needed. Every step says
what to do, what you will see afterwards, and how to check that it worked.

Last updated: October 2026. Licence: GPL-3.0-or-later.


CONTENTS
--------
 1. Which way suits me?
 2. The packages – download links
 3. What you need (per system)
 4. Step 1: create a setup key in the suite
 5. Step 2: download and unpack the package
 6. Step 3: install
    6.1  Windows 10 and Windows 11
    6.2  Windows Server 2016 and newer
    6.3  Linux (Ubuntu, Debian, Mint, Fedora, RHEL, openSUSE, Arch)
    6.4  Raspberry Pi 4 and 5
    6.5  Raspberry Pi 3 (with pi-hole)
    6.6  macOS 12 and newer
    6.7  Android (Termux)
    6.8  Home Assistant (its own operating system)
    6.9  Many Windows computers at once
 7. Step 4: how to check that it worked
 8. Common problems
    8.1  The virus scanner reacts
    8.2  The firewall blocks the connection
    8.3  There is a proxy in between
    8.4  The certificate is not trusted
    8.5  Python is missing
    8.6  “Setup key invalid”
    8.7  No systemd
 9. Updating and removing
10. For professionals


1. WHICH WAY SUITS ME?
----------------------
There are three programs. You can use one or several.

AGENT – on a computer you manage yourself.
  It reports what is inside this computer: manufacturer, model, serial number, operating system, processor,
  memory, disks, network cards, installed programs, running services, shares.
  This is the most accurate way. Use it for your own computers and servers.

CRAWLER – for devices where you cannot install anything.
  It scans the networks you enter in the suite and finds printers, switches, routers, cameras, network
  storage and other people's computers. It only determines whether a device answers, what it is called and
  which MAC address it has – it never signs in anywhere and never tries passwords.
  One crawler per network is enough.

HOME ASSISTANT INTEGRATION – if you use Home Assistant.
  It reports the Home Assistant machine and the devices Home Assistant manages.

All three deliver INVENTORY DATA ONLY. No user names, no sign-ins, no file contents.
The data goes to your own suite and nowhere else.


2. THE PACKAGES – DOWNLOAD LINKS
--------------------------------
Agents and crawlers for Windows, Linux, Raspberry Pi, macOS and Android:

    https://www.my-coaching4you.de/downloads/experimentell/software/mc4y-erkennung.zip

Home Assistant integration:

    https://www.my-coaching4you.de/downloads/experimentell/software/mc4y-cmdb-homeassistant.zip

Setting up many Windows computers at once (deploy helper):

    https://www.my-coaching4you.de/downloads/experimentell/software/mc4y-verteiler.zip

Everything at once (suite, tools, taskbar and these three packages in one file):

    https://www.my-coaching4you.de/downloads/experimentell/software/mc4y-all.zip

You will find the same packages inside the suite under  Administration › CMDB › 📡 Discovery  – the
download there already knows your suite address and includes it in the package.

Note: the packages are published under “Experimental – to try out”. They are being tried before they move
to “Resources and downloads”.


3. WHAT YOU NEED (PER SYSTEM)
-----------------------------
For every way:
  * A running MC4Y Productivity Suite you can reach over the network (https://…).
  * A setup key from that suite (step 1).
  * An OUTGOING connection to the suite. NOTHING incoming is needed – no open port on the device, no port
    forwarding.

In addition, per system:

  Windows 10 / 11 / Server 2016 and newer
    * Administrator rights on this computer.
    * Python 3.8 or newer. If it is missing, the installer can set it up for you (via winget).
      Why Python? Because since October 2026 the agent and the crawler run with Python on Windows too.
      A PowerShell program that regularly reads the installed software as the system account and sends it
      over the network looks like spyware to a virus scanner – that was exactly the problem before. See 8.1.

  Linux
    * root rights (sudo).
    * Python 3.8 or newer (almost always present; otherwise the script offers to install it).
    * systemd (present on Ubuntu, Debian, Mint, Fedora, RHEL, openSUSE and Arch). Without systemd a cron
      entry is created.

  Raspberry Pi
    * Raspberry Pi OS or Ubuntu, root rights, Python 3 (pre-installed).
    * Raspberry Pi 3: see 6.5 – there is one thing to know.

  macOS 12 (Monterey) and newer
    * Administrator rights and the password of your account.
    * Python 3.8 or newer. Check in the terminal: python3 --version
      If missing: install from https://www.python.org/downloads/macos/ (or: brew install python).

  Android
    * Termux and Termux:API, both from F-Droid (not from the Play Store – that version is outdated).

  Home Assistant
    * Access to the “config” folder (via the “File editor” add-on, Samba or SSH).


4. STEP 1: CREATE A SETUP KEY IN THE SUITE
------------------------------------------
 1. Sign in to your suite as an administrator.
 2. Go to  Administration › CMDB › 📡 Discovery.
 3. Under “Setup keys” click  “＋ New key”.
    Choose what it is for: “Agent”, “Crawler” or “both”.
 4. You now see a key made of letters and digits. Write it down, or click “⬇ Setup file” – you then get the
    file  mc4y-erkennung.json  which already contains the address and the key.

 Tip: put that file next to the installation script later. Then you do not have to type address and key.

 The key is only for setting up. Afterwards every device gets its own id; the setup key is not kept on the
 device.


5. STEP 2: DOWNLOAD AND UNPACK THE PACKAGE
------------------------------------------
WINDOWS
 1. Open the link from section 2 in your browser. The file lands in “Downloads”.
 2. Right-click  mc4y-erkennung.zip  and choose “Extract All…”, then “Extract”.
 3. You now see a folder  mc4y-erkennung  with the subfolders  windows  and  python.
 4. Put the file  mc4y-erkennung.json  (from step 1) into the folder  windows.

LINUX, RASPBERRY PI, macOS
 1. Open a terminal.
 2. Download and unpack:
        cd ~
        curl -LO https://www.my-coaching4you.de/downloads/experimentell/software/mc4y-erkennung.zip
        unzip mc4y-erkennung.zip -d mc4y-erkennung
        cd mc4y-erkennung/python
    (If unzip is missing:  sudo apt install unzip  or  sudo dnf install unzip,
     sudo zypper install unzip,  sudo pacman -S unzip.  On the Mac unzip is present.)
 3. Put  mc4y-erkennung.json  (from step 1) into this  python  folder.

 On the Mac a file sometimes loses its executable bit while unpacking, and macOS quarantines downloaded
 scripts. So on the Mac unpack and release it like this:
        ditto -x -k ~/Downloads/mc4y-erkennung.zip ~/mc4y-erkennung
        xattr -dr com.apple.quarantine ~/mc4y-erkennung
        cd ~/mc4y-erkennung/python


6. STEP 3: INSTALL
------------------

6.1  WINDOWS 10 AND WINDOWS 11
------------------------------
 1. Open the unpacked folder, then the subfolder  windows.
 2. Double-click  Agent-installieren.bat
    (for the crawler:  Crawler-installieren.bat).
 3. Windows asks whether changes may be made. Click “Yes”.
 4. If  mc4y-erkennung.json  is next to it, everything runs through. Otherwise address and key are asked for.
 5. If Python is missing you are asked whether it should be set up. Answer  y.
 6. You are asked whether a firewall rule for outgoing connections should be created. Usually this is not
    needed (Windows allows outgoing connections). Answer  y  if outgoing connections are blocked in your
    organisation.
 7. You now see:
        Done. The task MC4Y-CMDB-Agent runs every 5 minutes and at startup.
        Settings/log: C:\ProgramData\MC4Y-CMDB\agent
        Check the connection: "…\python.exe" "…\mc4y_agent.py" --pruefen

 Prefer the command line? Then in a PowerShell:
        cd "$HOME\Downloads\mc4y-erkennung\windows"
        Get-ChildItem *.ps1 | Unblock-File
        powershell -ExecutionPolicy RemoteSigned -File .\installieren.ps1 -Sprache en
 “Unblock-File” removes the mark Windows puts on files from the internet; “RemoteSigned” is the
 usual setting that runs local scripts. Both apply to these files and this call only and change
 nothing on your system. (Double-clicking Agent-installieren.bat does both for you.)

6.2  WINDOWS SERVER 2016 AND NEWER
----------------------------------
Exactly as 6.1, with two special points:

 * On a server winget is often absent. Install Python beforehand from
   https://www.python.org/downloads/windows/  (“Windows installer (64-bit)”) and tick “Install for all
   users”. Or pass the path to the installer:
        powershell -ExecutionPolicy RemoteSigned -File .\installieren.ps1 -Python "C:\Program Files\Python313\python.exe" -Sprache en
 * Python should be installed machine-wide (not only for your account), because the task runs as the
   system account. The installer tells you when that is not the case.

On a server the crawler usually makes sense as well – it runs all the time and reaches the whole network:
        powershell -ExecutionPolicy RemoteSigned -File .\installieren.ps1 -Crawler -Sprache en

6.3  LINUX (UBUNTU, DEBIAN, MINT, FEDORA, RHEL, openSUSE, ARCH)
---------------------------------------------------------------
 1. Open a terminal and change into the  python  folder (step 2).
 2. Set up the agent:
        sudo sh installieren.sh --lang en
    Set up the crawler:
        sudo sh installieren.sh --crawler --lang en
    Without the file mc4y-erkennung.json pass address and key:
        sudo sh installieren.sh --adresse https://suite.your-company.example/ --schluessel ABCD1234 --lang en
 3. Enter your password (no characters are shown).
 4. If Python 3 is missing the script asks whether to install it, naming the right command for your system:
        Ubuntu, Debian, Mint, Raspberry Pi OS   apt-get install -y python3
        Fedora, RHEL, Rocky, AlmaLinux          dnf install -y python3
        openSUSE, SLES                          zypper --non-interactive install python3
        Arch, Manjaro, EndeavourOS              pacman -S --noconfirm python
        Alpine                                  apk add python3
 5. You now see:
        Done. The service mc4y-cmdb-agent is running and starts on boot.
        Log: /etc/mc4y-cmdb/agent/protokoll.txt
        Check the connection: sudo python3 /opt/mc4y-cmdb-agent/mc4y_agent.py --pruefen

 Want to see what would happen first? Then:
        sh installieren.sh --probelauf --lang en
 This changes nothing and needs no root rights.

6.4  RASPBERRY PI 4 AND 5
-------------------------
Exactly as 6.3. Raspberry Pi OS and Ubuntu come with Python 3; nothing has to be prepared.
The Pi is listed in the CMDB as a single-board computer and reported with its model name
(for example “Raspberry Pi 5 Model B Rev 1.0”).

A Raspberry Pi is a good place for the CRAWLER: it runs around the clock and uses little power.
        sudo sh installieren.sh --crawler --lang en

6.5  RASPBERRY PI 3 (WITH pi-hole)
----------------------------------
Important: a current Ubuntu no longer runs properly on a Raspberry Pi 3 – the machine is too weak for it.
That is no problem for the agent:

 * Use  Raspberry Pi OS  there (32 or 64 bit). It comes with a current Python 3 and systemd.
 * If  pi-hole  runs on the device, everything needed is already there – pi-hole itself builds on
   Raspberry Pi OS. Simply install the agent or crawler alongside it:
        sudo sh installieren.sh --lang en
   or
        sudo sh installieren.sh --crawler --lang en
 * The agent and the crawler do not get in pi-hole's way: they open no ports and do not listen on port 53
   or 80. The crawler queries other devices from outside while pi-hole keeps answering DNS requests.
 * On a Pi 3 the crawler is a little slower. Prefer small networks there (a single /24) and do not let the
   run happen more often than hourly (adjustable in the suite).

 Check what is present first:
        python3 --version        (3.8 or newer? then you are fine)
        cat /etc/os-release      (shows Raspberry Pi OS or Debian)

6.6  macOS 12 AND NEWER
-----------------------
 1. Open the terminal (Command key + space, type “Terminal”, press Return).
 2. Change into the  python  folder (step 2, unpack with ditto and xattr).
 3. Start it – always with  bash  in front, never by double-clicking:
        bash installieren-macos.command --lang en
    For the crawler:
        bash installieren-macos.command --crawler --lang en
 4. The script obtains administrator rights itself. You will see:
        Administrator rights are required. Please enter your password (no characters shown).
    Type your password and press Return. No dots appear – that is normal.
 5. You now see:
        Done. The service is running and starts at login.

 If Python is missing the script says so and names the way (python.org or Homebrew). Then start again.

6.7  ANDROID (TERMUX)
---------------------
 1. Install  Termux  and  Termux:API  from F-Droid (https://f-droid.org).
 2. In Termux:
        pkg update
        pkg install python termux-api unzip
        termux-setup-storage          (Android asks for file access – allow it)
 3. Fetch and unpack the package:
        cd ~
        curl -LO https://www.my-coaching4you.de/downloads/experimentell/software/mc4y-erkennung.zip
        unzip mc4y-erkennung.zip -d mc4y-erkennung
        cd mc4y-erkennung/python
 4. Set it up:
        bash installieren-termux.sh --adresse https://suite.your-company.example/ --schluessel ABCD1234 --lang en
 5. You now see a message that the run happens via the Termux scheduler.

 On Android there is only the agent, no crawler.

6.8  HOME ASSISTANT (ITS OWN OPERATING SYSTEM)
----------------------------------------------
For Home Assistant OS (the ready-made image) there is a dedicated integration. You need neither Python
nor an installation script there.

 1. Download  mc4y-cmdb-homeassistant.zip  (link in section 2) and unpack it.
 2. You will see a folder  custom_components  with the subfolder  mc4y_cmdb.
 3. Copy the folder  mc4y_cmdb  into the folder  config/custom_components  of your Home Assistant
    installation. Ways to get there:
      * “File editor” add-on (easiest): open it in the menu on the left, create the folder, upload files.
      * “Samba share” add-on: open \\<address-of-home-assistant>\config in Windows Explorer.
      * “Advanced SSH & Web Terminal” add-on: copy the files with scp.
    If  config/custom_components  does not exist yet, create it.
 4. Restart Home Assistant:  Settings › System › ⋮ (top right) › Restart.
 5. Go to  Settings › Devices & services › ＋ Add integration,  search for “MC4Y CMDB” and select it.
 6. Enter the address of your suite and the setup key.
 7. You now see the integration with a note about the last report.

 The integration reports the Home Assistant machine and the devices Home Assistant manages.

6.9  MANY WINDOWS COMPUTERS AT ONCE
-----------------------------------
To bring the agent to many Windows computers, use the deploy helper. It sets up the machines remotely
(over WinRM) – you do not have to walk to every device.

 1. In the suite:  Administration › CMDB › 📡 Discovery › “Connect devices”.
 2. There you find the download  mc4y-verteiler.zip  and the file  verteiler.json.
 3. Unpack it, then double-click  Verteiler-starten.bat.  The view opens in your browser.
 4. Choose the role, enter the computer names (one per line), give an administrator account and password,
    click “Check connection”, then “Deploy”.

 For Linux, Raspberry Pi and Mac targets the helper can use SSH (provide a key file).

 Instead of the rollout helper you can also put the package on a network share once and install from
 there on each computer. Type the path into the address bar at the top of File Explorer in the long form
 (\\server\software\MC4Y-CMDB), not through a mapped drive letter such as Z: – Windows does not show
 mapped drives to a program running with administrator rights. The installation scripts convert a drive
 letter themselves; the long form is the more reliable way.


7. STEP 4: HOW TO CHECK THAT IT WORKED
--------------------------------------
Every program has a built-in check. It says in plain words what is allowed and what is missing – and it
changes nothing.

WINDOWS (in a PowerShell):
    & "C:\Program Files\Python313\python.exe" "C:\Program Files\MC4Y-CMDB-Agent\mc4y_agent.py" --pruefen
  The installer prints the exact command at the end; you can copy it from there.

LINUX, RASPBERRY PI, macOS:
    sudo python3 /opt/mc4y-cmdb-agent/mc4y_agent.py --pruefen
  (crawler:  …/mc4y-cmdb-crawler/mc4y_crawler.py --pruefen;  on the Mac the folder is
   /usr/local/mc4y-cmdb-agent)

You will then see something like:

    Checking the connection to the suite
      Address:       https://suite.your-company.example/
      Host:          suite.your-company.example   Port: 443   HTTPS
      Proxy:         none (direct)
      Name:          resolves to -> 192.168.10.20
      Connection:    open (6 ms)
      Certificate:   trusted, valid until Apr 26 12:00:00 2027 GMT
      Suite:         answers (interval 60 minutes)
      Result:        fine

If something else appears, section 8 helps – every line names the reason.

Other useful commands:
    --status     shows address, id and interval
    --jetzt      reports immediately (instead of waiting for the schedule)

And in the suite you see the device under  Administration › CMDB › 📡 Discovery  in the list of agents or
crawlers, with the time of the last report.


8. COMMON PROBLEMS
------------------

8.1  THE VIRUS SCANNER REACTS
Since October 2026 the agent and the crawler run with Python on Windows instead of PowerShell. The reason:
a PowerShell program that regularly reads the installed software as the system account and sends it over
the network matches the behaviour pattern of spyware exactly. Virus scanners with behaviour monitoring
(Bitdefender, for example) then step in – including during an update.

The present version avoids that pattern: readable Python files, no hidden process start, no downloading of
code, no autostart entry, no hidden window.

If your virus scanner still reacts:
 * Look in its quarantine to see which file is affected and restore it.
 * Add these folders as exceptions:
       C:\Program Files\MC4Y-CMDB-Agent
       C:\Program Files\MC4Y-CMDB-Crawler
 * A file that was in quarantine can sometimes only be overwritten after a restart. If the installation
   reports that, restart the computer and run it again.
 * Please change security settings yourself only – this package does not touch them.

8.2  THE FIREWALL BLOCKS THE CONNECTION
The check (section 7) says it clearly:

      Connection:    BLOCKED - No answer from … - the connection is probably dropped by a firewall.

What is needed:
 * AGENT: outgoing HTTPS to the suite (port 443 or the port in the address). Nothing incoming.
 * CRAWLER: additionally, into the networks to be scanned:
     – outgoing ICMP echo (“ping”),
     – outgoing TCP 22, 53, 80, 139, 443, 445, 515, 631, 3389, 5900, 8006, 9100, 23, 161,
     – outgoing UDP 161 only if you entered an SNMP community.
 * SERVER WITH THE SUITE: incoming HTTPS. Nothing else.

If a device does not answer a ping, that is not an error – the Windows firewall drops ping requests by
default. The crawler therefore always checks the usual TCP ports as well and still finds such devices. The
CMDB then records how it was found (“Found via: TCP 445”).

If you run an intrusion detection system: the crawler works at a throttled pace but can still look like a
network scan. Agree the schedule with your IT department and register the crawler as a known source.

Add the firewall rule on Windows later:
        powershell -ExecutionPolicy RemoteSigned -File .\installieren.ps1 -Firewall -Sprache en

8.3  THERE IS A PROXY IN BETWEEN
Normally the program finds the system proxy itself. The check shows which one is used. You can also give
it explicitly:
        --proxy http://proxy.your-company.example:3128
Or use none on purpose (for a suite inside your own network):
        --proxy ""
If the proxy requires authentication, the check reports “The proxy requires authentication (HTTP 407)”.
Then add the suite as an exception in the proxy.

If the check says “Something answers on … but not like an HTTPS server”, there is usually a captive portal
(guest Wi-Fi) or a proxy breaking up TLS in between.

8.4  THE CERTIFICATE IS NOT TRUSTED
This happens when your suite uses a self-signed certificate. The check says:

      Certificate:   NOT trusted - self signed certificate

Two ways:
 a) Pass the suite's certificate – it is in the suite under  /zertifikat/mc4y-suite.cer:
        --cafile "C:\Program Files\MC4Y-CMDB-Agent\mc4y-suite.cer"
    While installing you can hand it over directly:
        .\installieren.ps1 -Zertifikat .\mc4y-suite.cer -Sprache en
    The installer then also adds it to the trusted root store of Windows.
 b) Make the certificate known to all computers (on Windows via a group policy).

8.5  PYTHON IS MISSING
    Windows: the installer sets Python up via winget on request. If winget is missing (often on servers),
             install from https://www.python.org/downloads/windows/ (“Install for all users”).
    Linux:   the script names the command for your system and installs it on request (see 6.3).
    macOS:   https://www.python.org/downloads/macos/  or  brew install python
    Check:   python3 --version     or on Windows:  python --version

8.6  “SETUP KEY INVALID”
 * A key is valid for one role. A key for “Agent” does not set up a crawler.
 * Keys can be deleted in the suite. Create a new one (step 1).
 * Watch out for spaces at the start or end if you type the key by hand.
 * Easier: put the file  mc4y-erkennung.json  next to the installation script.

8.7  NO systemd
On systems without systemd (Alpine, or inside a container) the script creates a cron entry that starts a
run every five minutes. If cron is missing too, the script prints the command you can add to your own
scheduler.


9. UPDATING AND REMOVING
------------------------
UPDATING: download the new package, unpack it and simply run the installation again. The registration with
the suite is kept – the device keeps its id and its history in the CMDB. The earlier PowerShell files are
removed in the process.

REMOVING:
    Windows:      powershell -ExecutionPolicy RemoteSigned -File .\deinstallieren.ps1 -Sprache en
                  (crawler:  … .\deinstallieren.ps1 -Crawler -Sprache en)
    Linux/Pi:     sudo sh deinstallieren.sh --lang en          (or --crawler)
    macOS:        bash deinstallieren-macos.command --lang en  (or --crawler)
    Android:      bash deinstallieren-termux.sh
    Home Assistant: delete the integration, then remove the folder mc4y_cmdb and restart.

The device signs off from the suite while doing so. The settings are left in place so that a later
installation uses the same id. If you want them gone:
    Windows:  .\deinstallieren.ps1 -EinstellungenLoeschen
    Linux:    sudo sh deinstallieren.sh --einstellungen-loeschen

What is in the CMDB stays there. You can move the device to the recycle bin by hand.


10. FOR PROFESSIONALS
---------------------
Files and locations
    Windows   program    C:\Program Files\MC4Y-CMDB-Agent  (or -Crawler)
              data       C:\ProgramData\MC4Y-CMDB\<role>\einstellungen.json, protokoll.txt
              schedule   scheduled task “MC4Y-CMDB-Agent”, system account, every 5 minutes + at startup
    Linux     program    /opt/mc4y-cmdb-<role>/
              data       /etc/mc4y-cmdb/<role>/      (mode 0600)
              service    systemd unit mc4y-cmdb-<role>.service
    macOS     program    /usr/local/mc4y-cmdb-<role>/
              service    launchd  de.my-coaching4you.mc4y-cmdb-<role>
    Android   program    ~/mc4y-cmdb-<role>/, schedule via termux-job-scheduler

Options (same for agent and crawler)
    --adresse --schluessel --intervall <minutes> --cafile <file> --proxy <URL|""> --name <name>
    --einmal --jetzt --status --pruefen --abmelden --lang de|en
    crawler additionally: --community <SNMP community>

Options of the installation scripts
    Windows   -Crawler -Adresse -Schluessel -Intervall -Puls -Community -Zertifikat -Python
              -OhnePython -Firewall -OhneFirewall -OhneStart -Probelauf -Still -Sprache de|en
    Linux     --crawler --adresse --schluessel --intervall --cafile --community --ohne-start
              --probelauf --ja --lang de|en
    macOS     as Linux

What is reported
    Format  mc4y-inventar  version 1: system (manufacturer, model, serial number, category, domain),
    bs, cpu, speicher, netzwerk (name, MAC, IPv4/IPv6), datentraeger, partitionen, software, dienste,
    freigaben. NO user names, sign-ins or file contents.
    Per device the crawler reports: addresses, MAC, name (reverse DNS), open ports, how it was found and –
    only with a configured community – SNMP sysName/sysDescr.

Where the data comes from (no third-party packages, standard library only)
    Windows   SMBIOS via GetSystemFirmwareTable, registry, GetAdaptersAddresses, DeviceIoControl,
              service control manager – no WMI service, no PowerShell, no COM
    Linux     /sys/class/dmi, /proc, ip, dpkg/rpm/pacman, systemctl
    macOS     sysctl, ioreg, sw_vers, pkgutil, launchctl

Behaviour when something fails
    After a connection error the program waits 1, 2, 5, 10, 20, 30 and then 60 minutes. The same reason is
    written to the log only the first time and then every tenth attempt.

Changing the schedule
    In the suite under  Administration › CMDB › 📡 Discovery  per participant (“report every … minutes”,
    “report now”). The pace of the task/service is unaffected (default: check every 5 minutes).

No preset, no telemetry
    The packages contain NO suite address. Only the setup key (or the file mc4y-erkennung.json from your
    suite) determines where reports go. There is no connection to my-coaching4you.de, no update check and
    no usage statistics. The data stays in your network.
