MC4Y-CMDB-Erkennung: Agenten und Crawler – Schritt für Schritt
==============================================================

Diese kleinen Programme tragen Geräte, installierte Software und Adressen automatisch in die CMDB der
MC4Y-Produktivitätssuite ein. Sie installieren und betreiben sie in IHREM eigenen Netz und in eigener
Verantwortung; die Daten bleiben in Ihrer Suite. Diese Anleitung ist für Einsteiger – gehen Sie den Block
für Ihr Gerät Schritt für Schritt durch.


AM EINFACHSTEN UNTER WINDOWS: DER GRAFISCHE INSTALLER
-----------------------------------------------------
Auf einem Windows-Rechner brauchen Sie dafür KEIN Terminal. Laden Sie aus Ihrer Suite das große Paket
„mc4y-suite.zip“ herunter (oder nehmen Sie das, mit dem Sie die Suite eingerichtet haben), entpacken Sie es und
machen Sie einen Doppelklick auf „Installer-starten.bat“. Wählen Sie dann die Kachel „Dieses Gerät an die CMDB
melden (Agent/Crawler)“, tragen Sie die Adresse Ihrer Suite und den Einrichtungsschlüssel ein (oder legen Sie die
Datei „mc4y-erkennung.json“ aus Schritt 1 neben den Installer – dann ist beides schon ausgefüllt), setzen Sie die
Häkchen „Agent“ und/oder „Crawler“ und klicken Sie „Einrichten“. Windows fragt einmal nach Administratorrechten.
Den Einrichtungsschlüssel holen Sie wie in Schritt 1 beschrieben. Das war alles – die Schritte unten brauchen Sie
unter Windows nur, wenn Sie es lieber von Hand machen.

Unter Linux, Raspberry Pi, macOS und Android gehen Sie wie unten beschrieben vor (dort ist der Weg im Terminal
genauso einfach; der grafische Installer ließe sich zwar auch starten, verlangt dort aber ebenfalls das Terminal).


WELCHER WEG PASST ZU MIR?
-------------------------
Entscheiden Sie zuerst, was Sie einrichten:

  • AGENT auf diesem Gerät – wenn GENAU DIESER Rechner (oder dieses Handy) in die CMDB soll. Ein Agent je
    Gerät; er meldet System, Hersteller/Modell/Seriennummer, Arbeitsspeicher, Datenträger und Partitionen mit
    freiem Platz, Betriebssystem und Version, installierte Software, Dienste, Freigaben, Netzwerkkarten.
  • CRAWLER für das Netz – auf EINEM Rechner. Er durchsucht die Netze, die Sie in der Suite eintragen, und
    findet Geräte auch ohne Agenten (mit weniger Angaben: IP- und MAC-Adresse, Name, Hersteller aus der MAC).
  • HOME ASSISTANT – wenn Sie ein Smart-Home mit Home Assistant betreiben und dessen Gerät samt der dort
    verwalteten Geräte sehen möchten. Eigenes Paket „mc4y-cmdb-homeassistant.zip“.

Am besten: auf den wichtigen Rechnern (Server, Arbeitsplätze) je einen Agenten, dazu einen Crawler für den
Überblick über das übrige Netz.

Für welches System gibt es was?
  • Windows 10/11, Windows Server .......... Agent + Crawler (Ordner „windows“)
  • Linux, auch Raspberry Pi 3/4/5 ......... Agent + Crawler (Ordner „python“)
  • macOS ab Version 12 .................... Agent + Crawler (Ordner „python“)
  • Android-Handy/Tablet ................... Agent in der App „Termux“ (Ordner „python“)
  • Home Assistant ......................... eigenes Paket „mc4y-cmdb-homeassistant.zip“


