{ "info": { "author": "Isis Agora Lovecruft", "author_email": "isis@torproject.org 0xA3ADB67A2CDB8B35", "bugtrack_url": null, "classifiers": [], "description": "**********************************************************\nBridgeDB |Latest Version| |Build Status| |Coverage Status|\n**********************************************************\n\nBridgeDB is a collection of backend servers used to distribute `Tor Bridges\n`__. Currently, it mainly consists of\na webserver with `an HTTPS interface `__,\n`an email responder `__, and an SQLite database.\n\n.. |Latest Version| image:: https://pypip.in/version/bridgedb/badge.svg?style=flat\n :target: https://pypi.python.org/pypi/bridgedb/\n.. |Build Status| image:: https://travis-ci.org/isislovecruft/bridgedb.svg\n :target: https://travis-ci.org/isislovecruft/bridgedb\n.. |Coverage Status| image:: https://coveralls.io/repos/isislovecruft/bridgedb/badge.png?branch=develop\n :target: https://coveralls.io/r/isislovecruft/bridgedb?branch=develop\n\n\n.. image:: doc/sphinx/source/_static/bay-bridge.jpg\n :scale: 80%\n :align: center\n\n\n.. contents::\n :backlinks: entry\n\n\n=====================\nWhat are Tor Bridges?\n=====================\n\n`Tor Bridges `__ are special\nTor relays which are not listed in the public relay directory. They are\nused to help circumvent `censorship `__ by\nproviding users with connections to the public relays in the Tor\nnetwork.\n\nTor Bridges are different from normal relays in another important way:\nthey can run what are called *Pluggable* *Transports*.\n\n-----------------------------\nWhat's a Pluggable Transport?\n-----------------------------\n\nA `Pluggable\nTransport `__\nis a program which is *pluggable* \u2014 meaning that it is meant to work\nwith lots of other anonymity and censorship circumvention software, not\njust Tor \u2014 and is a *transport* \u2014 meaning that it transports your\ninternet traffic, usually in a way which makes it look different. For\nexample,\n`Obfsproxy `__ is\na Pluggable Transport which disguises your traffic by adding an\nobfuscating layer of encryption.\n\n---------------------\nSo how do I use this?\n---------------------\n\nWell, probably, you don't. But if you're looking for bridges, you can\nuse `the web interface `__ of the\nBridgeDB instance deployed by the Tor Project, which has instructions on\ngetting the Pluggable Transports-capable Tor Browser Bundle, as well as\ninstructions for getting extra Bridges.\n\n\n================\nMaintainer Setup\n================\n\nIf you'd like to hack on BridgeDB, you might wish to read BridgeDB's\n`developer documentation `__. The rest of\nthis document mainly concerns mainenance and installation instructions.\n\n-----------------------------\nDependencies and installation\n-----------------------------\n\nBridgeDB requires the following OS-level dependencies:\n\n- python>=2.7\n- python-dev\n- build-essential\n- gnupg (preferrably, gnupg2)\n- OpenSSL>=1.0.1g\n- `SQLite3 `__\n- `MaxMind GeoIP `__\n- libgeoip-dev\n- geoip-database\n- `python-setuptools `__\n- libjpeg-dev\n\nAs well as any Python dependencies in the ``requirements.txt`` file.\n\n.. note: There are additional dependencies for things like running the test\n suites, building BridgeDB's developer documentation, etc. Read on for more\n info if you wish to enable addition features.\n\n\n------------------\nDeploying BridgeDB\n------------------\n\nBridgeDB should work with or without a Python virtualenv.\n\n- Install Python 2.7, and other OS-level dependencies. On Debian, you\n can do::\n\n sudo apt-get install build-essential openssl python python-dev \\\n python-setuptools sqlite3 gnupg2 libgeoip-dev geoip-database\n\n\n- Install Pip 1.3.1 or later. Debian has this version, but if for some\n reason that or a newer version isn't available, the easiest way to\n install a newer Pip is to use the Pip development teams's `getpip\n script `__::\n\n wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py\n sudo python get-pip.py\n\n\n- **(virtualenv installs only)** Use Pip to install virtualenv and\n `virtualenvwrapper `__::\n\n sudo pip install --upgrade virtualenv virtualenvwrapper\n\n\n- **(virtualenv installs only)** Configure virtualenvwrapper and create a\n virtualenv for BridgeDB::\n\n WORKON_HOME=${HOME}/.virtualenvs\n export WORKON_HOME\n mkdir -p $WORKON_HOME\n source $(which virtualenvwrapper.sh)\n git clone https://git.torproject.org/bridgedb.git && cd bridgedb\n mkvirtualenv -a $PWD -r requirements.txt --unzip-setuptools --setuptools bridgedb\n\n From now on, to use BridgeDB's virtualenv, just do ``$ workon bridgedb``\n (after sourcing virtualenvwrapper.sh, as before). To exit the virtualenv\n without exiting the shell, do ``$ deactivate``.\n\n\n- **(virtualenv installs only)** To install, set PYTHONPATH to include the\n root directory of the virtualenv::\n\n export PYTHONPATH=$PYTHONPATH:${VIRTUAL_ENV}/lib/python2.7/site-packages\n\n\n- Then, proceed as usual::\n\n python setup.py install --record installed-files.txt\n\n\n============================\nEnabling additional features\n============================\n\n------------\nTranslations\n------------\n\n**Using New Translations**:\n\nThis should be done when newly completed translations are available in\nTransifex.\n\nPiece of cake. Running ``maint/get-completed-translations`` will take\ncare of cloning *only* the ``bridgedb_completed`` branch of Tor's\n`translations repo `__\nand placing all the updated files in their correct locations.\n\n-------\n\n**Requesting Translations for Altered/Added Source Code**:\n\nThis should be done whenever any of the strings requiring translation --\n``_(\"the ones inside the weird underscore function, like this\")`` -- are\nchanged, or new ones are added. See ``lib/bridgedb/strings.py``.\n\nTranslations for Tor Project repos are kept `in a separate\nrepo `__. You'll need to\nextract the strings from BridgeDB's source code into .pot templates, and\nplace these .po files into the ``translation`` repo in the ``bridgedb``\nbranch. After than the .po files should be put into Transifex (don't ask\nme how this works\u2026) and translated. After the translations are complete,\nthe finished .po files should be placed into the ``bridgedb_completed``\nbranch.\n\n- To extract all strings from BridgeDB's source::\n\n python setup.py extract_messages\n\n A .pot file will be created in ./i18n/templates/bridgedb.pot\n\n\n- Initialise catalogs for each desired language::\n\n python setup.py init_catalog -l LANG\n\n where ``LANG`` is the 2 or 4 letter country-code, eg. 'es'. If you've\n already initialised a particular language, do instead::\n\n python setup.py update_catalog\n\n\n-------\n\n--------------\nEnabling HTTPS\n--------------\n\nCreate a self-signed certificate with::\n\n scripts/make-ssl-cert\n\nOr, place an existing certificate in the path specified in bridgedb.conf\nby the ``HTTPS_CERT_FILE`` option, and a private key where\n``HTTPS_KEY_FILE`` points to. The defaults are 'cert' and 'privkey.pem',\nrespectively.\n\n\n------------------------\nEnabling CAPTCHA Support\n------------------------\n\nBridgeDB has two ways to use CAPTCHAs on webpages. The first uses reCaptcha_,\nan external Google service (this requires an account with them), which\nBridgeDB fetches the CAPTCHAs images from for each incoming request from a\nclient. The second method uses a local cache of pre-made CAPTCHAs, created by\nscripting Gimp using gimp-captcha_. The latter cannot easily be run on\nheadless server, unfortunately, because Gimp requires an X server to be\ninstalled.\n\n.. _reCaptcha: https://www.google.com/recaptcha\n.. _gimp-captcha: https://github.com/isislovecruft/gimp-captcha\n\n\n**reCaptcha**\n\nTo enable fetching CAPTCHAs from the reCaptcha API server, set these\noptions in bridgedb.conf::\n\n RECAPTCHA_ENABLED\n RECAPTCHA_PUB_KEY\n RECAPTCHA_SEC_KEY\n\n-------\n\n**gimp-captcha**\n\nTo enable using a local cache of CAPTCHAs, set the following options::\n\n GIMP_CAPTCHA_ENABLED\n GIMP_CAPTCHA_DIR\n GIMP_CAPTCHA_HMAC_KEYFILE\n GIMP_CAPTCHA_RSA_KEYFILE\n\n-------\n\n--------------------\nGnuPG email signing:\n--------------------\n\nIn your ``bridgedb.conf`` file, make sure that::\n\n EMAIL_GPG_SIGNING_ENABLED = True\n\nand edit the following option to add the full fingerprint of the GnuPG key\nthat should be used to by BridgeDB to sign outgoing emails::\n\n EMAIL_GPG_PRIMARY_KEY_FINGERPRINT\n\nThe key specified by ``EMAIL_GPG_PRIMARY_KEY_FINGERPRINT`` can be a master\nkey, or a subkey (with or without the private portions of its corresponding\nmaster key), but it **must** be inside the ``secring.gpg`` and ``pubring.gpg``\nkeyrings inside the directory specified in the ``bridgedb.conf`` option::\n\n EMAIL_GPG_HOMEDIR\n\nIf the key has requires a passphrase for signing, you'll also need to set\neither of::\n\n EMAIL_GPG_PASSPHRASE\n EMAIL_GPG_PASSPHRASE_FILE\n\n\n----------------------------------------------------------\nPreventing already-blocked bridges from being distributed:\n----------------------------------------------------------\n\nUncomment or add ``COUNTRY_BLOCK_FILE`` to your bridgedb.conf. This file\nshould contain one bridge entry per line, in the format::\n\n fingerprint country-code \n\nIf the ``COUNTRY_BLOCK_FILE`` file is present, bridgedb will filter\nblocked bridges from the responses it gives to clients requesting\nbridges.\n\n\n================\nTesting BridgeDB\n================\n\nBefore running to any of BridgeDB's test suites, make sure you have the\nadditional dependencies in the Pip requirements file,\n``.test.requirements.txt`` installed::\n\n pip install -r .test.requirements.txt\n\nTo create a bunch of fake bridge descriptors to test BridgeDB, do::\n\n bridgedb mock [-n NUMBER_OF_DESCRIPTORS]\n\nNote that you will need to install\n`leekspin `__ in order to run the\n``bridgedb mock`` command. See ``doc/HACKING.md`` for details.\n\nAnd finally, to run the test suites, do::\n\n make coverage\n\nIf you just want to run the tests, and don't care about code coverage\nstatistics, see the ``bridgedb trial`` and ``bridgedb test`` commands.\n\n\n================\nRunning BridgeDB\n================\n\nTo run BridgeDB, simply make any necessary changes to bridgedb.conf, and do::\n\n bridgedb\n\nAnd remember that all files/directories in ``bridgedb.conf`` are assumed\nrelative to the runtime directory. By default, BridgeDB uses the current\nworking directory; you can, however specify an a different runtime\ndirectory::\n\n bridgedb -r /srv/bridges.torproject.org/run\n\nMake sure that the files and directories referred to in bridgedb.conf\nexist. However, many of them, if not found, will be touched on disk so\nthat attempts to read/write from/to them will not raise excessive\nerrors.\n\n\n----------------------------------------------\nReloading Bridges From Their Descriptor Files:\n----------------------------------------------\n\nWhen you have new lists of bridges from the Bridge Authority, replace\nthe old files and do::\n\n bridgedb --reload\n\nOr just give it a SIGHUP::\n\n kill -s SIGHUP `cat .../run/bridgedb.pid`\n\n\n---------------------------------------------------\nTo extract bucket files of all unallocated bridges:\n---------------------------------------------------\n\nEdit the configuration file value ``FILE_BUCKETS`` according to your\nneeds. For example, the following is a possible configuration::\n\n FILE_BUCKETS = { \"name1\": 10, \"name2\": 15, \"foobar\": 3 }\n\nThis configuration for buckets would result in 3 files being created for\nbridge distribution: name1-2010-07-17.brdgs, name2-2010-07-17.brdgs and\nfoobar-2010-07-17.brdgs. The first file would contain 10 bridges from\nBridgeDB's 'unallocated' pool. The second file would contain 15 bridges\nfrom the same pool and the third one similarly 3 bridges. These files\ncan then be handed out to trusted parties via mail or fed to other\ndistribution mechanisms such as Twitter.\n\nTo dump all buckets to their files, send BridgeDB a ``SIGUSR1`` signal\nby doing::\n\n kill -s SIGUSR1 `cat .../run/bridgedb.pid`\n\n\n=========================\nUsing a BridgeDB Instance\n=========================\n\nObviously, you'll have to feed it bridge descriptor files from a\nBridgeAuthority. There's currently only one BridgeAuthority in the entire\nworld, but Tor Project is, of course, very interested in adding support for\nmultiple BridgeAuthorities so that we can scale our own network, and make it\neasier for individual and organisations who wish to run a lot of Tor bridge\nrelays have an easier time distributing those bridges themselves (if they wish\nto do so). If you'd like to fund our work on this, please contact\ntor-dev@lists.torproject.org!\n\n----------------------------------\nAccessing the HTTPS User Interface\n----------------------------------\n\nJust connect to the appropriate port. (See the ``HTTPS_PORT`` and\n``HTTP_UNENCRYPTED_PORT`` options in the ``bridgedb.conf`` file.)\n\nThe HTTPS interface for our BridgeDB instance can be found `here\n`__.\n\n\n----------------------------------\nAccessing the Email User Interface\n----------------------------------\n\nAny mail sent to the ``EMAIL_PORT`` with a destination username as defined by\nthe ``EMAIL_USERNAME`` configuration option (the default is ``'bridge'``,\ne.g. bridges@...) and sent from an ``@riseup.net``, ``@gmail.com``, or\n``@yahoo.com`` address (by default, but configurable with the\n``EMAIL_DOMAINS`` option).\n\nYou can email our BridgeDB instance `here `__.\n\n=================\nContact & Support\n=================\n\nSend your questions, patches, and suggestions to\n`the tor-dev mailing list `__\nor `isis `__.\n", "description_content_type": null, "docs_url": "https://pythonhosted.org/bridgedb/", "download_url": "https://gitweb.torproject.org/bridgedb.git", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://www.torproject.org", "keywords": null, "license": "UNKNOWN", "maintainer": null, "maintainer_email": null, "name": "bridgedb", "package_url": "https://pypi.org/project/bridgedb/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/bridgedb/", "project_urls": { "Download": "https://gitweb.torproject.org/bridgedb.git", "Homepage": "https://www.torproject.org" }, "release_url": "https://pypi.org/project/bridgedb/0.3.6/", "requires_dist": null, "requires_python": null, "summary": "Backend systems for distribution of Tor bridge relays", "version": "0.3.6" }, "last_serial": 2252199, "releases": { "0.3.0": [], "0.3.1": [ { "comment_text": "", "digests": { "md5": "152d057b02c5d37d3a6935e94b95ba0f", "sha256": "b684486ac9971f07bd7c58496c2b58e7f5223e3bf23f25f36898ce14293d6872" }, "downloads": -1, "filename": "bridgedb-0.3.1.tar.gz", "has_sig": true, "md5_digest": "152d057b02c5d37d3a6935e94b95ba0f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 753098, "upload_time": "2015-03-25T19:01:49", "url": "https://files.pythonhosted.org/packages/f6/81/ce384da7eb7925749ec35726ae81b27cef67a74ad3924a23fbec79d8f38a/bridgedb-0.3.1.tar.gz" } ], "0.3.6": [ { "comment_text": "", "digests": { "md5": "ac56a7250ffdd938e00550b9551ab42f", "sha256": "21ce5319379d5427f9f4946282a72107417e9c2b6285f189b79d7faaab94eba0" }, "downloads": -1, "filename": "bridgedb-0.3.6-py2.7.egg", "has_sig": true, "md5_digest": "ac56a7250ffdd938e00550b9551ab42f", "packagetype": "bdist_egg", "python_version": "2.7", "requires_python": null, "size": 1043091, "upload_time": "2016-07-29T22:59:56", "url": "https://files.pythonhosted.org/packages/27/91/7a61ec80a20c306eb9280301efb550634b3c1b4a12a2505f1567188240ec/bridgedb-0.3.6-py2.7.egg" }, { "comment_text": "", "digests": { "md5": "f08489421cf559b3750a19ce19c2b4e6", "sha256": "22842c56c72616d3d6886958414ab21ebd7bf195802d8da82882d1623e3bc85c" }, "downloads": -1, "filename": "bridgedb-0.3.6.tar.gz", "has_sig": true, "md5_digest": "f08489421cf559b3750a19ce19c2b4e6", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 277472, "upload_time": "2016-07-29T23:00:06", "url": "https://files.pythonhosted.org/packages/f8/23/e7c0f7a5a8bf2cda8634bf807207effea896a6f2e370769a47f2829b4209/bridgedb-0.3.6.tar.gz" }, { "comment_text": "", "digests": { "md5": "488e2dccbdb85d8081180e9b7204babd", "sha256": "0797796d3a1f2428abbbf2dbda94b677426aa698adcc317619c90c075b4277fa" }, "downloads": -1, "filename": "bridgedb-0.3.6.zip", "has_sig": true, "md5_digest": "488e2dccbdb85d8081180e9b7204babd", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 328875, "upload_time": "2016-07-29T23:00:17", "url": "https://files.pythonhosted.org/packages/c4/72/3a2213d9f5f796045fbbc69824f3375286c2ecc4bdab44f836825231e8ff/bridgedb-0.3.6.zip" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "ac56a7250ffdd938e00550b9551ab42f", "sha256": "21ce5319379d5427f9f4946282a72107417e9c2b6285f189b79d7faaab94eba0" }, "downloads": -1, "filename": "bridgedb-0.3.6-py2.7.egg", "has_sig": true, "md5_digest": "ac56a7250ffdd938e00550b9551ab42f", "packagetype": "bdist_egg", "python_version": "2.7", "requires_python": null, "size": 1043091, "upload_time": "2016-07-29T22:59:56", "url": "https://files.pythonhosted.org/packages/27/91/7a61ec80a20c306eb9280301efb550634b3c1b4a12a2505f1567188240ec/bridgedb-0.3.6-py2.7.egg" }, { "comment_text": "", "digests": { "md5": "f08489421cf559b3750a19ce19c2b4e6", "sha256": "22842c56c72616d3d6886958414ab21ebd7bf195802d8da82882d1623e3bc85c" }, "downloads": -1, "filename": "bridgedb-0.3.6.tar.gz", "has_sig": true, "md5_digest": "f08489421cf559b3750a19ce19c2b4e6", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 277472, "upload_time": "2016-07-29T23:00:06", "url": "https://files.pythonhosted.org/packages/f8/23/e7c0f7a5a8bf2cda8634bf807207effea896a6f2e370769a47f2829b4209/bridgedb-0.3.6.tar.gz" }, { "comment_text": "", "digests": { "md5": "488e2dccbdb85d8081180e9b7204babd", "sha256": "0797796d3a1f2428abbbf2dbda94b677426aa698adcc317619c90c075b4277fa" }, "downloads": -1, "filename": "bridgedb-0.3.6.zip", "has_sig": true, "md5_digest": "488e2dccbdb85d8081180e9b7204babd", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 328875, "upload_time": "2016-07-29T23:00:17", "url": "https://files.pythonhosted.org/packages/c4/72/3a2213d9f5f796045fbbc69824f3375286c2ecc4bdab44f836825231e8ff/bridgedb-0.3.6.zip" } ] }