flexVDI Desktop Client

Owned by Javier Celaya (Unlicensed)
Last updated: Sept 04, 2020 by Jorge Olmos (Unlicensed)
26 min read

Overview

Starting with version 3.1, the flexVDI clients for Windows, Linux and Mac OS have been unified into the flexVDI Desktop Client. It is a complete rewrite of the client code, that focuses on portability and uniformity. This client provides a common experience across all the supported platforms, both in terms of visual aspect and features. Besides, its new architecture allows to keep up with the most recent versions of the Spice Client library, with added stability and performance.

Installation

You can download the flexVDI Desktop Client 3.1 from our web page, as usual. Besides, we have made this new rewrite completely open source. You can find the source code in our GitHub repository.

The installation process depends on the platform:

  • Windows: The flexVDI Desktop Client for Windows 3.1 can be downloaded as an installer, for both 32 and 64 bit platforms. It supports Windows platforms from Windows 7 to Windows 10. Download the suitable installer for your platform, run it and follow the steps as described on screen.
  • Linux: Currently, the Linux version of the flexVDI Desktop Client is available as an AppImage executable, for both 32 and 64 bit platforms. Download the suitable version for your platform, move it to a directory that is in your PATH (~/bin, for instance), give it execution rights and you can start using it right away.
  • Mac OS: The Mac OS version of the flexVDI Desktop Client is distributed as a DMG image, in the usual way of other software for this platform. Just open the image and drag the flexVDI icon to your Applications folder.

Getting started

The first time you run the flexVDI Desktop Client, you will see the following window:

The main window of the flexVDI Desktop Client consist of some common elements and a form widget in the main body of the window that changes depending on the situation. The common elements are:

  • The top title bar, with the flexVDI logo on the left, and the settings (cog wheel) and about (interrogation mark) buttons on the right. Status and error messages appear just under this bar.
  • The main body, with a customizable client logo and the current form widget.
  • The footer, with information about the terminal ID of this client and its version.

The current form widget will change with the user actions, as it evolves through the authentication process until the desired desktop is selected. When you start the client for the first time, no flexVDI platform is configured yet, so the application takes you directly to the settings form.

Settings

In the settings form, you can set:

  • Connection address: The name or IP address of the flexVDI platform.
  • Port: The TCP port to connect to. By default it is 443.
  • Fullscreen: Whether to switch to fullscreen as soon as the connection to the desktop is made.
  • Proxy URI: The URI of a web proxy to use for the connection if no direct communication is available. E.g. https://user:passwd@proxy.mycompany.com

Click on "save settings" once you have configured them, or "discard changes" if you want to revert anything you changed. You can come back to the settings form at any time pushing the cog wheel button on the upper-right corner of the window, or pressing F3 on your keyboard.

If this is your first time trying out flexVDI, we encourage you to test our demo platform: connect to manager.flexvdi.com, port 443, and log in with user flexvdi and any password.

Authentication

When a flexVDI platform address is set, the application navigates to the login form:

This form shows an input for the username, another for the password and a login button. But before you can write anything, the client will connect with the platform and identify itself using its Terminal ID. If the platform decides that your terminal does not require authentication, the application will skip this step. Otherwise, you can write your credentials and push the login button (or just hit enter).

Desktop selection

Finally, the application navigates to the desktop selection form:

The client presents the list of possible desktops that the platform has offered. You can select one by clicking on it and then pushing the "connect" button, or just double-clicking on it. You can also navigate the list with the up and down arrow keys, or search for a desktop by typing its name. Finally, you can also go back to the login form with the "back" button. If the platform offers just one possible desktop, this step is skipped and the application jumps directly to connect with the desktop.

Status and errors

The flexVDI Desktop Client shows some status and error messages just under the main window's title bar. These are some examples:

Desktop presentation

When the client connects to a virtual desktop, the main window disappears and the desktop presentation window is shown. It consists of just a toolbar and the desktop area:

