August 2014 - tor-commits - lists.torproject.org

[tor/master] Merge remote-tracking branch 'origin/maint-0.2.5'
by nickm＠torproject.org 28 Aug '14

28 Aug '14

commit cc3b04a8c1edbeb1a488e319e3c0d28acd227417 Merge: 9f9b19e 37a76d7 Author: Nick Mathewson <nickm(a)torproject.org> Date: Thu Aug 28 08:36:00 2014 -0400 Merge remote-tracking branch 'origin/maint-0.2.5' changes/bug12948 | 8 ++++++++ src/or/config.c | 3 ++- 2 files changed, 10 insertions(+), 1 deletion(-)

1 0

[tor/maint-0.2.5] Resume expanding abbreviations for command-line options
by nickm＠torproject.org 28 Aug '14

28 Aug '14

commit 37a76d75dd38a1ebd45627bb6e29e40f60917188 Author: Roger Dingledine <arma(a)torproject.org> Date: Wed Aug 27 06:10:35 2014 -0400 Resume expanding abbreviations for command-line options The fix for bug 4647 accidentally removed our hack from bug 586 that rewrote HashedControlPassword to __HashedControlSessionPassword when it appears on the commandline (which allowed the user to set her own HashedControlPassword in the torrc file while the controller generates a fresh session password for each run). Fixes bug 12948; bugfix on 0.2.5.1-alpha. --- changes/bug12948 | 8 ++++++++ src/or/config.c | 3 ++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/changes/bug12948 b/changes/bug12948 new file mode 100644 index 0000000..431c0a1 --- /dev/null +++ b/changes/bug12948 @@ -0,0 +1,8 @@ + o Major bugfixes: + - Resume expanding abbreviations for command-line options. The fix + for bug 4647 accidentally removed our hack from bug 586 that rewrote + HashedControlPassword to __HashedControlSessionPassword when it + appears on the commandline (which allowed the user to set her + own HashedControlPassword in the torrc file while the controller + generates a fresh session password for each run). Fixes bug 12948; + bugfix on 0.2.5.1-alpha. diff --git a/src/or/config.c b/src/or/config.c index 6bb6209..921503b 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -1932,7 +1932,8 @@ config_parse_commandline(int argc, char **argv, int ignore_errors, } param = tor_malloc_zero(sizeof(config_line_t)); - param->key = is_cmdline ? tor_strdup(argv[i]) : tor_strdup(s); + param->key = is_cmdline ? tor_strdup(argv[i]) : + tor_strdup(config_expand_abbrev(&options_format, s, 1, 1)); param->value = arg; param->command = command; param->next = NULL;

1 0

[translation/torbutton-branddtd_completed] Update translations for torbutton-branddtd_completed
by translation＠torproject.org 28 Aug '14

28 Aug '14

commit 50a8082a6faa205057646c2223581c5d49b9e4ea Author: Translation commit bot <translation(a)torproject.org> Date: Thu Aug 28 12:15:44 2014 +0000 Update translations for torbutton-branddtd_completed --- ta/brand.dtd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ta/brand.dtd b/ta/brand.dtd index e7a92a4..992ee8f 100644 --- a/ta/brand.dtd +++ b/ta/brand.dtd @@ -5,4 +5,4 @@ <!ENTITY brandShortName "Torஉலாவி"> <!ENTITY brandFullName "Tor உலாவி"> <!ENTITY vendorShortName "Tor திட்டம்"> -<!ENTITY trademarkInfo.part1 "பையர்பாக்ஸ் மற்றும் பையர்பாக்ஸ் சின்னங்கள் மோசில்லா அறக்கட்டளையின் வர்த்தகமுத்திரைகளாகும்."> +<!ENTITY trademarkInfo.part1 "பையர்பாக்ஸ் பையர்பாக்ஸ் சின்னங்கள் ஆகியன மோசில்லா அறக்கட்டளையின் வணிக முத்திரைகளாகும்.">

1 0

[translation/torbutton-branddtd] Update translations for torbutton-branddtd
by translation＠torproject.org 28 Aug '14

28 Aug '14

commit e4123315dbbfcc4b2395cf503784fa97292dc1bd Author: Translation commit bot <translation(a)torproject.org> Date: Thu Aug 28 12:15:40 2014 +0000 Update translations for torbutton-branddtd --- ta/brand.dtd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ta/brand.dtd b/ta/brand.dtd index e7a92a4..992ee8f 100644 --- a/ta/brand.dtd +++ b/ta/brand.dtd @@ -5,4 +5,4 @@ <!ENTITY brandShortName "Torஉலாவி"> <!ENTITY brandFullName "Tor உலாவி"> <!ENTITY vendorShortName "Tor திட்டம்"> -<!ENTITY trademarkInfo.part1 "பையர்பாக்ஸ் மற்றும் பையர்பாக்ஸ் சின்னங்கள் மோசில்லா அறக்கட்டளையின் வர்த்தகமுத்திரைகளாகும்."> +<!ENTITY trademarkInfo.part1 "பையர்பாக்ஸ் பையர்பாக்ஸ் சின்னங்கள் ஆகியன மோசில்லா அறக்கட்டளையின் வணிக முத்திரைகளாகும்.">

