Skip to main content

UG-SHELL Guide

Overview​

UG-SHELL is a Mapped edge gateway local test and configuration tool, used to troubleshoot connectivity and operational issues, and to adjust settings as needed for a local network. It does not provide a full Linux shell, which helps maintain a more secure environment. Access is provided through SSH to the gateway’s IP address on custom port 23234. If the gateway has multiple network interfaces, UG-SHELL can be reached through any of them.

Linux terminal example:

user@host:~$ ssh <IP Address> -p 23234

Windows terminal example:

C:\Users\User> ssh <IP Address> -p 23234

You will receive a prompt for the SSH host‑key check. Type "yes". You will then be prompted for the password, which can be obtained by emailing [email protected]. If the display does not update to the Mapped Universal Gateway Config screen (Figure 1) within a few seconds, press Enter again. Once UG-SHELL opens, current settings display on the right, and configuration options appear on the left.

Figure 1 – Mapped Universal Gateway Config Figure 1 – Mapped Universal Gateway Config

Functions​

Test Network​

Test Network runs a series of 44 automated tests that check:

  • Compatibility of local network settings
  • Access to Mapped-hosted BalenaOS configuration and management services
  • Access to Mapped’s Microsoft Azure Cloud tenant services

It is the recommended first step when troubleshooting a gateway that looks to already have correct configuration settings.

Ethernet – Configure Ethernet interfaces​

This section displays all configuration options for the gateway’s network adapters. Adapter names vary by host:

  • Hardware gateways: eth0, eth1
  • Windows Server Hyper‑V: eth0, eth1
  • VMWare or Linux hosts: names such as ens160, eno1, enp3s0, etc.

Typically, the first adapter is used for the OT/BMS network, and the second for the IT / internet‑facing network. If only one adapter is required (e.g. OT network has Internet access), use the first adapter.

Figure 2 – Ethernet Config &gt; eth0 Config Figure 2 – Ethernet Config > eth0 Config

Configuration Modes (IPv4/IPv6)

  • Disabled – Adapter not used.
  • Automatic – IP settings obtained via DHCP.
  • Manual – User‑defined static IP settings.
  • Shared – Creates a local shared network for other devices (typically not used).
  • Link‑Local – Auto‑assigned local‑segment address if DHCP fails (typically not used).

For Manual configuration, IP addresses are entered using Classless Inter‑Domain Routing (CIDR) notation (e.g., 192.168.1.10/24). The default gateway follows a comma. DNS server entries follow below.

Figure 3 - Ethernet Config &gt; eth0 Config &gt; IPv4 Manual Config Figure 3 - Ethernet Config > eth0 Config > IPv4 Manual Config

WiFi​

WiFi is not currently supported by Mapped gateways, this section can be ignored.

Proxy​

A proxy server forwards traffic between the gateway and the internet, often used for security, performance, or controlled access. Supported proxy types include:

  • SOCKS4 (TCP)
  • SOCKS5 (TCP/UDP)
  • HTTP Connect (secure HTTP tunnel)
  • HTTP Relay (HTTP request/response forwarding)

Configurable fields include:

  • IP or hostname
  • Port
  • Login
  • Password
  • IPs and subnets to bypass the proxy

Figure 4 - Proxy Configuration Figure 4 - Proxy Configuration

Global Settings​

The Global Settings menu includes fallback and security‑related configuration options:

Figure 5 - Global Settings Figure 5 - Global Settings

  • Include Google DNS – Enables Google DNS as a fallback if the primary DNS server fails. Default: Yes.
  • NTP Servers – Network Time Protocol servers synchronize the gateway’s system clock. Accurate timekeeping is critical for logging, security, and reliable system operations. Default uses a server from pool.ntp.org.
  • Additional Root Certificate Authority (CA) – PEM (base64) – Adds root CA certificates when the gateway is behind a re‑encrypting device such as a transparent proxy or Deep Packet Inspection (DPI) system.

Fallback Static HOSTS​

Fallback Static HOSTS allows the gateway to bypass DNS resolution and use static entries to reach Mapped cloud services.

Figure 6 - Fallback Static HOSTS Figure 6 - Fallback Static HOSTS

  • Network has no DNS Server – Enables static host entries when no reliable DNS service is available.
  • Mapped API Hostname Prefix – Specifies the Fully Qualified Domain Name (FQDN) for the Mapped API.
  • Mapped API Static v4 IP Prefix – Fixed public IPv4 address for the Mapped API.
  • Manual HOSTS entries – Additional static host mappings required for operation. Full lists can be requested at [email protected].

Probe Host​

Probe Host is a diagnostic tool that sends targeted requests to a network host to confirm connectivity. Supported protocols:

  • TCP (Transmission Control Protocol)
  • UDP (User Datagram Protocol)
  • TLS (Transport Layer Security)

Enter a host IP or hostname followed by a colon and port (e.g., 10.10.10.5:443). Select protocol, specify a timeout (default: 10 seconds), and choose Yes to attempt a connection. This tool works well with packet capture tools such as Wireshark.

Figure 7 - Probe Host Figure 7 - Probe Host

Figure 8 - Probe host &gt; Try to connect Figure 8 - Probe host > Try to connect

Figure 9 - Probe Host &gt; Try to Connect &gt; Connection Established Figure 9 - Probe Host > Try to Connect > Connection Established

Save and Reboot​

Saves changes and reboots the gateway.

Reboot​

Reboots the gateway without saving changes.