usbipd-mac

A macOS implementation of the USB/IP protocol that allows sharing USB devices over IP networks.

Overview

usbipd-mac is a macOS implementation of the USB/IP protocol that allows sharing USB devices over IP networks. This server implementation enables macOS users to share USB devices with any compatible USB/IP client, with a focus on compatibility with the Linux Kernel virtual HCI driver (vhci-hcd.ko). Docker support on macOS is also a goal.

Features

• USB device sharing from macOS to other systems over network
• Full compatibility with the USB/IP protocol specification
• System Extensions integration for reliable device access and claiming
• Automated System Extension bundle creation and deployment
• Lightweight QEMU test server for validation
• Docker enablement for USB device access from containers

Requirements

• macOS 11.0+: System Extensions are only supported on macOS Big Sur and later
• Xcode 13+: Required for System Extensions support and Swift Package Manager
• Code Signing: Optional for development, required for distribution

Installation

Homebrew Installation (Recommended)

The easiest way to install usbipd-mac is through Homebrew:

# Add the usbip tap
brew tap beriberikix/usbipd-mac

# Install usbip
brew install usbip

Service Management

After installation, you can manage the usbipd daemon using Homebrew services:

# Start the service (requires sudo for System Extension access)
sudo brew services start usbip

# Stop the service
sudo brew services stop usbip

# Restart the service
sudo brew services restart usbip

# Check service status
brew services info usbip

System Extension Setup

After Homebrew installation, you'll need to install and approve the System Extension:

1. Automatic Installation: Use the built-in installation command:

   # Install and register the System Extension (requires sudo)
   sudo usbipd install-system-extension

2. System Extension Approval: macOS will prompt you to approve the System Extension in System Preferences > Security & Privacy > General

3. Restart Required: A restart may be required for the System Extension to become active

4. Verification: Check the System Extension status with usbipd status

Installation Diagnostics: If you encounter issues, run comprehensive diagnostics:

# Run complete installation diagnostics
usbipd diagnose

# Run verbose diagnostics for detailed troubleshooting
usbipd diagnose --verbose

Troubleshooting Homebrew Installation

Common installation issues and solutions:

• Permission Errors: Ensure you run service commands with sudo as the daemon requires System Extension privileges
• System Extension Blocked: Check System Preferences > Security & Privacy and approve the extension
• Service Won't Start: Verify the binary installed correctly with which usbipd and check logs with brew services list
• Version Issues: Update with brew upgrade usbip or reinstall with brew reinstall usbip

System Extension Installation Troubleshooting

For System Extension specific issues:

Installation Problems:

• Bundle Not Found: Ensure Homebrew installation completed successfully, reinstall if needed
• Registration Failed: Run sudo usbipd install-system-extension --verbose for detailed error information
• User Approval Required: System Extensions require explicit user approval in System Preferences
• Developer Mode Required: For unsigned builds, enable developer mode: sudo systemextensionsctl developer on

Common Error Solutions:

# Check detailed installation status
usbipd diagnose --verbose

# Re-install System Extension if corrupted
sudo usbipd install-system-extension --skip-verification

# Verify System Extension is properly registered
systemextensionsctl list

# Check System Extension process status
usbipd status

System Requirements:

• macOS 11.0+: System Extensions are only available on Big Sur and later
• Code Signing: Production releases require properly signed System Extensions
• System Integrity Protection: Must be compatible with SIP settings
• User Approval: Interactive approval required in System Preferences

Manual Installation (Development)

For development or manual installation, see the Building the Project section below.

Usage

Once installed, you can use usbip to share USB devices over the network:

Basic Commands

# List available USB devices
usbipd list

# Share a USB device (device ID from list command)
usbipd bind --device <device-id>

# Check daemon status and shared devices
usbipd status

# Stop sharing a device
usbipd unbind --device <device-id>

System Extension Management

# Install and register the System Extension
sudo usbipd install-system-extension

# Run comprehensive installation diagnostics
usbipd diagnose

# Run verbose diagnostics with detailed information
usbipd diagnose --verbose

# Check System Extension status and health
usbipd status --verbose

Client Connection

From a USB/IP client (typically Linux):

# Install USB/IP tools (Ubuntu/Debian)
sudo apt install linux-tools-generic

# Connect to shared device
sudo usbip attach -r <macos-ip-address> -b <device-id>

# List attached devices
usbip port

# Detach device
sudo usbip detach -p <port-number>

Docker Integration

For Docker Desktop users:

# Ensure the service is running
sudo brew services start usbip

# USB devices will be available to Docker containers
# through the USB/IP protocol integration

Project Status

This project is currently in early development. The core server functionality is being implemented as an MVP.

Building the Project

Quick Start

# Build the project
swift build

# Build with Xcode (recommended for development)
xcodebuild -scheme usbipd-mac build

System Extension Development

For development with System Extensions:

