MC4Y CMDB discovery: agents and crawler – step by step
=======================================================

These small programs record devices, installed software and addresses in the CMDB of the MC4Y productivity
suite automatically. You install and run them in YOUR own network and under your own responsibility; the data
stays in your suite. This guide is for beginners – follow the block for your device step by step.


EASIEST ON WINDOWS: THE GRAPHICAL INSTALLER
-------------------------------------------
On a Windows computer you need NO terminal for this. Download the large package “mc4y-suite.zip” from your suite
(or use the one you set the suite up with), unpack it and double-click “Installer-starten.bat”. Then choose the
tile “Report this device to the CMDB (agent/crawler)”, enter the address of your suite and the setup key (or place
the file “mc4y-erkennung.json” from step 1 next to the installer – then both are already filled in), tick “Agent”
and/or “Crawler” and click “Set up”. Windows asks for administrator rights once. You obtain the setup key as
described in step 1. That is all – on Windows you only need the steps below if you prefer to do it by hand.

On Linux, Raspberry Pi, macOS and Android, follow the steps below (there the terminal way is just as simple; the
graphical installer could be started too, but it also requires the terminal on those systems).


WHICH WAY SUITS ME?
-------------------
First decide what you are setting up:

  • AN AGENT on this device – if EXACTLY THIS computer (or phone) should appear in the CMDB. One agent per
    device; it reports the system, manufacturer/model/serial number, memory, disks and partitions with free
    space, operating system and version, installed software, services, shares, network cards.
  • A CRAWLER for the network – on ONE computer. It scans the networks you enter in the suite and finds devices
    even without an agent (with fewer details: IP and MAC address, name, manufacturer from the MAC).
  • HOME ASSISTANT – if you run a smart home with Home Assistant and want that device plus the devices it
    manages in the CMDB. Separate package "mc4y-cmdb-homeassistant.zip".

Best: an agent on the important computers (servers, workstations), plus a crawler for the overview of the
rest of the network.

Which system gets what?
  • Windows 10/11, Windows Server .......... agent + crawler (folder "windows")
  • Linux, including Raspberry Pi 3/4/5 .... agent + crawler (folder "python")
  • macOS from version 12 ................. agent + crawler (folder "python")
  • Android phone/tablet .................. agent in the "Termux" app (folder "python")
  • Home Assistant ........................ separate package "mc4y-cmdb-homeassistant.zip"


