1   Introduction

GraphTerm is a browser-based graphical terminal interface, that aims to seamlessly blend the command line and graphical user interfaces. The goal is to provide a fully backwards-compatible terminal emulator for xterm. You should be able to use it just like a regular terminal interface, accessing additional graphical features only as needed. GraphTerm builds upon two earlier projects, XMLTerm which implemented a terminal using the Mozilla framework and AjaxTerm which is an AJAX/Python terminal implementation. (Another recent project along these lines is TermKit.)

A GraphTerm terminal window is just a web page served from the GraphTerm web server program. Multiple users can connect simultaneously to the web server to share terminal sessions. Multiple hosts can also connect to the server (on a different port), allowing a single user to access all of them via the browser. The GraphTerm server acts as a router, sending input from browser windows for different users to the appropriate terminal (pseudo-tty) sessions running on different hosts, and transmitting the terminal output back to the browser windows.

This flexible, networked implementation allows for several possible applications for GraphTerm, such as:

• an enhanced terminal that combines the command line with basic GUI operations like navigating folders, file drag-and-drop, displaying images etc.
• a web-based remote desktop that supports a simple GUI without the need for installing VNC or X-windows on the remote host
• a detachable terminal multiplexer, sort of like GNU screen or tmux
• an inline data visualization tool to view output from plotting libraries like matplotlib
• a collaborative terminal that can be remotely accessed by multiple users simultaneously, to run programs, edit files etc.
• a simple presentation tool for webcasting images as slideshows (and receiving live feedback)
• a management console for a cluster of real or virtual hosts, with wildcard access to hosts/sessions (e.g., to manage a virtual computer lab using cloud instances),

The interface is designed to be touch-friendly for use with tablets, relying upon command re-use to minimize the need for a keyboard. It preserves history for all commands, whether entered by typing, clicking, or tapping. It is also themable using CSS.

Images of GraphTerm in action can be found in screenshots and in this YouTube Video. Here is a sample screenshot illustrating graphical gls and cat command output using a 3D perspective theme (captured on OS X Lion, using Google Chrome).

2   Installation

To install GraphTerm, you need to have Python 2.6+ and the Bash shell on your Mac/Linux/Unix computer. For a quick install, if the python setuptools module is already installed on your system, use the following commands:

sudo easy_install graphterm
sudo gterm_setup

(If setuptools is not installed, consider installing it using apt-get install -y python-setuptools on Debian Linux systems or its equivalent on other systems.)

For a manual install procedure, download the release tarball from the Python Package Index, untar, and execute the following command in the graphterm-<version> directory:

python setup.py install

For the manual install, you will also need to install the tornado web server, which can be downloaded from https://github.com/downloads/facebook/tornado/tornado-2.3.tar.gz

You can also try out GraphTerm without installing it, after untarring the source tarball (or checking out the source from github). You can run the server gtermserver.py in the graphterm subdirectory of the distribution, after you have installed the tornado module in your system (or in the graphterm subdirectory).

You can browse the GraphTerm source code, and download the development version, at Github.

3   Documentation and Support

Documentation and updates can be found on the project home page, info.mindmeldr.com/code/graphterm, which also has tutorials and examples for using GraphTerm.

Report bugs and other issues using the Github Issue Tracker.

4   Usage

To start the GraphTerm server, use the command:

gtermserver --auth_code=none

Type gtermserver -h to view all options. You can use the --daemon=start option to run it in the background.

Once the server is running, you can open a terminal window on the localhost in the following ways:

• Specify the --terminal option when starting gtermserver
• Use the gterm command in any terminal
• Within a GraphTerm window, you can use the New menu option, or use the keyboard shortcut Ctrl-Alt-T to create a new GraphTerm window

To open a remote terminal window, open up a browser of your choice that supports websockets, such as Google Chrome, Firefox, or Safari (Chrome works best), and enter the following URL:

http://localhost:8900

Once within the graphterm browser page, select the host you wish to connect to and create a new terminal session on the host.

Once you have a terminal, try out the following commands:

gls <directory>
gvi <text-filename>

These are graphterm-aware scripts that imitate basic features of the standard ls and vi commands. To display images as thumbnails, use the gls -i ... command. Use the -h option to display help information for these commands, and read the UsingGraphicalFeatures tutorial for usage examples.

You can use the command which gls to determine the directory containing graphterm-aware commands, to browse for other commands, which include:

giframe [filename|URL] To view files/URLs (or HTML from stdin) in inline iframe

gimage [-f] [filenames] To view images inline, or as a fullpage slideshow (with -f option)

gmatplot.py A matplotlib plotting demo

yweather [location] To view weather forecasts

gtweet [-s keywords]|tweet To send, search, or receive tweets

(There is also a sample gcowsay command which can be downloaded separately from its Github repository)

gtermhost --server_addr=<serveraddr> <hostname>

http://localhost:8900/local/mysession

http://localhost:8900/*/tty1

gimage -f

giframe --opacity=0.2 http://localhost:8900/local/new > $GRAPHTERM_SOCKET &

gfeedback 2> $GRAPHTERM_SOCKET 0<&2 | gfeed > $GRAPHTERM_SOCKET &
gimage -f

gtweet -f -s topic > $GRAPHTERM_SOCKET &
gimage -f

ssh -R 8898:localhost:8898 user@remote-computer

ssh -L 8900:localhost:8900 user@work-computer

5   otrace integration

GraphTerm was originally developed as a graphical front-end for otrace, an object-oriented python debugger. Any Python program can serve as a "host" and be connected to the GraphTerm server using the gotrace command:

gotrace example.py

The above command loads example.py as a module and connects to the GraphTerm server for debugging. This program will appear in the list of hosts under the name example. Open the terminal session example/osh to connect to the otrace console, and issue the run <function> command to begin executing a function in example.py. You can also initiate program execution directly from the command line as follows:

