Macros | Functions | Variables
control.c File Reference
#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/rend/rendcommon.h"
#include "feature/rend/rendservice.h"
#include "lib/evloop/procmon.h"
#include "feature/control/control_connection_st.h"

Go to the source code of this file.


#define MAX_COMMAND_LINE_LENGTH   (1024*1024)


control_connection_tTO_CONTROL_CONN (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)
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)


const struct signal_name_t signal_table []
static int network_is_live = 0
static char * owning_controller_process_spec = NULL
static tor_process_monitor_towning_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


#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 260 of file control.c.

Function Documentation

◆ connection_control_closed()

void connection_control_closed ( control_connection_t conn)

◆ 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 181 of file control.c.

References tor_assert().

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 346 of file control.c.

References CONTROL_CONN_STATE_NEEDAUTH, CONTROL_CONN_STATE_OPEN, control_connection_t::incoming_cmd, connection_t::state, and tor_assert().

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 189 of file control.c.

References tor_assert().

Referenced by connection_reached_eof().

◆ 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 79 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 571 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 118 of file control.c.

References CONN_TYPE_CONTROL_LISTENER, or_options_t::ControlPortWriteToFile, smartlist_add_asprintf(), and SMARTLIST_FOREACH_BEGIN.

◆ 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 285 of file control.c.

◆ is_valid_initial_command()

static int is_valid_initial_command ( control_connection_t conn,
const char *  cmd 

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

Definition at line 242 of file control.c.

References CONTROL_CONN_STATE_OPEN, control_connection_t::have_sent_protocolinfo, control_connection_t::safecookie_client_hash, and connection_t::state.

◆ lost_owning_controller()

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

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 201 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 522 of file control.c.

References owning_controller_process_monitor, owning_controller_process_spec, and tor_assert().

◆ owning_controller_procmon_cb()

static void owning_controller_procmon_cb ( void *  unused)

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

Definition at line 512 of file control.c.

References lost_owning_controller().

◆ peek_connection_has_control0_command()

static int peek_connection_has_control0_command ( connection_t conn)

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

Definition at line 267 of file control.c.

References connection_t::inbuf.


control_connection_t* TO_CONTROL_CONN ( connection_t c)

Convert a connection_t* to an control_connection_t*; assert if the cast is invalid.

Definition at line 67 of file control.c.

References DOWNCAST, connection_t::magic, and tor_assert().

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

Variable Documentation


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"
"<title>Tor's ControlPort is not an HTTP proxy</title>\n"
"<h1>Tor's ControlPort is not an HTTP proxy</h1>\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"
"See <a href=\"\">"
"</a> for more "
"<!-- 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"

Definition at line 316 of file control.c.

◆ network_is_live

int network_is_live = 0

Cached liveness for network liveness events and GETINFO

Definition at line 487 of file control.c.

◆ owning_controller_process_monitor

tor_process_monitor_t* owning_controller_process_monitor = NULL

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 507 of file control.c.

Referenced by monitor_owning_controller_process().

◆ owning_controller_process_spec

char* owning_controller_process_spec = NULL

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 503 of file control.c.

Referenced by monitor_owning_controller_process().

◆ signal_table

const struct signal_name_t signal_table[]
Initial value:
= {
{ SIGHUP, "HUP" },
{ SIGUSR1, "DUMP" },
{ SIGUSR1, "USR1" },
{ SIGUSR2, "USR2" },
{ 0, NULL },

Definition at line 160 of file control.c.