WHAT YOU NEED
-------------
  • A running MC4Y suite whose web address you know (e.g. https://suite.your-company.example/), and an account
    there with FULL ACCESS to the "CMDB" module. If unsure, your administrator will know.
  • Administrator or root rights on the device (to register a service or scheduled task).
  • For Linux, Raspberry Pi, macOS and Android: Python 3. On Linux/Raspberry Pi it is usually already present;
    for macOS and Android see the step below or "Common problems".
  • This package, downloaded to the device and unpacked.
  • A setup key from your suite (step 1).


STEP 1 – GET THE SETUP KEY IN THE SUITE (once, on the computer with the suite)
------------------------------------------------------------------------------
  1. Sign in to the suite and click "Administration" at the top right.
  2. Open the "CMDB" module and, at the top, the "📡 Discovery" tab.
     You now see the list of connected agents and crawlers (empty at first) and the buttons below it.
  3. Click "Create setup key".
     You now see a long string (the key) and the button "Download setup file".
  4. Click "Download setup file". The file "mc4y-erkennung.json" is saved.
  5. For the crawler only: under "Networks", enter the ranges to scan (e.g. 192.168.1.0/24, IPv6 too), a
     schedule if needed, and – if you use SNMP – the community (access word) per network.

  TIP: later place "mc4y-erkennung.json" NEXT TO the installer (in the same folder). The installer then takes
  the address and key from it by itself, and you have nothing to type.


STEP 2 – BRING THE PACKAGE TO THE DEVICE AND UNPACK IT
------------------------------------------------------
Copy the downloaded package to the device and unpack it. If you downloaded "mc4y-erkennung.json" in the suite,
place it in the "windows" or "python" folder (next to the install files). Then continue with the block for
your system.


STEP 3 – INSTALL
----------------

=== WINDOWS 10/11 and Windows Server ===
  1. Unpack: right-click the ZIP file in Explorer → "Extract All …" → "Extract".
     You now see a folder containing the "windows" subfolder.
  2. Easiest – by double-click: put the file "mc4y-erkennung.json" from step 1 into the "windows" folder (next to
     the other files). Then double-click "Agent-installieren.bat" – for the crawler "Crawler-installieren.bat".
     The installer takes the address and key from that file; you type nothing. Confirm the Windows prompt for
     administrator rights with "Yes"; the window then reports "eingerichtet" (set up), and a scheduled task
     "MC4Y-CMDB-Agent" or "MC4Y-CMDB-Crawler" is created (running as SYSTEM). If Windows SmartScreen shows a
     warning, choose "More info" → "Run anyway". You can then skip steps 3–6.
  3. Or by hand – open PowerShell: press the Windows key, type "PowerShell", open "Windows PowerShell" with Enter.
     (Administrator is NOT required – the script requests admin rights itself.)
  4. Change into the "windows" folder: open the "windows" folder in Explorer, click the address bar at the top,
     copy the path; in PowerShell type  cd  (with a space), paste the path with a right-click, press Enter.
  5. Set up the agent – enter one line (address and key from step 1; or, if mc4y-erkennung.json is next to the
     script, leave both out):
         powershell -ExecutionPolicy Bypass -File .\installieren.ps1 -Adresse https://suite.your-company.example/ -Schluessel <key>
     For the crawler instead:
         powershell -ExecutionPolicy Bypass -File .\installieren.ps1 -Crawler -Adresse https://suite.your-company.example/ -Schluessel <key>
     ("-ExecutionPolicy Bypass" applies only to this one call, so Windows starts the script; it changes none of
     your settings.)
  6. You now see: a Windows prompt for administrator rights – confirm it with "Yes". Then the window reports
     "eingerichtet" (set up), and a scheduled task "MC4Y-CMDB-Agent" or "MC4Y-CMDB-Crawler" is created, running
     as SYSTEM.

=== LINUX and Raspberry Pi (3/4/5) ===
  1. Unpack, e.g. in the terminal:  unzip ~/Downloads/mc4y-erkennung.zip -d ~/mc4y-erkennung
  2. Change into the "python" folder:  cd ~/mc4y-erkennung/python
  3. Set up (agent):
         sudo sh installieren.sh --adresse https://suite.your-company.example/ --schluessel <key>
     For the crawler add  --crawler .
  4. You now see: after the password prompt, a confirmation and a new service (systemd: mc4y-cmdb-agent or
     mc4y-cmdb-crawler) that runs automatically.

=== macOS from version 12 ===
  1. Unpack: double-click the ZIP file in Finder (Safari often unpacks it for you).
  2. Open Terminal: Command (⌘) + Space, type "Terminal", Enter.
  3. Change into the "python" folder: type  cd  (with a trailing space) and then drag the "python" folder from
     Finder into the Terminal window – the path is inserted – then Enter.
  4. Set up (agent):
         bash installieren-macos.command --adresse https://suite.your-company.example/ --schluessel <key>
     For the crawler add  --crawler .
     The script obtains the rights it needs and asks for your Mac password. Type it in – NO characters and no
     dot appear while you type, that is normal – then Enter.
  5. You now see: a confirmation and a service (launchd) for the agent or the crawler that runs automatically.

=== ANDROID (phone/tablet) ===
  1. Install the "Termux" app – best from the F-Droid store (https://f-droid.org); the Google Play version is
     outdated. Also install the "Termux:API" app from the same source.
  2. Open Termux and enter once:
         pkg install python termux-api
     Confirm both questions with  y .
  3. Give Termux access to storage:
         termux-setup-storage
     and allow the Android prompt. You now see a "storage" folder in Termux.
  4. Bring the unpacked package (the "python" folder) into Termux, e.g. from the download folder:
         cp -r ~/storage/downloads/mc4y-erkennung/python ~/mc4y-erkennung
         cd ~/mc4y-erkennung
     (If you only downloaded the ZIP:  unzip ~/storage/downloads/mc4y-erkennung.zip  and change into the
     "python" folder.)
  5. Set up:
         bash installieren-termux.sh --adresse https://suite.your-company.example/ --schluessel <key>
  6. You now see: a confirmation; from now on reporting runs on Termux's own schedule.

=== HOME ASSISTANT ===
  See the separate "LIESMICH.txt" guide in the package "mc4y-cmdb-homeassistant.zip".

Installer language: on Windows  -Sprache de|en , on the others  --lang de|en  (without it, following the
system language).


STEP 4 – HOW TO CHECK IT WORKED
-------------------------------
  1. In the suite, open "Administration › CMDB › 📡 Discovery" again. After a short while the new agent or
     crawler appears there with name, system and the time of its last report.
  2. Click "Request now" in the row – the agent reports at once.
  3. Open the "CMDB" module: the device (or the devices found by the crawler) is now in the list, with
     operating system, software and addresses.


COMMON PROBLEMS
---------------
A virus scanner flags the agent or moves it to quarantine:
  A program that reads a computer's installed software and reports it over the network resembles the pattern of
  spyware – some virus scanners flag it as a precaution even though it is not.
  • Add the agent's folder, or its scheduled task/service, to the virus scanner as an EXCEPTION. Check the files
    beforehand and download them only from your own suite or the official source.
  • If the agent does not appear in the discovery view, look in the virus scanner's QUARANTINE (it shows a
    message, and the file is missing at the expected location).
  • A remnant of a file already locked can sometimes only be removed after a RESTART of the device.
  • Workaround on Windows: the PYTHON agent (folder "python") instead of the PowerShell agent – it does the same
    and draws less attention.

Firewall:
  • 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, incl. ICMPv6), the few TCP ports it checks and – if used – SNMP
    (UDP 161) into the networks you entered. Mind IPv6.
  • On the suite SERVER only inbound HTTPS is required.
  • If ping is blocked in the network, some devices stay invisible to the crawler.

