### Initialize Client and Start Render Thread (C)

Source: https://github.com/apache/guacamole-manual/blob/main/src/custom-protocols.md

Initializes the ball's starting position and velocity, then creates and starts the rendering thread. This function is called during client initialization.

```c
int ball_free_handler(guac_client* client) {

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

    /* Wait for render thread to terminate */
    pthread_join(data->render_thread, NULL);

    ...

}

int guac_client_init(guac_client* client) {

    ... 

    /* Start ball at upper left */
    data->ball_x = 0;
    data->ball_y = 0;

    /* Move at a reasonable pace to the lower right */
    data->ball_velocity_x = 200; /* pixels per second */
    data->ball_velocity_y = 200; /* pixels per second */

    /* Start render thread */
    pthread_create(&data->render_thread, NULL, ball_render_thread, client);

    ... 

}
```

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

### Guacd Syslog Entries

Source: https://github.com/apache/guacamole-manual/blob/main/src/troubleshooting.md

These are example log entries from guacd, indicating its startup status and network binding. They help diagnose issues related to port conflicts or successful initialization.

```none
guacd[19663]: Guacamole proxy daemon (guacd) version 0.7.0

```

```none
guacd[19663]: Unable to bind socket to host ::1, port 4823: Address family
              not supported by protocol

```

```none
guacd[19663]: Successfully bound socket to host 127.0.0.1, port 4823

```

```none
guacd[19663]: Exiting and passing control to PID 19665

```

```none
guacd[19665]: Exiting and passing control to PID 19666

```

```none
guacd[19666]: Listening on host 127.0.0.1, port 4823

```

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

### Install Python Build Dependencies (pip3)

Source: https://github.com/apache/guacamole-manual/blob/main/README.md

Alternative command to install Python packages using 'pip3', which may be necessary on systems where 'pip' defaults to Python 2.

```bash
pip3 install sphinx sphinx-book-theme sphinx-inline-tabs sphinx-copybutton myst-parser Jinja2 
```

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

### Filesystem Instruction

Source: https://github.com/apache/guacamole-manual/blob/main/src/protocol-reference.md

Allocates a new object associated with arbitrary filesystem metadata. File and directory contents are sent via streams requested with 'get' or created with 'put'.

```APIDOC
## FILESYSTEM

### Description
Allocates a new object, associating it with the given arbitrary filesystem metadata. The contents of files and directories within the filesystem will later be sent along streams requested with get instructions or created with put instructions.

### Method
FILESYSTEM

### Parameters
#### Arguments
- **object** (integer) – The index of the object to allocate.
- **name** (string) – The name of the filesystem.
```

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

### Custom Authentication Provider in Java

Source: https://context7.com/apache/guacamole-manual/llms.txt

Implement a custom authentication provider by extending SimpleAuthenticationProvider. This example demonstrates how to define custom properties, validate credentials against guacamole.properties, and configure authorized connections (VNC and RDP).

```java
package org.apache.guacamole.auth;

import java.util.HashMap;
import java.util.Map;
import org.apache.guacamole.GuacamoleException;
import org.apache.guacamole.environment.Environment;
import org.apache.guacamole.environment.LocalEnvironment;
import org.apache.guacamole.net.auth.Credentials;
import org.apache.guacamole.net.auth.simple.SimpleAuthenticationProvider;
import org.apache.guacamole.properties.StringGuacamoleProperty;
import org.apache.guacamole.protocol.GuacamoleConfiguration;

public class CustomAuthenticationProvider extends SimpleAuthenticationProvider {

    // Define custom properties for guacamole.properties
    private static final StringGuacamoleProperty AUTH_USERNAME =
        new StringGuacamoleProperty() {
            @Override public String getName() { return "custom-auth-username"; }
        };

    private static final StringGuacamoleProperty AUTH_PASSWORD =
        new StringGuacamoleProperty() {
            @Override public String getName() { return "custom-auth-password"; }
        };

    @Override
    public String getIdentifier() {
        return "custom-auth";
    }

    @Override
    public Map<String, GuacamoleConfiguration> getAuthorizedConfigurations(
            Credentials credentials) throws GuacamoleException {

        // Get properties from guacamole.properties
        Environment environment = LocalEnvironment.getInstance();
        String expectedUsername = environment.getRequiredProperty(AUTH_USERNAME);
        String expectedPassword = environment.getRequiredProperty(AUTH_PASSWORD);

        // Validate credentials
        if (credentials.getUsername() == null ||
            !credentials.getUsername().equals(expectedUsername) ||
            !credentials.getPassword().equals(expectedPassword)) {
            // Return null to indicate invalid credentials
            return null;
        }

        // Build authorized connections map
        Map<String, GuacamoleConfiguration> configs = new HashMap<>();

        // Add a VNC connection
        GuacamoleConfiguration vncConfig = new GuacamoleConfiguration();
        vncConfig.setProtocol("vnc");
        vncConfig.setParameter("hostname", "192.168.1.100");
        vncConfig.setParameter("port", "5901");
        configs.put("My VNC Server", vncConfig);

        // Add an RDP connection
        GuacamoleConfiguration rdpConfig = new GuacamoleConfiguration();
        rdpConfig.setProtocol("rdp");
        rdpConfig.setParameter("hostname", "192.168.1.101");
        rdpConfig.setParameter("username", "Administrator");
        rdpConfig.setParameter("password", "secret");
        configs.put("Windows Server", rdpConfig);

        return configs;
    }
}

```

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