The toolbar contains the following actions:

  • Copy from guest: Copies the content of the virtual desktop's clipboard into the client's clipboard.
  • Paste to guest: Pastes the content of the client's clipboard into the virtual desktop's clipboard.
  • Send key combinations: Shows a dropdown with a list of key combinations to send to the virtual desktop, but that cannot be captured by the client. E.g. Ctrl+Alt+Supr.
  • Share USB devices: Shows a dropdown with the list of USB devices currently connected to the client's computer. Each one has checkbox that states whether the device is redirected to the virtual desktop.
  • Share printers: Like the previous one, this action shows a dropdown with the list of configured printers in the system, with a checkbox each one to redirect them to the virtual desktop.
  • Reset: Sends a reset signal to the virtual desktop, that is abruptly restarted. This action and the following two show a confirmation dialog.
  • Orderly shutdown: Sends a shutdown signal to the virtual desktop. The guest operating system can catch it and shut itself down in an orderly fashion, or ignore it. In the former case, the client application will exit.
  • Immediate poweroff: Sends a poweroff signal, terminating the virtual desktop at once and exiting the client application.
  • About: Shows the about dialog.
  • Go fullscreen: Puts the window in fullscreen mode.

When in fullscreen mode, only the desktop area is visible all the time. The toolbar slides down from the screen top edge (bottom edge in Mac OS) when you move the mouse pointer near it:

Besides, the "Go fullscreen" action is replaced with these other actions:

  • Minimize: Minimizes the client window.
  • Restore view: Exits from the fullscreen mode.
  • Close connection: Closes the connection with the virtual desktop and exits the client application.

Some of the buttons in the toolbar are not visible under the following circumstances:

  • The copy and paste buttons, USB devices dropdown, printers dropdown and power buttons do not appear when the respective features are disabled by the flexVDI platform for the current desktop.
  • The copy and paste buttons are visible only if automatic clipboard sharing is disabled (it is enabled by default).
  • The USB devices dropdown does not appear in Mac OS, because USB redirection is not supported in this platform.

Clipboard sharing

FlexVDI Client supports clipboard sharing with virtual desktops when the flexVDI Guest Tools are installed in the guest. Both copying from and pasting into the guest is supported, and can be disabled independently by the platform. By default, clipboard sharing is automatic, so you can just press Ctrl+C in the virtual desktop and Ctrl+V in the physical desktop, and the contents of the clipboard will be transferred automatically. If you do not want this to happen, or it is working erratically (this may happen if you have a clipboard manager installed in either side), automatic clipboard sharing can be disabled with a configuration flag, which are discussed later in this document. In that case, the copy and paste buttons are shown in the toolbar so that you can decide when to share the clipboard.

Clipboard sharing only supports certain basic types of data, like text and images. Copying whole files or directories is not supported, for that operation see the "File drag'n'drop" and "Shared folder" features later in this document.

Sending keystrokes

When the desktop presentation window is the active window, most keystrokes are sent to the virtual desktop. In particular, the Alt, Ctrl and Windows keys are inhibited in the client desktop so that the user has a better immersive experience in the virtual desktop. So combinations like Alt+Tab, Alt+F4, and other shortcuts are passed to the virtual desktop, and do not make the flexVDI Desktop Client lose the focus in the client desktop.

However, some key combinations cannot be captured. They are not sent to the virtual desktop and take effect in the client computer. These special key combinations are different in each platform. For instance, Ctrl+Alt+Supr cannot be captured in all platforms, Ctrl+Alt+F1 to F12 cannot be captured in Linux and Ctrl+L cannot be captured in Windows. These key combinations are provided in the "Send key combinations" dropdown so that they can be sent to the virtual desktop without affecting the client desktop.

USB device redirection

