Browse files

Added GRAPHTERM_EXPORT to mark exported environment; docs fixes

  • Loading branch information...
1 parent 0802716 commit 86829a40da5344634753550eb8a6e761f3ea6f14 @mitotic committed Aug 28, 2012
Showing with 114 additions and 55 deletions.
  1. +60 −35 README.rst
  2. +10 −11 graphterm/bin/giframe
  3. +4 −3 graphterm/bin/gimage
  4. +35 −3 graphterm/bin/gtermapi.py
  5. +4 −2 graphterm/lineterm.py
  6. +1 −1 graphterm/version.py
View
95 README.rst
@@ -24,7 +24,7 @@ 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")
+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.
@@ -102,7 +102,7 @@ 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/fork the ``GraphTerm`` source code, and download the development
+You can browse the ``GraphTerm`` source code, and download the development
version, at `Github <https://github.com/mitotic/graphterm>`_.
@@ -155,14 +155,15 @@ 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.
+and read the
+`UsingGraphicalFeatures tutorial <http://info.mindmeldr.com/code/graphterm/graphterm-tutorials/graphterm-tutorial-graphical>`_ 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
+ inline *iframe*
``gimage [-f] [filenames]`` To view images inline, or as a
fullpage slideshow (with ``-f`` option)
@@ -204,7 +205,7 @@ Enter key to execute it.
Icon display
------------------------------
-Select ``icons`` in the top menu to activate icon display for commands
+Select ``icons`` in the top menu to activate icon display for commands like
``gls``.
@@ -310,8 +311,8 @@ For example, if you forgot to detach your session at work, you can
to securely access your work desktop, and then steal the
session using your home browser.
-NOTE: Although GraphTerm supports multiple users, it is currently
-designed for a cooperative environment, where everyone trusts everyone
+NOTE: Although GraphTerm supports multiple users, it currently
+assumes a cooperative environment, where everyone trusts everyone
else. (This may change in the future.)
@@ -364,24 +365,34 @@ Widgets, sockets, and interactivity
--------------------------------------------------------------------------------------
A widget appears as an overlay on the terminal (like
-*picture-in-picture* for TVs, or the dashboard on the Mac). It is an
+*picture-in-picture* for TVs, or dashboard widgets on the Mac). This is an
experimental feature that allows programs running in the background to
-display information overlaid on the terminal. The specific use case is
-displaying user feedback on the screen during a presentation (e.g.,
-like Twitter feeds). You can try it out in a directory that
+display information overlaid on the terminal. The widget is accessed
+by redirecting ``stdout`` to a Bash ``tcp`` socket device whose
+address is stored in the environment variable ``GRAPHTERM_SOCKET``.
+For example, the following command will run a background job
+to open a new terminal in an overlay *iframe*::
+
+ giframe --opacity=0.2 http://localhost:8900/local/new > $GRAPHTERM_SOCKET &
+
+You can use the overlay terminal just like a regular terminal, including
+having recursive overlays within the overlay!
+
+A specific example of widget use is to display live feedback on the
+screen during a presentation. You can try it out in a directory that
contains your presentation slides as images::
gfeedback 2> $GRAPHTERM_SOCKET 0<&2 | gfeed > $GRAPHTERM_SOCKET &
gimage -f
The first command uses ``gfeedback`` to capture feedback from others
-viewing the terminal session as a stream of lines from the bash socket
+viewing the terminal session as a stream of lines from
$GRAPHTERM_SOCKET. The viewers use the overlaid *feedback* button
-to provide feedback. The feedback data is piped to ``gfeed`` which
-displays its ``stdin`` stream as a "live feed" overlay, also via
-$GRAPHTERM_SOCKET.
-The second commands displays all the images in the directory as a
-slideshow.
+to provide feedback. The ``stdout`` from ``gfeedback`` is piped to
+``gfeed`` which displays its ``stdin`` stream as a "live feed"
+overlay, also via $GRAPHTERM_SOCKET.
+(The ``gimage -f`` command displays all the images in the directory as a
+slideshow.)
To display a live twitter feed as an overlay on a presentation, you can use the commands::
@@ -402,7 +413,7 @@ use SSH port forwarding (see below) to securely connect to the
GraphTerm server for remote access.
As the code matures, security will be improved through
the use of SSL certificates and server/client authentication.
-(SSL/https support is already built-in. Feel free to experiment with
+(SSL/https support is already built in. Feel free to experiment with
it, although it is not yet ready for everyday use.)
@@ -471,35 +482,48 @@ Cloud integration
===============================
The GraphTerm distribution includes the scripts ``ec2launch, ec2list, ec2scp,``
-and ``ec2ssh`` to launch and monitor Amazon Web Services EC2 instances
-to run GraphTerm 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 command::
-
- ec2instance <instance_tagname>
+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, use the following command on the instance::
+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.*
-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). Also, when using ``ec2scp`` and ``ec2ssh``
-to access the instance, ensure that you specify the appropriate login name (e.g., ``ubuntu``
-for Ubuntu distribution).
+
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 will need to 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.
+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.)
+
API for GraphTerm-aware programs
==========================================
@@ -525,8 +549,9 @@ and then any data (such as the HTML fragment to be displayed).
A `graphterm-aware program <https://github.com/mitotic/graphterm/tree/master/graphterm/bin>`_
can be written in any language, much like a CGI script.
-See the programs ``gls``, ``gimage``, ``gvi``, ``gweather``, ``ec2launch`` and
-``ec2list`` for examples of GraphTerm API usage. You can use the ``which gls``
+See the programs ``gls``, ``gimage``, ``giframe``, ``gvi``, ``gfeed``,
+``gweather``, ``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.
View
21 graphterm/bin/giframe
@@ -17,23 +17,22 @@ import gtermapi
usage = "usage: %prog [file|URL]"
parser = OptionParser(usage=usage)
-(options, args) = parser.parse_args()
+parser.add_option("", "--opacity", dest="opacity", default=1.0,
+ help="Feed opacity (default: 1.0)")
+(options, args) = parser.parse_args()
if args:
if args[0].startswith("http:") or args[0].startswith("https:"):
iframe_url = args[0]
else:
- filename = args[0]
- fullname = os.path.expanduser(filename)
- filepath = os.path.normcase(os.path.abspath(fullname))
+ if gtermapi.Export_host:
+ iframe_url = gtermapi.create_blob(from_file=args[0])
+ else:
+ iframe_url = gtermapi.get_file_url(args[0], relative=True, exists=True)
- if not os.path.exists(filepath) or not os.path.isfile(filepath):
- print >> sys.stderr, "File %s not found" % filename
+ if not iframe_url:
+ print >> sys.stderr, "File %s not found" % args[0]
sys.exit(1)
-
- mimetype, encoding = mimetypes.guess_type(filepath)
- iframe_url = gtermapi.get_file_url(filepath, relative=True)
-
else:
try:
content = sys.stdin.read()
@@ -48,7 +47,7 @@ else:
IFRAMEFORMAT = '<iframe src="%s" width="100%%" height="95%%"></iframe><pre>Click here and type Control-C to exit</pre>'
-gtermapi.write_html(IFRAMEFORMAT % iframe_url, display="fullscreen")
+gtermapi.write_html(IFRAMEFORMAT % iframe_url, display="fullscreen", add_headers={"opacity": options.opacity})
try:
while True:
View
7 graphterm/bin/gimage
@@ -36,6 +36,9 @@ if not args:
args = [x for x in args if not x.startswith(".")]
args.sort()
+if gtermapi.Export_host:
+ options.blobs = True
+
if options.blobs:
print >> sys.stderr, "Loading images ..."
@@ -54,9 +57,7 @@ for filename in args:
mimetype, encoding = mimetypes.guess_type(filepath)
if mimetype and mimetype.startswith("image/"):
if options.blobs:
- with open(filepath) as fp:
- content = fp.read()
- file_url = gtermapi.create_blob(content, content_type=mimetype)
+ file_url = gtermapi.create_blob(from_file=filepath, content_type=mimetype)
else:
file_url = gtermapi.get_file_url(filepath, relative=True)
file_list.append((file_url, filepath, filename))
View
38 graphterm/bin/gtermapi.py
@@ -7,6 +7,7 @@
import hashlib
import hmac
import json
+import mimetypes
import os
import Queue
import random
@@ -21,6 +22,7 @@
HEX_DIGITS = 16
+Export_host = os.getenv("GRAPHTERM_EXPORT", "")
Lterm_cookie = os.getenv("GRAPHTERM_COOKIE", "")
Shared_secret = os.getenv("GRAPHTERM_SHARED_SECRET", "")
Path = os.getenv("GRAPHTERM_PATH", "")
@@ -77,8 +79,16 @@ def open_url(url, target="_blank"):
}
wrap_write("", headers=url_headers)
-def get_file_url(filepath, relative=False):
- """Construct file URL with hmac cookie suffix. If relative, return '/file/host/path'"""
+def get_file_url(filepath, relative=False, exists=False):
+ """Construct file URL by expanding/normalizing filepath, with hmac cookie suffix.
+ If relative, return '/file/host/path'
+ """
+ if not filepath.startswith("/"):
+ filepath = os.path.normcase(os.path.abspath(os.path.expanduser(filepath)))
+
+ if exists and not os.path.exists(filepath):
+ return None
+
filehmac = "?hmac="+hmac.new(str(Shared_secret), filepath, digestmod=hashlib.sha256).hexdigest()[:HEX_DIGITS]
if relative:
return "/file/" + Host + filepath + filehmac
@@ -89,8 +99,30 @@ def make_blob_url(blob_id=""):
blob_id = blob_id or str(uuid.uuid4())
return (blob_id, "/blob/"+Host+"/"+blob_id)
-def create_blob(content, content_type="text/html", blob_id=""):
+def create_blob(content=None, from_file="", content_type="", blob_id=""):
"""Create blob and returns URL to blob"""
+ if content is None:
+ if not from_file:
+ print >> sys.stderr, "Error: No content and no file to create blob"
+ return None
+ fullname = os.path.expanduser(from_file)
+ filepath = os.path.normcase(os.path.abspath(fullname))
+
+ if not os.path.exists(filepath) or not os.path.isfile(filepath):
+ print >> sys.stderr, "File %s not found" % from_file
+ return None
+
+ try:
+ with open(filepath) as fp:
+ content = fp.read()
+ except Exception, excp:
+ print >> sys.stderr, "Error in reading file %s: %s" % (from_file, excp)
+ return None
+
+ if not content_type:
+ content_type, encoding = mimetypes.guess_type(filepath)
+
+ content_type = content_type or "text/html"
params = {}
blob_id, blob_url = make_blob_url(blob_id)
params["blob_id"] = blob_id
View
6 graphterm/lineterm.py
@@ -10,7 +10,7 @@
from __future__ import with_statement
import array, cgi, copy, fcntl, glob, logging, mimetypes, optparse, os, pty
-import re, signal, select, sys, threading, time, termios, tty, struct, pwd
+import re, signal, select, socket, sys, threading, time, termios, tty, struct, pwd
import random
try:
@@ -35,7 +35,7 @@
UPDATE_INTERVAL = 0.05 # Fullscreen update time interval
TERM_TYPE = "xterm" # "screen" may be a better default terminal, but arrow keys do not always work
-NO_COPY_ENV = set(["TERM_PROGRAM","TERM_PROGRAM_VERSION", "TERM_SESSION_ID"])
+NO_COPY_ENV = set(["GRAPHTERM_EXPORT", "TERM_PROGRAM","TERM_PROGRAM_VERSION", "TERM_SESSION_ID"])
ALTERNATE_SCREEN_CODES = (47, 1047, 1049) # http://rtfm.etla.org/xterm/ctlseq.html
GRAPHTERM_SCREEN_CODES = (1150, 1155)
@@ -1574,6 +1574,8 @@ def term_env(self, term_name, cookie, export=False):
env.append( ("PROMPT_COMMAND", cmd_fmt % (GRAPHTERM_SCREEN_CODES[0], GRAPHTERM_SCREEN_CODES[0]) ) )
+ if export:
+ env.append( ("GRAPHTERM_EXPORT", socket.getfqdn() or "unknown") )
return env
def export_environment(self, term_name):
View
2 graphterm/version.py
@@ -1 +1 @@
-current = "0.30.9"
+current = "0.30.9+"

0 comments on commit 86829a4

Please sign in to comment.