Server Configuration FAQ

1 post / 0 new
Server Configuration FAQ

All the VirtualHere USB Server settings are stored in a single text file called config.ini, usually in the same directory as the vhusbd binary, or when auto-running at start-up in /root. When the server is initially started, or started without a config.ini file it will use sensible defaults and any non-default values are written to new config.ini. (In Synology NAS's the configuration can be found at /volume1/@appstore/VirtualHere/config.ini)

Make sure the server is completely stopped and exited before you edit because the server modifies the config.ini file while it is running

If you are directly editing the config.ini file make sure you are running the latest version of the server as the parameters below are available in the latest version.

You may use environment variables inside the settings by enclosing the variable with ${...}

The config.ini file has the following parameters (they are not case sensitive), the parameters are entered into the config.ini in a name=value format, one per line.


ServerName The name of the server that appears in the client e.g "Virtual USB Hub". If you set this value to the special string $HOSTNAME$ it will take the hostname value of the server.

License The license code for the server. This value is emailed by VirtualHere when the server is registered.

DeviceNicknames This is in the format <nickname>,<vendor hex value>,<product hex value>,<address decimal>e.g My Apple iPad,5ac,129a,1112 The address is always the same if the device is plugged into the same port. You should use the VirtualHere client to set the nickname by right clicking on the device and selecting "Rename..." rather than directly editing this value because the address is not accessible until a client is connected.

UseAVAHI 1 means use Bonjour to broadcast the existence of this server on the network, 0 means don't use broadcast messages to advertise this server on a network. The default is 1 on. Turning off this setting is useful for clients behind firewalls who would rather directly enter IP addresses in the client because the firewall or subnet blocks IP broadcast packets.

CompressionLimit Once a USB transfer is greater than the number of bytes specified here, it will be compressed to save network transmission time. Smaller values will use more CPU for marginally improved network throughput, large values will use less CPU but network throughput will suffer. From trial and error 384 seems about right.

IgnoredDevices This specifies the devices to ignore if they are plugged into the server. This setting is of the format xxxx/yyyy,xxxx/yyyy,... where xxxx is the device USB Vendor id and yyyy is the device USB Product id (There are no leading zeros and the values are in hexadecimal). For example, VirtualHere running on Raspberry PI automatically populates this with 424/ec00 because this is the internal Raspberry Pi USB based Ethernet adapter built into the board which should not be shareable. To figure out the vendor/product id of a particular device, plug it in and view the device properties from the VirtualHere client.

IgnoredBuses This specifies the particular USB port(s) to ignore. It is of the format hostcontroller-hub.port,hostcontroller-hub.port,... For example to ignore device attached to port 2 on the Raspberry pi, set this value to 1-1.2

AllowedDevicesAll devices will be ignored except those devices listed here. It is the inverse of the IgnoredDevices setting. The format is the same as the IgnoredDevices setting i.e xxxx/yyyy,xxxx/yyyy,... (no leading zeros). If this value is empty all devices will be allowed (while taking into account the IgnoredBuses and IgnoreDevices settings above)

AutoAttachToKernel Set this to 1 to enable the device to be available to the host whenever a remote user is not using the device. The default is 1 for NAS's, Android and Debian (64/32bit) and 0 for all other platforms

ClaimPortsBy default this is 0 (off). When set to 1 the virtualhere server will prevent the server kernel from interacting with a device. Setting this value to 1 makes the server more compatible with USB devices that are sensitive to their configuration 1 being selected. When this setting is on, the only interaction with the device by the kernel is to query the device descriptor, however at the moment external hubs cannot be used with this setting on.

PingInterval The default value is 4 seconds. This the the number of seconds between ping messages from the server to the client. The client needs to respond withing PingTimeout (see below) before the socket is considered dropped and the connection is cleaned up. Sometimes a socket can drop if the network connection is unstable and this setting and the one below help to tune the server for unstable connections, however you should almost always leave these settings as the defaults.

PingTimeout The default value is 9 seconds. If the server doesn't get a response ping from the client after this time it connection is considered broken and cleaned up.

ControlTimeout The default value is 3 seconds. If the device is badly behaving (jammed for some reason) this setting detects that and returns an error to the client within this time, rather than waiting indefinately...

The following are advanced parameters and therefore are only supported on purchased servers

ClientIdMap This setting allows you to remap client ids to nicknames. A Client id is automatically passed in when a client logs in, it is determined by the client machine OS and has the format <fullname><space>(<username>). For example if the client has a username of "Michael Jones (michael)" you can change the client id to "Mick", then this will appear in the in-use information for other clients. This setting format is ClientIdMap=<client id>,<nickname>[,<client id>,<nickname>...] e.g ClientIdMap=Michael Jones (michael),Mick,Steve Jones (steve),Steve. The client id must match exactly the username and full name of the client. This can be found by right clicking an in Use device and looking at the USER: entry in the properties.

HideClientInfoThe default value is 0 (false). If set to 1 Device In-Use information is not displayed to other clients

NetworkInterface This specifies what Network Interface to bind the server to. If this is not specified (the default) then the server will listen for incoming client connections on all network interfaces. Otherwise specify the IP address to bind the server to if you have multiple network cards and only want to listen on one of them.

ClientAuthorization This specifies the script to run to authorize particular user/device combinations. See here for more information

ClientDeauthorization Identical to ClientAuthorization except is called when a user disconnects from a device

SSLCert Full path to the ssl PEM certificate file (containing the public and private key unencrypted) to use for the SSL transport. If this parameter is specified then all communications with the server will run over SSL instead of plain TCP. The port will be specified in the sslPort setting below. See here for more information about SSL

SSLPortIf the sslCert parameter is specified then this port will be used for client communications. The port defaults to 7574

SSLUseClientCertsSet this parameter to 1 to turn on client SSL certificates. If this is on, the VirtualHere Client must present a SSL Client certificate to the server on connection

SSLCAFileThis file is contains the PEM encoded Certificate Authority(CA) Trusted Root Certificates used the Server and Client SSL certificates.

ReverseClients. (NEW, if you upgrade to (at least) server 2.4.5 and client 3.1.1 then this is configurable directly in the GUI or client API, no need to manually edit the server configuration file), This setting will make the server initiate a connection to the client, instead of the usual way of the client initiating the connection. This is useful for servers behind firewalls or NAT's. Specify the host ip and optional port of each client separated by comma. e.g ReverseClients=, If no port is specified, it will default to 7573. In the clients, make sure Enable Reverse Connections is checked under Right Click USB Hubs -> Specify Hubs -> Firewall/NAT. The server will attempt to connect to each client in turn.

ReverseClientsRetryPeriod This defaults to 15 seconds. This is the amount of seconds between connection attempts by the server to reverse clients (it doesn't have a connection to yet.)

The VirtualHere server also contains an event handling system that can be configured to call scripts at certain times. This is useful to workaround device quirks or to perform specific actions like logging see here