Skip to content

Installation

VIIPER comes in two distinct flavors:

  • VIIPER Server A self-contained, portable, standalone executable providing a lightweight TCP-based API for feeder application development.
    All client libraries are MIT licensed.
  • libVIIPER
    a single shared library that lets you emulate devices using USBIP directly from within your application. Requires your application to be GPL-3.0 licensed.

Regardless of the flavour you choose, VIIPER requires USBIP.

Requirements

USBIP

VIIPER relies on USBIP. You must have a USBIP-Client implementation available on your system to use VIIPER's virtual devices.

VIIPERs installation will install the necessary USBIP components/driver for you.
It is only listed here for informational purposes.

usbip-win2 is by far the most complete implementation of USBIP for Windows (comes with a SIGNED kernel mode driver).

Install and done 😉

Ubuntu/Debian

sudo apt install linux-tools-generic

Ubuntu USBIP Manual

Arch Linux

sudo pacman -S usbip

Arch Wiki: USBIP

Linux Kernel Module Setup

USBIP Client Requirement

USBIP requires the vhci-hcd (Virtual Host Controller Interface) kernel module on Linux for client operations. This includes VIIPER's auto-attach feature and manual device attachment.

Most Linux distributions include this module but do not load it automatically.

One-Time Setup

To load the module automatically on boot:

echo "vhci-hcd" | sudo tee /etc/modules-load.d/vhci-hcd.conf
sudo modprobe vhci-hcd

Manual Loading

To load the module for the current session only:

sudo modprobe vhci-hcd

Verification

lsmod | grep vhci_hcd

A standalone executable that exposes an API over TCP.

Installing VIIPER

VIIPER does not require system-wide installation. The viiper executable is completely self-contained (fully portable, no dependencies except USBIP) and can be:

  • Placed in any directory
  • Shipped alongside your application
  • Run directly without installation
  • Bundled with your application's distribution

Daemon/Service Conflicts

If VIIPER is already running as a system service or daemon on the target machine, be aware of potential port conflicts. Applications should: - Check if VIIPER is already running before starting their own instance - Use the ping API endpoint to check for VIIPER presence and version - Connect to the existing VIIPER instance (if accessible) - Use a custom port via --api.addr flag to run a separate instance

Disabling Auto-Update Notifications

VIIPER comes with an inbuilt auto updater.
If you decide to ship VIIPER portably, as opposed to installing it system-wide, you might want to disable auto-update notifications to avoid unexpected prompts.

To disable auto-update notifications, use the --update-notify=none flag, set the VIIPER_UPDATE_NOTIFY environment variable to none, or configure this option in VIIPER's configuration file.

Linux Permissions

On Linux, attaching devices via USBIP requires root permissions. You can run VIIPER with sudo, or configure appropriate udev rules to allow non-root users to attach devices.

Pre-built Binaries

Download the latest release from the GitHub Releases page. Pre-built binaries are available for:

  • Windows (x64, ARM64)
  • Linux (x64, ARM64)

Installer

The VIIPER executable is its own installer.
Run the release binary and you will be prompted to install VIIPER or run the sever portably.

Windows: VIIPER is on winget

winget install Alia5.VIIPER

Double-click viiper-windows-x64.exe and choose Install/Update VIIPER, or run:

.\viiper-windows-x64.exe install
  • Update to the latest release: checks GitHub and installs the newest release instead of the binary you ran
  • Autostart: starts the server when you log in
  • Start menu shortcut / Desktop shortcut
  • Install USBIP: downloads and runs the usbip-win2 installer when it is missing or outdated (asks for administrator rights; usbip-win2 asks for a reboot)
  • Start the server now

Installs to %LOCALAPPDATA%\VIIPER\viiper.exe by default and registers VIIPER in Apps & Features, where it can be modified or uninstalled.

Unattended install, for scripts and package managers (defaults for every choice, no output):

.\viiper-windows-x64.exe install --quiet

Installs to: %LOCALAPPDATA%\VIIPER\viiper.exe

  • --no-update disables the auto-update upon install
  • USBIP is installed without its wizard; a reboot may be required

Uninstall from Apps & Features or with:

viiper.exe uninstall

chmod +x viiper-linux-amd64
sudo ./viiper-linux-amd64 install
  • Update to the latest release: checks GitHub and installs the newest release instead of the binary you ran
  • Add systemd service / Enable service
  • Install USBIP: installs the distribution package (pacman, apt or dnf), loads vhci_hcd and configures it to autoload
  • Start the server now

Installs to /usr/local/bin/viiper by default.

Unattended install (defaults for every choice, no output):

sudo ./viiper-linux-amd64 install --quiet

Uninstall with:

sudo viiper uninstall

Manual installation

For package maintainers, or if you prefer not to use the built-in installer.
This is what the installer does:

  1. Copy the binary and the bundled licenses:

    sudo install -m 755 viiper-linux-amd64 /usr/local/bin/viiper
sudo install -m 644 licenses.txt /usr/local/bin/licenses.txt

  2. Install USBIP and load vhci_hcd on boot (see USBIP above):

    echo "vhci_hcd" | sudo tee /etc/modules-load.d/viiper.conf
sudo modprobe vhci_hcd

  3. Create /etc/systemd/system/viiper.service:

    [Unit]
Description=VIIPER server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart="/usr/local/bin/viiper" server
WorkingDirectory=/usr/local/bin
Restart=on-failure

[Install]
WantedBy=multi-user.target

  4. Enable and start it:

    sudo systemctl daemon-reload
sudo systemctl enable --now viiper.service

To remove: stop and disable the service, delete the unit file, /etc/modules-load.d/viiper.conf, the binary and licenses.txt.

To disable VIIPERs auto-update notifications, you can use the --update-notify=none flag or set the VIIPER_UPDATE_NOTIFY environment variable to none or place this option in VIIPERs configuration file.

One-line install

Downloads the release binary and runs install --quiet.

winget install Alia5.VIIPER

curl -fsSL https://alia5.github.io/VIIPER/stable/install.sh | sh

libVIIPER is a shared library (libVIIPER.dll on Windows, libVIIPER.so on Linux) that you link against directly from your application, eliminating the need for a separate VIIPER server process.

License

Linking against libVIIPER requires your application to be licensed under the GPL-3.0 (or a compatible license). If you cannot comply with the GPL-3.0, use the standalone executable and the TCP API instead. All client libraries are MIT licensed.

Pre-built Binaries

Download the latest libVIIPER release artifact from the GitHub Releases page. The archive contains:

  • libVIIPER.dll / libVIIPER.so: the shared library
  • libVIIPER.h: the C header
  • libVIIPER.def: Windows import definition (for generating .lib/.dll.a import libraries)

Building from Source

git clone https://github.com/Alia5/VIIPER.git
cd VIIPER
just build-libVIIPER

The output will be in dist/libVIIPER/.

CGO Required

Building libVIIPER requires CGO (CGO_ENABLED=1) and a C compiler (GCC / MSVC / Clang) in PATH. On Windows, llvm-mingw is recommended.

See libVIIPER documentation for integration guides and examples.