This shows you the differences between two versions of the page.
Both sides previous revision Previous revision | |||
wiki:advanced:x2gobroker:plaintexprotocol [2013/03/27 10:48] sunweaver removed |
— (current) | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== X2Go Session Broker Protocol: Plain Text ====== | ||
- | |||
- | //Client implementations: | ||
- | |||
- | The X2Go project offers a [[http:// | ||
- | |||
- | In theory, you can implement your own X2Go Session Broker by meeting some basic demands. | ||
- | |||
- | This documentation explains a minimal broker implementation along the code of a Perl script. | ||
- | |||
- | In this example, the X2Go Session Broker consists of two components: | ||
- | |||
- | - '' | ||
- | - the broker frontend (either of the below): | ||
- | - '' | ||
- | - '' | ||
- | |||
- | ===== X2Go Session Broker: The Backend ==== | ||
- | |||
- | The package '' | ||
- | |||
- | * listProfiles | ||
- | * selectProfile | ||
- | |||
- | If you want to use authentication with your session broker, the broker backend also has to provide a function called | ||
- | |||
- | * checkAccess | ||
- | |||
- | A very small and simple broker backend can look like this: | ||
- | |||
- | < | ||
- | package x2gobroker; | ||
- | use strict; | ||
- | use base ' | ||
- | our @EXPORT = (' | ||
- | |||
- | #we have two sessions | ||
- | sub selectSession | ||
- | { | ||
- | my ($user, $sid)=@_; | ||
- | if($sid eq " | ||
- | { | ||
- | print " | ||
- | } | ||
- | if($sid eq " | ||
- | { | ||
- | print " | ||
- | } | ||
- | } | ||
- | #do not check authentication data, | ||
- | #return true on any | ||
- | # | ||
- | sub checkAccess | ||
- | { | ||
- | return 1; | ||
- | } | ||
- | # | ||
- | sub listSessions | ||
- | { | ||
- | my $user=shift; | ||
- | print " | ||
- | < | ||
- | name=X2Go Session< | ||
- | command=KDE< | ||
- | host=x2goserver.org< | ||
- | user=$user< | ||
- | < | ||
- | name= Test X2Go Session 2<br> | ||
- | command=startxfce4< | ||
- | host=x2gotest.org< | ||
- | user=test< | ||
- | END_USER_SESSIONS< | ||
- | } | ||
- | |||
- | 1; | ||
- | </ | ||
- | |||
- | |||
- | ==== CLient side ==== | ||
- | |||
- | FIXME -> TODO | ||
- | |||
- | X2Go client can access a broker module using one of two broker methods. | ||
- | Via HTTP(S) or SSH. | ||
- | HTTP(S) broker is usually CGI script, which can look like: | ||
- | < | ||
- | # | ||
- | |||
- | use strict; | ||
- | use CGI; | ||
- | use CGI::Carp qw(fatalsToBrowser); | ||
- | use lib "/ | ||
- | use x2gobroker; | ||
- | my $cgi = new CGI; | ||
- | |||
- | my @formValues = $cgi-> | ||
- | |||
- | print $cgi-> | ||
- | | ||
- | $cgi-> | ||
- | | ||
- | | ||
- | | ||
- | ' | ||
- | |||
- | if (!checkAccess($cgi-> | ||
- | $cgi-> | ||
- | { | ||
- | printNoAccess(); | ||
- | print $cgi-> | ||
- | exit (0); | ||
- | } | ||
- | |||
- | print $cgi-> | ||
- | $cgi-> | ||
- | |||
- | if ($cgi-> | ||
- | { | ||
- | | ||
- | } | ||
- | |||
- | if ($cgi-> | ||
- | { | ||
- | | ||
- | } | ||
- | | ||
- | | ||
- | print $cgi-> | ||
- | |||
- | sub printNoAccess | ||
- | { | ||
- | print $cgi-> | ||
- | $cgi-> | ||
- | $cgi-> | ||
- | $cgi-> | ||
- | } | ||
- | </ | ||
- | |||
- | SSH broker can be a simple Perl script, which can look like: | ||
- | < | ||
- | # | ||
- | use strict; | ||
- | use lib "/ | ||
- | use x2gobroker; | ||
- | use Getopt:: | ||
- | |||
- | my $user=getlogin(); | ||
- | my $authid; | ||
- | my $task; | ||
- | my $sid; | ||
- | |||
- | #you don't need to check password on ssh brocker. | ||
- | #But possible you steel want to check auth id | ||
- | #if (!checkAccess($user, | ||
- | #{ | ||
- | # printNoAccess(); | ||
- | # exit (0); | ||
- | #} | ||
- | print " | ||
- | GetOptions(' | ||
- | ' | ||
- | if(! $task) | ||
- | { | ||
- | die " | ||
- | } | ||
- | if ($task | ||
- | { | ||
- | | ||
- | } | ||
- | elsif ($task eq ' | ||
- | { | ||
- | if(! $sid) | ||
- | { | ||
- | die " | ||
- | } | ||
- | | ||
- | } | ||
- | else | ||
- | { | ||
- | die "task \"" | ||
- | } | ||
- | sub printNoAccess | ||
- | { | ||
- | die ' | ||
- | } | ||
- | </ | ||
- | |||
- | 2. How X2Go broker work | ||
- | |||
- | 2.1. Authentication | ||
- | |||
- | The X2Go client can use different methods of authentication. On HTTP(S) | ||
- | broker it could be username and password. On SSH broker a SSH key | ||
- | authentication can also be used. With both types of broker you can | ||
- | verify additional parameter " | ||
- | is saved in file. Path to file can be specified as X2Go Client command | ||
- | line option " | ||
- | data as it shown in example above. In such case function checkAccess | ||
- | should always return 1. In example of SSH-Broker this function is not | ||
- | called at all. The broker just print " | ||
- | know, that authentication is successful. In some setups can make sense | ||
- | to give access to broker without authentication. For example in LAN if | ||
- | broker only serve as load balancer for X2Go Servers. | ||
- | |||
- | 2.2. List of predefined X2Go sessions | ||
- | |||
- | After successful authentication on broker, X2Go Client will request list | ||
- | of predefined X2Go Sessions. This list look just the same as session | ||
- | file of X2Go Client. The function, that send X2Go sessions to Client | ||
- | look like: | ||
- | < | ||
- | sub listSessions | ||
- | { | ||
- | print " | ||
- | < | ||
- | option1=value1< | ||
- | .... | ||
- | optionN=valueN< | ||
- | < | ||
- | option1=value1< | ||
- | .... | ||
- | optionN=valueN< | ||
- | END_USER_SESSIONS< | ||
- | } | ||
- | </ | ||
- | The options are the same as in X2Go Client configuration file. There is | ||
- | only a difference in parameters " | ||
- | parameters which are not supported in configuration file " | ||
- | " | ||
- | The " | ||
- | actual address of a server will be provided after session selection. It | ||
- | can make sense in a case of load balancing. The best server will be | ||
- | chosen after selection and sent to client. | ||
- | The " | ||
- | selection of session too. However, you can set this parameter with some | ||
- | value to inform the Client, that passwordless authentication should be | ||
- | tried, for example: " | ||
- | Parameter " | ||
- | should not be asked, but broker password should be used instead. It can | ||
- | be useful if the broker and X2Go Server using same authentication server | ||
- | and there is no need to ask the same password twice. It is not | ||
- | recommended to use such authentication with HTTP Broker without SSL | ||
- | encryption. | ||
- | Parameter " | ||
- | to say X2Go Client that an instance (or instances) of this session | ||
- | already running or are suspended on server. X2Go Client will display the | ||
- | status on the Session button. | ||
- | |||
- | 2.3. Selecting a session | ||
- | |||
- | When predefined sessions are listed in X2Go Client, user can choose a | ||
- | session from sessions list. The id of chosen session will be sent to | ||
- | broker and broker send a connection data back to client. It is | ||
- | responsibility of function " | ||
- | < | ||
- | sub selectSession | ||
- | { | ||
- | my ($user, $sid)=@_; | ||
- | if($sid eq " | ||
- | { | ||
- | print " | ||
- | } | ||
- | } | ||
- | </ | ||
- | |||
- | This function send a server address and SSH port for X2Go connection. If | ||
- | no other data are specified a new X2Go session will be created. | ||
- | Broker can also send to Client information, | ||
- | should be resumed. In this case broker should also send a session data | ||
- | to Client: | ||
- | < | ||
- | sub selectSession | ||
- | { | ||
- | my ($user, $sid)=@_; | ||
- | if($sid eq " | ||
- | { | ||
- | print " | ||
- | |||
- | " | ||
- | } | ||
- | </ | ||
- | Broker can get this data from session database or by executing | ||
- | " | ||
- | broker mode, it will not verify if there are existing sessions on X2Go | ||
- | server. It is a responsibility of X2Go Broker. Broker should also | ||
- | suspend session before providing session data to client if session is | ||
- | running. | ||
- | |||
- | The broker can also provide a SSH Key to client: | ||
- | < | ||
- | sub selectSession | ||
- | { | ||
- | my ($user, $sid)=@_; | ||
- | if($sid eq " | ||
- | { | ||
- | print " | ||
- | print " | ||
- | Proc-Type: 4,ENCRYPTED | ||
- | DEK-Info: AES-128-CBC, | ||
- | |||
- | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | ||
- | yX7XLwCszCLM1FCYpdIGmM98vuHVcpNlVUBVgNcTxE1XCCnPZPjUXiNnUZPk1lme | ||
- | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | ||
- | o1q7Q1YmH43qI18lifjUhGZUTYWKQSsj2Am9bnjqaveV2aMEWymC8J9aJOYLpVZG | ||
- | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | ||
- | G1DwWnSRgyJaxRm4Ik0/ | ||
- | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | ||
- | VR60OGB7dHy+7ozqkjzuX+uB04GIqPJwG797i26Bo4v7uhbALjMa5qsObqXIPM1S | ||
- | XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX | ||
- | XXXXXXXXXXXXXXXX== | ||
- | -----END DSA PRIVATE KEY-----"; | ||
- | } | ||
- | } | ||
- | </ | ||
- | It can be useful in some cases. It is recommended to transfer such keys | ||
- | only over encrypted channels. It is also recommended to transfer only | ||
- | temporary keys, which should be removed from known_hosts after | ||
- | authorization on X2Go server. | ||
- | |||
- | 3. Configuring X2Go client for connection to broker | ||
- | |||
- | There are several command line parameters to configure X2Go Client for | ||
- | use with broker: | ||
- | |||
- | --broker-name=< | ||
- | Name of broker to display in X2Go client. This parameter is optional | ||
- | |||
- | --broker-url=< | ||
- | URL of broker. Protocol is " | ||
- | username in URL. In this case it will be pasted in authorization dialog | ||
- | of X2Go Client. Examples of URL: | ||
- | --broker-url=https:// | ||
- | --broker-url=ssh:// | ||
- | |||
- | --broker-ssh-key=< | ||
- | Path to SSH key to use for authorization on broker. This parameter is | ||
- | valid only for SSH broker. | ||
- | |||
- | --broker-autologin | ||
- | Use default SSH key or SSH agent for authorization on broker. This | ||
- | parameter is valid only for SSH broker. | ||
- | |||
- | --broker-noauth | ||
- | Do not ask for user credentials for broker authorizations. This can be | ||
- | useful if you using HTTP(S) broker without authentication. Username will | ||
- | be sent to broker if it specified in broker URL. This option is valid | ||
- | only for HTTP(S) broker. | ||
- | |||
- | |||
- | |||