====== X2Go Session Broker for Newbies ======

//Provided by Oleksandr Shneyder, edited by Mike Gabriel//

===== What is an X2Go Session Broker? =====

Most of you have already used X2Go Client in standalone mode. X2Go Client in standalone mode allows to be configured by the user himself. Normally, the user creates a set of session profiles that allows the user to work remotely on one or more X2Go Servers. See the documentation that explains [[doc:usage:x2goclient|the usage of X2Go Client]].

When X2Go Client is run in broker mode, then it does not allow the local definition of session profiles. The list of session profiles gets provided by the X2Go Session Broker. A session broker is either a HTTP(s) server or an SSH server.

In large-scale deployments an X2Go Session Broker can be used to centrally provide X2Go session profiles to X2Go Client. The list of provided X2Go session profiles can be user or client-address specific.

An X2Go Session Broker is the piece of software (X2Go component) that you need to deploy X2Go where [[wiki:advanced:x2gobroker:loadbalancing|load-balancing setup scenarios]] are requested.

The implementation of X2Go Session Brokers can be manifold as long as a [[wiki:advanced:x2gobroker:howitworks|well-defined communication protocol]] (X2Go Client <-> X2Go Session Broker) is used.

One possible impementation is provided in our package archives:

<code bash>
$ sudo apt-get install x2gobroker-daemon
</code>

===== How do I use an X2Go Session Broker with X2Go Client? =====

If you have access to an X2Go Session Broker, you can launch X2Go Client in broker mode. There are several command line options to configure X2Go Client's broker mode

  * ''<nowiki>--broker-name=<name></nowiki>'': Sets the broker name to display in X2Go Client. This parameter is optional.

  * ''<nowiki>--broker-url=<protocol>://[username@]<host>[:port]/path</nowiki>'': Sets the URL of the session broker. "protocol" must be one of "http", "https" or "ssh". If "username@" is provided, it will be pasted into the authorization dialog of X2Go Client. URL examples are:
    * ''<nowiki>--broker-url=https://x2gobroker.org/cgi-bin/x2gobroker.cgi</nowiki>''
    * ''<nowiki>--broker-url=ssh://user@x2gobroker.org:22/usr/lib/x2go/x2gobroker.pl</nowiki>''

  * ''<nowiki>--broker-ssh-key=<path to key></nowiki>'': Sets the path to an SSH key to use for authentication against an SSH session broker. The client's behavior is undefined if this flag is used for non-SSH session brokers.

  * ''<nowiki>--broker-autologin</nowiki>'': Enables the use of the default SSH key or SSH agent for authentication against an SSH session broker. The client's behavior is undefined if this flag is used for non-SSH session brokers.

  * ''<nowiki>--broker-noauth</nowiki>'': Does not ask for user credentials during session broker authentication. This can be useful if you are using an HTTP(S) session broker without authentication. If you run an HTTP(S) server without authentication, but with user-specific profiles, then put the user name into the broker URL (refer to --broker-url.) The user name then will be extracted from the broker URL and be sent to the session broker. The client's behavior is undefined if this flag is used for non-HTTP(S) session brokers.