• Windows 10 October 2018 Update (1809)
  • Ubuntu 19.04 installed via 'Hyper-V Quick Create'

Starting from version 2.6.0, X410 can be used with Hyper-V Linux virtual machines for opening their GUI desktop via VSOCK (virtual socket).

By using VSOCK, you don't need to worry about configuring firewall or IP address. As X410 seamlessly supports Windowed Apps mode and shared clipboard, you can also use Linux GUI apps side by side with Windows apps instead of confining them to a Hyper-V console. Moreover, your virtual machines will be using less system resources since you don't need to run XRDP or other GUI desktop separately for each Linux virtual machine.

Hyper-V Linux Virtual Machine

STEP 1.1 Create an Ubuntu virtual machine

There are various ways to create a virtual machine in Hyper-V such as using the new feature added in Windows 10 Fall Creators Update (Windows 10 version 1709); 'Hyper-V Quick Create'.

You should be able to use any recent Linux distribution as long as it's supported in Hyper-V. However, we'll be using Ubuntu in this example. After creating your Ubuntu virtual machine, check its installed Linux modules and make sure 'hv_sock' is installed. For checking the installed modules, you can use 'lsmod' command.

If you cannot find 'hv_sock', you should be able to install it by using the following commands.

sudo sh -c 'echo "hv_sock" > /etc/modules-load.d/hv_sock.conf'
sudo reboot



Please also check the version of your Linux and make sure its version is 4.14 or higher. Hyper-V is supported since Linux 4.14.

STEP 1.2 Disable Ubuntu GUI Desktop

We'll be using X410 instead of Hyper-V console for Ubuntu GUI desktop. The following commands will turn off the XRDP graphical login and enable a text only mode for the console.

sudo apt purge xrdp
sudo systemctl set-default multi-user.target
sudo reboot







It's difficult to work with files in text mode over Hyper-V console. Instead of using the console, you should install an OpenSSH server and change the settings and files via an SSH client. Windows 10 has a built-in SSH client that can readily be used from PowerShell or Windows Command Prompt.

sudo apt install openssh-server



For finding out the IP address assigned to your Ubuntu virtual machine, you can use 'ip' command with 'address' as its argument.

If you want to re-enable the graphic mode, you can use the following commands. If you also want to bring back the XRDP graphical login for the 'Enhanced Session' feature in Hyper-V, you need to re-install 'xrdp'.

sudo apt install xrdp
sudo systemctl set-default graphical.target
sudo reboot








Windows 10

STEP 2.1 Add Windows registry entries

X410 runs in a secure sandbox and it cannot directly modify Windows registry. Hence you need to manually make the changes in Windows registry as described below.

In order to have X410 communicate with Hyper-V virtual machines via VSOCK, you first need to add a Windows registry key under 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\GuestCommunicationServices'. The new registry key must be in the following format:

<portnumber>-facb-11e6-bd58-64006a7986d3



<portnumber> is derived from the display number set for X410. If it's set to be '0', <portnumber> must be '6000 + 0 (= display number)' in 4-byte hexadecimal format; 00001770. Hence the new registry key becomes '00001770-facb-11e6-bd58-64006a7986d3'. For the display number 1, it becomes '00001771-facb-11e6-bd58-64006a7986d3' and so forth.

Under the new registry key, you also need to add the following string value for a friendly name that describes what the key is used for:

"ElementName"="X410 Display 0"







Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\GuestCommunicationServices\00001770-facb-11e6-bd58-64006a7986d3]
"ElementName"="X410 Display 0"




You can also download one of the following registry files for adding the entries mentioned above. You can import it from 'Registry Editor (regedit.exe)' in Windows.

Test Driving

▬  Windows 10

STEP 3.1 Start X410 with Hyper-V option

x410 /listen hyperv /desktop



When the Hyper-V option is properly enabled, X410 adds a '+hyperv' text label to its window title.

▬  Ubuntu Virtual Machine

STEP 3.2 Install 'socat'

Although X410 can be directly connected via VSOCK from Hyper-V Linux virtual machines, X-Window apps and tools are not built for VSOCK; we need an intermediate data relay server that can be seen as an X-Window server for those programs.

In this example, we're using a popular utility program called 'socat'.

sudo apt update
sudo apt install socat



You can then execute the following command to create a virtual X-Window server that forwards data to and from X410.

socat -b65536 UNIX-LISTEN:/tmp/.X11-unix/X0,fork,mode=777 SOCKET-CONNECT:40:0:x0000x70170000x02000000x00000000 &



Please note that the above command creates a server at display number '0'. So you should set the DISPLAY environment variable as the following in order to have X-Window apps use this server:

export DISPLAY=:0.0



