control.c File Reference

Implementation for Tor's control-socket interface. More...

#include "core/or/or.h"
#include "app/config/config.h"
#include "app/main/main.h"
#include "core/mainloop/connection.h"
#include "core/mainloop/mainloop.h"
#include "core/or/connection_or.h"
#include "core/proto/proto_control0.h"
#include "core/proto/proto_http.h"
#include "feature/control/control.h"
#include "feature/control/control_auth.h"
#include "feature/control/control_cmd.h"
#include "feature/control/control_events.h"
#include "feature/control/control_proto.h"
#include "feature/hs/hs_common.h"
#include "feature/hs/hs_service.h"
#include "lib/evloop/procmon.h"
#include "feature/control/control_connection_st.h"

Go to the source code of this file.

Macros
#define	CONTROL_MODULE_PRIVATE
#define	CONTROL_PRIVATE
#define	MAX_COMMAND_LINE_LENGTH   (1024*1024)

Functions
control_connection_t *	TO_CONTROL_CONN (connection_t *c)
const control_connection_t *	CONST_TO_CONTROL_CONN (const connection_t *c)
int	control_connection_add_local_fd (tor_socket_t sock, unsigned flags)
void	control_ports_write_to_file (void)
int	connection_control_finished_flushing (control_connection_t *conn)
int	connection_control_reached_eof (control_connection_t *conn)
static void	lost_owning_controller (const char *owner_type, const char *loss_manner)
void	connection_control_closed (control_connection_t *conn)
static int	is_valid_initial_command (control_connection_t *conn, const char *cmd)
static int	peek_connection_has_control0_command (connection_t *conn)
static int	peek_connection_has_http_command (connection_t *conn)
STATIC char *	control_split_incoming_command (char *incoming_cmd, size_t *data_len, char **current_cmd_out)
static void	control_send_v0_reject (control_connection_t *conn)
static void	control_send_http_reject (control_connection_t *conn)
static bool	control_protocol_is_valid (control_connection_t *conn)
int	connection_control_process_inbuf (control_connection_t *conn)
int	get_cached_network_liveness (void)
void	set_cached_network_liveness (int liveness)
static void	owning_controller_procmon_cb (void *unused)
void	monitor_owning_controller_process (const char *process_spec)
void	control_free_all (void)

Variables
const struct signal_name_t	signal_table []
static const char	CONTROLPORT_IS_NOT_AN_HTTP_PROXY_MSG []
static int	network_is_live = 0
static char *	owning_controller_process_spec = NULL
static tor_process_monitor_t *	owning_controller_process_monitor = NULL

Detailed Description

Implementation for Tor's control-socket interface.

A "controller" is an external program that monitors and controls a Tor instance via a text-based protocol. It connects to Tor via a connection to a local socket.

The protocol is line-driven. The controller sends commands terminated by a CRLF. Tor sends lines that are either replies to what the controller has said, or events that Tor sends to the controller asynchronously based on occurrences in the Tor network model.

See the control-spec.txt file in the torspec.git repository for full details on protocol.

This module generally has two kinds of entry points: those based on having received a command on a controller socket, which are handled in connection_control_process_inbuf(), and dispatched to individual functions with names like control_handle_COMMANDNAME(); and those based on events that occur elsewhere in Tor, which are handled by functions with names like control_event_EVENTTYPE().

Controller events are not sent immediately; rather, they are inserted into the queued_control_events array, and flushed later from flush_queued_events_cb(). Doing this simplifies our callgraph greatly, by limiting the number of places in Tor that can call back into the network stack.

Definition in file control.c.

Macro Definition Documentation

MAX_COMMAND_LINE_LENGTH

#define MAX_COMMAND_LINE_LENGTH   (1024*1024)

Do not accept any control command of more than 1MB in length. Anything that needs to be anywhere near this long probably means that one of our interfaces is broken.

Definition at line 278 of file control.c.

Function Documentation

connection_control_closed()

void connection_control_closed

(

control_connection_t *

conn

)

Called when conn is being freed.

Definition at line 231 of file control.c.

connection_control_finished_flushing()

int connection_control_finished_flushing

(

control_connection_t *

conn

)

Called when conn has no more bytes left on its outbuf.

Definition at line 201 of file control.c.

Referenced by connection_finished_flushing().

connection_control_process_inbuf()

int connection_control_process_inbuf

(

control_connection_t *

conn

)

Called when data has arrived on a v1 control connection: Try to fetch commands from conn->inbuf, and execute them.

Definition at line 418 of file control.c.

Referenced by connection_process_inbuf().

connection_control_reached_eof()

int connection_control_reached_eof

(

control_connection_t *

conn

)

Called when conn has gotten its socket closed.

Definition at line 209 of file control.c.

Referenced by connection_reached_eof().

CONST_TO_CONTROL_CONN()

const control_connection_t* CONST_TO_CONTROL_CONN

(

const connection_t *

c

)

Cast a const connection_t * to a const control_connection_t *.

Exit with an assertion failure if the input is not a control_connection_t.

Definition at line 84 of file control.c.

control_connection_add_local_fd()

int control_connection_add_local_fd	(	tor_socket_t	sock,
		unsigned	flags
	)

Create and add a new controller connection on sock. If CC_LOCAL_FD_IS_OWNER is set in flags, this Tor process should exit when the connection closes. If CC_LOCAL_FD_IS_AUTHENTICATED is set, then the connection does not need to authenticate.

Definition at line 95 of file control.c.

control_free_all()

void control_free_all

(

void

)

Free any leftover allocated memory of the control.c subsystem.

Definition at line 620 of file control.c.

control_ports_write_to_file()

void control_ports_write_to_file

(

void

)

Write all of the open control ports to ControlPortWriteToFile