### Build and Install Guacamole Plugin

Source: https://github.com/apache/guacamole-manual/blob/main/src/custom-protocols.md

Commands to build, install, and update shared library cache for a Guacamole plugin. Ensure you have root privileges for 'make install' and 'ldconfig'.

```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
```

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

### Allocate Filesystem Object

Source: https://github.com/apache/guacamole-manual/blob/main/src/protocol-reference.md

Use the 'filesystem' instruction to allocate a new object associated with arbitrary filesystem metadata. File and directory contents will be sent via streams requested with 'get' or created with 'put'.

```text
filesystem(object, name)
```

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

### Start Guacd Docker Container

Source: https://context7.com/apache/guacamole-manual/llms.txt

Launches the guacd container, which handles the actual remote desktop connections. It's configured to use the custom Docker network and log level.

```bash
# Start guacd container
docker run -d \
    --name guacd \
    --network guacamole-net \
    -e LOG_LEVEL=info \
    guacamole/guacd

```

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

### Get Instruction

Source: https://github.com/apache/guacamole-manual/blob/main/src/protocol-reference.md

Requests a new stream providing read access to an object stream by name. The response includes a 'body' instruction.

```APIDOC
## GET

### Description
Requests that a new stream be created, providing read access to the object stream having the given name. The requested stream will be created, in response, with a body instruction.

Stream names are arbitrary and dictated by the object from which they are requested, with the exception of the root stream of the object itself, which has the reserved name “`/`”. The root stream of the object has the mimetype “`application/vnd.glyptodon.guacamole.stream-index+json`”, and provides a simple JSON map of available stream names to their corresponding mimetypes. If the object contains a hierarchy of streams, some of these streams may also be “`application/vnd.glyptodon.guacamole.stream-index+json`”.

For example, the ultimate content of the body stream provided in response to a get request for the root stream of an object containing two text streams, “A” and “B”, would be the following:

```json
{
  "A" : "text/plain",
  "B" : "text/plain"
}
```

### Method
GET

### Parameters
#### Arguments
- **object** (integer) – The index of the object to request a stream from.
- **name** (string) – The name of the stream being requested from the given object.
```

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

### Example Guacamole Connection Import YAML

Source: https://github.com/apache/guacamole-manual/blob/main/src/batch-import.md

This YAML structure defines multiple connections, including VNC, RDP, SSH, and Kubernetes. Ensure correct indentation and parameter syntax for successful import.

```yaml
---
  - name: conn1
    protocol: vnc
    parameters:
      username: alice
      password: pass1
      hostname: conn1.web.com
    group: ROOT
    users:
      - guac user 1
      - guac user 2
    groups:
    - Connection 1 Users
    attributes:
      guacd-encryption: none
  - name: conn2
    protocol: rdp
    parameters:
      username: bob
      password: pass2
      hostname: conn2.web.com
    group: ROOT/Parent Group
    users:
      - guac user 1
    attributes:
      guacd-encryption: none
  - name: conn3
    protocol: ssh
    parameters:
      username: carol
      password: pass3
      hostname: conn3.web.com
    group: ROOT/Parent Group/Child Group
    users:
      - guac user 2
      - guac user 3
  - name: conn4
    protocol: kubernetes
```

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