The flexVDI Desktop Client is capable of redirecting USB devices from the client computer to the virtual desktop, in those platforms where this feature is supported:

  • Windows: You have to install an additional driver in the local windows machine: UsbDk. You can download the latest version from here. Besides, you need read and write access rights to USB devices, consult your local administrator.
  • Linux: You need read and write permissions on files under /dev/bus/usb. In some distributions, these files are owned by a special group (e.g. plugdev), in others you can do this by adding a udev rule, consult your distribution documentation.
  • Mac OS: USB redirection is not currently supported.

To redirect a USB device, click on the "Share USB devices" dropdown in the toolbar and select the proper device:

The list shows with a checkbox which devices are already redirected, and how many can be redirected at the same time (in the example, there are 4 free slots). The flexVDI Desktop Client makes its best to identify the devices, but when no descriptive name is available, the Vendor ID and Product ID are provided.

The client can be configured to redirect some devices automatically on startup or on plug-in. More on this in the Advanced configuration section, later.

Follow-me Printing

Printers configured in the client's computer can be redirected to the virtual desktop. For this feature to work, the flexVDI Guest Tools must be installed in the virtual desktop. When a printer is redirected, a "proxy" printer is created in the virtual desktop with the same name as the redirected one. Any document sent to the proxy printer will appear in the real printer. The proxy printer uses a default driver with the most common features (color/b&w, duplex printing, paper quality, etc), but any vendor-specific features will not be available. If you need any of these features, you can send your documents to the special printer "flexVDI PDF Printer". These documents will be rendered to a PDF file and opened in your client computer with your default PDF viewer. From there, you can print the document with the vendor-specific driver.

The flexVDI Desktop Client remembers which printers you had redirected when you last closed it. These printers are redirected again when you reconnect to your virtual desktop.

Grabbing and ungrabbing the mouse pointer

Mouse pointer integration is not possible when the Spice guest tools are not installed in the virtual desktop, or the guest agent is not running (during the virtual desktop boot process, for instance). In that case, the mouse pointer must be grabbed by the client in order to control the mouse pointer of the virtual desktop. You can do this by simply clicking on the desktop area. The mouse pointer is then used exclusively by the flexVDI Desktop Client, and it must be ungrabbed in order to use it with other applications. This is done with a special key combination, which is Left Ctrl+F9 by default. More on this in the Advanced configuration section, later.

File drag'n'drop

When connecting to a Linux guest, you can drag files and drop them on the client's window area. As a result, the file is transferred to the Downloads folder of the guest's desktop, and that folder is shown with the default file browser.

When connecting to a Windows guest, the files dropped on the client's window area are copied to the desktop.

Advanced configuration

Besides the basic configuration that can be set in the settings form, the flexVDI Desktop Client admits several other options through a configuration file. This file has the following default path on each platform:

  • Windows: %LOCALAPPDATA%\flexvdi-client\settings.ini
  • Linux: $XDG_CONFIG_HOME/flexvdi-client/settings.ini or $HOME/.config/flexvdi-client/settings.ini if $XDG_CONFIG_HOME is not set
  • Mac OS: $HOME/.config/flexvdi-client/settings.ini

The configuration file follows the classic INI file format. Four sections are accepted: General, Session, Devices and Layout. Any unknown section or option is silently ignored. Keys are case-sensitive, and they can have a string, integer or boolean value. Boolean values can be either "true" or "false", in lower-case; anything else is an error. Finally, some keys accept lists of values. In that case, they are written as a semicolon-separated list of values.

This is an example of a common configuration file. Unless said otherwise, keys not appearing in the file have a default value of "", 0 or false, respectively.

[General]
terminal-id=c8:60:00:6a:a7:75
host=manager.flexvdi.com

[Session]
fullscreen=true

[Devices]
share-printer=Printer1;Printer2;Printer3

The Layout section is a bit special. It is used to remember the size and position of the desktop presentation window, so that it appears in the same way on the next reconnection.

General options

