1 /* Copyright (c) 2001 Matej Pfajfar.
2 * Copyright (c) 2001-2004, Roger Dingledine.
3 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4 * Copyright (c) 2007-2021, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
8 * \file control_events.h
9 * \brief Header file for control_events.c.
12 #ifndef TOR_CONTROL_EVENTS_H
13 #define TOR_CONTROL_EVENTS_H
15 #include "lib/cc/ctassert.h"
16 #include "core/or/ocirc_event.h"
17 #include "core/or/orconn_event.h"
21 /** Used to indicate the type of a CIRC_MINOR event passed to the controller.
22 * The various types are defined in control-spec.txt . */
23 typedef enum circuit_status_minor_event_t
{
24 CIRC_MINOR_EVENT_PURPOSE_CHANGED
,
25 CIRC_MINOR_EVENT_CANNIBALIZED
,
26 } circuit_status_minor_event_t
;
28 /** Used to indicate the type of a stream event passed to the controller.
29 * The various types are defined in control-spec.txt */
30 typedef enum stream_status_event_t
{
31 STREAM_EVENT_SENT_CONNECT
= 0,
32 STREAM_EVENT_SENT_RESOLVE
= 1,
33 STREAM_EVENT_SUCCEEDED
= 2,
34 STREAM_EVENT_FAILED
= 3,
35 STREAM_EVENT_CLOSED
= 4,
37 STREAM_EVENT_NEW_RESOLVE
= 6,
38 STREAM_EVENT_FAILED_RETRIABLE
= 7,
39 STREAM_EVENT_REMAP
= 8,
40 STREAM_EVENT_CONTROLLER_WAIT
= 9
41 } stream_status_event_t
;
43 /** Used to indicate the type of a buildtime event */
44 typedef enum buildtimeout_set_event_t
{
45 BUILDTIMEOUT_SET_EVENT_COMPUTED
= 0,
46 BUILDTIMEOUT_SET_EVENT_RESET
= 1,
47 BUILDTIMEOUT_SET_EVENT_SUSPENDED
= 2,
48 BUILDTIMEOUT_SET_EVENT_DISCARD
= 3,
49 BUILDTIMEOUT_SET_EVENT_RESUME
= 4
50 } buildtimeout_set_event_t
;
52 /** Enum describing various stages of bootstrapping, for use with controller
53 * bootstrap status events. The values range from 0 to 100. */
55 BOOTSTRAP_STATUS_UNDEF
=-1,
56 BOOTSTRAP_STATUS_STARTING
=0,
58 /* Initial connection to any relay */
60 BOOTSTRAP_STATUS_CONN_PT
=1,
61 BOOTSTRAP_STATUS_CONN_DONE_PT
=2,
62 BOOTSTRAP_STATUS_CONN_PROXY
=3,
63 BOOTSTRAP_STATUS_CONN_DONE_PROXY
=4,
64 BOOTSTRAP_STATUS_CONN
=5,
65 BOOTSTRAP_STATUS_CONN_DONE
=10,
66 BOOTSTRAP_STATUS_HANDSHAKE
=14,
67 BOOTSTRAP_STATUS_HANDSHAKE_DONE
=15,
69 /* Loading directory info */
71 BOOTSTRAP_STATUS_ONEHOP_CREATE
=20,
72 BOOTSTRAP_STATUS_REQUESTING_STATUS
=25,
73 BOOTSTRAP_STATUS_LOADING_STATUS
=30,
74 BOOTSTRAP_STATUS_LOADING_KEYS
=40,
75 BOOTSTRAP_STATUS_REQUESTING_DESCRIPTORS
=45,
76 BOOTSTRAP_STATUS_LOADING_DESCRIPTORS
=50,
77 BOOTSTRAP_STATUS_ENOUGH_DIRINFO
=75,
79 /* Connecting to a relay for AP circuits */
81 BOOTSTRAP_STATUS_AP_CONN_PT
=76,
82 BOOTSTRAP_STATUS_AP_CONN_DONE_PT
=77,
83 BOOTSTRAP_STATUS_AP_CONN_PROXY
=78,
84 BOOTSTRAP_STATUS_AP_CONN_DONE_PROXY
=79,
85 BOOTSTRAP_STATUS_AP_CONN
=80,
86 BOOTSTRAP_STATUS_AP_CONN_DONE
=85,
87 BOOTSTRAP_STATUS_AP_HANDSHAKE
=89,
88 BOOTSTRAP_STATUS_AP_HANDSHAKE_DONE
=90,
90 /* Creating AP circuits */
92 BOOTSTRAP_STATUS_CIRCUIT_CREATE
=95,
93 BOOTSTRAP_STATUS_DONE
=100
96 /** Reason for remapping an AP connection's address: we have a cached
98 #define REMAP_STREAM_SOURCE_CACHE 1
99 /** Reason for remapping an AP connection's address: the exit node told us an
101 #define REMAP_STREAM_SOURCE_EXIT 2
103 void control_initialize_event_queue(void);
105 void control_update_global_event_mask(void);
106 void control_adjust_event_log_severity(void);
108 #define EVENT_NS 0x000F
109 int control_event_is_interesting(int event
);
111 void control_per_second_events(void);
112 int control_any_per_second_event_enabled(void);
114 int control_event_circuit_status(origin_circuit_t
*circ
,
115 circuit_status_event_t e
, int reason
);
116 int control_event_circuit_purpose_changed(origin_circuit_t
*circ
,
118 int control_event_circuit_cannibalized(origin_circuit_t
*circ
,
120 const struct timeval
*old_tv_created
);
121 int control_event_stream_status(entry_connection_t
*conn
,
122 stream_status_event_t e
,
124 int control_event_or_conn_status(or_connection_t
*conn
,
125 or_conn_status_event_t e
, int reason
);
126 int control_event_bandwidth_used(uint32_t n_read
, uint32_t n_written
);
127 int control_event_stream_bandwidth(edge_connection_t
*edge_conn
);
128 int control_event_stream_bandwidth_used(void);
129 int control_event_circ_bandwidth_used(void);
130 int control_event_circ_bandwidth_used_for_circ(origin_circuit_t
*ocirc
);
131 int control_event_conn_bandwidth(connection_t
*conn
);
132 int control_event_conn_bandwidth_used(void);
133 int control_event_circuit_cell_stats(void);
134 void control_event_logmsg(int severity
, log_domain_mask_t domain
,
136 void control_event_logmsg_pending(void);
137 int control_event_descriptors_changed(smartlist_t
*routers
);
138 int control_event_address_mapped(const char *from
, const char *to
,
139 time_t expires
, const char *error
,
140 const int cached
, uint64_t stream_id
);
141 int control_event_my_descriptor_changed(void);
142 int control_event_network_liveness_update(int liveness
);
143 int control_event_networkstatus_changed(smartlist_t
*statuses
);
145 int control_event_newconsensus(const networkstatus_t
*consensus
);
146 int control_event_networkstatus_changed_single(const routerstatus_t
*rs
);
147 int control_event_general_status(int severity
, const char *format
, ...)
149 int control_event_client_status(int severity
, const char *format
, ...)
151 int control_event_server_status(int severity
, const char *format
, ...)
154 int control_event_general_error(const char *format
, ...)
156 int control_event_client_error(const char *format
, ...)
158 int control_event_server_error(const char *format
, ...)
161 int control_event_guard(const char *nickname
, const char *digest
,
163 void control_event_conf_changed(const struct config_line_t
*changes
);
164 int control_event_buildtimeout_set(buildtimeout_set_event_t type
,
166 int control_event_signal(uintptr_t signal
);
168 void control_event_bootstrap(bootstrap_status_t status
, int progress
);
169 int control_get_bootstrap_percent(void);
170 MOCK_DECL(void, control_event_bootstrap_prob_or
,(const char *warn
,
172 or_connection_t
*or_conn
));
173 void control_event_boot_dir(bootstrap_status_t status
, int progress
);
174 void control_event_boot_first_orconn(void);
175 void control_event_bootstrap_problem(const char *warn
, const char *reason
,
176 const connection_t
*conn
, int dowarn
);
177 char *control_event_boot_last_msg(void);
178 void control_event_bootstrap_reset(void);
180 void control_event_clients_seen(const char *controller_str
);
181 void control_event_transport_launched(const char *mode
,
182 const char *transport_name
,
183 tor_addr_t
*addr
, uint16_t port
);
184 void control_event_pt_log(const char *log
);
185 void control_event_pt_status(const char *status
);
187 void control_event_hs_descriptor_requested(const char *onion_address
,
188 rend_auth_type_t auth_type
,
189 const char *id_digest
,
191 const char *hsdir_index
);
192 void control_event_hs_descriptor_created(const char *onion_address
,
195 void control_event_hs_descriptor_upload(const char *onion_address
,
198 const char *hsdir_index
);
199 void control_event_hs_descriptor_upload_end(const char *action
,
200 const char *onion_address
,
203 void control_event_hs_descriptor_uploaded(const char *hs_dir
,
204 const char *onion_address
);
205 /* Hidden service v3 HS_DESC specific. */
206 void control_event_hsv3_descriptor_failed(const char *onion_address
,
208 const char *hsdir_id_digest
,
210 void control_event_hsv3_descriptor_received(const char *onion_address
,
212 const char *hsdir_id_digest
);
213 void control_event_hs_descriptor_upload_failed(const char *hs_dir
,
214 const char *onion_address
,
216 void control_event_hs_descriptor_content(const char *onion_address
,
218 const char *hsdir_fp
,
219 const char *content
);
220 void cbt_control_event_buildtimeout_set(const circuit_build_times_t
*cbt
,
221 buildtimeout_set_event_t type
);
223 int control_event_enter_controller_wait(void);
225 void control_events_free_all(void);
227 #ifdef CONTROL_MODULE_PRIVATE
228 char *get_bw_samples(void);
229 #endif /* defined(CONTROL_MODULE_PRIVATE) */
231 #ifdef CONTROL_EVENTS_PRIVATE
232 /** Bitfield: The bit 1<<e is set if <b>any</b> open control
233 * connection is interested in events of type <b>e</b>. We use this
234 * so that we can decide to skip generating event messages that nobody
235 * has interest in without having to walk over the global connection
238 typedef uint64_t event_mask_t
;
240 /* Recognized asynchronous event types. It's okay to expand this list
241 * because it is used both as a list of v0 event types, and as indices
242 * into the bitfield to determine which controllers want which events.
244 /* This bitfield has no event zero 0x0000 */
245 #define EVENT_MIN_ 0x0001
246 #define EVENT_CIRCUIT_STATUS 0x0001
247 #define EVENT_STREAM_STATUS 0x0002
248 #define EVENT_OR_CONN_STATUS 0x0003
249 #define EVENT_BANDWIDTH_USED 0x0004
250 #define EVENT_CIRCUIT_STATUS_MINOR 0x0005
251 #define EVENT_NEW_DESC 0x0006
252 #define EVENT_DEBUG_MSG 0x0007
253 #define EVENT_INFO_MSG 0x0008
254 #define EVENT_NOTICE_MSG 0x0009
255 #define EVENT_WARN_MSG 0x000A
256 #define EVENT_ERR_MSG 0x000B
257 #define EVENT_ADDRMAP 0x000C
258 /* There was an AUTHDIR_NEWDESCS event, but it no longer exists. We
259 can reclaim 0x000D. */
260 #define EVENT_DESCCHANGED 0x000E
262 // #define EVENT_NS 0x000F
263 #define EVENT_STATUS_CLIENT 0x0010
264 #define EVENT_STATUS_SERVER 0x0011
265 #define EVENT_STATUS_GENERAL 0x0012
266 #define EVENT_GUARD 0x0013
267 #define EVENT_STREAM_BANDWIDTH_USED 0x0014
268 #define EVENT_CLIENTS_SEEN 0x0015
269 #define EVENT_NEWCONSENSUS 0x0016
270 #define EVENT_BUILDTIMEOUT_SET 0x0017
271 #define EVENT_GOT_SIGNAL 0x0018
272 #define EVENT_CONF_CHANGED 0x0019
273 #define EVENT_CONN_BW 0x001A
274 #define EVENT_CELL_STATS 0x001B
275 /* UNUSED : 0x001C */
276 #define EVENT_CIRC_BANDWIDTH_USED 0x001D
277 #define EVENT_TRANSPORT_LAUNCHED 0x0020
278 #define EVENT_HS_DESC 0x0021
279 #define EVENT_HS_DESC_CONTENT 0x0022
280 #define EVENT_NETWORK_LIVENESS 0x0023
281 #define EVENT_PT_LOG 0x0024
282 #define EVENT_PT_STATUS 0x0025
283 #define EVENT_MAX_ 0x0025
285 /* sizeof(control_connection_t.event_mask) in bits, currently a uint64_t */
286 #define EVENT_CAPACITY_ 0x0040
288 /* If EVENT_MAX_ ever hits 0x0040, we need to make the mask into a
289 * different structure, as it can only handle a maximum left shift of 1<<63. */
290 CTASSERT(EVENT_MAX_
< EVENT_CAPACITY_
);
292 #define EVENT_MASK_(e) (((uint64_t)1)<<(e))
294 #define EVENT_MASK_NONE_ ((uint64_t)0x0)
296 #define EVENT_MASK_ABOVE_MIN_ ((~((uint64_t)0x0)) << EVENT_MIN_)
297 #define EVENT_MASK_BELOW_MAX_ ((~((uint64_t)0x0)) \
298 >> (EVENT_CAPACITY_ - EVENT_MAX_ \
301 #define EVENT_MASK_ALL_ (EVENT_MASK_ABOVE_MIN_ \
302 & EVENT_MASK_BELOW_MAX_)
304 /** Helper structure: temporarily stores cell statistics for a circuit. */
305 typedef struct cell_stats_t
{
306 /** Number of cells added in app-ward direction by command. */
307 uint64_t added_cells_appward
[CELL_COMMAND_MAX_
+ 1];
308 /** Number of cells added in exit-ward direction by command. */
309 uint64_t added_cells_exitward
[CELL_COMMAND_MAX_
+ 1];
310 /** Number of cells removed in app-ward direction by command. */
311 uint64_t removed_cells_appward
[CELL_COMMAND_MAX_
+ 1];
312 /** Number of cells removed in exit-ward direction by command. */
313 uint64_t removed_cells_exitward
[CELL_COMMAND_MAX_
+ 1];
314 /** Total waiting time of cells in app-ward direction by command. */
315 uint64_t total_time_appward
[CELL_COMMAND_MAX_
+ 1];
316 /** Total waiting time of cells in exit-ward direction by command. */
317 uint64_t total_time_exitward
[CELL_COMMAND_MAX_
+ 1];
320 void sum_up_cell_stats_by_command(circuit_t
*circ
,
321 cell_stats_t
*cell_stats
);
322 void append_cell_stats_by_command(smartlist_t
*event_parts
,
324 const uint64_t *include_if_non_zero
,
325 const uint64_t *number_to_include
);
326 void format_cell_stats(char **event_string
, circuit_t
*circ
,
327 cell_stats_t
*cell_stats
);
329 /** Helper structure: maps event values to their names. */
330 struct control_event_t
{
332 const char *event_name
;
335 extern const struct control_event_t control_event_table
[];
337 void control_logmsg_strip_newlines(char *msg
);
339 #ifdef TOR_UNIT_TESTS
340 MOCK_DECL(STATIC
void,
341 send_control_event_string
,(uint16_t event
, const char *msg
));
343 MOCK_DECL(STATIC
void,
344 queue_control_event_string
,(uint16_t event
, char *msg
));
346 void control_testing_set_global_event_mask(uint64_t mask
);
348 #endif /* defined(TOR_UNIT_TESTS) */
350 #endif /* defined(CONTROL_EVENTS_PRIVATE) */
352 #endif /* !defined(TOR_CONTROL_EVENTS_H) */