Star on GitHub Register Serial Request Demo
Star GitHub Request Demo Register Serial Serial
View Categories

Installing terminal gatway Addon

Table of Contents

MikroWizard+ Terminal Gateway: Zero-Trust Web Terminal, Kernel Policy Enforcement & Session Recording Guide

1. Overview & How Terminal Gateway Works #

The MikroWizard+ Terminal Gateway is a specialized, zero-trust web access gateway and kernel-level policy enforcement engine engineered for MikroWizard. It bridges browser-based xterm.js sessions to remote network infrastructure—including MikroTik RouterOS, Linux servers, macOS, and BSD hosts—without requiring local desktop clients or insecure direct SSH/Telnet exposure.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                     MikroWizard Core                        │
│            (Authentication, RBAC & Redis Sessions)          │
└──────────────────────────────┬──────────────────────────────┘
                               │ HTTP REST API (Port 8200)
                               │ (Bearer Token Auth)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│             MikroWizard+ Terminal Gateway                   │
│          [ mikrowizard/terminal-gateway:latest ]            │
│                                                             │
│  ┌──────────────────────┐      ┌─────────────────────────┐  │
│  │   WebSocket Bridge   │ ───► │  Policy & Audit Engine  │  │
│  │     (xterm.js)       │      │  (Asciinema .cast logs) │  │
│  └──────────────────────┘      └────────────┬────────────┘  │
└─────────────────────────────────────────────┼───────────────┘
                                              │ SSH / Telnet / Agent PTY
                                              ▼
                                 ┌─────────────────────────┐
                                 │   Target Infrastructure │
                                 │  - MikroTik RouterOS    │
                                 │  - Linux (ptrace tier)  │
                                 │  - BSD / macOS (hooks)  │
                                 └─────────────────────────┘

Architecture

Key Technical Highlights: #

  • Zero-Client Browser Access: High-performance terminal emulator directly integrated into the MikroWizard UI with full 256-color and UTF-8 support.
  • Dual-Tier Command Interception: Kernel-level ptrace/seccomp mediation on Linux hosts and tamper-monitored shell hooks on BSD/macOS.
  • Multi-User Real-Time Collaboration: Multi-party shared terminal rooms with role-based permissions (Owner, Collaborator, Observer).
  • Immutable Session Audit Logs: High-fidelity Asciinema v2 (.cast) recordings saved on disk for compliance reviews and playback.
  • Zero-Trust Credential Isolation: Constant-time validated API tokens (Backend ↔ Gateway), ephemeral session tokens (120s TTL), and Ed25519-signed agents.

2. Dual-Tier Command & Policy Enforcement #

Unlike standard web consoles that rely purely on basic regex matching after a command is already sent to the shell, the Terminal Gateway enforces security at the OS and process level:

A. Kernel Tier (Linux Hosts) #

On Linux target devices, the gateway deploys a lightweight, statically compiled Go agent that attaches to the shell process using Linux ptrace and seccomp:

  • Pre-Execution Syscall Trap: Every execve system call is paused at the kernel boundary before execution begins.
  • Immutable Policy Validation: The agent inspects binary paths, arguments, and environment variables against the active security tier. If unauthorized, the syscall is blocked and the process receives EPERM.
  • Bypass Immunity: Shell aliases, custom scripts, subshells, and binary renames cannot evade kernel-level syscall tracing.

B. Compatible Tier (BSD / macOS / Generic Shells) #

For operating systems without Linux ptrace support, the agent deploys an advanced shell hook trap backed by two complementary detectors:

  • RC-File SHA256 Verification: Injected startup rc files are checksum-verified on a continuous interval. Modifying or unlinking the file trips an immediate session kill.
  • Heartbeat Silence Monitor: The shell emits a prompt heartbeat before each command prompt. If a user strips trap hooks during a session, the heartbeat silence alarm terminates the session fail-closed.

3. Multi-User Collaboration & Audit Recording #

MikroWizard+ Terminal Gateway allows network teams to collaborate on complex troubleshooting tasks in real time with clear permission boundaries:

