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

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

**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: an Example Implementation ====

==== Broker Module / Backend ====

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

  * listSessions
  * selectSessions

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 session profiles (hard-coded in this example)
#
#   + sid=123456789
#   + sid=abcdefg
# 
sub selectProfile
{
  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.
#
# Modify to your needs if you need authentication

sub checkAccess
{
        return 1;
}

# configuration for our two session profiles

sub listSessions
{
  my $user=shift;
  print "START_USER_SESSIONS
  
[123456789]
name=X2Go Session
command=KDE
host=x2goserver.org
user=$user

[abcdefg]
name= Test X2Go Session 2
command=XFCE
host=x2gotest.org
user=test

END_USER_SESSIONS
";
}

1;
</code>


==== Broker Frontends ====

X2Go Client can access a broker module using one of two broker methods:

  * HTTP(S)
  * SSH. 

==== Broker Frontend: HTTP(s) ====

The implementation of an HTTP(S) X2Go Session Broker is usually a CGI script, which can look like this (if written in Perl):

<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/plain',
                         -expires =>'+1h'),
      $cgi->start_html(  -title   =>'X2Go Broker',
                         -author  =>'team@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')
{
   selectSessions($cgi->param('user'), $cgi->param('sid'));
}
 $cgi->end_form();
 print $cgi->end_html();

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

==== Broker Frontend: SSH ====

An SSH broker implementation can be a simple Perl script that gets run from the command line via SSH. Such a script could look like this:

<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 still 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>