Options in the General section include connection and auto-login options:

  • host: string. Host name or ip address of the flexVDI platform to connect to.
  • port: integer, default value is 443. TCP port of the flexVDI platform.
  • proxy-uri: string. URI of the connection proxy, or empty if no proxy is used.
  • username: string. Name of the user that is used to log in to the flexVDI platform. The flexVDI Desktop Client remembers the last user name used.
  • password: string. Password used to log in. If both the user name and password are provided, the client will automatically try to log in.
  • desktop: string. Desktop name to connect to. If all of username, password and desktop are provided, the client will automatically try to log in and connect to the desktop.
  • terminal-id: string. Identifier of this client as a flexVDI terminal. If this ID is not given, the flexVDI Desktop Client calculates it automatically after the MAC address of the computer and saves it in the configuration file.
  • log-level: string, default value is "3". See next section for a description of how logging works.

Logging

The flexVDI Desktop Client writes all log messages to a file in the following path:

  • Windows: %LOCALAPPDATA%\flexvdi-client\flexvdi-client.log
  • Linux: $XDG_DATA_HOME/flexvdi-client/flexvdi-client.log, or $HOME/.local/share/flexvdi-client/flexvdi-client.log if $XDG_HOME is not set.
  • Mac OS: $HOME/.local/share/flexvdi-client/flexvdi-client.log

Logging can be configured with the log-level option, in the General section. The log level is configured with a comma-separated list of "domain:level" values, where "domain" is a logging domain and "level" is an integer number from 0 (log just errors) to 5 (log everything). Most common domains are "flexvdi", "GSpice", "GTK" and "GLib". If domain is not provided, the level is applied to any domain not configured otherwise. The default value is "3", so messages in any domain are logged up to level 3 (warnings and errors). These are some examples of log level configuration:

# Log all debug messages in any domain
log-level=5

# Log debug messages in domain "flexvdi", normal messages in any other
log-level=flexvdi:5,3

# Log debug messages in domain "GSpice", info messages in "flexvdi" and warnings in any other
log-level=GSpice:5,flexvdi:4,2

If you ever need to send the flexVDI Client log files to the support team, always use the following logging configuration:

log-level=flexvdi:5,GSpice:5,3

Session options

Session options are those that apply to a certain desktop connection:

  • fullscreen: boolean. Start the desktop connection in fullscreen mode.
  • inactivity-timeout: integer. Close the client application after this number of seconds of inactivity. By default (0), no timeout is set.
  • flexvdi-disable-printing: boolean. Disable the Follow-me Printing feature.
  • auto-clipboard: boolean, default value is true. Automatically share the clipboard between the client and guest desktops.
  • auto-usbredir: boolean. Automatically redirect USB devices as they are connected to the client computer.
  • grab-mouse: boolean, default value is true. Grab the mouse pointer in server mode (when no Spice Guest Agent is running in the virtual desktop).
  • grab-sequence: string, default value is "Shift_L+F12". Key sequence to ungrab the mouse pointer when it is grabbed.
  • resize-guest: boolean, default value is true. Resize the virtual desktop resolution to match the client's window size.
  • disable-power-actions: boolean. Disable the reset, orderly shutdown and immediate poweroff actions.
  • disable-usbredir: boolean. Disable the USB redirection feature.
  • preferred-compression: string. Preferred compression algorithm for images. Possible values are auto-glz, auto-lz, quic, glz, lz, lz4 and off. By default, the compression algorithm is selected by the server.
  • toolbar-edge: string, default value is "top". Screen edge where the toolbar appears in fullscreen mode. Possible values are "top", "bottom", "left" and "right". In Mac OS, the default value is "bottom" because the application menu appears in the top edge.
  • shared-folder: string. Folder in the client's computer that is shared with the Guest, using the WebDAV protocol. See next section to know how to use this feature.
  • shared-folder-ro: boolean. Make the shared folder read-only.

Shared folder

