Skip to content

Latest commit

 

History

History
57 lines (44 loc) · 3.09 KB

device_specs.md

File metadata and controls

57 lines (44 loc) · 3.09 KB
Raw

Device Configuration

There are three levels of device configuration:

  1. Device Descriptions: Flavor text for report generation.
  2. Device Groupings: Testing groups for synchronization and subnets.
  3. Device Topologies: Fine-grain network reachability control.

Device Descriptions

Device descriptions are simple text files indexed by MAC address included in generated reports. Located by default in directory local/site/mac_addrs/macaddressXX/aux, they are copied unmodified into the report. See resources/test_site/mac_addrs/3c5ab41e8f0a/aux/snake.txt for an example. The base site directory (local/site) is configurable by the site_path config parameter.

More on site_path configurations: Site wide configurations

Device Groupings

Devices can be grouped together for testing by using a "device specification" file that is indexed by the device_specs configuration parameter. See resources/device_specs folder for baseline examples (used for regression tests).

The basic structure is indexed by device MAC address, with a few basic fields:

  • group: Networking group for the device, which is functionally equivalent to a named subnet. If no group is specified, then it defaults to an isolated group based on the device's MAC address. Devices in the same group will have network reachability (sans MUD restrictions) with a shared DHCP server (et. al.), while devices in separate groups will be completely sequestered.
  • type: The type of device, used for indexing into an appropriate MUD file. If no type is specified, then it defaults to default and the corresponding mud_files/default.json MUD file. This value is used at runtime to index a device into a MUD file based on its MAC address. See the MUD ACL documentation for a more detailed description of how MUD files are applied.

All devices in the same group share a common network space, while devices in separate (or unspecified) groups are completely disjoint. On startup, the system will wait for all devices in a group to be present before starting. To limit communication between devices, rather than complete sequestering, they must be in the same group and have compatible type parameters applied.

Device Topologies

Specific flows can be setup between devices using a specification like the example in device_specs_bacnet_star.json. Devices (specified by MAC addresses) can be linked together through their corresponding MUD files. For example, the existence of the JSON path object:

macAddrs.9a:02:57:1e:8f:01.controllers.bacnet.controlees.bacnet.mac_addrs.9a:02:57:1e:8f:02

Implies that the device :01 is linked to device :02 by the bacnet 'controllers' in their corresponding MUD files, as specified by their type: The MUD file for type bacnet has multiple "controller": "bacnet" entries that correspond to the protocol/port combinations that should be allowed.