Apache Guacamole Manual

https://guacamole.apache.org/doc/gug/
Admin
Official documentation for Apache Guacamole, an HTML5 web application providing remote desktop...
Tokens:199,887
Snippets:1,683
Trust Score:10
Update:3 days ago
Show doc for...
Tokens:
Raw
### Build and install the plugin

Source: https://guacamole.apache.org/doc/gug/custom-protocols.html

Commands to compile the plugin using make, install the resulting library, and update the system library cache.

```bash
$ make
  CC       src/ball.lo
  CCLD     libguac-client-ball.la
# make install
make[1]: Entering directory '/home/user/libguac-client-ball'
 /usr/bin/mkdir -p '/usr/local/lib'
 /bin/sh ./libtool   --mode=install /usr/bin/install -c   libguac-client-ball.la '/usr/local/lib'
...
----------------------------------------------------------------------
Libraries have been installed in:
   /usr/local/lib

If you ever happen to want to link against installed libraries
in a given directory, LIBDIR, you must either use libtool, and
specify the full pathname of the library, or use the '-LLIBDIR'
flag during linking and do at least one of the following:
   - add LIBDIR to the 'LD_LIBRARY_PATH' environment variable
     during execution
   - add LIBDIR to the 'LD_RUN_PATH' environment variable
     during linking
   - use the '-Wl,-rpath -Wl,LIBDIR' linker flag
   - have your system administrator add LIBDIR to '/etc/ld.so.conf'

See any operating system documentation about shared libraries for
more information, such as the ld(1) and ld.so(8) manual pages.
----------------------------------------------------------------------
make[1]: Nothing to be done for 'install-data-am'.
make[1]: Leaving directory '/home/user/libguac-client-ball'
# ldconfig
```

--------------------------------

### Example user-mapping.xml configuration

Source: https://guacamole.apache.org/doc/gug/configuring-guacamole.html

A complete example of the user-mapping.xml file structure, demonstrating both simple and MD5-hashed authentication with multiple connection definitions.

```xml
<user-mapping>

    <!-- Per-user authentication and config information -->
    <authorize username="USERNAME" password="PASSWORD">
        <protocol>vnc</protocol>
        <param name="hostname">localhost</param>
        <param name="port">5900</param>
        <param name="password">VNCPASS</param>
    </authorize>

    <!-- Another user, but using md5 to hash the password
         (example below uses the md5 hash of "PASSWORD") -->
    <authorize
            username="USERNAME2"
            password="319f4d26e3c536b5dd871bb2c52e3178"
            encoding="md5">

        <!-- First authorized connection -->
        <connection name="localhost">
            <protocol>vnc</protocol>
            <param name="hostname">localhost</param>
            <param name="port">5901</param>
            <param name="password">VNCPASS</param>
        </connection>

        <!-- Second authorized connection -->
        <connection name="otherhost">
            <protocol>vnc</protocol>
            <param name="hostname">otherhost</param>
            <param name="port">5900</param>
            <param name="password">VNCPASS</param>
        </connection>

    </authorize>

</user-mapping>
```

--------------------------------

### Configure script failure due to missing libguac

Source: https://guacamole.apache.org/doc/gug/custom-protocols.html

Example output when the configure script fails because the required libguac library is not installed.

```bash
$ ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
...
checking for guac_client_stream_png in -lguac... no
configure: error: "libguac is required for communication via "
                   "the Guacamole protocol"
$
```

--------------------------------

### Run encrypt-json.sh with example key and auth.json

Source: https://guacamole.apache.org/doc/gug/json-auth.html

Command to encrypt and sign the example auth.json file using the provided hex encryption key. The output is base64 data that can be submitted to Guacamole for authentication.

```shell
$ ./encrypt-json.sh 4C0B569E4C96DF157EEE1B65DD0E4D41 auth.json

```

--------------------------------

### Initialize database schema natively

Source: https://guacamole.apache.org/doc/gug/mysql-auth.html

Run the schema initialization scripts against a native MySQL or MariaDB installation.

```bash
$ cat schema/*.sql | mysql -u root -p guacamole_db
Enter password:
$
```

--------------------------------

### Example HTML patch file for welcome message

Source: https://guacamole.apache.org/doc/gug/guacamole-ext.html

