x2go.backends.control.plain module¶
x2go.backends.control.plain.X2GoControlSession
class - core functions for handling your individual X2Go sessions.
This backend handles X2Go server implementations that respond via server-side PLAIN text output.
- class x2go.backends.control.plain.X2GoControlSession(profile_name='UNKNOWN', add_to_known_hosts=False, known_hosts=None, forward_sshagent=False, unique_hostkey_aliases=False, terminal_backend='PLAIN', info_backend='PLAIN', list_backend='PLAIN', proxy_backend='NX3', client_rootdir='/builddir/.x2goclient', sessions_rootdir='/builddir/.x2go', ssh_rootdir='/builddir/.ssh', logger=None, loglevel=56, published_applications_no_submenus=0, low_latency=False, **kwargs)[source]¶
Bases:
SSHClient
In the Python X2Go concept, X2Go sessions fall into two parts: a control session and one to many terminal sessions.
The control session handles the SSH based communication between server and client. It is mainly derived from
paramiko.SSHClient
and adds on X2Go related functionality.- check_host(hostname, port=22)[source]¶
Wraps around a Paramiko/SSH host key check.
- Parameters:
hostname (
str
) – the remote X2Go server’s hostnameport (
int
) – the SSH port of the remote X2Go server (Default value = 22)
- Returns:
True
if the host key check succeeded,False
otherwise- Return type:
bool
- clean_sessions(destroy_terminals=True, published_applications=False)[source]¶
Find X2Go terminals that have previously been started by the connected user on the remote X2Go server and terminate them.
- Parameters:
destroy_terminals (
bool
) – destroy the terminal session instances after cleanup (Default value = True)published_applications (
bool
) – also clean up published applications providing sessions (Default value = False)
- connect(hostname, port=22, username=None, password=None, passphrase=None, pkey=None, key_filename=None, timeout=None, allow_agent=False, look_for_keys=False, use_sshproxy=False, sshproxy_host=None, sshproxy_port=22, sshproxy_user=None, sshproxy_password=None, sshproxy_force_password_auth=False, sshproxy_key_filename=None, sshproxy_pkey=None, sshproxy_look_for_keys=False, sshproxy_passphrase='', sshproxy_allow_agent=False, sshproxy_tunnel=None, add_to_known_hosts=None, forward_sshagent=None, unique_hostkey_aliases=None, force_password_auth=False, session_instance=None)[source]¶
Connect to an X2Go server and authenticate to it. This method is directly inherited from the
paramiko.SSHClient
class. The features of the Paramiko SSH client connect method are recited here. The parametersadd_to_known_hosts
,force_password_auth
,session_instance
and all SSH proxy related parameters have been added as X2Go specific parametersThe server’s host key is checked against the system host keys (see
load_system_host_keys
) and any local host keys (load_host_keys
). If the server’s hostname is not found in either set of host keys, the missing host key policy is used (seeset_missing_host_key_policy
). The default policy is to reject the key and raise anSSHException
.Authentication is attempted in the following order of priority:
The
pkey
orkey_filename
passed in (if any)Any key we can find through an SSH agent
Any “id_rsa” or “id_dsa” key discoverable in
~/.ssh/
Plain username/password auth, if a password was given
If a private key requires a password to unlock it, and a password is passed in, that password will be used to attempt to unlock the key.
- Parameters:
hostname (
str
) – the server to connect toport (
int
) – the server port to connect to (Default value = 22)username (
str
) – the username to authenticate as (defaults to the current local username)password (
str
) – a password to use for authentication or for unlocking a private key (Default value = None)passphrase (
str
) – a passphrase to use for unlocking a private key in case the password is already needed for two-factor authentication (Default value = None)key_filename (
str
or list(str)) – the filename, or list of filenames, of optional private key(s) to try for authentication (Default value = None)pkey (
PKey
) – an optional private key to use for authentication (Default value = None)forward_sshagent (
bool
) – forward SSH agent authentication requests to the X2Go client-side (will update the class property of the same name) (Default value = None)unique_hostkey_aliases (
bool
) – update the unique_hostkey_aliases class property (Default value = None)timeout (float) – an optional timeout (in seconds) for the TCP connect (Default value = None)
look_for_keys (
bool
) – set toTrue
to enable searching for discoverable private key files in~/.ssh/
(Default value = False)allow_agent (
bool
) – set toTrue
to enable connecting to a local SSH agent for acquiring authentication information (Default value = False)add_to_known_hosts (
bool
) – non-paramiko option, ifTrue
paramiko.AutoAddPolicy() is used as missing-host-key-policy. If set toFalse
paramiko.RejectPolicy() is used (Default value = None)force_password_auth (
bool
) – non-paramiko option, disable pub/priv key authentication completely, even if thepkey
or thekey_filename
parameter is given (Default value = False)session_instance (
obj
) – an instancex2go.session.X2GoSession
using thisx2go.backends.control.plain.X2GoControlSession
instance. (Default value = None)use_sshproxy (
True
if an SSH proxy is to be used for tunneling the connection) – connect through an SSH proxy (Default value = False)sshproxy_host (
str
) – hostname of the SSH proxy server (Default value = None)sshproxy_port (
int
) – port of the SSH proxy server (Default value = 22)sshproxy_user (
str
) – username that we use for authenticating against<sshproxy_host>
(Default value = None)sshproxy_password (
str
) – a password to use for SSH proxy authentication or for unlocking a private key (Default value = None)sshproxy_passphrase (
str
) – a passphrase to use for unlocking a private key needed for the SSH proxy host in case the sshproxy_password is already needed for two-factor authentication (Default value = ‘’)sshproxy_force_password_auth (
bool
) – enforce using a givensshproxy_password
even if a key(file) is given (Default value = False)sshproxy_key_filename (
str
) – local file location of the private key file (Default value = None)sshproxy_pkey (
PKey
) – an optional private key to use for SSH proxy authentication (Default value = None)sshproxy_look_for_keys (
bool
) – set toTrue
to enable connecting to a local SSH agent for acquiring authentication information (for SSH proxy authentication) (Default value = False)sshproxy_allow_agent (
bool
) – set toTrue
to enable connecting to a local SSH agent for acquiring authentication information (for SSH proxy authentication) (Default value = False)sshproxy_tunnel (
str
) – the SSH proxy tunneling parameters, format is: <local-address>:<local-port>:<remote-address>:<remote-port> (Default value = None)
- Returns:
True
if an authenticated SSH transport could be retrieved by this method- Return type:
bool
- Raises:
BadHostKeyException – if the server’s host key could not be verified
AuthenticationException – if authentication failed
SSHException – if there was any other error connecting or establishing an SSH session
socket.error – if a socket error occurred while connecting
X2GoSSHProxyException – any SSH proxy exception is passed through while establishing the SSH proxy connection and tunneling setup
X2GoSSHAuthenticationException – any SSH proxy authentication exception is passed through while establishing the SSH proxy connection and tunneling setup
X2GoRemoteHomeException – if the remote home directory does not exist or is not accessible
X2GoControlSessionException – if the remote peer has died unexpectedly
- disconnect()[source]¶
Disconnect this control session from the remote server.
- Returns:
report success or failure after having disconnected
- Return type:
bool
- dissociate(terminal_session)[source]¶
Drop an associated terminal session.
- Parameters:
terminal_session (
X2GoTerminalSession*
) – the terminal session object to remove from the list of associated terminals
- get_hostname()[source]¶
Get the hostname as stored in the properties of this control session.
- Returns:
the hostname of the connected X2Go server
- Return type:
str
- get_port()[source]¶
Get the port number of the SSH connection as stored in the properties of this control session.
- Returns:
the server-side port number of the control session’s SSH connection
- Return type:
str
- get_published_applications(lang=None, refresh=False, raw=False, very_raw=False, max_no_submenus=10)[source]¶
Retrieve the menu tree of published applications from the remote X2Go server.
The
raw
option lets this method return alist
ofdict
elements. Eachdict
elements has adesktop
key containing a shortened version of the text output of a .desktop file and anicon
key which contains the desktop base64-encoded icon data.The {very_raw} lets this method return the output of the
x2gogetapps
script as is.- Parameters:
lang (
str
) – locale/language identifier (Default value = None)refresh (
bool
) – force reload of the menu tree from X2Go server (Default value = False)raw (
bool
) – retrieve a raw output of the server list of published applications (Default value = False)very_raw (
bool
) – retrieve a very raw output of the server list of published applications (Default value = False)max_no_submenus (
int
) – Number of applications before applications are put into XDG category submenus (Default value = defaults.PUBAPP_MAX_NO_SUBMENUS)
- Returns:
an i18n capable menu tree packed as a Python dictionary
- Return type:
list
- get_server_features(force=False)¶
Do a query for the server-side list of X2Go features.
- Parameters:
force (
bool
) – do not use the cached feature list, really ask the server (again) (Default value = False)- Returns:
list of X2Go feature names
- Return type:
list
- get_server_versions(force=False)¶
Do a query for the server-side list of X2Go components and their versions.
- Parameters:
force (
bool
) – do not use the cached component list, really ask the server (again) (Default value = False)- Returns:
dictionary of X2Go components (as keys) and their versions (as values)
- Return type:
list
- has_session_died()[source]¶
Test if the connection to the remote X2Go server died on the way.
- Returns:
True
if the connection has died,False
otherwise- Return type:
bool
- has_terminated(session_name)[source]¶
Returns
True
if the X2Go session with name<session_name>
has been seen by this control session and–in the meantime–has been terminated.If
<session_name>
has not been seen, yet, the method will returnNone
.- Parameters:
session_name (
str
) – X2Go name of the session to be queried- Returns:
X2Go session has terminated?
- Return type:
bool
orNone
- home_exists()[source]¶
Test if the remote home directory exists.
- Returns:
True
if the home directory exists,False
otherwise- Return type:
bool
- is_alive()[source]¶
Test if the connection to the remote X2Go server is still alive.
- Returns:
True
if the connection is still alive,False
otherwise- Return type:
bool
- is_connected()[source]¶
Returns
True
if this control session is connected to the remote server (that is: if it has a valid Paramiko/SSH transport object).- Returns:
X2Go session connected?
- Return type:
bool
- is_running(session_name)[source]¶
Returns
True
if the given X2Go session is in running state,False
else.- Parameters:
session_name (
str
) – X2Go name of the session to be queried- Returns:
X2Go session running? If
<session_name>
is not listable by thelist_sessions()
method thenNone
is returned- Return type:
bool
orNone
- is_sshfs_available()[source]¶
Check if the remote user is allowed to use SSHFS mounts.
- Returns:
True
if the user is allowed to connect client-side shares to the X2Go session- Return type:
bool
- is_suspended(session_name)[source]¶
Returns
True
if the given X2Go session is in suspended state,False
else.- Parameters:
session_name (
str
) – X2Go name of the session to be queried- Returns:
X2Go session suspended? If
<session_name>
is not listable by thelist_sessions()
method thenNone
is returned- Return type:
bool
orNone
- is_x2gouser(username)[source]¶
Is the remote user allowed to launch X2Go sessions?
FIXME: this method is currently non-functional.
- Parameters:
username (
str
) – remote user name- Returns:
True
if the remote user is allowed to launch X2Go sessions- Return type:
bool
- list_desktops(raw=False, maxwait=20)[source]¶
List all desktop-like sessions of current user (or of users that have granted desktop sharing) on the connected server.
- Parameters:
raw (
bool
) – ifTrue
, the raw output of the server-side X2Go commandx2golistdesktops
is returned. (Default value = False)maxwait (
int
) – time in secs to wait for server query to reply (Default value = 20)
- Returns:
a list of X2Go desktops available for sharing
- Return type:
list
- Raises:
X2GoTimeOutException – on command execution timeouts, with the server-side
x2golistdesktops
command this can sometimes happen. Make sure you ignore these time-outs and to try again
- list_mounts(session_name, raw=False, maxwait=20)[source]¶
List all mounts for a given session of the current user on the connected server.
- Parameters:
session_name (
str
) – name of a session to query a list of mounts forraw (
bool
) – ifTrue
, the raw output of the server-side X2Go commandx2golistmounts
is returned. (Default value = False)maxwait (
int
) – stop processingx2golistmounts
after<maxwait>
seconds (Default value = 20)
- Returns:
a list of client-side mounts for X2Go session
<session_name>
on the server- Return type:
list
- Raises:
X2GoTimeOutException – on command execution timeouts, queries with the server-side
x2golistmounts
query should normally be processed quickly, a time-out may hint that the control session has lost its connection to the X2Go server
- list_sessions(raw=False)[source]¶
List all sessions of current user on the connected server.
- Parameters:
raw (
bool
) – ifTrue
, the raw output of the server-side X2Go commandx2golistsessions
is returned. (Default value = False)- Returns:
normally an instance of a
X2GoServerSessionList*
backend is returned. However, if the raw argument is set, the plain text output of the server-sidex2golistsessions
command is returned- Return type:
X2GoServerSessionList
instance or str- Raises:
X2GoControlSessionException – on command execution timeouts, if this happens the control session will be interpreted as disconnected due to connection loss
- load_session_host_keys()[source]¶
Load known SSH host keys from the
known_hosts
file.If the file does not exist, create it first.
- query_server_features(force=False)[source]¶
Do a query for the server-side list of X2Go features.
- Parameters:
force (
bool
) – do not use the cached feature list, really ask the server (again) (Default value = False)- Returns:
list of X2Go feature names
- Return type:
list
- query_server_versions(force=False)[source]¶
Do a query for the server-side list of X2Go components and their versions.
- Parameters:
force (
bool
) – do not use the cached component list, really ask the server (again) (Default value = False)- Returns:
dictionary of X2Go components (as keys) and their versions (as values)
- Return type:
list
- remote_peername()[source]¶
Returns (and caches) the control session’s remote host (name or ip).
- Returns:
SSH transport’s peer name
- Return type:
tuple
- Raises:
X2GoControlSessionException – on SSH connection loss
- remote_username()[source]¶
Returns (and caches) the control session’s remote username.
- Returns:
SSH transport’s user name
- Return type:
str
- Raises:
X2GoControlSessionException – on SSH connection loss
- resume(session_name=None, session_instance=None, session_list=None, **kwargs)[source]¶
Resume a running/suspended X2Go session.
The
X2GoControlSession.resume()
method accepts any parameter that can be passed to any of theX2GoTerminalSession*
backend class constructors.- Parameters:
session_name (
str
) – the X2Go session name (Default value = None)session_instance (
x2go.session.X2GoSession
) – a Python X2Go session instance (Default value = None)session_list – Default value = None)
kwargs (
dict
) – catch any non-defined param in kwargs
- Returns:
True if the session could be successfully resumed
- Return type:
bool
- Raises:
X2GoUserException – if the remote user is not allowed to launch/resume X2Go sessions.
- set_profile_name(profile_name)[source]¶
Manipulate the control session’s profile name.
- Parameters:
profile_name (
str
) – new profile name for this control session
Share another already running desktop session. Desktop sharing can be run in two different modes: view-only and full-access mode.
- Parameters:
desktop (
str
) – desktop ID of a sharable desktop in format<user>@<display>
(Default value = None)user (
str
) – user name and display number can be given separately, here give the name of the user who wants to share a session with you (Default value = None)display (
str
) – user name and display number can be given separately, here give the number of the display that a user allows you to be shared with (Default value = None)share_mode (
int
) – desktop sharing mode, 0 stands for VIEW-ONLY, 1 for FULL-ACCESS mode (Default value = 0)kwargs (
dict
) – catch any non-defined param in kwargs
- Returns:
True if the session could be successfully shared
- Return type:
bool
- Raises:
X2GoDesktopSharingException – if
username
anddislpay
do not relate to a sharable desktop session
- start(**kwargs)[source]¶
Start a new X2Go session.
The
X2GoControlSession.start()
method accepts any parameter that can be passed to any of theX2GoTerminalSession
backend class constructors.- Parameters:
kwargs (
dict
) – parameters that get passed through to the control session’sresume()
method, only thesession_name
parameter will get removed before pass-through- Returns:
return: return value of the cascaded
resume()
method, denoting the success or failure of the session startup- Return type:
bool
- suspend(session_name)[source]¶
Suspend X2Go session with name
<session_name>
on the connected server.- Parameters:
session_name (
str
) – X2Go name of the session to be suspended- Returns:
True
if the session could be successfully suspended- Return type:
bool
- terminate(session_name, destroy_terminals=True)[source]¶
Terminate X2Go session with name
<session_name>
on the connected server.- Parameters:
session_name (
str
) – X2Go name of the session to be terminateddestroy_terminals (
bool
) – destroy all terminal sessions associated to this control session (Default value = True)
- Returns:
True
if the session could be successfully terminated- Return type:
bool