MIKROTIK-RMM/README.md

MikroTik Manager

A self-hosted, full-stack network management platform for MikroTik devices. Monitor, configure, and manage your entire MikroTik infrastructure — routers, switches, and wireless access points — from a single web interface.

---

Screenshots

Dashboard

Device Management

Device List	Device Overview
Switch Ports & Throughput	Hardware Monitor

Wireless

Client Tracking

Client List

Client Detail View

Network Topology

Events & Backups

Event Log

Backup Management

---

Features

Dashboard

• Live KPI cards: total devices, online/offline count, connected wireless clients, active alerts
• Device type distribution chart
• Firmware update notifications with per-device details
• Historical client count graph (1h → 30d range)

Device Management

• Add, edit, and delete MikroTik devices (routers, switches, wireless APs)
• Automatic polling: status, model, firmware version, RouterOS version
• Firmware update availability detection
• Per-device notes, rack location, and physical address with map support
• Device credential encryption at rest
• Bulk device add — "Try All" discovered devices runs as a server-side background job (survives browser tab close) with live progress and cancel support

Routers

• Routing table viewer
• Interface overview with IP assignments
• Firewall rule inspection
• Router-specific settings and configuration

Switches

• VLAN management (create, edit, delete VLANs)
• Per-port configuration and VLAN membership
• Switch overview with port status

Wireless

• Per-AP SSID management — create, edit, enable/disable, delete wireless interfaces
• Bulk SSID deployment — push an SSID configuration to all managed APs simultaneously
• Security profile management (WPA2/WPA3, PSK, EAP)
• Hardware radio information and band filtering (RouterOS 7 wifi package + legacy wlan package)
• Scheduled and on-demand spectral scans per radio
• Scheduled and on-demand AP scans (nearby access point discovery)
• Real-time radio monitoring
• Wireless client tracking with vendor lookup

Network Services

Each service supports multi-device management with conflict detection:

Service	Capabilities
DHCP	IPv4 & IPv6 servers, address pools, static leases, live lease table
DNS	Upstream servers, static records (A/AAAA/CNAME/MX/NS/PTR/TXT/SRV), cache flush, DoH
NTP	Server (broadcast/manycast), client (unicast/multicast), sync status
WireGuard	Interface management, peer configuration, public key display, RX/TX stats

Network Topology

• Auto-discovered network map using LLDP, CDP, and MNDP neighbor data
• Interactive node graph with device type icons
• Protocol-priority link deduplication

Client Tracking

• All connected clients across all devices in one view
• Filter by device, type, active status, or search by MAC/IP/hostname
• Client detail page with connection history and vendor identification
• Historical client count metrics
• Configurable list refresh interval (Not Updating / 30 s / 1 min / 3 min) with preference saved per browser

Backups

• Trigger RouterOS backups on demand via SSH
• Download and manage backup files from the UI

Alerts

Configurable alert rules with cooldown periods:

• Device online / offline
• High CPU or memory usage (configurable threshold)
• SSL certificate expiry warning
• Firmware update available
• RouterOS log errors and warnings
• New device discovered

Global Search

Instant search across devices, clients, and events from the top navigation bar.

User Management & Access Control

• Role-based access: Admin, Operator (read/write), Viewer (read-only)
• Admin-only user creation and role assignment
• JWT authentication with secure session handling
• Credential preset access control — presets can be restricted to admins only (allow_operator_use); operators only see presets they are permitted to use when adding or updating devices

TLS / HTTPS

• Automatic self-signed certificate generation on first run
• Upload a custom certificate and private key via the Settings UI
• nginx handles TLS termination and HTTP→HTTPS redirect

---

Tech Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite, Tailwind CSS
State / Data	TanStack Query v5, React Router v6, Zustand
Charts	Recharts
Topology	@xyflow/react
Maps	Leaflet
Terminal	xterm.js
Backend	Node.js, Express, TypeScript
Primary DB	PostgreSQL 15
Time-series DB	InfluxDB 2.7
Cache / Queue	Redis 7, BullMQ
Real-time	Socket.IO
Device comms	RouterOS API (port 8728), SSH2
Proxy	nginx (TLS termination, static file serving)
Container	Docker Compose

---

Requirements

• Docker and Docker Compose (v2+)
• MikroTik devices running RouterOS 6.x or 7.x with the API service enabled
• Network access from the host running this application to your MikroTik devices on port 8728 (or your configured API port)

---

Quick Deploy (Pre-built Images)

No source code or build toolchain required — just Docker and Docker Compose.

1. Download the compose file

curl -O https://raw.githubusercontent.com/2GT-Media-Group-LLC/mikrotik-manager/main/docker-compose.ghcr.yml

2. Create your environment file

curl -O https://raw.githubusercontent.com/2GT-Media-Group-LLC/mikrotik-manager/main/.env.example
mv .env.example .env

Edit .env and set at minimum:

JWT_SECRET=your_long_random_jwt_secret_here
ENCRYPTION_KEY=your_32_character_encryption_key_
CORS_ORIGIN=https://your-domain.example.com

3. Start the application

docker compose -f docker-compose.ghcr.yml up -d

Docker pulls the pre-built images from GitHub Container Registry and starts the stack. No compilation, no cloning.

4. Open the app

Navigate to https://localhost (or your server's IP/hostname) and log in with admin / admin.

To update to the latest release: docker compose -f docker-compose.ghcr.yml pull && docker compose -f docker-compose.ghcr.yml up -d

---

Quick Start (Build from Source)

For contributors or anyone who wants to build the images locally.

1. Clone the repository

git clone https://github.com/2GT-Media-Group-LLC/mikrotik-manager.git
cd mikrotik-manager

