Linuxapps/Mac2Ip
4
0
Fork 0
Code Issues 1 Pull Requests 2 Actions Packages Projects Releases 2 Wiki Activity

README.md und AGENTS.md auf mac2ip aktualisieren

Browse Source 
README.md: CLI-Nutzung, Konfigurationsdatei, Caching/TTL und Voraussetzungen
(ip/ping/nmap/sudo) dokumentiert; Template-Checkliste entfernt, generische
Paketierungs-/CI-CD-Abschnitte beibehalten.

AGENTS.md: Projektübersicht auf den 3-Stufen-Algorithmus und die neue
Modulstruktur umgeschrieben; veralteten Docker/TARGET_BIN-Hinweis entfernt
(keiner der Workflows baut tatsächlich ein Docker-Image); Paketierungs- und
Skript-Abschnitte um die neuen Laufzeit-Abhängigkeiten und das
Arch-Install-Skriptlet ergänzt.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0118Wbg95ADSDynYfci2qUjK
This commit is contained in:
DragonSlayer_14
2026-09-13 18:29:04 +02:00
co-authored by Claude Sonnet 5
parent 8f6570e385
commit b45afb921b
2 changed files with 155 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+34 -11
View File
@@ -6,9 +6,19 @@ Dieses Dokument dient als technischer Leitfaden und Kontextdokument für KI-Codi
## 1. Projektübersicht & Philosophie ## 1. Projektübersicht & Philosophie
Dieses Repository ist ein **Rust-Projekt-Template** für Linux-Anwendungen und CLI-Tools mit Fokus auf: **mac2ip** ist ein CLI-Tool, das zuverlässig die aktuelle IP-Adresse zu einer gegebenen MAC-Adresse im lokalen Netzwerk findet, über einen 3-stufigen Algorithmus:
1. **Cache** (`src/cache.rs`): globaler, systemweiter Cache auf Basis der `turso`-Crate (lokale Datei, Standard `/var/lib/mac2ip/cache.db`). Ein Treffer wird nur verwendet, wenn er nicht abgelaufen ist (TTL, `src/config.rs`) **und** die IP per Ping erreichbar ist.
2. **`ip neigh`** (`src/network.rs`): moderner Ersatz für `arp`. Treffer nur bei Ping-Erreichbarkeit.
3. **`nmap -sn`** (`src/network.rs`): ARP-/Ping-Scan der lokal angeschlossenen Subnetze. MAC-Adressen erscheinen in der nmap-Ausgabe nur mit Root-Rechten (Raw-Socket/libpcap), daher läuft dieser Schritt über `sudo nmap` (bzw. `nmap` direkt, falls schon root). Kein Treffer → Fehler ("nicht gefunden").
Die Orchestrierung dieser drei Schritte liegt in `src/resolver.rs`; `src/main.rs` ist nur ein dünner Entry-Point (CLI-Parsing via `src/cli.rs`, Konfiguration via `src/config.rs` + `config-ctdra`, Logging via `src/log.rs` + `logger-ctdra`).
Zur Laufzeit werden folgende System-Tools benötigt: `ip` (iproute2), `ping` (iputils), `nmap`, `sudo` (nur für Schritt 3, falls nicht schon root). Diese sind in den Paketierungs-Metadaten (`Cargo.toml`, siehe §3.2) als Abhängigkeiten hinterlegt.
Das Projekt basiert auf einem generischen **Rust-Projekt-Template** für Linux-Anwendungen/CLI-Tools mit Fokus auf:
- Automatisierte Multi-Architektur-Kompilierung (`x86_64`, `aarch64`, `i686`). - Automatisierte Multi-Architektur-Kompilierung (`x86_64`, `aarch64`, `i686`).
- Native Paketierung für Debian (`.deb`), Fedora/RHEL (`.rpm`) und Arch Linux (`.pkg.tar.zst`) sowie Docker-Container-Images. - Native Paketierung für Debian (`.deb`), Fedora/RHEL (`.rpm`) und Arch Linux (`.pkg.tar.zst`).
- Vollständig automatisierte CI/CD-Pipelines via Gitea Actions (kompatibel mit Forgejo / GitHub Actions). - Vollständig automatisierte CI/CD-Pipelines via Gitea Actions (kompatibel mit Forgejo / GitHub Actions).
- Automatisierte Sicherheits-Scans (Schwachstellen, Secrets) und Dependency-Updates. - Automatisierte Sicherheits-Scans (Schwachstellen, Secrets) und Dependency-Updates.
@@ -16,7 +26,6 @@ Dieses Repository ist ein **Rust-Projekt-Template** für Linux-Anwendungen und C
- **Sprache**: Rust (Edition 2024), Python 3 (für Hilfsskripte in `scripts/`). - **Sprache**: Rust (Edition 2024), Python 3 (für Hilfsskripte in `scripts/`).
- **Rust Toolchain**: Stable. - **Rust Toolchain**: Stable.
- **Zielplattform**: Linux (GLIBC-basiert, Cross-Kompilierung für `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`, `i686-unknown-linux-gnu`). - **Zielplattform**: Linux (GLIBC-basiert, Cross-Kompilierung für `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`, `i686-unknown-linux-gnu`).
- **Container**: Docker-Images werden zusätzlich zu den nativen Paketen gebaut und in die Gitea Container Registry veröffentlicht.
- **Sicherheits-Tooling**: Trivy, OSV-Scanner, TruffleHog (Secret-Scanning), Renovate (Dependency-Updates), Qodana (statische Codeanalyse). - **Sicherheits-Tooling**: Trivy, OSV-Scanner, TruffleHog (Secret-Scanning), Renovate (Dependency-Updates), Qodana (statische Codeanalyse).
- **Lizenz**: GPL-3.0-or-later (sofern nicht im abgeleiteten Projekt anders definiert). - **Lizenz**: GPL-3.0-or-later (sofern nicht im abgeleiteten Projekt anders definiert).
@@ -29,27 +38,40 @@ Dieses Repository ist ein **Rust-Projekt-Template** für Linux-Anwendungen und C
│ └── config.toml # Linker für Cross-Target-Kompilierung & Registry-Konfiguration │ └── config.toml # Linker für Cross-Target-Kompilierung & Registry-Konfiguration
├── .gitea/ ├── .gitea/
│ └── workflows/ │ └── workflows/
│ ├── main.yaml # CI/CD: Stabile Builds, Multi-Arch-Paketierung, Docker-Image, Release & Upload │ ├── main.yaml # CI/CD: Stabile Builds, Multi-Arch-Paketierung, Release & Upload
│ ├── testing.yaml # CI/CD: Preview-Builds, Docker-Image & Testing-Pakete │ ├── testing.yaml # CI/CD: Preview-Builds & Testing-Pakete
│ ├── unit-tests.yaml # CI: Unit-Tests für Pull Requests gegen 'testing' │ ├── unit-tests.yaml # CI: Unit-Tests für Pull Requests gegen 'testing'
│ ├── security-scan.yaml # CI: Trivy & OSV-Scanner (Schwachstellen/Misconfig/Secrets) │ ├── security-scan.yaml # CI: Trivy & OSV-Scanner (Schwachstellen/Misconfig/Secrets)
│ ├── trufflehog-scan.yaml # CI: TruffleHog Secret-Scan (inkl. Git-Historie) │ ├── trufflehog-scan.yaml # CI: TruffleHog Secret-Scan (inkl. Git-Historie)
│ └── renovate.yaml # CI: Wöchentlicher Renovate-Lauf für Dependency-Updates │ └── renovate.yaml # CI: Wöchentlicher Renovate-Lauf für Dependency-Updates
├── packaging/
│ ├── deb/postinst # Debian-Postinstall: legt /var/lib/mac2ip an
│ └── arch/mac2ip.install # Arch-Install-Skriptlet: legt /var/lib/mac2ip an
├── scripts/ ├── scripts/
│ ├── get-build-number.py # Ermittelt automatisch die nächste Revisions-/Build-Nummer │ ├── get-build-number.py # Ermittelt automatisch die nächste Revisions-/Build-Nummer
│ ├── package-arch.py # Erzeugt native Arch Linux .pkg.tar.zst Pakete │ ├── package-arch.py # Erzeugt native Arch Linux .pkg.tar.zst Pakete (inkl. optionalem Install-Skriptlet)
│ └── report-security-issue.py # Meldet Scan-Ergebnisse (Trivy/OSV/TruffleHog) als Gitea-Issue │ └── report-security-issue.py # Meldet Scan-Ergebnisse (Trivy/OSV/TruffleHog) als Gitea-Issue
├── src/ ├── src/
│ └── main.rs # Einstiegspunkt der Anwendung │ ├── main.rs # Einstiegspunkt (CLI-Parsing, Wiring)
│ ├── lib.rs # Modul-Wurzel (für Integrationstests)
│ ├── cli.rs # clap-Kommandozeilen-Definition
│ ├── config.rs # AppConfig + config-ctdra-Integration + CLI-Overlay
│ ├── log.rs # JSON-Modus-bewusster logger-ctdra-Wrapper
│ ├── mac.rs # MacAddress-Typ (Parsing/Kanonisierung)
│ ├── cache.rs # Globaler Turso-Cache (MAC -> IP)
│ ├── network.rs # ip neigh / ping / nmap: Exec- und Parse-Funktionen
│ ├── resolver.rs # 3-Stufen-Algorithmus (Orchestrierung)
│ └── output.rs # Human- und JSON-Ausgabe
├── tests/ # Integrationstests (pure Parsing-/Logik-Funktionen, kein Netzwerk/root/nmap nötig)
├── Cargo.toml # Projekt-Manifest & Metadaten für deb, rpm und arch ├── Cargo.toml # Projekt-Manifest & Metadaten für deb, rpm und arch
├── qodana.yaml # Konfiguration für JetBrains Qodana (statische Analyse) ├── qodana.yaml # Konfiguration für JetBrains Qodana (statische Analyse)
├── renovate.json # Renovate-Konfiguration (Gruppierung, Versions-Pins in Workflows) ├── renovate.json # Renovate-Konfiguration (Gruppierung, Versions-Pins in Workflows)
├── LICENSE # Lizenztext ├── LICENSE # Lizenztext
├── README.md # Benutzerdokumentation & Setup-Checkliste ├── README.md # Benutzerdokumentation
└── AGENTS.md # Dieses Agenten-Handbuch └── AGENTS.md # Dieses Agenten-Handbuch
``` ```
> **Hinweis:** `main.yaml`/`testing.yaml` bauen zusätzlich ein Docker-Image (`docker build .` mit `--build-arg TARGET_BIN=...`). Ein `Dockerfile` ist im Template noch **nicht** enthalten und muss von abgeleiteten Projekten ergänzt werden; der aktuell hartkodierte `TARGET_BIN`-Pfad (`.../release/mirror-package`) ist ein Platzhalter aus einem Referenzprojekt und muss beim Ableiten des Templates auf den tatsächlichen Binärnamen (`Cargo.toml` → `[package] name`) angepasst werden. > **Hinweis:** Dieses Projekt baut aktuell **kein** Docker-Image — keiner der Workflows unter `.gitea/workflows/` enthält einen Docker-Build-Schritt. Sollte das zukünftig ergänzt werden, muss ein `Dockerfile` hinzugefügt und der Binärname konsistent mit `[package] name` in `Cargo.toml` gehalten werden.
--- ---
@@ -68,12 +90,13 @@ Bei Änderungen an Binärnamen, Abhängigkeiten oder Beschreibungen müssen die
2. `[package.metadata.generate-rpm]` (für `cargo-generate-rpm`): 2. `[package.metadata.generate-rpm]` (für `cargo-generate-rpm`):
- `requires`, `assets`. - `requires`, `assets`.
3. `[package.metadata.arch]` (für `scripts/package-arch.py`): 3. `[package.metadata.arch]` (für `scripts/package-arch.py`):
- `pkgrel`, `arch`, `depends`, `optdepends`. - `pkgrel`, `arch`, `depends`, `optdepends`, optional `install_script` (Pfad zu einem pacman-Install-Skriptlet, siehe §3.3).
Ändert sich der Binärname (`[package] name`), muss auch der `TARGET_BIN`-Build-Arg im Docker-Build-Step von `main.yaml`/`testing.yaml` sowie das (abzuleitende) `Dockerfile` angepasst werden. Alle drei Blöcke listen bei mac2ip zusätzlich `sudo`, `iproute2`/`iproute`, `iputils`/`iputils-ping` und `nmap` als Laufzeit-Abhängigkeiten (benötigt für den 3-Stufen-Algorithmus, siehe §1). `[package.metadata.deb].maintainer-scripts` sowie `[package.metadata.generate-rpm].post_install_script` legen beim Paket-Install `/var/lib/mac2ip` mit den nötigen Rechten an (siehe §1, "Caching & TTL" in README.md).
### 3.3 Skripte in `scripts/` ### 3.3 Skripte in `scripts/`
- **Generizität**: Die Skripte dürfen keine hardcodierten Anwendungsnamen, spezifischen Abhängigkeiten oder projektspezifischen URLs enthalten. Alle Werte müssen dynamisch aus `Cargo.toml` (via `cargo metadata` oder Dateiparsing) oder Umgebungsvariablen (`BUILD_NUMBER`, `GITEA_URL`, `REPO`, `TOKEN`) ermittelt werden. - **Generizität**: Die Skripte dürfen keine hardcodierten Anwendungsnamen, spezifischen Abhängigkeiten oder projektspezifischen URLs enthalten. Alle Werte müssen dynamisch aus `Cargo.toml` (via `cargo metadata` oder Dateiparsing) oder Umgebungsvariablen (`BUILD_NUMBER`, `GITEA_URL`, `REPO`, `TOKEN`) ermittelt werden.
- **`package-arch.py`-Install-Skriptlet**: Liest optional `[package.metadata.arch].install_script` aus `cargo metadata` und bettet die referenzierte Datei pacman-konform als `<name>.install` (mit `install = <name>.install` in `.PKGINFO`) in das erzeugte `.pkg.tar.zst` ein — weiterhin vollständig metadatengetrieben, kein hartkodierter Anwendungsname im Skript selbst.
- **Python-Kompatibilität**: Verwende Standard-Python 3 ohne externe PyPI-Abhängigkeiten (nur Standardbibliothek: `json`, `subprocess`, `urllib`, `argparse`, `os`, `re`, `tempfile`, `tarfile` etc.). - **Python-Kompatibilität**: Verwende Standard-Python 3 ohne externe PyPI-Abhängigkeiten (nur Standardbibliothek: `json`, `subprocess`, `urllib`, `argparse`, `os`, `re`, `tempfile`, `tarfile` etc.).
- **`get-build-number.py`**: Ermittelt die nächste Build-/Revisions-Nummer nicht mehr rein lokal, sondern dynamisch über: - **`get-build-number.py`**: Ermittelt die nächste Build-/Revisions-Nummer nicht mehr rein lokal, sondern dynamisch über:
1. Gitea Releases API (Tag-/Asset-Namen), 1. Gitea Releases API (Tag-/Asset-Namen),
README.md
+121 -50
View File
@@ -1,29 +1,110 @@
# rust-template # mac2ip
Ein modernes Template-Projekt für Rust-basierte Linux-Anwendungen und Kommandozeilen-Tools (CLI). Ein Kommandozeilen-Tool (CLI), das zuverlässig die aktuelle IP-Adresse zu einer gegebenen MAC-Adresse im lokalen Netzwerk findet.
Dieses Template bietet eine vorkonfigurierte Umgebung für modernes Rust (Edition 2024), automatisierte Multi-Architektur-Kompilierung und native Paketierung für die gängigsten Linux-Distributionen (Debian/Ubuntu, Fedora/RHEL, Arch Linux) sowie vollständige CI/CD-Pipelines für Gitea Actions (kompatibel mit Forgejo und GitHub Actions). Dazu wird ein 3-stufiger Algorithmus verwendet:
1. **Cache**: Ein globaler, systemweiter Cache (für alle Nutzer dieses Rechners) wird geprüft. Ein Treffer wird nur verwendet, wenn er noch nicht abgelaufen ist (TTL) **und** die IP per Ping erreichbar ist.
2. **`ip neigh`**: Die Linux-Nachbartabelle (`ip neigh show`, der moderne Ersatz für den veralteten `arp`-Befehl) wird nach der MAC-Adresse durchsucht. Ein Treffer wird nur verwendet, wenn die IP per Ping erreichbar ist.
3. **`nmap`**: Als letzter Schritt wird ein Ping-/ARP-Scan (`nmap -sn`) der lokal angeschlossenen Subnetze durchgeführt. Da MAC-Adressen in der nmap-Ausgabe nur mit Root-Rechten sichtbar sind (ARP-Scans benötigen Raw-Socket-/libpcap-Zugriff), läuft dieser Schritt über `sudo nmap` (bzw. direkt `nmap`, falls das Programm bereits als root läuft). Wird auch hier keine erreichbare IP gefunden, bricht das Programm mit einem Fehler ("nicht gefunden") ab.
--- ---
## Features ## Features
- **Rust Edition 2024**: Moderner Rust-Sprachstandard. - **Zuverlässige MAC → IP-Auflösung** über Cache, `ip neigh` und `nmap`, jeweils mit Erreichbarkeitsprüfung per Ping.
- **Multi-Architektur-Kompilierung**: - **Globaler, systemweiter Cache** (via [`turso`](https://turso.tech), lokal-dateibasiert) mit konfigurierbarer TTL.
- `x86_64-unknown-linux-gnu` (64-Bit x86) - **Maschinenlesbare Ausgabe** über `--json` (unattended-Modus) — unterdrückt dabei alle sonstigen Log-Ausgaben.
- `aarch64-unknown-linux-gnu` (64-Bit ARM / ARM64) - **Vollständig über die Kommandozeile konfigurierbar**, mit Overlay-Kette CLI > Umgebungsvariable > Konfigurationsdatei > Standardwert.
- `i686-unknown-linux-gnu` (32-Bit x86) - **Funktioniert mit und ohne `sudo`** — Root-Rechte werden nur für den nmap-Schritt benötigt.
- **Linux-Paketierung out-of-the-box**: - **Rust Edition 2024**, Multi-Architektur-Kompilierung (`x86_64`, `aarch64`, `i686`), native Linux-Paketierung (`.deb`, `.rpm`, `.pkg.tar.zst`) und automatisierte CI/CD-Pipelines via Gitea Actions.
- **Debian / Ubuntu** (`.deb` via `cargo-deb`)
- **Fedora / RHEL / openSUSE** (`.rpm` via `cargo-generate-rpm`) ---
- **Arch Linux** (`.pkg.tar.zst` via mitgeliefertem `scripts/package-arch.py`)
- **Automatisierte CI/CD-Pipelines**: ## CLI-Nutzung
- `main`-Branch: Erstellt stabile Builds, ermittelt dynamisch Build-Nummern, paketiert für alle Architekturen, lädt Pakete in die Gitea Package Registry und erstellt Gitea Releases mit Dateianhängen.
- `testing`-Branch: Erstellt Preview-Builds und Pre-Releases mit Testing-Paketen. ```bash
- **Automatisierte Versions- & Build-Nummern**: mac2ip <MAC> [OPTIONEN]
- `scripts/get-build-number.py` fragt Gitea Releases, die Package Registry sowie lokale Artefakte ab, um Revisions-/Release-Nummern (z. B. `1.0.0-1`, `1.0.0-2`) automatisch zu erhöhen. ```
- **Vorkonfigurierte Cargo-Einstellungen**:
- `.cargo/config.toml` mit vorkonfigurierten Cross-Compilation-Linkern und Unterstützung für private/öffentliche Cargo Registries. Beispiel:
```bash
$ mac2ip aa:bb:cc:dd:ee:ff
aa:bb:cc:dd:ee:ff -> 192.168.1.42 (Quelle: cache)
```
Maschinenlesbare Ausgabe (unattended-Modus):
```bash
$ mac2ip aa:bb:cc:dd:ee:ff --json
{"status":"ok","mac":"aa:bb:cc:dd:ee:ff","ip":"192.168.1.42","source":"cache"}
```
Bei Fehlern (`status: "error"`) ist `source` nicht enthalten, dafür ein `error`-Feld mit einer Beschreibung; der Exit-Code ist in beiden Fällen ungleich 0 (`1`) bei Fehlschlag.
### Optionen
| Option | Umgebungsvariable | Standard | Beschreibung |
| :--- | :--- | :--- | :--- |
| `--json` | - | aus | Gibt das Ergebnis als einzeiliges JSON-Objekt aus; unterdrückt alle sonstigen Log-Ausgaben. |
| `--config <PATH>` | - | siehe unten | Benutzerdefinierter Pfad zur Konfigurationsdatei. |
| `--log-level <LEVEL>` | `MAC2IP_LOG_LEVEL` | `info` | Logging-Level: `error`, `warn`, `info`, `debug`. |
| `--cache-ttl-seconds <N>` | `MAC2IP_CACHE_TTL_SECONDS` | `1800` | Wie lange ein Cache-Eintrag als gültig angesehen wird (zusätzlich zur Ping-Prüfung). |
| `--cache-db-path <PATH>` | `MAC2IP_CACHE_DB_PATH` | `/var/lib/mac2ip/cache.db` | Pfad zur globalen Cache-Datenbankdatei. |
| `--nmap-timeout-seconds <N>` | `MAC2IP_NMAP_TIMEOUT_SECONDS` | `120` | Timeout für einen einzelnen nmap-Subnetz-Scan. |
| `--networks <CIDR,CIDR,...>` | `MAC2IP_NETWORKS` | Auto-Erkennung | Kommagetrennte Liste von Subnetzen für den nmap-Scan; überschreibt die automatische Erkennung über `ip route`. |
Die Überschreibungs-Reihenfolge ist immer: **CLI-Flag > Umgebungsvariable > Konfigurationsdatei > Standardwert.**
---
## Konfigurationsdatei
Die Konfiguration wird über [`config-ctdra`](https://gitea.creative-dragonslayer.de/Rust-Crates) verwaltet:
- Als **root** (bzw. beim nmap-Schritt via `sudo`): `/etc/mac2ip/config.toml`
- Als **normaler Nutzer**: `~/.config/mac2ip/config.toml`
- Oder explizit über `--config <PATH>`
Beispiel:
```toml
cache_ttl_seconds = 1800
cache_db_path = "/var/lib/mac2ip/cache.db"
log_level = "info"
nmap_timeout_seconds = 120
networks = []
```
Alle Felder sind optional (fehlende Felder verwenden den Standardwert) und können, wie oben beschrieben, zusätzlich per CLI-Flag oder Umgebungsvariable überschrieben werden.
---
## Caching & TTL
Der Cache liegt standardmäßig unter `/var/lib/mac2ip/cache.db` — **global für alle Nutzer des Rechners**, nicht pro Benutzerkonto. Verzeichnis und Datei sind bewusst world-writable (`0777`/`0666`), damit auch unprivilegierte Nutzer den Cache lesen und schreiben können, ohne dass mac2ip dafür Root-Rechte bräuchte.
Ein Cache-Treffer wird nur verwendet, wenn:
1. der Eintrag noch nicht älter als `cache_ttl_seconds` ist (Standard: 30 Minuten), **und**
2. die gespeicherte IP-Adresse aktuell per Ping erreichbar ist.
Die Ping-Prüfung ist die primäre Absicherung gegen veraltete Zuordnungen; die TTL ist eine zusätzliche Absicherung für den Fall, dass eine alte IP-Adresse inzwischen an ein anderes, ebenfalls erreichbares Gerät vergeben wurde (z. B. nach einem DHCP-Lease-Wechsel).
Kann das Cache-Verzeichnis beim Programmstart nicht angelegt/beschrieben werden (z. B. bei einem Entwicklungslauf ohne vorherige Paketinstallation), wird der Cache für diesen Lauf einfach deaktiviert (eine Warnung wird geloggt, im `--json`-Modus unterdrückt) — mac2ip führt den Lookup dann ohne Cache über `ip neigh`/`nmap` durch. Bei einer Installation über `.deb`/`.rpm`/`.pkg.tar.zst` wird das Verzeichnis automatisch mit den richtigen Rechten angelegt (siehe Paketierungs-Postinstall-Skripte unter `packaging/`).
---
## Voraussetzungen
Neben Rust/Cargo zur Laufzeit benötigt werden folgende System-Tools:
- `ip` (Paket `iproute2`) — für Schritt 2 (`ip neigh`) und die automatische Subnetz-Erkennung.
- `ping` (Paket `iputils`/`iputils-ping`) — für die Erreichbarkeitsprüfung.
- `nmap` — für Schritt 3.
- `sudo` — nur nötig, wenn Schritt 3 erreicht wird und das Programm nicht bereits als root läuft.
Im `--json`-Modus wird für Schritt 3 ausschließlich `sudo -n` (nicht-interaktiv) verwendet, damit das Programm niemals interaktiv nach einem Passwort fragt und dadurch ein Skript blockiert. Ist keine gültige sudo-Sitzung/NOPASSWD-Regel vorhanden, wird Schritt 3 abgebrochen und das Ergebnis als "nicht gefunden" zurückgegeben. Im interaktiven (Nicht-JSON-)Modus darf `sudo` regulär nach einem Passwort fragen.
--- ---
@@ -36,49 +117,39 @@ Dieses Template bietet eine vorkonfigurierte Umgebung für modernes Rust (Editio
│ └── workflows/ │ └── workflows/
│ ├── main.yaml # CI/CD-Workflow für stabile Releases (main-Branch) │ ├── main.yaml # CI/CD-Workflow für stabile Releases (main-Branch)
│ └── testing.yaml # CI/CD-Workflow für Pre-Releases (testing-Branch) │ └── testing.yaml # CI/CD-Workflow für Pre-Releases (testing-Branch)
├── packaging/
│ ├── deb/postinst # Debian-Postinstall: legt /var/lib/mac2ip an
│ └── arch/mac2ip.install # Arch-Install-Skriptlet: legt /var/lib/mac2ip an
├── scripts/ ├── scripts/
│ ├── get-build-number.py # Dynamische Ermittlung der nächsten Paket-Revisionsnummer │ ├── get-build-number.py # Dynamische Ermittlung der nächsten Paket-Revisionsnummer
│ └── package-arch.py # Erstellung von Arch Linux .pkg.tar.zst Paketen │ └── package-arch.py # Erstellung von Arch Linux .pkg.tar.zst Paketen
├── src/ ├── src/
│ └── main.rs # Quellcode & Einstiegspunkt der Anwendung │ ├── main.rs # Einstiegspunkt (CLI-Parsing, Wiring)
├── Cargo.toml # Cargo Manifest & Paketierungsmetadaten (deb, rpm, arch) │ ├── lib.rs # Modul-Wurzel (für Integrationstests)
├── LICENSE # Lizenzdatei (Standard: GPL-3.0-or-later) │ ├── cli.rs # clap-Kommandozeilen-Definition
├── AGENTS.md # Richtlinien und Leitfaden für KI-Coding-Agenten │ ├── config.rs # AppConfig + config-ctdra-Integration + CLI-Overlay
└── README.md # Projektdokumentation │ ├── log.rs # JSON-Modus-bewusster logger-ctdra-Wrapper
│ ├── mac.rs # MacAddress-Typ (Parsing/Kanonisierung)
│ ├── cache.rs # Globaler Turso-Cache (MAC -> IP)
│ ├── network.rs # ip neigh / ping / nmap: Exec- und Parse-Funktionen
│ ├── resolver.rs # 3-Stufen-Algorithmus (Orchestrierung)
│ └── output.rs # Human- und JSON-Ausgabe
├── tests/ # Integrationstests (pure Parsing-/Logik-Funktionen)
├── Cargo.toml # Cargo Manifest & Paketierungsmetadaten (deb, rpm, arch)
├── LICENSE # Lizenzdatei (Standard: GPL-3.0-or-later)
├── AGENTS.md # Richtlinien und Leitfaden für KI-Coding-Agenten
└── README.md # Projektdokumentation
``` ```
--- ---
## Checkliste zur Verwendung als Template
Wenn du ein neues Projekt aus diesem Template erstellst, gehe folgende Schritte durch:
1. **`Cargo.toml` anpassen**:
- `name`: Den Namen deiner Anwendung setzen.
- `version`: Initiale Version festlegen (z. B. `0.1.0`).
- `authors`, `repository`, `description`, `license`: Projektdaten eintragen.
- Paketierungsabschnitte prüfen:
- `[package.metadata.deb]`: `maintainer`, `copyright`, `section`, `extended-description` setzen.
- `[package.metadata.generate-rpm]`: `requires` anpassen.
- `[package.metadata.arch]`: `depends` und `optdepends` anpassen.
2. **`src/` implementieren**:
- Eigene Anwendungslogik in `src/main.rs` (bzw. Modulen / `src/lib.rs`) implementieren.
- Tests in `src/` oder `tests/` ergänzen.
3. **`.cargo/config.toml` prüfen**:
- Falls crates.io statt einer privaten Registry genutzt werden soll, den Standard-Registry-Eintrag anpassen oder auskommentieren.
4. **CI/CD Secrets konfigurieren**:
- In den Repository-Einstellungen von Gitea/Forgejo ein Secret `PACKAGE_TOKEN` (bzw. `GITEA_TOKEN`) mit Rechten für Pakete und Releases hinterlegen.
5. **Dokumentation aktualisieren**:
- `README.md` an die konkrete Funktionsweise deiner Anwendung anpassen.
---
## Lokale Entwicklung ## Lokale Entwicklung
### Voraussetzungen ### Voraussetzungen
- **Rust & Cargo** (aktuelle Stable-Version, Edition 2024 unterstützt) - **Rust & Cargo** (aktuelle Stable-Version, Edition 2024 unterstützt)
- **Python 3** (für Hilfsskripte in `scripts/`) - **Python 3** (für Hilfsskripte in `scripts/`)
- Zur Laufzeit: `ip`, `ping`, `nmap`, `sudo` (siehe "Voraussetzungen" oben)
- Für Cross-Compilation (optional): - Für Cross-Compilation (optional):
- `rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu i686-unknown-linux-gnu` - `rustup target add x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu i686-unknown-linux-gnu`
- Cross-Toolchains: `gcc-aarch64-linux-gnu`, `gcc-i686-linux-gnu` - Cross-Toolchains: `gcc-aarch64-linux-gnu`, `gcc-i686-linux-gnu`
@@ -126,6 +197,7 @@ Erstellt native Arch Linux-Pakete (`.pkg.tar.zst`), ohne dass `makepkg` oder ein
- Liest Konfiguration aus `[package.metadata.arch]` in `Cargo.toml`. - Liest Konfiguration aus `[package.metadata.arch]` in `Cargo.toml`.
- Installiert die Binary nach `/usr/bin/`, sowie `LICENSE` und `README.md` nach `/usr/share/`. - Installiert die Binary nach `/usr/bin/`, sowie `LICENSE` und `README.md` nach `/usr/share/`.
- Erzeugt eine standardkonforme `.PKGINFO`-Datei und komprimiert das Paket mit `zstandard`. - Erzeugt eine standardkonforme `.PKGINFO`-Datei und komprimiert das Paket mit `zstandard`.
- Unterstützt optional ein Install-Skriptlet (`[package.metadata.arch].install_script`), das pacman-konform als `<name>.install` mit `post_install()`/`post_upgrade()` eingebettet wird (bei mac2ip: legt `/var/lib/mac2ip` an).
- Parameter: - Parameter:
- `--target`: Rust Target-Triple (z. B. `x86_64-unknown-linux-gnu`) - `--target`: Rust Target-Triple (z. B. `x86_64-unknown-linux-gnu`)
- `--arch`: Zielarchitektur (z. B. `x86_64`, `aarch64`, `i686`) - `--arch`: Zielarchitektur (z. B. `x86_64`, `aarch64`, `i686`)
@@ -144,5 +216,4 @@ Erstellt native Arch Linux-Pakete (`.pkg.tar.zst`), ohne dass `makepkg` oder ein
## Lizenz ## Lizenz
Dieses Template steht standardmäßig unter der [GPL-3.0-or-later](LICENSE)-Lizenz. Die Lizenz kann bei Bedarf in `LICENSE` und `Cargo.toml` angepasst werden. mac2ip steht unter der [GPL-3.0-or-later](LICENSE)-Lizenz.