Difference between revisions of "Guacamole"

From Linuxintro
imported>ThorstenStaerk
imported>ThorstenStaerk
(8 intermediate revisions by the same user not shown)
Line 17: Line 17:
 
Here's what you do as root user:
 
Here's what you do as root user:
 
* install software that we will need later:
 
* install software that we will need later:
 +
<source>
 
  apt-get update
 
  apt-get update
 
  apt-get install tomcat6 tightvncserver gcc make xterm
 
  apt-get install tomcat6 tightvncserver gcc make xterm
 +
</source>
  
 
== configure VNC server ==
 
== configure VNC server ==
 
Guacamole does the communication between a VNC server and the web browser. So whatever you see in VNC will be in the browser. In this example let's use xfce as desktop environment:
 
Guacamole does the communication between a VNC server and the web browser. So whatever you see in VNC will be in the browser. In this example let's use xfce as desktop environment:
 
* install xfce:
 
* install xfce:
 +
<source>
 
  apt-get install xfce4
 
  apt-get install xfce4
 +
</source>
 
* activate gnome for your VNC:
 
* activate gnome for your VNC:
 +
<source>
 
  cd
 
  cd
 
  mkdir .vnc
 
  mkdir .vnc
Line 32: Line 37:
 
  EOF
 
  EOF
 
  chmod 777 .vnc/xstartup
 
  chmod 777 .vnc/xstartup
 +
</source>
  
 
== deploy guacamole client ==
 
== deploy guacamole client ==
 
* download the guacamole webapp from http://sourceforge.net/projects/guacamole/files/current/binary/
 
* download the guacamole webapp from http://sourceforge.net/projects/guacamole/files/current/binary/
 
* deploy it
 
* deploy it
 +
<source>
 
  # mv guacamole-0.9.3.war /var/lib/tomcat6/webapps/
 
  # mv guacamole-0.9.3.war /var/lib/tomcat6/webapps/
 +
</source>
 
* surf to http://localhost:8080/guacamole-0.9.3. A folder /var/lib/tomcat6/webapps/guacamole-0.9.3 will be created with some content. We will need that later.
 
* surf to http://localhost:8080/guacamole-0.9.3. A folder /var/lib/tomcat6/webapps/guacamole-0.9.3 will be created with some content. We will need that later.
 
* although login is not yet possible your browser will show a login screen like that:
 
* although login is not yet possible your browser will show a login screen like that:
  
[[File:guacamole-login.png]]
+
<pic src=http://www.linuxintro.org/images/Guacamole-login.png width=50% align=text />
  
 
== install guacamole server ==
 
== install guacamole server ==
 
* install some [[dependencies]] that the server will need to build with vnc support:
 
* install some [[dependencies]] that the server will need to build with vnc support:
 +
<source>
 
  apt-get install libvncserver-dev libpng-dev libcairo-dev
 
  apt-get install libvncserver-dev libpng-dev libcairo-dev
 +
</source>
 
* download guacamole-server from http://sourceforge.net/projects/guacamole/files/current/source/
 
* download guacamole-server from http://sourceforge.net/projects/guacamole/files/current/source/
 
* unpack it, in this example 0.9.3:
 
* unpack it, in this example 0.9.3:
 +
<source>
 
  tar xvzf guacamole-server-0.9.3.tar.gz
 
  tar xvzf guacamole-server-0.9.3.tar.gz
 +
</source>
 
* build the server:
 
* build the server:
 +
<source>
 
  cd guacamole-server-0.9.3
 
  cd guacamole-server-0.9.3
 
  ./configure && make -j8 && make install
 
  ./configure && make -j8 && make install
 +
</source>
 
* the following step is ugly; installation and binary do not completely fit so we must do that:
 
* the following step is ugly; installation and binary do not completely fit so we must do that:
 +
<source>
 
  ln -s /usr/local/lib/libguac.so* /lib
 
  ln -s /usr/local/lib/libguac.so* /lib
 
  ln -s /usr/local/lib/libguac-client-vnc.so* /lib/
 
  ln -s /usr/local/lib/libguac-client-vnc.so* /lib/
 +
</source>
 
* now we start the guacamole daemon:
 
* now we start the guacamole daemon:
 +
<source>
 
  # guacd
 
  # guacd
 
  guacd[17669]: INFO:  Guacamole proxy daemon (guacd) version 0.9.3
 
  guacd[17669]: INFO:  Guacamole proxy daemon (guacd) version 0.9.3
