[tor-commits] [bridgedb/develop] Convert README from Markdown to ReStructuredText.
isis at torproject.org
isis at torproject.org
Thu Aug 28 11:55:14 UTC 2014
commit cf99f14dc0029a980e184d7035b8a55c3ea89d03
Author: Isis Lovecruft <isis at 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 [](https://travis-ci.org/isislovecruft/bridgedb) [](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 at ...) and sent from an ```@riseup.net```,
-```@gmail.com```, or ```@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 at 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 at 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 at ...) and sent from an ``@riseup.net``, ``@gmail.com``, or
+``@yahoo.com`` address (by default, but configurable with the
+``EMAIL_DOMAINS`` option).
+
+You can email our BridgeDB instance `here <mailto:bridges at torproject.org>`__.
+
+=================
+Contact & Support
+=================
+
+Send your questions, patches, and suggestions to
+`the tor-dev mailing list <mailto:tor-dev at lists.torproject.org>`__
+or `isis <mailto:isis at 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
More information about the tor-commits
mailing list