Skip to content

GUACAMOLE-2038: Document configuring outbound IPv6 connections from guacamole #268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pv2b wants to merge 3 commits into
base: main
Choose a base branch
from
+34 −0
Open

GUACAMOLE-2038: Document configuring outbound IPv6 connections from guacamole #268

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
213453d
GUACAMOLE-2038: Document configuring outbound IPv6 connections from g…
pv2b Feb 25, 2025
e43e1ff
GUACAMOLE-2038: Reword docs for guacamole client outbound IPv6
pv2b Feb 26, 2025
42852b7
GUACAMOLE-2038: Also mention database connections
pv2b Feb 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions src/guacamole-docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,31 @@ detail in the sections below. If the required configuration options for at
least one authentication mechanism are not provided, the Guacamole image will
not be able to start up, and you will see an error.

(guacamole-docker-ipv6)=

### Configure Guacamole to prefer IPv6 for outbound connections

By default, Guacamole will use IPv4 for all outbound connections, where an
A record is present in DNS. IPv6 will be used only if there are only AAAA
records in DNS, or if an IPv6 address is hard-coded.

Additionally, Guacamole will only attempt to make one connection to a single
IP address, so if the IPv4 connection fails, it will not fall back to IPv6.
This can be problematic for IPv6-only deployments, where such connections may
fail with a "Network is unreachable" error.

To override this, set the `JAVA_OPTS` environment variable to
`-Djava.net.preferIPv6Addresses=true`.
Copy link
Copy Markdown
Contributor

@mike-jumper mike-jumper Feb 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is entirely correct:

  • The JVM defaults to preferring IPv4. That's not to say this isn't worth documenting, but it's not something specific to the Guacamole webapp.

  • As written, it sounds like connections to other machines (ie: remote desktops) will fail for IPv6, but this is not the case. The JVM configuration option in question controls only whether IPv6 is used by the JVM, which would affect only the connection to guacd itself and external auth systems (databases, LDAP, etc.).

    This is eventually clarified later, but I think we can avoid the confusion earlier by specifically noting what this affects. Users would need to set this option only in the event that they need IPv6 to communicate with their own guacd service, their own database, or other authentication backends.

Copy link
Copy Markdown
Author

@pv2b pv2b Feb 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've re-worded this documentation section, hopefully this addresses your concerns


This does not affect which protocol guacd uses to connect to servers.

This will however affect the protocol used by guacamole to connect to guacd, to
use IPv6 if available. By default, guacd listens to IPv4 connections only. You'll
also need to [configure guacd to listen to IPv6 connections](#guacd-docker-ipv6).

This will also affect other outbound connections from guacamole-server, such as
connections to connect to a JWKS endpoint, as used by the OIDC extension.

(guacamole-docker-mysql)=

### MySQL authentication
Expand Down