Skip to main content

Illumio Administration Guide 26.x

  • Illumio Administration Guide 26.x
  • Illumio VEN on IoT Gateway Setup and Admin Guide

Illumio VEN on IoT Gateway Setup and Admin Guide

This guide describes how to install and configure the Illumio VEN on a virtual IoT gateway so that traffic to and from the gateway is visible in Illumio and can be segmented. It covers AWS IoT Greengrass v2 and Azure IoT Edge 1.5 LTS. The detailed steps use AWS Greengrass v2 as the worked example; the VEN install, coexistence, visibility, and enforcement flow is identical on Azure IoT Edge, with only the gateway's own broker and component names differing. It assumes a working gateway and covers the Illumio-specific steps.

What the VEN does on a gateway

The VEN is a control-plane agent. It doesn't sit inline in the packet path and is not a bump-in-the-wire proxy. It programs the host's native OS firewall (Linux iptables/netfilter) and reports flow telemetry to the Illumio PCE.

  • Because the VEN is not inline, it adds no forwarding hop and doesn't terminate Message Queuing Telemetry Transport (MQTT) or Transport Layer Security (TLS). Gateway traffic keeps flowing through the device's own stack; the VEN observes it and applies host firewall rules.

  • Enforcement is at the network layer, using IP address, port, and protocol. The VEN doesn't inspect or decrypt MQTT payloads.

What the VEN doesn't do

  • The VEN operates at the network layer (IP address, port, protocol). It doesn't inspect, decrypt, or filter MQTT payloads or topics.

  • It is not inline. It doesn't proxy, terminate, or forward traffic; it programs the host firewall and reports flows.

  • It doesn't run on downstream leaf devices that cannot host an agent. Those are represented as unmanaged workloads, and the VEN cannot see traffic that never reaches the gateway, such as device-to-device mesh traffic that terminates at a radio coordinator.

  • Coverage follows VEN deployment: a gateway without the VEN is neither visible nor enforced.

Supported gateway platforms

  • AWS IoT Greengrass v2 (the worked example in this guide).

  • Azure IoT Edge 1.5 LTS. The equivalent runtime modules are edgeAgent and edgeHub, with edgeHub acting as the local MQTT broker; confirm its listening ports before building the allowlist.

  • Validated host: Ubuntu 22.04, x86-64. The VEN installs the same way as on any supported 64-bit Linux server.

Prerequisites