Line 60: Line 77:
 
  guacd[17669]: INFO:  Exiting and passing control to PID 17671
 
  guacd[17669]: INFO:  Exiting and passing control to PID 17671
 
  root@tstaerk-desktop:/var/log# guacd[17671]: INFO:  Exiting and passing control to PID 17672
 
  root@tstaerk-desktop:/var/log# guacd[17671]: INFO:  Exiting and passing control to PID 17672
 +
</source>
  
 
== configure guacamole ==
 
== configure guacamole ==
 
* create a folder for guacamole's configuration:
 
* create a folder for guacamole's configuration:
 +
<source>
 
  mkdir /etc/guacamole
 
  mkdir /etc/guacamole
 +
</source>
 
* create a file /etc/guacamole/guacamole.properties with the content
 
* create a file /etc/guacamole/guacamole.properties with the content
 +
<source>
 
  # Hostname and port of guacamole proxy
 
  # Hostname and port of guacamole proxy
 
  guacd-hostname: localhost
 
  guacd-hostname: localhost
Line 77: Line 98:
 
  # Properties used by BasicFileAuthenticationProvider
 
  # Properties used by BasicFileAuthenticationProvider
 
  basic-user-mapping: /etc/guacamole/user-mapping.xml
 
  basic-user-mapping: /etc/guacamole/user-mapping.xml
 +
</source>
 +
 
* create a file /etc/guacamole/user-mapping.xml with the content
 
* create a file /etc/guacamole/user-mapping.xml with the content
 +
<source>
 
  <user-mapping>
 
  <user-mapping>
 
     <authorize username="user" password="password">
 
     <authorize username="user" password="password">
Line 86: Line 110:
 
     </authorize>
 
     </authorize>
 
  </user-mapping>
 
  </user-mapping>
 +
</source>
  
 
== configure tomcat ==
 
== configure tomcat ==
 
* find out your tomcat's user directory:
 
* find out your tomcat's user directory:
 +
<source>
 
  # cat /etc/passwd|grep tomcat
 
  # cat /etc/passwd|grep tomcat
 
  tomcat6:x:113:116::/usr/share/tomcat6:/bin/false
 
  tomcat6:x:113:116::/usr/share/tomcat6:/bin/false
 +
</source>
 
: in this case it is /usr/share/tomcat6
 
: in this case it is /usr/share/tomcat6
 
* create a folder .guacamole in your tomcat's user directory:
 
* create a folder .guacamole in your tomcat's user directory:
 +
<source>
 
  mkdir /usr/share/tomcat6/.guacamole
 
  mkdir /usr/share/tomcat6/.guacamole
 +
</source>
 
* link guacamole.properties into your tomcat's user directories' guacamole folder
 
* link guacamole.properties into your tomcat's user directories' guacamole folder
 +
<source>
 
  ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat6/.guacamole
 
  ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat6/.guacamole
 +
</source>
  
 
== finishing ==
 
== finishing ==
 
* start a vnc server, as password set password (the vnc password given in user-mappings.xml)
 
* start a vnc server, as password set password (the vnc password given in user-mappings.xml)
 +
<source>
 
  vncserver
 
  vncserver
 +
</source>
 
* restart your tomcat server
 
* restart your tomcat server
 +
<source>
 
  /etc/init.d/tomcat6 restart
 
  /etc/init.d/tomcat6 restart
 +
</source>
 
* point your browser to http://localhost:8080/guacamole-0.9.3
 
* point your browser to http://localhost:8080/guacamole-0.9.3
 
* log in as user, password password (the user given in user-mappings.xml)
 
* log in as user, password password (the user given in user-mappings.xml)
 
* you should see a screen like this:
 
* you should see a screen like this:
  
[[File:Guacamole-after-login.png]]
+
<pic src=http://www.linuxintro.org/images/Guacamole-after-login.png width=30% align=text />
  
 
Now when you click on "Default" you will see your VNC desktop in your browser.
 
Now when you click on "Default" you will see your VNC desktop in your browser.
  
* next steps: [[set up Apache for https]]
+
== secure transmission ==
* next steps: proxypass
+
[[Set up apache for https]] so your passwords are not transmitted unencrypted over the internet
 +
 
 +
== make it work from behind a firewall ==
 +
Most companies will have an internet proxy that does not allow users to access port 8080 on a server outside the company network. So you need a reverse proxy that tells apache if someone calls http://yourserver.yourdomain/guacamole this is forwarded to http://yourserver.yourdomain:8080 internally. To do this,
 +