RoleTerminal I/OPermission ControlsDescription
OwnerFull Read & WriteFull Control / Room KickSession initiator who can invite peers, approve elevated commands, and terminate the session.
CollaboratorInteractive Read & WriteExecute Allowed CommandsInvited engineer who can type commands and run diagnostics collaboratively.
ObserverRead-Only StreamView Live Output OnlyAuditor, trainee, or viewer with strictly read-only terminal stream access.

Session Recording & Compliance Playback #

Every terminal session automatically generates an Asciinema v2 format (.cast) audit record. The recording captures exact timing, keystrokes, and terminal window resize events, allowing administrators to replay sessions directly inside the MikroWizard Web UI with pause, fast-forward, and search capabilities.

4. Network Ports & Firewall Rules #

Before installing the Terminal Gateway, ensure the host system and network firewalls meet the following port specifications:

PortProtocolScopeDescription
8200TCPLoopback / Reverse ProxyTerminal WebSocket & Health API: Handles browser terminal sessions and backend health queries.
8201TCPLoopback / LANAgent Verification Port: Endpoint for deployed agents to verify tokens and log enforcement events.

5. Installing Terminal Gateway Locally (Same Server) #

If you are running the gateway on the same host or VM as MikroWizard, the automated installer sets up the Docker container, provisions the API token, and links with /opt/mikrowizard/server-conf.json.

Step 1: Execute the 1-Line Installer #

Open a terminal on your MikroWizard server and run:

Bash
curl -fsSL https://raw.githubusercontent.com/MikroWizard/mikrowizard-terminal-gateway/master/install.sh | sudo bash
Bash

Step 2: Installation Output & Verification #

The installer pulls the official image from Docker Hub, validates configuration, and restarts the MikroWizard backend service:

Bash
Terminal Output




============================================================
    MikroWizard+ Terminal Gateway — Installation Wizard     
============================================================
[+] Local MikroWizard instance detected: /opt/mikrowizard/server-conf.json
[+] Pulling latest official image: mikrowizard/terminal-gateway:latest...
[+] Starting container: mikrowizard-terminal-gateway...
[+] Waiting for gateway to initialize... [OK]
[+] Updating MikroWizard configuration in /opt/mikrowizard/server-conf.json...
[+] Reloading MikroWizard server...
============================================================
 SUCCESS! MikroWizard+ Terminal Gateway is active and linked!
 Port: 8200 (Loopback: 127.0.0.1)
============================================================

Terminal
Bash

Then reload the backend server to apply the changes: #

Bash
sudo docker exec -it mikroman bash -c "touch reload"
Bash

7. Security Model & Enterprise NDA Source Code Access #

To safeguard the integrity of kernel-level interception heuristics, anti-tampering algorithms, and proprietary protocol state machines, the core engine of the Terminal Gateway is distributed as an audited, pre-compiled Docker container on Docker Hub.

If your organization requires an in-depth source code audit, sovereign air-gapped validation, or internal regulatory compliance review:

  • Contact our security team at [email protected].
  • Provide your Company Name, MikroWizard License ID, and designated security auditor contact.
  • Upon mutual NDA execution, your engineers are granted access to private source repositories and build pipelines.

❓ 8. Troubleshooting & FAQ #

Symptom / ErrorRoot CauseRecommended Solution
HTTP 401 Unauthorized on /healthBearer token mismatch between gateway and backendVerify that terminal_gateway_token in server-conf.json matches the GATEWAY_TOKEN variable inside /opt/mikrowizard/terminal-gateway/gateway.env.
WebSocket fails to connect (404/502)Nginx proxy missing WebSocket Upgrade headersEnsure your Nginx location block contains proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";.
Backend reports “Terminal Gateway not installed”Gateway service is not running or healthcheck failedCheck container status with docker ps | grep terminal-gateway and review logs via docker logs mikrowizard-terminal-gateway.
Recordings not saving to diskFilesystem permission restrictions on recordings folderEnsure /opt/mikrowizard/terminal_recordings is owned by user ID 10001:10001: sudo chown -R 10001:10001 /opt/mikrowizard/terminal_recordings.

What are your Feelings