Ensure the following before you begin:

  • A running gateway on a supported 64-bit Linux host, validated on Ubuntu 22.04, x86-64: an AWS Greengrass v2 core device, or an Azure IoT Edge 1.5 LTS device. The VEN installs the same way as on any Linux server.

  • On AWS Greengrass, the core deployed with at least aws.greengrass.Cli, aws.greengrass.clientdevices.Auth, aws.greengrass.clientdevices.mqtt.Bridge, and aws.greengrass.clientdevices.mqtt.Moquette. On Azure IoT Edge, the edgeAgent and edgeHub modules running.

  • Outbound HTTPS reachability from the gateway to your Illumio PCE, plus a pairing profile and pairing key from the PCE.

  • Root or sudo on the gateway.

  • The MQTT ports in use: 8883 for MQTT over TLS (leaf devices to the gateway, and the gateway's cloud uplink), and 1883 only if plaintext MQTT is used.

Best practices

  • Roll enforcement out one gateway at a time, and keep new gateways in visibility-only until their flow map is confirmed.

  • Re-baseline when the gateway's components, brokers, or downstream devices change, since new legitimate flows may need new rules.

  • Monitor for drops after every enforcement change, the same way you would for any managed workload.

Note

The detailed steps are validated against an AWS IoT Greengrass v2 lab; the same VEN install, coexistence, visibility, and enforcement flow applies to Azure IoT Edge 1.5 LTS. Replace all example identifiers, IP ranges, and topic names with your own. Supported environments and capabilities vary by release; contact your Illumio representative for current support details.

STEP 1: Confirm the gateway baseline

Verify the Greengrass core is healthy and the client-device path works before adding the VEN so you can distinguish the VEN-induced changes from pre-existing issues.

  1. Confirm a client device (for example, an MQTTX test client on the same subnet as the core) connects to the local Moquette broker over mutual TLS on 8883.

  2. The client device needs the CA retrieved from the core at /greengrass/v2/work/aws.greengrass.clientdevices.Auth/, plus its own client certificate and key. Mutual TLS is mandatory.

  3. Record the ports and peers currently in use (broker 8883, outbound cloud uplink 8883, any 1883) so you can build an allowlist that doesn't break MQTT.

STEP 2: Install the VEN on the core device

  1. Install the 64-bit Linux VEN on the core device host using the standard Illumio Linux VEN installer, then activate it against the PCE with your pairing profile and key. The gateway then appears in the PCE as a managed workload.

  2. Install in Firewall Coexistence mode so the VEN co-owns the host firewall with Greengrass instead of taking exclusive control. Greengrass and its components manage local iptables entries; coexistence prevents the VEN from clearing them.

STEP 3: Start in visibility only

  1. Set the gateway workload to visibility-only. The VEN reports flows to the PCE and programs no blocking rules.

  2. Let traffic run so the PCE builds a flow map: leaf and client devices to the core on 8883, the core's outbound uplink on 8883, inter-component traffic, and management traffic to the PCE.

  3. Confirm the MQTT flows you recorded in STEP 1 all appear. This is the visibility milestone and carries no policy risk.

STEP 4: Label the gateway and its peers

  1. Label the gateway workload: for example, a Role label for the gateway plus your Application, Environment, and Location labels.

  2. Represent downstream leaf devices that cannot run an agent as unmanaged workloads, populated from asset inventory or defined manually, so policy can reference them.

STEP 5: Author and test segmentation

  1. Write rules that allow the flows the gateway legitimately needs: leaf devices to the core on 8883, the core's cloud uplink on 8883 outbound, PCE management, and any required inter-component traffic. Greengrass needs no inbound connection from the cloud; the uplink is outbound only.

  2. Review the draft firewall against the visibility map to confirm nothing required is missing before you enable enforcement.

STEP 6: Move to enforcement

  1. Move the gateway workload to a selective or full enforcement state. The VEN programs the host firewall to allow only the sanctioned flows and drop the rest.

  2. The core keeps running when the cloud link is down, so the host firewall stays in effect during disconnection; enforcement doesn't depend on PCE reachability.

  3. Watch for dropped MQTT, such as a leaf device that can no longer reach the broker on 8883 or a blocked uplink, and adjust rules. Roll enforcement out one gateway at a time.

STEP 7: Validate the configuration

  1. On the core device, confirm the VEN is active and paired and that iptables shows the Illumio chains alongside the Greengrass rules.

  2. From a client device, publish and subscribe on a test topic (for example test/hello) and confirm messages still flow.

  3. In Illumio, confirm the gateway workload is enforced with the expected allowed flows and no unexpected drops.

Setup Outcomes

After completing this setup, verify that you have:

  • The gateway running as a managed Illumio workload visible in the PCE alongside your servers and endpoints.

  • A flow map of traffic to, from, and through the gateway: leaf and client devices to the local broker, the cloud uplink, inter-component traffic, and management traffic to the PCE.

  • Host-firewall enforcement on the gateway that allows only the sanctioned flows and drops the rest, applied at the network layer without terminating or inspecting MQTT.

  • Enforcement that stays in effect when the gateway is disconnected from the cloud because it is programmed into the host firewall rather than dependent on the PCE or the cloud uplink.

  • Downstream leaf devices represented as unmanaged workloads so policy can reference them even though they cannot run an agent.

Use cases

  • Full visibility into traffic entering, leaving, and passing through the gateway.

  • Detection of lateral movement at the gateway chokepoint, where operational technology meets the enterprise network.

  • Micro-segmentation and enforcement of gateway traffic using the labels and rules you already run.

  • Ring-fencing the gateway to only the leaf devices, brokers, and cloud endpoints it legitimately needs.

  • Containing a compromised gateway or device by isolating it at the host firewall.

Benefits

  • Closes the agent blind spot at the IoT and OT boundary, where downstream devices cannot run a security agent.

  • Applies the same policy model, labels, and console already used across the rest of the environment, with no new tooling to operate.

  • Runs without dependency on the gateway's own runtime networking, through Firewall Coexistence mode.

  • Keeps enforcement in effect during cloud disconnection, matching the offline resilience of the gateway itself.

  • Adds no forwarding hop and no MQTT or TLS termination, so it doesn't change how the gateway's traffic flows or performs.

Troubleshooting

  • MQTT stops flowing after enforcement: a required flow was not allowed. Check for drops on 8883 between leaf devices and the local broker, and on the outbound cloud uplink, and add the missing rule. Re-check against the visibility map from STEP 3.

  • The gateway doesn't appear in the PCE: confirm the VEN activated against the pairing profile and that the gateway has outbound HTTPS reachability to the PCE.

  • Greengrass rules disappear or the platform's own networking breaks: confirm the VEN was installed in Firewall Coexistence mode, not exclusive mode, so it doesn't clear the components' iptables entries.

  • Flows are missing from the map: confirm the workload is in visibility-only or enforcement rather than idle, that it is actively reporting, and allow time for periodic traffic to appear.

  • A client device cannot establish mutual TLS: this is a gateway-side certificate issue, not a VEN issue. Confirm the CA, client certificate, and client key as in STEP 1.