RouterOS/Manual.md

# RouterOS Assistant — Handbuch / Manual

Dieses Handbuch beschreibt ausschließlich Funktionen, die **live gegen
echte MikroTik-Hardware getestet und bestätigt** sind (Meilensteine mit
✅ in der README). Funktionen, die noch nicht vollständig getestet sind
(z.B. WLAN-Einrichtung, Teile der Härtung), stehen bewusst **nicht**
hier — Details dazu in `HANDOFF.md`.

This handbook documents only features that are **live-tested and
confirmed against real MikroTik hardware** (milestones marked ✅ in the
README). Features not yet fully verified (e.g. WLAN setup, parts of
hardening) are deliberately **not** listed here — see `HANDOFF.md` for
those.

---

## Sprache / Language

- [Deutsch](#deutsch)
- [English](#english)

---

# Deutsch

## Inhaltsverzeichnis

1. [Überblick](#überblick)
2. [Verbinden](#1-verbinden)
3. [Einrichten (Wizard)](#2-einrichten-wizard)
4. [Übersicht](#3-übersicht)
5. [LAN-Scanner](#4-lan-scanner)
6. [Experte](#5-experte)
7. [Sicherungen](#6-sicherungen)

## Überblick

RouterOS Assistant ist eine native macOS-App, die Mikrotik-RouterOS-Router
per geführtem Wizard einrichtet und über fünf Tabs verwaltet: Verbinden,
Einrichten, Übersicht, LAN-Scanner, Experte, Sicherungen. Die App spricht mit
dem Router per REST-API (bevorzugt) oder SSH (Fallback) — beides wird
automatisch gewählt, ohne dass du dich darum kümmern musst.

Ein DE/EN-Umschalt-Button in der Toolbar wechselt die Sprache der App
(persistiert über Neustarts). Aktuell vollständig übersetzt: alle
Tab-Namen, der komplette Experte-Tab (alle Menü-Bereiche, Buttons,
Tooltips) sowie der komplette Verbinden-Tab. Weitere Tabs folgen
schrittweise.

## 1. Verbinden

- Router-Adresse, Benutzername und Passwort eingeben, verbinden.
- Beim ersten Verbinden per SSH wird der Host-Schlüssel des Routers
  angezeigt und muss einmalig bestätigt werden (Trust-on-First-Use) —
  schützt vor einem ausgetauschten/gefälschten Router unter derselben
  IP-Adresse.
- Nach dem Verbinden zeigt die Detailseite vollständige Routerboard-Infos
  (Modell, Revision, Seriennummer, Firmware-Typ/-Version).
- **Software-Update-Check**: zeigt Kanal, installierte und neueste
  RouterOS-Version, Button "Jetzt prüfen" und "Update installieren".
- **Firmware-Update**: aktualisiert die Routerboard-Bootloader-Firmware
  separat, mit "Jetzt neu starten"-Button danach.
- Schnell-Backup-Button direkt im Verbinden-Tab.
- "Trennen"-Button beendet die Verbindung sauber.
- **Bekannte Router**: nach jeder erfolgreichen Verbindung merkt sich die
  App Host und Benutzername (Passwort bleibt wie gewohnt im macOS-
  Schlüsselbund). Anzeigename wird beim ersten Mal automatisch auf die
  Hardware-Bezeichnung gesetzt (z.B. "hEX"), lässt sich aber jederzeit
  über "Bearbeiten" ändern — dort auch ein freies Standort-Feld (z.B.
  "Keller, Serverschrank" oder "1. OG") zur besseren Unterscheidung
  mehrerer Router. Klick auf einen Eintrag füllt Host/Benutzername/
  Passwort ins Formular, ohne sofort zu verbinden. Ab ca. 4 Einträgen
  scrollt die Liste in sich selbst.
- **Live-Traffic-Anzeige**: der Punkt vor jedem Interface in der
  Geräte-Übersicht ist grau (kein Link), grün (Link, aber kein
  Datenverkehr) oder pulsierend grün (überträgt gerade tatsächlich
  Daten).

## 2. Einrichten (Wizard)

Geführter Schritt-für-Schritt-Assistent für die Grundkonfiguration:

- **WAN**: Internetanschluss einrichten — automatische Adresse (DHCP-
  Client) oder feste IP-Adresse.
- **LAN**: ein oder mehrere Netzwerke mit eigenem DHCP-Server. Im
  Experte-Modus lassen sich mehrere physische Ports/Interfaces als
  getrennte Netzwerke einrichten, jeweils mit eigenem Adressbereich und
  optionaler **Netzwerk-Isolation** (Geräte in diesem Netz erreichen
  keine anderen konfigurierten Netze, Internetzugriff bleibt erhalten).
- **VLAN**: zusätzliche virtuelle Netzwerke auf demselben Kabel.
- **Firewall-Grundschutz**: Internetfreigabe (NAT) plus Schutz vor
  unaufgeforderten Zugriffen aus dem Internet — mit einem Klick
  aktivierbar, bestehende eigene Regeln bleiben erhalten.
- **Review/Apply**: zeigt jeden einzelnen Befehl vor der Ausführung an,
  sichert vorher automatisch die aktuelle Konfiguration.
- Der Wizard lässt sich auf einem bereits eingerichteten Router erneut
  ausführen (z.B. um ein weiteres Netzwerk hinzuzufügen) — bereits
  bestehende Einstellungen werden dabei nicht doppelt angelegt oder
  beschädigt.

## 3. Übersicht

Grafisches Diagramm des kompletten aktuellen Router-Zustands:

- Spalten: Interfaces → IP-Adressen → DHCP/Pools → Routen →
  Firewall/NAT, mit echten Verbindungslinien (keine Vermutungen,
  abgeleitet aus den tatsächlichen RouterOS-Referenzfeldern).
- **Hover** über einen Knoten hebt seine Verbindungen hervor; **Klick**
  macht die Hervorhebung dauerhaft (bleibt aktiv, bis ein anderer Knoten
  angeklickt wird).
- **Klick auf eine Verbindungslinie** zeigt rechts eine verständliche
  Erklärung, was diese Verbindung bedeutet, plus Sprung zu den beiden
  verbundenen Elementen. Die "Verbindungen"-Liste im Detailpanel eines
  Knotens ist ebenfalls klickbar (springt direkt zum verbundenen
  Element) und zeigt beim Hovern eine kurze Erklärung als Tooltip.
- **Direktes Bearbeiten**: IP-Adressen, Pools, DHCP-Server/-Netzwerke/
  -Clients, Routen, Firewall-Filter-/NAT-Regeln, WireGuard-Peers und
  Interfaces (Ethernet, Bridge, WLAN, VLAN, WireGuard) lassen sich
  anklicken und über "Bearbeiten" direkt ändern — schreibt sofort an den
  Router zurück. (Adress-Listen-Knoten sind hier noch nicht direkt
  editierbar, nur über den Experte-Tab, da ein Knoten dort mehrere
  Einträge zusammenfasst.) Dynamische/automatisch angelegte Routen
  (z.B. die Verbindungsroute eines Netzwerks) zeigen bewusst keinen
  Bearbeiten-Button, da RouterOS solche Einträge selbst verwaltet.
- Aktualisiert sich automatisch, sobald du in den Tab wechselst.
- Zoom-Buttons (−/100%/+) für die Diagrammgröße.
- Verbindungslinien laufen animiert in Flussrichtung ("von → nach").
- **Kästchen lassen sich frei verschieben** (anklicken zum Auswählen
  funktioniert weiterhin parallel) — Verbindungslinien folgen live mit.
  "Zurücksetzen"-Button in der Toolbar stellt die ursprüngliche
  Spalten-Anordnung wieder her.

## 4. LAN-Scanner

Zeigt alle Geräte im Netzwerk (aus DHCP-Leases und ARP-Tabelle),
gruppiert nach physischem Port. "Neu scannen"-Button fragt Leases/ARP/
Bridge-Host-Tabelle erneut ab.

- Rechtsklick auf ein Gerät mit dynamischer Adresse → "Feste IP
  zuweisen" (macht die aktuelle Adresse dauerhaft, RouterOS' "Make
  Static"). Der Warnhinweis erklärt auch den Rückweg: Rechtsklick →
  "Feste Zuweisung entfernen" (hier im selben Tab), danach muss das
  Gerät kurz die Verbindung trennen/neu aufbauen (Kabel/WLAN kurz
  trennen, oder neu starten), um automatisch wieder eine dynamische
  Adresse zu bekommen.
- Rechtsklick auf ein Gerät mit fester Adresse → "Feste Zuweisung
  entfernen" (Rückweg zu dynamisch — Gerät muss danach kurz die
  Verbindung trennen/neu verbinden, um eine neue Adresse zu bekommen).
- **Netzwerk-Tools** (Rechtsklick auf ein Gerät):
  - **Ping** und **Traceroute** — ausgeführt vom Router aus (nicht von
    diesem Mac), zeigt die rohe RouterOS-Ausgabe.
  - **DNS-Auflösung (nslookup)** — nur verfügbar, wenn ein Hostname
    bekannt ist; prüft, ob der Router diesen Namen selbst auflösen kann.
  - **Port-Scan** — läuft direkt von diesem Mac aus (nicht über den
    Router) gegen ca. 19 gängige TCP-Ports. Ergebnis farbig: rot =
    offen, grün = geschlossen (Gerät antwortet, aber nichts lauscht dort),
    grau = keine Antwort (Firewall, Gerät aus, oder Port gefiltert).

## 5. Experte

Direkter, kuratierter Zugriff auf die meisten RouterOS-Bereiche, mit
Tooltips und Warnhinweisen zu jedem Feld:

- Vollständig kuratiert: Firewall (Filter/NAT/Mangle/Raw/Adress-Listen),
  IP-Adressierung, VPN (PPP), viele weitere Bereiche.
- Für jedes Feld gibt es einen Hilfetext mit Format-Beispiel (z.B.
  "192.168.88.1/24").
- **Eigener Menüpfad**: jeder RouterOS-Menüpfad ist erreichbar, auch
  ohne kuratiertes Formular — Felder erscheinen dann generisch als
  Schlüssel/Wert-Paare.
- Vor jeder Änderung: Bestätigungsdialog mit dem exakten Befehl, der
  ausgeführt wird. Automatisches Backup einmal pro Verbindungssitzung
  vor der ersten Änderung.

## 6. Sicherungen

- **Backup erstellen**: exportiert die aktuelle Konfiguration, wählbarer
  Speicherort.
- **Backup wiederherstellen**: lädt ein gespeichertes Backup über SFTP
  hoch und spielt es zurück ein. Prüft vorher, ob das Backup zum
  angeschlossenen Routermodell passt (Schutz vor einem "Brick" durch
  falsches Modell), und erhält den aktuellen Login automatisch (Backups
  enthalten grundsätzlich keine Passwörter).
- **Werkseinstellungen wiederherstellen**: Notfallschalter in der
  Gefahrenzone, setzt den Router komplett zurück.

---

# English

## Table of Contents

1. [Overview](#overview)
2. [Connect](#1-connect)
3. [Setup Wizard](#2-setup-wizard)
4. [Topology](#3-topology)
5. [LAN Scanner](#4-lan-scanner)
6. [Expert](#5-expert)
7. [Backups](#6-backups)

## Overview

RouterOS Assistant is a native macOS app that sets up and manages
MikroTik RouterOS routers through a guided wizard and five tabs:
Connect, Setup, Topology, LAN Scanner, Expert, Backups. The app talks to the
router over its REST API (preferred) or SSH (fallback) — chosen
automatically, no configuration needed.

A DE/EN toggle button in the toolbar switches the app's language
(persists across restarts). Fully translated so far: every tab name,
the entire Expert tab (all menu areas, buttons, tooltips), and the
entire Connect tab. More tabs will follow incrementally.

## 1. Connect

- Enter the router's address, username and password, then connect.
- On the first SSH connection, the router's host key is shown and must
  be confirmed once (trust-on-first-use) — protects against a swapped/
  spoofed device answering at the same IP address.
- Once connected, the detail page shows full routerboard info (model,
  revision, serial number, firmware type/version).
- **Software update check**: shows channel, installed and latest
  RouterOS version, "Check now" and "Install update" buttons.
- **Firmware update**: updates the routerboard bootloader firmware
  separately, with a "Reboot now" button afterwards.
- Quick-backup button right in the Connect tab.
- "Disconnect" button cleanly ends the session.
- **Known Routers**: after every successful connection, the app remembers
  the host and username (the password stays in macOS Keychain as usual).
  The display name defaults to the hardware designation (e.g. "hEX") the
  first time, but can be changed anytime via "Edit" — which also has a
  free-text location field (e.g. "Basement, server rack" or "1st Floor")
  to tell multiple routers apart. Clicking an entry fills in host/
  username/password without connecting yet. The list scrolls in place
  past about 4 entries.
- **Live traffic indicator**: the dot in front of each interface in the
  device overview is grey (no link), green (link but no traffic), or
  pulsing green (actually carrying data right now).

## 2. Setup Wizard

Guided step-by-step assistant for base configuration:

- **WAN**: set up the internet connection — automatic address (DHCP
  client) or a static IP.
- **LAN**: one or more networks, each with its own DHCP server. In
  Expert mode, multiple physical ports/interfaces can be set up as
  separate networks, each with its own address range and optional
  **network isolation** (devices on this network can't reach any other
  configured network, while internet access still works).
- **VLAN**: additional virtual networks on the same cable.
- **Basic firewall**: internet sharing (NAT) plus protection against
  unsolicited access from the internet — one click to enable, existing
  custom rules are preserved.
- **Review/Apply**: shows every single command before it runs, and
  automatically backs up the current configuration first.
- The wizard can be safely re-run on an already-configured router (e.g.
  to add one more network) — existing settings aren't duplicated or
  broken by a second run.

## 3. Topology

Graphical diagram of the router's complete current state:

- Columns: Interfaces → IP addresses → DHCP/pools → routes →
  firewall/NAT, with real connection lines (no guesswork — derived from
  RouterOS' own reference fields).
- **Hovering** a node highlights its connections; **clicking** makes the
  highlight persistent (stays active until a different node is
  clicked).
- **Clicking a connection line** shows a plain-language explanation of
  what it means in the right-hand panel, plus a jump to both connected
  elements. The "Connections" list in a node's detail panel is also
  clickable (jumps straight to the connected element) and shows a short
  explanation as a tooltip on hover.
- **Direct editing**: IP addresses, pools, DHCP servers/networks/
  clients, routes, firewall filter/NAT rules, WireGuard peers and
  interfaces (Ethernet, bridge, WLAN, VLAN, WireGuard) can be clicked
  and changed via "Edit" — writes back to the router immediately.
  (Address-list nodes aren't directly editable here yet, only through
  the Expert tab, since one node there folds several entries together.)
  Dynamic/auto-created routes (e.g. a network's own connected route)
  deliberately show no Edit button, since RouterOS manages those itself.
- Refreshes automatically whenever you switch to this tab.
- Zoom buttons (−/100%/+) for the diagram size.
- Connection lines run an animated flow direction ("from → to").
- **Cards can be freely dragged** (click-to-select still works alongside
  it) — connection lines follow live. A "Reset" button in the toolbar
  restores the original column layout.

## 4. LAN Scanner

Shows every device on the network (from DHCP leases and the ARP table),
grouped by physical port. "Rescan" button re-queries leases/ARP/bridge
host table.

- Right-click a device with a dynamic address → "Assign static IP"
  (makes its current address permanent, RouterOS' "Make Static"). The
  warning also explains the way back: right-click → "Remove static
  assignment" (in this same tab), after which the device needs to
  briefly disconnect/reconnect (unplug cable, toggle Wi-Fi, or reboot)
  to automatically get a dynamic address again.
- Right-click a device with a static address → "Remove static
  assignment" (back to dynamic — the device needs to briefly
  disconnect/reconnect afterwards to get a fresh address).
- **Network Tools** (right-click a device):
  - **Ping** and **Traceroute** — run from the router (not from this
    Mac), shows the raw RouterOS output.
  - **DNS lookup (nslookup)** — only available when a hostname is known;
    checks whether the router itself can resolve that name.
  - **Port scan** — runs directly from this Mac (not through the
    router) against about 19 common TCP ports. Color-coded result: red
    = open, green = closed (device responds, but nothing listens
    there), grey = no response (firewall, device off, or filtered port).

## 5. Expert

Direct, curated access to most RouterOS areas, with tooltips and warning
notes on every field:

- Fully curated: Firewall (Filter/NAT/Mangle/Raw/address lists), IP
  addressing, VPN (PPP), and many more areas.
- Every field has a help text with a format example (e.g.
  "192.168.88.1/24").
- **Custom menu path**: any RouterOS menu path is reachable, even
  without a curated form — fields then appear generically as key/value
  pairs.
- Before every change: a confirmation dialog showing the exact command
  that will run. Automatic backup once per connection session before the
  first change.

## 6. Backups

- **Create backup**: exports the current configuration, choosable save
  location.
- **Restore backup**: uploads a saved backup over SFTP and restores it.
  Checks beforehand that the backup matches the connected router model
  (protects against bricking the device with the wrong model), and
  automatically preserves the current login (backups never contain
  passwords).
- **Restore factory defaults**: emergency switch in the danger zone,
  fully resets the router.