December 2015 - tor-commits - lists.torproject.org

[translation/abouttor-homepage] Update translations for abouttor-homepage
by translation＠torproject.org 07 Dec '15

07 Dec '15

commit 3500f08a05630d484592f60dcc0b2b2281b6cbca Author: Translation commit bot <translation(a)torproject.org> Date: Mon Dec 7 03:15:59 2015 +0000 Update translations for abouttor-homepage --- nb/aboutTor.dtd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nb/aboutTor.dtd b/nb/aboutTor.dtd index cbac1b6..5b679f6 100644 --- a/nb/aboutTor.dtd +++ b/nb/aboutTor.dtd @@ -49,4 +49,4 @@ <!ENTITY aboutTor.learnMore.link "https://www.torproject.org/about/overview.html.en"> <!ENTITY aboutTor.donate.donate "Doner"> -<!ENTITY aboutTor.donate.supportTor "Please support Tor!"> +<!ENTITY aboutTor.donate.supportTor "Vennligst støtt Tor!">

1 0

[stem/master] Check that we have 'man' for tests
by atagar＠torproject.org 07 Dec '15

07 Dec '15

commit a4fce191c843971991b482fdbb258cc4bcc18cc1 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Dec 6 15:32:30 2015 -0800 Check that we have 'man' for tests On reflection our unit tests will now fail on Windows due to running 'man'. Adding a check for this. --- test/integ/manual.py | 4 ++-- test/unit/manual.py | 11 +++++++++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/test/integ/manual.py b/test/integ/manual.py index c961101..53f9faf 100644 --- a/test/integ/manual.py +++ b/test/integ/manual.py @@ -128,8 +128,8 @@ class TestManual(unittest.TestCase): options. Unlike most other tests this doesn't require network access. """ - if stem.util.system.is_windows(): - test.runner.skip(self, '(unavailable on windows)') # needs to run 'man' + if not stem.util.system.is_available('man'): + test.runner.skip(self, '(require man command)') return manual = stem.manual.Manual.from_man(os.path.join(os.path.dirname(__file__), 'tor.1_with_unknown')) diff --git a/test/unit/manual.py b/test/unit/manual.py index 4d9d539..bb2e2d5 100644 --- a/test/unit/manual.py +++ b/test/unit/manual.py @@ -9,6 +9,9 @@ import unittest import stem.prereq import stem.manual +import stem.util.system + +import test.runner try: # account for urllib's change between python 2.x and 3.x @@ -115,6 +118,10 @@ class TestManual(unittest.TestCase): expand our example (or add another). """ + if not stem.util.system.is_available('man'): + test.runner.skip(self, '(require man command)') + return + manual = stem.manual.Manual.from_man(EXAMPLE_MAN_PATH) self.assertEqual('tor - The second-generation onion router', manual.name) @@ -130,6 +137,10 @@ class TestManual(unittest.TestCase): Check that we can save and reload manuals. """ + if not stem.util.system.is_available('man'): + test.runner.skip(self, '(require man command)') + return + manual = stem.manual.Manual.from_man(EXAMPLE_MAN_PATH) with tempfile.NamedTemporaryFile(prefix = 'saved_test_manual.') as tmp:

1 0

[stem/master] Missing is_available() mocks for unit tests
by atagar＠torproject.org 06 Dec '15

06 Dec '15