If you've launched X410 for a different display number, you need to adjust the 'socat' command shown above accordingly. For example, if X410 is set for display number '1', you just need to change 'x70170000' to 'x71170000'. This value is derived from '6000 (base port number) + 1 (= display number)'; hexadecimal format (0x00001771) in little-endian byte order.

'socat' is used in this example in order to simply demonstrate the possibility of using VSOCK; it's definitely not used for its performance. We'll update this article soon with better tools for setting up a virtual X-Window server.

STEP 3.3 Create a script for starting Ubuntu desktop

For a quick test, try launching 'xclock':

xclock



If 'socat' is working properly, you should see xclock running in X410. Once confirmed, you can terminate xclock by pressing CTRL+C from your text console.

Now, let's create a script file that starts Ubuntu desktop.

sudo vi /usr/bin/start-ubuntu-desktop.sh



In the script file, enter the following lines:

#!/bin/bash

export XDG_SESSION_TYPE=x11
export XDG_CURRENT_DESKTOP="ubuntu:GNOME"
export GNOME_SHELL_SESSION_MODE=ubuntu

exec gnome-session --session=ubuntu




Once you finish entering the above lines, save and close the file. Since you want to run the script file, don't forget to add an 'execute' permission to the file:

sudo chmod +x /usr/bin/start-ubuntu-desktop.sh





STEP 3.4 Execute the script create in Step 3.3

start-ubuntu-desktop.sh


Please be patient! It may take 30+ seconds depending on your computer hardware before you see Ubuntu desktop on X410.

Directly Booting Ubuntu Desktop onto X410

You can automatically open Ubuntu desktop on X410 when you simply start your Ubuntu virtual machine. You can do this by creating startup services as described below.

STEP 4.1 Create a service unit for relaying X-Window data via VSOCK

The method shown in Step 3.2 can be created into a service unit and have it automatically loaded when Ubuntu boots up.

sudo vi /etc/systemd/system/x410vsock.service


[Unit]
Description=X410 VSOCK Service
After=network.target

[Service]
User=root
Restart=always
Type=simple
ExecStart=/usr/bin/socat -b65536 UNIX-LISTEN:/tmp/.X11-unix/X0,fork,mode=777 SOCKET-CONNECT:40:0:x0000x70170000x02000000x00000000

[Install]
WantedBy=multi-user.target




STEP 4.2 Create a service unit for automatically launching Ubuntu desktop

We're using /sbin/agetty in this service unit for automatically logging into a virtual terminal. During its login process, a startup shell script also then automatically launches an Ubuntu GUI desktop that makes use of the X-Window data relay server created in Step 4.1. An example of such startup script is shown in the next Step 4.3.

sudo vi /etc/systemd/system/x410tty.service


[Unit]
Description=X410 Autologin Service
After=network.target x410vsock.service

[Service]
User=root
Restart=always
Type=simple
ExecStart=-/sbin/agetty --autologin your_login_account --noclear tty2 $TERM

[Install]
WantedBy=multi-user.target



Please make sure to change the 'ExecStart=-/sbin/agetty --autologin your_login_account --noclear tty2 $TERM' line with your user account; replace the 'your_login_account' with your user ID.

STEP 4.3 Update or create '~/.profile'

If you're using Bash as your login shell, add the following lines to '~/.profile'. '~/.profile' is a file that is automatically executed when you log in.

if [[ ! $DISPLAY && -S "/tmp/.X11-unix/X0" ]]; then
    export DISPLAY=:0.0
    if [[ $XDG_VTNR -eq 2 ]]; then
        exec /usr/bin/start-ubuntu-desktop.sh
    fi
fi




The service file created in Step 4.1 acquires a virtual terminal as tty2. Hence $XDG_VTNR -eq 2 checks the value '2'. If you're using tty3, it should be $XDG_VTNR -eq 3 and so forth.

Please also note that the commands shown above automatically set the DISPLAY environment variable if a Unix domain socket is available for X-Window apps. Hence, if you're connecting locally to this Ubuntu virtual machine via an SSH client, you don't need to activate the SSH X11 forwarding; X-Window apps will be automatically displayed on X410.

STEP 4.4 Automatically start the service script created in Step 4.1 and 4.2 on boot

You can start or stop the newly created services in Step 4.1 and 4.2 by using the following command.

sudo service x410vsock start|stop|restart
sudo service x410tty start|stop|restart




But in order to have the new services automatically started when Ubuntu is booting up, you need to use the following commands:

sudo systemctl enable x410vsock.service
sudo systemctl enable x410tty.service




Now try rebooting your Ubuntu virtual machine while X410 is launched with '/listen hyperv' command-line argument. Ubuntu desktop should be automatically shown on X410 within a minute (it takes a bit longer than you would expect).