### Implement Mouse Event Handler in C

Source: https://github.com/apache/guacamole-manual/blob/main/src/libguac.md

Install a callback function to handle mouse events. The handler receives the user, current X/Y coordinates, and a button mask indicating pressed/released buttons.

```c
int mouse_handler(guac_user* user, int x, int y, int button_mask) {
    /* Do something */
}
```

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

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

### Run MySQL Container for Guacamole

Source: https://context7.com/apache/guacamole-manual/llms.txt

This command starts a MySQL 8 container, configuring it with root password, database name, user, and password for Guacamole. It also sets up a persistent volume for data.

```bash
docker run -d \
    --name guacamole-mysql \
    --network guacamole-net \
    -e MYSQL_ROOT_PASSWORD=rootpassword \
    -e MYSQL_DATABASE=guacamole_db \
    -e MYSQL_USER=guacamole \
    -e MYSQL_PASSWORD=secretpassword \
    -v guacamole-mysql-data:/var/lib/mysql \
    mysql:8
```

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

### Implement Custom HTTP Tunnel Servlet

Source: https://context7.com/apache/guacamole-manual/llms.txt

Extend `GuacamoleHTTPTunnelServlet` and override `doConnect()` to handle authentication and build connection configurations. This example shows how to extract parameters, authenticate users, and configure connections for VNC, RDP, and SSH.

```java
package org.apache.guacamole.example;

import javax.servlet.http.HttpServletRequest;
import org.apache.guacamole.GuacamoleException;
import org.apache.guacamole.net.GuacamoleSocket;
import org.apache.guacamole.net.GuacamoleTunnel;
import org.apache.guacamole.net.InetGuacamoleSocket;
import org.apache.guacamole.net.SimpleGuacamoleTunnel;
import org.apache.guacamole.protocol.ConfiguredGuacamoleSocket;
import org.apache.guacamole.protocol.GuacamoleConfiguration;
import org.apache.guacamole.servlet.GuacamoleHTTPTunnelServlet;

public class MyTunnelServlet extends GuacamoleHTTPTunnelServlet {

    @Override
    protected GuacamoleTunnel doConnect(HttpServletRequest request)
        throws GuacamoleException {

        // Get connection parameters from request
        String hostname = request.getParameter("hostname");
        String port = request.getParameter("port");
        String protocol = request.getParameter("protocol");

        // Validate/authenticate user here
        String username = request.getParameter("username");
        if (username == null || !isAuthorized(username)) {
            throw new GuacamoleException("Not authorized");
        }

        // Build connection configuration
        GuacamoleConfiguration config = new GuacamoleConfiguration();
        config.setProtocol(protocol); // "vnc", "rdp", "ssh", etc.
        config.setParameter("hostname", hostname);
        config.setParameter("port", port);

        // Protocol-specific parameters
        if ("vnc".equals(protocol)) {
            config.setParameter("password", request.getParameter("password"));
        } else if ("rdp".equals(protocol)) {
            config.setParameter("username", request.getParameter("rdp-user"));
            config.setParameter("password", request.getParameter("rdp-pass"));
            config.setParameter("security", "nla");
            config.setParameter("ignore-cert", "true");
        } else if ("ssh".equals(protocol)) {
            config.setParameter("username", request.getParameter("ssh-user"));
            config.setParameter("private-key", getPrivateKey(username));
        }

        // Connect to guacd (default port 4822)
        GuacamoleSocket socket = new ConfiguredGuacamoleSocket(
            new InetGuacamoleSocket("localhost", 4822),
            config
        );

        // Return tunnel wrapping the socket
        return new SimpleGuacamoleTunnel(socket);
    }

    private boolean isAuthorized(String username) {
        // Implement your authentication logic
        return true;
    }

    private String getPrivateKey(String username) {
        // Retrieve SSH private key for user
        return "-----BEGIN RSA PRIVATE KEY-----\n...";
    }
}
```

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

### Start PostgreSQL Docker Container

Source: https://context7.com/apache/guacamole-manual/llms.txt