commit 734a7ebc496d1aaa6fa0a852a97a2b7232ba6370 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Dec 6 14:42:11 2015 -0800 Missing is_available() mocks for unit tests Our jenkins tests are presently failing in quite a few ways. First addressing some of the easiest ones about a2x not being present... ====================================================================== ERROR: test_download_man_page_when_successful ---------------------------------------------------------------------- Traceback (most recent call last): File "/usr/lib/python2.7/dist-packages/mock.py", line 1224, in patched return func(*args, **keywargs) File "/srv/jenkins-workspace/workspace/stem-tor-ci/test/unit/manual.py", line 214, in test_download_man_page_when_successful stem.manual.download_man_page(file_handle = output) File "/srv/jenkins-workspace/workspace/stem-tor-ci/stem/manual.py", line 196, in download_man_page raise IOError('We require a2x from asciidoc to provide a man page') IOError: We require a2x from asciidoc to provide a man page ====================================================================== FAIL: test_download_man_page_when_a2x_fails ---------------------------------------------------------------------- Traceback (most recent call last): File "/usr/lib/python2.7/dist-packages/mock.py", line 1224, in patched return func(*args, **keywargs) File "/srv/jenkins-workspace/workspace/stem-tor-ci/test/unit/manual.py", line 197, in test_download_man_page_when_a2x_fails self.assertEqual("Unable to run 'a2x -f manpage /no/such/path/tor.1.txt': call failed", str(exc)) AssertionError: "Unable to run 'a2x -f manpage /no/such/path/tor.1.txt': call failed" != 'We require a2x from asciidoc to provide a man page' ====================================================================== FAIL: test_download_man_page_when_download_fails ---------------------------------------------------------------------- Traceback (most recent call last): File "/usr/lib/python2.7/dist-packages/mock.py", line 1224, in patched return func(*args, **keywargs) File "/srv/jenkins-workspace/workspace/stem-tor-ci/test/unit/manual.py", line 185, in test_download_man_page_when_download_fails self.assertEqual("Unable to download tor's manual from https://www.atagar.com/foo/bar to /no/such/path/tor.1.txt: <urlopen error <urlopen error [Errno -2] Name or service not known>>", str(exc)) AssertionError: "Unable to download tor's manual from https://www.atagar.com/foo/bar to /no/such/path/tor.1.txt: <urlopen error <urlopen error [Errno -2] Name or service not known>>" != 'We require a2x from asciidoc to provide a man page' ====================================================================== FAIL: test_download_man_page_when_unable_to_write ---------------------------------------------------------------------- Traceback (most recent call last): File "/usr/lib/python2.7/dist-packages/mock.py", line 1224, in patched return func(*args, **keywargs) File "/srv/jenkins-workspace/workspace/stem-tor-ci/test/unit/manual.py", line 174, in test_download_man_page_when_unable_to_write self.assertEqual("Unable to download tor's manual from https://gitweb.torproject.org/tor.git/plain/doc/tor.1.txt to /no/such/path/tor.1.txt: unable to write to file", str(exc)) AssertionError: "Unable to download tor's manual from https://gitweb.torproject.org/tor.git/plain/doc/tor.1.txt to /no/such/path/tor.1.txt: unable to write to file" != 'We require a2x from asciidoc to provide a man page' --- test/unit/manual.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/test/unit/manual.py b/test/unit/manual.py index 21f578d..4d9d539 100644 --- a/test/unit/manual.py +++ b/test/unit/manual.py @@ -166,6 +166,7 @@ class TestManual(unittest.TestCase): @patch('tempfile.mkdtemp', Mock(return_value = '/no/such/path')) @patch('shutil.rmtree', Mock()) @patch('stem.manual.open', Mock(side_effect = IOError('unable to write to file')), create = True) + @patch('stem.util.system.is_available', Mock(return_value = True)) def test_download_man_page_when_unable_to_write(self): try: stem.manual.download_man_page('/tmp/no_such_file') @@ -176,6 +177,7 @@ class TestManual(unittest.TestCase): @patch('tempfile.mkdtemp', Mock(return_value = '/no/such/path')) @patch('shutil.rmtree', Mock()) @patch('stem.manual.open', Mock(return_value = io.BytesIO()), create = True) + @patch('stem.util.system.is_available', Mock(return_value = True)) @patch(URL_OPEN, Mock(side_effect = urllib.URLError('<urlopen error [Errno -2] Name or service not known>'))) def test_download_man_page_when_download_fails(self): try: @@ -188,6 +190,7 @@ class TestManual(unittest.TestCase): @patch('shutil.rmtree', Mock()) @patch('stem.manual.open', Mock(return_value = io.BytesIO()), create = True) @patch('stem.util.system.call', Mock(side_effect = OSError('call failed'))) + @patch('stem.util.system.is_available', Mock(return_value = True)) @patch(URL_OPEN, Mock(return_value = io.BytesIO(b'test content'))) def test_download_man_page_when_a2x_fails(self): try: @@ -200,6 +203,7 @@ class TestManual(unittest.TestCase): @patch('shutil.rmtree', Mock()) @patch('stem.manual.open', create = True) @patch('stem.util.system.call') + @patch('stem.util.system.is_available', Mock(return_value = True)) @patch('os.path.exists', Mock(return_value = True)) @patch(URL_OPEN, Mock(return_value = io.BytesIO(b'test content'))) def test_download_man_page_when_successful(self, call_mock, open_mock):

1 0

[stem/master] Test that we install all files
by atagar＠torproject.org 06 Dec '15

06 Dec '15

