Installing terminal gatway 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

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

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"

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 [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 / 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`.

Introduction

Getting started

General

Devices, Users & Permissions

Tasks, Backups & Snippets

Development

Reports

Firmware Manager

Installing terminal gatway Addon

1. Overview & How Terminal Gateway Works #

Key Technical Highlights: #

2. Dual-Tier Command & Policy Enforcement #

A. Kernel Tier (Linux Hosts) #

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

3. Multi-User Collaboration & Audit Recording #

Session Recording & Compliance Playback #

4. Network Ports & Firewall Rules #

5. Installing Terminal Gateway Locally (Same Server) #

Step 1: Execute the 1-Line Installer #

Step 2: Installation Output & Verification #

Then reload the backend server to apply the changes: #

7. Security Model & Enterprise NDA Source Code Access #

❓ 8. Troubleshooting & FAQ #

1. Overview & How Terminal Gateway Works #

Key Technical Highlights: #

2. Dual-Tier Command & Policy Enforcement #

A. Kernel Tier (Linux Hosts) #

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

3. Multi-User Collaboration & Audit Recording #

Session Recording & Compliance Playback #

4. Network Ports & Firewall Rules #

5. Installing Terminal Gateway Locally (Same Server) #

Step 1: Execute the 1-Line Installer #

Step 2: Installation Output & Verification #

Then reload the backend server to apply the changes: #

7. Security Model & Enterprise NDA Source Code Access #

❓ 8. Troubleshooting & FAQ #

Share This Article :