commit 3c3822d5aea6d90f438383a2cd8318d87e8c10cc Author: Damian Johnson <atagar@torproject.org> Date: Wed Dec 25 18:58:14 2013 -0800 Fetching string resources via a msg() helper Over time I've been moving more and more strings to our config. This moves the remainder of the starter strings over, places them in namespaces, and added a helper to make our code for fetching string resources *much* nicer. This might also help with internationalization later on if we go that route (since strings are now being segregated to their own config). --- arm/arguments.py | 15 +++-- arm/logPanel.py | 4 +- arm/settings.cfg | 148 ++++++++++++++++++++++++++++++-------------------- arm/starter.py | 78 +++++++++++--------------- arm/util/__init__.py | 56 +++++++++++++++++++ arm/util/tracker.py | 24 ++++---- 6 files changed, 198 insertions(+), 127 deletions(-) diff --git a/arm/arguments.py b/arm/arguments.py index f449412..cc512bd 100644 --- a/arm/arguments.py +++ b/arm/arguments.py @@ -9,12 +9,8 @@ import os import arm import stem.connection -import stem.util.conf -CONFIG = stem.util.conf.config_dict("arm", { - 'msg.event_types': '', - 'msg.help': '', -}) +from arm.util import msg DEFAULT_ARGS = { 'control_address': '127.0.0.1', @@ -102,13 +98,13 @@ def get_help(): :returns: **str** with our usage information """ - return CONFIG['msg.help'].format( + return msg('usage.help_output', address = DEFAULT_ARGS['control_address'], port = DEFAULT_ARGS['control_port'], socket = DEFAULT_ARGS['control_socket'], config = DEFAULT_ARGS['config'], events = DEFAULT_ARGS['logged_events'], - event_flags = CONFIG['msg.event_types'], + event_flags = msg('misc.event_types'), ) @@ -119,4 +115,7 @@ def get_version(): :returns: **str** with our versioning information """ - return "arm version %s (released %s)\n" % (arm.__version__, arm.__release_date__) + return msg('usage.version_output', + version = arm.__version__, + date = arm.__release_date__, + ) diff --git a/arm/logPanel.py b/arm/logPanel.py index 3b58125..9b877d0 100644 --- a/arm/logPanel.py +++ b/arm/logPanel.py @@ -56,7 +56,7 @@ CONFIG = conf.config_dict("arm", { "features.log.maxRefreshRate": 300, "features.log.regex": [], "cache.logPanel.size": 1000, - "msg.event_types": '', + "msg.misc.event_types": '', "tor.chroot": '', }, conf_handler) @@ -752,7 +752,7 @@ class LogPanel(panel.Panel, threading.Thread, logging.Handler): # displays the available flags popup.win.box() popup.addstr(0, 0, "Event Types:", curses.A_STANDOUT) - eventLines = CONFIG['msg.event_types'].split("\n") + eventLines = CONFIG['msg.misc.event_types'].split("\n") for i in range(len(eventLines)): popup.addstr(i + 1, 1, eventLines[i][6:]) diff --git a/arm/settings.cfg b/arm/settings.cfg index 198a6b5..eac04e2 100644 --- a/arm/settings.cfg +++ b/arm/settings.cfg @@ -1,25 +1,66 @@ settings_loaded true -msg.help -|Usage arm [OPTION] -|Terminal status monitor for Tor relays. +################################################################################ +# +# User facing strings. These are sorted into the following namespaces... +# +# * config parsing or handling configuration options +# * connect connection and authentication to tor +# * debug concerns the --debug argument +# * misc anything that doesn't fit into a present namespace +# * setup notificaitons or issues arising while starting arm +# * tracker related to tracking resource usage or connections +# * usage usage information about starting and running arm +# +################################################################################ + +msg.config.unable_to_load_settings Unable to load arm's internal configuration ({path}): {error} +msg.config.unable_to_read_file Failed to load configuration (using defaults): "{error}" +msg.config.nothing_loaded No armrc loaded, using defaults. You can customize arm by placing a configuration file at {path} (see the armrc.sample for its options). +msg.connect.general_auth_failure Unable to authenticate: {error} +msg.connect.incorrect_password Incorrect password +msg.connect.no_control_port Unable to connect to tor. Maybe it's running without a ControlPort? +msg.connect.password_prompt Tor controller password: +msg.connect.socket_doesnt_exist The socket file you specified ({path}) doesn't exist +msg.connect.tor_isnt_running Unable to connect to tor. Are you sure it's running? +msg.connect.unable_to_use_port Unable to connect to {address}:{port}: {error} +msg.connect.unable_to_use_socket Unable to connect to '{path}': {error} +msg.debug.saving_to_path Saving a debug log to {path}, please check it for sensitive information before sharing it. +msg.debug.unable_to_write_file Unable to write to our debug log file ({path}): {error} +msg.setup.arm_is_running_as_root Arm is currently running with root permissions. This isn't a good idea, nor should it be necessary. Try starting arm with "sudo -u {tor_user} arm" instead. +msg.setup.chroot_doesnt_exist The chroot path set in your config ({path}) doesn't exist. +msg.setup.set_freebsd_chroot Adjusting paths to account for Tor running in a FreeBSD jail at: {path} +msg.setup.tor_is_running_as_root Tor is currently running with root permissions. This isn't a good idea, nor should it be necessary. See the 'User UID' option on Tor's man page for an easy method of reducing its permissions after startup. +msg.setup.unable_to_determine_pid Unable to determine Tor's pid. Some information, like its resource usage will be unavailable. +msg.setup.unknown_event_types arm doesn't recognize the following event types: {event_types} (log 'UNKNOWN' events to see them) +msg.tracker.abort_getting_resources Failed three attempts to get process resource usage from {resolver}, {response} ({exc}) +msg.tracker.unable_to_get_resources Unable to query process resource usage from {resolver} ({exc}) +msg.tracker.unable_to_use_all_resolvers We were unable to use any of your system's resolvers to get tor's connections. This is fine, but means that the connections page will be empty. This is usually permissions related so if you would like to fix this then run arm with the same user as tor (ie, "sudo -u <tor user> arm"). +msg.tracker.unable_to_use_resolver Unable to query connections with {old_resolver}, trying {new_resolver} +msg.usage.invalid_arguments {error} (for usage provide --help) +msg.usage.unrecognized_log_flag Unrecognized event flag: {flag} + +msg.connect.missing_password_bug +|BUG: You provided a password but despite this stem reported that it was +|missing. This shouldn't happen - please let us know about it! | -| -i, --interface [ADDRESS:]PORT change control interface from {address}:{port} -| -s, --socket SOCKET_PATH attach using unix domain socket if present, -| SOCKET_PATH defaults to: {socket} -| -c, --config CONFIG_PATH loaded configuration options, CONFIG_PATH -| defaults to: {config} -| -d, --debug LOG_PATH writes all arm logs to the given location -| -e, --event EVENT_FLAGS event types in message log (default: {events}) -|{event_flags} -| -v, --version provides version information -| -h, --help presents this help +| http://bugs.torproject.org + +msg.connect.unreadable_cookie_file +|We were unable to read tor's authentication cookie... | -|Example: -|arm -i 1643 attach to control port 1643 -|arm -e we -c /tmp/cfg use this configuration file with 'WARN'/'ERR' events +| Path: {path} +| Issue: {issue} + +msg.connect.wrong_port_type +|Please check in your torrc that {port} is the ControlPort. Maybe you +|configured it to be the ORPort or SocksPort instead? + +msg.connect.wrong_socket_type +|Unable to connect to tor. Are you sure the interface you specified belongs to +|tor? -msg.debug_header +msg.debug.header |Arm {arm_version} Debug Dump |Stem Version: {stem_version} |Python Version: {python_version} @@ -29,13 +70,21 @@ msg.debug_header |{armrc_content} |-------------------------------------------------------------------------------- -msg.wrong_port_type -|Please check in your torrc that {port} is the ControlPort. Maybe you -|configured it to be the ORPort or SocksPort instead? +msg.misc.event_types +| d DEBUG a ADDRMAP k DESCCHANGED s STREAM +| i INFO f AUTHDIR_NEWDESCS g GUARD r STREAM_BW +| n NOTICE h BUILDTIMEOUT_SET l NEWCONSENSUS t STATUS_CLIENT +| w WARN b BW m NEWDESC u STATUS_GENERAL +| e ERR c CIRC p NS v STATUS_SERVER +| j CLIENTS_SEEN q ORCONN +| DINWE tor runlevel+ A All Events +| 12345 arm runlevel+ X No Events +| U Unknown Events -msg.wrong_socket_type -|Unable to connect to tor. Are you sure the interface you specified belongs to -|tor? +msg.setup.unknown_term +|Unknown $TERM: ({term}) +|Either update your terminfo database or run arm using "TERM=xterm arm". +| msg.uncrcognized_auth_type |Tor is using a type of authentication we do not recognize... @@ -45,46 +94,29 @@ msg.uncrcognized_auth_type |Please check that arm is up to date and if there is an existing issue on |'http://bugs.torproject.org'. If there isn't one then let us know! -msg.missing_password_bug -|BUG: You provided a password but despite this stem reported that it was -|missing. This shouldn't happen - please let us know about it! +msg.usage.help_output +|Usage arm [OPTION] +|Terminal status monitor for Tor relays. | -| http://bugs.torproject.org - -msg.unreadable_cookie_file -|We were unable to read tor's authentication cookie... +| -i, --interface [ADDRESS:]PORT change control interface from {address}:{port} +| -s, --socket SOCKET_PATH attach using unix domain socket if present, +| SOCKET_PATH defaults to: {socket} +| -c, --config CONFIG_PATH loaded configuration options, CONFIG_PATH +| defaults to: {config} +| -d, --debug LOG_PATH writes all arm logs to the given location +| -e, --event EVENT_FLAGS event types in message log (default: {events}) +|{event_flags} +| -v, --version provides version information +| -h, --help presents this help | -| Path: {path} -| Issue: {issue} - -msg.tor_is_running_as_root Tor is currently running with root permissions. This isn't a good idea, nor should it be necessary. See the 'User UID' option on Tor's man page for an easy method of reducing its permissions after startup. -msg.arm_is_running_as_root Arm is currently running with root permissions. This isn't a good idea, nor should it be necessary. Try starting arm with "sudo -u {tor_user} arm" instead. -msg.config_not_found No armrc loaded, using defaults. You can customize arm by placing a configuration file at {path} (see the armrc.sample for its options). -msg.unable_to_read_config Failed to load configuration (using defaults): "{error}" -msg.unable_to_determine_pid Unable to determine Tor's pid. Some information, like its resource usage will be unavailable. - -msg.unable_to_use_resolver Unable to query connections with {old_resolver}, trying {new_resolver} -msg.unable_to_use_all_resolvers We were unable to use any of your system's resolvers to get tor's connections. This is fine, but means that the connections page will be empty. This is usually permissions related so if you would like to fix this then run arm with the same user as tor (ie, "sudo -u <tor user> arm"). - -msg.unable_to_get_resources Unable to query process resource usage from {resolver} ({exc}) -msg.abort_getting_resources Failed three attempts to get process resource usage from {resolver}, {response} ({exc}) +|Example: +|arm -i 1643 attach to control port 1643 +|arm -e we -c /tmp/cfg use this configuration file with 'WARN'/'ERR' events -msg.unknown_term -|Unknown $TERM: ({term}) -|Either update your terminfo database or run arm using "TERM=xterm arm". +msg.usage.version_output +|arm version {version} (released {date}) | -msg.event_types -| d DEBUG a ADDRMAP k DESCCHANGED s STREAM -| i INFO f AUTHDIR_NEWDESCS g GUARD r STREAM_BW -| n NOTICE h BUILDTIMEOUT_SET l NEWCONSENSUS t STATUS_CLIENT -| w WARN b BW m NEWDESC u STATUS_GENERAL -| e ERR c CIRC p NS v STATUS_SERVER -| j CLIENTS_SEEN q ORCONN -| DINWE tor runlevel+ A All Events -| 12345 arm runlevel+ X No Events -| U Unknown Events - # Important tor configuration options (shown by default) config.important BandwidthRate config.important BandwidthBurst diff --git a/arm/starter.py b/arm/starter.py index 7c1e689..bc139c5 100644 --- a/arm/starter.py +++ b/arm/starter.py @@ -33,41 +33,30 @@ import stem.util.connection import stem.util.log import stem.util.system +from arm.util import msg, trace, notice, warn + SETTINGS_PATH = os.path.join(os.path.dirname(__file__), 'settings.cfg') CONFIG = stem.util.conf.config_dict("arm", { 'tor.chroot': '', 'tor.password': None, - 'startup.events': 'N3', - 'msg.debug_header': '', - 'msg.wrong_port_type': '', - 'msg.wrong_socket_type': '', - 'msg.uncrcognized_auth_type': '', - 'msg.missing_password_bug': '', - 'msg.unreadable_cookie_file': '', - 'msg.tor_is_running_as_root': '', - 'msg.arm_is_running_as_root': '', - 'msg.config_not_found': '', - 'msg.unable_to_read_config': '', - 'msg.unable_to_determine_pid': '', - 'msg.unknown_term': '', }) def main(): - config = stem.util.conf.get_config("arm") + config = stem.util.conf.get_config('arm') config.set('start_time', str(int(time.time()))) try: config.load(SETTINGS_PATH) except IOError as exc: - print "Unable to load arm's internal configuration (%s): %s" % (SETTINGS_PATH, exc) + print msg('config.unable_to_load_settings', path = SETTINGS_PATH, error = exc) sys.exit(1) try: args = arm.arguments.parse(sys.argv[1:]) except getopt.GetoptError as exc: - print "%s (for usage provide --help)" % exc + print msg('usage.invalid_arguments', error = exc) sys.exit(1) except ValueError as exc: print exc @@ -83,9 +72,9 @@ def main(): if args.debug_path is not None: try: _setup_debug_logging(args) - print "Saving a debug log to %s, please check it for sensitive information before sharing" % args.debug_path + print msg('debug.saving_to_path', path = args.debug_path) except IOError as exc: - print "Unable to write to our debug log file (%s): %s" % (args.debug_path, exc.strerror) + print msg('debug.unable_to_write_file', path = args.debug_path, error = exc.strerror) sys.exit(1) # loads user's personal armrc if available @@ -94,9 +83,9 @@ def main(): try: config.load(args.config) except IOError as exc: - stem.util.log.warn(CONFIG['msg.unable_to_read_config'].format(error = exc.strerror)) + warn('config.unable_to_read_file', error = exc.strerror) else: - stem.util.log.notice(CONFIG['msg.config_not_found'].format(path = args.config)) + notice('config.nothing_loaded', path = args.config) config.set('startup.events', args.logged_events) @@ -105,7 +94,7 @@ def main(): chroot = CONFIG['tor.chroot'].strip().rstrip(os.path.sep) if chroot and not os.path.exists(chroot): - stem.util.log.notice("The chroot path set in your config (%s) doesn't exist." % chroot) + stem.util.log.notice(msg('setup.chroot_doesnt_exist', path = chroot)) config.set('tor.chroot', '') else: config.set('tor.chroot', chroot) # use the normalized path @@ -116,7 +105,7 @@ def main(): arm.logPanel.expandEvents(args.logged_events) except ValueError as exc: for flag in str(exc): - print "Unrecognized event flag: %s" % flag + print msg('usage.unrecognized_log_flag', flag = flag) sys.exit(1) @@ -141,11 +130,9 @@ def main(): tor_user = controller.get_user(None) if tor_user == "root": - stem.util.log.notice(CONFIG['msg.tor_is_running_as_root']) + notice('setup.tor_is_running_as_root') elif os.getuid() == 0: - stem.util.log.notice(CONFIG['msg.arm_is_running_as_root'].format( - tor_user = tor_user if tor_user else "<tor user>" - )) + notice('setup.arm_is_running_as_root', tor_user = tor_user if tor_user else "<tor user>") # fetches descriptions for tor's configuration options @@ -166,7 +153,7 @@ def main(): try: controller.get_pid() except ValueError: - stem.util.log.warn(CONFIG['msg.unable_to_determine_pid']) + warn('setup.unable_to_determine_pid') # If we're running under FreeBSD then check the system for a chroot path. @@ -174,7 +161,7 @@ def main(): jail_chroot = stem.util.system.get_bsd_jail_path(controller.get_pid(0)) if jail_chroot and os.path.exists(jail_chroot): - stem.util.log.info("Adjusting paths to account for Tor running in a FreeBSD jail at: %s" % jail_chroot) + info('setup.set_freebsd_chroot', path = jail_chroot) config.set('tor.chroot', jail_chroot) # If using our LANG variable for rendering multi-byte characters lets us @@ -189,14 +176,13 @@ def main(): missing_event_types = arm.logPanel.getMissingEventTypes() if missing_event_types: - plural_label = "s" if len(missing_event_types) > 1 else "" - stem.util.log.info("arm doesn't recognize the following event type%s: %s (log 'UNKNOWN' events to see them)" % (plural_label, ", ".join(missing_event_types))) + info('setup.unknown_event_types', event_types = ', '.join(missing_event_types)) try: curses.wrapper(arm.controller.start_arm) except UnboundLocalError as exc: if os.environ['TERM'] != 'xterm': - print CONFIG['msg.unknown_term'].format(term = os.environ['TERM']) + print msg('setup.unknown_term', term = os.environ['TERM']) else: raise exc except KeyboardInterrupt: @@ -226,20 +212,20 @@ def _get_controller(args): return stem.control.Controller.from_socket_file(args.control_socket) except stem.SocketError as exc: if args.user_provided_socket: - raise ValueError("Unable to connect to '%s': %s" % (args.control_socket, exc)) + raise ValueError(msg('connect.unable_to_use_socket', path = args.control_socket, error = exc)) elif args.user_provided_socket: - raise ValueError("The socket file you specified (%s) doesn't exist" % args.control_socket) + raise ValueError(msg('connect.socket_doesnt_exist', path = args.control_socket)) try: return stem.control.Controller.from_port(args.control_address, args.control_port) except stem.SocketError as exc: if args.user_provided_port: - raise ValueError("Unable to connect to %s:%i: %s" % (args.control_address, args.control_port, exc)) + raise ValueError(msg('connect.unable_to_use_port', address = args.control_address, port = args.control_port, error = exc)) if not stem.util.system.is_running('tor'): - raise ValueError("Unable to connect to tor. Are you sure it's running?") + raise ValueError(msg('connect.tor_isnt_running')) else: - raise ValueError("Unable to connect to tor. Maybe it's running without a ControlPort?") + raise ValueError(msg('connect.no_control_port')) def _authenticate(controller, password): @@ -259,23 +245,23 @@ def _authenticate(controller, password): control_socket = controller.get_socket() if isinstance(control_socket, stem.socket.ControlPort): - raise ValueError(CONFIG['msg.wrong_port_type'].format(port = control_socket.get_port())) + raise ValueError(msg('connect.wrong_port_type', port = control_socket.get_port())) else: - raise ValueError(CONFIG['msg.wrong_socket_type']) + raise ValueError(msg('connect.wrong_socket_type')) except stem.connection.UnrecognizedAuthMethods as exc: - raise ValueError(CONFIG['msg.uncrcognized_auth_type'].format(auth_methods = ', '.join(exc.unknown_auth_methods))) + raise ValueError(msg('uncrcognized_auth_type', auth_methods = ', '.join(exc.unknown_auth_methods))) except stem.connection.IncorrectPassword: - raise ValueError("Incorrect password") + raise ValueError(msg('connect.incorrect_password')) except stem.connection.MissingPassword: if password: - raise ValueError(CONFIG['msg.missing_password_bug']) + raise ValueError(msg('connect.missing_password_bug')) - password = getpass.getpass("Tor controller password: ") + password = getpass.getpass(msg('connect.password_prompt') + ' ') return _authenticate(controller, password) except stem.connection.UnreadableCookieFile as exc: - raise ValueError(CONFIG['msg.unreadable_cookie_file'].format(path = exc.cookie_path, issue = str(exc))) + raise ValueError(msg('connect.unreadable_cookie_file', path = exc.cookie_path, issue = str(exc))) except stem.connection.AuthenticationFailure as exc: - raise ValueError("Unable to authenticate: %s" % exc) + raise ValueError(msg('connect.general_auth_failure', error = exc)) def _setup_debug_logging(args): @@ -311,7 +297,7 @@ def _setup_debug_logging(args): except IOError as exc: armrc_content = "[unable to read file: %s]" % exc.strerror - stem.util.log.trace(CONFIG['msg.debug_header'].format( + trace('debug.header', arm_version = arm.__version__, stem_version = stem.__version__, python_version = '.'.join(map(str, sys.version_info[:3])), @@ -319,7 +305,7 @@ def _setup_debug_logging(args): platform = " ".join(platform.dist()), armrc_path = args.config, armrc_content = armrc_content, - )) + ) def _shutdown_daemons(controller): diff --git a/arm/util/__init__.py b/arm/util/__init__.py index 06ae312..2879f37 100644 --- a/arm/util/__init__.py +++ b/arm/util/__init__.py @@ -6,3 +6,59 @@ and safely working with curses (hiding some of the gory details). __all__ = ["connections", "panel", "sysTools", "textInput", "torConfig", "torTools", "tracker", "uiTools"] +import stem.util.conf +import stem.util.log + +def msg(message, **attr): + """ + Provides the given message. + + :param str message: message handle to log + :param dict attr: attributes to format the message with + + :returns: **str** that was requested + """ + + config = stem.util.conf.get_config('arm') + + try: + return config.get('msg.%s' % message).format(**attr) + except: + stem.util.log.notice('BUG: We attempted to use an undefined string resource (%s)' % message) + return '' + + +def trace(msg, **attr): + _log(stem.util.log.TRACE, msg, **attr) + + +def debug(msg, **attr): + _log(stem.util.log.DEBUG, msg, **attr) + + +def info(msg, **attr): + _log(stem.util.log.INFO, msg, **attr) + + +def notice(msg, **attr): + _log(stem.util.log.NOTICE, msg, **attr) + + +def warn(msg, **attr): + _log(stem.util.log.WARN, msg, **attr) + + +def error(msg, **attr): + _log(stem.util.log.ERROR, msg, **attr) + + +def _log(runlevel, message, **attr): + """ + Logs the given message, formatted with optional attributes. + + :param stem.util.log.Runlevel runlevel: runlevel at which to log the message + :param str message: message handle to log + :param dict attr: attributes to format the message with + """ + + stem.util.log.log(runlevel, msg(message, **attr)) diff --git a/arm/util/tracker.py b/arm/util/tracker.py index ee4fdcc..2bb87dd 100644 --- a/arm/util/tracker.py +++ b/arm/util/tracker.py @@ -44,13 +44,11 @@ import arm.util.torTools from stem.control import State from stem.util import conf, connection, log, proc, str_tools, system +from arm.util import debug, info, notice + CONFIG = conf.config_dict('arm', { 'queries.resources.rate': 5, 'queries.connections.rate': 5, - 'msg.unable_to_use_resolver': '', - 'msg.unable_to_use_all_resolvers': '', - 'msg.unable_to_get_resources': '', - 'msg.abort_getting_resources': '', }) CONNECTION_TRACKER = None @@ -383,12 +381,12 @@ class ConnectionTracker(Daemon): self._failure_count = 0 if self._resolvers: - log.notice(CONFIG['msg.unable_to_use_resolver'].format( + notice('tracker.unable_to_use_resolver', old_resolver = resolver, new_resolver = self._resolvers[0], - )) + ) else: - log.notice(CONFIG['msg.unable_to_use_all_resolvers']) + notice('tracker.unable_to_use_all_resolvers') return False @@ -480,25 +478,25 @@ class ResourceTracker(Daemon): self._use_proc = False self._failure_count = 0 - log.info(CONFIG['msg.abort_getting_resources'].format( + info('tracker.abort_getting_resources', resolver = 'proc', response = 'falling back to ps', exc = exc, - )) + ) else: - log.debug(CONFIG['msg.unable_to_get_resources'].format(resolver = 'proc', exc = exc)) + debug('tracker.unable_to_get_resources', resolver = 'proc', exc = exc) else: if self._failure_count >= 3: # Give up on further attempts. - log.info(CONFIG['msg.abort_getting_resources'].format( + info('tracker.abort_getting_resources', resolver = 'ps', response = 'giving up on getting resource usage information', exc = exc, - )) + ) self.stop() else: - log.debug(CONFIG['msg.unable_to_get_resources'].format(resolver = 'ps', exc = exc)) + debug('tracker.unable_to_get_resources', resolver = 'ps', exc = exc) return False