* edit /etc/sysconfig/apache2 and add the following words to APACHE_MODULES: proxy proxy_http. In the end your line may read like this:
 +
<source>
 +
APACHE_MODULES="actions alias auth_basic proxy proxy_http authn_file authz_host authz_groupfile authz_default authz_user autoindex cgi dir env expires include log_config mime negotiation setenvif ssl userdir php5"
 +
</source>
 +
 
 +
* edit /etc/apache2/default-server.conf, add a block
 +
<source>
 +
<IfModule mod_proxy.c>
 +
<Location /guacamole>
 +
    ProxyPass http://127.0.0.1:8080
 +
</Location>
 +
</IfModule>
 +
</source>
  
 
= Persist it =
 
= Persist it =
Add the following line to /etc/crontab:
+
You want your configuration to survive a reboot so add the following line to /etc/crontab:
 +
<source>
 
  @reboot root /usr/local/sbin/guacd &
 
  @reboot root /usr/local/sbin/guacd &
 +
</source>
  
 
= TroubleShooting =
 
= TroubleShooting =
Line 128: Line 181:
 
* so add it
 
* so add it
 
* cat /etc/passwd gives me a line
 
* cat /etc/passwd gives me a line
 +
<source>
 
  tomcat6:x:113:116::/usr/share/tomcat6:/bin/false
 
  tomcat6:x:113:116::/usr/share/tomcat6:/bin/false
  
Line 135: Line 189:
 
  drwxr-xr-x 6 root root 4096 Nov 26 07:57 ../
 
  drwxr-xr-x 6 root root 4096 Nov 26 07:57 ../
 
  lrwxrwxrwx 1 root root  35 Nov 26 07:58 guacamole.properties -> /etc/guacamole/guacamole.properties
 
  lrwxrwxrwx 1 root root  35 Nov 26 07:58 guacamole.properties -> /etc/guacamole/guacamole.properties
 +
</source>
  
 
* works now. So the thing is:
 
* works now. So the thing is:
 
** take care that it is called guacamole and not guacamole-0.8.3 (sure?)
 
** take care that it is called guacamole and not guacamole-0.8.3 (sure?)
 
** make sure the classpath in /etc/guacamole/guacamole.properties is correct, e.g.  
 
** make sure the classpath in /etc/guacamole/guacamole.properties is correct, e.g.  
 +
<source>
 
  # Location to read extra .jar's from
 
  # Location to read extra .jar's from
 
  lib-directory:  /var/lib/tomcat6/webapps/guacamole/WEB-INF/classes
 
  lib-directory:  /var/lib/tomcat6/webapps/guacamole/WEB-INF/classes
 +
</source>
  
 
== Server error ==
 
== Server error ==
 
* now I got a server error so I straced guacd:
 
* now I got a server error so I straced guacd:
 +
<source>
 
  strace -p 15332
 
  strace -p 15332
 +
</source>
 
and saw
 
and saw
 +
<source>
 
  [pid 20344] open("/usr/lib/x86_64-linux-gnu/libguac-client-vnc.so", O_RDONLY) = -1 ENOENT (No such file or directory)
 
  [pid 20344] open("/usr/lib/x86_64-linux-gnu/libguac-client-vnc.so", O_RDONLY) = -1 ENOENT (No such file or directory)
 +
</source>
 
so the problem is that libguac-client-vnc.so is missing.
 
so the problem is that libguac-client-vnc.so is missing.
 
* downloaded java version 1.7.45 and compiled guacamole-client using mvn. But there was no *.so* file in it
 
* downloaded java version 1.7.45 and compiled guacamole-client using mvn. But there was no *.so* file in it
Line 155: Line 216:
 
== Failed to load ==
 
== Failed to load ==
 
When logging in I got an error message
 
When logging in I got an error message
 +
<source>
 
  Failed to execute 'send' on 'XMLHttpRequest': Failed to load 'http://162.209.103.145:8080/guacamole-0.8.3/login'.
 
  Failed to execute 'send' on 'XMLHttpRequest': Failed to load 'http://162.209.103.145:8080/guacamole-0.8.3/login'.
 +
</source>
 
Solution was to:
 
Solution was to:
 +
<source>
 
  /etc/init.d/tomcat6 restart
 
  /etc/init.d/tomcat6 restart
 +
</source>
  
 
== Error initializing VNC client ==
 
== Error initializing VNC client ==
 
After logging in I got the error message
 
After logging in I got the error message
 +
