vanguards-example.conf

## Example vanguards configuration file
#
# The values in this file are the defaults. You do not need to specify
# options in your config file unless you wish to change the defaults.

## Global options
[Global]

# IP address that the Tor control port is listening on:
control_ip = 127.0.0.1

# TCP port the control port is listening on.
# Empty means try both 9051 and 9151
control_port =

# If set, use this filesystem control socket instead of IP+Port:
# If this and control_port are not set, we first try
# "/run/tor/control", and then 9051, then 9151.
control_socket =

# If set, use this value as the control port password.
# Note that vanguards discovers and uses Cookie authentication
# automatically, so you should not need a password if Tor is configured
# to use CookieAuthentication, via tor's torrc.
control_pass =

# Enable/disable active vanguard update of layer2 and layer3 guards
enable_vanguards = True

# Enable/disable the bandwidth side channel detection checks:
enable_bandguards = True

# Enable/disable circuit build timeout analysis (informational only):
enable_cbtverify = False

# Enable/disable checks on Rendezvous Point overuse attacks:
enable_rendguard = True

# Enable/disable reporting of important/relevant Tor logs
enable_logguard = True

# Close circuits upon suspected attack conditions:
close_circuits = True

# Enable/disable path validation analysis (for integration tests):
enable_pathverify = False

# If True, we write (or update/rotate) layer2 and layer3 vanguards in torrc,
# then exit. This option disables the bandguards and rendguard defenses.
# This option exists so that vanguards can be run hourly, from eg cron,
# in situations where control port load is too high to keep a vanguards
# instance attached. Note that with this option set, Tor will stop working
# if all guard relays in a layer go down (on the other hand, when vanguards
# is continually running, it can monitor the consensus and switch relays
# that go down on the fly).
one_shot_vanguards = False

# The current loglevel. Do not log below this level.
# Available values are: ERROR, WARN, NOTICE, INFO, DEBUG.
loglevel = NOTICE

# If specified, log to this file instead of stdout.
# If this is :syslog:, then log to the system logger.
logfile =

# Name of state file (with absolute path, or relative to current directory):
state_file = vanguards.state


## Vanguards: layer1, layer2, and layer3 rotation params.
[Vanguards]

# How long to keep our layer1 guard(s).
# (0 means use Tor default: ~90 days currently):
layer1_lifetime_days = 0

# The maximum amount of time to keep a layer2 guard:
max_layer2_lifetime_hours = 1080

# The maximum amount of time to keep a layer3 guard:
max_layer3_lifetime_hours = 48

# The minimum amount of time to keep a layer2 guard:
min_layer2_lifetime_hours = 24

# The minimum amount of time to keep a layer3 guard:
min_layer3_lifetime_hours = 1

# The number of layer1 guards.
# Note that this setting causes us to set NumEntryGuards torrc option,
# which should apply to both bridge and guard use.
num_layer1_guards = 2

# The number of layer2 guards:
num_layer2_guards = 4

# The number of layer3 guards:
num_layer3_guards = 8


## Bandguards: Mechanisms to detect + mitigate bandwidth side channel attacks.
[Bandguards]

# Maximum number of hours to allow any circuit to remain open.
# This option exists because Tor relays rotate TLS connections 1x/week
# and an aversary that holds circuits opened longer than this will have
# an easier time with traffic analysis, due to lack of multiplexing with
# other traffic. Shorter values than 24 hours do not make much sense,
# and extremely low values like 1 hour may make you stand out.
# Set this higher if you actually need connections to stay open
# to your service.
# (set to 0 to disable):
circ_max_age_hours = 24

# Maximum amount of kilobytes that can be present in a hidden service
# descriptor before we close the circuit.
# Typical onion service descriptors are only 14kb, but onionbalance
# configurations may take more. This option exists because relays
# can flood hsdesc lookups and responses with extra data, which
# may be useful for traffic analysis.
# (set to 0 to disable):
circ_max_hsdesc_kilobytes = 30

# Maximum amount of kilobytes that can be sent on a service-side
# introduction circuit before it is closed.
# This can help with DoS attacks and resulting traffic analysis,
# but it may impact reachability so it is off by default.
# (set to 0 to disable):
circ_max_serv_intro_kilobytes = 0

# Total maximum megabytes on any circuit before we close it. Note that
# while HTTP GET can resume if this limit is hit, HTTP POST will not.
# This means that applications that require large data submission (eg
# SecureDrop or onionshare) should set this much higher. Also, While web
# clients *can* resume GET downloads that get cut off due to this setting,
# most do not handle this case properly. Hence it is disabled by
# default. However, flooding circuits with traffic can be used to assist
# various traffic analysis attacks, hence if you do not need large downloads,
# consider setting this, as well as generaly monitoring your service for
# large traffic spikes.
# (set to 0 to disable):
circ_max_megabytes = 0

# Warn if we can't build or use circuits for this many seconds.
# Connectivity loss can be a side channel or confirmation attack, especially
# for services. Log monitoring tools should be used to keep an eye on this.
# Very low values may have false positives, though.
# (set to 0 to disable):
circ_max_disconnected_secs = 30

# Warn if we are disconnected from the Tor network for this many seconds.
# This should be less likely to happen than failure to build circuits, since
# our TLS connections to the Tor network should not die in normal operation,
# unless Guards go down. Again, use log monitoring tools to keep an eye out
# for this.
# (set to 0 to disable):
conn_max_disconnected_secs = 15

## Rendguard: Monitors service-side Rendezvous Points to detect misuse/attack
[Rendguard]

# No relay should show up as a Rendezvous Point more often than this ratio
# multiplied by its bandwidth weight:
rend_use_max_use_to_bw_ratio = 5.0

# What is percent of the network weight is not in the consensus right now?
# Put another way, the max number of rend requests from relays not in the
# consensus is rend_use_max_use_to_bw_ratio times this churn rate. This
# option protects against rend use attacks that try to connect to fake
# or private rendezvous points.
rend_use_max_consensus_weight_churn = 1.0

# Close circuits where the Rendezvous Point appears too often. Note that an
# adversary can deliberately cause RP overuse in order to impact availability.
# If this is a concern, either set this to false, or raise the ratio
# parameter above.
rend_use_close_circuits_on_overuse = True

# Total number of circuits we need before we begin enforcing rendezvous point
# ratio limits. Setting this lower may cause our percentile usages to have
# false positives in the above usage detection. We need enough circuits built
# to get a representative sample of the probabilities of relays. Consider
# raising this value (and filing a bug) if you get false positives of
# rend overuse.
rend_use_global_start_count = 1000

# Number of times a relay must be seen as a Rendezvous Point before applying
# ratio limits. Again, this helps reduce false positives. Consider
# raising this value (and filing a bug) if you get false positives of
# rend overuse.
rend_use_relay_start_count = 100

# Divide all relay counts by two once the total circuit count hits this many.
# This helps ensure that new relays can't show up and get overused.
rend_use_scale_at_count = 20000


## Logguard: Monitors log messages for potential issues and debugging
[Logguard]

# If true, set ProtocolWarnings to 1 in Tor. This raises the loglevel
# of various Tor procol errors to WARN. Most such messages are due to
# Tor implementation bugs, but they may also appear while a service is
# under attack.
log_protocol_warns = True

# Save this many Tor log messages in a FIFO queue (rolling list), and dump
# them to NOTICE logs in vanguards when we encounter a suspicious issue
# that caused us to close a circuit.
log_dump_limit = 25

# The Tor log-level to use for the above log buffer.
log_dump_level = "NOTICE"