github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/docs/devices/external/usb.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: 'Devices: USB'
     4  sidebar_title: USB <sup>Beta</sup>
     5  description: The USB Device Plugin detects and makes USB devices available to tasks
     6  ---
     7  
     8  # USB Device Plugin
     9  
    10  Name: `usb`
    11  
    12  The `usb` device plugin is used to expose USB devices to Nomad. The USB plugin
    13  is not included within Nomad and requires downloading and providing on each
    14  node.
    15  
    16  ## Fingerprinted Attributes
    17  
    18  | Attribute        | Unit   | Description                                     |
    19  |------------------|--------|-------------------------------------------------|
    20  | `vendor_id`      | int    | USB VID in decimal format                       |
    21  | `product_id`     | int    | USB PID in decimal format                       |
    22  | `class_id`       | int    | USB Class code in decimal format                |
    23  | `sub_class_id`   | int    | USB SubClass code in decimal format             |
    24  | `protocol_id`    | int    | USB Protocol code in decimal format             |
    25  | `vendor`         | string | Human readable vendor                           |
    26  | `product`        | string | Human readable product                          |
    27  | `description`    | string | Human readable description of the USB device    |
    28  | `classification` | string | Human readable classification of the USB device |
    29  
    30  ## Runtime Environment
    31  
    32  The `usb` device plugin exposes the following environment variables:
    33  
    34  - `USB_VISIBLE_DEVICES` - List of USB IDs (from the plugin) available to the task.
    35  
    36  ## Installation Requirements
    37  
    38  In order to use the `usb` device plugin the following prerequisites must be
    39  met:
    40  
    41  1. GNU/Linux i368/amd64/armv7/arm64 (Other Architectures and OS may work but
    42     have not been tested)
    43  2. [libusb-1.0](https://github.com/libusb/libusb/wiki) installed
    44  
    45  ## Installation
    46  
    47  To install the `usb` device plugin you will first need to download the binary
    48  for your Nomad client. You can find the latest release of these binaries on
    49  the [release
    50  page](https://gitlab.com/CarbonCollins/nomad-usb-device-plugin/-/releases).
    51  
    52  This binary needs to be downloaded into the plugins directory of the Nomad
    53  node and the plugin stanza then needs to be added. A full example of the
    54  plugin stanza needed for the `usb` driver can be found under the plugin
    55  configuration section.
    56  
    57  ## Plugin Configuration
    58  
    59  ```hcl
    60  plugin "usb" {
    61    config {
    62      enabled = true
    63  
    64      included_vendor_ids = [0x1CF1, 0x067b]
    65      excluded_vendor_ids = []
    66  
    67      included_product_ids = [0x0030, 0x2303]
    68      excluded_product_ids = []
    69  
    70      fingerprint_period = "1m"
    71    }
    72  }
    73  ```
    74  
    75  The `usb` device plugin supports the following configuration in the agent config:
    76  
    77  - `enabled` `(bool: true)` - the `usb` driver may be disabled on clients by
    78    setting this option to `false` (defaults to `true`).
    79  
    80  - `included_vendor_ids` (`array<uint16>: []`): An array of VIDs to pass to
    81    nomad if found
    82  
    83  - `excluded_vendor_ids` (`array<uint16>: []`): An array of VIDs to not pass to
    84    nomad if found (this takes priority over the include list)
    85  
    86  - `included_product_ids` (`array<uint16>: []`): An array of PIDs to pass to
    87    nomad if found
    88  
    89  - `excluded_product_ids` (`array<uint16>: []`): An array of PIDs to not pass
    90    to nomad if found (this takes priority over the include list)
    91  
    92  - `fingerprint_period` `(string: "1m")` - The period in which to fingerprint
    93    for device changes.
    94  
    95  ## Limitations
    96  
    97  Currently the `usb` driver does not automatically provide dev paths for the
    98  USB devices into the task, this means in containerized applications you will
    99  still have to supply the dev path manually e.g. `/dev/ttyUSB0` however this
   100  plugin does allow containerized tasks to only be deployed on nodes which have
   101  specified USB devices connected.
   102  
   103  ## Other Information
   104  
   105  The `usb` device plugin is currently in beta and thus is not recommended for
   106  production use. This will remain the case until the current limitations have
   107  been solved with the plugin. If you find any issues with the `usb` plugin
   108  please raise an issue on the plugins [issues
   109  page](https://gitlab.com/CarbonCollins/nomad-usb-device-plugin/-/issues/new?issue)
   110  
   111  ### USB Codes
   112  
   113  For a full list of available class, subclass, and protocol codes you can see
   114  the [usb-if-defined-class-codes](https://www.usb.org/defined-class-codes) page
   115  on the usb
   116  
   117  ### USB Vendors & Products
   118  
   119  There are several sources where you can find known vendor and product ids for
   120  USB devices. These are independently maintained lists from third parties but
   121  can be useful as a reference.
   122  
   123  - [linux-usb.org](http://www.linux-usb.org/)
   124  - [devicehunt.com](https://devicehunt.com/all-usb-vendors)
   125  
   126  ### Source Code & Compiled Binaries
   127  
   128  The source code for this plugin can be found at
   129  [CarbonCollins/nomad-usb-device-plugin](https://gitlab.com/CarbonCollins/nomad-usb-device-plugin). You
   130  will also find pre built binaries on the [releases
   131  page](https://gitlab.com/CarbonCollins/nomad-usb-device-plugin/-/releases).