gotrace -f test example.py arg1 arg2

The above command executes the function test(arg=[]) in example.py, where arg is a list of string arguments from the command line.

If you wish to use the otrace console features for multiplexing, without actually needing to a debug a program, you can use the --oshell option when using gtermhost to connect to the server.

(You can also embed code in a Python program to directly connect to the GraphTerm server for monitoring/debugging. See gotrace.py to find out how it can be done.)

6   Cloud integration

The GraphTerm distribution includes the scripts ec2launch, ec2list, ec2scp, and ec2ssh to launch and monitor Amazon Web Services EC2 instances. These are the scripts used to test new versions of GraphTerm by running them in the "cloud". You will need to have an Amazon AWS account to use these scripts, and also need to install the boto python module.

To create an instance, use the ec2launch command. You will be presented with a "web form" to enter details of the instance to be launched. Once you fill in the form and submit it, a command line will be automatically created, with command options, to launch the instance. To launch another instance with slightly different properties, you can simply recall the command line and edit it. Ensure that the security group associated with the cloud instance allows access to inbound TCP port 22 (for SSH access), 8900 (for GraphTerm users to connect), and port 8899 (for GraphTerm hosts to connect).

To temporarily run a publicly accessible GraphTerm server for demonstration or teaching purposes, log in to the instance using the command ec2ssh ubuntu@instance_address, wait a few minutes for tornado and graphterm packages to finish installing, and then issue the following command:

gtermserver --daemon=start --auth_code=none --host=<primary_domain_or_address>

Note: This is totally insecure and should not be used for handling any sensitive information.

Secondary cloud instances should connect to the GraphTerm server on the primary instance using the command:

gtermhost --daemon=start --server_addr=<primary_domain_or_address> <secondary_host_name>

For increased security in a publicly-accessible server, you can use a cryptic authentication code, and also use https instead of http, with SSL certificates. Since GraphTerm is currently in alpha status, security cannot be guaranteed even with these options enabled. (To avoid these problems, use SSH port forwarding to access GraphTerm on localhost whenever possble.)

7   API for GraphTerm-aware programs

A graphterm-aware program writes to to the standard output in a format similar to a HTTP response, preceded and followed by xterm-like escape sequences:

\x1b[?1155;<cookie>h
{"content_type": "text/html", ...}

<div>
...
</div>
\x1b[?1155l

where <cookie> denotes a numeric value stored in the environment variable GRAPHTERM_COOKIE. (The random cookie is a security measure that prevents malicious files from accessing GraphTerm.) The opening escape sequence is followed by a dictionary of header names and values, using JSON format. This is followed by a blank line, and then any data (such as the HTML fragment to be displayed).

A graphterm-aware program can be written in any language, much like a CGI script. See the programs gls, gimage, giframe, gvi, gfeed, yweather, ec2launch and ec2list for examples of GraphTerm API usage. You can use the which gls command to figure out where these programs are located. The file gtermapi.py contains many helper functions for accessing the GraphTerm API. See also the gcowsay program for an example of a stand-alone GraphTerm-aware command.

8   Implementation

The GraphTerm server written in pure python, using the Tornado web framework, with websocket support. The GraphTerm client uses standard HTML5+Javascript+CSS (with jQuery).

The GraphTerm server may be run on your desktop or on a remote computer. Users create and access terminal sessions by the connecting to the Graphterm server on port 8900, either directly or through SSH port forwarding. By default, the localhost on the computer where the GraphTerm server is running is available for opening terminal sessions. Other computers can also connect to the GraphTerm server, on a different port (8899), to make them accessible as hosts for connection from the browser.

A pseudo-tty (pty) is opened on the host for each terminal session. By setting the PROMP_COMMAND environment variable, GraphTerm determines when the stdout of the previous command ends, and the prompt for the new command begins.

The connection between the browser and the GraphTerm server is implemented using websockets (bi-directional HTTP). The GraphTerm server acts as a router sending input from controlling browser terminal sessions to the appropriate pty on the host computer, and transmitting output from each pty to all connected browser terminal sessions.

GraphTerm extends the xterm terminal API by adding a new control sequence for programs to transmit a CGI-like HTTP response through standard output (via a websocket) to be displayed in the browser window. GraphTerm-aware programs can interact with the user using HTML forms etc.

9   Caveats and limitations

• Reliability: This software has not been subject to extensive testing. Use at your own risk.

• Platforms: The GraphTerm client should work on most recent browsers that support Websockets, such as Google Chrome, Firefox, and Safari. The GraphTerm server is pure-python, but with some OS-specific calls for file, shell, and terminal-related operations. It has been tested only on Linux and Mac OS X so far.

• Current limitations:

  • Support for xterm escape sequences is incomplete.
  • Most features of GraphTerm only work with the bash shell, not with C-shell, due the need for PROMPT_COMMAND to keep track of the current working directory.
  • At the moment, you cannot customize the shell prompt. (You should be able to so in the future.)

10   Credits

GraphTerm is inspired by two earlier projects that implement the terminal interface within the browser, XMLTerm and AjaxTerm. It borrows many of the ideas from XMLTerm and re-uses chunks of code from AjaxTerm. The server uses the asynchronous Tornado web framework and the client uses jQuery.

The gls command uses icons from the Tango Icon Library, and graphical editing uses the Ajax.org Cloud9 Editor

The 3D perspective mode was inspired by Sean Slinsky's Star Wars Opening Crawl with CSS3.

GraphTerm was developed as part of the Mindmeldr project, which is aimed at improving classroom interaction.

11   License

GraphTerm is distributed as open source under the BSD-license.