Package x2go :: Package backends :: Package control :: Module plain :: Class X2GoControlSession

[frames] | no frames]

# Class X2GoControlSession

source code

                             object --+
                                      |
    paramiko.util.ClosingContextManager --+
                                          |
                  paramiko.client.SSHClient --+
                                              |
                                             X2GoControlSession

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.

Instance Methods

__init__(self, 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=`'``/home/buildd/.x2goclient``'`, sessions_rootdir=`'``/home/buildd/.x2go``'`, ssh_rootdir=`'``/home/buildd/.ssh``'`, logger=None, loglevel=56, published_applications_no_submenus=0, low_latency=False, **kwargs)
Initialize an X2Go control session.

source code

`str`

get_hostname(self) Get the hostname as stored in the properties of this control session. | source code

`str`

get_port(self) Get the port number of the SSH connection as stored in the properties of this control session. | source code

load_session_host_keys(self) Load known SSH host keys from the `known_hosts` file. | source code

__del__(self) On instance descruction, do a proper session disconnect from the server. | source code

test_sftpclient(self) | source code

`list`

query_server_versions(self, force=False) Do a query for the server-side list of X2Go components and their versions. | source code

`list`

get_server_versions(self, force=False) Do a query for the server-side list of X2Go components and their versions. | source code

`list`

query_server_features(self, force=False) Do a query for the server-side list of X2Go features. | source code

`list`

get_server_features(self, force=False) Do a query for the server-side list of X2Go features. | source code

`bool`

is_x2gouser(self, username) Is the remote user allowed to launch X2Go sessions? | source code

`bool`

is_sshfs_available(self) Check if the remote user is allowed to use SSHFS mounts. | source code

`str`

remote_username(self) Returns (and caches) the control session's remote username. | source code

`tuple`

remote_peername(self) Returns (and caches) the control session's remote host (name or ip). | source code

set_profile_name(self, profile_name) Manipulate the control session's profile name. | source code

`bool`

check_host(self, hostname, port=22) Wraps around a Paramiko/SSH host key check. | source code

`bool`

connect(self, 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)
Connect to an X2Go server and authenticate to it.

source code

dissociate(self, terminal_session) Drop an associated terminal session. | source code

`bool`

disconnect(self) Disconnect this control session from the remote server. | source code

`bool`

home_exists(self) Test if the remote home directory exists. | source code

`bool`

is_alive(self) Test if the connection to the remote X2Go server is still alive. | source code

`bool`

has_session_died(self) Test if the connection to the remote X2Go server died on the way. | source code

`list`

get_published_applications(self, lang=None, refresh=False, raw=False, very_raw=False, max_no_submenus=10) Retrieve the menu tree of published applications from the remote X2Go server. | source code

`bool`

start(self, **kwargs) Start a new X2Go session. | source code

`bool`

resume(self, session_name=None, session_instance=None, session_list=None, **kwargs) Resume a running/suspended X2Go session. | source code

`bool`

share_desktop(self, desktop=None, user=None, display=None, share_mode=0, **kwargs) Share another already running desktop session. | source code

`list`

list_desktops(self, raw=False, maxwait=20) List all desktop-like sessions of current user (or of users that have granted desktop sharing) on the connected server. | source code

`list`

list_mounts(self, session_name, raw=False, maxwait=20) List all mounts for a given session of the current user on the connected server. | source code

`X2GoServerSessionList` instance or str

list_sessions(self, raw=False) List all sessions of current user on the connected server. | source code

clean_sessions(self, destroy_terminals=True, published_applications=False) Find X2Go terminals that have previously been started by the connected user on the remote X2Go server and terminate them. | source code

`bool`

is_connected(self) Returns `True` if this control session is connected to the remote server (that is: if it has a valid Paramiko/SSH transport object). | source code

`bool` or `None`

is_running(self, session_name) Returns `True` if the given X2Go session is in running state, `False` else. | source code

`bool` or `None`