2. Configure environment variables

Copy the example environment file and edit it:

cp .env.example .env

At minimum, change these values in .env:

# Required — use long, random strings
JWT_SECRET=your_long_random_jwt_secret_here
ENCRYPTION_KEY=your_32_character_encryption_key_

# Required for production deployments (set to your domain)
# CORS_ORIGIN=https://manager.example.com

# Optional — defaults work for a local install
DB_PASSWORD=mikrotik_secure_pw
INFLUXDB_TOKEN=mytoken123456789

Security note: Never commit your .env file to version control. The .gitignore already excludes it.

3. Start the application

docker compose up -d

The first run will:

• Build the frontend (React → static files)
• Build the backend (TypeScript → Node.js)
• Initialize PostgreSQL with the database schema
• Initialize InfluxDB
• Generate a self-signed TLS certificate

4. Open the app

Navigate to https://localhost (or your server's IP/hostname).

Accept the browser's self-signed certificate warning, or upload a real certificate in Settings → TLS Certificate.

5. Log in

Default credentials on first run:

Username	Password	Role
admin	admin	Admin

Change the default password immediately in Settings → Users.

---

Enabling the RouterOS API

Typically, API access is enabled on MikroTik devices. However if you can't connect via API, ensure the API service is enabled:

/ip service enable api

For API over SSL (port 8729):

/ip service enable api-ssl

The default API port is 8728. You can configure a different port per device in the MikroTik Manager interface.

---

Configuration Reference

All configuration is done via environment variables in .env:

Variable	Default	Description
JWT_SECRET	changeme_use_a_long_random_secret_at_least_32_chars	Secret for signing JWT tokens. Change this.
ENCRYPTION_KEY	changeme32byteslongencryptionkey	32-character key for encrypting device passwords at rest. Change this.
CORS_ORIGIN	(localhost defaults set by Docker Compose)	Comma-separated list of browser origins allowed to call the API (e.g. https://manager.example.com). Required in production — set this to your domain.
DB_PASSWORD	mikrotik_secure_pw	PostgreSQL password
INFLUXDB_TOKEN	mytoken123456789	InfluxDB admin token
INFLUXDB_ORG	mikrotik-manager	InfluxDB organization name
INFLUXDB_BUCKET	metrics	InfluxDB bucket for time-series data
INFLUXDB_ADMIN_PASSWORD	admin_password_123	InfluxDB admin UI password
HTTP_PORT	80	Host port for HTTP (redirects to HTTPS)
HTTPS_PORT	443	Host port for HTTPS

Credential encryption (ENCRYPTION_KEY)

Device API and SSH passwords stored in PostgreSQL are encrypted at rest using AES-256-GCM (backend/src/utils/crypto.ts). The key material comes from the ENCRYPTION_KEY environment variable (see table above). If the value is exactly 32 bytes long it is used as-is; otherwise the implementation derives a 32-byte key with SHA-256 (still driven by that env var).

If the key is lost: ciphertext cannot be decrypted; you must re-enter credentials on each device (or restore a database backup that was encrypted with the old key).

If the key is rotated (compromise or policy): there is no automatic bulk re-encryption in the app today. Operational recovery is:

1. Set a new ENCRYPTION_KEY and restart the backend.
2. For each managed device, update API/SSH credentials via the UI (or API) so the server stores new ciphertext under the new key. Old rows still hold ciphertext from the previous key until updated.

For a planned rotation with many devices, restore from backup or script updates against the API using plaintext passwords from your vault.

---

Updating

Pull the latest changes and rebuild:

git pull
docker compose up -d --build backend nginx

Database migrations run automatically on backend startup.

---

Project Structure

mikrotik-manager/
├── frontend/               # React + TypeScript (Vite)
│   └── src/
│       ├── pages/          # Page components (one per route)
│       ├── components/     # Shared UI components
│       ├── services/       # API client (Axios)
│       ├── hooks/          # Custom React hooks
│       └── types/          # TypeScript type definitions
│
├── backend/                # Node.js + Express + TypeScript
│   └── src/
│       ├── routes/         # REST API route handlers
│       ├── services/       # Business logic (polling, alerts, backups)
│       │   └── mikrotik/   # RouterOS API client and device collector
│       ├── db/             # Database migrations
│       ├── config/         # DB, InfluxDB, Redis connections
│       ├── middleware/      # Auth, error handling
│       └── utils/          # Helpers (crypto, OUI lookup, etc.)
│
├── nginx/                  # Reverse proxy config and Dockerfile
├── docker-compose.yml
└── .env.example

---

Contributing

Contributions are welcome! Please open an issue before submitting a pull request so we can discuss the approach.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit your changes: git commit -m "Add your feature"
4. Push to the branch: git push origin feature/your-feature
5. Open a pull request

---

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3) — see the LICENSE file for the full text.

What this means

• You are free to use, modify, and distribute this software.
• If you run a modified version of this software as a network service (e.g., as a hosted web app), you must make your modified source code available to users of that service under the same AGPLv3 license.
• Any distributed copies or derivatives must also carry the AGPLv3 license.

This license was chosen to ensure that improvements made to this project — including those deployed as a service — remain open and available to the community.

---

AI Assistance

This project was designed and built with the help of Claude by Anthropic. AI assistance was used throughout development — including architecture decisions, backend services, frontend components, the CI/CD pipeline, security configuration, and unit tests.

We believe in being transparent about how software is made. The code has also been reviewed and tested using AI and is maintained by the project authors.

---

Disclaimer

This project is not affiliated with or endorsed by MikroTik. MikroTik and RouterOS are trademarks of SIA MikroTīkls. Use this software at your own risk. Always test configuration changes in a non-production environment first.