You can share a folder of your computer with the guest using the shared-folder option. For this feature to work, you need to configure the guest in the following way:

  1. Install and start the spice-webdavd service. On Windows, it is included in the flexVDI Guest Tools. On Linux, install the correct package for your distribution. For instance, on Red Hat distributions, install the spice-webdavd package.
  2. Connect with a WebDAV client to http://localhost:9843. On Windows, a network-connected drive will appear automatically when the spice-webdavd service is started. On Linux, most desktop file browsers will open the location webdav://localhost:9843.

Device options

Device options are those that apply to device redirection:

  • usbredir-auto-redirect-filter: string. Filter that selects which USB devices to redirect when they are plugged in the client computer. More on USB redirection filters in the next section.
  • usbredir-on-connect: string. Filter that selects which USB devices to redirect when the client connects to the desktop.
  • flexvdi-serial-port: string list. Serial ports to redirect to the virtual desktop. This feature is only available in Linux. Values are in the form "device,speed,mode", where "device" is the local serial port that is redirected (e.g. /dev/ttyS0), "speed" is the speed in bauds and mode is the parity mode (e.g. 8N1).
  • share-printer: string list. List of printers to redirect when the client connects to the virtual desktop. The flexVDI Desktop Client automatically saves the list of printers from the last session.

USB redirection filters

You can configure which USB devices are redirected automatically when the client connects to the virtual desktop and when a new device is plugged in the client computer. This is done with two sets of filters. Each set is a pipe(|)-separated list of filters in the form "class,vendor,product,version,allow", where "class", "vendor", "product" and "version" are device properties and "allow" can be 1 or 0. Device properties are hexadecimal numbers, with the 0x prefix, and a value of -1 means "any" for all of them. Devices that match those properties are filtered in if "allow" is 1, and filtered out if "allow" is 0.

These are some examples of USB redirection filters:

# filter out HID (class 0x03) USB devices and allow anything else
0x03,-1,-1,-1,0|-1,-1,-1,-1,1

# allow only the device with Vendor ID 0x045e and Product ID 0x028e (a Microsoft XBOX USB controller)
-1,0x045e,0x028e,-1,1|-1,-1,-1,-1,0

Options in the command line

You can provide all the previous options in the command line. Options that appear in the command line take precedence over the ones in the configuration file. All of them are passed as --option-name, followed by an argument in the case of string and integer options. For boolean options, --option-name sets the option to true and --no-option-name sets it to false. Most common options also have a short version, with only one leading dash and one letter. Besides, you can provide the following options only in the command line:

  • --version: Shows a message with the version number and exits.
  • --config-file: string. Alternative path to the configuration file.
  • --help, --help-all, --help-X: Shows a help message about feature X.

You can also connect to any virtual desktop using the Spice protocol if you pass a Spice URI as the last parameter of the command line. A Spice URI has the form spice://host?port=XXX&password=YYYY, where XXX is the port where the Spice server is listening for connections, and YYYY is the Spice password for that virtual desktop.

This is the full help message shown with the --help-all option:

Usage:
  flexvdi-client [OPTION...] [Spice URI]

flexVDI Client is a Virtual Desktop client for flexVDI platforms. It can also be used as a generic Spice client providing a Spice URI on the command line.

Help Options:
  -?, --help                                                         Show help options
  --help-all                                                         Show all help options
  --help-gapplication                                                Show GApplication options
  --help-gtk                                                         Show GTK+ Options
  --help-gst                                                         Show GStreamer Options
  --help-device                                                      Show device options
  --help-session                                                     Show session options

GApplication options
  --gapplication-service                                             Enter GApplication service mode (use from D-Bus service files)

GTK+ Options
  --class=CLASS                                                      Program class as used by the window manager
  --name=NAME                                                        Program name as used by the window manager
  --gdk-debug=FLAGS                                                  GDK debugging flags to set
  --gdk-no-debug=FLAGS                                               GDK debugging flags to unset
  --gtk-module=MODULES                                               Load additional GTK+ modules
  --g-fatal-warnings                                                 Make all warnings fatal
  --gtk-debug=FLAGS                                                  GTK+ debugging flags to set
  --gtk-no-debug=FLAGS                                               GTK+ debugging flags to unset

