452 lines
16 KiB
Markdown
452 lines
16 KiB
Markdown
# 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
|
|
|
|
<p align="center">
|
|
<img src=".github/images/Login%20Page.png" alt="Login Page" width="100%" />
|
|
</p>
|
|
|
|
<br>
|
|
|
|
### Dashboard
|
|
|
|
<p align="center">
|
|
<img src=".github/images/Dashboard.png" alt="Dashboard" width="100%" />
|
|
</p>
|
|
|
|
### Device Management
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center">
|
|
<img src=".github/images/Device%20List.png" alt="Device List" /><br>
|
|
<sub><b>Device List</b></sub>
|
|
</td>
|
|
<td align="center">
|
|
<img src=".github/images/Device%20Overview.png" alt="Device Overview" /><br>
|
|
<sub><b>Device Overview</b></sub>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">
|
|
<img src=".github/images/Device%20Ports.png" alt="Switch Ports" /><br>
|
|
<sub><b>Switch Ports & Throughput</b></sub>
|
|
</td>
|
|
<td align="center">
|
|
<img src=".github/images/Device%20Hardware.png" alt="Hardware Monitor" /><br>
|
|
<sub><b>Hardware Monitor</b></sub>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
### Wireless
|
|
|
|
<p align="center">
|
|
<img src=".github/images/Device%20Wireless%20Radio.png" alt="Wireless Radio Management" width="100%" />
|
|
</p>
|
|
|
|
### Client Tracking
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center">
|
|
<img src=".github/images/Clients.png" alt="Client List" /><br>
|
|
<sub><b>Client List</b></sub>
|
|
</td>
|
|
<td align="center">
|
|
<img src=".github/images/Client%20Details.png" alt="Client Details" /><br>
|
|
<sub><b>Client Detail View</b></sub>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
### Network Topology
|
|
|
|
<p align="center">
|
|
<img src=".github/images/Topology.png" alt="Network Topology" width="100%" />
|
|
</p>
|
|
|
|
### Events & Backups
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center">
|
|
<img src=".github/images/Events.png" alt="Event Log" /><br>
|
|
<sub><b>Event Log</b></sub>
|
|
</td>
|
|
<td align="center">
|
|
<img src=".github/images/Backups.png" alt="Backup Management" /><br>
|
|
<sub><b>Backup Management</b></sub>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
---
|
|
|
|
## 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
|
|
- CPU load and historical sparkline displayed correctly for all device types, including hardware switches that report 0% CPU via ASIC offloading
|
|
|
|
### 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
|
|
- **Copy VLANs from another switch** — 3-step wizard that copies VLAN IDs and names from any other managed switch onto the current device, with manual per-VLAN port assignment (tagged/untagged) using a click-to-cycle interface chip grid, conflict detection with per-VLAN skip/overwrite control, and a review summary before any changes are applied
|
|
|
|
### 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 |
|
|
| **Syslog** | Logging actions (remote/memory/disk/echo) and routing rules; single-device or push-to-all with per-entry coverage; enable/disable rules |
|
|
|
|
### 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](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) (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
|
|
|
|
```bash
|
|
curl -O https://raw.githubusercontent.com/2GT-Media-Group-LLC/mikrotik-manager/main/docker-compose.ghcr.yml
|
|
```
|
|
|
|
### 2. Create your environment file
|
|
|
|
```bash
|
|
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:
|
|
|
|
```env
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
At minimum, change these values in `.env`:
|
|
|
|
```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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](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](https://claude.ai) 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.
|