Network protection systems (IDS/IPS):
  A network-wide scan can resemble an attack and then gets flagged. Agree the crawler with those responsible for
  the network beforehand, place the schedule outside working hours where possible and let it run throttled.

"Python 3 missing" (macOS/Linux/Android):
  • Linux/Raspberry Pi:  sudo apt install python3   (or your distribution's package tool).
  • macOS: install Python 3 from https://www.python.org/downloads/macos/ and run the script again.
  • Android: in Termux  pkg install python termux-api .

"Sign-in refused" / key invalid:
  The setup key is valid for a limited time only. Create a new one in the suite (step 1) and repeat step 3.

No connection to the suite:
  Is the address correct (with https:// and a trailing slash)? Can you reach the suite in the browser of the
  same device? Does a firewall block outbound HTTPS?

Self-signed suite certificate:
  If the suite uses a self-signed certificate, give the certificate file to the installer so the encrypted
  connection can be verified:
    • Windows:              … -Zertifikat mc4y-suite.cer
    • Linux/macOS/Android:  … --cafile /path/to/mc4y-suite.pem
  The TLS check is never switched off.


UPDATING AND REMOVING
---------------------
Update: unpack the new package and run the install command from step 3 again.
Remove (also de-registers the agent in the suite):
  • Windows:          powershell -ExecutionPolicy Bypass -File .\deinstallieren.ps1
  • Linux/Raspberry:  sudo sh deinstallieren.sh
  • macOS:            bash deinstallieren-macos.command
  • Android (Termux): bash deinstallieren-termux.sh
For the crawler, add  -Crawler  on Windows and  --crawler  on Linux/Raspberry Pi and macOS.


FOR EXPERTS
-----------
  • Call without the beginner wrapper above:
      Windows:  .\installieren.ps1 -Adresse … -Schluessel …  [ -Crawler ] [ -Intervall <min> ] [ -Puls <min> ]
                [ -Community <SNMP> ] [ -Zertifikat <file.cer> ] [ -OhneStart ] [ -Sprache de|en ]
      Linux/macOS/Android:  sh installieren.sh | bash installieren-macos.command | bash installieren-termux.sh
                --adresse … --schluessel … [ --crawler ] [ --intervall <min> ] [ --cafile <file.pem> ] [ --lang de|en ]
    If mc4y-erkennung.json sits next to the script, it replaces --adresse/--schluessel.
  • No hidden processes, no downloading of further code, no obfuscation. Autostart only through the service or
    scheduled task that the installer registers.
  • Settings and log sit in plain text: Windows C:\ProgramData\MC4Y-CMDB, otherwise /etc/mc4y-cmdb or
    ~/.config/mc4y-cmdb.
  • Only inventory data is transmitted – NO user names, logins or file contents. Each agent has its own identity
    (stored on the server only as a check value); it sends only to the entered suite over HTTPS.
  • Set the interval in the suite (or at the installer with --intervall <minutes> / -Intervall). SNMP read-only,
    community per network in the suite. The crawler scans only the networks entered there.
  • The website package contains NO preset address. No telemetry, no update check at my-coaching4you.de, no
    online manufacturer lookup (the manufacturer identifier comes from a list held locally).


License: GPL-3.0-or-later – MY COACHING FOR YOU (https://www.my-coaching4you.de)
