[tor-commits] [arm/master] Implementing /help for interpretor commands
atagar at torproject.org
atagar at torproject.org
Wed Sep 14 16:57:59 UTC 2011
commit d40a26f6bbd69fa63436983905ed261f164b5cb9
Author: Damian Johnson <atagar at torproject.org>
Date: Wed Sep 14 09:19:53 2011 -0700
Implementing /help for interpretor commands
Beginning to implement the '/help [OPTION]' interpretor command. This will
provide usage information on interpretor commands, tor controller commands,
and tor configuration options. At present just the general help and interpretor
commands are implemented.
---
src/util/torInterpretor.py | 103 ++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 100 insertions(+), 3 deletions(-)
diff --git a/src/util/torInterpretor.py b/src/util/torInterpretor.py
index fbb33da..3908d6e 100644
--- a/src/util/torInterpretor.py
+++ b/src/util/torInterpretor.py
@@ -14,6 +14,9 @@ from util import connections, enum, hostnames, torTools
COLOR_PROMPT = True # provides a colored interpretor prompt
INFO_HOSTNAMES = False # hostname lookups in /info results
+# initial location /write will save to when no path is specified
+DEFAULT_WRITE_PATH = "/tmp/torInterpretor_output"
+
INIT_MSG = """Arm %s Control Interpretor
Enter \"/help\" for usage information and \"/quit\" to stop.
""" % version.VERSION
@@ -45,6 +48,64 @@ RESET = CSI % "0"
BACKLOG_LIMIT = 100
CONTENT_LIMIT = 20000
+GENERAL_HELP = """Interpretor commands include:
+ help - provides information for interpretor and tor commands/config options
+ write - saves backlog to a given location
+ info - general information for a relay
+ find - searches backlog for lines with the given regex
+ quit - shuts down the interpretor
+
+Tor commands include:
+ GETINFO - queries information from tor
+ GETCONF, SETCONF, RESETCONF - show or edit a configuration option
+ SIGNAL - issues control signal to the process (for resetting, stopping, etc)
+ SETEVENT - configures the events tor will notify us of
+
+ USEFEATURE - enables custom behavior for the controller
+ SAVECONF - writes tor's current configuration to our torrc
+ LOADCONF - loads the given input like it was part of our torrc
+ MAPADDRESS - replaces requests for one address with another
+ POSTDESCRIPTOR - adds a relay descriptor to our cache
+ EXTENDCIRCUIT - create or extend a tor circuit
+ SETCIRCUITPURPOSE - configures the purpose associated with a circuit
+ CLOSECIRCUIT - closes the given circuit
+ ATTACHSTREAM - associates an application's stream with a tor circuit
+ REDIRECTSTREAM - sets a stream's destination
+ CLOSESTREAM - closes the given stream
+ RESOLVE - issues an asynchronous dns or rdns request over tor
+ TAKEOWNERSHIP - instructs tor to quit when this control connection is closed
+ PROTOCOLINFO - queries version and controller authentication information
+ QUIT - disconnect control connection
+
+For more information use '/help [OPTION]'."""
+
+HELP_HELP = """Provides usage information for the given interpretor, tor command, or tor
+configuration option.
+
+Example:
+ /help info # provides a description of the '/info' option
+ /help GETINFO # usage information for tor's GETINFO controller option
+ /help ExitPolicy # description of tor's ExitPolicy configuration option"""
+
+HELP_WRITE = """Writes the interpretor's backlog to the given path. If no location is
+specified then this saves to the last path specified (initially '%s').""" % DEFAULT_WRITE_PATH
+
+HELP_INFO = """Provides general information for a relay that's currently in the consensus.
+If no relay is specified then this provides information on ourselves."""
+
+HELP_FIND = """Searches the backlog for lines matching a given regular expression pattern.
+Results are deduplicated and the matching portions bolded."""
+
+HELP_QUIT = """Terminates the interpretor."""
+
+INTERPRETOR_HELP = {
+ "HELP": ("/help [OPTION]", HELP_HELP),
+ "WRITE": ("/write [PATH]", HELP_WRITE),
+ "INFO": ("/info [relay fingerprint, nickname, or IP address]", HELP_INFO),
+ "FIND": ("/find PATTERN", HELP_FIND),
+ "QUIT": ("/quit", HELP_QUIT)
+}
+
class InterpretorClosed(Exception):
"""
Exception raised when the interpretor should be shut down.
@@ -156,7 +217,7 @@ class TorControlCompleter:
self.commands.append("MAPADDRESS ")
self.commands.append("EXTENDCIRCUIT ")
self.commands.append("SETCIRCUITPURPOSE ")
- self.commands.append("SETROUTERPURPOSE ")
+ #self.commands.append("SETROUTERPURPOSE ") # deprecated option
self.commands.append("ATTACHSTREAM ")
self.commands.append("+POSTDESCRIPTOR ") # TODO: needs to support multiline options for this (ugg)
self.commands.append("REDIRECTSTREAM ")
@@ -197,7 +258,7 @@ class ControlInterpretor:
def __init__(self):
self.backlog = [] # prior requests the user has made
self.contents = [] # (msg, format list) tuples for what's been displayed
- self.writePath = "/tmp/torInterpretor_output" # last location we've saved to
+ self.writePath = DEFAULT_WRITE_PATH # last location we've saved to
def getBacklog(self):
"""
@@ -220,6 +281,37 @@ class ControlInterpretor:
return self.contents + [appendPrompt]
else: return self.contents
+ def doHelp(self, arg, outputEntry):
+ """
+ Performs the '/help' operation, giving usage information for the given
+ argument or a general summary if there wasn't one.
+ """
+
+ arg = arg.upper()
+
+ if arg:
+ if arg in INTERPRETOR_HELP:
+ # Provides information for the interpretor argument. This bolds the
+ # usage information and indents the description after it.
+ usage, description = INTERPRETOR_HELP[arg]
+
+ outputEntry.append((usage + "\n", OUTPUT_FORMAT + (Attr.BOLD, )))
+
+ for line in description.split("\n"):
+ outputEntry.append((" " + line + "\n", OUTPUT_FORMAT))
+ else:
+ outputEntry.append(("No help information for '%s'..." % arg, ERROR_FORMAT))
+ else:
+ # provides the GENERAL_HELP with everything bolded except descriptions
+ for line in GENERAL_HELP.split("\n"):
+ cmdStart = line.find(" - ")
+
+ if cmdStart != -1:
+ outputEntry.append((line[:cmdStart], OUTPUT_FORMAT + (Attr.BOLD, )))
+ outputEntry.append((line[cmdStart:] + "\n", OUTPUT_FORMAT))
+ else:
+ outputEntry.append((line + "\n", OUTPUT_FORMAT + (Attr.BOLD, )))
+
def doWrite(self, arg, outputEntry):
"""
Performs the '/write' operation, which attempts to save the backlog to a
@@ -286,7 +378,11 @@ class ControlInterpretor:
# determines the fingerprint, leaving it unset and adding an error message
# if unsuccessful
if not arg:
- outputEntry.append(("No fingerprint or nickname to look up", ERROR_FORMAT))
+ # uses our fingerprint if we're a relay, otherwise gives an error
+ fingerprint = conn.getInfo("fingerprint")
+
+ if not fingerprint:
+ outputEntry.append(("We aren't a relay, no information to provide", ERROR_FORMAT))
elif len(arg) == 40 and re.match("^[0-9a-fA-F]+$", arg):
# we got a fingerprint (fourty character hex string)
fingerprint = arg
@@ -438,6 +534,7 @@ class ControlInterpretor:
inputEntry.append((input, INPUT_INTERPRETOR_FORMAT))
if cmd == "/quit": raise InterpretorClosed()
+ elif cmd == "/help": self.doHelp(arg, outputEntry)
elif cmd == "/write": self.doWrite(arg, outputEntry)
elif cmd == "/find": self.doFind(arg, outputEntry)
elif cmd == "/info": self.doInfo(arg, outputEntry)
More information about the tor-commits
mailing list