--- title: Installing Terminal Gateway Addon description: "**MikroWizard+ Terminal Gateway: Zero-Trust Web Terminal, Kernel Policy Enforcement & Session Recording Guide** Document Category: Core Addons & Security | Target Audience: Network Administrators, SecOps Engineers, & Infrastructure Teams | Applies to: MikroWizard v2.0+ (Pro & Enterprise) ## 1. Overview…" url: "https://mikrowizard.com/docs/installing-terminal-gatway-addon/" updated: "2026-10-15" category: Getting started --- # Installing Terminal Gateway Addon **MikroWizard+ Terminal Gateway: Zero-Trust Web Terminal, Kernel Policy Enforcement & Session Recording Guide** Document Category: Core Addons & Security | Target Audience: Network Administrators, SecOps Engineers, & Infrastructure Teams | Applies to: MikroWizard v2.0+ (Pro & Enterprise) ## 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: | Role | Terminal I/O | Permission Controls | Description | | --- | --- | --- | --- | | **Owner** | Full Read & Write | Full Control / Room Kick | Session initiator who can invite peers, approve elevated commands, and terminate the session. | | **Collaborator** | Interactive Read & Write | Execute Allowed Commands | Invited engineer who can type commands and run diagnostics collaboratively. | | **Observer** | Read-Only Stream | View Live Output Only | Auditor, 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: | Port | Protocol | Scope | Description | | --- | --- | --- | --- | | **8200** | TCP | Loopback / Reverse Proxy | **Terminal WebSocket & Health API**: Handles browser terminal sessions and backend health queries. | | **8201** | TCP | Loopback / LAN | **Agent Verification Port**: Endpoint for deployed agents to verify tokens and log enforcement events. | Security Notice: For same-host installations, keep Port 8200 and 8201 bound to 127.0.0.1. If deployed on a separate remote server, restrict inbound access to Port 8200 strictly to the MikroWizard backend IP address. ## 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. Enterprise Compliance Notice: Full source code access (including Python backend sources, Go agent code, and signing toolchains) is provided to MikroWizard Pro and Enterprise customers under a standard mutual Non-Disclosure Agreement (NDA). If your organization requires an in-depth source code audit, sovereign air-gapped validation, or internal regulatory compliance review: - Contact our security team at **[security@mikrowizard.com](mailto:security@mikrowizard.com)**. - 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 / Error | Root Cause | Recommended Solution | | --- | --- | --- | | **HTTP 401 Unauthorized on /health** | Bearer token mismatch between gateway and backend | Verify 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 headers | Ensure 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 failed | Check container status with `docker ps | grep terminal-gateway` and review logs via `docker logs mikrowizard-terminal-gateway`. | | **Recordings not saving to disk** | Filesystem permission restrictions on recordings folder | Ensure `/opt/mikrowizard/terminal_recordings` is owned by user ID `10001:10001`: `sudo chown -R 10001:10001 /opt/mikrowizard/terminal_recordings`. |