[How to] access VB NAT VM using Guacamole with 2FA

This is the best place for community developers to publish their genius work. Your Apps enrich the QNAP Turbo NAS.
Post Reply
User avatar
Experience counts
Posts: 1146
Joined: Tue May 19, 2009 2:08 am
Location: Norway, Oslo

[How to] access VB NAT VM using Guacamole with 2FA

Post by oyvindo » Tue Sep 12, 2017 3:08 am

How to remote access Oracle VB virtual machines in NAT mode using Apache Guacamole with Duo Security 2-Factor Authentication.

In this How-To-Guide, I use a QNAP HS-251 NAS to run the Guacamole server.
There are many ways to deploy and run a Guacamole server on various host machines, including running it in Docker environment which will be my next project.
But for now, I’m using the QPKG package provided by QNAP_Stephane which can be found here:
http://www.qoolbox.fr/Guacamole_0.9.13. ... 4.qpkg.zip
(It can also be found in the French QNAP_Club App repository)
The QNAP Forum has a thread where Stephane maintains versions and provide user support:
Installing Guacamole on a QNAP NAS using Stephane’s QPKG is easy enough. Currently version has fixed a few minor but critical bugs which prevented me from succeeding in my first attempts, but now it works ok.
Once it has been installed, Guacamole can be accessed from any browser on your LAN using this URL:
(This a case sensitive URL)
But in order to put Guacamole to work, it has to be configured properly first. There is no user-friendly GUI where you can do all the necessary configuration. You have to do this from the command line with scripted XML files.
I use a windows tool called WinSCP for this purpose, but you can of course use Putty and the VI editor…..
The first obstacle is to locate where inside QTS these config files are stored. Luckily, all QPKG’s installed in QTS are found in the same place (as far as I know):
(Keep in mind that the folder ‘.qpkg’ (including the dot) is a hidden folder).
Inside this folder, you will find three important files:

Code: Select all


(Note the inconsistency in case! This is important!)
The first file; guacamole.properties becomes important later, when we shall set up and configure 2-factor authentication. But for now, you can leave this as-is.
The second file; Guacamole.sh is the bash file used to start and stop the Guacamole server. There were a few syntax errors in this bash script initially which prevented the server from stopping and starting properly. This may have been corrected now (I’m not sure), but in any case – Here is the correct bash script:

Code: Select all

QPKG_ROOT=`/sbin/getcfg $QPKG_NAME Install_Path -f ${CONF}`
APACHE_ROOT=/share/`/sbin/getcfg SHARE_DEF defWeb -d Qweb -f /etc/config/def_share.info`

export QPKG_NAME
export QPKG_ROOT
export PATH=$QPKG_ROOT/bin:$PATH
export SHELL=/bin/sh
export LC_ALL=en_US.UTF-8
export USER=admin
export LANG=en_US.UTF-8
export LC_CTYPE=en_US.UTF-8
export JAVA_HOME=/opt/QJK8

export PS=$QPKG_ROOT/bin/ps
export KILL=$QPKG_ROOT/bin/kill

