# Python X2Go (Client) API Documentation (v0.6.1.4)

## 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='/sbuild-nonexistent/.x2goclient', sessions_rootdir='/sbuild-nonexistent/.x2go', ssh_rootdir='/sbuild-nonexistent/.ssh', logger=None, loglevel=56, published_applications_no_submenus=0, low_latency=False, **kwargs)

  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)

    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)

    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)

    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()

    Disconnect this control session from the remote server.

    Returns:

      report success or failure after having disconnected

    Return type:

      `bool`

  dissociate(terminal_session)

    Drop an associated terminal session.

    Parameters:

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

  get_hostname()

    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()

    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)

    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()

    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)

    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()

    Test if the remote home directory exists.

    Returns:

      `True` if the home directory exists, `False` otherwise

    Return type:

      `bool`

  is_alive()

    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()

    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)

    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()

    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)

    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)

    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)

    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)

    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)

    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()

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

    If the file does not exist, create it first.

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

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

  remote_peername()

    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()

    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)

    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)

    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)

    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)

    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)

    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)

    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()