Deploys a PostgreSQL container for storing Guacamole's authentication and configuration data. It's connected to the custom network and configured with user, password, and database name.

```bash
# Start PostgreSQL for authentication storage
docker run -d \
    --name guacamole-postgres \
    --network guacamole-net \
    -e POSTGRES_USER=guacamole \
    -e POSTGRES_PASSWORD=secretpassword \
    -e POSTGRES_DB=guacamole_db \
    -v guacamole-postgres-data:/var/lib/postgresql/data \
    postgres:15

```

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

### Request Object Stream

Source: https://github.com/apache/guacamole-manual/blob/main/src/protocol-reference.md

Use the 'get' instruction to request a new stream providing read access to an object stream by name. The root stream ('/') provides a JSON map of available stream names and their mimetypes.

```text
get(object, name)
```

```json
{
  "A" : "text/plain",
  "B" : "text/plain"
}
```

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

### Install Python Build Dependencies

Source: https://github.com/apache/guacamole-manual/blob/main/README.md

Installs the required Python packages for building the Guacamole manual using pip. Ensure Python 3.8 or later is installed.

```bash
pip install sphinx sphinx-book-theme sphinx-inline-tabs sphinx-copybutton myst-parser Jinja2 
```

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

### Client Select Instruction

Source: https://github.com/apache/guacamole-manual/blob/main/src/guacamole-protocol.md

The initial instruction sent by the client to select the desired protocol.

```none
6.select,3.vnc;
```

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

### Server Args Instruction

Source: https://github.com/apache/guacamole-manual/blob/main/src/guacamole-protocol.md

Server response listing accepted parameter names and protocol version.

```none
4.args,13.VERSION_1_1_0,8.hostname,4.port,8.password,13.swap-red-blue,9.read-only;
```

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

### Server Ready Instruction

Source: https://github.com/apache/guacamole-manual/blob/main/src/guacamole-protocol.md

Server response indicating successful handshake and providing the new connection ID.

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

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

### Generate Configure Script and Configure Project

Source: https://github.com/apache/guacamole-manual/blob/main/src/custom-protocols.md

Commands to generate the configure script using autoreconf and then run it to prepare the build environment. This is necessary before the first 'make' invocation.

```bash
$ autoreconf -fi
libtoolize: putting auxiliary files in '.'.
libtoolize: copying file './ltmain.sh'
libtoolize: putting macros in AC_CONFIG_MACRO_DIRS, 'm4'.
libtoolize: copying file 'm4/libtool.m4'
libtoolize: copying file 'm4/ltoptions.m4'
libtoolize: copying file 'm4/ltsugar.m4'
libtoolize: copying file 'm4/ltversion.m4'
libtoolize: copying file 'm4/lt~obsolete.m4'
configure.ac:10: installing './compile'
configure.ac:4: installing './missing'
Makefile.am: installing './depcomp'
$ ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
...
configure: creating ./config.status
config.status: creating Makefile
config.status: executing depfiles commands
config.status: executing libtool commands
$
```

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

### Configure Script Error for Missing libguac

Source: https://github.com/apache/guacamole-manual/blob/main/src/custom-protocols.md

This console output shows the error message generated when the `configure` script fails because the libguac library is not installed. Ensure guacamole-server is installed before running `configure`.

```console
$ ./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"
$
```

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

### Example Guacamole Instruction: Set Display Size

Source: https://github.com/apache/guacamole-manual/blob/main/src/guacamole-protocol.md

A concrete example of a Guacamole instruction for setting the display size to 1024x768. It demonstrates the opcode 'size', layer index '0', width '1024', and height '768'.

```none
4.size,1.0,4.1024,3.768;
```

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

### Implement File Handler in C

Source: https://github.com/apache/guacamole-manual/blob/main/src/libguac.md

Set up a handler for incoming files. This callback is invoked when the remote desktop sends a file to the client. It receives the user, a stream, the file's MIME type, and its filename.

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

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

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

### close Instruction

Source: https://github.com/apache/guacamole-manual/blob/main/src/protocol-reference.md

Closes the current path by drawing a straight line from the current point to the starting point.

```APIDOC
## close

### Description
Closes the current path by connecting the start and end points with a straight line.

### Arguments
**layer** (integer) – The layer whose path should be closed.
```

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

