Go to file
Michael Jumper 189d8fab30 GUACAMOLE-1201: Throttle outbound audio data to avoid overflowing RDP server audio input buffer.
The RDP specification for the AUDIO_INPUT channel requires that all
audio be sent in packets of a specific size. Guacamole does correctly
limit itself to sending packets of this size to the RDP server, but will
send quite a few of these packets all at once if it has received more
audio data than the RDP packet size. This is OK in principle (the
Guacamole client should be able to send audio in packets of whatever
size it chooses), but may overwhelm the software running within the RDP
server if the amount of data received exceeds the available buffer
space, resulting in dropped samples.

As there is no way to know the size of the remote audio buffer, we need
to instead ensure that audio is streamed as close to real time as
possible, with each audio packet of N bytes not being sent until roughly
the amount of time represented by those N bytes has elapsed since the
last packet. This throttling ensures that software expecting to process
audio in real time should never run out of buffer space.

That said, if we never exceed the per-packet data rate and occasionally
send a packet earlier than real time would dictate, unavoidable latency
in sending/receiving audio data would accumulate over time. For example,
if each audio packet represents 10ms of audio data, but we receive that
audio packet 10.1ms after the previous packet, we need to adjust the
timing of the next audio packet(s) to account for that additional 0.1ms.
Simply waiting 10ms after sending each packet would cause that 0.1ms to
accumulate each time it occurs, eventually resulting in noticable
latency and finally running out of buffer space.

Thus, these changes:

1. Leverage a flush thread and per-packet scheduling to ensure that each
   flushed audio packet does not exceed the equivalent real time rate.
2. Calculate the amount of additional latency from the amount of data
   received beyond the required packet size, and amortize scheduling
   corrections to account for that latency over the next several audio
   packets.

This ensures that audio is streamed exactly as it is received if the
audio matches the packet size of the RDP server, and audio that is
received in a different size or varying sizes is buffered and throttled
to keep things within the expectations of software running within the
RDP server.
2021-05-01 16:23:32 -07:00
bin GUACAMOLE-1205: Update Guacamole Server version numbers for 1.3.0 release 2020-11-03 14:54:55 -05:00
doc GUACAMOLE-423: Automatically populate package version within Doxyfile. 2017-12-06 01:13:39 -08:00
m4 Add m4/README and .gitignore. 2013-06-04 16:31:14 -07:00
src GUACAMOLE-1201: Throttle outbound audio data to avoid overflowing RDP server audio input buffer. 2021-05-01 16:23:32 -07:00
util GUACAMOLE-637: Not all systems place Perl in /usr/bin. The line #!/usr/bin/env perl should be used for portability. 2019-01-23 18:44:45 -08:00
.dockerignore GUACAMOLE-456: use Docker multi-stage build 2017-12-06 07:57:12 -05:00
.gitignore GUACAMOLE-1151: Add .gitignore entry for NetBeans project directory 2020-08-05 16:43:43 -04:00
configure.ac GUACAMOLE-1307: Use VerifyCertificateEx callback if supported. 2021-03-09 22:53:11 -08:00
CONTRIBUTING GUACAMOLE-436: Remove incubator prefix from repositories and URLs. 2017-12-06 00:54:21 -08:00
Dockerfile GUACAMOLE-1133: Add gcrypt build dependency for Docker image. 2021-01-23 22:16:58 -05:00
LICENSE GUACAMOLE-1: Add required LICENSE and NOTICE. Remove old MIT license. 2016-03-28 20:39:48 -07:00
Makefile.am GUACAMOLE-662: Migrate tests to test runners generated by new convenience script. Remove unnecessary test runners. 2018-11-17 18:06:40 -08:00
NOTICE GUACAMOLE-929: Update copyright date to 2020. 2020-01-19 13:36:09 -08:00
README GUACAMOLE-572: Fix typo from "test-based protocol" to "text-based protocol" 2018-06-17 17:40:59 +01:00
README-unit-testing.md GUACAMOLE-637: The $^ variable is non-portable and specific to GNU Make. As otherwise POSIX-compliant platforms may not provide this variable, we shouldn't use it here. 2019-01-23 18:44:45 -08:00

------------------------------------------------------------
 About this README
------------------------------------------------------------

This README is intended to provide quick and to-the-point documentation for
technical users intending to compile parts of Apache Guacamole themselves.

Source archives are available from the downloads section of the project website:
 
    http://guacamole.apache.org/

A full manual is available as well:

    http://guacamole.apache.org/doc/gug/


------------------------------------------------------------
 What is guacamole-server?
