guacd

Bind to a specific port on localhost

$ guacd -b [127.0.0.1] -l [4823]

$ guacd -f -L [debug]

$ guacd -C [my-cert.crt] -K [my-key.pem]

$ guacd -p [path/to/file.pid]

guacd [OPTIONS]

-b, --bind-host <hostname>
    Specifies the hostname or IP address guacd should bind to. Default is 0.0.0.0 (all interfaces).

-p, --bind-port <port>
    Sets the TCP port guacd will listen on. Default is 4822.

-f, --foreground
    Prevents guacd from detaching and running as a background daemon. Useful for debugging or when running under a service manager like systemd.

-L, --log-level <level>
    Defines the verbosity of logging. Possible levels include trace, debug, info, warn, and error. Default is info.

-l, --log-file <path>
    Specifies a file path where guacd should write its logs instead of standard error.

-P, --pid-file <path>
    Specifies a file path where guacd should write its process ID (PID).

-v, --version
    Displays the version of guacd and exits.

-h, --help
    Shows a help message listing all available command-line options and exits.

guacd is the Guacamole proxy daemon, a fundamental component of the Apache Guacamole remote desktop gateway. It acts as a lightweight, language-agnostic proxy that mediates communication between the Guacamole web application (running in a servlet container like Tomcat) and various remote desktop servers.

guacd understands standard remote desktop protocols such as VNC, RDP, and SSH. When a user connects to a remote desktop session through the Guacamole web application, the application establishes a connection to guacd. guacd then translates the Guacamole protocol messages into the respective native remote desktop protocol (e.g., VNC, RDP) and forwards them to the target remote desktop server.

This architecture ensures that no plugins or client software are required on the user's machine, as all protocol translation and communication with the remote server occur on the server where guacd runs. It typically listens on port 4822 by default and can be configured to run in the foreground or as a background service.

Security: guacd listens on a network port. It is crucial to restrict network access to this port (default 4822) using a firewall or by binding guacd to a specific internal IP address. Only trusted Guacamole web application instances should be able to connect to guacd.

Resource Usage: Each active Guacamole connection consumes resources on the server running guacd, including CPU for protocol translation and memory for buffering. Scaling considerations are important for environments with many concurrent users.

Dependency: guacd is a backend service and requires the guacamole-client web application to function as a complete remote access gateway. It does not provide a user interface on its own.

guacd operates as a crucial middleware in the Guacamole ecosystem. The Guacamole web application (running in a servlet container like Tomcat) establishes a WebSocket or HTTP tunnel connection with the user's browser. Simultaneously, the web application connects to guacd (typically on port 4822). guacd then establishes a connection to the target remote desktop server using the native protocol (VNC, RDP, SSH, etc.). All user input (keyboard, mouse) and remote display updates are relayed between the browser and the remote desktop server, with guacd performing the real-time protocol translation and proxying. This layered architecture enhances security by centralizing protocol handling and reduces the client-side burden.

The Guacamole project, including guacd, began development around 2010. It was created to provide clientless remote desktop access through standard web browsers, leveraging HTML5 and JavaScript. The core idea was to eliminate the need for plugins or specialized client software, making remote access universally accessible. guacd was designed as the crucial bridging component, abstracting the complexities of various remote desktop protocols from the web application and handling the low-level communication. Over the years, Guacamole, and by extension guacd, have evolved to support a wider range of protocols and improve performance and security, becoming an Apache project.

guacamole-client, systemd(1), VNC, RDP, SSH