gateone.py - Gate One's Main Script

Gate One

Gate One is a web-based terminal emulator written in Python using the Tornado web framework. This module runs the primary daemon process and acts as a central controller for all running terminals and terminal programs. It supports numerous configuration options and can also be called with the --kill switch to kill all running terminal programs (if using dtach--otherwise they die on their own when gateone.py is stopped).

Dependencies

Gate One requires Python 2.6+ but runs best with Python 2.7+. It also depends on the following 3rd party Python modules:

• Tornado 2.1+ - Non-blocking web server framework that powers FriendFeed.

The following modules are optional and can provide Gate One with additional functionality:

• pyOpenSSL 0.10+ - OpenSSL wrapper for Python. Only used to generate self-signed SSL keys and certificates.
• kerberos 1.0+ - A high-level Kerberos interface for Python. Only necessary if you plan to use the Kerberos authentication module.

On most platforms both the required and optional modules can be installed via one of these commands:

user@modern-host:~ $ sudo pip install tornado pyopenssl kerberos

...or:

user@legacy-host:~ $ sudo easy_install tornado pyopenssl kerberos

Note

The use of pip is recommended. See http://www.pip-installer.org/en/latest/installing.html if you don't have it.

Settings

All of Gate One's configurable options can be controlled either via command line switches or by settings in the server.conf file (they match up 1-to-1). If no server.conf exists one will be created using defaults (i.e. when Gate One is run for the first time). Settings in the server.conf file use the following format:

<setting> = <value>

Here's an example:

address = "0.0.0.0" # Strings are surrounded by quotes
port = 443 # Numbers don't need quotes

There are a few important differences between the configuration file and command line switches in regards to boolean values (True/False). A switch such as --debug evaluates to "debug = True" and this is exactly how it would be configured in server.conf:

debug = True # Booleans don't need quotes either

Note

server.conf is case sensitive for "True", "False" and "None".

Running gateone.py with the --help switch will print the usage information as well as descriptions of what each configurable option does:

root@host:~ $ ./gateone.py --help
Usage: ./gateone.py [OPTIONS]

Options:
  --help                           show this help information
  --log_file_max_size              max size of log files before rollover
  --log_file_num_backups           number of log files to keep
  --log_file_prefix=PATH           Path prefix for log files. Note that if you are running multiple tornado processes, log_file_prefix must be different for each of them (e.g. include the port number)
  --log_to_stderr                  Send log output to stderr (colorized if possible). By default use stderr if --log_file_prefix is not set and no other logging is configured.
  --logging=info|warning|error|none Set the Python log level. If 'none', tornado won't touch the logging configuration.
  --address                        Run on the given address.
  --auth                           Authentication method to use.  Valid options are: none, kerberos, google
  --certificate                    Path to the SSL certificate.  Will be auto-generated if none is provided.
  --command                        Run the given command when a user connects (e.g. 'nethack').
  --cookie_secret                  Use the given 45-character string for cookie encryption.
  --debug                          Enable debugging features such as auto-restarting when files are modified.
  --disable_ssl                    If enabled, Gate One will run without SSL (generally not a good idea).
  --dtach                          Wrap terminals with dtach. Allows sessions to be resumed even if Gate One is stopped and started (which is a sweet feature =).
  --embedded                       Run Gate One in Embedded Mode (no toolbar, only one terminal allowed, etc.  See docs).
  --keyfile                        Path to the SSL keyfile.  Will be auto-generated if none is provided.
  --kill                           Kill any running Gate One terminal processes including dtach'd processes.
  --port                           Run on the given port.
  --session_dir                    Path to the location where session information will be stored.
  --session_logging                If enabled, logs of user sessions will be saved in <user_dir>/logs.  Default: Enabled
  --session_timeout                Amount of time that a session should be kept alive after the client has logged out.  Accepts <num>X where X could be one of s, m, h, or d for seconds, minutes, hours, and days.  Default is '5d' (5 days).
  --sso_realm                      Kerberos REALM (aka DOMAIN) to use when authenticating clients. Only relevant if Kerberos authentication is enabled.
  --sso_service                    Kerberos service (aka application) to use. Defaults to HTTP. Only relevant if Kerberos authentication is enabled.
  --syslog_facility                Syslog facility to use when logging to syslog (if syslog_session_logging is enabled).  Must be one of: auth, cron, daemon, kern, local0, local1, local2, local3, local4, local5, local6, local7, lpr, mail, news, syslog, user, uucp.  Default: daemon
  --syslog_session_logging         If enabled, logs of user sessions will be written to syslog.
  --user_dir                       Path to the location where user files will be stored.

