User Tools

Site Tools


wiki:development:x2gobroker:plaintexprotocol

Differences

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

Link to this comparison view

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 ====== ====== 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. 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)     - ''​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): 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 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'​);​ 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)=@_;   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 sub checkAccess
 { {
         return 1;         return 1;
 } }
-#​configuration for two sessions+ 
 +# configuration for our two session profiles 
 sub listSessions sub listSessions
 { {
   my $user=shift;​   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>​ <​code>​
 #​!/​usr/​bin/​perl #​!/​usr/​bin/​perl
Line 96: Line 121:
 my @formValues = $cgi->​param();​ my @formValues = $cgi->​param();​
  
-print $cgi->​header(-type ​   =>'​text/​html',+print $cgi->​header(-type ​   =>'​text/​plain',
                          ​-expires =>'​+1h'​),​                          ​-expires =>'​+1h'​),​
       $cgi->​start_html( ​ -title ​  ​=>'​X2Go Broker',​       $cgi->​start_html( ​ -title ​  ​=>'​X2Go Broker',​
Line 122: Line 147:
 if ($cgi->​param('​task'​) eq '​selectsession'​) 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();​  ​$cgi->​end_form();​
  print $cgi->​end_html();​  print $cgi->​end_html();​
Line 131: Line 155:
 { {
       print $cgi->​start_form(),​       print $cgi->​start_form(),​
-            $cgi->​hr(),​ 
             $cgi->​strong('​Access denied'​),​             $cgi->​strong('​Access denied'​),​
             $cgi->​end_form();​             $cgi->​end_form();​
Line 137: Line 160:
 </​code>​ </​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>​ <​code>​
 #​!/​usr/​bin/​perl #​!/​usr/​bin/​perl
Line 150: Line 176:
 my $sid; 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) #if (!checkAccess($user,​ $authid) == 1)
 #{ #{
Line 157: Line 186:
 #  exit (0); #  exit (0);
 #} #}
 +
 print "​Access granted\n";​ print "​Access granted\n";​
 GetOptions('​task=s'​ => \$task, GetOptions('​task=s'​ => \$task,
            '​sid=s'​ => \$sid);            '​sid=s'​ => \$sid);
 +
 if(! $task) if(! $task)
 { {
     die "​parameter --task is required";​     die "​parameter --task is required";​
 } }
 +
 if ($task ​ eq '​listsessions'​) if ($task ​ eq '​listsessions'​)
 { {
Line 180: Line 212:
    die "task \""​.$task."​\"​ not implemented on broker\n";​    die "task \""​.$task."​\"​ not implemented on broker\n";​
 } }
 +
 sub printNoAccess sub printNoAccess
 { {
Line 185: Line 218:
 } }
 </​code>​ </​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. 
- 
- 
  
  
wiki/development/x2gobroker/plaintexprotocol.txt · Last modified: 2013/03/27 15:48 by sunweaver