Chris, Nick, and Mike - thanks for the quick guidance. I'll work
through this and do a writeup for doc improvement!
Appreciate you all.
David
------ Original Message ------
From "Michael Jumper" <[email protected]>
To [email protected]; "David Haukeness" <[email protected]>
Date 7/6/2022 12:55:33 PM
Subject Re: Doc - Adding new protocols missing guacamole-client
On Wed, Jul 6, 2022 at 11:30 AM David Haukeness <[email protected]>
wrote:
Hello,
I'm working through the documentation and have worked through the
"adding new protocols" section that covers guacd, however there's no
guidance on what/where needs to be modified on guacamole-client to get
the new protocols to show up in the "Add new connection" screen, or
demo the connection.
Is there a resource available that explains this part somewhere?
alternatively is there someone willing to offer guidance, and i'm
willing to write it up and PR the manual?
The existence of a protocol and its parameters are defined by JSON
files that separate each parameter into a typed field within a named
group of fields called a form. Built-in definitions can be found here:
https://github.com/apache/guacamole-client/tree/e348d3f89ab6488ab874aace78a5006279e2907e/guacamole-ext/src/main/resources/org/apache/guacamole/protocols
https://github.com/apache/guacamole-client/blob/e348d3f89ab6488ab874aace78a5006279e2907e/guacamole-ext/src/main/java/org/apache/guacamole/environment/LocalEnvironment.java#L56-L65
The built-in field types correspond to the types defined within
guacamole-ext and the webapp itself:
https://guacamole.apache.org/doc/guacamole-ext/org/apache/guacamole/form/package-summary.html
https://github.com/apache/guacamole-client/blob/e348d3f89ab6488ab874aace78a5006279e2907e/guacamole/src/main/frontend/src/app/form/services/formService.js#L33-L210
Extensions can define their own field types if needed. In practice,
this most often happens for authentication extensions (the Duo, TOTP,
and SAML extensions all do this), but can be also used for protocol
definitions.
Additional, third-party definitions can be added by creating the same
sort of JSON files within "GUACAMOLE_HOME/protocols/". If JSON for a
built-in protocol is found within this directory, that JSON takes
precedence over the built-in copy.
The human-readable text for the name of the protocol and for each
parameter and form are defined with translation strings. Each of these
strings will be derived from the protocol name and parameter name,
canonicalized to UPPERCASE_WITH_UNDERSCORES. For example:
https://github.com/apache/guacamole-client/blob/e348d3f89ab6488ab874aace78a5006279e2907e/guacamole/src/main/frontend/src/translations/en.json#L789-L860
In the above, the protocol ("vnc") determines the name of the namespace
containing the relevant strings ("PROTOCOL_VNC"). Within that
namespace, each parameter (like "audio-servername") is transformed to
the translation string for the field header
("FIELD_HEADER_AUDIO_SERVERNAME"), and each form (like
"authentication") is transformed to the translation string for the
section header ("SECTION_HEADER_AUTHENTICATION").
- Mike