### Automake Configuration: Makefile.am

Source: https://github.com/apache/guacamole-manual/blob/main/src/custom-protocols.md

This `Makefile.am` file defines the build process for the libguac-client-ball library, specifying source files and linking requirements for the Guacamole client plugin.

```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

```

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

### Body Instruction

Source: https://github.com/apache/guacamole-manual/blob/main/src/protocol-reference.md

Allocates a new stream associated with a stream name requested by a 'get' instruction. Stream contents are sent via blob instructions.

```APIDOC
## BODY

### Description
Allocates a new stream, associating it with the name of a stream previously requested by a get instruction. The contents of the stream will be sent later with blob instructions. The full size of the stream need not be known ahead of time.

### Method
BODY

### Parameters
#### Arguments
- **object** (integer) – The index of the object associated with this stream.
- **stream** (integer) – The index of the stream to allocate.
- **mimetype** (string) – The mimetype of the data being sent.
- **name** (string) – The name of the stream associated with the object.
```

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

### Initialize Guacamole Database

Source: https://context7.com/apache/guacamole-manual/llms.txt

Executes the generated SQL script to set up the necessary tables and structures within the PostgreSQL database.

```bash
# Initialize the database
docker exec -i guacamole-postgres psql -U guacamole -d guacamole_db < initdb.sql

```

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

### Input/Event Instructions

Source: https://github.com/apache/guacamole-manual/blob/main/src/protocol-reference.md

Instructions sent by the client to the server to report user input events.

```APIDOC
## key

### Description
Sends the specified key press or release event.

### Method
Client-to-Server

### Endpoint
Not applicable (Instruction within protocol stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **keysym** (integer) - Required - The [X11 keysym](https://www.x.org/releases/X11R7.6/doc/xproto/x11protocol.html#keysym_encoding) of the key being pressed or released.
- **pressed** (integer) - Required - 0 if the key is not pressed, 1 if the key is pressed.

### Request Example
```json
{
  "keysym": 65307, 
  "pressed": 1
}
```

### Response
#### Success Response (200)
None

#### Response Example
None

## mouse

### Description
Sends the specified mouse movement or button press or release event (or combination thereof).

### Method
Client-to-Server

### Endpoint
Not applicable (Instruction within protocol stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **x** (integer) - Required - The current X coordinate of the mouse pointer.
- **y** (integer) - Required - The current Y coordinate of the mouse pointer.
- **mask** (integer) - Required - The button mask, representing the pressed or released status of each mouse button.

### Request Example
```json
{
  "x": 150,
  "y": 250,
  "mask": 2
}
```

### Response
#### Success Response (200)
None

#### Response Example
None

## size

### Description
Specifies that the client’s optimal screen size has changed from what was specified during the handshake, or from previously-sent “size” instructions.

### Method
Client-to-Server

### Endpoint
Not applicable (Instruction within protocol stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **width** (integer) - Required - The new, optimal screen width.
- **height** (integer) - Required - The new, optimal screen height.

### Request Example
```json
{
  "width": 1920,
  "height": 1080
}
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### Client Handshake Instructions

Source: https://github.com/apache/guacamole-manual/blob/main/src/guacamole-protocol.md

Client response detailing display size, supported codecs, timezone, and connection parameters.

```none
4.size,4.1024,3.768,2.96;
```

```none
5.audio,9.audio/ogg;
```

```none
5.video;
```

```none
5.image,9.image/png,10.image/jpeg;
```

```none
8.timezone,16.America/New_York;
```

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

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

### Initialize Remote Display and Background

Source: https://github.com/apache/guacamole-manual/blob/main/src/custom-protocols.md

Initializes the remote display size and fills it with a gray background. This handler is called when a user joins the connection.

```c
#include <guacamole/client.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 user-specific socket */
    guac_socket* socket = user->socket;

    /* Send the display size */
    guac_protocol_send_size(socket, GUAC_DEFAULT_LAYER, 1024, 768);

    /* Prepare a curve which covers the entire layer */
    guac_protocol_send_rect(socket, GUAC_DEFAULT_LAYER,
            0, 0, 1024, 768);

    /* Fill curve with solid color */
    guac_protocol_send_cfill(socket,
            GUAC_COMP_OVER, GUAC_DEFAULT_LAYER,
            0x80, 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 guac_client_init(guac_client* client) {

    /* This example does not implement any arguments */
    client->args = TUTORIAL_ARGS;

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

    return 0;

}
```

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

