[tor-commits] [bridgedb/develop] Rewrite several sections of README.

[isis at torproject.org]

commit f20779b57b9729a15ce7aba85711a06f9efa6f45
Author: Isis Lovecruft <isis at 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 at ...)
-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 at ...)  and sent from an ```@riseup.net```,
+```@gmail.com```, or ```@yahoo.com``` address (by default, configured with the
 EMAIL_DOMAINS option).
 
 ### Support