<source>
 
  Error initializing VNC client
 
  Error initializing VNC client
 +
</source>
 
Solution was to start  
 
Solution was to start  
 +
<source>
 
  vncserver
 
  vncserver
 +
</source>
  
 
== Could not connect ==
 
== Could not connect ==
 
If you surf to the page and get an error message like
 
If you surf to the page and get an error message like
 +
<source>
 
  Unable to connect
 
  Unable to connect
 +
</source>
 
It probably means that tomcat is not running. It must be possible to connect to port 8080, a java process for tomcat must be running.
 
It probably means that tomcat is not running. It must be possible to connect to port 8080, a java process for tomcat must be running.
 +
<source>
 
  /etc/init.d/tomcat6 status
 
  /etc/init.d/tomcat6 status
 +
</source>
 
must deliver something like
 
must deliver something like
 +
<source>
 
  * Tomcat servlet engine is running with pid 17546
 
  * Tomcat servlet engine is running with pid 17546
 +
</source>
  
 
= See also =
 
= See also =

Revision as of 08:17, 13 April 2020


A Linux desktop in a browser

Overview

Guacamole is a program to control a Linux desktop over the network in a browser.

Sometimes in your Linux life, you need to control your servers in the internet with a graphical user interface. This is tedious when you are behind a corporate firewall blocking ssh requests to the public internet. Typical corporate firewalls only allow proxified client access to port 80, 8080 and 443 in the public internet. One way to go is to use a browser to display a Linux desktop. The solution is guacamole.

Quickstart

This will show you

  • how to install guacamole 0.9.3 on Ubuntu (tested with 14.04)
  • how to make this configuration survive a reboot
  • how to secure transmission with SSL
  • how to make the website accessible from behind a firewall (port 80 or 443)

Here's what you do as root user:

  • install software that we will need later:

<source>

apt-get update
apt-get install tomcat6 tightvncserver gcc make xterm

</source>

configure VNC server

Guacamole does the communication between a VNC server and the web browser. So whatever you see in VNC will be in the browser. In this example let's use xfce as desktop environment:

  • install xfce:

<source>

apt-get install xfce4

</source>

  • activate gnome for your VNC:

<source>

cd
mkdir .vnc
cat >> .vnc/xstartup <<EOF
#!/bin/sh
xfce4-session || xterm
EOF
chmod 777 .vnc/xstartup

</source>

deploy guacamole client

<source>

# mv guacamole-0.9.3.war /var/lib/tomcat6/webapps/

</source>

  • surf to http://localhost:8080/guacamole-0.9.3. A folder /var/lib/tomcat6/webapps/guacamole-0.9.3 will be created with some content. We will need that later.
  • although login is not yet possible your browser will show a login screen like that:

install guacamole server

  • install some dependencies that the server will need to build with vnc support:

<source>

apt-get install libvncserver-dev libpng-dev libcairo-dev

</source>

<source>

tar xvzf guacamole-server-0.9.3.tar.gz

</source>

  • build the server:

<source>

cd guacamole-server-0.9.3
./configure && make -j8 && make install

</source>

  • the following step is ugly; installation and binary do not completely fit so we must do that:

<source>

ln -s /usr/local/lib/libguac.so* /lib
ln -s /usr/local/lib/libguac-client-vnc.so* /lib/

</source>

  • now we start the guacamole daemon:

<source>

# guacd
guacd[17669]: INFO:  Guacamole proxy daemon (guacd) version 0.9.3
guacd[17669]: INFO:  Successfully bound socket to host ::1, port 4822
guacd[17669]: INFO:  Exiting and passing control to PID 17671
root@tstaerk-desktop:/var/log# guacd[17671]: INFO:  Exiting and passing control to PID 17672

</source>

configure guacamole

  • create a folder for guacamole's configuration:

<source>

mkdir /etc/guacamole

</source>

  • create a file /etc/guacamole/guacamole.properties with the content

<source>

# Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port:     4822

# Location to read extra .jar's from
lib-directory:  /var/lib/tomcat6/webapps/guacamole-0.9.3/WEB-INF/classes

# Authentication provider class
auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider

# Properties used by BasicFileAuthenticationProvider
basic-user-mapping: /etc/guacamole/user-mapping.xml

</source>

  • create a file /etc/guacamole/user-mapping.xml with the content

<source>

<user-mapping>
   <authorize username="user" password="password">
      <protocol>vnc</protocol>
         <param name="hostname">localhost</param>
         <param name="port">5901</param>
         <param name="password">password</param>
    </authorize>