1 0

[bridgedb/develop] Add BridgeDB's new rst README to the Sphinx developer doc builds.
by isis＠torproject.org 28 Aug '14

28 Aug '14

commit 63e280af4f136428277549d611bee0a20f8297c6 Author: Isis Lovecruft <isis(a)torproject.org> Date: Thu Aug 28 11:15:56 2014 +0000 Add BridgeDB's new rst README to the Sphinx developer doc builds. --- doc/sphinx/source/index.rst | 9 +++++++++ doc/sphinx/source/readme.rst | 2 ++ 2 files changed, 11 insertions(+) diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst index 06eeac8..02f50ad 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/sphinx/source/index.rst @@ -28,6 +28,15 @@ BridgeDB Package and Module Documentation: bridgedb +^^^^^^^^^^^^^^^^^ +BridgeDB's README +^^^^^^^^^^^^^^^^^ +.. toctree:: + :maxdepth: 3 + + readme + + Help Us Develop BridgeDB! ========================= diff --git a/doc/sphinx/source/readme.rst b/doc/sphinx/source/readme.rst new file mode 100644 index 0000000..2b7c6f7 --- /dev/null +++ b/doc/sphinx/source/readme.rst @@ -0,0 +1,2 @@ + +.. include:: ../../../README.rst

1 0

[bridgedb/develop] Add an image to the head of the developer documentation.
by isis＠torproject.org 28 Aug '14

28 Aug '14

commit 9c2b7cea6bdc33baf57cfb93cbcd0ab45676215b Author: Isis Lovecruft <isis(a)torproject.org> Date: Thu Aug 28 11:15:06 2014 +0000 Add an image to the head of the developer documentation. --- doc/sphinx/source/index.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst index 70edc17..06eeac8 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/sphinx/source/index.rst @@ -6,6 +6,10 @@ Welcome to BridgeDB's documentation! ==================================== +.. image:: _static/bay-bridge.jpg + :align: center + + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Tor Bridge Descriptor Formats: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1 0

[bridgedb/develop] Fix docstring for bridgedb.email.EmailResponse.
by isis＠torproject.org 28 Aug '14

28 Aug '14

commit 54d4d831841cee3b10b6d4ec57faf62da8faa9c1 Author: Isis Lovecruft <isis(a)torproject.org> Date: Thu Aug 28 11:16:56 2014 +0000 Fix docstring for bridgedb.email.EmailResponse. --- lib/bridgedb/email/autoresponder.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/bridgedb/email/autoresponder.py b/lib/bridgedb/email/autoresponder.py index 44f4079..3f53e6e 100644 --- a/lib/bridgedb/email/autoresponder.py +++ b/lib/bridgedb/email/autoresponder.py @@ -181,13 +181,12 @@ class EmailResponse(object): keyfile, for example, rather than simply pasting it into the body of the email.) - :cvar _buff: (unicode or buffer) Used internally to write lines for the + :var _buff: (unicode or buffer) Used internally to write lines for the response email into the ``_mailfile``. The reason why both of these attributes have two possible types is for the same Python-buggy reasons which require :data:`~bridgedb.crypto.NEW_BUFFER_INTERFACE`. - :cvar mailfile: (:class:`io.StringIO` or :class:`io.BytesIO`) An in-memory + :var mailfile: (:class:`io.StringIO` or :class:`io.BytesIO`) An in-memory file for storing the formatted headers and body of the response email. - :var str delimiter: Delimiter between lines written to the :data:`mailfile`. :var bool closed: ``True`` if :meth:`close` has been called.

1 0

[bridgedb/develop] Add Sphinx source file for bridgedb.bridgerequest documentation.
by isis＠torproject.org 28 Aug '14

28 Aug '14

