Host Preparation

This page covers everything that must be in place on the Asset Gateway host and in the surrounding network before a multi-VLAN discovery job can succeed, in either mode. The mode-specific network configuration is described on the Discovery over VXLAN and Discovery over Trunk Port pages.

User-managed network configuration

The Asset Gateway acts on the existing user infrastructure and on the values supplied in the discovery job. It does not validate the VLAN or VXLAN configuration behind those values: it cannot verify that a switch port is really configured as a trunk, that the trunk carries the requested VLAN, that a VNI is mapped to the intended VLAN on the remote endpoint, or that the resulting topology is correct. Whatever segmentId, vlanSubnet, probeIP, remoteIP, and the parent interface point to is used as given.

The user therefore owns the correctness of the underlying setup: switch, trunk, VTEP, VNI mapping, routing, and VPN. A mismatch between the job parameters and the actual network does not produce a configuration error. It typically shows up as a job that returns no assets, incomplete results, or assets from an unintended VLAN. See Troubleshooting.

Host requirements

The Asset Gateway host must run the docker engine and must have the kernel driver for the selected mode available: the VXLAN driver for VXLAN mode, or the 802.1Q VLAN driver for VLAN mode. On standard Linux hosts both are enabled by default.
The host must have an interface that reaches the target network. This interface is supplied as parentInterfaceName or parentInterfaceIP and is referred to as the parent interface. In VXLAN mode it is the interface that carries the tunnel; in VLAN mode it is the interface cabled to the trunk port.
Multi-VLAN discovery is available only in the Docker Compose deployment of the Asset Gateway.

Planning the probe address

The probeIP is the address the Asset Gateway assigns to the interface it creates, and the source address of every discovery probe. It must:

belong to the subnet given in vlanSubnet,
be free inside the target VLAN, and
be reserved for the Asset Gateway so that it is not handed out to any other host, for example by a DHCP server, while the job runs.

A conflict with an existing host causes the discovery to fail or return incomplete results. Reserve one address per VLAN that is to be scanned, and agree these addresses with whoever administers the target networks.

One job per VLAN

A discovery job always targets exactly one VLAN. To discover multiple VLANs, submit one discovery job per VLAN with the matching segmentId, vlanSubnet, and probeIP values. The remaining options — the parent interface, and in VXLAN mode also remoteIP and vxlanDstPort — typically stay the same across all jobs that share the same parent interface or the same remote endpoint.

The identifiers of the VLANs to be discovered, VNIs in VXLAN mode and VLAN IDs in VLAN mode, must be shared with the operator who configures the discovery jobs.

Note

Even with a correctly configured discovery job, devices from neighboring VLANs may occasionally appear in results. This can happen when VLAN segmentation is incomplete on the switch, or when a device has multiple active network interfaces and responds across VLAN boundaries. See Troubleshooting for details and remediation steps.

Host firewall requirements

If a host firewall such as ufw is active on the Asset Gateway host and its default policy for incoming traffic is to drop packets, open the following ports before running a multi-VLAN discovery job. Packets that are blocked by the host firewall never reach the Asset Gateway, so the discovery fails or returns no results without an obvious error.

VXLAN tunnel port (UDP)

This applies to VXLAN mode only. The remote VXLAN endpoint sends its encapsulated replies to the UDP port configured in the vxlanDstPort discovery option. Many endpoints send these packets from a random source port, so the firewall does not recognize them as replies to the outgoing tunnel traffic and drops them as new connections. Allow incoming UDP traffic on the configured port explicitly, preferably limited to the interface that carries the tunnel:

# Limited to the interface configured as parentInterfaceName (recommended)
sudo ufw allow in on wg0 proto udp to any port 4789

# Or, without limiting the rule to an interface
sudo ufw allow 4789/udp

Replace wg0 with the interface used by the tunnel and 4789 with the value supplied in vxlanDstPort. Any port can be configured there, for example 8472, so always use the value of the discovery job instead of a fixed port.

