[tor-commits] [bridgedb/master] Cleanup explanations of options in bridgedb.conf.
isis at torproject.org
isis at torproject.org
Sun Jan 12 06:06:30 UTC 2014
commit 5f26b667d3a30a48c0f8582f88e2ef6b78ccdaf0
Author: Isis Lovecruft <isis at torproject.org>
Date: Sun Oct 6 05:39:22 2013 +0000
Cleanup explanations of options in bridgedb.conf.
---
bridgedb.conf | 268 +++++++++++++++++++++++++++++++++++++++------------------
1 file changed, 185 insertions(+), 83 deletions(-)
diff --git a/bridgedb.conf b/bridgedb.conf
index 88aa231..a0a1f57 100644
--- a/bridgedb.conf
+++ b/bridgedb.conf
@@ -1,13 +1,101 @@
+# -*- mode: python ; coding: utf-8 -*-
+#
+# +---------------+
+# | bridgedb.conf |
+# +---------------+
+#
+# This file uses Python syntax, and is sourced as if it were a .py file. Just
+# pretend you're writing Python, and everything will be peachy keen.
+#______________________________________________________________________________
+#
+# This file is part of BridgeDB, a Tor bridge distribution system.
+#
+# :copyright: (c) 2007-2013, The Tor Project, Inc.
+# (c) 2007-2013, all sentient entities within the AUTHORS file
+# :license: see LICENSE for licensing information
+#______________________________________________________________________________
-#==========
-# General-purpose options.
+#===========================#
+# General-purpose options #
+#___________________________#
-# Either a file in which to write our pid, or None
-PIDFILE = "bridgedb.pid"
+#----------------
+# Required Files \ You'll want to make sure that these ones exist!
+#------------------------------------------------------------------------------
+#
+# All filenames are taken as relative to the RUNTIME directory, which is the
+# current working directory when you call the ``bridgedb`` script, or you may
+# specify a particular RUNTIME directory by doing:
+#
+# $ bridgedb -r /path/to/some/nice/place
+#
+# Obviously, this config file should live in that directory, so that BridgeDB
+# can read it.
+#------------------------------------------------------------------------------
+
+# List of filenames from which we read ``@type bridge-server-descriptor``s, on
+# startup and on SIGHUP.
+BRIDGE_FILES = ["bridge-descriptors"]
+
+# List of filenames from which we read ``@type bridge-extra-info``
+# descriptors, for learning about a bridge's pluggable transports:
+EXTRA_INFO_FILES = ["cached-extrainfo", "cached-extrainfo.new"]
+
+# Filename from which we read ``@type bridge-network-status`` entries, for
+# learning which current bridges are Running, as well as their IPv6 addresses.
+STATUS_FILE = "networkstatus-bridges"
+
+# Certificate file and private key for the HTTPS Distributor. To create a
+# self-signed cert, run ``scripts/make-ssl-cert`` it will create these files
+# in your current directory.
+HTTPS_CERT_FILE="cert"
+HTTPS_KEY_FILE="privkey.pem"
+
+#----------------
+# Output Files \ Where to store created data
+#------------------------------------------------------------------------------
+#
+# These will get automatically created for you, just specify where they should
+# go.
+#------------------------------------------------------------------------------
# Either a file to log to, or None if we should log to the console.
LOGFILE = "bridgedb.log"
+# File to which we dump bridge pool assignments for statistics.
+ASSIGNMENTS_FILE = "assignments.log"
+
+# File in which to write our pid
+PIDFILE = "bridgedb.pid"
+
+# Filename of the database to store persistent info in.
+DB_FILE = "bridgedist.db"
+
+# Filename to log changes to persistent info in. For debugging and bugfixing.
+DB_LOG_FILE = "bridgedist.log"
+
+# Filename where we store our secret HMAC root key. This file and the key
+# inside are automatically created for you if they do not exist.
+MASTER_KEY_FILE = "secret_key"
+
+# Filename that contains blocked bridges list. Comment out to disable.
+#COUNTRY_BLOCK_FILE = "blocked-bridges"
+
+# A list of filenames that contain IP addresses (one per line) of proxies.
+# All IP-based distributors that see an incoming connection from a proxy
+# will treat them specially.
+PROXY_LIST_FILES = []
+
+#------------------
+# Logging Options \
+#------------------------------------------------------------------------------
+#
+# Be sure to also see the LOGFILE option above!
+#------------------------------------------------------------------------------
+
+# One of "DEBUG", "INFO", "WARNING", "ERROR"...
+LOGLEVEL = "DEBUG"
+
# If true, we scrub all potentially identifying information before we log it
SAFELOGGING = True
@@ -15,34 +103,9 @@ SAFELOGGING = True
LOGFILE_COUNT = 5
LOGFILE_ROTATE_SIZE = 10000000
-# One of "DEBUG", "INFO", "WARNING", "ERROR"...
-LOGLEVEL = "WARNING"
-
-# Files from which we read bridge descriptors, on start and on SIGHUP.
-BRIDGE_FILES = [ "./bridge-descriptors" ]
-
-# File from which we read routerstatus entries, for learning which
-# current bridges are Running.
-STATUS_FILE = "networkstatus-bridges"
-
-# Either a file that contains blocked bridges list or None
-#COUNTRY_BLOCK_FILE = "./blocked-bridges"
-
-# File from which we read extra-info entries, for learning pluggable
-# transports
-EXTRA_INFO_FILES = ["cached-extrainfo", "cached-extrainfo.new"]
# Only consider routers whose purpose matches this string.
BRIDGE_PURPOSE = "bridge"
-# File to store persistent info in.
-DB_FILE = "bridgedist.db"
-# File to log changes to persistent info in. For debugging and bugfixing.
-DB_LOG_FILE = "bridgedist.log"
-# File in which we store our secret HMAC root key.
-MASTER_KEY_FILE = "secret_key"
-
-# File to which we dump bridge pool assignments for statistics.
-ASSIGNMENTS_FILE = "assignments.log"
# How many clusters do we group IPs in when distributing bridges based on IP?
# Note that if PROXY_LIST_FILES is set (below), what we actually do here
@@ -51,60 +114,72 @@ ASSIGNMENTS_FILE = "assignments.log"
N_IP_CLUSTERS = 4
# If possible, always give a certain number of answers with a given ORPort.
-# This is a list of (port,minimum) tuples.
-FORCE_PORTS = [ (443, 1) ]
+# This is a list of ``(port, minimum)`` tuples.
+FORCE_PORTS = [(443, 1)]
# If possible, always give a certain number of answers with a given flag.
# Only "stable" is now supported. This is a list of (flag,minimum) tuples.
-FORCE_FLAGS = [ ("Stable", 1) ]
+FORCE_FLAGS = [("Stable", 1)]
-# A list of filenames that contain IP addresses (one per line) of proxies.
-# All IP-based distributors that see an incoming connection from a proxy
-# will treat them specially.
-PROXY_LIST_FILES = [ ]
-
-#==========
-# Options related to HTTPS
+#-------------------------------
+# HTTP(S) Distribution Options \
+#------------------------------------------------------------------------------
+#
+# These options configure the behaviour of the web interface bridge
+# distribution mechanism. If HTTPS_DIST is enabled, make sure that the above
+# HTTPS_CERT_FILE and HTTPS_KEY_FILE options point to the correct location of
+# your SSL certificate and key!
+#------------------------------------------------------------------------------
-# True if we are enabling distribution via HTTP or HTTPS; False otherwise.
+# Set to ``True`` to enable distribution via HTTP or HTTPS; False otherwise.
HTTPS_DIST = True
-# What proportion of bridges do we allocate to HTTP distribution? See
-# EMAIL_SHARE and RESERVED_SHARE.
-HTTPS_SHARE=10
-# An IP address (form "1.2.3.4") where we listen for HTTPS connections.
-# "None" to listen on the default interface.
-HTTPS_BIND_IP='127.0.0.1'
-# Port to listen on for incoming HTTPS connections
-HTTPS_PORT=6789
-# Certificate file
-HTTPS_CERT_FILE="cert"
-# Private key file.
-HTTPS_KEY_FILE="privkey.pem"
+
+# (string or None) The IP address where we listen for HTTPS connections. If
+# ``None``, listen on the default interface.
+HTTPS_BIND_IP = '127.0.0.1'
+
+# (integer or None) The port to listen on for incoming HTTPS connections.
+HTTPS_PORT = 6789
+
+# How many bridges do we give back in an answer?
+HTTPS_N_BRIDGES_PER_ANSWER = 3
+
+# Should we tell http users about the bridge fingerprints? Turn this on
+# once we have the vidalia/tor interaction fixed for everbody.
+HTTPS_INCLUDE_FINGERPRINTS = True
+
# If true, there is a trusted proxy relaying incoming messages to us: take
# the *last* entry from its X-Forwarded-For header as the client's IP.
HTTPS_USE_IP_FROM_FORWARDED_HEADER = False
-# IP and port to listen on for unencrypted HTTP connections.
-HTTP_UNENCRYPTED_BIND_IP=None
-HTTP_UNENCRYPTED_PORT=None
-# As HTTPS_USE_IP_FROM_FORWARDED_HEADER, but for unencrypted connections.
+# (string or None) The IP address to listen on for unencrypted HTTP
+# connections. Set to ``None`` to disable unencrypted connections to the web
+# interface.
+HTTP_UNENCRYPTED_BIND_IP = None
+
+# (integer or None) The port to listen on for incoming HTTP connections.
+HTTP_UNENCRYPTED_PORT = None
+
+# Same as the ``HTTPS_USE_IP_FROM_FORWARDED_HEADER`` option, but for
+# unencrypted connections.
HTTP_USE_IP_FROM_FORWARDED_HEADER = False
-# How many bridges do we give back in an answer?
-HTTPS_N_BRIDGES_PER_ANSWER=3
-HTTP_N_BRIDGES_PER_ANSWER=3
-# Should we tell http users about the bridge fingerprints? Turn this on
-# once we have the vidalia/tor interaction fixed for everbody.
-HTTPS_INCLUDE_FINGERPRINTS=True
+# The number of bridges to hand out per response by the unencrypted HTTP
+# distributor
+HTTP_N_BRIDGES_PER_ANSWER = 3
-#==========
-# Options related to Email
+#-------------------------------
+# Email Distribution Options \
+#------------------------------------------------------------------------------
+#
+# These options configure the behaviour of the email bridge distribution
+# mechanism. If EMAIL_DIST is enabled, make sure that the above
+# HTTPS_CERT_FILE and HTTPS_KEY_FILE options point to the correct location of
+# your SSL certificate and key!
+# ------------------------------------------------------------------------------
# True if we are enabling distribution via Email; false otherwise.
EMAIL_DIST = True
-# What proportion of bridges do we allocate to Email distribution? See
-# HTTPS_SHARE and RESERVED_SHARE.
-EMAIL_SHARE=10
# What email addresses do we use for outgoing email? EMAIL_FROM_ADDR goes
# in the From: line in outgoing headers, and EMAIL_SMTP_FROM_ADDR goes in
@@ -118,11 +193,12 @@ EMAIL_SMTP_PORT = 25
EMAIL_USERNAME = "bridges"
# Canonical versions of domains that we will reply to.
-EMAIL_DOMAINS = [ "gmail.com", "yahoo.com" ]
+EMAIL_DOMAINS = ["gmail.com", "yahoo.com"]
+
# Map from unofficial domain to canonical domain.
EMAIL_DOMAIN_MAP = { "mail.google.com" : "gmail.com",
- "googlemail.com" : "gmail.com",
- }
+ "googlemail.com" : "gmail.com"}
+
# Map from canonical domain to list of options for that domain. Recognized
# options are:
# "ignore_dots" -- the service ignores "." characters in email addresses.
@@ -131,14 +207,16 @@ EMAIL_DOMAIN_MAP = { "mail.google.com" : "gmail.com",
#
# Note that unrecognized options are ignored; be sure to spell them right!
EMAIL_DOMAIN_RULES = { 'gmail.com' : ["ignore_dots", "dkim"],
- 'yahoo.com' : ["dkim"]
- }
+ 'yahoo.com' : ["dkim"]}
+
# If there are any IPs in this list, only allow incoming connections from
# those IPs.
-EMAIL_RESTRICT_IPS=[]
+EMAIL_RESTRICT_IPS = []
+
# IP and port to listen on for email connections. Debugging only.
EMAIL_BIND_IP="127.0.0.1"
EMAIL_PORT=6725
+
# How many bridges do we give back in an answer?
EMAIL_N_BRIDGES_PER_ANSWER=3
@@ -150,22 +228,46 @@ EMAIL_INCLUDE_FINGERPRINTS = True
EMAIL_GPG_SIGNING_ENABLED = True
EMAIL_GPG_SIGNING_KEY = 'gnupghome/TESTING.subkeys.sec'
-#==========
-# Options related to unallocated bridges.
+#-------------------------------
+# Hashring Allocation Options \
+#------------------------------------------------------------------------------
+#
+# These options determine the proportions of bridges per hashring. When
+# BridgeDB receives a descriptor for a new bridge, that bridge is assigned to
+# a hashring. For example, if ``HTTPS_DIST`` and ``EMAIL_DIST`` are both
+# enabled, there is a hashring for bridges allocated to the HTTP(S)
+# Distributor, and another for the Email Distributor. In addition, an
+# "Unallocated" hashring is always created, in order to reserve some portion
+# of bridges for manual distribution, or as backup in the case of a major
+# blocking event. Once a bridge is assigned to one of these allocation groups,
+# it stays there; there is currently no mechanism for changing a bridge's
+# hashring allocation.
+#
+# The bridges are allocated to these groups with the following proportions:
+#
+# ``HTTPS_SHARE`` : ``EMAIL_SHARE`` : ``RESERVED_SHARE``
+# ------------------------------------------------------------------------------
+
+# The proportion of bridges to allocate to HTTP distribution.
+HTTPS_SHARE = 10
-# We split bridges into a group accessible by HTTPS queries; a group
-# accessible by email queries; and a group that we don't assign to any
-# query mechanism. Once a bridge is assigned to either of the first
-# two groups, it stays there persistently. The bridges are allocated
-# to these groups in a proportion of
-# HTTPS_SHARE : EMAIL_SHARE : RESERVED_SHARE
-RESERVED_SHARE=2
+# The proportion of bridges to allocate to Email distribution.
+EMAIL_SHARE = 10
+# An integer specifying the proportion of bridges which should remain
+# unallocated, for backup usage and manual distribution.
+RESERVED_SHARE = 2
+
+# A dictionary of {FILENAME: NUMBER} where FILENAME is a string specifying the
+# filename to store a certain NUMBER (an integer) of bridges in. The number of
+# bridges here is *not* a share/proportion, as above; instead it's literally
+# the number of bridges.
FILE_BUCKETS = {}
# Options related to recaptcha support.
# Enable/Disable recaptcha
RECAPTCHA_ENABLED = False
+
# Recaptcha API keys
RECAPTCHA_PUB_KEY = ''
-RECAPTCHA_PRIV_KEY = ''
+RECAPTCHA_PRIV_KEY = ''
More information about the tor-commits
mailing list