is_suspended(self, session_name) Returns `True` if the given X2Go session is in suspended state, `False` else. | source code

`bool` or `None`

has_terminated(self, session_name) Returns `True` if the X2Go session with name `<session_name>` has been seen by this control session and--in the meantime--has been terminated. | source code

`bool`

suspend(self, session_name) Suspend X2Go session with name `<session_name>` on the connected server. | source code

`bool`

terminate(self, session_name, destroy_terminals=True) Terminate X2Go session with name `<session_name>` on the connected server. | source code

Inherited from `paramiko.client.SSHClient`: `close`, `exec_command`, `get_host_keys`, `get_transport`, `invoke_shell`, `load_host_keys`, `load_system_host_keys`, `open_sftp`, `save_host_keys`, `set_log_channel`, `set_missing_host_key_policy`

Inherited from `paramiko.util.ClosingContextManager`: `__enter__`, `__exit__`

Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__sizeof__`, `__str__`, `__subclasshook__`

Properties
Inherited from `object`: `__class__`

Method Details

### __init__(self, 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=`'``/home/buildd/.x2goclient``'`, sessions_rootdir=`'``/home/buildd/.x2go``'`, ssh_rootdir=`'``/home/buildd/.ssh``'`, logger=None, loglevel=56, published_applications_no_submenus=0, low_latency=False, **kwargs)
(Constructor)

source code

Initialize an X2Go control session. For each connected session profile there will be one SSH-based control session and one to many terminal sessions that all server-client-communicate via this one common control session.

A control session normally gets set up by an X2GoSession instance. Do not use it directly!!!

Parameters:
  - `profile_name` (`str`) - the profile name of the session profile this control session works for
  - `add_to_known_hosts` (`bool`) - Auto-accept server host validity?
  - `known_hosts` (`str`) - the underlying Paramiko/SSH systems `known_hosts` file
  - `forward_sshagent` (`bool`) - forward SSH agent authentication requests to the X2Go client-side
  - `unique_hostkey_aliases` (`bool`) - instead of storing [<hostname>]:<port> in known_hosts file, use the (unique-by-design) profile ID
  - `terminal_backend` (`str`) - X2Go terminal session backend to use
  - `info_backend` (`X2GoServerSessionInfo*` instance) - backend for handling storage of server session information
  - `list_backend` (`X2GoServerSessionList*` instance) - backend for handling storage of session list information
  - `proxy_backend` (`X2GoProxy*` instance) - backend for handling the X-proxy connections
  - `client_rootdir` (`str`) - client base dir (default: ~/.x2goclient)
  - `sessions_rootdir` (`str`) - sessions base dir (default: ~/.x2go)
  - `ssh_rootdir` (`str`) - ssh base dir (default: ~/.ssh)
  - `published_applications_no_submenus` (`int`) - published applications menus with less items than `published_applications_no_submenus` are rendered without submenus
  - `logger` (X2GoLogger instance) - you can pass an X2GoLogger object to the X2GoControlSession constructor
  - `loglevel` (`int`) - if no X2GoLogger object has been supplied a new one will be constructed with the given loglevel
  - `low_latency` (`bool`) - set this boolean switch for weak connections, it will double all timeout values.
  - `kwargs` (`dict`) - catch any non-defined parameters in `kwargs`
Overrides: object.__init__

### get_hostname(self)

source code

Get the hostname as stored in the properties of this control session.

Returns: `str`
  the hostname of the connected X2Go server

### get_port(self)

source code

Get the port number of the SSH connection as stored in the properties of this control session.

Returns: `str`
  the server-side port number of the control session's SSH connection

### load_session_host_keys(self)

source code

Load known SSH host keys from the `known_hosts` file.

If the file does not exist, create it first.

### query_server_versions(self, force=False)

source code

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)
Returns: `list`
  dictionary of X2Go components (as keys) and their versions (as values)

### get_server_versions(self, force=False)

source code

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)
Returns: `list`
  dictionary of X2Go components (as keys) and their versions (as values)

### query_server_features(self, force=False)

source code

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)
Returns: `list`
  list of X2Go feature names

### get_server_features(self, force=False)

source code

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)
Returns: `list`
  list of X2Go feature names

### is_x2gouser(self, username)

source code

Is the remote user allowed to launch X2Go sessions?

FIXME: this method is currently non-functional.

Parameters:
  - `username` (`str`) - remote user name
Returns: `bool`
  `True` if the remote user is allowed to launch X2Go sessions

### is_sshfs_available(self)

source code

Check if the remote user is allowed to use SSHFS mounts.

Returns: `bool`
  `True` if the user is allowed to connect client-side shares to the X2Go session

### remote_username(self)

source code

Returns (and caches) the control session's remote username.

Returns: `str`
  SSH transport's user name
Raises:
  - `X2GoControlSessionException` - on SSH connection loss

### remote_peername(self)

source code

Returns (and caches) the control session's remote host (name or ip).

Returns: `tuple`
  SSH transport's peer name
Raises:
  - `X2GoControlSessionException` - on SSH connection loss

### set_profile_name(self, profile_name)

source code

Manipulate the control session's profile name.

Parameters:
  - `profile_name` (`str`) - new profile name for this control session

### check_host(self, hostname, port=22)

source code

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
Returns: `bool`
  `True` if the host key check succeeded, `False` otherwise

### connect(self, 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 code

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
  - `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
  - `passphrase` (`str`) - a passphrase to use for unlocking a private key in case the password is already needed for two-factor authentication
  - `key_filename` (`str` or list(str)) - the filename, or list of filenames, of optional private key(s) to try for authentication
  - `pkey` (`PKey`) - an optional private key to use for authentication
  - `forward_sshagent` (`bool`) - forward SSH agent authentication requests to the X2Go client-side (will update the class property of the same name)
  - `unique_hostkey_aliases` (`bool`) - update the unique_hostkey_aliases class property
  - `timeout` (float) - an optional timeout (in seconds) for the TCP connect
  - `look_for_keys` (`bool`) - set to `True` to enable searching for discoverable private key files in `~/.ssh/`
  - `allow_agent` (`bool`) - set to `True` to enable connecting to a local SSH agent for acquiring authentication information
  - `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
  - `force_password_auth` (`bool`) - non-paramiko option, disable pub/priv key authentication completely, even if the `pkey` or the `key_filename` parameter is given
  - `session_instance` (`obj`) - an instance X2GoSession using this X2GoControlSession instance.
  - `use_sshproxy` (`True` if an SSH proxy is to be used for tunneling the connection) - connect through an SSH proxy
  - `sshproxy_host` (`str`) - hostname of the SSH proxy server
  - `sshproxy_port` (`int`) - port of the SSH proxy server
  - `sshproxy_user` (`str`) - username that we use for authenticating against `<sshproxy_host>`
  - `sshproxy_password` (`str`) - a password to use for SSH proxy authentication or for unlocking a private key
  - `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
  - `sshproxy_force_password_auth` (`bool`) - enforce using a given `sshproxy_password` even if a key(file) is given
  - `sshproxy_key_filename` (`str`) - local file location of the private key file
  - `sshproxy_pkey` (`PKey`) - an optional private key to use for SSH proxy authentication
  - `sshproxy_look_for_keys` (`bool`) - set to `True` to enable connecting to a local SSH agent for acquiring authentication information (for SSH proxy authentication)
  - `sshproxy_allow_agent` (`bool`) - set to `True` to enable connecting to a local SSH agent for acquiring authentication information (for SSH proxy authentication)
  - `sshproxy_tunnel` (`str`) - the SSH proxy tunneling parameters, format is: <local-address>:<local-port>:<remote-address>:<remote-port>