WAS SIE BRAUCHEN
----------------
  • Eine laufende MC4Y-Suite, deren Internet-Adresse Sie kennen (z. B. https://suite.ihre-firma.de/), und darin
    ein Konto mit VOLLZUGRIFF auf das Modul „CMDB“. Wenn Sie unsicher sind: Ihre Administratorin oder Ihr
    Administrator weiß das.
  • Auf dem Gerät Administrator- bzw. root-Rechte (um einen Dienst bzw. eine geplante Aufgabe einzurichten).
  • Für Linux, Raspberry Pi, macOS und Android: Python 3. Bei Linux/Raspberry Pi ist es meist schon da; für
    macOS und Android steht es unten im jeweiligen Schritt bzw. unter „Häufige Probleme“.
  • Dieses Paket, auf das Gerät heruntergeladen und entpackt.
  • Einen Einrichtungsschlüssel aus Ihrer Suite (Schritt 1).


SCHRITT 1 – DEN EINRICHTUNGSSCHLÜSSEL IN DER SUITE HOLEN (einmal, am Rechner mit der Suite)
------------------------------------------------------------------------------------------
  1. Melden Sie sich in der Suite an und klicken Sie oben rechts auf „Verwaltung“.
  2. Öffnen Sie das Modul „CMDB“ und darin oben den Reiter „📡 Erkennung“.
     Sie sehen jetzt die Liste der verbundenen Agenten und Crawler (anfangs leer) und die Knöpfe darunter.
  3. Klicken Sie auf „Einrichtungsschlüssel erzeugen“.
     Sie sehen jetzt eine lange Zeichenkette (den Schlüssel) und den Knopf „Einrichtungsdatei herunterladen“.
  4. Klicken Sie „Einrichtungsdatei herunterladen“. Es wird die Datei „mc4y-erkennung.json“ gespeichert.
  5. Nur für den Crawler: Tragen Sie unter „Netze“ die zu durchsuchenden Bereiche ein (z. B. 192.168.1.0/24,
     IPv6 ebenso), bei Bedarf einen Zeitplan und – falls Sie SNMP nutzen – je Netz die Community (Zugangswort).

  TIPP: Legen Sie die Datei „mc4y-erkennung.json“ später NEBEN das Installationsskript (in denselben Ordner).
  Dann übernimmt der Installer Adresse und Schlüssel von selbst, und Sie müssen nichts abtippen.


SCHRITT 2 – DAS PAKET AUF DAS GERÄT BRINGEN UND ENTPACKEN
---------------------------------------------------------
Kopieren Sie das heruntergeladene Paket auf das Gerät und entpacken Sie es. Wenn Sie in der Suite die Datei
„mc4y-erkennung.json“ geladen haben, legen Sie sie in den Ordner „windows“ bzw. „python“ (neben die
Installationsdateien). Danach weiter mit dem Block für Ihr System.


SCHRITT 3 – INSTALLIEREN
------------------------

=== WINDOWS 10/11 und Windows Server ===
  1. Entpacken: Rechtsklick auf die ZIP-Datei im Explorer → „Alle extrahieren …“ → „Extrahieren“.
     Sie sehen jetzt einen Ordner mit dem Unterordner „windows“ darin.
  2. Am einfachsten – per Doppelklick: Legen Sie die Datei „mc4y-erkennung.json“ aus Schritt 1 in den Ordner
     „windows“ (neben die übrigen Dateien). Doppelklicken Sie dann „Agent-installieren.bat“ – für den Crawler
     „Crawler-installieren.bat“. Adresse und Schlüssel übernimmt der Installer aus der Datei; Sie müssen nichts
     abtippen. Bestätigen Sie die Windows-Rückfrage nach Administratorrechten mit „Ja“; danach meldet das Fenster
     „eingerichtet“, und es entsteht eine geplante Aufgabe „MC4Y-CMDB-Agent“ bzw. „MC4Y-CMDB-Crawler“ (läuft als
     SYSTEM). Startet Windows SmartScreen eine Warnung, wählen Sie „Weitere Informationen“ → „Trotzdem ausführen“.
     Die Schritte 3–6 brauchen Sie dann nicht.
  3. Oder von Hand – PowerShell öffnen: Windows-Taste drücken, „PowerShell“ tippen, Eintrag „Windows PowerShell“ mit der
     Eingabetaste öffnen. (Admin ist NICHT nötig – das Skript fragt die Administratorrechte selbst ab.)
  4. In den Ordner „windows“ wechseln: Öffnen Sie den Ordner „windows“ im Explorer, klicken Sie oben in die
     Adressleiste, kopieren Sie den Pfad; tippen Sie in der PowerShell  cd  (mit Leerzeichen), fügen Sie den
     Pfad mit Rechtsklick ein und drücken Sie die Eingabetaste.
  5. Den Agenten einrichten – eine Zeile eingeben (Adresse und Schlüssel aus Schritt 1; oder, wenn
     mc4y-erkennung.json daneben liegt, beides weglassen):
         powershell -ExecutionPolicy Bypass -File .\installieren.ps1 -Adresse https://suite.ihre-firma.de/ -Schluessel <Schlüssel>
     Für den Crawler stattdessen:
         powershell -ExecutionPolicy Bypass -File .\installieren.ps1 -Crawler -Adresse https://suite.ihre-firma.de/ -Schluessel <Schlüssel>
     (Das „-ExecutionPolicy Bypass“ gilt nur für diesen einen Aufruf, damit Windows das Skript startet; es
     ändert nichts an Ihren Einstellungen.)
  6. Sie sehen jetzt: eine Windows-Rückfrage nach Administratorrechten – bestätigen Sie sie mit „Ja“. Danach
     meldet das Fenster „eingerichtet“, und es entsteht eine geplante Aufgabe „MC4Y-CMDB-Agent“ bzw.
     „MC4Y-CMDB-Crawler“, die als SYSTEM läuft.

=== LINUX und Raspberry Pi (3/4/5) ===
  1. Entpacken, z. B. im Terminal:  unzip ~/Downloads/mc4y-erkennung.zip -d ~/mc4y-erkennung
  2. In den Ordner „python“ wechseln:  cd ~/mc4y-erkennung/python
  3. Einrichten (Agent):
         sudo sh installieren.sh --adresse https://suite.ihre-firma.de/ --schluessel <Schlüssel>
     Für den Crawler zusätzlich  --crawler .
  4. Sie sehen jetzt: nach der Kennwortabfrage eine Bestätigung und einen neuen Dienst (systemd:
     mc4y-cmdb-agent bzw. mc4y-cmdb-crawler), der automatisch läuft.

=== macOS ab Version 12 ===
  1. Entpacken: Doppelklick auf die ZIP-Datei im Finder (Safari entpackt oft schon selbst).
  2. Terminal öffnen: Tastenkombination Befehl (⌘) + Leertaste, „Terminal“ tippen, Eingabetaste.
  3. In den Ordner „python“ wechseln: Tippen Sie  cd  (mit einem Leerzeichen danach) und ziehen Sie dann den
     Ordner „python“ aus dem Finder in das Terminal-Fenster – der Pfad wird eingefügt –, dann Eingabetaste.
  4. Einrichten (Agent):
         bash installieren-macos.command --adresse https://suite.ihre-firma.de/ --schluessel <Schlüssel>
     Für den Crawler zusätzlich  --crawler .
     Das Skript holt sich die nötigen Rechte selbst und fragt nach Ihrem Mac-Kennwort. Tippen Sie es ein –
     bei der Kennworteingabe erscheinen KEINE Zeichen und kein Punkt, das ist normal –, dann Eingabetaste.
  5. Sie sehen jetzt: eine Bestätigung und einen Dienst (launchd) für den Agenten bzw. den Crawler, der
     automatisch läuft.

=== ANDROID (Handy/Tablet) ===
  1. App „Termux“ installieren – am besten aus dem F-Droid-Store (https://f-droid.org); die Fassung aus dem
     Google-Play-Store ist veraltet. Zusätzlich die App „Termux:API“ aus derselben Quelle.
  2. Termux öffnen und einmalig eingeben:
         pkg install python termux-api
     Beide Fragen mit  y  bestätigen.
  3. Termux Zugriff auf den Speicher geben:
         termux-setup-storage
     und die Android-Rückfrage erlauben. Sie sehen jetzt einen Ordner „storage“ in Termux.
  4. Das entpackte Paket (den Ordner „python“) nach Termux holen, z. B. aus dem Download-Ordner:
         cp -r ~/storage/downloads/mc4y-erkennung/python ~/mc4y-erkennung
         cd ~/mc4y-erkennung
     (Falls Sie die ZIP nur heruntergeladen haben:  unzip ~/storage/downloads/mc4y-erkennung.zip  und dann in
     den Ordner „python“ wechseln.)
  5. Einrichten:
         bash installieren-termux.sh --adresse https://suite.ihre-firma.de/ --schluessel <Schlüssel>
  6. Sie sehen jetzt: eine Bestätigung; die Meldung läuft künftig über den Zeitplan von Termux.

=== HOME ASSISTANT ===
  Siehe die eigene Anleitung „LIESMICH.txt“ im Paket „mc4y-cmdb-homeassistant.zip“.

Sprache des Installers: unter Windows  -Sprache de|en , bei den übrigen  --lang de|en  (ohne Angabe nach der
Sprache des Systems).


SCHRITT 4 – SO PRÜFEN SIE, OB ES GEKLAPPT HAT
---------------------------------------------
  1. Öffnen Sie in der Suite wieder „Verwaltung › CMDB › 📡 Erkennung“. Nach kurzer Zeit erscheint dort der
     neue Agent bzw. Crawler mit Name, System und dem Zeitpunkt der letzten Meldung.
  2. Klicken Sie in der Zeile auf „Jetzt abfragen“ – der Agent meldet sofort.
  3. Öffnen Sie das Modul „CMDB“: Das Gerät (bzw. die vom Crawler gefundenen Geräte) steht nun in der Liste,
     mit Betriebssystem, Software und Adressen.


HÄUFIGE PROBLEME
----------------
Virenscanner meldet den Agenten oder verschiebt ihn in Quarantäne:
  Ein Programm, das die installierte Software liest und über das Netz meldet, ähnelt dem Muster eines
  Schnüffelprogramms – manche Virenscanner stufen es vorsorglich ein, auch wenn es keines ist.
  • Nehmen Sie den Ordner des Agenten bzw. seine geplante Aufgabe/seinen Dienst im Virenscanner als AUSNAHME
    auf. Prüfen Sie die Dateien vorher und laden Sie sie nur aus Ihrer eigenen Suite oder der offiziellen Quelle.
  • Erscheint der Agent nicht in der Erkennungsansicht, sehen Sie in der QUARANTÄNE des Virenscanners nach (er
    zeigt eine Meldung, und die Datei fehlt am erwarteten Ort).
  • Ein bereits gesperrter Dateirest lässt sich mitunter erst nach einem NEUSTART des Geräts entfernen.
  • Ausweg unter Windows: der PYTHON-Agent (Ordner „python“) statt des PowerShell-Agenten – er leistet dasselbe
    und fällt seltener auf.

Firewall:
  • AGENTEN brauchen nur AUSGEHEND HTTPS (Port 443) zu Ihrer Suite. Auf den Geräten muss KEIN Port geöffnet werden.
  • Der CRAWLER braucht ausgehend: Ping (ICMP, auch ICMPv6), die wenigen TCP-Ports, die er prüft, und – falls
    genutzt – SNMP (UDP 161) in die eingetragenen Netze. Denken Sie an IPv6.
  • Auf dem Suite-SERVER ist nur HTTPS eingehend nötig.
  • Ist der Ping im Netz gesperrt, bleiben manche Geräte für den Crawler unsichtbar.

Netzwerk-Schutzsysteme (IDS/IPS):
  Ein netzweiter Scan kann einem Angriff ähneln und wird dann gemeldet. Stimmen Sie den Crawler vorher mit den
  Netzverantwortlichen ab, legen Sie den Zeitplan möglichst außerhalb der Arbeitszeit und lassen Sie ihn
  gedrosselt laufen.

„Python 3 fehlt“ (macOS/Linux/Android):
  • Linux/Raspberry Pi:  sudo apt install python3   (bzw. das Paketwerkzeug Ihrer Distribution).
  • macOS: Python 3 von https://www.python.org/downloads/macos/ installieren und das Skript erneut ausführen.
  • Android: in Termux  pkg install python termux-api .

„Anmeldung abgelehnt“ / Schlüssel ungültig:
  Der Einrichtungsschlüssel gilt nur begrenzt. Erzeugen Sie in der Suite einen neuen (Schritt 1) und
  wiederholen Sie Schritt 3.

Keine Verbindung zur Suite:
  Stimmt die Adresse (mit https:// und Schrägstrich am Ende)? Erreichen Sie die Suite im Browser desselben
  Geräts? Blockiert eine Firewall ausgehendes HTTPS?

Selbst signiertes Zertifikat der Suite:
  Nutzt die Suite ein selbst signiertes Zertifikat, geben Sie die Zertifikatsdatei beim Installer an, damit die
  verschlüsselte Verbindung geprüft werden kann:
    • Windows:              … -Zertifikat mc4y-suite.cer
    • Linux/macOS/Android:  … --cafile /pfad/zu/mc4y-suite.pem
  Die TLS-Prüfung wird nie abgeschaltet.


AKTUALISIEREN UND ENTFERNEN
---------------------------
Aktualisieren: neues Paket entpacken und den Installationsbefehl aus Schritt 3 erneut ausführen.
Entfernen (meldet den Agenten auch in der Suite ab):
  • Windows:          powershell -ExecutionPolicy Bypass -File .\deinstallieren.ps1
  • Linux/Raspberry:  sudo sh deinstallieren.sh
  • macOS:            bash deinstallieren-macos.command
  • Android (Termux): bash deinstallieren-termux.sh
Für den Crawler hängen Sie unter Windows  -Crawler  an, unter Linux/Raspberry Pi und macOS  --crawler .


FÜR FACHLEUTE
-------------
  • Aufruf ohne die obige Einsteiger-Umhüllung:
      Windows:  .\installieren.ps1 -Adresse … -Schluessel …  [ -Crawler ] [ -Intervall <Min> ] [ -Puls <Min> ]
                [ -Community <SNMP> ] [ -Zertifikat <Datei.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 <Datei.pem> ] [ --lang de|en ]
    Liegt mc4y-erkennung.json neben dem Skript, ersetzt sie --adresse/--schluessel.
  • Keine verborgenen Prozesse, kein Nachladen, keine Verschleierung. Autostart nur über den vom Installer
    eingerichteten Dienst bzw. die geplante Aufgabe.
  • Einstellungen und Protokoll liegen lesbar: Windows C:\ProgramData\MC4Y-CMDB, sonst /etc/mc4y-cmdb bzw.
    ~/.config/mc4y-cmdb.
  • Übertragen werden nur Bestandsdaten – KEINE Benutzernamen, Anmeldungen oder Dateiinhalte. Je Agent eine
    eigene Kennung (auf dem Server nur als Prüfwert gespeichert); gesendet wird nur an die eingetragene Suite
    über HTTPS.
  • Das Intervall stellen Sie in der Suite ein (bzw. beim Installer mit --intervall <Minuten> / -Intervall). SNMP
    nur lesend, Community je Netz in der Suite. Der Crawler durchsucht nur die dort eingetragenen Netze.
  • Das Website-Paket enthält KEINE voreingestellte Adresse. Keine Telemetrie, keine Update-Prüfung bei
    my-coaching4you.de, keine Online-Herstellerabfrage (die Herstellerkennung kommt aus einer lokal
    hinterlegten Liste).


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