commit eb4226569ae87f3a8f6cbc9d22125b80027efb4c Author: Isis Lovecruft <isis(a)torproject.org> Date: Thu Aug 28 08:43:37 2014 +0000 Add Sphinx source file for bridgedb.bridgerequest documentation. --- doc/sphinx/source/bridgedb.bridgerequest.rst | 8 ++++++++ doc/sphinx/source/bridgedb.rst | 1 + 2 files changed, 9 insertions(+) diff --git a/doc/sphinx/source/bridgedb.bridgerequest.rst b/doc/sphinx/source/bridgedb.bridgerequest.rst new file mode 100644 index 0000000..d4ad663 --- /dev/null +++ b/doc/sphinx/source/bridgedb.bridgerequest.rst @@ -0,0 +1,8 @@ +bridgedb.bridgerequest +---------------------- + +.. automodule:: bridgedb.bridgerequest + :members: + :undoc-members: + :private-members: + :show-inheritance: diff --git a/doc/sphinx/source/bridgedb.rst b/doc/sphinx/source/bridgedb.rst index ab14ead..ffac1fd 100644 --- a/doc/sphinx/source/bridgedb.rst +++ b/doc/sphinx/source/bridgedb.rst @@ -6,6 +6,7 @@ BridgeDB Package and Module Documentation .. autosummary:: :toctree: + bridgedb.bridgerequest bridgedb.Bridges bridgedb.Bucket bridgedb.captcha

1 0

[bridgedb/develop] Convert README from Markdown to ReStructuredText.
by isis＠torproject.org 28 Aug '14

28 Aug '14

