Package: bridgedb
BridgeDB is a collection of backend servers used to distributeTor Bridges. Currently, it mainly consists of
a webserver withan HTTPS interface,an email responder, and an SQLite database.ContentsWhat are Tor Bridges?What’s a Pluggable Transport?So how do I use this?Maintainer SetupDependencies and installationDeploying BridgeDBEnabling additional featuresTranslationsEnabling HTTPSEnabling CAPTCHA SupportGnuPG email signing:Preventing already-blocked bridges from being distributed:Testing BridgeDBRunning BridgeDBReloading Bridges From Their Descriptor Files:To extract bucket files of all unallocated bridges:Using a BridgeDB InstanceAccessing the HTTPS User InterfaceAccessing the Email User InterfaceContact & SupportWhat are Tor Bridges?Tor Bridgesare special
Tor relays which are not listed in the public relay directory. They are
used to help circumventcensorshipby
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 calledPluggableTransports.What’s a Pluggable Transport?APluggable
Transportis a program which ispluggable— meaning that it is meant to work
with lots of other anonymity and censorship circumvention software, not
just Tor — and is atransport— meaning that it transports your
internet traffic, usually in a way which makes it look different. For
example,Obfsproxyis
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
usethe web interfaceof 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 SetupIf you’d like to hack on BridgeDB, you might wish to read BridgeDB’sdeveloper documentation.  The rest of
this document mainly concerns mainenance and installation instructions.Dependencies and installationBridgeDB requires the following OS-level dependencies:python>=2.7python-devbuild-essentialgnupg (preferrably, gnupg2)OpenSSL>=1.0.1gSQLite3MaxMind GeoIPlibgeoip-devgeoip-databasepython-setuptoolslibjpeg-devAs well as any Python dependencies in therequirements.txtfile.Deploying BridgeDBBridgeDB 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 gnupg2 libgeoip-dev geoip-databaseInstall 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’sgetpip
script: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 andvirtualenvwrapper: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 bridgedbFrom 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-packagesThen, proceed as usual:python setup.py install --record installed-files.txtEnabling additional featuresTranslationsUsing New Translations:This should be done when newly completed translations are available in
Transifex.Piece of cake. Runningmaint/get-completed-translationswill take
care of cloningonlythebridgedb_completedbranch of Tor’stranslations repoand 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 –_("theones inside the weird underscore function, like this")– are
changed, or new ones are added. Seelib/bridgedb/strings.py.Translations for Tor Project repos are keptin a separate
repo. You’ll need to
extract the strings from BridgeDB’s source code into .pot templates, and
place these .po files into thetranslationrepo in thebridgedbbranch. 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 thebridgedb_completedbranch.To extract all strings from BridgeDB’s source:python setup.py extract_messagesA .pot file will be created in ./i18n/templates/bridgedb.potInitialise catalogs for each desired language:python setup.py init_catalog -l LANGwhereLANGis the 2 or 4 letter country-code, eg. ‘es’. If you’ve
already initialised a particular language, do instead:python setup.py update_catalogEnabling HTTPSCreate a self-signed certificate with:scripts/make-ssl-certOr, place an existing certificate in the path specified in bridgedb.conf
by theHTTPS_CERT_FILEoption, and a private key whereHTTPS_KEY_FILEpoints to. The defaults are ‘cert’ and ‘privkey.pem’,
respectively.Enabling CAPTCHA SupportBridgeDB has two ways to use CAPTCHAs on webpages. The first usesreCaptcha,
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 usinggimp-captcha. The latter cannot easily be run on
headless server, unfortunately, because Gimp requires an X server to be
installed.reCaptchaTo enable fetching CAPTCHAs from the reCaptcha API server, set these
options in bridgedb.conf:RECAPTCHA_ENABLED
RECAPTCHA_PUB_KEY
RECAPTCHA_SEC_KEYgimp-captchaTo enable using a local cache of CAPTCHAs, set the following options:GIMP_CAPTCHA_ENABLED
GIMP_CAPTCHA_DIR
GIMP_CAPTCHA_HMAC_KEYFILE
GIMP_CAPTCHA_RSA_KEYFILEGnuPG email signing:In yourbridgedb.conffile, make sure that:EMAIL_GPG_SIGNING_ENABLED = Trueand edit the following option to add the full fingerprint of the GnuPG key
that should be used to by BridgeDB to sign outgoing emails:EMAIL_GPG_PRIMARY_KEY_FINGERPRINTThe key specified byEMAIL_GPG_PRIMARY_KEY_FINGERPRINTcan be a master
key, or a subkey (with or without the private portions of its corresponding
master key), but itmustbe inside thesecring.gpgandpubring.gpgkeyrings inside the directory specified in thebridgedb.confoption:EMAIL_GPG_HOMEDIRIf the key has requires a passphrase for signing, you’ll also need to set
either of:EMAIL_GPG_PASSPHRASE
EMAIL_GPG_PASSPHRASE_FILEPreventing already-blocked bridges from being distributed:Uncomment or addCOUNTRY_BLOCK_FILEto your bridgedb.conf. This file
should contain one bridge entry per line, in the format:fingerprint <bridge fingerprint> country-code <country code>If theCOUNTRY_BLOCK_FILEfile is present, bridgedb will filter
blocked bridges from the responses it gives to clients requesting
bridges.Testing BridgeDBBefore running to any of BridgeDB’s test suites, make sure you have the
additional dependencies in the Pip requirements file,.test.requirements.txtinstalled:pip install -r .test.requirements.txtTo create a bunch of fake bridge descriptors to test BridgeDB, do:bridgedb mock [-n NUMBER_OF_DESCRIPTORS]Note that you will need to installleekspinin order to run thebridgedb mockcommand. Seedoc/HACKING.mdfor details.And finally, to run the test suites, do:make coverageIf you just want to run the tests, and don’t care about code coverage
statistics, see thebridgedb trialandbridgedb testcommands.Running BridgeDBTo run BridgeDB, simply make any necessary changes to bridgedb.conf, and do:bridgedbAnd remember that all files/directories inbridgedb.confare 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/runMake 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 --reloadOr just give it a SIGHUP:kill -s SIGHUP `cat .../run/bridgedb.pid`To extract bucket files of all unallocated bridges:Edit the configuration file valueFILE_BUCKETSaccording 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 aSIGUSR1signal
by doing:kill -s SIGUSR1 `cat .../run/bridgedb.pid`Using a BridgeDB InstanceObviously, you’ll have to feed it bridge descriptor files from a
BridgeAuthority. There’s currently only one BridgeAuthority in the entire
world, but Tor Project is, of course, very interested in adding support for
multiple BridgeAuthorities 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 have an easier time distributing those bridges themselves (if they wish
to do so). If you’d like to fund our work on this, please contacttor-dev@lists.torproject.org!Accessing the HTTPS User InterfaceJust connect to the appropriate port. (See theHTTPS_PORTandHTTP_UNENCRYPTED_PORToptions in thebridgedb.conffile.)The HTTPS interface for our BridgeDB instance can be foundhere.Accessing the Email User InterfaceAny mail sent to theEMAIL_PORTwith a destination username as defined by
theEMAIL_USERNAMEconfiguration option (the default is'bridge',
e.g. bridges@…) and sent from an@riseup.net,@gmail.com, or@yahoo.comaddress (by default, but configurable with theEMAIL_DOMAINSoption).You can email our BridgeDB instancehere.Contact & SupportSend your questions, patches, and suggestions tothe tor-dev mailing listorisis.