An example of an HTML patch file that inserts a welcome message and privacy policy link after the login dialog.

```html
<meta name="after" content=".login-ui .login-dialog">

<div class="welcome">
    <h2>Welcome to our Guacamole server!</h2>
    <p>
        Please be sure to read our <a href="/path/to/some/privacy.html">privacy
        policy</a> before continuing.
    </p>
</div>
```

--------------------------------

### Example guacd.conf configuration file

Source: https://guacamole.apache.org/doc/gug/configuring-guacamole.html

A standard guacd.conf file showing the [daemon], [server], and [ssl] sections.

```ini
#
# guacd configuration file
#

[daemon]

pid_file = /var/run/guacd.pid
log_level = info

[server]

bind_host = localhost
bind_port = 4822

#
# The following parameters are valid only if
# guacd was built with SSL support.
#

[ssl]

server_certificate = /etc/ssl/certs/guacd.crt
server_key = /etc/ssl/private/guacd.key
```

--------------------------------

### Run Guacamole container with dedicated network

Source: https://guacamole.apache.org/doc/gug/guacamole-docker.html

Example command to start the Guacamole container on a specific Docker network, using the container name as the guacd hostname.

```bash
$ docker run --network=some-network --name some-guacamole \
    -e GUACD_HOSTNAME=some-guacamole -d -p 8080:8080 guacamole/guacamole
```

--------------------------------

### Build instructions in Makefile.am

Source: https://guacamole.apache.org/doc/gug/custom-protocols.html

The Makefile.am file describing how to build the libguac-client-ball library.

```makefile
AUTOMAKE_OPTIONS = foreign

ACLOCAL_AMFLAGS = -I m4
AM_CFLAGS = -Werror -Wall -pedantic

lib_LTLIBRARIES = libguac-client-ball.la

# All source files of libguac-client-ball
libguac_client_ball_la_SOURCES = src/ball.c

# libtool versioning information
libguac_client_ball_la_LDFLAGS = -version-info 0:0:0
```

--------------------------------

### start

Source: https://guacamole.apache.org/doc/gug/protocol-reference.html

Starts a new subpath at the specified point.

```APIDOC
## start

### Description
Starts a new subpath at the specified point.

### Arguments
- **layer** (integer) - The layer which should start a new subpath.
- **x** (integer) - The X coordinate of the first point of the new subpath.
- **y** (integer) - The Y coordinate of the first point of the new subpath.
```

--------------------------------

### Build the web application with Maven

Source: https://guacamole.apache.org/doc/gug/writing-you-own-guacamole-app.html

Run the mvn package command to build the project and verify that the skeleton application is correctly configured.

```bash
$ mvn package
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building guacamole-tutorial
[INFO]    task-segment: [package]
[INFO] ------------------------------------------------------------------------
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4 seconds
[INFO] Finished at: Fri Jan 11 13:04:11 PST 2013
[INFO] Final Memory: 18M/128M
[INFO] ------------------------------------------------------------------------
$
```

--------------------------------

### Implement client handlers and initialization

Source: https://guacamole.apache.org/doc/gug/custom-protocols.html

Sets up the join handler to initialize the ball layer, the free handler to clean up resources, and the client init function to allocate data.

```c
#include "ball.h"

#include <guacamole/client.h>
#include <guacamole/layer.h>
#include <guacamole/protocol.h>
#include <guacamole/socket.h>
#include <guacamole/user.h>

#include <stdlib.h>

...

int ball_join_handler(guac_user* user, int argc, char** argv) {

    /* Get client associated with user */
    guac_client* client = user->client;

    /* Get ball layer from client data */
    ball_client_data* data = (ball_client_data*) client->data;
    guac_layer* ball = data->ball;

    ...

    /* Set up ball layer */
    guac_protocol_send_size(socket, ball, 128, 128);

    /* Prepare a curve which covers the entire layer */
    guac_protocol_send_rect(socket, ball,
            0, 0, 128, 128);

    /* Fill curve with solid color */
    guac_protocol_send_cfill(socket,
            GUAC_COMP_OVER, ball,
            0x00, 0x80, 0x80, 0xFF);

    /* Mark end-of-frame */
    guac_protocol_send_sync(socket, client->last_sent_timestamp);

    /* Flush buffer */
    guac_socket_flush(socket);

    /* User successfully initialized */
    return 0;

}

int ball_free_handler(guac_client* client) {

    ball_client_data* data = (ball_client_data*) client->data;

    /* Free client-level ball layer */
    guac_client_free_layer(client, data->ball);

    /* Free client-specific data */
    free(data);

    /* Data successfully freed */
    return 0;

}

int guac_client_init(guac_client* client) {

    /* Allocate storage for client-specific data */
    ball_client_data* data = malloc(sizeof(ball_client_data));

    /* Set up client data and handlers */
    client->data = data;

    /* Allocate layer at the client level */
    data->ball = guac_client_alloc_layer(client);

    ...

    /* Client-level handlers */
    client->join_handler = ball_join_handler;
    client->free_handler = ball_free_handler;

    return 0;

}
```