------------------------------------------------------------

The guacamole-server package is a set of software which forms the basis of the
Guacamole stack. It consists of guacd, libguac, and several protocol support
libraries.

guacd is the Guacamole proxy daemon used by the Guacamole web application and
framework. As JavaScript cannot handle binary protocols (like VNC and remote
desktop) efficiently, a new text-based protocol was developed which would
contain a common superset of the operations needed for efficient remote desktop
access, but would be easy for JavaScript programs to process. guacd is the
proxy which translates between arbitrary protocols and the Guacamole protocol.


------------------------------------------------------------
 Required dependencies
------------------------------------------------------------

All software within guacamole-server is built using the popular GNU Automake,
and thus provides the standard configure script. Before compiling, at least
the following required dependencies must already be installed:

    1) Cairo (http://cairographics.org/)

    2) libjpeg-turbo (http://libjpeg-turbo.virtualgl.org/)
       OR libjpeg (http://www.ijg.org/)

    3) libpng (http://www.libpng.org/pub/png/libpng.html)

    4) OSSP UUID (http://www.ossp.org/pkg/lib/uuid/)


------------------------------------------------------------
 Optional dependencies
------------------------------------------------------------

In addition, the following optional dependencies may be installed in order to
enable optional features of Guacamole. Note that while the various supported
protocols are technically optional, you will no doubt wish to install the 
dependencies of at least ONE supported protocol, as Guacamole would be useless
otherwise.

    RDP:
        * FreeRDP (http://www.freerdp.com/)

    SSH:
        * libssh2 (http://www.libssh2.org/)
        * OpenSSL (https://www.openssl.org/)
        * Pango (http://www.pango.org/)

    Telnet:
        * libtelnet (https://github.com/seanmiddleditch/libtelnet)
        * Pango (http://www.pango.org/)

    VNC:
        * libVNCserver (http://libvnc.github.io/)

    Support for audio within VNC:
        * PulseAudio (http://www.freedesktop.org/wiki/Software/PulseAudio/)

    Support for SFTP file transfer for VNC or RDP:
        * libssh2 (http://www.libssh2.org/)
        * OpenSSL (https://www.openssl.org/)

    Support for WebP image compression:
        * libwebp (https://developers.google.com/speed/webp/)

    "guacenc" video encoding utility:
        * FFmpeg (https://ffmpeg.org/)


------------------------------------------------------------
 Compiling and installing guacd, libguac, etc.
------------------------------------------------------------

All software within guacamole-server is built using the popular GNU Automake,
and thus provides the standard configure script.

1) Run configure

    $ ./configure

    Assuming all dependencies have been installed, this should succeed without
    errors. If you wish to install the init script as well, you need to specify
    the location where your system init scripts are located (typically
    /etc/init.d):

    $ ./configure --with-init-dir=/etc/init.d

    Running configure in this manner will cause the "make install" step to
    install an init script to the specified directory, which you can then
    activate using the service management mechanism provided by your
    distribution).

2) Run make

    $ make

    guacd, libguac, and any available protocol support libraries will now
    compile.

3) Install (as root)

    # make install

    All software that was just built, including documentation, will be
    installed.

    guacd will install to your /usr/local/sbin directory by default. You can
    change the install location by using the --prefix option for configure.


------------------------------------------------------------
 Running guacd 
------------------------------------------------------------

If you installed the init script during compile and install, you should be
able to start guacd through the service management utilities provided by
your distribution (if any) or by running the init script directly (as root):

    # /etc/init.d/guacd start

Root access is needed to write the pidfile /var/run/guacd.pid. You can also run
guacd itself directly without the init script (as any user):

    $ guacd

guacd currently takes several command-line options:

    -b HOST 

        Changes the host or address that guacd listens on.

    -l PORT

        Changes the port that guacd listens on (the default is port 4822).

    -p PIDFILE

        Causes guacd to write the PID of the daemon process to the specified
        file. This is useful for init scripts and is used by the provided init
        script.

    -L LEVEL

        Sets the maximum level at which guacd will log messages to syslog and,
        if running in the foreground, the console.  Legal values are debug,
        info, warning, and error.  The default value is info.

    -f
        Causes guacd to run in the foreground, rather than automatically
        forking into the background. 

Additional information can be found in the guacd man page:

    $ man guacd

------------------------------------------------------------
 Reporting problems
------------------------------------------------------------

Please report any bugs encountered by opening a new issue in the JIRA system
hosted at:
    
    https://issues.apache.org/jira/browse/GUACAMOLE