commit b4faa8230304a331babf9cd539121ce57096087c Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Nov 28 17:54:30 2015 -0800 Test that we install all files Few times now we've had bugs (and even releases!) where installation misses files. This is because in our setup.py we need to enumerate all modules and non-source files. This is damn easy to forget. Renaming stem/settings.cfg hit this again so adding a test to ensure it stops happening in the future. --- setup.py | 2 +- test/integ/installation.py | 78 +++++++++++++++++++++++++++++++++++++++----- 2 files changed, 70 insertions(+), 10 deletions(-) diff --git a/setup.py b/setup.py index 002e982..8fb47e6 100644 --- a/setup.py +++ b/setup.py @@ -17,6 +17,6 @@ distutils.core.setup( packages = ['stem', 'stem.descriptor', 'stem.interpreter', 'stem.response', 'stem.util'], keywords = 'tor onion controller', scripts = ['tor-prompt'], - package_data = {'stem': ['manual.cfg'], 'stem.interpreter': ['settings.cfg'], 'stem.util': ['ports.cfg']}, + package_data = {'stem': ['settings.cfg'], 'stem.interpreter': ['settings.cfg'], 'stem.util': ['ports.cfg']}, ) diff --git a/test/integ/installation.py b/test/integ/installation.py index 70a8ad9..6b0f759 100644 --- a/test/integ/installation.py +++ b/test/integ/installation.py @@ -9,27 +9,87 @@ import stem.util.system import test.runner +BASE_DIRECTORY = os.path.sep.join(__file__.split(os.path.sep)[:-3]) + class TestInstallation(unittest.TestCase): - @test.runner.only_run_once - def test_installing_stem(self): - base_directory = os.path.sep.join(__file__.split(os.path.sep)[:-3]) + @classmethod + def setUpClass(self): + self.site_packages_path = None + self.skip_reason = None + self.installation_error = None - if not os.path.exists(os.path.sep.join([base_directory, 'setup.py'])): - test.runner.skip(self, '(only for git checkout)') + if not os.path.exists(os.path.join(BASE_DIRECTORY, 'setup.py')): + self.skip_reason = '(only for git checkout)' original_cwd = os.getcwd() try: - os.chdir(base_directory) + os.chdir(BASE_DIRECTORY) stem.util.system.call(sys.executable + ' setup.py install --prefix /tmp/stem_test') stem.util.system.call(sys.executable + ' setup.py clean --all') # tidy up the build directory site_packages_paths = glob.glob('/tmp/stem_test/lib*/*/site-packages') if len(site_packages_paths) != 1: - self.fail('We should only have a single site-packages directory, but instead had: %s' % site_packages_paths) + self.installation_error = 'We should only have a single site-packages directory, but instead had: %s' % site_packages_paths - self.assertEqual(stem.__version__, stem.util.system.call([sys.executable, '-c', "import sys;sys.path.insert(0, '%s');import stem;print(stem.__version__)" % site_packages_paths[0]])[0]) + self.site_packages_path = site_packages_paths[0] + except Exception as exc: + self.installation_error = 'Unable to download the man page: %s' % exc finally: - shutil.rmtree('/tmp/stem_test') os.chdir(original_cwd) + + @classmethod + def tearDownClass(self): + if os.path.exists('/tmp/stem_test'): + shutil.rmtree('/tmp/stem_test') + + def requires_installation(self): + if self.skip_reason: + test.runner.skip(self, self.skip_reason) + return True + elif self.installation_error: + self.fail(self.installation_error) + + return False + + @test.runner.only_run_once + def test_installing_stem(self): + """ + Attempt to use the package we install. + """ + + if self.requires_installation(): + return + + self.assertEqual(stem.__version__, stem.util.system.call([sys.executable, '-c', "import sys;sys.path.insert(0, '%s');import stem;print(stem.__version__)" % self.site_packages_path])[0]) + + def test_installs_all_files(self): + """ + Check that all the files in the stem directory are present in the + installatnion. This is a very common gotcha since our setup.py + requires us to remember to add new modules and non-source files. + """ + + if self.requires_installation(): + return + + expected, installed = set(), set() + + for root, dirnames, filenames in os.walk(os.path.join(BASE_DIRECTORY, 'stem')): + for filename in filenames: + if not filename.endswith('.pyc'): + expected.add(os.path.join(root, filename)[len(BASE_DIRECTORY) + 1:]) + + for root, dirnames, filenames in os.walk(self.site_packages_path): + for filename in filenames: + if not filename.endswith('.pyc') and not filename.endswith('egg-info'): + installed.add(os.path.join(root, filename)[len(self.site_packages_path) + 1:]) + + missing = expected.difference(installed) + extra = installed.difference(expected) + + if missing: + self.fail("The following files were expected to be in our installation but weren't. Maybe our setup.py needs to be updated?\n\n%s" % '\n'.join(missing)) + elif extra: + self.fail("The following files weren't expected to be in our installation.\n\n%s" % '\n'.join(extra))

1 0

[stem/master] Unit test with a minimal man page
by atagar＠torproject.org 06 Dec '15

06 Dec '15

commit 94cc91695b9f32d7f8c0c2e2789e4804b9d5dd1f Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Nov 29 12:09:54 2015 -0800 Unit test with a minimal man page I backed off from bundling a copy of tor's man page in our tests due to its size (136 KB). However, a trimmed man page sidesteps that while still providing great test coverage. Exercising our parser with a real (but minimal) copy of tor's man page, providing unit test coverage of our parser that's quick to invoke. --- stem/manual.py | 2 +- test/unit/manual.py | 87 +++++++++++++++++ test/unit/tor_man_example | 227 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 315 insertions(+), 1 deletion(-) diff --git a/stem/manual.py b/stem/manual.py index 138380e..868f866 100644 --- a/stem/manual.py +++ b/stem/manual.py @@ -218,7 +218,7 @@ class Manual(object): :var dict signals: mapping of signals tor accepts to their description :var dict files: mapping of file paths to their description - :var dict config_option: :class:`~stem.manual.ConfigOption` tuples for tor configuration options + :var dict config_options: :class:`~stem.manual.ConfigOption` tuples for tor configuration options """ def __init__(self, name, synopsis, description, commandline_options, signals, files, config_options): diff --git a/test/unit/manual.py b/test/unit/manual.py index 1f5ea74..6bed338 100644 --- a/test/unit/manual.py +++ b/test/unit/manual.py @@ -3,6 +3,7 @@ Unit testing for the stem.manual module. """ import io +import os import unittest import stem.prereq @@ -28,6 +29,74 @@ except ImportError: URL_OPEN = 'urllib.request.urlopen' if stem.prereq.is_python_3() else 'urllib2.urlopen' +EXPECTED_DESCRIPTION = 'Tor is a connection-oriented anonymizing communication service. Users choose a source-routed path through a set of nodes, and negotiate a "virtual circuit" through the network, in which each node knows its predecessor and successor, but no others. Traffic flowing down the circuit is unwrapped by a symmetric key at each node, which reveals the downstream node.' + +EXPECTED_CLI_OPTIONS = { + '-f FILE': 'Specify a new configuration file to contain further Tor configuration options OR pass - to make Tor read its configuration from standard input. (Default: @CONFDIR@/torrc, or $HOME/.torrc if that file is not found)', + '-h, -help': 'Display a short help message and exit.', + '--allow-missing-torrc': 'Do not require that configuration file specified by -f exist if default torrc can be accessed.', +} + +EXPECTED_SIGNALS = { + 'SIGHUP': 'The signal instructs Tor to reload its configuration (including closing and reopening logs), and kill and restart its helper processes if applicable.', + 'SIGTERM': 'Tor will catch this, clean up and sync to disk if necessary, and exit.', + 'SIGINT': 'Tor clients behave as with SIGTERM; but Tor servers will do a controlled slow shutdown, closing listeners and waiting 30 seconds before exiting. (The delay can be configured with the ShutdownWaitLength config option.)', +} + +EXPECTED_FILES = { + '@LOCALSTATEDIR@/lib/tor/': 'The tor process stores keys and other data here.', + 'DataDirectory/cached-status/': 'The most recently downloaded network status document for each authority. Each file holds one such document; the filenames are the hexadecimal identity key fingerprints of the directory authorities. Mostly obsolete.', + 'DataDirectory/cached-certs': 'This file holds downloaded directory key certificates that are used to verify authenticity of documents generated by Tor directory authorities.', + 'DataDirectory/state': 'A set of persistent key-value mappings. These are documented in the file. These include: o The current entry guards and their status. o The current bandwidth accounting values (unused so far; see below). o When the file was last written o What version of Tor generated the state file o A short history of bandwidth usage, as produced in the server descriptors.', + '@CONFDIR@/torrc': 'The configuration file, which contains "option value" pairs.', + 'DataDirectory/bw_accounting': "Used to track bandwidth accounting values (when the current period starts and ends; how much has been read and written so far this period). This file is obsolete, and the data is now stored in the 'state' file as well. Only used when bandwidth accounting is enabled.", + '$HOME/.torrc': 'Fallback location for torrc, if @CONFDIR@/torrc is not found.', +} + +EXPECTED_CONFIG_OPTIONS = OrderedDict() + +EXPECTED_CONFIG_OPTIONS['AllowInvalidNodes'] = stem.manual.ConfigOption( + category = 'Client', + name = 'AllowInvalidNodes', + usage = 'entry|exit|middle|introduction|rendezvous|...', + summary = 'Permits use of relays flagged as invalid by authorities', + description = 'If some Tor servers are obviously not working right, the directory authorities can manually mark them as invalid, meaning that it\'s not recommended you use them for entry or exit positions in your circuits. You can opt to use them in some circuit positions, though. The default is "middle,rendezvous", and other choices are not advised.') + +EXPECTED_CONFIG_OPTIONS['ExcludeSingleHopRelays'] = stem.manual.ConfigOption( + category = 'Client', + name = 'ExcludeSingleHopRelays', + usage = '0|1', + summary = 'Permits use of relays that allow single hop connections', + description = 'This option controls whether circuits built by Tor will include relays with the AllowSingleHopExits flag set to true. If ExcludeSingleHopRelays is set to 0, these relays will be included. Note that these relays might be at higher risk of being seized or observed, so they are not normally included. Also note that relatively few clients turn off this option, so using these relays might make your client stand out. (Default: 1)') + +EXPECTED_CONFIG_OPTIONS['Bridge'] = stem.manual.ConfigOption( + category = 'Client', + name = 'Bridge', + usage = '[transport] IP:ORPort [fingerprint]', + summary = 'Available bridges', + description = 'When set along with UseBridges, instructs Tor to use the relay at "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint" is provided (using the same format as for DirAuthority), we will verify that the relay running at that location has the right fingerprint. We also use fingerprint to look up the bridge descriptor at the bridge authority, if it\'s provided and if UpdateBridgesFromAuthority is set too.\n\nIf "transport" is provided, and matches to a ClientTransportPlugin line, we use that pluggable transports proxy to transfer data to the bridge.') + +EXPECTED_CONFIG_OPTIONS['BandwidthRate'] = stem.manual.ConfigOption( + category = 'General', + name = 'BandwidthRate', + usage = 'N bytes|KBytes|MBytes|GBytes|KBits|MBits|GBits', + summary = 'Average bandwidth usage limit', + description = 'A token bucket limits the average incoming bandwidth usage on this node to the specified number of bytes per second, and the average outgoing bandwidth usage to that same value. If you want to run a relay in the public network, this needs to be at the very least 75 KBytes for a relay (that is, 600 kbits) or 50 KBytes for a bridge (400 kbits) -- but of course, more is better; we recommend at least 250 KBytes (2 mbits) if possible. (Default: 1 GByte)\n\nWith this option, and in other options that take arguments in bytes, KBytes, and so on, other formats are also supported. Notably, "KBytes" can also be written as "kilobytes" or "kb"; "MBytes" can be written as "megabytes" or "MB"; "kbits" can be written as "kilobits"; and so forth. Tor also accepts "byte" and "bit" in the singular. The prefixes "tera" and "T" are also recognized. If no units are given, we default to bytes. To avoid confusion, we recommend writing "bytes" or "bits" explicitly, since it\'s easy to forge t that "B" means bytes, not bits.') + +EXPECTED_CONFIG_OPTIONS['BandwidthBurst'] = stem.manual.ConfigOption( + category = 'General', + name = 'BandwidthBurst', + usage = 'N bytes|KBytes|MBytes|GBytes|KBits|MBits|GBits', + summary = 'Maximum bandwidth usage limit', + description = 'Limit the maximum token bucket size (also known as the burst) to the given number of bytes in each direction. (Default: 1 GByte)') + +EXPECTED_CONFIG_OPTIONS['MaxAdvertisedBandwidth'] = stem.manual.ConfigOption( + category = 'General', + name = 'MaxAdvertisedBandwidth', + usage = 'N bytes|KBytes|MBytes|GBytes|KBits|MBits|GBits', + summary = 'Limit for the bandwidth we advertise as being available for relaying', + description = 'If set, we will not advertise more than this amount of bandwidth for our BandwidthRate. Server operators who want to reduce the number of clients who ask to build circuits through them (since this is proportional to advertised bandwidth rate) can thus reduce the CPU demands on their server without impacting network performance.') + class TestManual(unittest.TestCase): def test_is_important(self): @@ -37,6 +106,24 @@ class TestManual(unittest.TestCase): self.assertFalse(stem.manual.is_important('ConstrainedSockSize')) + def test_parsing_example_man_page(self): + """ + Read a trimmed copy of tor's man page. This gives a good exercise of our + parser with static content. As new oddball man oddities appear feel free to + expand our example (or add another). + """ + + man_path = os.path.join(os.path.dirname(__file__), 'tor_man_example') + manual = stem.manual.Manual.from_man(man_path) + + self.assertEqual('tor - The second-generation onion router', manual.name) + self.assertEqual('tor [OPTION value]...', manual.synopsis) + self.assertEqual(EXPECTED_DESCRIPTION, manual.description) + self.assertEqual(EXPECTED_CLI_OPTIONS, manual.commandline_options) + self.assertEqual(EXPECTED_SIGNALS, manual.signals) + self.assertEqual(EXPECTED_FILES, manual.files) + self.assertEqual(EXPECTED_CONFIG_OPTIONS, manual.config_options) + def test_download_man_page_without_arguments(self): try: stem.manual.download_man_page() diff --git a/test/unit/tor_man_example b/test/unit/tor_man_example new file mode 100644 index 0000000..c6116f6 --- /dev/null +++ b/test/unit/tor_man_example @@ -0,0 +1,227 @@ +'\" t +.\" Title: tor +.\" Author: [see the "AUTHORS" section] +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> +.\" Date: 11/29/2015 +.\" Manual: Tor Manual +.\" Source: Tor +.\" Language: English +.\" +.TH "TOR" "1" "11/29/2015" "Tor" "Tor Manual" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +tor \- The second\-generation onion router +.SH "SYNOPSIS" +.sp +\fBtor\fR [\fIOPTION\fR \fIvalue\fR]\&... +.SH "DESCRIPTION" +.sp +Tor is a connection\-oriented anonymizing communication service\&. Users choose a source\-routed path through a set of nodes, and negotiate a "virtual circuit" through the network, in which each node knows its predecessor and successor, but no others\&. Traffic flowing down the circuit is unwrapped by a symmetric key at each node, which reveals the downstream node\&. +.SH "COMMAND-LINE OPTIONS" +.PP +\fB\-h\fR, \fB\-help\fR +.RS 4 +Display a short help message and exit\&. +.RE +.PP +\fB\-f\fR \fIFILE\fR +.RS 4 +Specify a new configuration file to contain further Tor configuration options OR pass +\fB\-\fR +to make Tor read its configuration from standard input\&. (Default: @CONFDIR@/torrc, or $HOME/\&.torrc if that file is not found) +.RE +.PP +\fB\-\-allow\-missing\-torrc\fR +.RS 4 +Do not require that configuration file specified by +\fB\-f\fR +exist if default torrc can be accessed\&. +.RE +.PP +.sp +Options on the command line override those in configuration files\&. See the next section for more information\&. +.SH "THE CONFIGURATION FILE FORMAT" +.sp +All configuration options in a configuration are written on a single line by default\&. They take the form of an option name and a value, or an option name and a quoted value (option value or option "value")\&. Anything after a # character is treated as a comment\&. Options are case\-insensitive\&. C\-style escaped characters are allowed inside quoted values\&. To split one configuration entry into multiple lines, use a single backslash character (\e) before the end of the line\&. Comments can be used in such multiline entries, but they must start at the beginning of a line\&. +.sp +By default, an option on the command line overrides an option found in the configuration file, and an option in a configuration file overrides one in the defaults file\&. +.SH "GENERAL OPTIONS" +.PP +\fBBandwidthRate\fR \fIN\fR \fBbytes\fR|\fBKBytes\fR|\fBMBytes\fR|\fBGBytes\fR|\fBKBits\fR|\fBMBits\fR|\fBGBits\fR +.RS 4 +A token bucket limits the average incoming bandwidth usage on this node to the specified number of bytes per second, and the average outgoing bandwidth usage to that same value\&. If you want to run a relay in the public network, this needs to be +\fIat the very least\fR +75 KBytes for a relay (that is, 600 kbits) or 50 KBytes for a bridge (400 kbits) \(em but of course, more is better; we recommend at least 250 KBytes (2 mbits) if possible\&. (Default: 1 GByte) + +With this option, and in other options that take arguments in bytes, KBytes, and so on, other formats are also supported\&. Notably, "KBytes" can also be written as "kilobytes" or "kb"; "MBytes" can be written as "megabytes" or "MB"; "kbits" can be written as "kilobits"; and so forth\&. Tor also accepts "byte" and "bit" in the singular\&. The prefixes "tera" and "T" are also recognized\&. If no units are given, we default to bytes\&. To avoid confusion, we recommend writing "bytes" or "bits" explicitly, since it\(cqs easy to forget that "B" means bytes, not bits\&. +.RE +.PP +\fBBandwidthBurst\fR \fIN\fR \fBbytes\fR|\fBKBytes\fR|\fBMBytes\fR|\fBGBytes\fR|\fBKBits\fR|\fBMBits\fR|\fBGBits\fR +.RS 4 +Limit the maximum token bucket size (also known as the burst) to the given number of bytes in each direction\&. (Default: 1 GByte) +.RE +.PP +\fBMaxAdvertisedBandwidth\fR \fIN\fR \fBbytes\fR|\fBKBytes\fR|\fBMBytes\fR|\fBGBytes\fR|\fBKBits\fR|\fBMBits\fR|\fBGBits\fR +.RS 4 +If set, we will not advertise more than this amount of bandwidth for our BandwidthRate\&. Server operators who want to reduce the number of clients who ask to build circuits through them (since this is proportional to advertised bandwidth rate) can thus reduce the CPU demands on their server without impacting network performance\&. +.RE +.SH "CLIENT OPTIONS" +.sp +The following options are useful only for clients (that is, if \fBSocksPort\fR, \fBTransPort\fR, \fBDNSPort\fR, or \fBNATDPort\fR is non\-zero): +.PP +\fBAllowInvalidNodes\fR \fBentry\fR|\fBexit\fR|\fBmiddle\fR|\fBintroduction\fR|\fBrendezvous\fR|\fB\&...\fR +.RS 4 +If some Tor servers are obviously not working right, the directory authorities can manually mark them as invalid, meaning that it\(cqs not recommended you use them for entry or exit positions in your circuits\&. You can opt to use them in some circuit positions, though\&. The default is "middle,rendezvous", and other choices are not advised\&. +.RE +.PP +\fBExcludeSingleHopRelays\fR \fB0\fR|\fB1\fR +.RS 4 +This option controls whether circuits built by Tor will include relays with the AllowSingleHopExits flag set to true\&. If ExcludeSingleHopRelays is set to 0, these relays will be included\&. Note that these relays might be at higher risk of being seized or observed, so they are not normally included\&. Also note that relatively few clients turn off this option, so using these relays might make your client stand out\&. (Default: 1) +.RE +.PP +\fBBridge\fR [\fItransport\fR] \fIIP\fR:\fIORPort\fR [\fIfingerprint\fR] +.RS 4 +When set along with UseBridges, instructs Tor to use the relay at "IP:ORPort" as a "bridge" relaying into the Tor network\&. If "fingerprint" is provided (using the same format as for DirAuthority), we will verify that the relay running at that location has the right fingerprint\&. We also use fingerprint to look up the bridge descriptor at the bridge authority, if it\(cqs provided and if UpdateBridgesFromAuthority is set too\&. + +If "transport" is provided, and matches to a ClientTransportPlugin line, we use that pluggable transports proxy to transfer data to the bridge\&. +.RE +.SH "SIGNALS" +.sp +Tor catches the following signals: +.PP +\fBSIGTERM\fR +.RS 4 +Tor will catch this, clean up and sync to disk if necessary, and exit\&. +.RE +.PP +\fBSIGINT\fR +.RS 4 +Tor clients behave as with SIGTERM; but Tor servers will do a controlled slow shutdown, closing listeners and waiting 30 seconds before exiting\&. (The delay can be configured with the ShutdownWaitLength config option\&.) +.RE +.PP +\fBSIGHUP\fR +.RS 4 +The signal instructs Tor to reload its configuration (including closing and reopening logs), and kill and restart its helper processes if applicable\&. +.RE +.SH "FILES" +.PP +\fB@CONFDIR@/torrc\fR +.RS 4 +The configuration file, which contains "option value" pairs\&. +.RE +.PP +\fB$HOME/\&.torrc\fR +.RS 4 +Fallback location for torrc, if @CONFDIR@/torrc is not found\&. +.RE +.PP +\fB@LOCALSTATEDIR@/lib/tor/\fR +.RS 4 +The tor process stores keys and other data here\&. +.RE +.PP +\fIDataDirectory\fR\fB/cached\-status/\fR +.RS 4 +The most recently downloaded network status document for each authority\&. Each file holds one such document; the filenames are the hexadecimal identity key fingerprints of the directory authorities\&. Mostly obsolete\&. +.RE +.PP +\fIDataDirectory\fR\fB/cached\-certs\fR +.RS 4 +This file holds downloaded directory key certificates that are used to verify authenticity of documents generated by Tor directory authorities\&. +.RE +.PP +\fIDataDirectory\fR\fB/state\fR +.RS 4 +A set of persistent key\-value mappings\&. These are documented in the file\&. These include: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The current entry guards and their status\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The current bandwidth accounting values (unused so far; see below)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +When the file was last written +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +What version of Tor generated the state file +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A short history of bandwidth usage, as produced in the server descriptors\&. +.RE +.RE +.PP +\fIDataDirectory\fR\fB/bw_accounting\fR +.RS 4 +Used to track bandwidth accounting values (when the current period starts and ends; how much has been read and written so far this period)\&. This file is obsolete, and the data is now stored in the \*(Aqstate\*(Aq file as well\&. Only used when bandwidth accounting is enabled\&. +.RE +.SH "SEE ALSO" +.sp +\fBtorsocks\fR(1), \fBtorify\fR(1) +.sp +\fBhttps://www\&.torproject\&.org/\fR +.sp +\fBtorspec: \fR\fBhttps://spec\&.torproject\&.org\fR\fB \fR +.SH "BUGS" +.sp +Plenty, probably\&. Tor is still in development\&. Please report them at https://trac\&.torproject\&.org/\&. +.SH "AUTHORS" +.sp +Roger Dingledine [arma at mit\&.edu] Nick Mathewson [nickm at alum\&.mit\&.edu]\&.

1 0

[stem/master] Accept Config.set() to allow unicode
by atagar＠torproject.org 06 Dec '15

06 Dec '15

commit 08be7a955f8c0c3de1d7409a810d6225943fcc9f Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Nov 29 12:40:53 2015 -0800 Accept Config.set() to allow unicode Oops, type checking didn't include unicode strings... Traceback (most recent call last): File "scrap.py", line 4, in <module> manual.save('/home/atagar/Desktop/output') File "/home/atagar/Desktop/stem/stem/manual.py", line 314, in save conf.set('name', self.name) File "/home/atagar/Desktop/stem/stem/util/conf.py", line 641, in set raise ValueError("Config.set() only accepts str, list, or tuple. Provided value was a '%s'" % type(value)) ValueError: Config.set() only accepts str, list, or tuple. Provided value was a '<type 'unicode'>' Obviously something we want to allow. --- stem/util/conf.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/stem/util/conf.py b/stem/util/conf.py index 92be685..22cf1c7 100644 --- a/stem/util/conf.py +++ b/stem/util/conf.py @@ -161,6 +161,8 @@ import inspect import os import threading +import stem.prereq + from stem.util import log try: @@ -621,7 +623,9 @@ class Config(object): """ with self._contents_lock: - if isinstance(value, str): + unicode_type = str if stem.prereq.is_python_3() else unicode + + if isinstance(value, bytes) or isinstance(value, unicode_type): if not overwrite and key in self._contents: self._contents[key].append(value) else: @@ -638,7 +642,7 @@ class Config(object): for listener in self._listeners: listener(self, key) else: - raise ValueError("Config.set() only accepts str, list, or tuple. Provided value was a '%s'" % type(value)) + raise ValueError("Config.set() only accepts str (bytes or unicode), list, or tuple. Provided value was a '%s'" % type(value)) def get(self, key, default = None): """

1 0

[stem/master] Misparesed descriptions with indented lines
by atagar＠torproject.org 06 Dec '15

06 Dec '15

commit afa0d29e24a36f457a23309b998775f79f6afe8b Author: Damian Johnson <atagar(a)torproject.org> Date: Fri Dec 4 09:37:27 2015 -0800 Misparesed descriptions with indented lines Our parser mishandled config option descriptions with indented lines, like the ExitPolicy. Trouble was that we only added newlines when there's an empty line. --- stem/manual.py | 8 ++++---- test/integ/manual.py | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 4 deletions(-) diff --git a/stem/manual.py b/stem/manual.py index 60ffc25..ee800c4 100644 --- a/stem/manual.py +++ b/stem/manual.py @@ -523,9 +523,9 @@ def _join_lines(lines): for line in lines: if not line: - if result and result[-1] != '\n\n': - result.append('\n\n') + if result and result[-1] != '\n': + result.append('\n') else: - result.append(line) + result.append(line + '\n') - return ''.join(result) + return ''.join(result).strip() diff --git a/test/integ/manual.py b/test/integ/manual.py index ddb007c..d3fb19d 100644 --- a/test/integ/manual.py +++ b/test/integ/manual.py @@ -50,6 +50,40 @@ EXPECTED_FILE_DESCRIPTION = 'Specify a new configuration file to contain further EXPECTED_BANDWIDTH_RATE_DESCRIPTION = 'A token bucket limits the average incoming bandwidth usage on this node to the specified number of bytes per second, and the average outgoing bandwidth usage to that same value. If you want to run a relay in the public network, this needs to be at the very least 75 KBytes for a relay (that is, 600 kbits) or 50 KBytes for a bridge (400 kbits) -- but of course, more is better; we recommend at least 250 KBytes (2 mbits) if possible. (Default: 1 GByte)\n\nWith this option, and in other options that take arguments in bytes, KBytes, and so on, other formats are also supported. Notably, "KBytes" can also be written as "kilobytes" or "kb"; "MBytes" can be written as "megabytes" or "MB"; "kbits" can be written as "kilobits"; and so forth. Tor also accepts "byte" and "bit" in the singular. The prefixes "tera" and "T" are also recognized. If no units are given, we default to bytes. To avoid confusion, we recommend writing "bytes" or "bits" explicitly, sin ce it\'s easy to forget that "B" means bytes, not bits.' +EXPECTED_EXIT_POLICY_DESCRIPTION = """\ +Set an exit policy for this server. Each policy is of the form "accept[6]|reject[6] ADDR[/MASK][:PORT]". If /MASK is omitted then this policy just applies to the host given. Instead of giving a host or network you can also use "*" to denote the universe (0.0.0.0/0 and ::/128), or *4 to denote all IPv4 addresses, and *6 to denote all IPv6 addresses. PORT can be a single port number, an interval of ports "FROM_PORT-TO_PORT", or "*". If PORT is omitted, that means "*". + +For example, "accept 18.7.22.69:*,reject 18.0.0.0/8:*,accept *:*" would reject any IPv4 traffic destined for MIT except for web.mit.edu, and accept any other IPv4 or IPv6 traffic. + +Tor also allows IPv6 exit policy entries. For instance, "reject6 [FC00::]/7:*" rejects all destinations that share 7 most significant bit prefix with address FC00::. Respectively, "accept6 [C000::]/3:*" accepts all destinations that share 3 most significant bit prefix with address C000::. + +accept6 and reject6 only produce IPv6 exit policy entries. Using an IPv4 address with accept6 or reject6 is ignored and generates a warning. accept/reject allows either IPv4 or IPv6 addresses. Use *4 as an IPv4 wildcard address, and *6 as an IPv6 wildcard address. accept/reject * expands to matching IPv4 and IPv6 wildcard address rules. + +To specify all IPv4 and IPv6 internal and link-local networks (including 0.0.0.0/8, 169.254.0.0/16, 127.0.0.0/8, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, [::]/8, [FC00::]/7, [FE80::]/10, [FEC0::]/10, [FF00::]/8, and [::]/127), you can use the "private" alias instead of an address. ("private" always produces rules for IPv4 and IPv6 addresses, even when used with accept6/reject6.) + +Private addresses are rejected by default (at the beginning of your exit policy), along with any configured primary public IPv4 and IPv6 addresses, and any public IPv4 and IPv6 addresses on any interface on the relay. These private addresses are rejected unless you set the ExitPolicyRejectPrivate config option to 0. For example, once you've done that, you could allow HTTP to 127.0.0.1 and block all other connections to internal networks with "accept 127.0.0.1:80,reject private:*", though that may also allow connections to your own computer that are addressed to its public (external) IP address. See RFC 1918 and RFC 3330 for more details about internal and reserved IP address space. + +This directive can be specified multiple times so you don't have to put it all on one line. + +Policies are considered first to last, and the first match wins. If you want to allow the same ports on IPv4 and IPv6, write your rules using accept/reject *. If you want to allow different ports on IPv4 and IPv6, write your IPv6 rules using accept6/reject6 *6, and your IPv4 rules using accept/reject *4. If you want to _replace_ the default exit policy, end your exit policy with either a reject *:* or an accept *:*. Otherwise, you're _augmenting_ (prepending to) the default exit policy. The default exit policy is: + + reject *:25 + reject *:119 + reject *:135-139 + reject *:445 + reject *:563 + reject *:1214 + reject *:4661-4666 + reject *:6346-6429 + reject *:6699 + reject *:6881-6999 + accept *:* + + Since the default exit policy uses accept/reject *, it applies to both + IPv4 and IPv6 addresses.\ +""" + + class TestManual(unittest.TestCase): @classmethod def setUpClass(self): @@ -141,6 +175,18 @@ class TestManual(unittest.TestCase): for line in lines: check(line) + def test_parsing_with_indented_lines(self): + """ + Our ExitPolicy's description is an interesting one for our parser in that + it has indented lines within it. Ensure we parse this correctly. + """ + + if self.requires_downloaded_manual(): + return + + manual = stem.manual.Manual.from_man(self.man_path) + self.assertEqual(EXPECTED_EXIT_POLICY_DESCRIPTION, manual.config_options['ExitPolicy'].description) + def test_that_cache_is_up_to_date(self): """ Check if the cached manual information bundled with Stem is up to date or not.

1 0

[stem/master] Consolidate manual newlines
by atagar＠torproject.org 06 Dec '15

06 Dec '15

commit e078c7881265c2b5a84d22d02572625d887f3aee Author: Damian Johnson <atagar(a)torproject.org> Date: Tue Dec 1 09:52:57 2015 -0800 Consolidate manual newlines When we have a man entry that's 'pretty\n\n\nflowers' we want to treat all those newlines as a single one. Previously we replaced each with two new newlines, making it... 'pretty\n\n\n\n\n\nflowers' Unsure why the tests passed on my netbook but oh well. *shrug* --- stem/manual.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/stem/manual.py b/stem/manual.py index 975ac1a..60ffc25 100644 --- a/stem/manual.py +++ b/stem/manual.py @@ -519,4 +519,13 @@ def _join_lines(lines): Simple join, except we want empty lines to still provide a newline. """ - return ''.join([line if line else '\n\n' for line in lines]) + result = [] + + for line in lines: + if not line: + if result and result[-1] != '\n\n': + result.append('\n\n') + else: + result.append(line) + + return ''.join(result)

1 0

[stem/master] Ignore vim swap files for installation integ test
by atagar＠torproject.org 06 Dec '15

06 Dec '15

commit ffa61f8b1a6952fd85f27b4b9bea44abe4ef9bdb Author: Damian Johnson <atagar(a)torproject.org> Date: Tue Dec 1 09:55:27 2015 -0800 Ignore vim swap files for installation integ test We have a new test that asserts that everything in the stem directory gets installed. Vim swap files are an obvious exception - ignoring those... ====================================================================== FAIL: test_installs_all_files ---------------------------------------------------------------------- Traceback (most recent call last): File "/home/atagar/Desktop/stem/test/integ/installation.py", line 93, in test_installs_all_files self.fail("The following files were expected to be in our installation but weren't. Maybe our setup.py needs to be updated?\n\n%s" % '\n'.join(missing)) AssertionError: The following files were expected to be in our installation but weren't. Maybe our setup.py needs to be updated? stem/.manual.py.swp ---------------------------------------------------------------------- Ran 2 tests in 0.432s --- test/integ/installation.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/integ/installation.py b/test/integ/installation.py index 6b0f759..986fb3c 100644 --- a/test/integ/installation.py +++ b/test/integ/installation.py @@ -78,7 +78,7 @@ class TestInstallation(unittest.TestCase): for root, dirnames, filenames in os.walk(os.path.join(BASE_DIRECTORY, 'stem')): for filename in filenames: - if not filename.endswith('.pyc'): + if not filename.endswith('.pyc') and not filename.endswith('.swp'): expected.add(os.path.join(root, filename)[len(BASE_DIRECTORY) + 1:]) for root, dirnames, filenames in os.walk(self.site_packages_path):

1 0

[stem/master] Preserve config ordering when saving
by atagar＠torproject.org 06 Dec '15

06 Dec '15

commit 50bdfe192da3d279a5e21e6d466c189934995c7e Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Nov 29 15:59:44 2015 -0800 Preserve config ordering when saving Saving the config contents in the order that the entries were added. This is important in case the caller cares about preserving ordering. --- stem/util/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/stem/util/conf.py b/stem/util/conf.py index 22cf1c7..3c97058 100644 --- a/stem/util/conf.py +++ b/stem/util/conf.py @@ -452,7 +452,7 @@ class Config(object): def __init__(self): self._path = None # location we last loaded from or saved to - self._contents = {} # configuration key/value pairs + self._contents = OrderedDict() # configuration key/value pairs self._listeners = [] # functors to be notified of config changes # used for accessing _contents @@ -549,7 +549,7 @@ class Config(object): with self._contents_lock: with open(self._path, 'w') as output_file: - for entry_key in sorted(self.keys()): + for entry_key in self.keys(): for entry_value in self.get_value(entry_key, multiple = True): # check for multi line entries if '\n' in entry_value:

1 0