feat: The Other Dude v9.0.1 — full-featured email system
ci: add GitHub Pages deployment workflow for docs site Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jason Staack
246
docs/USER-GUIDE.md
Normal file
246
docs/USER-GUIDE.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# TOD - The Other Dude: User Guide
|
||||
|
||||
MSP fleet management platform for MikroTik RouterOS devices.
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### First Login
|
||||
|
||||
1. Navigate to the portal URL provided by your administrator.
|
||||
2. Log in with the admin credentials created during initial deployment.
|
||||
3. Complete **SRP security enrollment** -- the portal uses zero-knowledge authentication (SRP-6a), so a unique Secret Key is generated for your account.
|
||||
4. **Save your Emergency Kit PDF immediately.** This PDF contains your Secret Key, which you will need to log in from any new browser or device. Without it, you cannot recover access.
|
||||
5. Complete the **Setup Wizard** to create your first organization and add your first device.
|
||||
|
||||
### Setup Wizard
|
||||
|
||||
The Setup Wizard launches automatically for first-time super_admin users. It walks through three steps:
|
||||
|
||||
- **Step 1 -- Create Organization**: Enter a name for your tenant (organization). This is the top-level container for all your devices, users, and configuration.
|
||||
- **Step 2 -- Add Device**: Enter the IP address, API port (default 8729 for TLS), and RouterOS credentials for your first device. The portal will attempt to connect and verify the device.
|
||||
- **Step 3 -- Verify & Complete**: The portal polls the device to confirm connectivity. Once verified, you are taken to the dashboard.
|
||||
|
||||
You can always add more organizations and devices later from the sidebar.
|
||||
|
||||
---
|
||||
|
||||
## Navigation
|
||||
|
||||
TOD uses a collapsible sidebar with four sections. Press `[` to toggle the sidebar between expanded (240px) and collapsed (48px) views. On mobile, the sidebar opens as an overlay.
|
||||
|
||||
### Fleet
|
||||
|
||||
| Item | Description |
|
||||
|------|-------------|
|
||||
| **Dashboard** | Overview of your fleet with device status cards, active alerts, and metrics sparklines. The landing page after login. |
|
||||
| **Devices** | Fleet table with search, sort, and filter. Click any device row to open its detail page. |
|
||||
| **Map** | Geographic map view of device locations. |
|
||||
|
||||
### Manage
|
||||
|
||||
| Item | Description |
|
||||
|------|-------------|
|
||||
| **Config Editor** | Browse and edit RouterOS configuration paths in real-time. Select a device from the header dropdown. |
|
||||
| **Batch Config** | Apply configuration changes across multiple devices simultaneously using templates. |
|
||||
| **Bulk Commands** | Execute RouterOS CLI commands across selected devices in bulk. |
|
||||
| **Templates** | Create and manage reusable configuration templates. |
|
||||
| **Firmware** | Check for RouterOS updates and schedule firmware upgrades across your fleet. |
|
||||
| **Maintenance** | Schedule maintenance windows to suppress alerts during planned work. |
|
||||
| **VPN** | WireGuard VPN tunnel management -- create, deploy, and monitor tunnels between devices. |
|
||||
| **Certificates** | Internal Certificate Authority management -- generate, deploy, and rotate TLS certificates for your devices. |
|
||||
### Monitor
|
||||
|
||||
| Item | Description |
|
||||
|------|-------------|
|
||||
| **Topology** | Interactive network map showing device connections and shared subnets, rendered with ReactFlow and Dagre layout. |
|
||||
| **Alerts** | Live alert feed with filtering by severity (info, warning, critical) and acknowledgment actions. |
|
||||
| **Alert Rules** | Define threshold-based alert rules on device metrics with configurable severity and notification channels. |
|
||||
| **Audit Trail** | Immutable, append-only log of all operations -- configuration changes, logins, user management, and admin actions. |
|
||||
| **Transparency** | KMS access event dashboard showing encryption key usage across your organization (admin only). |
|
||||
| **Reports** | Generate and export PDF reports: fleet summary, device health, compliance, and SLA. |
|
||||
|
||||
### Admin
|
||||
|
||||
| Item | Description |
|
||||
|------|-------------|
|
||||
| **Users** | User management with role-based access control (RBAC). Assign roles: super_admin, admin, operator, viewer. |
|
||||
| **Organizations** | Create and manage tenants for multi-tenant MSP operation. Each tenant has isolated data via PostgreSQL row-level security. |
|
||||
| **API Keys** | Generate and manage programmatic access tokens (prefixed `mktp_`) with operator-level permissions. |
|
||||
| **Settings** | System configuration, theme toggle (dark/light), and profile settings. |
|
||||
| **About** | Platform version, feature summary, and project information. |
|
||||
|
||||
---
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Cmd+K` / `Ctrl+K` | Open command palette for quick navigation and actions |
|
||||
| `[` | Toggle sidebar collapsed/expanded |
|
||||
| `?` | Show keyboard shortcut help dialog |
|
||||
| `g d` | Go to Dashboard |
|
||||
| `g f` | Go to Firmware |
|
||||
| `g t` | Go to Topology |
|
||||
| `g a` | Go to Alerts |
|
||||
|
||||
The command palette (`Cmd+K`) provides fuzzy search across all pages, devices, and common actions. It is accessible in both dark and light themes.
|
||||
|
||||
---
|
||||
|
||||
## Device Management
|
||||
|
||||
### Adding Devices
|
||||
|
||||
There are several ways to add devices to your fleet:
|
||||
|
||||
1. **Setup Wizard** -- automatically offered on first login.
|
||||
2. **Fleet Table** -- click the "Add Device" button from the Devices page.
|
||||
3. **Subnet Scanner** -- enter a CIDR range (e.g., `192.168.1.0/24`) to auto-discover MikroTik devices on the network.
|
||||
|
||||
When adding a device, provide:
|
||||
|
||||
- **IP Address** -- the management IP of the RouterOS device.
|
||||
- **API Port** -- default is 8729 (TLS). The portal connects via the RouterOS binary API protocol.
|
||||
- **Credentials** -- username and password for the device. Credentials are encrypted at rest with AES-256-GCM.
|
||||
|
||||
### Device Detail Page
|
||||
|
||||
Click any device in the fleet table to open its detail page. Tabs include:
|
||||
|
||||
| Tab | Description |
|
||||
|-----|-------------|
|
||||
| **Overview** | System info, uptime, hardware model, RouterOS version, resource usage, and interface status summary. |
|
||||
| **Interfaces** | Real-time traffic graphs for each network interface. |
|
||||
| **Config** | Browse the full device configuration tree by RouterOS path. |
|
||||
| **Firewall** | View and manage firewall filter rules, NAT rules, and address lists. |
|
||||
| **DHCP** | Active DHCP leases, server configuration, and address pools. |
|
||||
| **Backups** | Configuration backup timeline with side-by-side diff viewer to compare changes over time. |
|
||||
| **Clients** | Connected clients and wireless registrations. |
|
||||
|
||||
### Config Editor
|
||||
|
||||
The Config Editor provides direct access to RouterOS configuration paths (e.g., `/ip/address`, `/ip/firewall/filter`, `/interface/bridge`).
|
||||
|
||||
- Select a device from the header dropdown.
|
||||
- Navigate the configuration tree to browse, add, edit, or delete entries.
|
||||
- Two apply modes are available:
|
||||
- **Standard Apply** -- changes are applied immediately.
|
||||
- **Safe Apply** -- two-phase commit with automatic panic-revert. Changes are applied, and you have a confirmation window to accept them. If the confirmation times out (device becomes unreachable), changes automatically revert to prevent lockouts.
|
||||
|
||||
Safe Apply is strongly recommended for firewall rules and routing changes on remote devices.
|
||||
|
||||
### Simple Config
|
||||
|
||||
Simple Config provides a consumer-router-style interface modeled after Linksys and Ubiquiti UIs. It is designed for operators who prefer guided configuration over raw RouterOS paths.
|
||||
|
||||
Seven category tabs:
|
||||
|
||||
1. **Internet** -- WAN connection type, PPPoE, DHCP client settings.
|
||||
2. **LAN / DHCP** -- LAN addressing, DHCP server and pool configuration.
|
||||
3. **WiFi** -- Wireless SSID, security, and channel settings.
|
||||
4. **Port Forwarding** -- NAT destination rules for inbound services.
|
||||
5. **Firewall** -- Simplified firewall rule management.
|
||||
6. **DNS** -- DNS server and static DNS entries.
|
||||
7. **System** -- Device identity, timezone, NTP, admin password.
|
||||
|
||||
Toggle between **Simple** (guided) and **Standard** (full config editor) modes at any time. Per-device settings are stored in browser localStorage.
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & Alerts
|
||||
|
||||
### Alert Rules
|
||||
|
||||
Create threshold-based rules that fire when device metrics cross defined boundaries:
|
||||
|
||||
- Select the metric to monitor (CPU, memory, disk, interface traffic, uptime, etc.).
|
||||
- Set the threshold value and comparison operator.
|
||||
- Choose severity: **info**, **warning**, or **critical**.
|
||||
- Assign one or more notification channels.
|
||||
|
||||
### Notification Channels
|
||||
|
||||
Alerts can be delivered through multiple channels:
|
||||
|
||||
| Channel | Description |
|
||||
|---------|-------------|
|
||||
| **Email** | SMTP-based email notifications. Configure server, port, and recipients. |
|
||||
| **Webhook** | HTTP POST to any URL with a JSON payload containing alert details. |
|
||||
| **Slack** | Slack incoming webhook with Block Kit formatting for rich alert messages. |
|
||||
|
||||
### Maintenance Windows
|
||||
|
||||
Schedule maintenance periods to suppress alerts during planned work:
|
||||
|
||||
- Define start and end times.
|
||||
- Apply to specific devices or fleet-wide.
|
||||
- Alerts generated during the window are recorded but do not trigger notifications.
|
||||
- Maintenance windows can be recurring or one-time.
|
||||
|
||||
---
|
||||
|
||||
## Reports
|
||||
|
||||
Generate PDF reports from the Reports page. Four report types are available:
|
||||
|
||||
| Report | Content |
|
||||
|--------|---------|
|
||||
| **Fleet Summary** | Overall fleet health, device counts by status, top alerts, and aggregate statistics. |
|
||||
| **Device Health** | Per-device detailed report with hardware info, resource trends, and recent events. |
|
||||
| **Compliance** | Security posture audit -- firmware versions, default credentials, firewall policy checks. |
|
||||
| **SLA** | Uptime and availability metrics over a selected period with percentage calculations. |
|
||||
|
||||
Reports are generated as downloadable PDFs using server-side rendering.
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
### Zero-Knowledge Architecture
|
||||
|
||||
TOD uses a 1Password-style hybrid zero-knowledge model:
|
||||
|
||||
- **SRP-6a authentication** -- your password never leaves the browser. The server verifies a cryptographic proof without knowing the password.
|
||||
- **Secret Key** -- a 128-bit key in `A3-XXXXXX` format, generated during enrollment. Combined with your password for two-secret key derivation (2SKD).
|
||||
- **Emergency Kit** -- a downloadable PDF containing your Secret Key. Store it securely offline; you need it to log in from new browsers.
|
||||
- **Envelope encryption** -- configuration backups and audit logs are encrypted at rest using per-tenant keys managed by the KMS (OpenBao Transit).
|
||||
|
||||
### Roles and Permissions
|
||||
|
||||
| Role | Capabilities |
|
||||
|------|-------------|
|
||||
| **super_admin** | Full platform access across all tenants. Can create organizations, manage all users, and access system settings. |
|
||||
| **admin** | Full access within their tenant. Can manage users, devices, and configuration for their organization. |
|
||||
| **operator** | Can view devices, apply configurations, and acknowledge alerts. Cannot manage users or organization settings. |
|
||||
| **viewer** | Read-only access to devices, dashboards, and reports within their tenant. |
|
||||
|
||||
### Credential Storage
|
||||
|
||||
Device credentials (RouterOS username/password) are encrypted at rest with AES-256-GCM (Fernet) and only decrypted in memory by the poller when connecting to devices.
|
||||
|
||||
---
|
||||
|
||||
## Theme
|
||||
|
||||
TOD supports dark and light modes:
|
||||
|
||||
- **Dark mode** (default) uses the Midnight Slate palette.
|
||||
- **Light mode** provides a clean, high-contrast alternative.
|
||||
- Toggle in **Settings** or let the portal follow your system preference.
|
||||
- The command palette and all UI components adapt to the active theme.
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
- Use the **command palette** (`Cmd+K`) for the fastest way to navigate. It searches pages, devices, and actions.
|
||||
- The **Audit Trail** is immutable -- every configuration change, login, and admin action is recorded and cannot be deleted.
|
||||
- **Safe Apply** is your safety net for remote devices. If a firewall change locks you out, the automatic revert restores access.
|
||||
- **API Keys** (prefixed `mktp_`) provide programmatic access at operator-level permissions for automation and scripting.
|
||||
- The **Topology** view uses automatic Dagre layout. Toggle shared subnet edges to reduce visual clutter on complex networks.
|
||||
|
||||
---
|
||||
|
||||
*TOD -- The Other Dude is not affiliated with or endorsed by MikroTik (SIA Mikrotikls).*
|
||||
Reference in New Issue
Block a user