Definition at line 134 of file control.c.

control_protocol_is_valid()

static bool control_protocol_is_valid ( control_connection_t *  conn )

static

Check if a control connection has tried to use a known invalid protocol. If it has, then:

• send a reject response,
• log a notice-level message, and
• return false.

Definition at line 395 of file control.c.

control_send_http_reject()

static void control_send_http_reject ( control_connection_t *  conn )

static

Return an error on a control connection that tried to use HTTP.

Definition at line 382 of file control.c.

control_send_v0_reject()

static void control_send_v0_reject ( control_connection_t *  conn )

static

Return an error on a control connection that tried to use the v0 protocol.

Definition at line 363 of file control.c.

Referenced by control_protocol_is_valid().

control_split_incoming_command()

STATIC char* control_split_incoming_command	(	char *	incoming_cmd,
		size_t *	data_len,
		char **	current_cmd_out
	)

Helper: take a nul-terminated command of given length, and find where the command starts and the arguments begin. Separate them, allocate a new string in current_cmd_out for the command, and return a pointer to the arguments.

Definition at line 303 of file control.c.

is_valid_initial_command()

static int is_valid_initial_command ( control_connection_t *  conn, const char *  cmd  )

static

Return true iff cmd is allowable (or at least forgivable) at this stage of the protocol.

Definition at line 260 of file control.c.

lost_owning_controller()

static void lost_owning_controller ( const char *  owner_type, const char *  loss_manner  )

static

Shut down this Tor instance in the same way that SIGINT would, but with a log message appropriate for the loss of an owning controller.

Definition at line 221 of file control.c.

Referenced by owning_controller_procmon_cb().

monitor_owning_controller_process()

void monitor_owning_controller_process

(

const char *

process_spec

)

Set process_spec as Tor's owning controller process. Exit on failure.

Definition at line 571 of file control.c.

owning_controller_procmon_cb()

static void owning_controller_procmon_cb ( void *  unused )

static

Process-termination monitor callback for Tor's owning controller process.

Definition at line 561 of file control.c.

peek_connection_has_control0_command()

static int peek_connection_has_control0_command ( connection_t *  conn )

static

Wrapper around peek_buf_has_control0 command: presents the same interface as that underlying functions, but takes a connection_t instead of a buf_t.

Definition at line 285 of file control.c.

Referenced by control_protocol_is_valid().

TO_CONTROL_CONN()

control_connection_t* TO_CONTROL_CONN

(

connection_t *

c

)

Cast a connection_t * to a control_connection_t *.

Exit with an assertion failure if the input is not a control_connection_t.

Definition at line 71 of file control.c.

Referenced by connection_finished_flushing(), connection_free_all(), connection_process_inbuf(), connection_reached_eof(), and CONST_TO_CONTROL_CONN().

Variable Documentation

CONTROLPORT_IS_NOT_AN_HTTP_PROXY_MSG

const char CONTROLPORT_IS_NOT_AN_HTTP_PROXY_MSG[]

static

Initial value:

=
  "HTTP/1.0 501 Tor ControlPort is not an HTTP proxy"
  "\r\nContent-Type: text/html; charset=iso-8859-1\r\n\r\n"
  "<html>\n"
  "<head>\n"
  "<title>Tor's ControlPort is not an HTTP proxy</title>\n"
  "</head>\n"
  "<body>\n"
  "<h1>Tor's ControlPort is not an HTTP proxy</h1>\n"
  "<p>\n"
  "It appears you have configured your web browser to use Tor's control port"
  " as an HTTP proxy.\n"
  "This is not correct: Tor's default SOCKS proxy port is 9050.\n"
  "Please configure your client accordingly.\n"
  "</p>\n"
  "<p>\n"
  "See <a href=\"https://www.torproject.org/documentation.html\">"
  "https://www.torproject.org/documentation.html</a> for more "
  "information.\n"
  "<!-- Plus this comment, to make the body response more than 512 bytes, so "
  "     IE will be willing to display it. Comment comment comment comment "
  "     comment comment comment comment comment comment comment comment.-->\n"
  "</p>\n"
  "</body>\n"
  "</html>\n"

Definition at line 334 of file control.c.

network_is_live

int network_is_live = 0

static

Cached liveness for network liveness events and GETINFO

Definition at line 536 of file control.c.

owning_controller_process_monitor

tor_process_monitor_t* owning_controller_process_monitor = NULL

static

A process-termination monitor for Tor's owning controller, or NULL if this Tor instance is not currently owned by a process.

Definition at line 556 of file control.c.

Referenced by monitor_owning_controller_process().

owning_controller_process_spec

char* owning_controller_process_spec = NULL

static

A copy of the process specifier of Tor's owning controller, or NULL if this Tor instance is not currently owned by a process.

Definition at line 552 of file control.c.

Referenced by monitor_owning_controller_process().

signal_table

const struct signal_name_t signal_table[]

Initial value:

= {
  
  { SIGHUP, "RELOAD" },
  { SIGHUP, "HUP" },
  { SIGINT, "SHUTDOWN" },
  { SIGUSR1, "DUMP" },
  { SIGUSR1, "USR1" },
  { SIGUSR2, "DEBUG" },
  { SIGUSR2, "USR2" },
  { SIGTERM, "HALT" },
  { SIGTERM, "TERM" },
  { SIGTERM, "INT" },
  { SIGNEWNYM, "NEWNYM" },
  { SIGCLEARDNSCACHE, "CLEARDNSCACHE"},
  { SIGHEARTBEAT, "HEARTBEAT"},
  { SIGACTIVE, "ACTIVE" },
  { SIGDORMANT, "DORMANT" },
  { 0, NULL },
}

Definition at line 134 of file control.c.