commit f20779b57b9729a15ce7aba85711a06f9efa6f45 Author: Isis Lovecruft isis@torproject.org Date: Sat Mar 29 07:50:48 2014 +0000

Rewrite several sections of README. --- README | 59 +++++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 47 insertions(+), 12 deletions(-)

diff --git a/README b/README index 8d372de..2a2fa81 100644 --- a/README +++ b/README @@ -160,20 +160,39 @@ 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: + +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

-A [recaptcha.net](https://www.google.com/recaptcha) account is required. +##### 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: +Add these two options to your bridgedb.conf::

- EMAIL_GPG_SIGNING_ENABLED - EMAIL_GPG_SIGNING_KEY + 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. @@ -207,14 +226,25 @@ Enter the following commands at the ```sqlite>``` prompt: To run BridgeDB, simply make any necessary changes to bridgedb.conf, and do: ```bridgedb```.

-When you have new lists of bridges, replace the old files and do: +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 --reload + 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: @@ -229,13 +259,18 @@ 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 a yahoo or gmail address (by default, configured with the +#### 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 ```@riseup.net```, +```@gmail.com```, or ```@yahoo.com``` address (by default, configured with the EMAIL_DOMAINS option).

### Support