### Build Docker Image for Guacamole Manual

Source: https://github.com/apache/guacamole-manual/blob/main/README.md

Builds a Docker image tagged 'guacamole/manual' containing the Guacamole user manual. Requires Docker CE version 1.6 or later.

```bash
docker image build -t guacamole/manual .
```

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

### Start Guacamole Web Application Docker Container

Source: https://context7.com/apache/guacamole-manual/llms.txt

Deploys the Guacamole web application container, connecting it to the guacd and PostgreSQL containers. It's exposed on port 8080 and configured with connection details for guacd and the database.

```bash
# Start Guacamole web application
docker run -d \
    --name guacamole \
    --network guacamole-net \
    -e GUACD_HOSTNAME=guacd \
    -e GUACD_PORT=4822 \
    -e POSTGRESQL_HOSTNAME=guacamole-postgres \
    -e POSTGRESQL_PORT=5432 \
    -e POSTGRESQL_DATABASE=guacamole_db \
    -e POSTGRESQL_USER=guacamole \
    -e POSTGRESQL_PASSWORD=secretpassword \
    -p 8080:8080 \
    guacamole/guacamole

```

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

### Automake Configuration: configure.ac

Source: https://github.com/apache/guacamole-manual/blob/main/src/custom-protocols.md

This `configure.ac` file specifies project information and checks for required dependencies, notably the libguac library, for building the Guacamole client plugin.

```autoconf
# Project information
AC_PREREQ([2.61])
AC_INIT([libguac-client-ball], [0.1.0])
AM_INIT_AUTOMAKE([-Wall -Werror foreign subdir-objects])
AM_SILENT_RULES([yes])

AC_CONFIG_MACRO_DIRS([m4])

# Check for required build tools
AC_PROG_CC
AC_PROG_CC_C99
AC_PROG_LIBTOOL

# Check for libguac
AC_CHECK_LIB([guac], [guac_client_stream_png],,
      AC_MSG_ERROR("libguac is required for communication via "
                   "the Guacamole protocol"))

AC_CONFIG_FILES([Makefile])
AC_OUTPUT

```

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

### Streaming Instructions

Source: https://github.com/apache/guacamole-manual/blob/main/src/protocol-reference.md

Instructions for managing data streams, including acknowledgments, argument passing, audio/file/clipboard data transfer, and stream termination.

```APIDOC
## ack

### Description
The ack instruction acknowledges a received data blob, providing a status
code and message indicating whether the operation associated with the blob
succeeded or failed. A status code other than 0 (`SUCCESS`) implicitly
ends the stream.

### Arguments
* **stream** (*integer*) – The index of the stream the corresponding blob was received on.
* **message** (*string*) – A human-readable error message. This typically is not exposed within
any user interface, and mainly helps with debugging.
* **status** (*integer*) – The Guacamole status code denoting success or failure. For a list of status
codes, see the table in [Status codes](#status-codes).

## argv

### Description
Allocates a new stream, associating it with the given argument (connection
parameter) metadata. The relevant connection parameter data will later be
sent along the stream with blob instructions. If sent by the client, this
data will be the desired new value of the connection parameter being
changed, and will be applied if the server supports changing that
connection parameter while the connection is active. If sent by the server, 
this data will be the current value of a connection parameter being exposed
to the client.

### Arguments
* **stream** (*integer*) – The index of the stream to allocate.
* **mimetype** (*string*) – The mimetype of the connection parameter being sent. In most cases,
this will be “text/plain”.
* **name** (*string*) – The name of the connection parameter whose value is being sent.

## audio

### Description
Allocates a new stream, associating it with the given audio metadata.
Audio data will later be sent along the stream with blob instructions.  The
mimetype given must be a mimetype previously specified by the client during
the handshake procedure. Playback will begin immediately and will continue
as long as blobs are received along the stream.

### Arguments
* **stream** (*integer*) – The index of the stream to allocate.
* **mimetype** (*string*) – The mimetype of the audio data being sent.

## blob

### Description
Sends a blob of data along the given stream. This blob of data is
arbitrary, base64-encoded data, and only has meaning to the Guacamole
client or server through the metadata assigned to the stream when the
stream was allocated.

### Arguments
* **stream** (*integer*) – The index of the stream along which the given data should be sent.
* **data** (*string*) – The base64-encoded data to send.

## clipboard

### Description
Allocates a new stream, associating it with the given clipboard metadata.
The clipboard data will later be sent along the stream with blob
instructions. If sent by the client, this data will be the contents of the
client-side clipboard. If sent by the server, this data will be the
contents of the clipboard within the remote desktop.

### Arguments
* **stream** (*integer*) – The index of the stream to allocate.
* **mimetype** (*string*) – The mimetype of the clipboard data being sent. In most cases, this
will be “text/plain”.

## end

### Description
The end instruction terminates an open stream, freeing any client-side or
server-side resources. Data sent to a terminated stream will be ignored.
Terminating a stream with the end instruction only denotes the end of the
stream and does not imply an error.

### Arguments
**stream** (*integer*) – The index of the stream the corresponding blob was received on.

## file

### Description
Allocates a new stream, associating it with the given arbitrary file
metadata. The contents of the file will later be sent along the stream with
blob instructions. The full size of the file need not be known ahead of
time.

### Arguments
* **stream** (*integer*) – The index of the stream to allocate.
* **mimetype** (*string*) – The mimetype of the file being sent.
* **filename** (*string*) – The name of the file, as it would be saved on a filesystem.
```

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