--------------------------------

### Install Guacamole components and update library cache

Source: https://guacamole.apache.org/doc/gug/guacamole-native.html

Run these commands to install the built components and update the system's shared library cache.

```bash
# make install
Making install in src/libguac
make[1]: Entering directory `/home/mjumper/guacamole/guacamole-server/src/libguac'
make[2]: Entering directory `/home/mjumper/guacamole/guacamole-server/src/libguac'
...
----------------------------------------------------------------------
Libraries have been installed in:
   /usr/local/lib

If you ever happen to want to link against installed libraries
in a given directory, LIBDIR, you must either use libtool, and
specify the full pathname of the library, or use the `-LLIBDIR'
flag during linking and do at least one of the following:
   - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
     during execution
   - add LIBDIR to the `LD_RUN_PATH' environment variable
     during linking
   - use the `-Wl,-rpath -Wl,LIBDIR' linker flag
   - have your system administrator add LIBDIR to `/etc/ld.so.conf'

See any operating system documentation about shared libraries for
more information, such as the ld(1) and ld.so(8) manual pages.
----------------------------------------------------------------------
make[2]: Nothing to be done for `install-data-am'.
make[2]: Leaving directory `/home/mjumper/guacamole/guacamole-server/src/protocols/vnc'
make[1]: Leaving directory `/home/mjumper/guacamole/guacamole-server/src/protocols/vnc'
make[1]: Entering directory `/home/mjumper/guacamole/guacamole-server'
make[2]: Entering directory `/home/mjumper/guacamole/guacamole-server'
make[2]: Nothing to be done for `install-exec-am'.
make[2]: Nothing to be done for `install-data-am'.
make[2]: Leaving directory `/home/mjumper/guacamole/guacamole-server'
make[1]: Leaving directory `/home/mjumper/guacamole/guacamole-server'
# ldconfig
#
```

--------------------------------

### Enable QuickConnect with docker run

Source: https://guacamole.apache.org/doc/gug/adhoc-connections.html

Use the -e option to set the QUICKCONNECT_ENABLED environment variable when starting the container manually.

```bash
$ docker run --name some-guacamole \
    -e QUICKCONNECT_ENABLED="true" \
    -d -p 8080:8080 guacamole/guacamole
```

--------------------------------

### ready instruction

Source: https://guacamole.apache.org/doc/gug/guacamole-protocol.html

Sent by the server after successful connection initialization, containing the unique connection ID.

```APIDOC
## ready instruction

### Description
Sent by the server after successful connection initialization, containing the unique connection ID.

### Instruction
ready

### Parameters
- connection ID (string) - Required - The unique ID of the new client connection.

