USB Device Plugin

Name: usb

The usb device plugin is used to expose USB devices to Nomad. The USB plugin is not included within Nomad and requires downloading and providing on each node.

Fingerprinted Attributes

Attribute	Unit	Description
`vendor_id`	int	USB VID in decimal format
`product_id`	int	USB PID in decimal format
`class_id`	int	USB Class code in decimal format
`sub_class_id`	int	USB SubClass code in decimal format
`protocol_id`	int	USB Protocol code in decimal format
`vendor`	string	Human readable vendor
`product`	string	Human readable product
`description`	string	Human readable description of the USB device
`classification`	string	Human readable classification of the USB device
`serial`	string	Serial Number of the USB device

Runtime Environment

The usb device plugin exposes the following environment variables:

USB_VISIBLE_DEVICES - List of USB IDs (from the plugin) available to the task.

Installation Requirements

In order to use the usb device plugin the following prerequisites must be met:

GNU/Linux i368/amd64/armv7/arm64 (Other Architectures and OS may work but have not been tested)
libusb-1.0 installed

Installation

To install the usb device plugin you will first need to download the binary for your Nomad client. You can find the latest release of these binaries on the release page.

This binary needs to be downloaded into the plugins directory of the Nomad node and the plugin block then needs to be added. A full example of the plugin block needed for the usb driver can be found under the plugin configuration section.

Plugin Configuration

plugin "usb" {
  config {
    enabled = true

    included_vendor_ids = [0x1CF1, 0x067b]
    excluded_vendor_ids = []

    included_product_ids = [0x0030, 0x2303]
    excluded_product_ids = []

    fingerprint_period = "1m"
  }
}

The usb device plugin supports the following configuration in the agent config:

enabled (bool: true) - the usb driver may be disabled on clients by setting this option to false (defaults to true).
included_vendor_ids (array<uint16>: []): An array of VIDs to pass to nomad if found
excluded_vendor_ids (array<uint16>: []): An array of VIDs to not pass to nomad if found (this takes priority over the include list)
included_product_ids (array<uint16>: []): An array of PIDs to pass to nomad if found
excluded_product_ids (array<uint16>: []): An array of PIDs to not pass to nomad if found (this takes priority over the include list)
fingerprint_period (string: "1m") - The period in which to fingerprint for device changes.

Limitations

Currently the usb driver does not automatically provide dev paths for the USB devices into the task, this means in containerized applications you will still have to supply the dev path manually e.g. /dev/ttyUSB0 however this plugin does allow containerized tasks to only be deployed on nodes which have specified USB devices connected.

Other Information

The usb device plugin is currently in beta and thus is not recommended for production use. This will remain the case until the current limitations have been solved with the plugin. If you find any issues with the usb plugin please raise an issue on the plugins issues page

USB Codes

For a full list of available class, subclass, and protocol codes you can see the usb-if-defined-class-codes page on the usb

USB Vendors & Products

There are several sources where you can find known vendor and product ids for USB devices. These are independently maintained lists from third parties but can be useful as a reference.

Source Code & Compiled Binaries

The source code for this plugin can be found at CarbonCollins/nomad-usb-device-plugin. You will also find pre built binaries on the releases page.