Note

Some of these options (e.g. log_file_prefix) are inherent to the Tornado framework. You won't find them anywhere in gateone.py.

File Paths

Gate One stores its files, temporary session information, and persistent user data in the following locations (Note: Many of these are configurable):

File/Directory	Description
gateone.py	Gate One's primary executable/script. Also, the file containing this documentation
auth.py	Authentication classes
logviewer.py	A utility to view Gate One session logs
server.conf	Gate One's configuration file
sso.py	A Kerberos Single Sign-on module for Tornado (used by auth.py)
terminal.py	A Pure Python terminal emulator module
termio.py	Terminal input/output control module
utils.py	Various supporting functions
docs/	Gate One documentation
static/	Non-dynamic files that get served to clients (e.g. gateone.js, gateone.css, etc)
templates/	Tornado template files such as index.html
tests/	Gate One-specific automated unit/acceptance tests
plugins/	Plugins go here in the form of ./plugins/<plugin name>/<plugin files|directories>
users/	Persistent user data in the form of ./users/<username>/<user-specific files>
users/<user>/logs	This is where session logs get stored if session_logging is set.
/tmp/gateone	Temporary session data in the form of /tmp/gateone/<session ID>/<files>

Running

Executing Gate One is as simple as:

root@host:~ $ ./gateone.py

NOTE: By default Gate One will run on port 443 which requires root on most systems. Use --port=<something greater than 1024> for non-root users.

Plugins

Gate One includes support for any combination of the following types of plugins:

• Python
• JavaScript
• CSS

Python plugins can integrate with Gate One in three ways:

• Adding or overriding tornado.web.RequestHandlers (with a given regex).
• Adding or overriding methods (aka "commands") in TerminalWebSocket.
• Adding special plugin-specific escape sequence handlers (see the plugin development documentation for details on what/how these are/work).

JavaScript plugins will be added to the <body> tag of Gate One's base index.html template like so:

<!-- Begin JS files from plugins -->
{% for jsplugin in jsplugins %}
<script type="text/javascript" src="{{jsplugin}}"></script>
{% end %}
<!-- End JS files from plugins -->

CSS plugins are similar to JavaScript but instead of being appended to the <body> they are added to the <head>:

<!-- Begin CSS files from plugins -->
{% for cssplugin in cssplugins %}
<link rel="stylesheet" href="{{cssplugin}}" type="text/css" media="screen" />
{% end %}
<!-- End CSS files from plugins -->

There are also hooks throughout Gate One's code for plugins to add or override Gate One's functionality. Documentation on how to write plugins can be found in the Plugin Development docs. From the perspective of gateone.py, it performs the following tasks in relation to plugins:

• Imports Python plugins and connects their hooks.
• Creates symbolic links inside ./static/ that point to each plugin's respective /static/ directory and serves them to clients.
• Serves the index.html that includes plugins' respective .js and .css files.

Class Docstrings

class gateone.BaseHandler(application, request, **kwargs)

A base handler that all Gate One RequestHandlers will inherit methods from.

get_current_user()

Tornado standard method--implemented our way.

class gateone.MainHandler(application, request, **kwargs)

Renders index.html which loads Gate One.

Will include the minified version of gateone.js if available as gateone.min.js.

Will encode GATEONE_DIR/static/bell.ogg as a data:URI and put it as the <source> of the <audio> tag inside the index.html template. Gate One administrators can replace bell.ogg with whatever they like but the file size should be less than 32k when encoded to Base64.

class gateone.StyleHandler(application, request, **kwargs)

Serves up our CSS templates (e.g. the 'black' or 'white' schemes)

class gateone.RecordingHandler(application, request, **kwargs)

Handles uploads of session recordings and returns them to the client in a self-contained HTML file that will auto-start playback.

NOTE: The real crux of the code that handles this is in the template.

class gateone.OpenLogHandler(application, request, **kwargs)

Handles uploads of user logs and returns them to the client as a basic HTML page. Essentially, this works around the limitation of an HTML page being unable to save itself =).

class gateone.TidyThread(session)

Kills a user's termio session if the client hasn't updated the keepalive within TIMEOUT (global). Also, tidies up sessions, logs, and whatnot based on Gate One's settings (when the time is right).

NOTE: This is necessary to prevent shells from running eternally in the background.

session - 45-character string containing the user's session ID

keepalive(datetime_obj=None)

Resets the keepalive timer. Typically called when the user performs a new action.

datetime_obj - A datetime object that will be used to measure TIMEOUT against. Will end up defaulting to datetime.now() (if None) which is what you'd want 99% of the time.