### JSON Connection Import Format

Source: https://github.com/apache/guacamole-manual/blob/main/src/batch-import.md

Illustrates the JSON structure for importing connections. It's a list of connection objects, each requiring 'name' and 'protocol'. Optional fields include 'parameters', 'parentIdentifier', 'group', 'users', 'groups', and 'attributes'.

```json
[
  {
    "name": "conn1",
    "protocol": "vnc",
    "parameters": { "username": "alice", "password": "pass1", "hostname": "conn1.web.com" },
    "parentIdentifier": "ROOT",
    "users": [ "guac user 1", "guac user 2" ],
    "groups": [ "Connection 1 Users" ],
    "attributes": { "guacd-encryption": "none" }
  },
  {
    "name": "conn2",
    "protocol": "rdp",
    "parameters": { "username": "bob", "password": "pass2", "hostname": "conn2.web.com" },
    "group": "ROOT/Parent Group",
    "users": [ "guac user 1" ],
    "attributes": { "guacd-encryption": "none" }
  },
  {
    "name": "conn3",
    "protocol": "ssh",
    "parameters": { "username": "carol", "password": "pass3", "hostname": "conn3.web.com" },
    "group": "ROOT/Parent Group/Child Group",
    "users": [ "guac user 2", "guac user 3" ]
  },
  {
    "name": "conn4",
    "protocol": "kubernetes"
  }
]
```

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

### Initialize Guacamole Client and Ball Layer

Source: https://github.com/apache/guacamole-manual/blob/main/src/custom-protocols.md

Initializes the Guacamole client, allocates client-specific data, and creates the ball layer. Sets up the join and free handlers for the client.

```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 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;

}
```

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

### Allocate Video Stream

Source: https://github.com/apache/guacamole-manual/blob/main/src/protocol-reference.md

Use the 'video' instruction to allocate a new stream for video data. The mimetype must have been previously specified during the handshake. Playback begins immediately and continues as long as blobs are received.

```text
video(stream, layer, mimetype)
```

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

### Server Control Instructions

Source: https://github.com/apache/guacamole-manual/blob/main/src/protocol-reference.md

Instructions sent by the server to control the client or report connection status.

