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