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 (Landesflagge) in der Toolbar wechselt die
Sprache der App (persistiert über Neustarts). Alle fünf Tabs sind
vollständig übersetzt (statische UI-Texte, Buttons, Tooltips). Werte, die
direkt vom Router kommen (Fehlermeldungen, CLI-Befehlszeilen, Live-Log),
bleiben unübersetzt.

## 1. Verbinden

- Router-Adresse, Benutzername und Passwort eingeben, verbinden. Ein
  Augen-Symbol neben dem Passwortfeld deckt die Eingabe zur Kontrolle
  auf.
- Beim ersten Verbinden wird ein unbekanntes Zertifikat (REST-API) oder
  ein unbekannter SSH-Host-Schlüssel angezeigt und muss einmalig
  bestätigt werden (Trust-on-First-Use) — schützt vor einem
  ausgetauschten/gefälschten Router unter derselben IP-Adresse. Bei
  einer REST-Verbindung können beide Dialoge nacheinander erscheinen:
  den SSH-Host-Schlüssel prüft die App auch dann einmalig im
  Hintergrund, weil einige Funktionen (automatisches Backup vor jeder
  Änderung, Update-Check u.a.) immer SSH brauchen, unabhängig vom
  Verbindungsweg.
- 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, Benutzername und (falls vom Router gemeldet) Seriennummer.
  Zwei unterschiedliche Router mit identischem Host+Benutzername (z.B.
  beide auf MikroTiks Werks-Adresse 192.168.88.1/admin) bleiben dadurch
  getrennte Einträge, erkennbar an der "SN: ..."-Zeile; auch das
  gemerkte Passwort wird pro Gerät getrennt gespeichert. 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).
  Adressfelder starten leer — das Feld selbst zeigt ein Beispielformat
  (z.B. "Router-Adresse (z.B. 192.168.88.1/24)"), das beim Tippen
  verschwindet.
- **VLAN**: zusätzliche virtuelle Netzwerke auf demselben Kabel.
  Adressfelder starten hier ebenfalls leer, mit Beispielformat im
  jeweiligen Feld.
- **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.
- **Abbrechen**: jederzeit über den Button oben rechts verfügbar
  (Einfach- wie Experte-Modus), mit Bestätigungsdialog gegen
  versehentlichen Verlust bereits eingegebener Werte — setzt den
  Assistenten auf den ersten Schritt zurück.

## 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. Jede Port-Überschrift zeigt zusätzlich
den aktuellen Live-Durchsatz (↓/↑, grünes Symbol bei aktivem
Datenverkehr, graues im Leerlauf) mit kleinem Liniendiagramm der
letzten 10 Sekunden.

Alle Aktionen zu einem Gerät liegen im "Aktionen"-Button (•••) hinter
der jeweiligen Zeile:

- Bei dynamischer Adresse → "Feste IP zuweisen" (macht die aktuelle
  Adresse dauerhaft, RouterOS' "Make Static"). Der Warnhinweis erklärt
  auch den Rückweg: "Aktionen" → "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.
- Bei 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** (im "Aktionen"-Menü):
  - **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.
- Kategorien sind einklappbar (Standard: zugeklappt) — Klick auf die
  größere, farblich hinterlegte Überschrift klappt sie auf/zu, für
  bessere Übersicht bei den vielen Bereichen.
- 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 (country flag) in the toolbar switches the app's
language (persists across restarts). All five tabs are fully translated
(static UI text, buttons, tooltips). Values that come straight from the
router (error messages, CLI command lines, live log) stay untranslated.

## 1. Connect

- Enter the router's address, username and password, then connect. An
  eye icon next to the password field reveals it for a quick check.
- On the first connection, an unknown certificate (REST API, the usual
  case) or an unknown SSH host key (SSH fallback) is shown and must be
  confirmed once (trust-on-first-use) — protects against a swapped/
  spoofed device answering at the same IP address. Which of the two
  dialogs appears depends on whether the app connects over REST or SSH.
- 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, username, and (when the router reports one) serial number.
  Two different routers sharing the same host+username (e.g. both left
  at MikroTik's factory default 192.168.88.1/admin) stay separate
  entries because of this, shown by an "SN: ..." line; the remembered
  password is also kept separate per device. 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). Address
  fields start empty — the field itself shows a format example (e.g.
  "Router Address (e.g. 192.168.88.1/24)"), which disappears as you
  type.
- **VLAN**: additional virtual networks on the same cable. Address
  fields here start empty too, with a format example shown in each
  field.
- **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.
- **Cancel**: available anytime via the button in the top right (Simple
  and Expert mode alike), with a confirmation dialog to guard against
  losing values you've already entered — resets the wizard to the
  first step.

## 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. Each port header also shows live throughput (↓/↑, green
icon when actively carrying traffic, grey when idle) with a small line
chart of the last 10 seconds.

Every action for a device lives in the "Actions" button (•••) behind
its row:

- With a dynamic address → "Assign static IP" (makes its current
  address permanent, RouterOS' "Make Static"). The warning also
  explains the way back: "Actions" → "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.
- 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** (also in the "Actions" menu):
  - **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.
- Categories are collapsible (start collapsed by default) — click the
  larger, colored header to expand/collapse, for a clearer overview
  across the many 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.