Asset Gateway container port (TCP 18080)

This applies to both modes. The Asset Gateway consists of several containers. Most of them run in the custom Docker bridge network cdm, while the container that listens on TCP port 18080 runs in host network mode. Requests from the bridge network therefore enter the host for the port 18080 and are dropped by the host firewall before they reach that container. Therefore, allow this traffic:

sudo ufw allow 18080/tcp

To keep the rule narrow, limit it to the bridge interface of the cdm network:

CDM_BRIDGE="br-$(docker network inspect cdm -f '{{.Id}}' | cut -c1-12)"
sudo ufw allow in on "$CDM_BRIDGE" proto tcp to any port 18080

Parent interface lifecycle

Before a multi-VLAN discovery job starts, the Asset Gateway checks the state of the parent network interface identified by parentInterfaceName or parentInterfaceIP:

If the parent interface is down, the Asset Gateway brings it up, uses it for the discovery, and brings it back down after the job completes. This keeps the network communication available only for the duration of the discovery and minimizes the time the interface stays active.
If the parent interface is already up before the job starts, the Asset Gateway uses it as is and leaves it unchanged after the job completes.

Only the parent interface used by the discovery job is affected. The VXLAN interface or 802.1Q sub-interface created on top of it is always created at the start of the job and removed at the end.

Note

Because the parent interface remains under the control of the user, changes made to it before or during a discovery job can interfere with the job. This matters in particular when several VPN interfaces exist on the host; see Using multiple WireGuard interfaces.

Supported Asset Links

Multi-VLAN discovery works with any Asset Link. The Asset Link itself does not need to be aware of VXLAN or VLAN tagging; the Asset Gateway sets up the interface and presents the remote VLAN to the Asset Link as a regular network.

For the Asset Gateway to attach the interface to the correct container, the Asset Link container name must include the trailing segment of the assetLinkId. The Asset Gateway derives that segment as follows:

If the assetLinkId contains a ., the segment is everything after the last .. This segment may itself contain -. For cdm-device-class-driver-siemens.cdm.dcd.default-ip-scanner the segment is default-ip-scanner.
If the assetLinkId contains no ., the segment is everything after the last -. For cdm-dcd-snmp the segment is snmp.

The container name must contain that segment as a whole, either at the start of the name or preceded by . or -, and either at the end of the name or followed by . or -. Container names must match the regular expression:

^(?:.*[.-])?<segment>(?:[.-].*)?$

Replace <segment> with the segment derived from the assetLinkId. A container whose name merely contains the segment as part of a longer word, such as snmpwalk for the segment snmp, is not matched.

`assetLinkId`	Segment
`cdm-device-class-driver-siemens.cdm.dcd.default-ip-scanner`	`default-ip-scanner`
`cdm-dcd-snmp`	`snmp`

Overriding the container name

Some Asset Links do not run the scan themselves but delegate it to a separate tool that runs in its own container. The container name of that tool is unrelated to the assetLinkId, so the Asset Gateway cannot derive it from the job. The SAT Asset Link is such a case: it has the id cdm-device-class-driver-siemens.cdm.dcd.sat, while the scan is performed by the SIMATIC Automation Tool container named SimaticAutomationTool, which does not match the pattern above.

For these Asset Links, supply the optional networkScannerName discovery option to name the target container explicitly:

{ "key": "networkScannerName", "comparisonOperator": "EQUAL", "value": "SimaticAutomationTool" }

When networkScannerName is supplied, the Asset Gateway attaches the interface it creates to the container with that name and does not use the assetLinkId for container resolution. This ensures that the container which actually sends the discovery probes is the one connected to the target VLAN. The option applies to both VXLAN and VLAN mode.

Note

Omit networkScannerName when the Asset Link container name already matches the assetLinkId pattern described above. In that case the Asset Gateway resolves the container from the assetLinkId as before.

Any questions left?

Ask the community