# sridhardv/secured-usbip architecture

> Architecture diagram of the GitHub repository sridhardv/secured-usbip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sridhardv/secured-usbip
- Repository: https://github.com/sridhardv/secured-usbip

## Overview

#### Purpose and execution model
Secured-USBIP is a GPLv2-derived USB/IP userspace implementation intended as a basis for adding a security protocol. It manages Linux kernel USB/IP drivers: exporting physical USB devices or gadget-backed virtual devices from a server, discovering them remotely, and importing them through a client VHCI controller over TCP (default port 3240).

Primary executables are the `usbip` management CLI (`src/usbip.c`) and the server daemon `usbipd` (`src/usbipd.c`).

#### CLI command dispatcher
`usbip` parses global options and dispatches subcommands to focused command implementations:
- Export lifecycle: `src/usbip_bind.c`, `src/usbip_unbind.c`
- Client lifecycle: `src/usbip_attach.c`, `src/usbip_detach.c`
- Discovery/status: `src/usbip_list.c`, `src/usbip_port.c`

The CLI is the principal control-plane boundary between operators/scripts and kernel-driver sysfs interfaces or the remote USB/IP daemon.

#### Server daemon and protocol boundary
`usbipd` accepts TCP USB/IP control connections, enumerates exportable devices, and services attach/import requests. `src/usbipd.c` owns daemon startup and server behavior; `src/usbip_network.c` and `src/usbip_network.h` provide protocol/network operations shared with client-side remote discovery and attachment.

Any security-protocol work is most likely centered at this wire boundary, while preserving compatibility with the kernel USB/IP transport and management flows.

#### Device export path
For physical USB devices, an operator binds a bus ID to the kernel `usbip-host`/stub driver. Userspace discovers devices and writes/reads driver state through sysfs-oriented abstractions:
- Generic device and driver operations: `libsrc/usbip_device_driver.c`, `libsrc/usbip_device_driver.h`
- Physical host-driver operations: `libsrc/usbip_host_driver.c`, `libsrc/usbip_host_common.c`
- Sysfs access: `libsrc/sysfs_utils.c`

The kernel modules themselves are external prerequisites, not included in this repository: `usbip-core`, `usbip-host`, `vhci-hcd`, and optionally `usbip-vudc`.

#### Client import path
`usbip attach` contacts a remote daemon, requests a bus ID, then attaches the received connection to an available local virtual host-controller port via the VHCI kernel driver. `usbip detach` removes it; `usbip port` reports local attachment state.

The VHCI-specific kernel/sysfs boundary is encapsulated by `libsrc/vhci_driver.c` and consumed by `src/usbip_attach.c`, `src/usbip_detach.c`, and `src/usbip_port.c`. Once attached, ordinary local Linux USB drivers consume the imported device.

#### Shared models and presentation
Shared USB/IP protocol structures, device metadata, and common operations reside in `libsrc/usbip_common.c` and `libsrc/usbip_common.h`. Host enumeration/building of exportable-device information is in `libsrc/usbip_host_common.c`. USB vendor/product/class naming is resolved through `libsrc/names.c`, optionally using hwdata USB ID data.

#### Virtual gadget export
The daemon can also export USB Gadget instances attached to the external `usbip-vudc` kernel module rather than physical host devices. `vudc/vudc_server_example.sh` demonstrates the ConfigFS gadget-to-vUDC setup. This path shares daemon/network control flow but relies on gadget ConfigFS and vUDC naming instead of physical bus-ID binding.

#### Runtime and build dependencies
This is native Linux C software built with Autotools (`configure.ac`, `Makefile.am`). Runtime dependencies include libudev for device/sysfs discovery and optional libwrap TCP wrappers for daemon connection policy. The operational environment requires privileged access to sysfs, loaded USB/IP kernel modules, network reachability to TCP/3240, and potentially ConfigFS for gadget export.

