In the vast majority of cases Dinkey dongles will work correctly under a virtual machine environment and also with containers.

In this article we will give some guidance on how to use Dinkey dongles with some of the most popular virtual machines and also list some restrictions of using these environments.

The first section is general advice. The next section gives specific details for each different brand of VM.

Claim the Dinkey Dongle device in the VM

You must allow the virtual machine to access USB devices and to "claim" the Dinkey Dongle device. The dongle can be attached to the host or the client computer. Only one VM can access a dongle at any one time. For Docker containers you must allow access to the USB dongle on the host. In this case many containers can access the same device (but this can create its own problems - see below).

Restrictions

1. If you are using an FD Plus or FD Net dongle then our API will not return the drive letter or mount name of the flash disk. This is because virtual machines do not preserve the USB device hierarchy. You must set the DONT_RETURN_FD_DRIVE flag otherwise the protection check will fail with error 578.
2. There may be some restrictions when using the "lock dongle to user's computer" option; or when using Temporary Software Keys; or Demo Software Keys.
3. In some rare cases users have reported intermittent problems communicating with the dongle. However, these cases are becoming rarer as USB support is improved.

VMWare

If you have to use a virtual machine setup we would recommend you use VMWare because we have encountered the least amount of problems with this setup.

Setup:

1. If your client OS is Linux then you may need to add USB support: Select the VM and then select Edit | Virtual Hardware. If there is no USB controller listed then you need to add one: Add Other Device | USB Controller.
2. You need to capture our Dinkey Dongle device. This is different depending on whether the device is attached to the host or the local client comupter:
   Dongle attached to host. Choose Edit | Virtual Hardware and then Add Other Device | USB Device. Select "HID Dongle" from the list of devices.
   Dongle attached to local computer. For vSphere versions before 6.5 you should run the vSphere Client to claim the "HID Dongle". For vSphere versions 6.5 or higher you need to use the Remote Console. If this has not been installed on the local computer then choose Console | Download VMRC. After the Remote Console has been installed then choose Console | Launch Remote Console. From the remote console choose VMRC | Removable Devices | HID Dongle | Connect.

Notes:

1. There are no restrictions with software keys or locking the dongle to the computer.
2. We have noticed no differences if you use VMWare vSphere ESXi (bare metal) or whether you use a host OS.

VirtualBox

Setup:

1. You need to make sure you install USB support.
2. In Settings, choose USB. Tick "Enable USB Controller" and add device "OEM HID Dongle" (and appropriate flash disk if using Dinkey FD) to the list of "USB Device Filters". In the virtual box the HID Dongle device should have a tick by it.

Problems:

No current problems but in the past we have had reports of following problems:

1. The client OS failing to capture the Dinkey Dongle devices.
2. It is possible to very occassionally receive errors communicating with the dongle - such as 486/33 or 466/33 or 461... If this is the case we would recommend checking the dongle again on failure - only abort your program on two successive dongle check failures.

Notes:

1. There are no restrictions with software keys or locking the dongle to the computer.

Microsoft Hyper-V

Versions of Hyper-V before Windows Server 2012 R2 do not support USB controllers. Therefore no USB devices are recognised (except for the keyboard and mouse).

Hyper-V for Windows Server 2012 R2 claims to support USB-passthrough (in enhanced session mode). However, support for USB devices appears to be very limited and none of our devices are recognised by the virtual machine.

A work-around is to use a Remote Desktop Connection or a USB-over-network solution that can share USB ports across the network.

Virtual PC

Some limited USB exists but USB HID devices are not supported. Therefore Dinkey Pro and Dinkey FD Plus/Net devices are not supported. However, Dinkey FD Lite dongles are supported as are our original Dinkey 1S/2/Net dongles.

Parallels

No reported problems.

Proxmox VE - Full Virtualisation with KVM

Dongle attached to the host. Select the Virtual Machine from the list on the Proxmox management page, then Hardware, "Add" and choose USB device, then "Passthrough full port" for the port with the dongle attached.

