Code to interpret the user's configuration of Tor. More...

#include "or.h"
#include "bridges.h"
#include "compat.h"
#include "addressmap.h"
#include "channel.h"
#include "circuitbuild.h"
#include "circuitlist.h"
#include "circuitmux.h"
#include "circuitmux_ewma.h"
#include "circuitstats.h"
#include "compress.h"
#include "config.h"
#include "connection.h"
#include "connection_edge.h"
#include "connection_or.h"
#include "consdiffmgr.h"
#include "control.h"
#include "confparse.h"
#include "cpuworker.h"
#include "crypto_rand.h"
#include "crypto_util.h"
#include "dirserv.h"
#include "dns.h"
#include "dos.h"
#include "entrynodes.h"
#include "git_revision.h"
#include "geoip.h"
#include "hibernate.h"
#include "main.h"
#include "networkstatus.h"
#include "nodelist.h"
#include "policies.h"
#include "relay.h"
#include "rendclient.h"
#include "rendservice.h"
#include "hs_config.h"
#include "rephist.h"
#include "router.h"
#include "sandbox.h"
#include "util.h"
#include "routerlist.h"
#include "routerset.h"
#include "scheduler.h"
#include "statefile.h"
#include "transports.h"
#include "ext_orport.h"
#include "voting_schedule.h"
#include "procmon.h"
#include "dirauth/dirvote.h"
#include "dirauth/mode.h"
#include "auth_dirs.inc"
#include "fallback_dirs.inc"

Macros
#define	CONFIG_PRIVATE

#define	DOWNLOAD_SCHEDULE(name) { #name "DownloadSchedule", #name "DownloadInitialDelay", 0, 1 }

#define	VAR(name, conftype, member, initvalue)

#define	V(member, conftype, initvalue) VAR(#member, conftype, member, initvalue)

#define	OBSOLETE(name) { name, CONFIG_TYPE_OBSOLETE, 0, NULL }

#define	VPORT(member)

#define	OR_OPTIONS_MAGIC 9090909

#define	YES_IF_CHANGED_BOOL(opt) if (!CFG_EQ_BOOL(old_options, new_options, opt)) return 1;

#define	YES_IF_CHANGED_INT(opt) if (!CFG_EQ_INT(old_options, new_options, opt)) return 1;

#define	YES_IF_CHANGED_STRING(opt) if (!CFG_EQ_STRING(old_options, new_options, opt)) return 1;

#define	YES_IF_CHANGED_LINELIST(opt) if (!CFG_EQ_LINELIST(old_options, new_options, opt)) return 1;

#define	YES_IF_CHANGED_SMARTLIST(opt) if (!CFG_EQ_SMARTLIST(old_options, new_options, opt)) return 1;

#define	YES_IF_CHANGED_ROUTERSET(opt) if (!CFG_EQ_ROUTERSET(old_options, new_options, opt)) return 1;

#define	RELAY_BRIDGE_STATS_DELAY (6 * 60 * 60)

#define	MIN_REND_POST_PERIOD (10*60)

#define	MIN_REND_POST_PERIOD_TESTING (5)

#define	MAX_CIRCS_AVAILABLE_TIME (246060)

#define	MAX_DIR_PERIOD ((72460*60)/2)

#define	MIN_MAX_CIRCUIT_DIRTINESS 10

#define	MAX_MAX_CIRCUIT_DIRTINESS (302460*60)

#define	MIN_CIRCUIT_STREAM_TIMEOUT 10

#define	RECOMMENDED_MIN_CIRCUIT_BUILD_TIMEOUT (10)

#define	REJECT(arg) STMT_BEGIN *msg = tor_strdup(arg); return -1; STMT_END

#define	COMPLAIN(args, ...) STMT_BEGIN log_warn(LD_CONFIG, args, ##__VA_ARGS__); STMT_END

#define	CHECK_DEFAULT(arg)

#define	ONE_GIGABYTE (U64_LITERAL(1) << 30)

#define	ONE_MEGABYTE (U64_LITERAL(1) << 20)

#define	RAM_IS_VERY_LARGE(x) (0)

#define	DIRCACHE_MIN_MEM_MB 300

#define	DIRCACHE_MIN_MEM_BYTES (DIRCACHE_MIN_MEM_MB*ONE_MEGABYTE)

#define	STRINGIFY(val) #val

#define	BAD_CHANGE_TO(opt, how)

#define	NO_CHANGE_BOOL(opt) if (! CFG_EQ_BOOL(old, new_val, opt)) BAD_CHANGE_TO(opt,"")

#define	NO_CHANGE_INT(opt) if (! CFG_EQ_INT(old, new_val, opt)) BAD_CHANGE_TO(opt,"")

#define	NO_CHANGE_STRING(opt) if (! CFG_EQ_STRING(old, new_val, opt)) BAD_CHANGE_TO(opt,"")

#define	SB_NOCHANGE_STR(opt)

#define	SB_NOCHANGE_LINELIST(opt)

#define	SB_NOCHANGE_INT(opt)

#define	GENERATED_FILE_PREFIX

#define	GENERATED_FILE_COMMENT

Enumerations
enum	takes_argument_t { TAKES_NO_ARGUMENT = 0, ARGUMENT_NECESSARY = 1, ARGUMENT_OPTIONAL = 2 }