Main entry points: [`src/usbip.c`](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip.c) (usbip CLI), [`src/usbipd.c`](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbipd.c) (usbipd daemon), [`src/usbip_network.c`](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip_network.c) (USB/IP network protocol), [`src/usbip_attach.c`](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip_attach.c) (Client lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Operator Control"]
  node_operator(("Operator or scripts<br/>actor"))
  node_usbip_cli["usbip CLI<br/>management executable<br/>[usbip.c]"]
  node_export_commands["Export lifecycle<br/>CLI commands<br/>[usbip_bind.c]"]
  node_client_commands["Client lifecycle<br/>CLI commands<br/>[usbip_attach.c]"]
  node_status_commands["Discovery and status<br/>CLI commands<br/>[usbip_list.c]"]
end

subgraph group_userspace["USB/IP Userspace"]
  node_usbipd["usbipd daemon<br/>server executable<br/>[usbipd.c]"]
  node_network_protocol{{"USB/IP network protocol<br/>shared wire layer<br/>[usbip_network.c]"}}
  node_common_model["Shared USB/IP models<br/>protocol and device model<br/>[usbip_common.c]"]
  node_host_enumeration["Host export enumeration<br/>device inventory"]
  node_device_driver["Device-driver sysfs layer<br/>driver abstraction"]
  node_vhci_driver["VHCI sysfs layer<br/>client driver abstraction<br/>[vhci_driver.c]"]
end

subgraph group_kernel["Linux Kernel Boundaries"]
  node_usbip_host{{"usbip-host kernel driver<br/>external kernel module"}}
  node_vhci_hcd{{"vhci-hcd kernel driver<br/>external kernel module"}}
  node_local_usb_drivers["Local Linux USB drivers<br/>kernel consumers"]
end

subgraph group_remote["Remote Export Host"]
  node_remote_usbipd["Remote usbipd<br/>remote server<br/>[usbipd.c]"]
  node_physical_devices["Physical USB devices<br/>exported hardware"]
  node_gadget_vudc["Gadget ConfigFS and usbip-vudc<br/>virtual export source"]
end

node_operator -->|"runs"| node_usbip_cli
node_usbip_cli -->|"bind / unbind"| node_export_commands
node_usbip_cli -->|"attach / detach"| node_client_commands
node_usbip_cli -->|"list / port"| node_status_commands
node_export_commands -->|"manages binding"| node_device_driver
node_device_driver -->|"sysfs control"| node_usbip_host
node_usbip_host -->|"exports"| node_physical_devices
node_client_commands -->|"requests remote device"| node_network_protocol
node_status_commands -->|"remote discovery"| node_network_protocol
node_network_protocol -->|"TCP/3240"| node_remote_usbipd
node_remote_usbipd -.->|"same daemon role"| node_usbipd
node_usbipd -->|"serves protocol"| node_network_protocol
node_usbipd -->|"enumerates exports"| node_host_enumeration
node_host_enumeration -->|"builds device metadata"| node_common_model
node_host_enumeration -->|"reads driver state"| node_device_driver
node_client_commands -->|"attach / detach"| node_vhci_driver
node_status_commands -->|"reads port state"| node_vhci_driver
node_vhci_driver -->|"sysfs control"| node_vhci_hcd
node_vhci_hcd -->|"presents imported USB device"| node_local_usb_drivers
node_gadget_vudc -->|"optional virtual export"| node_usbipd

click node_usbip_cli "https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip.c"
click node_export_commands "https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip_bind.c"
click node_client_commands "https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip_attach.c"
click node_status_commands "https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip_list.c"
click node_usbipd "https://github.com/sridhardv/secured-usbip/blob/Master/src/usbipd.c"
click node_network_protocol "https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip_network.c"
click node_common_model "https://github.com/sridhardv/secured-usbip/blob/Master/libsrc/usbip_common.c"
click node_host_enumeration "https://github.com/sridhardv/secured-usbip/blob/Master/libsrc/usbip_host_common.c"
click node_device_driver "https://github.com/sridhardv/secured-usbip/blob/Master/libsrc/usbip_device_driver.c"
click node_vhci_driver "https://github.com/sridhardv/secured-usbip/blob/Master/libsrc/vhci_driver.c"
click node_remote_usbipd "https://github.com/sridhardv/secured-usbip/blob/Master/src/usbipd.c"
click node_gadget_vudc "https://github.com/sridhardv/secured-usbip/blob/Master/vudc/vudc_server_example.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_operator,node_usbip_cli,node_export_commands,node_client_commands,node_status_commands toneBlue
class node_usbipd,node_network_protocol,node_common_model,node_host_enumeration,node_device_driver,node_vhci_driver toneAmber
class node_usbip_host,node_vhci_hcd,node_local_usb_drivers toneMint
class node_remote_usbipd,node_physical_devices,node_gadget_vudc toneRose
```

## Components

### Operator Control

- **Operator or scripts**: actor
- [usbip CLI](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip.c): management executable · Dispatches export, import, discovery, and status commands. · `src/usbip.c`
- [Export lifecycle](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip_bind.c): CLI commands · `src/usbip_bind.c`
- [Client lifecycle](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip_attach.c): CLI commands · `src/usbip_attach.c`
- [Discovery and status](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip_list.c): CLI commands · `src/usbip_list.c`

### USB/IP Userspace

- [usbipd daemon](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbipd.c): server executable · Accepts USB/IP control connections and services exports. · `src/usbipd.c`
- [USB/IP network protocol](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbip_network.c): shared wire layer · Shared client/server TCP control operations; primary security-protocol boundary. · `src/usbip_network.c`
- [Shared USB/IP models](https://github.com/sridhardv/secured-usbip/blob/Master/libsrc/usbip_common.c): protocol and device model · `libsrc/usbip_common.c`
- [Host export enumeration](https://github.com/sridhardv/secured-usbip/blob/Master/libsrc/usbip_host_common.c): device inventory · `libsrc/usbip_host_common.c`
- [Device-driver sysfs layer](https://github.com/sridhardv/secured-usbip/blob/Master/libsrc/usbip_device_driver.c): driver abstraction · `libsrc/usbip_device_driver.c`
- [VHCI sysfs layer](https://github.com/sridhardv/secured-usbip/blob/Master/libsrc/vhci_driver.c): client driver abstraction · Allocates ports, attaches connections, and reports local imports. · `libsrc/vhci_driver.c`

### Linux Kernel Boundaries

- **usbip-host kernel driver**: external kernel module · Exports bound physical USB devices.
- **vhci-hcd kernel driver**: external kernel module · Provides local virtual host-controller ports.
- **Local Linux USB drivers**: kernel consumers · Consume imported devices after VHCI attachment.

### Remote Export Host

- [Remote usbipd](https://github.com/sridhardv/secured-usbip/blob/Master/src/usbipd.c): remote server · Provides discovery and requested device exports over TCP/3240. · `src/usbipd.c`
- **Physical USB devices**: exported hardware
- [Gadget ConfigFS and usbip-vudc](https://github.com/sridhardv/secured-usbip/blob/Master/vudc/vudc_server_example.sh): virtual export source · Optional gadget-backed export path. · `vudc/vudc_server_example.sh`

## Connections

- Operator or scripts → usbip CLI: runs
- usbip CLI → Export lifecycle: bind / unbind
- usbip CLI → Client lifecycle: attach / detach
- usbip CLI → Discovery and status: list / port
- Export lifecycle → Device-driver sysfs layer: manages binding
- Device-driver sysfs layer → usbip-host kernel driver: sysfs control
- usbip-host kernel driver → Physical USB devices: exports
- Client lifecycle → USB/IP network protocol: requests remote device
- Discovery and status → USB/IP network protocol: remote discovery
- USB/IP network protocol → Remote usbipd: TCP/3240
- Remote usbipd → usbipd daemon: same daemon role
- usbipd daemon → USB/IP network protocol: serves protocol
- usbipd daemon → Host export enumeration: enumerates exports
- Host export enumeration → Shared USB/IP models: builds device metadata
- Host export enumeration → Device-driver sysfs layer: reads driver state
- Client lifecycle → VHCI sysfs layer: attach / detach
- Discovery and status → VHCI sysfs layer: reads port state
- VHCI sysfs layer → vhci-hcd kernel driver: sysfs control
- vhci-hcd kernel driver → Local Linux USB drivers: presents imported USB device
- Gadget ConfigFS and usbip-vudc → usbipd daemon: optional virtual export