Differences

This shows you the differences between two versions of the page.

--- wiki:development:x2gobroker:plaintexprotocol [2013/03/27 10:48]
sunweaver created
+++ wiki:development:x2gobroker:plaintexprotocol [2013/03/27 15:48] (current)
sunweaver
@@ Line 1: / Line 1: @@
 ====== X2Go Session Broker Protocol: Plain Text ======
-//Client implementations: X2Go Client (since 3.x.y.z), Python X2Go (planned for 0.6.x.y)//
+//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.
@@ Line 16: / Line 21: @@
     - ''x2gobroker'' (a command line script written in Perl -> SSH based broker)
-===== X2Go Session Broker: The Backend ====
+===== 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):
-  * listProfiles
+  * listSessions
-  * selectProfile
+  * selectSessions
 If you want to use authentication with your session broker, the broker backend also has to provide a function called
@@ Line 35: / Line 42: @@
 our @EXPORT = ('checkAccess', 'listSessions', 'selectSession');
-#we have two sessions
+#
-sub selectSession
+# We have two session profiles (hard-coded in this example)
+#
+#   + sid=123456789
+#   + sid=abcdefg
+#
+sub selectProfile
 {
   my ($user, $sid)=@_;
@@ Line 48: / Line 60: @@
   }
 }
-#do not check authentication data,
-#return true on any
+# Do not check authentication data,
-#combination of username/password
+# return true on any combination of username/password.
+#
+# Modify to your needs if you need authentication
 sub checkAccess
 {
         return 1;
 }
-#configuration for two sessions
+# configuration for our two session profiles
 sub listSessions
 {
   my $user=shift;
-  print "START_USER_SESSIONS<br>
+  print "START_USER_SESSIONS
-<br>[123456789]<br>
-name=X2Go Session<br>
+[123456789]
-command=KDE<br>
+name=X2Go Session
-host=x2goserver.org<br>
+command=KDE
-user=$user<br>
+host=x2goserver.org
-<br>[abcdefg]<br>
+user=$user
-name= Test X2Go Session 2<br>
-command=startxfce4<br>
+[abcdefg]
-host=x2gotest.org<br>
+name= Test X2Go Session 2
-user=test<br>
+command=XFCE
-END_USER_SESSIONS<br>";
+host=x2gotest.org
+user=test
+END_USER_SESSIONS
+";
 }
@@ Line 77: / Line 98: @@
-==== CLient side ====
+==== Broker Frontends ====
-FIXME -> TODO
+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):
-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
@@ Line 96: / Line 121: @@
 my @formValues = $cgi->param();
-print $cgi->header(-type    =>'text/html',
+print $cgi->header(-type    =>'text/plain',
                          -expires =>'+1h'),
       $cgi->start_html(  -title   =>'X2Go Broker',
@@ Line 122: / Line 147: @@
 if ($cgi->param('task') eq 'selectsession')
 {
-   selectSession($cgi->param('user'), $cgi->param('sid'));
+   selectSessions($cgi->param('user'), $cgi->param('sid'));
 }
- $cgi->hr(),
  $cgi->end_form();
  print $cgi->end_html();
@@ Line 131: / Line 155: @@
 {
       print $cgi->start_form(),
-            $cgi->hr(),
             $cgi->strong('Access denied'),
             $cgi->end_form();
@@ Line 137: / Line 160: @@
 </code>
-SSH broker can be a simple Perl script, which can look like:
+==== 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
@@ Line 150: / Line 176: @@
 my $sid;
-#you don't need to check password on ssh brocker.
+#
-#But possible you steel want to check auth id
+# You don't need to check password on ssh brocker.
+# But possible you still want to check auth id
+#
 #if (!checkAccess($user, $authid) == 1)
 #{
@@ Line 157: / Line 186: @@
 #  exit (0);
 #}
 print "Access granted\n";
 GetOptions('task=s' => \$task,
            'sid=s' => \$sid);
 if(! $task)
 {
     die "parameter --task is required";
 }
 if ($task  eq 'listsessions')
 {
@@ Line 180: / Line 212: @@
    die "task \"".$task."\" not implemented on broker\n";
 }
 sub printNoAccess
 {
@@ Line 185: / Line 218: @@
 }
 </code>
-. How X2Go broker work
-.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. 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.
-.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.
-. 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.

X2Go - everywhere@home

User Tools

Site Tools

Differences

Page Tools