sudo reboot









Launching X410 and Ubuntu VM from a Batch File

STEP 5.1 Add yourself to Hyper-V Administrators group

The simplest way we recommend for starting your virtual machine from a batch file is using Windows built-in 'hvc.exe' command. However, 'hvc.exe' requires 'administrator' privileges; you cannot use it from a normal batch file. To workaround this problem, you can add your account to 'Hyper-V Administrators' group in Windows; [ Windows Start (right-click) ] » [ Computer Management ] » [ Local Users and Groups ] » [ Groups ] » [ Hyper-V Administrators ]. After adding your account, you need to reboot Windows for the changes to take effect.

If you don't want to make changes to the 'Hyper-V Administrators' group, you need to create a shortcut for your batch file and enable its 'Run as administrator' option.

STEP 5.2 Create a Windows batch file

start-ubuntu-vm.bat
start x410.exe /desktop /listen hyperv
hvc.exe start "Ubuntu 19.04"



You can now directly start your Hyper-V Ubuntu virtual machine and open its GUI desktop on X410 simply by double-clicking the newly created batch file!

Tips and Tricks

  • Running X410 in Windowed Apps mode

    Instead of running a full Ubuntu desktop, you can run Linux GUI apps individually and use them side by side with Windows apps. You can accomplish this by first starting X410 in 'Windowed Apps' mode:

    start x410.exe /wm /listen hyperv
    
    
    

    You also need to change the script created in Step 3.3; you should add a command for starting a GUI terminal. Any Linux GUI app that is executed from this terminal will be opened as a separate floating window that can be placed among Windows apps.

    start-ubuntu-desktop.sh
    #!/bin/bash
    
    export XDG_SESSION_TYPE=x11
    export XDG_CURRENT_DESKTOP="ubuntu:GNOME"
    export GNOME_SHELL_SESSION_MODE=ubuntu
    
    gnome-session --session=ubuntu & 
    gnome-terminal & /usr/lib/gnome-terminal/gnome-terminal-server
    
    
    

    When adding a terminal or any GUI app, make sure the main script keeps running while your added programs are active. The service unit created in Step 4.2 gets automatically restarted when its target (i.e., a virtual terminal acquired via /sbin/agetty) is terminated. So, for the above script, we added a workaround for preventing its immediate exit; 'gnome-terminal' returns even when it's still active, but 'gnome-terminal-server' remains running if there is any instance of 'gnome-terminal'.

    If you don't want to use a workaround, you can use a straightforward GUI terminal such as Xterm. You can also try adapting the Xfce launcher method as shown in 'Get your sidekick for easily managing and launching Linux GUI apps (WSL)'.

  • Xfce

    Running Ubuntu desktop in X410 via VSOCK should give you better rendering performance than the default Hyper-V console. However, if you want faster and snappier user experience, try using Xfce desktop.

  • Running Ubuntu desktop in WSL1

    The script created in Step 3.3 (/usr/bin/start-ubuntu-desktop.sh) can also be used for Ubuntu/WSL1 and start the same Ubuntu desktop on X410 without any change after installing 'ubuntu-desktop' package; sudo apt install ubuntu-desktop. Before executing the script, you just need to make sure dbus service is running; sudo service dbus restart, and the DISPLAY environment variable is pointing to '127.0.0.1:0.0' instead of ':0.0'; export DISPLAY=127.0.0.1:0.0.

    However, it seems Ubuntu desktop uses various services and components that are not fully compatible with WSL1. Hence, unfortunately, Ubuntu desktop in WSL1 is not as stable as in Hyper-V.

  • X410 with WSL2

    WSL2 is based on virtualization technology similar to Hyper-V. So it should provide much better performance and stability for Linux GUI apps including Ubuntu desktop. However, currently available versions (Windows 10 build 18917 and others) don't seem to support VSOCK or shared loopback network that can be utilized to internally and efficiently communicate with X410 (Using X410 with WSL2).

    We should wait a bit longer for it to mature and properly support the same handy features that are already available in WSL1. Moreover, we hope the interop features for Unix domain sockets are improved soon and allow Windows apps such as X410 to communicate directly with Linux apps just by creating a symbolic link in WSL to a Unix domain socket created in Windows. It's already partially supported but it cannot be used with X-Window apps as they call 'setsockopt' function to adjust the size of their buffers before making connections; such behavior breaks the interop requirements. However, this usage pattern is common (i.e., create a socket » adjust its buffer size with setsockopt » connect/bind) for many Linux apps and if it's supported, servers running in Windows should be able to directly service the apps running in WSL without making any modification to those apps.