Functions
	DUMMY_TYPECHECK_INSTANCE (or_options_t)

	MOCK_IMPL (const char *, get_dirportfrontpage,(void))

	MOCK_IMPL (or_options_t *, get_options_mutable,(void))

	MOCK_IMPL (const or_options_t *, get_options,(void))

int	set_options (or_options_t new_val, char *msg)

const char *	get_version (void)

const char *	get_short_version (void)

STATIC void	or_options_free_ (or_options_t *options)

void	config_free_all (void)

const char *	safe_str_client (const char *address)

const char *	safe_str (const char *address)

const char *	escaped_safe_str_client (const char *address)

const char *	escaped_safe_str (const char *address)

int	get_protocol_warning_severity_level (void)

void	init_protocol_warning_severity_level (void)

STATIC void	add_default_trusted_dir_authorities (dirinfo_type_t type)

	MOCK_IMPL (void, add_default_fallback_dir_servers,(void))

int	consider_adding_dir_servers (const or_options_t options, const or_options_t old_options)

int	create_keys_directory (const or_options_t *options)

int	options_need_geoip_info (const or_options_t options, const char *reason_out)

uint32_t	get_effective_bwrate (const or_options_t *options)

uint32_t	get_effective_bwburst (const or_options_t *options)

STATIC int	options_act (const or_options_t *old_options)

int	config_parse_commandline (int argc, char argv, int ignore_errors, config_line_t result, config_line_t **cmdline_result)

int	option_is_recognized (const char *key)

const char *	option_get_canonical_name (const char *key)

config_line_t *	option_get_assignment (const or_options_t options, const char key)

setopt_err_t	options_trial_assign (config_line_t list, unsigned flags, char *msg)

uint32_t	get_last_resolved_addr (void)

void	reset_last_resolved_addr (void)

int	using_default_dir_authorities (const or_options_t *options)

int	resolve_my_address (int warn_severity, const or_options_t options, uint32_t addr_out, const char method_out, char hostname_out)

	MOCK_IMPL (int, is_local_addr,(const tor_addr_t *addr))

or_options_t *	options_new (void)

void	options_init (or_options_t *options)

char *	options_dump (const or_options_t *options, int how_to_dump)

STATIC int	options_validate_single_onion (or_options_t options, char *msg)

STATIC int	options_validate (or_options_t old_options, or_options_t options, or_options_t default_options, int from_setconf, char *msg)

STATIC uint64_t	compute_real_max_mem_in_queues (const uint64_t val, int log_guess)

STATIC int	have_enough_mem_for_dircache (const or_options_t options, size_t total_mem, char *msg)

int	options_init_from_torrc (int argc, char **argv)

setopt_err_t	options_init_from_string (const char cf_defaults, const char cf, int command, const char command_arg, char *msg)

const char *	get_torrc_fname (int defaults_fname)

void	config_register_addressmaps (const or_options_t *options)

int	addressmap_register_auto (const char from, const char to, time_t expires, addressmap_entry_source_t addrmap_source, const char **msg)

void	bridge_line_free_ (bridge_line_t *bridge_line)

bridge_line_t *	parse_bridge_line (const char *line)

STATIC int	parse_transport_line (const or_options_t options, const char line, int validate_only, int server)

smartlist_t *	get_options_from_transport_options_line (const char line, const char transport)

char *	get_transport_bindaddr_from_config (const char *transport)

smartlist_t *	get_options_for_server_transport (const char *transport)

STATIC int	parse_dir_authority_line (const char *line, dirinfo_type_t required_type, int validate_only)

int	parse_dir_fallback_line (const char *line, int validate_only)

STATIC port_cfg_t *	port_cfg_new (size_t namelen)

STATIC void	port_cfg_free_ (port_cfg_t *port)

int	port_cfg_line_extract_addrport (const char line, char addrport_out, int is_unix_out, const char **rest_out)

STATIC int	check_bridge_distribution_setting (const char *bd)

STATIC int	parse_port_config (smartlist_t out, const config_line_t ports, const char portname, int listener_type, const char defaultaddr, int defaultport, const unsigned flags)

	MOCK_IMPL (const smartlist_t *, get_configured_ports,(void))

char *	get_first_listener_addrport_string (int listener_type)

int	get_first_advertised_port_by_type_af (int listener_type, int address_family)

const tor_addr_t *	get_first_advertised_addr_by_type_af (int listener_type, int address_family)

int	port_exists_by_type_addr_port (int listener_type, const tor_addr_t *addr, int port, int check_wildcard)

int	port_exists_by_type_addr32h_port (int listener_type, uint32_t addr_ipv4h, int port, int check_wildcard)

int	options_save_current (void)

int	get_num_cpus (const or_options_t *options)

	MOCK_IMPL (char , options_get_dir_fname2_suffix,(const or_options_t options, directory_root_t roottype, const char sub1, const char sub2, const char *suffix))

int	check_or_create_data_subdir (const char *subdir)

int	write_to_data_subdir (const char subdir, const char fname, const char str, const char descr)

smartlist_t *	get_list_of_ports_to_forward (void)

int	getinfo_helper_config (control_connection_t conn, const char question, char answer, const char errmsg)

int	init_cookie_authentication (const char fname, const char header, int cookie_len, int group_readable, uint8_t *cookie_out, int cookie_is_set_out)

int	options_any_client_port_set (const or_options_t *options)

Variables
STATIC config_format_t	options_format

Detailed Description