</user-mapping>

</source>

configure tomcat

  • find out your tomcat's user directory:

<source>

# cat /etc/passwd|grep tomcat
tomcat6:x:113:116::/usr/share/tomcat6:/bin/false

</source>

in this case it is /usr/share/tomcat6
  • create a folder .guacamole in your tomcat's user directory:

<source>

mkdir /usr/share/tomcat6/.guacamole

</source>

  • link guacamole.properties into your tomcat's user directories' guacamole folder

<source>

ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat6/.guacamole

</source>

finishing

  • start a vnc server, as password set password (the vnc password given in user-mappings.xml)

<source>

vncserver

</source>

  • restart your tomcat server

<source>

/etc/init.d/tomcat6 restart

</source>

Now when you click on "Default" you will see your VNC desktop in your browser.

secure transmission

Set up apache for https so your passwords are not transmitted unencrypted over the internet

make it work from behind a firewall

Most companies will have an internet proxy that does not allow users to access port 8080 on a server outside the company network. So you need a reverse proxy that tells apache if someone calls http://yourserver.yourdomain/guacamole this is forwarded to http://yourserver.yourdomain:8080 internally. To do this,

  • edit /etc/sysconfig/apache2 and add the following words to APACHE_MODULES: proxy proxy_http. In the end your line may read like this:

<source>

APACHE_MODULES="actions alias auth_basic proxy proxy_http authn_file authz_host authz_groupfile authz_default authz_user autoindex cgi dir env expires include log_config mime negotiation setenvif ssl userdir php5"

</source>

  • edit /etc/apache2/default-server.conf, add a block

<source>

<IfModule mod_proxy.c>
<Location /guacamole>
    ProxyPass http://127.0.0.1:8080
</Location>
</IfModule>

</source>

Persist it

You want your configuration to survive a reboot so add the following line to /etc/crontab: <source>

@reboot root /usr/local/sbin/guacd &

</source>

TroubleShooting

invalid login

  • now the problem is that tomcat does not know where to find the Authentication class:

/var/lib/tomcat6/webapps/guacamole/WEB-INF/classes/net/sourceforge/guacamole/net/basic/BasicFileAuthenticationProvider.class

is not in /etc/guacamole/guacamole.properties

  • so add it
  • cat /etc/passwd gives me a line

<source>

tomcat6:x:113:116::/usr/share/tomcat6:/bin/false
ll /usr/share/tomcat6/.guacamole/
total 8
drwxr-xr-x 2 root root 4096 Nov 26 07:58 ./
drwxr-xr-x 6 root root 4096 Nov 26 07:57 ../
lrwxrwxrwx 1 root root   35 Nov 26 07:58 guacamole.properties -> /etc/guacamole/guacamole.properties

</source>

  • works now. So the thing is:
    • take care that it is called guacamole and not guacamole-0.8.3 (sure?)
    • make sure the classpath in /etc/guacamole/guacamole.properties is correct, e.g.

<source>

# Location to read extra .jar's from
lib-directory:  /var/lib/tomcat6/webapps/guacamole/WEB-INF/classes

</source>

Server error

  • now I got a server error so I straced guacd:

<source>

strace -p 15332

</source> and saw <source>

[pid 20344] open("/usr/lib/x86_64-linux-gnu/libguac-client-vnc.so", O_RDONLY) = -1 ENOENT (No such file or directory)

</source> so the problem is that libguac-client-vnc.so is missing.

  • downloaded java version 1.7.45 and compiled guacamole-client using mvn. But there was no *.so* file in it
  • so installed libvncserver-dev and rebuild and reinstalled guacamole-server
  • and there it is, libguac-client-vnc.so
  • now the error message changed from "server error" to "unauthorized"

Failed to load

When logging in I got an error message <source>

Failed to execute 'send' on 'XMLHttpRequest': Failed to load 'http://162.209.103.145:8080/guacamole-0.8.3/login'.

</source> Solution was to: <source>

/etc/init.d/tomcat6 restart

</source>

Error initializing VNC client

After logging in I got the error message <source>

Error initializing VNC client

</source> Solution was to start <source>

vncserver

</source>

Could not connect

If you surf to the page and get an error message like <source>

Unable to connect

</source> It probably means that tomcat is not running. It must be possible to connect to port 8080, a java process for tomcat must be running. <source>

/etc/init.d/tomcat6 status

</source> must deliver something like <source>

* Tomcat servlet engine is running with pid 17546

</source>

See also