# Enable System Extension development mode (requires reboot)
sudo systemextensionsctl developer on

# Build the project (includes System Extension bundle creation)
swift build

# Install System Extension for development
sudo usbipd install-system-extension

# Run diagnostics to verify installation
usbipd diagnose

# Check detailed status including bundle information
usbipd status --verbose

Running Tests

# Run all tests
swift test

# Run specific test environments (see Documentation for details)
./Scripts/run-development-tests.sh    # Fast development tests
./Scripts/run-ci-tests.sh             # CI-compatible tests  
./Scripts/run-production-tests.sh     # Comprehensive validation

Documentation

For detailed information about development, architecture, and troubleshooting, see the comprehensive documentation in the Documentation/ folder:

Development Documentation

• Architecture - System design and component overview
• CI/CD Pipeline - Continuous integration and branch protection
• System Extension Development - System Extension setup and development
• Testing Strategy - Test environments and validation approaches

API and Protocol Documentation

• USB Implementation - USB/IP protocol implementation details
• Protocol Reference - USB/IP protocol specification
• QEMU Test Tool - QEMU validation server usage

Troubleshooting Guides

• Build Troubleshooting - Common build and setup issues
• System Extension Troubleshooting - System Extension specific problems
• Homebrew Troubleshooting - Homebrew installation and service issues
• QEMU Troubleshooting - QEMU test server issues

Release Automation

usbipd-mac uses automated GitHub Actions workflows for consistent and reliable releases.

For Maintainers

Release Process

1. Create and Edit Changelog:

   # Manually edit CHANGELOG.md to document changes for the release
   # Add entries under the [Unreleased] section
   # Follow Keep a Changelog format

2. Commit Changelog:

   # Commit the changelog updates
   git add CHANGELOG.md
   git commit -m "docs: update changelog for v1.2.3 release"

3. Prepare Release Locally:

   # Prepare specific version (will prompt to review auto-generated changelog)
   ./Scripts/prepare-release.sh --version v1.2.3
   
   # The script will:
   # - Update CHANGELOG.md with version entry
   # - Pause for you to manually edit the changelog
   # - Run validation, tests, and create the Git tag

   Available options:

   • --version VERSION: Specific version (e.g., v1.2.3 or 1.2.3)
   • --dry-run: Preview actions without making changes
   • --skip-tests: Skip test execution (not recommended)
   • --skip-lint: Skip code quality checks (not recommended)
   • --force: Override safety checks and skip manual changelog review

4. Push Release Tag:

   # Push the created tag to trigger automated workflows
   git push origin v1.2.3

5. Automated Pipeline: Once a version tag is pushed, GitHub Actions automatically:

   • Validates the release candidate
   • Builds production artifacts with code signing
   • Runs comprehensive test validation
   • Updates Homebrew formula automatically
   • Creates GitHub release with artifacts and checksums
   • Pushes formula changes back to the repository

6. Emergency Releases: For critical fixes, use --force to skip manual changelog review and validation.

Homebrew Formula Management

External Tap Architecture: The Homebrew formula is managed in a separate tap repository and is updated automatically via homebrew-releaser GitHub Action during the release workflow.

Automated Formula Update Process:

The release workflow uses homebrew-releaser for direct formula updates:

• Homebrew-releaser action automatically updates formula in the external tap repository: homebrew-usbipd-mac
• Formula is committed directly to tap repository with proper version and SHA256
• No metadata files or manual intervention required

Immediate Availability - users can install and update through Homebrew immediately after a release is published.

Formula Testing and Validation:

# Test installation from tap
brew uninstall usbip || true
brew untap beriberikix/usbipd-mac || true
brew tap beriberikix/usbipd-mac
brew install usbip

Formula Repository: The formula and automation workflows are maintained in the separate homebrew-usbipd-mac repository.

Versioning Strategy

• Semantic Versioning: Follow semver (MAJOR.MINOR.PATCH) for all releases
• Release Schedule: Monthly minor releases with patch releases as needed
• Pre-releases: Use -alpha, -beta, -rc suffixes for testing releases
• Changelog: Automatically generated from conventional commits

Required Setup

For release automation to work properly:

1. Code Signing: Configure Apple Developer certificates in GitHub repository secrets
2. Permissions: Ensure maintainer access to repository settings and secrets
3. Environment: Validate local environment with release preparation script

Validation commands:

# Check release preparation environment
./Scripts/prepare-release.sh --help

# Validate formula update tools
./Scripts/update-formula.sh --help

# Validate formula syntax
./Scripts/validate-formula.sh --help

See Release Automation Documentation for complete setup instructions and troubleshooting.

For Contributors

Release automation is handled by maintainers. Contributors should:

• Follow conventional commit format for automatic changelog generation
• Ensure all PRs pass CI validation before merge
• Report issues with release automation to repository maintainers

License

MIT License