Code to interpret the user's configuration of Tor.

This module handles torrc configuration file, including parsing it, combining it with torrc.defaults and the command line, allowing user changes to it (via editing and SIGHUP or via the control port), writing it back to disk (because of SAVECONF from the control port), and – most importantly, acting on it.

The module additionally has some tools for manipulating and inspecting values that are calculated as a result of the configured options.

How to add new options

To add new items to the torrc, there are a minimum of three places to edit:

The or_options_t structure in or.h, where the options are stored.
The option_vars_ array below in this module, which configures the names of the torrc options, their types, their multiplicities, and their mappings to fields in or_options_t.
The manual in doc/tor.1.txt, to document what the new option is, and how it works.

Additionally, you might need to edit these places too:

options_validate() below, in case you want to reject some possible values of the new configuration option.
options_transition_allowed() below, in case you need to forbid some or all changes in the option while Tor is running.
options_transition_affects_workers(), in case changes in the option might require Tor to relaunch or reconfigure its worker threads.
options_transition_affects_descriptor(), in case changes in the option might require a Tor relay to build and publish a new server descriptor.
options_act() and/or options_act_reversible(), in case there's some action that needs to be taken immediately based on the option's value.

Changing the value of an option

Because of the SAVECONF command from the control port, it's a bad idea to change the value of any user-configured option in the or_options_t. If you want to sometimes do this anyway, we recommend that you create a secondary field in or_options_t; that you have the user option linked only to the secondary field; that you use the secondary field to initialize the one that Tor actually looks at; and that you use the one Tor looks as the one that you modify.

Macro Definition Documentation

◆ BAD_CHANGE_TO

#define BAD_CHANGE_TO	(	opt,
		how
	)

Value:

do {                                    \
    *msg = tor_strdup("While Tor is running"how", changing " #opt       \
                      " is not allowed");                               \
    return -1;                                                          \
  } while (0)

◆ CHECK_DEFAULT

#define CHECK_DEFAULT ( arg )

Value:

STMT_BEGIN                                                            \
    if (!options->TestingTorNetwork &&                                  \
        !options->UsingTestNetworkDefaults_ &&                          \
        !config_is_same(&options_format,options,                        \
                        default_options,#arg)) {                        \
      REJECT(#arg " may only be changed in testing Tor "                \
             "networks!");                                              \
    } STMT_END

◆ DOWNLOAD_SCHEDULE

#define DOWNLOAD_SCHEDULE ( name ) { #name "DownloadSchedule", #name "DownloadInitialDelay", 0, 1 }

macro to help with the bulk rename of *DownloadSchedule to *DowloadInitialDelay .

◆ GENERATED_FILE_COMMENT

#define GENERATED_FILE_COMMENT

Value:

"# The old torrc file was renamed " \

"to torrc.orig.1 or similar, and Tor will ignore it"

This string can change; it tries to give the reader an idea that editing this file by hand is not a good plan.

◆ GENERATED_FILE_PREFIX

#define GENERATED_FILE_PREFIX

Value:

"# This file was generated by Tor; " \

"if you edit it, comments will not be preserved"

This string must remain the same forevermore. It is how we recognize that the torrc file doesn't need to be backed up.

◆ MAX_CIRCS_AVAILABLE_TIME

#define MAX_CIRCS_AVAILABLE_TIME (24*60*60)

Highest allowable value for CircuitsAvailableTimeout. If this is too large, client connections will stay open for too long, incurring extra padding overhead.

◆ MAX_DIR_PERIOD

#define MAX_DIR_PERIOD ((7*24*60*60)/2)

Highest allowable value for RendPostPeriod.

◆ MAX_MAX_CIRCUIT_DIRTINESS

#define MAX_MAX_CIRCUIT_DIRTINESS (30*24*60*60)

Highest allowable value for MaxCircuitDirtiness: prevents time_t overflows.

◆ MIN_CIRCUIT_STREAM_TIMEOUT

#define MIN_CIRCUIT_STREAM_TIMEOUT 10

Lowest allowable value for CircuitStreamTimeout; if this is too low, Tor will generate too many circuits and potentially overload the network.

◆ MIN_MAX_CIRCUIT_DIRTINESS

#define MIN_MAX_CIRCUIT_DIRTINESS 10

Lowest allowable value for MaxCircuitDirtiness; if this is too low, Tor will generate too many circuits and potentially overload the network.

◆ MIN_REND_POST_PERIOD

#define MIN_REND_POST_PERIOD (10*60)

Lowest allowable value for RendPostPeriod; if this is too low, hidden services can overload the directory system.

◆ OBSOLETE

#define OBSOLETE ( name ) { name, CONFIG_TYPE_OBSOLETE, 0, NULL }

An entry for config_vars: "The option <b>name</b> is obsolete."

◆ OR_OPTIONS_MAGIC

#define OR_OPTIONS_MAGIC 9090909

Magic value for or_options_t.

◆ RECOMMENDED_MIN_CIRCUIT_BUILD_TIMEOUT

#define RECOMMENDED_MIN_CIRCUIT_BUILD_TIMEOUT (10)

Lowest recommended value for CircuitBuildTimeout; if it is set too low and LearnCircuitBuildTimeout is off, the failure rate for circuit construction may be very high. In that case, if it is set below this threshold emit a warning.

◆ SB_NOCHANGE_INT

#define SB_NOCHANGE_INT ( opt )

Value:

if (! CFG_EQ_INT(old, new_val, opt)) \

BAD_CHANGE_TO(opt," with Sandbox active")

◆ SB_NOCHANGE_LINELIST

#define SB_NOCHANGE_LINELIST ( opt )

Value:

if (! CFG_EQ_LINELIST(old, new_val, opt)) \

BAD_CHANGE_TO(opt," with Sandbox active")

◆ SB_NOCHANGE_STR

#define SB_NOCHANGE_STR ( opt )

Value:

if (! CFG_EQ_STRING(old, new_val, opt)) \

BAD_CHANGE_TO(opt," with Sandbox active")

◆ V

#define V	(	member,
		conftype,
		initvalue
	)	VAR(#member, conftype, member, initvalue)

As VAR, but the option name and member name are the same.

◆ VAR

#define VAR	(	name,
		conftype,
		member,
		initvalue
	)

