Mapping configuration

Port and device mappings are configured by leveraging node tags. You may add or remove the tags even after you have started a node. PATty periodically scans the tag configuration of running lab nodes across all users, and adds or removes open ports or IP forwarding rules accordingly. The mappings are therefore not applied immediately when they are created, or when a node starts or acquires its L3 NAT IPv4 address.

Configuration

As introduced in PATty Tool Overview, you can add any combination of PAT and device mappings to a lab node, by adding one or more node tags to the node in the sidebar panel, which shows after you click the node in the Workbench canvas or nodes table.

For PAT with TCP, simply add pat:<outside-port>:<inside-port> as a tag to a node of a lab. For example, pat:4201:22. Alternatively, an explicit pat:tcp:4201:22 also works.

Similar for UDP PAT: add pat:udp:<outside-port>:<inside-port> as a tag to a node of a lab. For example, pat:udp:4201:22. For UDP, the protocol must be specified.

For serial devices / console access, add serial:<outside-port>:<line-number> as a tag to a node of a lab. If the console / line 0 should be used, the line-number can be omitted. For example, serial:4001 for console access or serial:4001:1 for line number 1 which is typically the aux port on a router.

For VNC devices, add vnc:<outside-port> as a tag to a node of a lab. For example, vnc:4901. Note that there’s only one VNC device per node, at a maximum.

For both serial and VNC console access, you can open the port in read-only mode if you append :ro to the tag. This allows outside connections to read and watch the console output but not control it.

Note

Outside ports are constrained to the minimum and maximum port number configured for PATty. The defaults are 2000-7999. This can be changed via options passed to the PATty service. Port specifications outside the allowed range are silently ignored. Clashing port numbers may produce inconsistent results.

PAT requirements

While device access works regardless of external IP exposure, PAT requires nodes to be “externally exposed”. The specific requirements are:

  • A node must have outside connectivity via an external connector.

  • This external connector must be configured to use the “NAT” bridge.

  • The node must have acquired an IPv4 address from the NAT bridge segment or must be configured to use a static IPv4 address on the NAT bridge network segment.

  • The node must have recently (within the past 1 hour) sent an ARP or DHCP message which associates the MAC and IP addresses, which must be seen on the L3 NAT external bridge (virbr0).

In case of a valid association, you can see the associated IPv4 address on the given interface in the Interfaces tab of the sidebar panel when you click the node in the Workbench. You may need to refresh the association by e.g. pinging the L3 NAT gateway address from console.

This typically means that the PATed node must be layer 2 connected to the NAT bridge:

  • ✅ External connector [NAT] -- Alpine node

  • ✅ External connector [NAT] -- Unmanaged switch -- Alpine node

  • ✅ External connector [NAT] -- IOSvL2 -- IOSvL2 -- Alpine node (assuming the switches are layer 2 and do not route)

  • ❌ External connector [Bridge] -- Alpine node (device is not seen by the IP snooper for the NAT bridge. Besides, PAT wouldn’t be needed anyway)

  • ❌ External connector [NAT] -- IOSv -- Alpine node (Alpine node does not acquire an IP on the NAT bridge)

  • ❌ Alpine node (Alpine node does not have any external connectivity)