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: paramiko.client.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 hostname

  • port (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 parameters add_to_known_hosts, force_password_auth, session_instance and all SSH proxy related parameters have been added as X2Go specific parameters

The 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 (see set_missing_host_key_policy). The default policy is to reject the key and raise an SSHException.

Authentication is attempted in the following order of priority:

  • The pkey or key_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 to

  • port (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 to True to enable searching for discoverable private key files in ~/.ssh/ (Default value = False)

  • allow_agent (bool) – set to True to enable connecting to a local SSH agent for acquiring authentication information (Default value = False)

  • add_to_known_hosts (bool) – non-paramiko option, if True paramiko.AutoAddPolicy() is used as missing-host-key-policy. If set to False paramiko.RejectPolicy() is used (Default value = None)

  • force_password_auth (bool) – non-paramiko option, disable pub/priv key authentication completely, even if the pkey or the key_filename parameter is given (Default value = False)

  • session_instance (obj) – an instance x2go.session.X2GoSession using this x2go.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 given sshproxy_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 to True to enable connecting to a local SSH agent for acquiring authentication information (for SSH proxy authentication) (Default value = False)

  • sshproxy_allow_agent (bool) – set to True 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 a list of dict elements. Each dict elements has a desktop key containing a shortened version of the text output of a .desktop file and an icon 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 return None.

Parameters

session_name (str) – X2Go name of the session to be queried

Returns

X2Go session has terminated?

Return type

bool or None

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 the list_sessions() method then None is returned

Return type

bool or None

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 the list_sessions() method then None is returned

Return type

bool or None

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) – if True, the raw output of the server-side X2Go command x2golistdesktops 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 for

  • raw (bool) – if True, the raw output of the server-side X2Go command x2golistmounts is returned. (Default value = False)

  • maxwait (int) – stop processing x2golistmounts 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) – if True, the raw output of the server-side X2Go command x2golistsessions 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-side x2golistsessions 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 the X2GoTerminalSession* 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_desktop(desktop=None, user=None, display=None, share_mode=0, **kwargs)[source]

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 and dislpay 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 the X2GoTerminalSession backend class constructors.

Parameters

kwargs (dict) – parameters that get passed through to the control session’s resume() method, only the session_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 terminated

  • destroy_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

test_sftpclient()[source]