Value:

{ name, CONFIG_TYPE_ ## conftype, offsetof(or_options_t, member), \

initvalue CONF_TEST_MEMBERS(or_options_t, conftype, member) }

or_options_t

Definition: or.h:3657

An entry for config_vars: "The option name has type CONFIG_TYPE_conftype, and corresponds to or_options_t.member"

◆ VPORT

#define VPORT ( member )

Value:

VAR(#member "Lines", LINELIST_V, member ## _lines, NULL),     \
  VAR(#member, LINELIST_S, member ## _lines, NULL),             \
  VAR("__" #member, LINELIST_S, member ## _lines, NULL)

Macro to declare *Port options. Each one comes in three entries. For example, most users should use "SocksPort" to configure the socks port, but TorBrowser wants to use __SocksPort so that it isn't stored by SAVECONF. The SocksPortLines virtual option is used to query both options from the controller.

Function Documentation

◆ add_default_trusted_dir_authorities()

STATIC void add_default_trusted_dir_authorities ( dirinfo_type_t type )

Add the default directory authorities directly into the trusted dir list, but only add them insofar as they share bits with type. Each authority's bits are restricted to the bits shared with type. If type is ALL_DIRINFO or NO_DIRINFO (zero), add all authorities.

◆ addressmap_register_auto()

int addressmap_register_auto	(	const char *	from,
		const char *	to,
		time_t	expires,
		addressmap_entry_source_t	addrmap_source,
		const char **	msg
	)

As addressmap_register(), but detect the wildcarded status of "from" and "to", and do not steal a reference to to.

Here is the call graph for this function:

◆ bridge_line_free_()

void bridge_line_free_ ( bridge_line_t * bridge_line )

Deallocate a bridge_line_t structure.

◆ check_bridge_distribution_setting()

STATIC int check_bridge_distribution_setting ( const char * bd )

Validate the configured bridge distribution method from a BridgeDistribution config line.

The input bd, is a string taken from the BridgeDistribution config line (if present). If the option wasn't set, return 0 immediately. The BridgeDistribution option is then validated. Currently valid, recognised options are:

"none"
"any"
"https"
"email"
"moat"
"hyphae"

If the option string is unrecognised, a warning will be logged and 0 is returned. If the option string contains an invalid character, -1 is returned.

◆ check_or_create_data_subdir()

int check_or_create_data_subdir ( const char * subdir )

Check wether the data directory has a private subdirectory subdir. If not, try to create it. Return 0 on success, -1 otherwise.

◆ config_free_all()

void config_free_all ( void )

Release all memory and resources held by global configuration structures.

◆ config_parse_commandline()

int config_parse_commandline	(	int	argc,
		char **	argv,
		int	ignore_errors,
		config_line_t **	result,
		config_line_t **	cmdline_result
	)

Helper: Read a list of configuration options from the command line. If successful, or if ignore_errors is set, put them in *result, put the commandline-only options in *cmdline_result, and return 0; otherwise, return -1 and leave *result and cmdline_result alone.

◆ config_register_addressmaps()

void config_register_addressmaps ( const or_options_t * options )

Adjust the address map based on the MapAddress elements in the configuration options

Here is the call graph for this function:

◆ consider_adding_dir_servers()

int consider_adding_dir_servers	(	const or_options_t *	options,
		const or_options_t *	old_options
	)

Look at all the config options and assign new dir authorities as appropriate.

Here is the call graph for this function:

◆ create_keys_directory()

int create_keys_directory ( const or_options_t * options )

Ensure that our keys directory exists, with appropriate permissions. Return 0 on success, -1 on failure.

◆ DUMMY_TYPECHECK_INSTANCE()

DUMMY_TYPECHECK_INSTANCE ( or_options_t )

dummy instance of or_options_t, used for type-checking its members with CONF_CHECK_VAR_TYPE.

◆ escaped_safe_str()

const char* escaped_safe_str ( const char * address )

Equivalent to escaped(safe_str(address)). See reentrancy note on escaped(): don't use this outside the main thread, or twice in the same log statement.

Here is the call graph for this function:

◆ escaped_safe_str_client()

const char* escaped_safe_str_client ( const char * address )

Equivalent to escaped(safe_str_client(address)). See reentrancy note on escaped(): don't use this outside the main thread, or twice in the same log statement.

Here is the call graph for this function:

◆ get_effective_bwburst()

uint32_t get_effective_bwburst ( const or_options_t * options )

Return the bandwidthburst that we are going to report to the authorities based on the config options.

◆ get_effective_bwrate()

uint32_t get_effective_bwrate ( const or_options_t * options )

Return the bandwidthrate that we are going to report to the authorities based on the config options.

◆ get_first_advertised_addr_by_type_af()

const tor_addr_t* get_first_advertised_addr_by_type_af	(	int	listener_type,
		int	address_family
	)

Return the first advertised address of type listener_type in address_family. Returns NULL if there is no advertised address, and when passed AF_UNSPEC.

◆ get_first_advertised_port_by_type_af()

int get_first_advertised_port_by_type_af	(	int	listener_type,
		int	address_family
	)

Return the first advertised port of type listener_type in address_family. Returns 0 when no port is found, and when passed AF_UNSPEC.

Here is the caller graph for this function:

◆ get_first_listener_addrport_string()

char* get_first_listener_addrport_string ( int listener_type )

Return an address:port string representation of the address where the first listener_type listener waits for connections. Return NULL if we couldn't find a listener. The string is allocated on the heap and it's the responsibility of the caller to free it after use.

This function is meant to be used by the pluggable transport proxy spawning code, please make sure that it fits your purposes before using it.

◆ get_last_resolved_addr()

uint32_t get_last_resolved_addr ( void )

Accessor for last_resolved_addr from outside this file.

Here is the caller graph for this function:

◆ get_list_of_ports_to_forward()

smartlist_t* get_list_of_ports_to_forward ( void )

Return a smartlist of ports that must be forwarded by tor-fw-helper. The smartlist contains the ports in a string format that is understandable by tor-fw-helper.

XXX TODO tor-fw-helper does not support forwarding ports to other hosts than the local one. If the user is binding to a different IP address, tor-fw-helper won't work.

Here is the call graph for this function:

◆ get_num_cpus()

int get_num_cpus ( const or_options_t * options )

Return the number of cpus configured in options. If we are told to auto-detect the number of cpus, return the auto-detected number.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_options_for_server_transport()

smartlist_t* get_options_for_server_transport ( const char * transport )

Given the name of a pluggable transport in transport, check the configuration file to see if the user has asked us to pass any parameters to the pluggable transport. Return a smartlist containing the parameters, otherwise NULL.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_options_from_transport_options_line()

smartlist_t* get_options_from_transport_options_line	(	const char *	line,
		const char *	transport
	)

Given a ServerTransportOptions line, return a smartlist with the options. Return NULL if the line was not well-formed.

If transport is set, return NULL if the line is not referring to transport.

The returned smartlist and its strings are allocated on the heap and it's the responsibility of the caller to free it.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_protocol_warning_severity_level()

int get_protocol_warning_severity_level ( void )

Return the severity level that should be used for warnings of severity LOG_PROTOCOL_WARN.

Here is the call graph for this function:

◆ get_short_version()

const char* get_short_version ( void )

Return the current Tor version, without any git tag.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_torrc_fname()

const char* get_torrc_fname ( int defaults_fname )

Return the location for our configuration file. May return NULL.

◆ get_transport_bindaddr_from_config()

char* get_transport_bindaddr_from_config ( const char * transport )

Given the name of a pluggable transport in transport, check the configuration file to see if the user has explicitly asked for it to listen on a specific port. Return a <address:port> string if so, otherwise NULL.

Here is the caller graph for this function:

◆ get_version()

const char* get_version ( void )

Return the current Tor version.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getinfo_helper_config()

int getinfo_helper_config	(	control_connection_t *	conn,
		const char *	question,
		char **	answer,
		const char **	errmsg
	)

Helper to implement GETINFO functions about configuration variables (not their values). Given a "config/names" question, set *answer to a new string describing the supported configuration variables and their types.

◆ have_enough_mem_for_dircache()

STATIC int have_enough_mem_for_dircache	(	const or_options_t *	options,
		size_t	total_mem,
		char **	msg
	)

Create a warning message for emitting if we are a dircache but may not have enough system memory, or if we are not a dircache but probably should be. Return -1 when a message is returned in msg, else return 0.

◆ init_cookie_authentication()

int init_cookie_authentication	(	const char *	fname,
		const char *	header,
		int	cookie_len,
		int	group_readable,
		uint8_t **	cookie_out,
		int *	cookie_is_set_out
	)

Initialize cookie authentication (used so far by the ControlPort and Extended ORPort).

Allocate memory and create a cookie (of length cookie_len) in cookie_out. Then write it down to fname and prepend it with header.

If group_readable is set, set fname to be readable by the default GID.

If the whole procedure was successful, set cookie_is_set_out to True.

◆ init_protocol_warning_severity_level()

void init_protocol_warning_severity_level ( void )

Initialize the log warning severity level for protocol warnings. Call only once at startup.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ MOCK_IMPL() [1/7]

MOCK_IMPL	(	const char *	,
		get_dirportfrontpage	,
		(void)
	)

Return the contents of our frontpage string, or NULL if not configured.

◆ MOCK_IMPL() [2/7]

MOCK_IMPL	(	or_options_t *	,
		get_options_mutable	,
		(void)
	)

Returns the currently configured options.

◆ MOCK_IMPL() [3/7]

MOCK_IMPL	(	const or_options_t *	,
		get_options	,
		(void)
	)

Returns the currently configured options

◆ MOCK_IMPL() [4/7]

MOCK_IMPL	(	void	,
		add_default_fallback_dir_servers	,
		(void)
	)

Add the default fallback directory servers into the fallback directory server list.

Here is the call graph for this function:

◆ MOCK_IMPL() [5/7]

MOCK_IMPL	(	int	,
		is_local_addr	,
		(const tor_addr_t *addr)
	)

Return true iff addr is judged to be on the same network as us, or on a private network.

◆ MOCK_IMPL() [6/7]

MOCK_IMPL	(	const smartlist_t *	,
		get_configured_ports	,
		(void)
	)

Return a list of port_cfg_t for client ports parsed from the options.

◆ MOCK_IMPL() [7/7]

MOCK_IMPL	(	char *	,
		options_get_dir_fname2_suffix	,
		(const or_options_t options, directory_root_t roottype, const char sub1, const char sub2, const char suffix)
	)

Return a newly allocated string holding a filename relative to the directory in options specified by roottype. If sub1 is present, it is the first path component after the data directory. If sub2 is also present, it is the second path component after the data directory. If suffix is present, it is appended to the filename.

Note: Consider using macros in config.h that wrap this function; you should probably never need to call it as-is.

◆ option_get_assignment()

config_line_t* option_get_assignment	(	const or_options_t *	options,
		const char *	key
	)

Return a canonical list of the options assigned for key.

Here is the call graph for this function:

◆ option_get_canonical_name()

const char* option_get_canonical_name ( const char * key )

Return the canonical name of a configuration option, or NULL if no such option exists.

Here is the call graph for this function:

◆ option_is_recognized()

int option_is_recognized ( const char * key )

Return true iff key is a valid configuration option.

Here is the call graph for this function:

◆ options_act()

STATIC int options_act ( const or_options_t * old_options )

Fetch the active option list, and take actions based on it. All of the things we do should survive being done repeatedly. If present, old_options contains the previous value of the options.

Return 0 if all goes well, return -1 if it's time to die.

Note: We haven't moved all the "act on new configuration" logic here yet. Some is still in do_hup() and other places.

◆ options_any_client_port_set()

int options_any_client_port_set ( const or_options_t * options )

Return true if any option is set in options to make us behave as a client.

Here is the caller graph for this function:

◆ options_dump()

char* options_dump	(	const or_options_t *	options,
		int	how_to_dump
	)

Return a string containing a possible configuration file that would give the configuration in options. If minimal is true, do not include options that are the same as Tor's defaults.

◆ options_init()

void options_init ( or_options_t * options )

Set options to hold reasonable defaults for most options. Each option defaults to zero.

Here is the call graph for this function:

◆ options_init_from_string()

setopt_err_t options_init_from_string	(	const char *	cf_defaults,
		const char *	cf,
		int	command,
		const char *	command_arg,
		char **	msg
	)

Load the options from the configuration in cf, validate them for consistency and take actions based on them.

Return 0 if success, negative on error:

-1 for general errors.
-2 for failure to parse/validate,
-3 for transition not allowed
-4 for error while setting the new options

◆ options_init_from_torrc()

int options_init_from_torrc	(	int	argc,
		char **	argv
	)

Read a configuration file into options, finding the configuration file location based on the command line. After loading the file call options_init_from_string() to load the config. Return 0 if success, -1 if failure, and 1 if we succeeded but should exit anyway.

◆ options_need_geoip_info()

int options_need_geoip_info	(	const or_options_t *	options,
		const char **	reason_out
	)

If we need to have a GEOIP ip-to-country map to run with our configured options, return 1 and set *reason_out to a description of why.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ options_new()

or_options_t* options_new ( void )

Return a new empty or_options_t. Used for testing.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ options_save_current()

int options_save_current ( void )

Save the current configuration file value to disk. Return 0 on success, -1 on failure.

◆ options_trial_assign()

setopt_err_t options_trial_assign	(	config_line_t *	list,
		unsigned	flags,
		char **	msg
	)

Try assigning list to the global options. You do this by duping options, assigning list to the new one, then validating it. If it's ok, then throw out the old one and stick with the new one. Else, revert to old and return failure. Return SETOPT_OK on success, or a setopt_err_t on failure.

If not success, point *msg to a newly allocated string describing what went wrong.

Here is the call graph for this function:

◆ options_validate()

STATIC int options_validate	(	or_options_t *	old_options,
		or_options_t *	options,
		or_options_t *	default_options,
		int	from_setconf,
		char **	msg
	)

Return 0 if every setting in options is reasonable, is a permissible transition from old_options, and none of the testing-only settings differ from default_options unless in testing mode. Else return -1. Should have no side effects, except for normalizing the contents of options.

On error, tor_strdup an error explanation into *msg.

XXX If from_setconf, we were called by the controller, and our Log line should stay empty. If it's 0, then give us a default log if there are no logs defined.

If get_bindaddr_from_transport_listen_line() fails with 'transport' being NULL, it means that something went wrong while parsing the ServerTransportListenAddr line.

If get_options_from_transport_options_line() fails with 'transport' being NULL, it means that something went wrong while parsing the ServerTransportOptions line.

◆ or_options_free_()

STATIC void or_options_free_ ( or_options_t * options )

Release additional memory allocated in options

◆ parse_bridge_line()

bridge_line_t* parse_bridge_line ( const char * line )

Parse the contents of a string, line, containing a Bridge line, into a bridge_line_t.

Validates that the IP:PORT, fingerprint, and SOCKS arguments (given to the Pluggable Transport, if a one was specified) are well-formed.

Returns NULL If the Bridge line could not be validated, and returns a bridge_line_t containing the parsed information otherwise.

Bridge line format: Bridge [transport] IP:PORT [id-fingerprint] [k=v] [k=v] ...

◆ parse_dir_authority_line()

STATIC int parse_dir_authority_line	(	const char *	line,
		dirinfo_type_t	required_type,
		int	validate_only
	)

Read the contents of a DirAuthority line from line. If validate_only is 0, and the line is well-formed, and it shares any bits with required_type or required_type is NO_DIRINFO (zero), then add the dirserver described in the line (minus whatever bits it's missing) as a valid authority. Return 0 on success or filtering out by type, or -1 if the line isn't well-formed or if we can't add it.

◆ parse_dir_fallback_line()

int parse_dir_fallback_line	(	const char *	line,
		int	validate_only
	)

Read the contents of a FallbackDir line from line. If validate_only is 0, and the line is well-formed, then add the dirserver described in the line as a fallback directory. Return 0 on success, or -1 if the line isn't well-formed or if we can't add it.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ parse_port_config()

STATIC int parse_port_config	(	smartlist_t *	out,
		const config_line_t *	ports,
		const char *	portname,
		int	listener_type,
		const char *	defaultaddr,
		int	defaultport,
		const unsigned	flags
	)

Parse port configuration for a single port type.

Read entries of the "FooPort" type from the list ports. Syntax is that FooPort can have any number of entries of the format "[Address:][Port] IsolationOptions".

In log messages, describe the port type as portname.

If no address is specified, default to defaultaddr. If no FooPort is given, default to defaultport (if 0, there is no default).

If CL_PORT_NO_STREAM_OPTIONS is set in flags, do not allow stream isolation options in the FooPort entries.

If CL_PORT_WARN_NONLOCAL is set in flags, warn if any of the ports are not on a local address. If CL_PORT_FORBID_NONLOCAL is set, this is a control port with no password set: don't even allow it.

If CL_PORT_SERVER_OPTIONS is set in flags, do not allow stream isolation options in the FooPort entries; instead allow the server-port option set.

If CL_PORT_TAKES_HOSTNAMES is set in flags, allow the options {No,}IPv{4,6}Traffic.

On success, if out is given, add a new port_cfg_t entry to out for every port that the client should listen on. Return 0 on success, -1 on failure.

Here is the call graph for this function:

◆ parse_transport_line()

STATIC int parse_transport_line	(	const or_options_t *	options,
		const char *	line,
		int	validate_only,
		int	server
	)

Read the contents of a ClientTransportPlugin or ServerTransportPlugin line from line, depending on the value of server. Return 0 if the line is well-formed, and -1 if it isn't.

If validate_only is 0, the line is well-formed, and the transport is needed by some bridge:

If it's an external proxy line, add the transport described in the line to our internal transport list.
If it's a managed proxy line, launch the managed proxy.

◆ port_cfg_free_()

STATIC void port_cfg_free_ ( port_cfg_t * port )

Free all storage held in port

◆ port_cfg_line_extract_addrport()

int port_cfg_line_extract_addrport	(	const char *	line,
		char **	addrport_out,
		int *	is_unix_out,
		const char **	rest_out
	)

Take a string (line) that begins with either an address:port, a port, or an AF_UNIX address, optionally quoted, prefixed with "unix:". Parse that line, and on success, set addrport_out to a new string containing the beginning portion (without prefix). Iff there was a unix: prefix, set is_unix_out to true. On success, also set rest_out to point to the part of the line after the address portion.

Return 0 on success, -1 on failure.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ port_cfg_new()

STATIC port_cfg_t* port_cfg_new ( size_t namelen )

Allocate and return a new port_cfg_t with reasonable defaults.

Here is the caller graph for this function:

◆ port_exists_by_type_addr_port()

int port_exists_by_type_addr_port	(	int	listener_type,
		const tor_addr_t *	addr,
		int	port,
		int	check_wildcard
	)

Return 1 if a port exists of type listener_type on addr and port. If check_wildcard is true, INADDR[6]_ANY and AF_UNSPEC addresses match any address of the appropriate family; and port -1 matches any port. To match auto ports, pass CFG_PORT_AUTO. (Does not match on the actual automatically chosen listener ports.)

◆ reset_last_resolved_addr()

void reset_last_resolved_addr ( void )

Reset last_resolved_addr from outside this file.

◆ resolve_my_address()

int resolve_my_address	(	int	warn_severity,
		const or_options_t *	options,
		uint32_t *	addr_out,
		const char **	method_out,
		char **	hostname_out
	)

Attempt getting our non-local (as judged by tor_addr_is_internal() function) IP address using following techniques, listed in order from best (most desirable, try first) to worst (least desirable, try if everything else fails).

First, attempt using options->Address to get our non-local IP address.

If options->Address represents a non-local IP address, consider it ours.

If options->Address is a DNS name that resolves to a non-local IP address, consider this IP address ours.

If options->Address is NULL, fall back to getting local hostname and using it in above-described ways to try and get our IP address.

In case local hostname cannot be resolved to a non-local IP address, try getting an IP address of network interface in hopes it will be non-local one.

Fail if one or more of the following is true:

DNS name in options->Address cannot be resolved.
options->Address is a local host address.
Attempt at getting local hostname fails.
Attempt at getting network interface address fails.

Return 0 if all is well, or -1 if we can't find a suitable public IP address.

If we are returning 0:

Put our public IP address (in host order) into *addr_out.
If method_out is non-NULL, set *method_out to a static string describing how we arrived at our answer.
- "CONFIGURED" - parsed from IP address string in options->Address
- "RESOLVED" - resolved from DNS name in options->Address
- "GETHOSTNAME" - resolved from a local hostname.
- "INTERFACE" - retrieved from a network interface.
If hostname_out is non-NULL, and we resolved a hostname to get our address, set *hostname_out to a newly allocated string holding that hostname. (If we didn't get our address by resolving a hostname, set *hostname_out to NULL.)

XXXX ipv6

Here is the caller graph for this function:

◆ safe_str()

const char* safe_str ( const char * address )

Make address – a piece of information of unspecified sensitivity – safe to log according to the settings in options->SafeLogging, and return it.

(We return "[scrubbed]" if SafeLogging is anything besides "0", and address otherwise.)

◆ safe_str_client()

const char* safe_str_client ( const char * address )

Make address – a piece of information related to our operation as a client – safe to log according to the settings in options->SafeLogging, and return it.

(We return "[scrubbed]" if SafeLogging is "1", and address otherwise.)

Here is the caller graph for this function:

◆ set_options()

int set_options	(	or_options_t *	new_val,
		char **	msg
	)

Change the current global options to contain new_val instead of their current value; take action based on the new value; free the old value as necessary. Returns 0 on success, -1 on failure.

◆ write_to_data_subdir()

int write_to_data_subdir	(	const char *	subdir,
		const char *	fname,
		const char *	str,
		const char *	descr
	)

Create a file named fname with contents str in the subdirectory subdir of the data directory. descr should be a short description of the file's content and will be used for the warning message, if it's present and the write process fails. Return 0 on success, -1 otherwise.

Variable Documentation

◆ options_format

STATIC config_format_t options_format

Initial value:

= {
  sizeof(or_options_t),
  OR_OPTIONS_MAGIC,
  offsetof(or_options_t, magic_),
  option_abbrevs_,
  option_deprecation_notes_,
  option_vars_,
  options_validate_cb,
  NULL
}

Configuration format for or_options_t.

Macros

Enumerations

Functions

Variables

Detailed Description

How to add new options

Changing the value of an option

Macro Definition Documentation

◆ BAD_CHANGE_TO

◆ CHECK_DEFAULT

◆ DOWNLOAD_SCHEDULE

◆ GENERATED_FILE_COMMENT

◆ GENERATED_FILE_PREFIX

◆ MAX_CIRCS_AVAILABLE_TIME

◆ MAX_DIR_PERIOD

◆ MAX_MAX_CIRCUIT_DIRTINESS

◆ MIN_CIRCUIT_STREAM_TIMEOUT

◆ MIN_MAX_CIRCUIT_DIRTINESS

◆ MIN_REND_POST_PERIOD

◆ OBSOLETE

◆ OR_OPTIONS_MAGIC

◆ RECOMMENDED_MIN_CIRCUIT_BUILD_TIMEOUT

◆ SB_NOCHANGE_INT

◆ SB_NOCHANGE_LINELIST

◆ SB_NOCHANGE_STR

◆ V

◆ VAR

◆ VPORT

Function Documentation

◆ add_default_trusted_dir_authorities()

◆ addressmap_register_auto()

◆ bridge_line_free_()

◆ check_bridge_distribution_setting()

◆ check_or_create_data_subdir()

◆ config_free_all()

◆ config_parse_commandline()

◆ config_register_addressmaps()

◆ consider_adding_dir_servers()

◆ create_keys_directory()

◆ DUMMY_TYPECHECK_INSTANCE()

◆ escaped_safe_str()

◆ escaped_safe_str_client()

◆ get_effective_bwburst()

◆ get_effective_bwrate()

◆ get_first_advertised_addr_by_type_af()

◆ get_first_advertised_port_by_type_af()

◆ get_first_listener_addrport_string()

◆ get_last_resolved_addr()

◆ get_list_of_ports_to_forward()

◆ get_num_cpus()

◆ get_options_for_server_transport()

◆ get_options_from_transport_options_line()

◆ get_protocol_warning_severity_level()

◆ get_short_version()

◆ get_torrc_fname()

◆ get_transport_bindaddr_from_config()

◆ get_version()

◆ getinfo_helper_config()

◆ have_enough_mem_for_dircache()

◆ init_cookie_authentication()

◆ init_protocol_warning_severity_level()

◆ MOCK_IMPL() [1/7]

◆ MOCK_IMPL() [2/7]

◆ MOCK_IMPL() [3/7]

◆ MOCK_IMPL() [4/7]

◆ MOCK_IMPL() [5/7]

◆ MOCK_IMPL() [6/7]

◆ MOCK_IMPL() [7/7]

◆ option_get_assignment()

◆ option_get_canonical_name()

◆ option_is_recognized()

◆ options_act()

◆ options_any_client_port_set()

◆ options_dump()

◆ options_init()

◆ options_init_from_string()

◆ options_init_from_torrc()

◆ options_need_geoip_info()

◆ options_new()

◆ options_save_current()