commit cf99f14dc0029a980e184d7035b8a55c3ea89d03 Author: Isis Lovecruft <isis(a)torproject.org> Date: Thu Aug 28 06:28:14 2014 +0000 Convert README from Markdown to ReStructuredText. --- README | 277 -------------------- README.md | 1 - README.rst | 422 ++++++++++++++++++++++++++++++ doc/sphinx/source/_static/bay-bridge.jpg | Bin 0 -> 113187 bytes 4 files changed, 422 insertions(+), 278 deletions(-) diff --git a/README b/README deleted file mode 100644 index 2a2fa81..0000000 --- a/README +++ /dev/null @@ -1,277 +0,0 @@ -## BridgeDB [![Build Status](https://travis-ci.org/isislovecruft/bridgedb.svg)](https://travis-c… [![Coverage Status](https://coveralls.io/repos/isislovecruft/bridgedb/badge.png)](https://coveralls.io/r/isislovecruft/bridgedb) - -BridgeDB is a collection of backend servers used to distribute -[Tor Bridges](https://www.torproject.org/docs/bridges). It currently consists -of a webserver with [an HTTPS interface](https://bridges.torproject.org), an -email responder, and an SQLite database. - -#### What are Tor Bridges? -[Tor Bridges](https://www.torproject.org/docs/bridges) are special Tor relays -which are not listed in the public relay directory. They are used to help -circumvent [censorship](https://ooni.torproject.org) by providing users with -connections to the public relays in the Tor network. - -Tor Bridges are different from normal relays in another important way: they -can run what are called *Pluggable* *Transports*. - -#### What's a Pluggable Transport? -A -[Pluggable Transport](https://www.torproject.org/docs/pluggable-transports.html.en) -is a program which is *pluggable* — meaning that it is meant to work with lots -of other anonymity and censorship circumvention software, not just Tor — and -is a *transport* — meaning that it transports your internet traffic, usually -in a way which makes it look different. For example, -[Obfsproxy](https://www.torproject.org/projects/obfsproxy.html.en) is a -Pluggable Transport which disguises your traffic by adding an obfuscating -layer of encryption. - -#### So how do I use this? -Well, probably, you don't. But if you're looking for bridges, you can use -[the web interface](https://bridges.torproject.org) of the BridgeDB instance -deployed by the Tor Project, which has instructions on getting the Pluggable -Transports-capable Tor Browser Bundle, as well as instructions for getting -extra Bridges. - - -## Maintainer Setup - -### Dependencies and installation -BridgeDB requires the following OS-level dependencies: - - - python>=2.7 - - python-dev - - build-essential - - libgpgme11 - - libgpgme11-dev - - OpenSSL>=1.0.1e - - [SQLite3](http://www.maxmind.com/app/python) - - [MaxMind GeoIP](https://www.maxmind.com/en/geolocation_landing) - - libgeoip-dev - - geoip-database - - [python-setuptools](https://pypi.python.org/pypi/setuptools) - -As well as any Python dependencies in requirements.txt. - -### Deploying BridgeDB - -BridgeDB should work with or without a Python virtualenv. - - - Install Python 2.7, and other OS-level dependencies. On Debian, you can do: - - sudo apt-get install build-essential openssl python python-dev \ - python-setuptools sqlite3 libgpgme11 libgpgme11-dev libgeoip-dev \ - geoip-database - - - Install Pip 1.3.1 or later. Debian has this version, but if for some reason - that or a newer version isn't available, the easiest way to install a newer - Pip is to use the Pip development teams's [getpip - script](https://raw.github.com/pypa/pip/master/contrib/get-pip.py): - - wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py - sudo python get-pip.py - - - (virtualenv installs only) Use Pip to install virtualenv and - [virtualenvwrapper](https://virtualenvwrapper.readthedocs.org): - - sudo pip install --upgrade virtualenv virtualenvwrapper - - - (virtualenv installs only) Configure virtualenvwrapper and create a - virtualenv for Bridgedb: - - WORKON_HOME=${HOME}/.virtualenvs - export WORKON_HOME - mkdir -p $WORKON_HOME - source $(which virtualenvwrapper.sh) - git clone https://git.torproject.org/bridgedb.git && cd bridgedb - mkvirtualenv -a $PWD -r requirements.txt --unzip-setuptools \ - --setuptools bridgedb - - From now on, to use BridgeDB's virtualenv, just do ```$ workon bridgedb``` - (after sourcing virtualenvwrapper.sh, as before). To exit the virtualenv - without exiting the shell, do ```$ deactivate```. - - - (virtualenv installs only) To install, set PYTHONPATH to include the root - directory of the virtualenv: - - export PYTHONPATH=$PYTHONPATH:${VIRTUAL_ENV}/lib/python2.7/site-packages - - - Then proceed as usual: - - python setup.py install --record installed-files.txt - -### Testing BridgeDB - -To create a bunch of fake bridge descriptors to test BridgeDB, do: - - bridgedb mock [-n NUMBER_OF_DESCRIPTORS] - -Then to run unittests, see the ```bridgedb test``` and ```bridgedb trial``` -commands. - -### Enabling additional features: - -#### Translations - -**Using New Translations**: This should be done when newly completed - translations are available in Transifex. - -Piece of cake. Running ```maint/get-completed-translations``` will take care -of cloning *only* the ```bridgedb_completed``` branch of Tor's -[translations repo](https://gitweb.torproject.org/translation.git) and placing -all the updated files in their correct locations. - -**Requesting Translations for Altered/Added Source Code**: This should be done - whenever any of the strings requiring translation -- _("they are formatted - like this") -- are changed, or new ones are added. - See ```lib/bridgedb/strings.py```. - -Translations for Tor Project repos are kept -[in a separate repo](https://gitweb.torproject.org/translation.git). You'll -need to extract the strings from BridgeDB's source code into .pot templates, -and place these .po files into the ```translation``` repo in the -```bridgedb``` branch. After than the .po files should be put into Transifex -(don't ask me how this works…) and translated. After the translations are -complete, the finished .po files should be placed into the -```bridgedb_completed``` branch. - - - To extract all strings from BridgeDB's source: - - python setup.py extract_messages --input-dirs ./lib/bridgedb/templates - - A .pot file will be created in ./i18n/templates/bridgedb.pot - - - Initialise catalogs for each desired language: - - python setup.py init_catalog -l LANG - - where ```LANG``` is the 2 or 4 letter country-code, eg. 'es'. If you've - already initialised a particular language, do instead: - - python setup.py update_catalog - - -#### Enabling HTTPS -Create a self-signed certificate with: - - scripts/make-ssl-cert - -Or, place an existing certificate in the path specified in bridgedb.conf by -the ```HTTPS_CERT_FILE``` option, and a private key where ```HTTPS_KEY_FILE``` -points to. The defaults are 'cert' and 'privkey.pem', respectively. - -#### CAPTCHAs - -BridgeDB has two ways to use CAPTCHAs on webpages. The first uses reCaptcha_, -an external Google service (this requires an account with them), which -BridgeDB fetches the CAPTCHAs images from for each incoming request from a -client. The second method uses a local cache of pre-made CAPTCHAs, created by -scripting Gimp using gimp-captcha_. The latter cannot easily be run on -headless server, unfortunately, because Gimp requires an X server to be -installed. - -.. _reCaptcha: https://www.google.com/recaptcha -.. gimp-capthca: https://github.com/isislovecruft/gimp-captcha - -##### reCaptcha -To enable fetching CAPTCHAs from the reCaptcha API server, set these options -in bridgedb.conf: - - RECAPTCHA_ENABLED - RECAPTCHA_PUB_KEY - RECAPTCHA_SEC_KEY - -##### gimp-captcha -To enable using a local cache of CAPTCHAs, set the following options:: - - GIMP_CAPTCHA_ENABLED - GIMP_CAPTCHA_DIR - GIMP_CAPTCHA_HMAC_KEYFILE - GIMP_CAPTCHA_RSA_KEYFILE - -#### GnuPG email signing -Add these two options to your bridgedb.conf:: - - EMAIL_GPG_SIGNING_ENABLED - EMAIL_GPG_SIGNING_KEY - -The former may be either True or False, and the latter must point to the -ascii-armored private key file. The keyfile must not be passphrase protected. - -#### Preventing already-blocked bridges from being distributed -Uncomment or add ```COUNTRY_BLOCK_FILE``` to your bridgedb.conf. This file -should contain one bridge entry per line, in the format: - - fingerprint <bridge fingerprint> country-code <country code> - -If the ```COUNTRY_BLOCK_FILE``` file is present, bridgedb will filter blocked -bridges from the responses it gives to clients requesting bridges. - -#### Updating the SQL schema -Make sure that SQLite3 is installed. (You should have installed it already -during the setup and installation stage.) To update, do: - - sqlite3 path/to/bridgedist.db.sqlite - -Enter the following commands at the ```sqlite>``` prompt: - - CREATE TABLE BlockedBridges ( id INTEGER PRIMARY KEY NOT NULL, hex_key, blocking_country); - CREATE INDEX BlockedBridgesBlockingCountry on BlockedBridges(hex_key); - CREATE TABLE WarnedEmails ( email PRIMARY KEY NOT NULL, when_warned); - CREATE INDEX WarnedEmailsWasWarned on WarnedEmails ( email ); - REPLACE INTO Config VALUES ( 'schema-version', 2 ); - - -## Running BridgeDB - -To run BridgeDB, simply make any necessary changes to bridgedb.conf, and -do: ```bridgedb```. - -And remember that all files/directories in ```bridgedb.conf``` are assumed -relative to the runtime directory. By default, BridgeDB uses the current -working directory; you can, however specify an a different runtime directory:: - - bridgedb -r /srv/bridges.torproject.org/run - -Make sure that the files and directories referred to in bridgedb.conf -exist. However, many of them, if not found, will be touched on disk so that -attempts to read/write from/to them will not raise excessive errors. - -When you have new lists of bridges from the Bridge Authority, replace the old -files and do:: - - bridgedb --reload - -Or just give it a SIGHUP:: - - kill -s SIGHUP `cat .../run/bridgedb.pid` - -#### To extract bucket files of all unallocated bridges: -Edit the configuration file value ```FILE_BUCKETS``` according to your -needs. For example, the following is a possible configuration: - - FILE_BUCKETS = { "name1": 10, "name2": 15, "foobar": 3 } - -This configuration for buckets would result in 3 files being created for -bridge distribution: name1-2010-07-17.brdgs, name2-2010-07-17.brdgs and -foobar-2010-07-17.brdgs. The first file would contain 10 bridges from -BridgeDB's 'unallocated' pool. The second file would contain 15 bridges from -the same pool and the third one similarly 3 bridges. These files can then be -handed out to trusted parties via mail or fed to other distribution mechanisms -such as Twitter. - -To dump all buckets to their files, send BridgeDB a ```SIGUSR1``` signal by -doing:: - - kill -s SIGUSR1 `cat .../run/bridgedb.pid` - -#### To use with HTTPS: -Just connect to the appropriate port. - -#### To use with email: Any mail sent to the email port with a destination -username as defined by the EMAIL_USERNAME configuration option (default is -'bridge', e.g. bridges@...) and sent from an ```(a)riseup.net```, -```(a)gmail.com```, or ```(a)yahoo.com``` address (by default, configured with the -EMAIL_DOMAINS option). - -### Support -Send your questions to isis (A) torproject (circle) org. diff --git a/README.md b/README.md deleted file mode 120000 index 100b938..0000000 --- a/README.md +++ /dev/null @@ -1 +0,0 @@ -README \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..8a33983 --- /dev/null +++ b/README.rst @@ -0,0 +1,422 @@ +***************************************** +BridgeDB |Build Status| |Coverage Status| +***************************************** + +BridgeDB is a collection of backend servers used to distribute `Tor Bridges +<https://www.torproject.org/docs/bridges>`__. Currently, it mainly consists of +a webserver with `an HTTPS interface <https://bridges.torproject.org>`__, +`an email responder <mailto:bridges@torproject.org>`__, and an SQLite database. + + +.. |Build Status| image:: https://travis-ci.org/isislovecruft/bridgedb.svg + :target: https://travis-ci.org/isislovecruft/bridgedb +.. |Coverage Status| image:: https://coveralls.io/repos/isislovecruft/bridgedb/badge.png?branch=develop + :target: https://coveralls.io/r/isislovecruft/bridgedb?branch=develop + + +.. image:: doc/sphinx/source/_static/bay-bridge.jpg + :scale: 80% + :align: center + + +.. contents:: + :backlinks: entry + + +===================== +What are Tor Bridges? +===================== + +`Tor Bridges <https://www.torproject.org/docs/bridges>`__ are special +Tor relays which are not listed in the public relay directory. They are +used to help circumvent `censorship <https://ooni.torproject.org>`__ by +providing users with connections to the public relays in the Tor +network. + +Tor Bridges are different from normal relays in another important way: +they can run what are called *Pluggable* *Transports*. + +----------------------------- +What's a Pluggable Transport? +----------------------------- + +A `Pluggable +Transport <https://www.torproject.org/docs/pluggable-transports.html.en>`__ +is a program which is *pluggable* — meaning that it is meant to work +with lots of other anonymity and censorship circumvention software, not +just Tor — and is a *transport* — meaning that it transports your +internet traffic, usually in a way which makes it look different. For +example, +`Obfsproxy <https://www.torproject.org/projects/obfsproxy.html.en>`__ is +a Pluggable Transport which disguises your traffic by adding an +obfuscating layer of encryption. + +--------------------- +So how do I use this? +--------------------- + +Well, probably, you don't. But if you're looking for bridges, you can +use `the web interface <https://bridges.torproject.org>`__ of the +BridgeDB instance deployed by the Tor Project, which has instructions on +getting the Pluggable Transports-capable Tor Browser Bundle, as well as +instructions for getting extra Bridges. + + +================ +Maintainer Setup +================ + +----------------------------- +Dependencies and installation +----------------------------- + +BridgeDB requires the following OS-level dependencies: + +- python>=2.7 +- python-dev +- build-essential +- libgpgme11 +- libgpgme11-dev +- OpenSSL>=1.0.1g +- `SQLite3 <http://www.maxmind.com/app/python>`__ +- `MaxMind GeoIP <https://www.maxmind.com/en/geolocation_landing>`__ +- libgeoip-dev +- geoip-database +- `python-setuptools <https://pypi.python.org/pypi/setuptools>`__ + +As well as any Python dependencies in the ``requirements.txt`` file. + +.. note: There are additional dependencies for things like running the test + suites, building BridgeDB's developer documentation, etc. Read on for more + info if you wish to enable addition features. + + +------------------ +Deploying BridgeDB +------------------ + +BridgeDB should work with or without a Python virtualenv. + +- Install Python 2.7, and other OS-level dependencies. On Debian, you + can do:: + + sudo apt-get install build-essential openssl python python-dev \ + python-setuptools sqlite3 libgpgme11 libgpgme11-dev libgeoip-dev \ + geoip-database + + +- Install Pip 1.3.1 or later. Debian has this version, but if for some + reason that or a newer version isn't available, the easiest way to + install a newer Pip is to use the Pip development teams's `getpip + script <https://raw.github.com/pypa/pip/master/contrib/get-pip.py>`__:: + + wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py + sudo python get-pip.py + + +- **(virtualenv installs only)** Use Pip to install virtualenv and + `virtualenvwrapper <https://virtualenvwrapper.readthedocs.org>`__:: + + sudo pip install --upgrade virtualenv virtualenvwrapper + + +- **(virtualenv installs only)** Configure virtualenvwrapper and create a + virtualenv for BridgeDB:: + + WORKON_HOME=${HOME}/.virtualenvs + export WORKON_HOME + mkdir -p $WORKON_HOME + source $(which virtualenvwrapper.sh) + git clone https://git.torproject.org/bridgedb.git && cd bridgedb + mkvirtualenv -a $PWD -r requirements.txt --unzip-setuptools --setuptools bridgedb + + From now on, to use BridgeDB's virtualenv, just do ``$ workon bridgedb`` + (after sourcing virtualenvwrapper.sh, as before). To exit the virtualenv + without exiting the shell, do ``$ deactivate``. + + +- **(virtualenv installs only)** To install, set PYTHONPATH to include the + root directory of the virtualenv:: + + export PYTHONPATH=$PYTHONPATH:${VIRTUAL_ENV}/lib/python2.7/site-packages + + +- Then, proceed as usual:: + + python setup.py install --record installed-files.txt + + +============================ +Enabling additional features +============================ + +------------ +Translations +------------ + +**Using New Translations**: + +This should be done when newly completed translations are available in +Transifex. + +Piece of cake. Running ``maint/get-completed-translations`` will take +care of cloning *only* the ``bridgedb_completed`` branch of Tor's +`translations repo <https://gitweb.torproject.org/translation.git>`__ +and placing all the updated files in their correct locations. + +------- + +**Requesting Translations for Altered/Added Source Code**: + +This should be done whenever any of the strings requiring translation -- +``_("the ones inside the weird underscore function, like this")`` -- are +changed, or new ones are added. See ``lib/bridgedb/strings.py``. + +Translations for Tor Project repos are kept `in a separate +repo <https://gitweb.torproject.org/translation.git>`__. You'll need to +extract the strings from BridgeDB's source code into .pot templates, and +place these .po files into the ``translation`` repo in the ``bridgedb`` +branch. After than the .po files should be put into Transifex (don't ask +me how this works…) and translated. After the translations are complete, +the finished .po files should be placed into the ``bridgedb_completed`` +branch. + +- To extract all strings from BridgeDB's source:: + + python setup.py extract_messages --input-dirs ./lib/bridgedb/templates + + A .pot file will be created in ./i18n/templates/bridgedb.pot + + +- Initialise catalogs for each desired language:: + + python setup.py init_catalog -l LANG + + where ``LANG`` is the 2 or 4 letter country-code, eg. 'es'. If you've + already initialised a particular language, do instead:: + + python setup.py update_catalog + + +------- + +-------------- +Enabling HTTPS +-------------- + +Create a self-signed certificate with:: + + scripts/make-ssl-cert + +Or, place an existing certificate in the path specified in bridgedb.conf +by the ``HTTPS_CERT_FILE`` option, and a private key where +``HTTPS_KEY_FILE`` points to. The defaults are 'cert' and 'privkey.pem', +respectively. + + +------------------------ +Enabling CAPTCHA Support +------------------------ + +BridgeDB has two ways to use CAPTCHAs on webpages. The first uses reCaptcha_, +an external Google service (this requires an account with them), which +BridgeDB fetches the CAPTCHAs images from for each incoming request from a +client. The second method uses a local cache of pre-made CAPTCHAs, created by +scripting Gimp using gimp-captcha_. The latter cannot easily be run on +headless server, unfortunately, because Gimp requires an X server to be +installed. + +.. _reCaptcha: https://www.google.com/recaptcha +.. _gimp-captcha: https://github.com/isislovecruft/gimp-captcha + + +**reCaptcha** + +To enable fetching CAPTCHAs from the reCaptcha API server, set these +options in bridgedb.conf:: + + RECAPTCHA_ENABLED + RECAPTCHA_PUB_KEY + RECAPTCHA_SEC_KEY + +------- + +**gimp-captcha** + +To enable using a local cache of CAPTCHAs, set the following options:: + + GIMP_CAPTCHA_ENABLED + GIMP_CAPTCHA_DIR + GIMP_CAPTCHA_HMAC_KEYFILE + GIMP_CAPTCHA_RSA_KEYFILE + +------- + +-------------------- +GnuPG email signing: +-------------------- + +Add these two options to your bridgedb.conf:: + + EMAIL_GPG_SIGNING_ENABLED + EMAIL_GPG_SIGNING_KEY + +The former may be either True or False, and the latter must point to the +ascii-armored private key file. The keyfile must not be passphrase +protected. + + +---------------------------------------------------------- +Preventing already-blocked bridges from being distributed: +---------------------------------------------------------- + +Uncomment or add ``COUNTRY_BLOCK_FILE`` to your bridgedb.conf. This file +should contain one bridge entry per line, in the format:: + + fingerprint <bridge fingerprint> country-code <country code> + +If the ``COUNTRY_BLOCK_FILE`` file is present, bridgedb will filter +blocked bridges from the responses it gives to clients requesting +bridges. + + +------------------------ +Updating the SQL schema: +------------------------ + +Make sure that SQLite3 is installed. (You should have installed it +already during the setup and installation stage.) To update, do:: + + sqlite3 path/to/bridgedist.db.sqlite + +Enter the following commands at the ``sqlite>`` prompt:: + + CREATE TABLE BlockedBridges ( id INTEGER PRIMARY KEY NOT NULL, hex_key, blocking_country); + CREATE INDEX BlockedBridgesBlockingCountry on BlockedBridges(hex_key); + CREATE TABLE WarnedEmails ( email PRIMARY KEY NOT NULL, when_warned); + CREATE INDEX WarnedEmailsWasWarned on WarnedEmails ( email ); + REPLACE INTO Config VALUES ( 'schema-version', 2 ); + + +================ +Testing BridgeDB +================ + +Before running to any of BridgeDB's test suites, make sure you have the +additional dependencies in the Pip requirements file, +``.test.requirements.txt`` installed:: + + pip install -r .test.requirements.txt + +To create a bunch of fake bridge descriptors to test BridgeDB, do:: + + bridgedb mock [-n NUMBER_OF_DESCRIPTORS] + +And finally, to run the test suites, do:: + + make coverage + +If you just want to run the tests, and don't care about code coverage +statistics, see the ``bridgedb trial`` and ``bridgedb test`` commands. + + +================ +Running BridgeDB +================ + +To run BridgeDB, simply make any necessary changes to bridgedb.conf, and do:: + + bridgedb + +And remember that all files/directories in ``bridgedb.conf`` are assumed +relative to the runtime directory. By default, BridgeDB uses the current +working directory; you can, however specify an a different runtime +directory:: + + bridgedb -r /srv/bridges.torproject.org/run + +Make sure that the files and directories referred to in bridgedb.conf +exist. However, many of them, if not found, will be touched on disk so +that attempts to read/write from/to them will not raise excessive +errors. + + +---------------------------------------------- +Reloading Bridges From Their Descriptor Files: +---------------------------------------------- + +When you have new lists of bridges from the Bridge Authority, replace +the old files and do:: + + bridgedb --reload + +Or just give it a SIGHUP:: + + kill -s SIGHUP `cat .../run/bridgedb.pid` + + +--------------------------------------------------- +To extract bucket files of all unallocated bridges: +--------------------------------------------------- + +Edit the configuration file value ``FILE_BUCKETS`` according to your +needs. For example, the following is a possible configuration:: + + FILE_BUCKETS = { "name1": 10, "name2": 15, "foobar": 3 } + +This configuration for buckets would result in 3 files being created for +bridge distribution: name1-2010-07-17.brdgs, name2-2010-07-17.brdgs and +foobar-2010-07-17.brdgs. The first file would contain 10 bridges from +BridgeDB's 'unallocated' pool. The second file would contain 15 bridges +from the same pool and the third one similarly 3 bridges. These files +can then be handed out to trusted parties via mail or fed to other +distribution mechanisms such as Twitter. + +To dump all buckets to their files, send BridgeDB a ``SIGUSR1`` signal +by doing:: + + kill -s SIGUSR1 `cat .../run/bridgedb.pid` + + +========================= +Using a BridgeDB Instance +========================= + +Obviously, you'll have to feed it bridge descriptor files from a +BridgeAuth. There's currently only one BridgeAuth in the entire world, but Tor +Project is, of course, very interested in adding support for multiple +BridgeAuths so that we can scale our own network, and make it easier for +individual and organisations who wish to run a lot of Tor bridge relays, and +distribute those themselves, have an easier time doing so. If you'd like to +fund our work on this, please contact tor-dev(a)lists.torproject.org! + +---------------------------------- +Accessing the HTTPS User Interface +---------------------------------- + +Just connect to the appropriate port. (See the ``HTTPS_PORT`` and +``HTTP_UNENCRYPTED\_PORT`` options in the ``bridgedb.conf`` file.) + +The HTTPS interface for our BridgeDB instance can be found `here +<https://bridges.torproject.org>`__. + + +---------------------------------- +Accessing the Email User Interface +---------------------------------- + +Any mail sent to the ``EMAIL_PORT`` with a destination username as defined by +the ``EMAIL_USERNAME`` configuration option (the default is ``'bridge'``, +e.g. bridges@...) and sent from an ``(a)riseup.net``, ``(a)gmail.com``, or +``(a)yahoo.com`` address (by default, but configurable with the +``EMAIL_DOMAINS`` option). + +You can email our BridgeDB instance `here <mailto:bridges@torproject.org>`__. + +================= +Contact & Support +================= + +Send your questions, patches, and suggestions to +`the tor-dev mailing list <mailto:tor-dev@lists.torproject.org>`__ +or `isis <mailto:isis@torproject.org>`__. diff --git a/doc/sphinx/source/_static/bay-bridge.jpg b/doc/sphinx/source/_static/bay-bridge.jpg new file mode 100644 index 0000000..fc00116 Binary files /dev/null and b/doc/sphinx/source/_static/bay-bridge.jpg differ

