USB/IP — sing-box

Два сервиса предоставляют общий доступ к USB-устройствам по USB/IP: usbip-server экспортирует локальные устройства, а usbip-client импортирует устройства с удалённого сервера. Оба построены на sing-usbip, который добавляет к стандартному протоколу улучшения вроде горячего подключения, оставаясь с ним совместимым: стандартный клиент USB/IP может импортировать с usbip-server, но usbip-client требует сервер sing-box (sing-usbip).

Сервер — usbip-server

type: "usbip-server" в services[]:

Поле	Тип	По умолчанию	Допустимые значения	Описание
provider	string	default	default | dynamic	Откуда берутся экспортируемые устройства. default экспортирует локальные устройства, подходящие под devices (только при запуске из CLI в Linux, Windows и macOS, с повышенными правами). dynamic получает устройства во время работы от клиента API sing-box — графических клиентов в macOS и Android или sing-box Dashboard в браузере на базе Chromium.

Исходный код: option/usbip.go:17-21 · зафиксировано на v1.14.2 (af6e64c)

Сервер также встраивает ListenOptions (см. Входящие); listen_port по умолчанию 3240 — стандартный порт USB/IP. При provider: "default" принимается:

Поле	Тип	По умолчанию	Допустимые значения	Описание
devices	[]USBIPDeviceMatch	(required)	[USBIPDeviceMatch]	Какие локальные устройства экспортировать. Обязательно для поставщика default.

Исходный код: option/usbip.go:77-79 · зафиксировано на v1.14.2 (af6e64c)

У поставщика dynamic дополнительных полей нет.

Сопоставление устройств

Поле	Тип	По умолчанию	Допустимые значения	Описание
bus_id	string	(any)	<bus-port>	Идентификатор шины USB, например 1-2.
vendor_id	uint16	(any)	<uint16>	Идентификатор производителя USB в виде числа JSON (десятичного — например, 1133 для 0x046d).
product_id	uint16	(any)	<uint16>	Идентификатор продукта USB в виде числа JSON.
serial	string	(any)	<string>	Серийный номер устройства.

Исходный код: option/usbip.go:70-75 · зафиксировано на v1.14.2 (af6e64c)

Все поля, заданные в одном объекте, должны совпасть; несколько объектов объединяются. В каждом объекте нужно хотя бы одно поле.

Клиент — usbip-client

type: "usbip-client" в services[]:

Поле	Тип	По умолчанию	Допустимые значения	Описание
server	string	(required)	<host>	Адрес удалённого usbip-server.
server_port	uint16	3240	<port>	Порт удалённого usbip-server.

Исходный код: option/outbound.go:183-186 · зафиксировано на v1.14.2 (af6e64c)

Поле	Тип	По умолчанию	Допустимые значения	Описание
devices	[]USBIPDeviceMatch	(all exported)	[USBIPDeviceMatch]	Какие удалённые устройства импортировать, с теми же объектами сопоставления, что и на сервере. Пустое значение импортирует все экспортируемые устройства.

Исходный код: option/usbip.go:64-68 · зафиксировано на v1.14.2 (af6e64c)

Клиент встраивает поля подключения (см. Исходящие), но действует только detour.

Минимальный пример

Сервер, экспортирующий клавиатуру по идентификаторам производителя и продукта плюс всё, что подключено к порту шины 1-2:

{
  "services": [
    {
      "type": "usbip-server",
      "tag": "usb-share",
      "listen": "0.0.0.0",
      "devices": [
        { "vendor_id": 1133, "product_id": 49948 },
        { "bus_id": "1-2" }
      ]
    }
  ]
}

Клиент, импортирующий только устройство на порту шины 1-2:

{
  "services": [
    {
      "type": "usbip-client",
      "tag": "usb-remote",
      "server": "192.0.2.10",
      "devices": [{ "bus_id": "1-2" }]
    }
  ]
}

Примечания

• Требуется тег сборки with_usbip, и сервисы собираются только для Linux, Windows и macOS с CGO. В остальных случаях (включая iOS) оба типа существуют, но запуск завершается ошибкой "USB/IP is not included in this build".
• provider: "default" работает только при запуске sing-box напрямую из CLI и требует повышенных прав; для экспорта в macOS дополнительно нужно отключить System Integrity Protection.
• При provider: "dynamic" устройства предоставляются во время работы через сервис API — из графических клиентов, Dashboard или командой sing-box api.
• Стандартный USB/IP не шифрует трафик и не аутентифицирует клиентов, а у обоих сервисов нет полей для учётных данных. Открывайте usbip-server только в доверенных сетях или подключайтесь к нему через туннель с помощью detour клиента.

Сравнение с другими ядрами

• Ни у Xray-core, ни у mihomo нет аналога USB/IP.

Исходный код: option/usbip.go:17-81 · v1.14.2 (af6e64c)