```APIDOC
## sync

### Description
Reports that all operations as of the given server-relative timestamp have been completed. Both client and server are expected to occasionally send sync to report on current operation execution state, with the server using sync to denote the end of a logical frame.

If a sync is received from the server, the client must respond with a corresponding sync once all previous operations have been completed, or the server may stop sending updates until the client catches up. For the client, sending a sync with a timestamp newer than any timestamp received from the server is an error.

### Method
Not specified (Server-to-Client or Client-to-Server)

### Endpoint
Not applicable (Instruction within protocol stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None

## error

### Description
Notifies the client that the connection is about to be closed due to the specified error. This message can be sent by the server during any phase.

### Method
Server-to-Client

### Endpoint
Not applicable (Instruction within protocol stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **message** (string) - Required - An arbitrary message describing the error
- **status** (integer) - Required - The Guacamole status code describing the error. For a list of status codes, see the table in [Status codes](#status-codes).

### Request Example
```json
{
  "message": "Invalid credentials",
  "status": 401
}
```

### Response
#### Success Response (200)
None

#### Response Example
None

## log

### Description
The log instruction sends an arbitrary string for debugging purposes. This instruction will be ignored by Guacamole clients, but can be seen in protocol dumps if such dumps become necessary. Sending a log instruction can help add context when searching for the cause of a fault in protocol support.

### Method
Server-to-Client

### Endpoint
Not applicable (Instruction within protocol stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **message** (string) - Required - An arbitrary, human-readable message.

### Request Example
```json
{
  "message": "User logged in successfully."
}
```

### Response
#### Success Response (200)
None

#### Response Example
None

## mouse

### Description
Reports that a user on the current connection has moved the mouse to the given coordinates.

### Method
Server-to-Client

### Endpoint
Not applicable (Instruction within protocol stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **x** (integer) - Required - The current X coordinate of the mouse pointer.
- **y** (integer) - Required - The current Y coordinate of the mouse pointer.

### Request Example
```json
{
  "x": 100,
  "y": 200
}
```

### Response
#### Success Response (200)
None

#### Response Example
None

## ready

### Description
The ready instruction sends the ID of a new connection and marks the beginning of the interactive phase of a new, successful connection. The ID sent is a completely arbitrary string, and has no standard format. It must be unique from all existing and future connections and may not match the name of any installed protocol support.

### Method
Server-to-Client

### Endpoint
Not applicable (Instruction within protocol stream)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **identifier** (string) - Required - An arbitrary, unique identifier for the current connection. This identifier must be unique from all existing and future connections, and may not match the name of any installed protocol support (such as “vnc” or “rdp”).

### Request Example
```json
{
  "identifier": "conn-12345"
}
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### Build the Guacamole Manual

Source: https://github.com/apache/guacamole-manual/blob/main/README.md

Builds the Guacamole manual using Sphinx. The generated HTML files will be located in the 'build/html/' directory.

```bash
make
```

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

### Initialize Guacamole Touch Input

Source: https://github.com/apache/guacamole-manual/blob/main/src/guacamole-common-js.md

Use Guacamole.Touchpad or Guacamole.Touchscreen to abstract touch events, providing mouse-like events. Assign event handlers for mousedown, mousemove, and mouseup to process touch states, which are represented as Guacamole.Mouse.State objects.

```javascript
var element = document.getElementById("some-arbitrary-id");
var touch = new Guacamole.Touchpad(element); // or Guacamole.Touchscreen

touch.onmousedown =
touch.onmousemove =
touch.onmouseup   = function(state) {

    // Do something with the mouse state received ...

};
```

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

### Initialize Guacamole Client and Handle Events

Source: https://github.com/apache/guacamole-manual/blob/main/tutorials/guacamole-tutorial/src/main/webapp/index.html

Instantiate the Guacamole client using an HTTP tunnel and append its display element to the document. Set up error handling and connect to the remote desktop. This code is intended for client-side JavaScript integration.

```javascript
/* <![CDATA[ */ // Get display div from document var display = document.getElementById("display"); // Instantiate client, using an HTTP tunnel for communications. var guac = new Guacamole.Client( new Guacamole.HTTPTunnel("tunnel") ); // Add client to display div display.appendChild(guac.getDisplay().getElement()); // Error handler guac.onerror = function(error) { alert(error); }; // Connect guac.connect(); // Disconnect on close window.onunload = function() { guac.disconnect(); } // Mouse var mouse = new Guacamole.Mouse(guac.getDisplay().getElement()); mouse.onmousedown = mouse.onmouseup = mouse.onmousemove = function(mouseState) { guac.sendMouseState(mouseState); }; // Keyboard var keyboard = new Guacamole.Keyboard(document); keyboard.onkeydown = function (keysym) { guac.sendKeyEvent(1, keysym); }; keyboard.onkeyup = function (keysym) { guac.sendKeyEvent(0, keysym); }; /* ]]> */
```