Returns: `bool`
  `True` if an authenticated SSH transport could be retrieved by this method
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 event unexpectedly
Overrides: paramiko.client.SSHClient.connect

### dissociate(self, terminal_session)

source code

Drop an associated terminal session.

Parameters:
  - `terminal_session` (`X2GoTerminalSession*`) - the terminal session object to remove from the list of associated terminals

### disconnect(self)

source code

Disconnect this control session from the remote server.

Returns: `bool`
  report success or failure after having disconnected

### home_exists(self)

source code

Test if the remote home directory exists.

Returns: `bool`
  `True` if the home directory exists, `False` otherwise

### is_alive(self)

source code

Test if the connection to the remote X2Go server is still alive.

Returns: `bool`
  `True` if the connection is still alive, `False` otherwise

### has_session_died(self)

source code

Test if the connection to the remote X2Go server died on the way.

Returns: `bool`
  `True` if the connection has died, `False` otherwise

### get_published_applications(self, lang=None, refresh=False, raw=False, very_raw=False, max_no_submenus=10)

source code

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
  - `refresh` (`bool`) - force reload of the menu tree from X2Go server
  - `raw` (`bool`) - retrieve a raw output of the server list of published applications
  - `very_raw` (`bool`) - retrieve a very raw output of the server list of published applications
