pub const ARTI_EXAMPLE_CONFIG: &str = "# (Built-in defaults for the arti configuration format.)\n# (This is an example file you can use as a template or as documentation.)\n\n# Rules about how arti should behave as an application\n[application]\n# If true, we should watch our configuration files for changes.\n#\n# (Note that this feature may misbehave if you change symlinks in the\n# paths to the directory holding the configuration files, if you\n# remove and recreate those directories, or if those directories\n# change for some other reason.)\n#\n# **Warning**: on platforms other than Windows, Linux, and Android,\n# the files are watched using a polling watcher,\n# which introduces a perceivable delay in configuration reloading,\n# and can be very expensive for large file trees.\n# This is due to a limitation in our file watching code,\n# which we hope to lift someday.\n#watch_configuration = false\n\n# If true, we should allow other processes run by the same user to inspect this\n# process\'s memory.\n#\n# (By default, assuming arti has been built with the `harden` feature flag, we\n# take what step we can, including disabling core dumps, to keep its memory and\n# state secret from other processes.)\n#\n#permit_debugging = false\n\n# If true, then we allow Arti to start even if the current user is root.\n#\n# (By default, we exit if we are running as root, since this is usually a\n# mistake.)\n#allow_running_as_root = false\n\n# Set up the Arti program to run as a proxy.\n[proxy]\n# Default port to use when listening to SOCKS connections. We always\n# listen on localhost.\n#\n# Note that only one process can listen on a given port at a time.\n#socks_listen = 9150\n\n# Port to use to listen for DNS requests. 0 means disabled.\n#dns_listen = 0\n\n# Configure logging\n[logging]\n\n# Specify filtering directives for sending trace messages to the console\n# (via standard output).\n#\n# It can be as simple as a single loglevel, or as complicated as a\n# list with per-module settings.\n#\n# You can override this setting with the -l, --log-level command-line option.\n#\n# Example:\n# trace_filter = \"info,tor_proto::channel=trace\"\n#\n# For more information, see https://docs.rs/tracing-subscriber/0.2.20/tracing_subscriber/filter/struct.EnvFilter.html\n#console = \"info\"\n\n# As above, but specify filtering directives for sending trace messages to\n# the journald logging system. Empty string means not to use journald.\n#journald = \"\"\n\n# You can also configure one or more log files, with different filters, and optional\n# rotation.\n#\n# For example (not the default):\n#files = [\n# {path = \"~/logs/debug.log\", filter=\"debug\"},\n# {path = \"~/logs/trace.log\", filter=\"trace\", rotate=\"daily\"},\n#]\n\n# Whether to log sensitive information (such as target hostnames and ip addresses)\n#\n# If set to `false` (the default), such information is not logged in messages of\n# level `info` or higher.\n#log_sensitive_information = false\n\n# The granularity with which to display times in our logs.\n#\n# When logging persistently, it can be risky to record very precise timing\n# information: if the logs are later exposed or compromised, they can help\n# traffic analysis attacks.\n#\n# To lower this risk, we support rounding the times in our logs, and displaying\n# them with less precision. This option configures the maximum degree of\n# precision we\'ll use. (We may use even a little less precision if you specify\n# an odd interval of time.)\n#\n# This option can\'t affect the granularity of times recorded by logging systems\n# outside of arti, including journald.\n#\n#time_granularity = \"1s\"\n\n# Locations to use for storing things on disk.\n#\n# These paths can use ~ to indicate the user\'s home directory, or a set\n# of shell-style variables to indicate platform-specific paths.\n#\n# Supported variables are ARTI_CACHE, ARTI_CONFIG, ARTI_SHARED_DATA,\n# ARTI_LOCAL_DATA, and USER_HOME.\n#\n# Multiple processes can share the same cache_dir. If they do, one of them\n# will download directory information for all of the others.\n[storage]\n#cache_dir = \"${ARTI_CACHE}\"\n#state_dir = \"${ARTI_LOCAL_DATA}\"\n\n#[storage.keystore]\n# Whether the keystore is enabled.\n#\n# If the `keymgr` feature is enabled and this option is:\n# * set to false, we will ignore the configured keystore path.\n# * set to \"auto\", the configured keystore, or the default keystore, if the\n# keystore path is not specified, will be used\n# * set to true, the configured keystore, or the default keystore, if the\n# keystore path is not specified, will be used\n#\n# If the `keymgr` feature is disabled and this option is:\n# * set to false, we will ignore the configured keystore path.\n# * set to \"auto\", we will ignore the configured keystore path.\n#\n# Setting this option to true when the `keymgr` feature is disabled is a\n# configuration error. Setting this option to false when `kind` is not `auto`\n# is a configuration error.\n#enabled = \"auto\"\n\n#[storage.keystore.primary]\n# The type of primary keystore to use, if any\n#\n# If the `keymgr` feature is enabled, this option can be set to\n# * \"auto\", to use the default keystore (native)\n# * \"native\", to use the native keystore\n# * \"ephemeral\", to use the ephemeral keystore (only supported if the\n# `ephemeral-keystore` feature is enabled)\n#\n# If the `keymgr` feature is not enabled, this option has no effect,\n# and can only be set to \"auto\".\n#\n# Setting this option to anything besides auto when the `keymgr`\n# feature is disabled is a configuration error.\n#kind = \"auto\"\n\n# Optionally configure C Tor keystores for arti to use.\n#\n# Note: The keystores listed here are read-only (keys are only\n# ever written to the primary keystore, configured in\n# `storage.keystore.primary`).\n#\n# Each C Tor keystore **must**:\n#\n# * have a unique identifier. It is an error to configure multiple keystores\n# with the same ID.\n# * have a corresponding arti hidden service configured in the\n# `[onion_services]` section with the same nickname\n#\n# For example:\n#\n# [storage.keystore.ctor.services.\"allium-cepa\"]\n#\n# This should be set to the `HiddenServiceDirectory` of your hidden service.\n# Arti will read `HiddenServiceDirectory/hostname`\n# and `HiddenServiceDirectory/private_key`.\n# (Note: if your service is running in restricted discovery mode, you must also set the\n# `[[onion_services.\"<the nickname of your svc>\".restricted_discovery.key_dirs]]`\n# to `HiddenServiceDirectory/client_keys`).\n# path = \"/var/lib/tor/allium_cepa\"\n#\n# The identifier of this keystore.\n# id = \"foo\"\n\n# [[storage.keystore.ctor.clients]]\n#\n# The identifier of this keystore.\n# id = \"bar\"\n#\n# This should be set to the `ClientOnionAuthDir` of your client.\n# If Arti is configured to run as a client (i.e. if it runs in SOCKS proxy mode),\n# it will read the client restricted discovery keys from this path.\n#\n# The key files are expected to have the `.auth_private` extension,\n# and their content **must** be of the form:\n# `<56-char-onion-addr-without-.onion-part>:descriptor:x25519:<x25519 private key in base32>`.\n#\n# Malformed files, and files that don\'t have the `.auth_private` extension, will be ignored.\n# path = \"/var/lib/tor/onion_auth\"\n\n# Describe how to enforce permissions on the filesystem when accessing the cache\n# and state directories. (This does not apply to configuration files)\n[storage.permissions]\n# If set to true, we ignore all filesystem permissions.\n#dangerously_trust_everyone = false\n\n# What user (if any) is trusted to own files and directories? \":current\" means\n# to trust the current user.\n#trust_user = \":current\"\n\n# What group (if any) is trusted to have read/write access to files and\n# directories? \":selfnamed\" means to trust the group with the same name as the\n# current user, if that user is a member.\n#trust_group = \":username\"\n\n# If set, gives a path prefix that will always be trusted. For example, if this\n# option is set to \"/home/\", and we are checking \"/home/username/.cache\", then\n# we always accept the permissions on \"/\" and \"/home\", but we check the\n# permissions on \"/home/username\" and \"/home/username/.cache\".\n#\n# (This is not the default.)\n#\n# ignore_prefix = \"/home/\"\n#ignore_prefix = \"\"\n\n# Bridges (for anticensorship support)\n[bridges]\n\n# Should we use configured bridges?\n# If set to false, we will ignore the configured bridges.\n# If set to \"auto\", we will use any bridges that are configured.\n# If set to true, bridges must be configured and will be used.\n#enabled = \"auto\"\n\n# What bridges (including pluggable transports) to use, in this syntax:\n# bridges = [\n# \"<IP>:<ORPort> <fingerprint> [<fingerprint> ...]\",\n# \"<transport> <host>:<ORPort>|- <fingerprint> [...] [<key>=<val> ...]\",\n# ]\n#\n# For example:\n# bridges = [\n# \"192.0.2.83:80 $0bac39417268b96b9f514ef763fa6fba1a788956\",\n# \"[2001:db8::3150]:8080 $0bac39417268b96b9f514e7f63fa6fb1aa788957\",\n# \"obfs4 bridge.example.net:80 $0bac39417268b69b9f514e7f63fa6fba1a788958 ed25519:dGhpcyBpcyBbpmNyZWRpYmx5IHNpbGx5ISEhISEhISA iat-mode=1\",\n# ]\n#\n# You may specify all the bridge lines in one multi-line string:\n# bridges = \'\'\'\n# 192.0.2.83:80 $0bac39417268b96b9f514ef763fa6fba1a788956\n# [2001:db8::3150]:8080 $0bac39417268b96b9f514e7f63fa6fb1aa788957\n# obfs4 bridge.example.net:80 $0bac39417268b69b9f514e7f63fa6fba1a788958 ed25519:dGhpcyBpcyBbpmNyZWRpYmx5IHNpbGx5ISEhISEhISA iat-mode=1\n# \'\'\'\n#\n# (Note that these are just examples, not real bridges - they will not work.)\n#\n#bridges = []\n\n# An example managed pluggable transport binary.\n# [[bridges.transports]]\n\n# Which pluggable transports does this binary provide?\n# protocols = [\"obfs4\", \"obfs5\"]\n\n# Path to the binary to be run.\n# path = \"/usr/bin/obfsproxy\"\n\n# Any command-line arguments to pass to the binary (empty if not specified).\n# arguments = [\"-obfs4\", \"-obfs5\"]\n\n# Should we run this binary on startup? If false or unspecified, the binary will be\n# launched when we first attempt to use any of the transports it provides instead.\n# run_on_startup = true\n\n# An example unmanaged pluggable transport.\n# [[bridges.transports]]\n#\n# Which protocols does this transport provide?\n# protocols = [\"obfs4\"]\n#\n# Where can we contact this transport?\n# (This should be a local SOCKS5 proxy address.)\n# proxy_addr = \"127.0.0.1:31337\"\n\n# Replacement values for consensus parameters. This is an advanced option\n# and you probably should leave it alone. Not all parameters are supported.\n# These are case-sensitive.\n#\n[override_net_params]\n# For example (not the defaults):\n# circwindow = 1000\n# min_paths_for_circs_pct = 60\n\n# Configuration for timing when and how often we should download directory\n# information.\n#\n# We use a randomized algorithm for determining when to retry. With\n# the various retry_* options, \"num\" is the number of downloads to\n# attempt, and \"initial_delay\" is a parameter determining both our\n# _first_ delay before we reattempt, and our _minimum_ delay for\n# subsequent attempts.\n[download_schedule]\n\n# How to retry our initial bootstrapping when we\'re trying to start up.\n#retry_bootstrap = { attempts = 128, initial_delay = \"1 sec\", parallelism = 1 }\n\n# How to retry a single consensus download.\n#retry_consensus = { attempts = 3, initial_delay = \"1 sec\", parallelism = 1 }\n\n# How to retry a set of authority certificate downloads.\n#retry_certs = { attempts = 3, initial_delay = \"1 sec\", parallelism = 1 }\n\n# How to retry a set of microdescriptor downloads.\n#retry_microdescs = { attempts = 3, initial_delay = \"1 sec\", parallelism = 4 }\n\n# Information about how premature or expired our directories are allowed to be.\n#\n# These options help us tolerate clock skew, and help survive the case where the\n# directory authorities are unable to reach consensus for a while.\n[directory_tolerance]\n# For how long before a directory document is valid should we accept it?\n#pre_valid_tolerance = \"1 day\"\n\n# For how long after a directory document is valid should we consider it usable?\n#post_valid_tolerance = \"3 days\"\n\n# Tells the circuit manager rule for constructing circuit paths\n[path_rules]\n\n# How far apart do relays need to be in IP-space before they can be\n# used in the same circuit? For example, \"ipv4_subnet_family_prefix=16\"\n# means that two relays cannot appear in the same circuit if their\n# IPv4 addresses begin with the same 16 bits.\n#ipv4_subnet_family_prefix = 16\n#ipv6_subnet_family_prefix = 32\n\n# Which addresses are we willing to contact directly?\n#\n# This option can be used to specify a set of addresses or ports that are\n# permitted: typically, because a local firewall blocks everything else. For\n# example, [ \"*:80\", \"*:443\"] would only try to connect to relays on the network\n# that support port 80 or port 443. You can use prefix lengths and port ranges,\n# too: \"198.51.100.0/24:1-1024\" is a valid pattern.\n#\n# By default, all addresses and ports are permitted.\n#reachable_addrs = [ \"*:*\" ]\n\n# Which target (exit) ports may require long-lived connections?\n#\n# When we connect to a port on this list, we only consider relays that have the\n# Stable flag, indicating that they have a relatively high time between circuit\n# failures.\n#long_lived_ports = [ 21, 22, 706, 1863, 5050, 5190, 5222, 5223, 6523, 6667, 6697, 8300 ]\n\n# Configure preemptive circuit construction.\n#\n# Preemptive circuits are built ahead of time, to anticipate client need. This\n# section configures the way in which this demand is anticipated and in which\n# these circuits are constructed.\n[preemptive_circuits]\n# If we have at least this many available circuits, we suspend\n# construction of preemptive circuits. whether our available circuits\n# support our predicted exit ports or not.\n#disable_at_threshold = 12\n\n# At startup, which exit ports should we expect that the client will want?\n#\n# (Over time, new ports are added to this list in response to what the client\n# has actually requested.)\n#initial_predicted_ports = [80, 443]\n\n# After we see the client request a connection to a new port, how long should we\n# predict that the client will still want to have circuits available for that\n# port?\n#prediction_lifetime = \"1 hour\"\n\n# How many available circuits should we try to have, at minimum, for each\n# predicted exit port?\n#min_exit_circs_for_port = 2\n\n# Configuration information about the Tor network itself\n[tor_network]\n# List of locations to look in when downloading directory information\n# we don\'t actually have a directory yet.\n# fallback_caches = [ <default list is compiled-in > ]\n\n# List of directory authorities which we expect to sign consensus documents.\n# authorities = [ <default list is compiled-in > ]\n\n# Channels and their behaviour\n[channel]\n\n# Should we use reduced channel padding? (This roughly halves the padding\n# cell frequency, and makes the padding unidirectional, increasing the\n# traceability of the client connections.)\n# Or disable it entirely?\n#\n#padding = \"normal\"\n# padding = \"reduced\"\n# padding = \"none\"\n\n# Full manual control of the precise padding timing parameters is available\n# by setting `override_net_params.nf_ito_low` et al.\n# (See torpsec/padding-spec.txt section 3.4.)\n\n# Rules for how long circuits should survive, and how long pending\n# requests should wait for a circuit.\n[circuit_timing]\n\n# Once a circuit has been used for a request, we stop giving it out for\n# other requests after this time.\n#max_dirtiness = \"10 minutes\"\n\n# When a circuit is requested, we keep trying to build circuits for up\n# to this long before the request gives up.\n#request_timeout = \"60 sec\"\n\n# When a circuit is requested, we make up to this many attempts to build\n# circuits for it before the request gives up.\n#request_max_retries = 16\n\n# If a circuit is finished that would satisfy a pending request, but the\n# request is still waiting for its own circuits to complete, the request\n# will wait this long before using the unexpectedly available circuit.\n#request_loyalty = \"50 msec\"\n\n# When we\'re trying to connect to a hidden service (.onion service),\n# how many attempts will we make to (i) download the descriptor from the directories\n# (ii) conduct the introduction and rendezvous exchange, before giving up.\n#hs_desc_fetch_attempts = 6\n#hs_intro_rend_attempts = 6\n\n# Rules for which addresses a client is willing to try to connect to over\n# the tor network.\n[address_filter]\n\n# Should we allow attempts to make Tor connections to local addresses?\n#allow_local_addrs = false\n\n# Should Arti make connections to hidden services (.onion services) ?\n#allow_onion_addrs = true\n\n# Rules for how long streams should wait when connecting to host or performing a\n# DNS lookup.\n#\n# These timeouts measure the permitted time between sending a request on an\n# established circuit, and getting a response from the exit node.\n[stream_timeouts]\n\n# How long should we wait before timing out a stream when connecting to a host?\n#connect_timeout = \"10 sec\"\n\n# How long should we wait before timing out when resolving a DNS record?\n#resolve_timeout = \"10 sec\"\n\n# How long should we wait before timing out when resolving a DNS PTR record?\n#resolve_ptr_timeout = \"10 sec\"\n\n# Configuration for the system resources used by Arti.\n[system]\n\n# What is the maximum number of file descriptors which should be available\n# to Arti when we launch?\n#max_files = 16384\n\n# Are we limiting memory use and if so to how much?\n# The default is unlimited.\n#\n# Maximum memory use, after which reclamation starts:\n# memory.max = \"8 GiB\"\n# (If anything is specified in `[system.memory]`, this value is mandatory.)\n#\n# When reclaiming memory, we stop when we reach this amount:\n# memory.low_water = \"6 GiB\"\n# (The default is 3/4 of `system.memory.max`.)\n\n##### ONION SERVICES\n#\n# NOTE: Some of the security features needed for onion service privacy\n# are not yet implemented. See\n# <https://gitlab.torproject.org/tpo/core/arti/-/blob/main/doc/OnionService.md>\n# for more information.\n#\n# Configuration for an onion service. You can include multiple\n# `[onion_services]` sections in order to configure multiple onion services.\n#\n# The second part of this section\'s name (\"allum-cepa\") is a local nickname\n# for this onion service.\n#\n# This nickname is saved on disk, and used to tell onion services apart;\n# it is not visible outside your own Arti instance.\n#\n# [onion_services.\"allium-cepa\"]\n\n# A description of what to do with incoming connections to different ports.\n# This is given as a list of rules; the first matching rule applies.\n#\n# proxy_ports = [\n# # Forward port 80 on the service to localhost:10080.\n# [\"80\", \"127.0.0.1:10080\"],\n# # Tear down the circuit on attempts to connect to port 22.\n# [\"22\", \"destroy\"],\n# # Ignore attempts to connect to port 265.\n# # (\"ignore\" is not generally a good idea for an anonymous service;\n# # \"destroy\" is safer.)\n# [\"265\", \"ignore\"],\n# # Reject attempts to connect to port 443.\n# [\"443\", \"reject\"],\n# # Any other connection attempts will make us destroy the circuit.\n# # (This is the default; you do not need to include this line.)\n# [\"*\", \"destroy\"]\n# ]\n\n# Number of introduction points to establish and advertise.\n#\n# num_intro_points = 3\n\n# How many streams will we allow at a time for each circuit?\n#\n# max_concurrent_streams_per_circuit = 65535\n\n# Whether to enable proof-of-work based DOS mitigation when under high load.\n#\n# enable_pow = false\n\n# [onion_services.\"allium-cepa\".restricted_discovery]\n# Whether to enable restricted discovery mode.\n#\n# Services running in restricted discovery mode are only discoverable\n# by the configured clients.\n#\n# Can only be enabled if the `restricted-discovery` feature is enabled.\n#\n# If you enable this, you must also specify the authorized clients (via `static_keys`),\n# or the directories where the authorized client keys should be read from (via `key_dirs`).\n#\n# Restricted discovery mode is disabled by default.\n#\n# enabled = true\n\n# [[onion_services.\"allium-cepa\".restricted_discovery.key_dirs]]\n# Directories containing the client keys, each in the\n# `descriptor:x25519:<base32-encoded-x25519-public-key>` format.\n#\n# Each file in this directory must have a file name of the form `<nickname>.auth`,\n# where `<nickname>` is a valid client nickname.\n#\n# path = \"/var/lib/tor/hidden_service/authorized_clients\"\n\n# A static mapping from client nicknames to keys.\n#\n# Each client key must be in the `descriptor:x25519:<base32-encoded-x25519-public-key>`\n# format.\n#\n# [onion_services.\"allium-cepa\".restricted_discovery.static_keys]\n# alice = \"descriptor:x25519:PU63REQUH4PP464E2Y7AVQ35HBB5DXDH5XEUVUNP3KCPNOXZGIBA\"\n# bob = \"descriptor:x25519:B5ZQGTPERMMUDA6VC63LHJUF5IHPOKJMUK26LY2XKSF7VG52AESQ\"\n\n[vanguards]\n# The kind of vanguard to use when building onion service circuits.\n#\n# If the `vanguards` feature is enabled and this option can be set to\n# * \"auto\", to use the default setting (lite vanguards)\n# * \"full\", to enable full vanguards\n# * \"lite\", to enable lite vanguards\n# * \"disabled\", to disable vanguards\n#\n# If the `vanguards` feature is not enabled, \"auto\" has the same effect as\n# \"disabled\".\n#\n# Setting this option to anything other than \"auto\" or \"disabled\" when\n# the `vanguards` feature is disabled is a configuration error.\n#mode = \"auto\"\n";Expand description
Example file demonstrating our configuration and the default options.
The options in this example file are all commented out; the actual defaults are done via builder attributes in all the Rust config structs.