[X2Go-Commits] page added: wiki:development:x2gobroker:plaintexprotocol

wiki-admin at x2go.org wiki-admin at x2go.org
Wed Mar 27 11:48:35 CET 2013


A page in your DokuWiki was added or changed. Here are the details:

Date        : 2013/03/27 10:48
Browser     : Mozilla/5.0 (X11; Linux x86_64; rv:18.0) Gecko/20100101 Firefox/18.0 Iceweasel/18.0.1
IP-Address  : 46.142.186.224
Hostname    : 224-186-142-46.pool.kielnet.net
Old Revision: ---
New Revision: http://wiki.x2go.org/doku.php/wiki:development:x2gobroker:plaintexprotocol
Edit Summary: created
User        : sunweaver

====== X2Go Session Broker Protocol: Plain Text ======

//Client implementations: X2Go Client (since 3.x.y.z), Python X2Go (planned for 0.6.x.y)//

The X2Go project offers a [[http://code.x2go.org/gitweb?p=x2gobroker.git;a=summary|public X2Go Session Broker implementation]]. However, there also exist several other implementations in large-scale production deployments.

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: 

  - ''x2gobroker.pm'' (a Perl module, the broker backend)
  - the broker frontend (either of the below):
    - ''x2gobroker.cgi'' (a CGI script written in Perl -> HTTP based broker)
    - ''x2gobroker'' (a command line script written in Perl -> SSH based broker)

===== X2Go Session Broker: The Backend ====

The package ''x2gobroker.pm'' can be considered as the broker backend. It has to implement two functions at minimal (names are arbitrary):

  * 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:

<code>
package x2gobroker;
use strict;
use base 'Exporter';
our @EXPORT = ('checkAccess', 'listSessions', 'selectSession');

#we have two sessions
sub selectSession
{
  my ($user, $sid)=@_;
  if($sid eq "123456789")
  {
      print
"SERVER:x2goserver.org:22\n";
  }
  if($sid eq "abcdefg")
  {
      print "SERVER:x2gotest.org:22\n";
  }
}
#do not check authentication data,
#return true on any
#combination of username/password
sub checkAccess
{
        return 1;
}
#configuration for two sessions
sub listSessions
{
  my $user=shift;
  print "START_USER_SESSIONS<br>
<br>[123456789]<br>
name=X2Go Session<br>
command=KDE<br>
host=x2goserver.org<br>
user=$user<br>
<br>[abcdefg]<br>
name= Test X2Go Session 2<br>
command=startxfce4<br>
host=x2gotest.org<br>
user=test<br>
END_USER_SESSIONS<br>";
}

1;
</code>


==== 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:
<code>
#!/usr/bin/perl

use strict;
use CGI;
use CGI::Carp qw(fatalsToBrowser);
use lib "/usr/lib/x2go";
use x2gobroker;
my $cgi = new CGI;

my @formValues = $cgi->param();

print $cgi->header(-type    =>'text/html',
           
             -expires =>'+1h'),
      $cgi->start_html(  -title   =>'X2Go Broker',
                         -author  =>'team at obviously-nice.de',
                         -base    =>'true',
                         -meta    =>{'keywords'   =>'x2go',
                         'description'=>'X2Go Broker'});

if (!checkAccess($cgi->param('user'), $cgi->param('password'),
$cgi->param('authid')) == 1)
{
  printNoAccess();
  print $cgi->end_html();
  exit (0);
}

print $cgi->start_form(),
$cgi->strong('Access granted');

if ($cgi->param('task') eq 'listsessions')
{
   listSessions($cgi->param('user'));
}

if ($cgi->param('task') eq 'selectsession')
{
   selectSession($cgi->param('user'), $cgi->param('sid'));
}
 $cgi->hr(),
 $cgi->end_form();
 print $cgi->end_html();

sub printNoAccess
{
      print $cgi->start_form(),
            $cgi->hr(),
            $cgi->strong('Access denied'),
            $cgi->end_form();
}
</code>

SSH broker can be a simple Perl script, which can look
like:
<code>
#!/usr/bin/perl
use strict;
use lib "/usr/lib/x2go";
use x2gobroker;
use Getopt::Long;

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, $authid) == 1)
#{
#  printNoAccess();
#  exit (0);
#}
print "Access granted\n";
GetOptions('task=s' => \$task,
           'sid=s' => \$sid);