_findpid() {
   $PS -eo 'pid,cmd'| grep 'bootstrap.jar' | grep -v grep | awk '{ print $1 }'

export PID=`_findpid`

case "$1" in
    ENABLED=$(/sbin/getcfg $QPKG_NAME Enable -u -d FALSE -f $CONF)
    if [ "$ENABLED" != "TRUE" ]; then
        echo "$QPKG_NAME is disabled."
        exit 1

ln -sf $QPKG_ROOT /opt/$QPKG_NAME

cd $QPKG_ROOT/bin
./startup.sh &
sleep 5
./guacd &



killall -9 guacd
sleep 5
cd $QPKG_ROOT/bin
./shutdown.sh &
sleep 5

   if [[ -n "$PID" ]]; then
     echo "$DESC (pid $PID)"
     $KILL -9 $PID
           echo "$DESC is stopped."

rm -rf /opt/$QPKG_NAME


    $0 stop
    $0 start

    echo "Usage: $0 {start|stop|restart}"
    exit 1

exit 0

The third file; user.mapping.xml contains the setup XML script required for Guacamole to know everything needed to provide a working logon, both to the Guacamole server itself, as well as onwards logon to your RDP servers.
This is described in the Guacamole User Manual which you can find here:


The setup configuration is described in chapter 5.
But – as always, these explanations are not perfect and not always easy to follow. Here is a script that works for me which allows you to log on to a windows RDP server (if you first follow the remaining steps in this guide):

Code: Select all


   <connection name="connection_name">
           <param name="hostname">remote_host_IP</param>
      <param name="username">remote_host_username</param>
      <param name="password">password</param>
      <param name="ignore-cert">true</param>
      <param name="security">nla</param>
      <param name="enable-wallpaper">true</param>
      <param name="enable-theming">true</param>
      <param name="enable-font-smoothing">true</param>
      <param name="enable-full-window-drag">true</param>
      <param name="enable-desktop-composition">true</param>
      <param name="enable-menu-animations">true</param>
      <param name="server-layout">failsafe</param>


The username guacamole_username can be anything you like, followed by a useful password. Same also with the connection name connection_name. But I would avoid using space or any other non-US characters.

The host name remote_host_IP is the IP-Address of the machine that you wish to connect to remotely. I could never figure out how to use the real alphanumeric machine name here, instead of the IP-address, so just type in the IP-address i.e. or whatever the IP address of your remote machine may be. Remember that this should be LAN NAT IP-address and not the one given to you by your ISP.
Then you need to type in the username (or a username) remote_host_username which exist on the remote machine and can be used for logon. Most people only have one user account registered on their machines and that is the admin user (but perhaps with a different name). According to the Guacamole documentation, it should be possible to omit username and password to the host, which should initiate a GUI session for manual logon, but I have never been able to get that to work. Also, I have found that using an account without a password (blank password) also does not work. Last but not least, if you have foreign characters in your account name (or password), you’re in bad luck. Guacamole does not understand that.
You should be able to use your Microsoft Account (MSA), but I have not tested what happens if your host machine is set up with key code, fingerprint recognition or any other ‘Hello’ sign-in method.
My advice; use your main administrator account or set up a new local user account. Using more than one RDP session with Windows 10 doesn’t work anyway. That only works with the Enterprise version of Windows.

Now is the time to configure your Remote Host machine. I assume you are using Windows 10 Pro. The Home version does not support RDP.

Log into your Windows 10 host machine and open a file explorer window. Right-Click on ‘This PC’ and select ‘Properties’.
Then click on ‘Remote Properties’ and in the new window (on the Remote Tab), deselect ‘Remote Assistance’ and select ‘Remote Desktop’ = ‘Allow Remote Connections to this computer’. Also, you should select the ‘Network Level Authentication’ (LNA) checkbox.
Click OK and your computer is now magically running a as an RDP server.

So, let’s go back to the Guacamole user.mapping.xml file again. Here you must add the following parameters:

<param name="ignore-cert">true</param>
<param name="security">nla</param>

The first one is to ignore any certificates that may be passed between the server and the client. Most of them are just self-signed anyway. The second is to comply with the Network Level Authentication (nla) protocol you just activated on the host machine.

That’s it.
If you have done everything exactly and correctly, with upper/lower case, correct IP addresses etc. you should now be able to run.
It’s a good idea to reboot everything before your first try. Also, I have found that if you have made a number of unsuccessful attempts to log on to Guacamole using either Chrome, FireFox or IE, you should flush the browser cache before you try again (it took me a whole day to solve that problem).

To test your connections. First use another Windows 10 Pro PC on the same LAN and run the Microsoft RDP client. Hit the Win key and type ‘Remote desktop Connection’ to find the client and run it. In the logon window, just type the IP address of your ready made RDP host machine. Everything defaults to use port 3389 whih is the default RDP port.
The MS Windows RDP client/server is very robust, and should connect easily. Even if your host is set up with username/password, it will connect using Singel-Sign-On (SSO) if possible. As long as you are on the same closed LAN, the protocol will ignore the logon process if you are and administrator, and log you on anyway. If it needs you credentials to log on, it will ask you for it.
Regretfully, Guacamole is not quite that robust. If you make just the smallest mistake, it refuses to connect. Then, all you get is this:

(Or something similar)

But if you can get the Microsoft RDP client to work, then you’ve come a long way. At least, then you know that things do work.

Why am I not mentioning VNC at all?
I used VNC initially, and it’s actually easier to get VNC to work. But since RealVNC changed their policy, moved to the cloud and now demand payment unless you play it exactly their way. I thought it would make more sense to use RDP since it is included free in every Windows Pro installation after all. And one more thing: RDP is way faster than VNC. This is because RDP use screen draw commands to render the desktop while VNC effectively just plays a bitmap movie.

So, in order to get Guacamole to dance – walk over to a different computer connected to the same LAN and launch your favorite browser. It can be any kind of computer; Windows 7, Macintosh, Chromebook, iPad, Android – you name it. As long as it has a reasonable up-to-date OS and browser, it will work. You could even use your iPhone or your Android phone (but the tiny screens aren’t very useful).
Then go to:


And the Guacamole logon screen should come up in your browser:

Type in whatever username and password you defined in the user.mapping.xml file stored in the Guacamole folder on your QNAP.
If you type something wrong in the above box, or in the setting file, then the box will shake it’s head.

If everything goes well, you should be taken in to the Guacamole host connection list where you can choose among all the different connections you have defined in the Guacamole setting file.
Note that in order to connect, you must actually click on the host name itself. It doesn’t work if you just click on the red focus bar.

If you managed to connect successfully, you can tap yourself on the back and go get a cup of coffee.
To terminate the connection, you could of course just close the browser window, but that would log you out from Guacamole as well. A hidden secret key-combination is provided for that purpose: just type Ctrl-Alt-LeftShift and viola, the Guacamole menu will unfold from the left edge of your browser.


Unless you have successfully made to this point, there’s no point in reading on. You must be able to verify and log on locally from the LAN using simple authentication before you move on to establish two-factor authentication.
Before you expose your network to the world, making Guacamole accessible from the internet, you should definitely establish 2-factor authentication. My advice: NEVER open your router and expose apps with simple text based logon credentials. You will be hit by hackers sooner rather than later.
So, even a full 2FA can be configured, set up and tested in your LAN before you finally open up your router to the world.
The only 2FA supported by Guacamole, is the Duo Security 2FA. You will find this on the internet here:
It is a highly dependable, robust, flexible and secure service, and they do offer free versions for private users at home. The first thing to do, is to register and set up a Free account with Duo. If you are a business user, you should go for the Duo Access plan, which is low cost, but also has a 30 day free trial period. So, no money up front. Their support service is excellent, by the way.
However, setting up 2FA for Guacamole is rather painful for beginners. But pay close attention and you will make it. It consists of two main steps:

1. Configure the application (Guacamole) in Duo
2. Configure Guacamole on your QNAP to use the duo 2FA service

So, first things first. Once you have successfully been able to establish an account with Duo, you should also have finished downloading the security App to your cell phone (iPhone or Android). It is possible to use the Duo service without a cell phone app, but I strongly discourage that. Since logging into your Duo account on the net also requires 2-fctor authentication, everything is much smoother with a phone app. So do as you’ve been told!
Once successfully logged in to your Duo dashboard, select ‘Add New Application’ from the menu. This will bring you to a long list of preconfigured applications. Regretfully, you will not find Guacamole among them. The one you should choose is called ‘Web SDK’. Click on it, and you’ll get to this page:

The Integration key and the API hostname is the same for all, but the secret key is very secret and just for you. When you click on page above where it says ‘Click to view’, you’ll get a long alphanumerical key that you need to copy and paste into the guacamole.properties file on your NAS, along with all the other keys listed above, plus a little bit more. Here’s how:
Use WinSCP (or any other favorite editor) and open the guacamole.properties file from the Guacamole folder on your QNAP NAS.
Paste the following at the end of the file:

Code: Select all

duo-api-hostname: api-29c98887.duosecurity.com
duo-integration-key: DITRBU0XBGMYS7Y0CEX5
duo-secret-key: XXXXXXXX
duo-application-key: XXXXXXX

Replace all the X’s in the duo-secret-key with the secret key you were given. I advise you strongly to use cut’n’paste here. If you make just a single typo here, nothing will work. Make sure you don’t get any leading or trailing spaces.
The duo-application-key is something you make up yourself. It can be anything as long as it is minmum 40 characters long. Just type something gibberish, but avoid special characters, spaces, underlines, hyphens and stuff like that. Use normal uppercase/lowercase US-ASCII characters and some numbers here and there.
Sav the file back to the Guacamole folder.
Not ready yet!
Now you must make a new folder inside the Guacamole folder, named ‘extensions’. The full path should be:
In this folder, you must store a javascript file named:
You must download this file from the Apache Guacamole Web here:
http://apache.org/dyn/closer.cgi?action ... ing.tar.gz
This is a zipped file that you need to unzip using winrar or some other unzipper capable of reading tar balls. Inside it, you will find the java file we are looking for. Copy it to the ‘extension’ folder on your NAS.
That’s’ it!
Now, stop Guacamole, and restart it and you should be good to go. Sometimes, I have experienced that the Guacamole bash script fails to completely stop the Guacamole server, so a NAS reboot may be needed the first time.
ON your first attempt to log in using 2FA, there’s a bit of housekeeping and configurations that needs to be done. But it’s very straight forward. If your Guacamole Server fails to properly contact and interact with the Duo server, it will simply shake it’s head.
Then you have to go back and check everything again.
If you have trouble, take a look in the Guacamole log files. You’ll find them here:
The one file you should look for is named catalina.out
It’s a good idea to empty this file before you start logging again.
You may also need to increase the level of logging in order to iron out more details. You can do that by following the description ‘Logging within the web application’ under chapter 5 in the Guacamole Documentation.
But if you made it so far – successfully performing a 2-Factor Authentication logon to Guacamole, then it’s time to open the door to internet.
You do that by configuring a port forward in your internet firewall on your router. Since I have noidea what type of router you have, I cannot tell you how to do that. But in general, you need to open up port 8890 to TCP traffic so that Guacamole can be reached from the outside using the IP-address assigned to you by your ISP. If you have an ISP that frequently changes your external IP from a pool of addresses shared among its customers, then you might be better off using a DNS service to redirect your traffic. It is beyond the scope of this guide to teach how to do that. But in general, you need to know your external IP-address in order to be able to access Guacamole from the internet. If you type http://www.myIp.ms it will tell you.
Then all you need to do is to run down to nearest internet shop, fire up a PC and type in:
and you should be able to enjoy full remote access to all your computers set up in Guacamole to allow such access, and you will be thoroughly protecting your LAN and your NAS through the Dua 2FA.
One final notice: Make sure you turn off uPnP in your internet router. It’s a dangerous setting.


It is not the intention of this guide to tell you how to set up and run a virtual version of Windows 10Pro inside Oracle Virtual Box. All I can say is that this technique requires some CPU horsepower (at least an i5) and a lot or RAM (at least 8Gb preferably 16Gb). But the added benefit of running an extra copy of windows inside Virtual box, is fantastic – if you need to experiment with ill-behaved SW or during SW development. Next to Docker, VirtualBox is a wonderful tool – and it’s free!
There are many ways to install Windows in VB and many ways to configure it. The easiest and least secure is to use bridge mode networking. If you do that, then there is no reason to read on. Just do exactly with your virtual Windows as you did with your RDP host server. The procedure is identical.
But, if you are serious about virtualization, then you isolate your VB completely, using Network Address Translation (NAT). The advantages are plentiful. The disadvantage is that it suddenly becomes somewhat tweaky to get access in and out of the box. But, then again – that’s often the whole point of virtualization. Still – being able to pass data in and out, and even do remote control of Virtual boxes, can be very handy. And it is possible – but somewhat difficult to achieve.
First of all, in order to establish an easy way to access the host disk from inside the box in a safe way, install the Oracle Virtual Box GuestApplications. That’s all I’m going to say about that. The rest is easy.
Now, since the VM is running in NAT mode, it is no longer possible to access it using the normal RDP server setup. But if you look inside VB ‘settings’ under ‘display’ you’ll find a setting the named ‘Remote Display’. In this tab you can activate the server, but regretfully it will just give a warning. In order to make it work, you have to install the Virtual Box Extension Pack. Make sure you pick the one that matches the version of your VB. You’ll find all these addon’s on the Oracle home Web Server.
The documentation here is regretfully not the best. Again, you should first attempt to make connection using Microsoft’s RDP Client before you attempt to try with Guacamole. For some reason the default Windows RDP port 3389 cannot be used. So, you have to use a different one. In my setup I used port 5001. You can use any port you want as long as it is free.
Remember to set this port number also in the VB setting under Display Remote Display, Server Port.
Then from the RDP client, you should use this connection string:
Make sure your VB is running.
You can do all of this on one and the same computer.
If you can successfully connect to the VB, then it’s time to move on to Guacamole.
The connection setting in the user.mapping.xml file, need to be:

Code: Select all

<connection name="RDP VB">
   <param name="hostname">IP_of_the PC_where_the_VB_is_running</param>
   <param name="port">5001</param>
   <param name="security">any</param>
   <param name="ignore-cert">true</param>
   <param name="username">username_to_log_in_to_the_Windows_VM</param>
   <param name="password">password</param>

For some reason localhost does not seem to work with Guacamole. It has to be a real LAN IP. Secondly, I have not been able to make this work with an account without a password.
Since you have installed the Oracle GuestAddition, enjoy experimenting with scaled windows, seamless windows etc, and see how Guacamole handles that. Ones you get the hang of it, its joyful to see how flexible this remote combo solution (VB RDP + Guacamole) handles dynamic windows scaling and resolution.
Have fun and let me know if your find any errors in this guide or if you find solutions to things I haven’t found.

Post Reply

Return to “Community Apps”