.. X2Go Session Broker documentation master file, created by
   sphinx-quickstart on Fri Sep  7 08:45:37 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to X2Go Session Broker's Documentation
==============================================

Brokerage for X2Go is the add-on feature that turns X2Go into a site-wide
configurable desktop solution. With brokerage support, site-admins can...

  * provision X2Go client session profiles on-the-fly via one or more central
    broker servers
  * provision X2Go client session profiles based on user and/or group privileges
  * hook X2Go client into non-PAM, non-SSH authentication mechanisms
  * let X2Go users resume suspended sessions on X2Go server farms
  * etc.

There are many X2Go broker implementations out there, mostly running in
commercial production environments. Mostly highly customized for the
customer that ordered such a broker.

The official **X2Go Session Broker** is the attempt of providing X2Go users
with a generically configurable X2Go broker that is easy to administrate.

This API documentation is about Python X2GoBroker. Python X2GoBroker is
the brainy backend behind X2Go Session Broker. The goal of this API
documentation is to provide enough information for you to allow you
customizing X2Go Session Broker to your needs and also possibly
contribute your code back to the X2Go developers' community.

With this broker approach, we attempt at providing

  (a) a free and quickly-to-use broker for X2Go
  (b) an easy-to-extend piece of Python software that allows
      site admins and/or developers to adapt the current code
      base to their specific use cases
  (c) a brokerage solution hat can be used in production environments

The Concept
-----------

In standalone setups, an X2Go client application knows the session
profiles that the user configure locally (in a file named
``~/.x2goclient/sessions`` (or in the Windows registry, for *X2Go Client
for Windows*).

In brokerage setups, there is one (or more) server(s) that tell the X2Go
client application what X2Go servers and session types are available on
the corporate network.

The **authentication** to an X2Go sessions falls into two parts:

  (1) authentication against the X2Go Session Broker
  (2) authentication against the X2Go Server (where the remote session will be run)

This authentication split-up adds an extra authentication step that we
try to reduce by providing the so-calls broker autologon feature. An X2Go
client that could successfully authenticate against an X2Go Session
Broker is legitimate to launch an X2Go session on attached X2Go servers.
So, the second authentication step (to the actual X2Go Server) can be
handled by the broker internally.

To achieve this, the X2Go Session Broker requires a tool on each attached
X2Go server, the so called **X2Go Broker Agent**. X2Go Session Broker can
ask the X2Go Broker Agent to perform several tasks:

  * temporarily deploy public SSH user keys
  * query X2Go server load factors
  * check, if a remote X2Go server is actually available for login
    (Down for maintenance? Maximum number of users already reached?)
  * query the attached servers, if logging-in broker user already has
    a running (or suspended) session
  * do some extra checks on X2Go Server integrity (site-admin hackable,
    e.g. file systems writeable, home directories mounted, etc.)

Further Information
-------------------

Please do not hesitate to ask for more information. Visit our website [1] or contact the developers [2].

References
----------

  * [1] https://wiki.x2go.org/
  * [2] mailto:x2go-dev@lists.x2go.org

Commercial Support
------------------

Commercial support for the X2Go Session Broker is provided by:

  * DAS-NETZWERKTEAM, Mike Gabriel <mike.gabriel@das-netzwerkteam.de>


Contents
--------

.. toctree::
   :maxdepth: 4

   x2gobroker

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
