You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@guacamole.apache.org by David Haukeness <da...@hauken.us> on 2022/07/06 18:30:36 UTC
Doc - Adding new protocols missing guacamole-client
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?
Thanks,
David
Re: [EXTERNAL] Re: Doc - Adding new protocols missing guacamole-client
Posted by Chris Nigh <cn...@equinix.com>.
In the past, I’ve also added protocol json files mentioned in #2 into the Guacamole Home in a directory named protocols. Not sure if that’s still an appropriate method – the readProtocols() method in guacamole-ext/src/main/java/org/apache/guacamole/environment/LocalEnvironment.java suggests that might still work.
You’ll still need to handle the translations for #3.
-Chris
From: Nick Couchman <vn...@apache.org>
Date: Wednesday, July 6, 2022 at 2:49 PM
To: user@guacamole.apache.org <us...@guacamole.apache.org>, David Haukeness <da...@hauken.us>
Subject: [EXTERNAL] Re: Doc - Adding new protocols missing guacamole-client
On Wed, Jul 6, 2022 at 2:30 PM David Haukeness <da...@hauken.us>> 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?
David,
Thanks for the feedback - getting protocols to show up in the Guacamole Client menu requires three changes:
1) The protocol needs to be added to the file guacamole-ext/src/main/java/org/apache/guacamole/environment/LocalEnvironment.java:
/**
* Array of all known protocol names.
*/
private static final String[] KNOWN_PROTOCOLS = new String[] {
"kubernetes",
"rdp",
"ssh",
"telnet",
"vnc",
};
2) A json file needs to be created in guacamole-ext/src/main/resources/org/apache/guacamole/protocols with the required configuration parameters (see existing protocols for examples).
3) The translation files need to be updated with the key/value pairs for translations, else the fields for the new protocol will only show the expected translation key and not the actual translation. See guacamole/src/main/frontend/src/translations/en.json for the main translation file and examples from other protocols.
-Nick
Re: Doc - Adding new protocols missing guacamole-client
Posted by Nick Couchman <vn...@apache.org>.
On Wed, Jul 6, 2022 at 2:30 PM David Haukeness <da...@hauken.us> 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?
>
>
David,
Thanks for the feedback - getting protocols to show up in the Guacamole
Client menu requires three changes:
1) The protocol needs to be added to the
file guacamole-ext/src/main/java/org/apache/guacamole/environment/LocalEnvironment.java:
/**
* Array of all known protocol names.
*/
private static final String[] KNOWN_PROTOCOLS = new String[] {
"kubernetes",
"rdp",
"ssh",
"telnet",
"vnc",
};
2) A json file needs to be created
in guacamole-ext/src/main/resources/org/apache/guacamole/protocols with the
required configuration parameters (see existing protocols for examples).
3) The translation files need to be updated with the key/value pairs for
translations, else the fields for the new protocol will only show the
expected translation key and not the actual translation.
See guacamole/src/main/frontend/src/translations/en.json for the main
translation file and examples from other protocols.
-Nick
Re: Doc - Adding new protocols missing guacamole-client
Posted by Nick Couchman <vn...@apache.org>.
On Wed, Jul 6, 2022 at 2:30 PM David Haukeness <da...@hauken.us> 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?
>
> Thanks,
> David
>
Re[2]: Doc - Adding new protocols missing guacamole-client
Posted by David Haukeness <da...@hauken.us>.
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" <mj...@apache.org>
To user@guacamole.apache.org; "David Haukeness" <da...@hauken.us>
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 <da...@hauken.us>
>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
>
Re: Doc - Adding new protocols missing guacamole-client
Posted by Michael Jumper <mj...@apache.org>.
On Wed, Jul 6, 2022 at 11:30 AM David Haukeness <da...@hauken.us> 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