GStreamer Options
  --gst-version                                                      Print the GStreamer version
  --gst-fatal-warnings                                               Make all warnings fatal
  --gst-debug-help                                                   Print available debug categories and exit
  --gst-debug-level=LEVEL                                            Default debug level from 1 (only error) to 9 (anything) or 0 for no output
  --gst-debug=LIST                                                   Comma-separated list of category_name:level pairs to set specific levels for the individual categories. Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3
  --gst-debug-no-color                                               Disable colored debugging output
  --gst-debug-color-mode                                             Changes coloring mode of the debug log. Possible modes: off, on, disable, auto, unix
  --gst-debug-disable                                                Disable debugging
  --gst-plugin-spew                                                  Enable verbose plugin loading diagnostics
  --gst-plugin-path=PATHS                                            Colon-separated paths containing plugins
  --gst-plugin-load=PLUGINS                                          Comma-separated list of plugins to preload in addition to the list stored in environment variable GST_PLUGIN_PATH
  --gst-disable-segtrap                                              Disable trapping of segmentation faults during plugin loading
  --gst-disable-registry-update                                      Disable updating the registry
  --gst-disable-registry-fork                                        Disable spawning a helper process while scanning the registry

Device options
  --usbredir-auto-redirect-filter=<filter-string>                    Filter selecting USB devices to be auto-redirected when plugged in
  --usbredir-redirect-on-connect=<filter-string>                     Filter selecting USB devices to redirect on connect
  --flexvdi-serial-port=<device,speed,mode>                          Add serial port redirection. Can appear multiple times. Example: /dev/ttyS0,9600,8N1
  -P, --share-printer=<printer_name>                                 Share a client's printer with the virtual desktop. Can appear multiple times

Session options
  -f, --fullscreen                                                   Show desktop in fullscreen mode
  --inactivity-timeout=<seconds>                                     Close the client after a certain time of inactivity
  --flexvdi-disable-printing                                         Disable printing support
  --auto-clipboard                                                   Automatically share clipboard between guest and client
  --auto-usbredir                                                    Automatically redirect newly connected USB devices
  --grab-mouse                                                       Grab mouse in server mode
  --grab-sequence                                                    Key sequence to release mouse grab (default Shift_L+F12)
  --resize-guest                                                     Resize guest display to match window size
  --disable-power-actions                                            Disable reset/poweroff guest actions
  --disable-usbredir                                                 Disable USB device redirection
  --preferred-compression=<auto-glz,auto-lz,quic,glz,lz,lz4,off>     Preferred image compression algorithm
  --shared-folder                                                    Shared directory with the guest
  --shared-folder-ro                                                 Shared directory with the guest is readonly
  --toolbar-edge=<top,bottom,left,right>                             Window edge where toolbar is shown (default top)

Application Options:
  -h, --host=<hostname or IP>                                        Connection host address
  -p, --port=<port number>                                           Connection port (default 443)
  --proxy-uri=<uri>                                                  Use this URI to connect through a proxy server (default use system settings)
  -u, --username=<user name>                                         User name
  -w, --password=<password>                                          Password
  -d, --desktop=<desktop name>                                       Desktop name to connect to
  --terminal-id=<terminal ID>                                        Use a given Terminal ID instead of calculating it automatically
  --kiosk                                                            Enable kiosk mode
  -v, --log-level=<[domain:]level,...>                               Log level for each domain, or for all messages if domain is ommited. 0 = ERROR, 5 = DEBUG
  -V, --version                                                      Show version and exit
  -c, --config-file=<file name>                                      Alternative configuration file name
  --display=DISPLAY                                                  X display to use