### Example
5.ready,37.$260d01da-779b-4ee9-afc1-c16bae885cc7;
```

--------------------------------

### Restart Tomcat and start guacd with SysV init

Source: https://guacamole.apache.org/doc/gug/guacamole-native.html

Alternative to systemd for traditional init (SysV) systems. Restart Tomcat and start guacd using service commands.

```bash
# service tomcat9 restart
# service guacd start
```

--------------------------------

### Initialize Native PostgreSQL Database

Source: https://guacamole.apache.org/doc/gug/postgresql-auth.html

Run schema initialization scripts against a native PostgreSQL installation using the psql client.

```bash
$ cat schema/*.sql | psql -d guacamole_db -f -
```

--------------------------------

### Restart Tomcat and start guacd with systemd

Source: https://guacamole.apache.org/doc/gug/guacamole-native.html

After deploying the .war file, restart Tomcat to force deployment and start the guacd daemon if not running. This uses systemd init scripts.

```bash
# systemctl restart tomcat9
# systemctl start guacd
```

--------------------------------

### View guacenc manual page

Source: https://guacamole.apache.org/doc/gug/configuring-guacamole.html

Access the detailed documentation for guacenc options and output format configuration.

```bash
$ man guacenc
```

--------------------------------

### Example auth.json with two RDP connections

Source: https://guacamole.apache.org/doc/gug/json-auth.html

Example JSON file containing a username, expiration timestamp, and two RDP connections with parameters such as hostname, port, ignore-cert, and recording settings. This file is used as input to the encrypt-json.sh script.

```json
{
    "username" : "test",
    "expires" : "1446323765000",
    "connections" : {
        "My Connection" : {
            "protocol" : "rdp",
            "parameters" : {
                "hostname" : "10.10.209.63",
                "port" : "3389",
                "ignore-cert": "true",
                "recording-path": "/recordings",
                "recording-name": "My-Connection-${GUAC_USERNAME}-${GUAC_DATE}-${GUAC_TIME}"
            }
        },
        "My OTHER Connection" : {
            "protocol" : "rdp",
            "parameters" : {
                "hostname" : "10.10.209.64",
                "port" : "3389",
                "ignore-cert": "true",
                "recording-path": "/recordings",
                "recording-name": "My-OTHER-Connection-${GUAC_USERNAME}-${GUAC_DATE}-${GUAC_TIME}"
            }
        }
    }
}

```

--------------------------------

### Initialize native database via initdb.sh

Source: https://guacamole.apache.org/doc/gug/mysql-auth.html

Pipe the output of the initdb.sh script directly into a native MySQL client.

```bash
$ docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql | \
    mysql -u root -p guacamole_db
```

--------------------------------

### file_handler

Source: https://guacamole.apache.org/doc/gug/libguac.html

Handler for received files. Installed in the file_handler member of guac_user.

```APIDOC
## file_handler

### Description
Called when a user sends a file. The handler should assign further handlers to the provided guac_stream to handle blob and end instructions.

### Signature
int file_handler(guac_user* user, guac_stream* stream, char* mimetype, char* filename)

### Parameters
- **user** (guac_user*) - The user associated with the event.
- **stream** (guac_stream*) - The stream over which the file data will be received.
- **mimetype** (char*) - The MIME type of the file.
- **filename** (char*) - The name of the file.

### Installation
Set the file_handler member of guac_user within the join handler of guac_client.

### Example
```c
int file_handler(guac_user* user, guac_stream* stream,
        char* mimetype, char* filename) {
    /* Do something */
}

/* Within the "join" handler of guac_client */
user->file_handler = file_handler;
```
```

--------------------------------

### connect instruction

Source: https://guacamole.apache.org/doc/gug/guacamole-protocol.html

Final instruction of the handshake, terminating the handshake and starting the connection.

```APIDOC
## connect instruction

### Description
Final instruction of the handshake, terminating the handshake and starting the connection.

### Instruction
connect

### Parameters
- version (string) - Required - The protocol version.
- hostname (string) - Required - The hostname to connect to.
- port (string) - Required - The port to connect to.
- additional parameters (string) - Optional - Values for other connection parameters.

### Example
7.connect,13.VERSION_1_1_0,9.localhost,4.5900,0.,0.,0.;
```

--------------------------------

### Insert Connection and Parameters SQL

Source: https://guacamole.apache.org/doc/gug/jdbc-auth-schema.html

Example SQL commands to create a new connection named 'test' using the VNC protocol, retrieve its generated ID, and assign specific connection parameters.

```sql
-- Create connection
INSERT INTO guacamole_connection (connection_name, protocol) VALUES ('test', 'vnc');

-- Determine the connection_id
SELECT * FROM guacamole_connection WHERE connection_name = 'test' AND parent_id IS NULL;

-- Add parameters to the new connection
INSERT INTO guacamole_connection_parameter VALUES (1, 'hostname', 'localhost');
INSERT INTO guacamole_connection_parameter VALUES (1, 'port', '5901');
```
Tokens:
Raw