if(! $task)
{
    die "parameter --task is required";
}
if ($task  eq 'listsessions')
{
   listSessions($user);
}
elsif ($task eq 'selectsession')
{
   if(! $sid)
   {
       die "parameter --sid is required";
   }
   selectSession($user, $sid);
}
else
{
   die "task \"".$task."\" not implemented on broker\n";
}
sub printNoAccess
{
      die 'Access denied';
}
</code>

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 "authid". It is a user defined string which
is saved in file. Path to file can be specified as X2Go Client command
line option "--auth-id". You can configure your broker not to check user
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 "Access granted" to let X2Go Client
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:
<code>
sub listSessions
{
  print "START_USER_SESSIONS<br>
<br>[ 
<session 1>  ]<br>
option1=value1<br>
....
optionN=valueN<br>
<br>[  <session 2>  ]<br>
option1=value1<br>
....
optionN=valueN<br>
END_USER_SESSIONS<br>";
}
</code>
The options are the same as in X2Go Client configuration file. There is
only a difference in parameters "host" and "key". And there are two
parameters which are not supported in configuration file "status" and
"usebrokerpass".
The "host" parameter it is not necessary a hostname of X2Go server. 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 "key" parameter is also ignored. Key can be provided to client after
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: "key=will be provided later".
Parameter "usebrokerpass" say, that a user password for this session
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 "status" can be one of two values "S" or "R". It can be used
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 "selectSession":
<code>
sub selectSession
{
  my ($user, $sid)=@_;
  if($sid eq "123456789")
  {
      print "SERVER:x2goserver.org:22\n";
  }
}
</code>

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, that suspended session
should be resumed. In this case broker should also send a session data
to Client:
<code>
sub selectSession
{
  my ($user, $sid)=@_;
  if($sid eq "123456789")
  {
      print "SERVER:phoca:22\n";
      print
"SESSION_INFO:12542|ncryer-53-1348753256_stDstartxfce4_dp24|53|debian|S|2012-09-27T06:40:57|7db77095d8a782f479d509d96f2e3261|188.195.168.12|30004|30005|2012-09-27T06:41:28|ncryer|285|30006|\n";
}
</code>
Broker can get this data from session database or by executing
"x2golistsessions $user" on X2Go server. If X2Go Client running in
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:
<code>
sub selectSession
{
  my ($user, $sid)=@_;
 
if($sid eq "123456789")
  {
      print "SERVER:phoca:22\n";
      print "-----BEGIN DSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: AES-128-CBC,XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
yX7XLwCszCLM1FCYpdIGmM98vuHVcpNlVUBVgNcTxE1XCCnPZPjUXiNnUZPk1lme
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
o1q7Q1YmH43qI18lifjUhGZUTYWKQSsj2Am9bnjqaveV2aMEWymC8J9aJOYLpVZG
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
G1DwWnSRgyJaxRm4Ik0/kh78ioUfkVerXaCf2OKCMyiZBWcsNfvQwDa9MBrZ4rYW
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
VR60OGB7dHy+7ozqkjzuX+uB04GIqPJwG797i26Bo4v7uhbALjMa5qsObqXIPM1S
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXX==
-----END DSA PRIVATE KEY-----";
 }
}
</code>
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>
Name of broker to display in X2Go client. This parameter is optional

--broker-url=<protocol>://[username@]<host>[:port]/path
URL of broker. Protocol is "http", "https" or "ssh". You can specify an
username in URL. In this case it will be pasted in authorization dialog
of X2Go Client. Examples of URL:
--broker-url=https://x2gobroker.org/cgi-bin/x2gobroker.cgi
--broker-url=ssh://user@x2gobroker.org:22/usr/lib/x2go/x2gobroker.pl

--broker-ssh-key=<path to 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.






-- 
This mail was generated by DokuWiki at
http://wiki.x2go.org/




More information about the x2go-commits mailing list