monoadmin/the-other-dude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify terminology and expand acronyms in user guide

Browse Source
This commit is contained in:
Jason Staack
2026-03-16 08:57:22 -05:00
parent d0eae197dc
commit d9acd6bc66
1 changed files with 14 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/USER-GUIDE.md
View File

@@ -1,6 +1,6 @@
# TOD - The Other Dude: User Guide # TOD - The Other Dude: User Guide
MSP fleet management platform for MikroTik RouterOS devices. Managed Service Provider (MSP) fleet management platform for MikroTik RouterOS devices.
--- ---
@@ -10,7 +10,7 @@ MSP fleet management platform for MikroTik RouterOS devices.
1. Navigate to the portal URL provided by your administrator. 1. Navigate to the portal URL provided by your administrator.
2. Log in with the admin credentials created during initial deployment. 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. 3. Complete **security enrollment** — the portal uses zero-knowledge authentication, meaning your password never leaves your browser, 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. 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. 5. Complete the **Setup Wizard** to create your first organization and add your first device.
@@ -19,7 +19,7 @@ MSP fleet management platform for MikroTik RouterOS devices.
The Setup Wizard launches automatically for first-time super_admin users. It walks through three steps: 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 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 2 -- Add Device**: Enter the IP address, API port (default 8729 for TLS — this is the RouterOS API-SSL service, which must be enabled on the device under IP > Services), 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. - **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. You can always add more organizations and devices later from the sidebar.
@@ -54,7 +54,7 @@ TOD uses a collapsible sidebar with four sections. Press `[` to toggle the sideb
| Item | Description | | Item | Description |
|------|-------------| |------|-------------|
| **Topology** | Interactive network map showing device connections and shared subnets, rendered with ReactFlow and Dagre layout. | | **Topology** | Interactive network map showing device connections and shared subnets, with automatic layout for readability. |
| **Alerts** | Live alert feed with filtering by severity (info, warning, critical) and acknowledgment actions. | | **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. | | **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. | | **Audit Trail** | Immutable, append-only log of all operations -- configuration changes, logins, user management, and admin actions. |
@@ -66,7 +66,7 @@ TOD uses a collapsible sidebar with four sections. Press `[` to toggle the sideb
| Item | Description | | Item | Description |
|------|-------------| |------|-------------|
| **Users** | User management with role-based access control (RBAC). Assign roles: super_admin, admin, operator, viewer. | | **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. | | **Organizations** | Create and manage tenants for multi-tenant MSP operation. Each tenant's data is fully isolated — users in one organization cannot see another's devices or data. |
| **API Keys** | Generate and manage programmatic access tokens (prefixed `mktp_`) with operator-level permissions. | | **API Keys** | Generate and manage programmatic access tokens (prefixed `mktp_`) with operator-level permissions. |
| **Settings** | System configuration, theme toggle (dark/light), and profile settings. | | **Settings** | System configuration, theme toggle (dark/light), and profile settings. |
| **About** | Platform version, feature summary, and project information. | | **About** | Platform version, feature summary, and project information. |
@@ -97,12 +97,12 @@ There are several ways to add devices to your fleet:
1. **Setup Wizard** -- automatically offered on first login. 1. **Setup Wizard** -- automatically offered on first login.
2. **Fleet Table** -- click the "Add Device" button from the Devices page. 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. 3. **Subnet Scanner** -- enter a network range (e.g., `192.168.1.0/24` covers all addresses from .0 to .255) to auto-discover MikroTik devices on the network.
When adding a device, provide: When adding a device, provide:
- **IP Address** -- the management IP of the RouterOS device. - **IP Address** -- the management IP of the RouterOS device.
- **API Port** -- default is 8729 (TLS). The portal connects via the RouterOS binary API protocol. - **API Port** -- default is 8729 (TLS). Ensure the API-SSL service is enabled on your router (RouterOS: IP > Services > api-ssl).
- **Credentials** -- username and password for the device. Credentials are encrypted at rest with AES-256-GCM. - **Credentials** -- username and password for the device. Credentials are encrypted at rest with AES-256-GCM.
### Device Detail Page ### Device Detail Page
@@ -118,7 +118,7 @@ Click any device in the fleet table to open its detail page. Tabs include:
| **DHCP** | Active DHCP leases, server configuration, and address pools. | | **DHCP** | Active DHCP leases, server configuration, and address pools. |
| **Backups** | Configuration backup timeline with side-by-side diff viewer to compare changes over time. | | **Backups** | Configuration backup timeline with side-by-side diff viewer to compare changes over time. |
| **Clients** | Connected clients and wireless registrations. | | **Clients** | Connected clients and wireless registrations. |
| **Wireless** | Wireless metrics charts -- client count, signal strength (dBm), and CCQ per interface over time. | | **Wireless** | Wireless metrics charts -- client count, signal strength (dBm), and CCQ (Client Connection Quality) per interface over time. |
### Config Editor ### Config Editor
@@ -146,7 +146,7 @@ Seven category tabs:
6. **DNS** -- DNS server and static DNS entries. 6. **DNS** -- DNS server and static DNS entries.
7. **System** -- Device identity, timezone, NTP, admin password. 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. Toggle between **Simple** (guided) and **Standard** (full config editor) modes at any time. Your mode preference is saved in the browser — switching browsers resets it to Simple mode.
--- ---
@@ -156,7 +156,7 @@ Toggle between **Simple** (guided) and **Standard** (full config editor) modes a
Create threshold-based rules that fire when device metrics cross defined boundaries: Create threshold-based rules that fire when device metrics cross defined boundaries:
- Select the metric to monitor (CPU, memory, disk, interface traffic, wireless signal, wireless CCQ, uptime, etc.). - Select the metric to monitor (CPU, memory, disk, interface traffic, wireless signal, wireless link quality, uptime, etc.).
- Set the threshold value and comparison operator. - Set the threshold value and comparison operator.
- Choose severity: **info**, **warning**, or **critical**. - Choose severity: **info**, **warning**, or **critical**.
- Assign one or more notification channels. - Assign one or more notification channels.
@@ -171,7 +171,7 @@ Alerts can be delivered through multiple channels:
| **Webhook** | HTTP POST to any URL with a JSON payload containing alert details. | | **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. | | **Slack** | Slack incoming webhook with Block Kit formatting for rich alert messages. |
Default wireless alert rules (Signal Degraded at -75 dBm, CCQ Low at 50%) are automatically created when a new tenant is added. Default wireless alert rules (Signal Degraded at -75 dBm (a level where connection quality noticeably degrades), CCQ Low at 50% (indicating a poor or congested wireless link)) are automatically created when a new tenant is added.
### Maintenance Windows ### Maintenance Windows
@@ -208,7 +208,7 @@ 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. - **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). - **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. - **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). - **Envelope encryption** -- configuration backups and audit logs are encrypted at rest, with each organization getting its own encryption key managed by the built-in key management service.
### Roles and Permissions ### Roles and Permissions
@@ -221,7 +221,7 @@ TOD uses a 1Password-style hybrid zero-knowledge model:
### Credential Storage ### 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. Device credentials (RouterOS username/password) are encrypted at rest and only decrypted in memory when the poller connects to the device.
--- ---
@@ -242,7 +242,7 @@ TOD supports dark and light modes:
- The **Audit Trail** is immutable -- every configuration change, login, and admin action is recorded and cannot be deleted. - 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. - **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. - **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. - The **Topology** view automatically arranges devices for readability. Toggle shared subnet edges to reduce visual clutter on complex networks.
--- ---