Dongle attached to the local computer. If the dongle is plugged into the client PC that connects to a guest Virtual Machine on the host and needs to be passed through to the VM, the VM will need to be configured to use the SPICE console. Instructions on how to configure this are available on the Proxmox website and other places, but the first thing to do is to configure the display adapter for the VM to be SPICE, which will enable the SPICE option on the Console menu. You must also ensure that there is a USB port of type SPICE in the VM hardware configuration for the device passed through to bind to. Windows clients will need virt-viewer installed for the SPICE console and the UsbDk driver to allow USB passthrough. Both of these are downloadable from the SPICE download page.

Open a SPICE console to the VM and click the middle of the three icons in the top left corner, which opens the USB management dialog. Select the dongle plugged into the client machine and this will be passed through to the guest.

We are aware of an issue affecting USB passthrough on some Windows 10 and 11 clients. It is a general issue with USB passthrough from Windows clients and not specific to Dinkey Dongle. Please see this topic for an explanation and solution:
https://gitlab.com/virt-viewer/virt-viewer/-/issues/61

Proxmox VE - Linux Containers (LXC)

Note - all these commands are executed on the host.

1. As root run "lsusb" to list connected USB devices. Note the Bus number and the Device number for the HID Dongle. e.g.
   Bus 005 Device 002: ID 096e:0007 HID Dongle
   In this case the bus number is 005 and the device number is 002. We will use these in the following steps.
2. Execute: ls -al /dev/bus/usb/005/002
   example output: crw-rw-r-- 1 root root 189, 513 Nov 15 09:54 /dev/bus/usb/005/002 Record the first number e.g. 189.
3. Change the ownership of the device on the host:
   chown 100000:100020 /dev/bus/usb/005/002
   The base values of 100000 mean "host". 20 is the "dialout" group. These get passed to the guest less 100000, so it appears there as root:dialout.
4. Edit the container configuration file: /etc/pve/lxc/100.conf
   (where 100 is the container ID of the one you want to use the dongle). Add these lines to the end of the file:
   lxc.cgroup.devices.allow: c 189:* rwm
   lxc.mount.entry: /dev/bus/usb/005/002 dev/bus/usb/005/002 none
   bind,optional,create=file
   Note - in the devices.allow line you can optionally restrict it to the device id of 513 rather than *
5. The container should now be restarted and then dongle should be now be accessible from it. (You will stil have to run "inst" on the container like normal).

If you have more than one container accessing a dongle on the same host then you need to mount the host /tmp into all the containers which access the dongle.

The "lock dongle to user's computer" feature will not work in the container. Temporary and Demo Software Keys also will not work correctly.

Docker Containers

Containers are similar to virtual machines except that they virtualise the necessary environment for a particular application rather than an entire operating system.

The main problem we have found is that we need to use a system-wide Mutex to control access to the dongle from multiple processes. This Mutex would need to work across all the containers (that need to access the dongle) on a host. If this is not done then you will receive occasional errors accessing the dongle if you access them from more than one container.

To do this under Linux or Mac you must mount the host /tmp into all the containers which run programs needing to access the dongle.

Under Windows this does not appear to be possible. In this case we do not recommend that more than one docker container accesses the dongle at any one time or that a container shares access to the dongle with the host.

The "lock dongle to user's computer" feature will not work.

Temporary Software Keys and Demo Software Keys will only work until the container is restarted.

Note - sometimes people use Alpine Linux with Docker containers because it is a slim Linux distribution. However, Apline Linux uses musl rather than glibc and therefore is incompatible with the Dinkey Pro software.

Windows Subsystem for Linux (WSL)

We tested WSL by following the official documentation to install Ubuntu 22.04 on WSL 2 on Windows 11. No issues were found.

When installing the Dinkey Pro SDK on WSL, you must extract the SDK archive to the WSL file system, e.g. in /home/<user>/dinkey-pro-sdk. Do not extract the archive on Windows and try to access it via /mnt/c in WSL, or errors may occur when using the SDK utilities.