commit 6d3da5ba38c2d6c348c0bc2cb64a46a18022cbb0 Author: Isis Lovecruft isis@torproject.org Date: Mon Aug 12 14:05:58 2013 +0000
Move README.md → README so that it gets included in packages by setuptools.
* CHANGE the "Translations" section to accurately reflect required steps for updateing .pot files with strings which are newly added to BridgeDB's source code, as well as instructions for getting finished translations from gitweb.torproject.org/translations.git. * FIX a couple typos in the README. --- README | 258 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 220 +--------------------------------------------------- 2 files changed, 259 insertions(+), 219 deletions(-)
diff --git a/README b/README new file mode 100644 index 0000000..6d390e4 --- /dev/null +++ b/README @@ -0,0 +1,258 @@ +## 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 +[BridgeDB's web interface](https://bridges.torproject.org), which has +instructions on getting the Pluggable Transports 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.6 + - OpenSSL>=1.0.1e + - [SQLite3](http://www.maxmind.com/app/python) + - [MaxMind GeoIP](https://www.maxmind.com/en/geolocation_landing) + - [python-setuptools](https://pypi.python.org/pypi/setuptools) + +As well as the following Python dependencies (from ./requirements.txt): + + Babel==0.9.6 + BeautifulSoup==3.2.1 + Mako==0.8.1 + MarkupSafe==0.18 + Twisted>=13.0.0 + argparse>=1.2.1 + distribute>=0.6.46 + ipaddr>=2.1.10 + pyOpenSSL>=0.13 + pygeoip>=0.2.6 + pygpgme==0.3 + recaptcha>=1.0rc1 + recaptcha-client>=1.0.6 + wsgiref>=0.1.2 + zope.interface>=4.0.5 + +### Deploying BridgeDB in a Python virtualenv + + - Install Python 2.6 or later, and other OS-level dependencies. On Debian, + you can do: + + sudo apt-get install python openssl sqlite3 tor-geoip + + - Install Pip 1.3.1 or later. Debian sid has this version, but if you're + tracking a different release, 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 + + - Use Pip to install virtualenv and [virtualenvwrapper](https://virtualenvwrapper.readthedocs.org): + + sudo pip install --upgrade virtualenv virtualenvwrapper + + - 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```. + + - To run unit tests: + + python setup.py test + + - To install BridgeDB: + + python setup.py install + + +### Enabling additional features: + +#### Translations + +**Using New Translations**: This should be done when newly completed + translations are available in Transifex. + +Clone/Update the +[translations repository](https://gitweb.torproject.org/translation.git), +checkout the ```bridgedb_completed``` branch, and copy the .po files into +```lib/bridgedb/i18n/```. + +Assuming a side-by-side repo layout (if you're in the parent directory of the +bridgedb repo): + + git clone https://gitweb.torproject.org/translation.git + git fetch --all + cd translation && git checkout bridgedb_completed + cd .. && rsync -PCAXrv \ + --filter 'include ./translation/*/LC_MESSAGES/bridgedb.po' \ + --filter 'exclude .gitignore' \ + ./translation/ ./bridgedb/lib/bridgedb/i18n/ + +and then convert them to binary (.mo) format so that they can be installed: + + cd bridgedb && python setup.py compile_catalog + +Don't forget to reinstall BridgeDB to update the templates! + + python setup.py install + +[xxx outdated, these commands seem to not exist...] + + python setup.py trans && python setup.py install_data + +**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/I18n.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: + + openssl req -x509 -new -nodes > 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 +To enable Captchas on the webserver interface, set these options in +bridgedb.conf: + + RECAPTCHA_ENABLED + RECAPTCHA_PUB_KEY + RECAPTCHA_PRIV_KEY + +A [recaptcha.net](https://www.google.com/recaptcha) account is required. + +#### 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: + + python -m TorBridgeDB -c bridgedb.conf + +When you have new lists of bridges, replace the old files and send the process +a SIGHUP. + +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. + +#### 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 use with HTTPS: +Just connect to the appropriate port. + +#### To use with email: +Any mail sent to the email port with a subject or a single line _exactly_ +equal to "get bridges" will get answered, assuming the domain is okay. + +### Support +Send your questions to isis (A) torproject (circle) org. diff --git a/README.md b/README.md deleted file mode 100644 index 9a50246..0000000 --- a/README.md +++ /dev/null @@ -1,219 +0,0 @@ -## 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 -[BridgeDB's web interface](https://bridges.torproject.org), which has -instructions on getting the Pluggable Transports 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.6 - - OpenSSL>=1.0.1e - - [SQLite3](http://www.maxmind.com/app/python) - - [MaxMind GeoIP](https://www.maxmind.com/en/geolocation_landing) - - [python-setuptools](https://pypi.python.org/pypi/setuptools) - -As well as the following Python dependencies (from ./requirements.txt): - - Babel==0.9.6 - BeautifulSoup==3.2.1 - Mako==0.8.1 - MarkupSafe==0.18 - Twisted>=13.0.0 - argparse>=1.2.1 - distribute>=0.6.46 - ipaddr>=2.1.10 - pyOpenSSL>=0.13 - pygeoip>=0.2.6 - pygpgme==0.3 - recaptcha>=1.0rc1 - recaptcha-client>=1.0.6 - wsgiref>=0.1.2 - zope.interface>=4.0.5 - -### Deploying BridgeDB in a Python virtualenv - - - Install Python 2.6 or later, and other OS-level dependencies. On Debian, - you can do: - - sudo apt-get install python openssl sqlite3 tor-geoip - - - Install Pip 1.3.1 or later. Debian sid has this version, but if you're - tracking a different release, 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 - - - Use Pip to install virtualenv and [virtualenvwrapper](https://virtualenvwrapper.readthedocs.org): - - sudo pip install --upgrade virtualenv virtualenvwrapper - - - 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```. - - - To run unit tests: - - python setup.py test - - - To install BridgeDB: - - python setup.py install - - -### Enabling additional features: - -#### Translations - - To extract all strings from BridgeDB's source: - - python setup.py extract_messages - - 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'. - - Edit strings in ./i18n/LANG/bridgedb.po, and then convert them to binary - format: - - python setup.py compile_catalog - - Don't forget to reinstall BridgeDB to update the templates! - - python setup.py install - - - To generate translation files, and then install them, do: - - python setup.py trans && python setup.py install_data - -#### Enabling HTTPS -Create a self-signed certificate with: - - openssl req -x509 -new -nodes > 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 -To enable Captchas on the webserver interface, set the options in -bridgedb.conf: - - RECAPTCHA_ENABLED - RECAPTCHA_PUB_KEY - RECAPTCHA_PRIV_KEY - -A [recaptcha.net](https://www.google.com/recaptcha) account is required. - -#### 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: - - python -m TorBridgeDB -c bridgedb.conf - -When you have new lists of bridges, replace the old files and send the process -a SIGHUP. - -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. - -#### 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 use with HTTPS: -Just connect to the appropriate port. - -#### To use with email: -Any mail sent to the email port with a subject or a single line _exactly_ -equal to "get bridges" will get answered, assuming the domain is okay. - -### Support -Send your questions to aagbsn@torproject.org. diff --git a/README.md b/README.md new file mode 120000 index 0000000..100b938 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +README \ No newline at end of file