Returns: `list`
  an i18n capable menu tree packed as a Python dictionary

### start(self, **kwargs)

source code

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: `bool`
  return value of the cascaded resume() method, denoting the success or failure of the session startup

### resume(self, session_name=None, session_instance=None, session_list=None, **kwargs)

source code

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.

Returns: `bool`
  True if the session could be successfully resumed
Raises:
  - `X2GoUserException` - if the remote user is not allowed to launch/resume X2Go sessions.

### share_desktop(self, desktop=None, user=None, display=None, share_mode=0, **kwargs)

source code

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>`
  - `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
  - `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
  - `share_mode` (`int`) - desktop sharing mode, 0 stands for VIEW-ONLY, 1 for FULL-ACCESS mode
Returns: `bool`
  True if the session could be successfully shared
Raises:
  - `X2GoDesktopSharingException` - if `username` and `dislpay` do not relate to a sharable desktop session

### list_desktops(self, raw=False, maxwait=20)

source code

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.
Returns: `list`
  a list of X2Go desktops available for sharing
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(self, session_name, raw=False, maxwait=20)

source code

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.
  - `maxwait` (`int`) - stop processing `x2golistmounts` after `<maxwait>` seconds
Returns: `list`
  a list of client-side mounts for X2Go session `<session_name>` on the server
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(self, raw=False)

source code

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.
Returns: `X2GoServerSessionList` instance or str
  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
Raises:
  - `X2GoControlSessionException` - on command execution timeouts, if this happens the control session will be interpreted as disconnected due to connection loss

### clean_sessions(self, destroy_terminals=True, published_applications=False)

source code

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
  - `published_applications` (`bool`) - also clean up published applications providing sessions

### is_connected(self)

source code

Returns `True` if this control session is connected to the remote server (that is: if it has a valid Paramiko/SSH transport object).

Returns: `bool`
  X2Go session connected?

### is_running(self, session_name)

source code

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: `bool` or `None`
  X2Go session running? If `<session_name>` is not listable by the list_sessions() method then `None` is returned

### is_suspended(self, session_name)

source code

Returns `True` if the given X2Go session is in suspended state, `False` else.

Returns: `bool` or `None`
  X2Go session suspended? If `<session_name>` is not listable by the list_sessions() method then `None` is returned

### has_terminated(self, session_name)

source code

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`.

Returns: `bool` or `None`
  X2Go session has terminated?

### suspend(self, session_name)

source code

Suspend X2Go session with name `<session_name>` on the connected server.

Parameters:
  - `session_name` (`str`) - X2Go name of the session to be suspended
Returns: `bool`
  `True` if the session could be successfully suspended

### terminate(self, session_name, destroy_terminals=True)

source code

Terminate X2Go session with name `<session_name>` on the connected server.

Parameters:
  - `session_name` (`str`) - X2Go name of the session to be terminated
Returns: `bool`
  `True` if the session could be successfully terminated