1 0

[bridgedb/develop] Add Sphinx source file for bridgedb.interfaces documentation.
by isis＠torproject.org 28 Aug '14

28 Aug '14

commit 08bce640e9359dd28defeaae474ea3927afc0353 Author: Isis Lovecruft <isis(a)torproject.org> Date: Thu Aug 28 08:45:03 2014 +0000 Add Sphinx source file for bridgedb.interfaces documentation. --- doc/sphinx/source/bridgedb.interfaces.rst | 8 ++++++++ doc/sphinx/source/bridgedb.rst | 1 + 2 files changed, 9 insertions(+) diff --git a/doc/sphinx/source/bridgedb.interfaces.rst b/doc/sphinx/source/bridgedb.interfaces.rst new file mode 100644 index 0000000..fb41f2c --- /dev/null +++ b/doc/sphinx/source/bridgedb.interfaces.rst @@ -0,0 +1,8 @@ +bridgedb.interfaces +---------------------- + +.. automodule:: bridgedb.interfaces + :members: + :undoc-members: + :private-members: + :show-inheritance: diff --git a/doc/sphinx/source/bridgedb.rst b/doc/sphinx/source/bridgedb.rst index 92d16bd..6da86f0 100644 --- a/doc/sphinx/source/bridgedb.rst +++ b/doc/sphinx/source/bridgedb.rst @@ -21,6 +21,7 @@ BridgeDB Package and Module Documentation bridgedb.email.templates bridgedb.Filters bridgedb.HTTPServer + bridgedb.interfaces bridgedb.Main bridgedb.parse bridgedb.persistent

1 0