1 /* 2 ** Copyright (C) 2004-2020 by Carnegie Mellon University. 3 ** 4 ** @OPENSOURCE_LICENSE_START@ 5 ** See license information in ../../LICENSE.txt 6 ** @OPENSOURCE_LICENSE_END@ 7 */ 8 9 /* 10 ** libflowsource.h 11 ** 12 ** Definitions/Declaration for the libflowsource library and all 13 ** the possible external flow sources (IPFIX, PDU, etc). 14 ** 15 */ 16 #ifndef _LIBFLOWSOURCE_H 17 #define _LIBFLOWSOURCE_H 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 #include <silk/silk.h> 23 24 RCSIDENTVAR(rcsID_LIBFLOWSOURCE_H, "$SiLK: libflowsource.h ef14e54179be 2020-04-14 21:57:45Z mthomas $"); 25 26 #include <silk/silk_types.h> 27 #include <silk/rwrec.h> 28 #include <silk/probeconf.h> 29 30 /** 31 * @file 32 * 33 * libflowsource is used by flowcap and rwflowpack to import 34 * NetFlowV5, IPFIX, or NetFlowV9 flow records. 35 * 36 * This file is part of libflowsource. 37 */ 38 39 40 /** 41 * Value returned by skpcProbeGetLogFlags() when all log messages 42 * should be suppressed. 43 */ 44 #define SOURCE_LOG_NONE 0 45 46 /** 47 * Log flag returned by skpcProbeGetLogFlags() denoting log 48 * messages about out of sequence NetFlow v5 packets. 49 */ 50 #define SOURCE_LOG_MISSING (1 << 0) 51 52 /** 53 * Log flag returned by skpcProbeGetLogFlags() denoting log 54 * messages about invalid NetFlow v5 packets. 55 */ 56 #define SOURCE_LOG_BAD (1 << 1) 57 58 /** 59 * Log flag returned by skpcProbeGetLogFlags() denoting log 60 * messages about the sampling interval used in IPFIX and NetFlow 61 * v9. (Since SiLK 3.8.0.) 62 */ 63 #define SOURCE_LOG_SAMPLING (1 << 2) 64 65 /** 66 * Log flag returned by skpcProbeGetLogFlags() denoting log 67 * messages about flow records being ignored due to an IPFIX or 68 * NetFlow v9 firewall event setting. (Since SiLK 3.8.1.) 69 */ 70 #define SOURCE_LOG_FIREWALL (1 << 3) 71 72 /** 73 * Log flag returned by skpcProbeGetLogFlags() denoting log 74 * messages about the timestamps on the IPFIX, NetFlow v9, and 75 * NetFlow v5 records. (Since SiLK 3.10.0.) 76 */ 77 #define SOURCE_LOG_TIMESTAMPS (1 << 4) 78 79 /** 80 * Log flag returned by skpcProbeGetLogFlags() denoting log 81 * messages showing the content of the IPFIX or NetFlow v9 82 * templates. This flag is global, since setting it for ANY probe 83 * causes it to apply to all probes. 84 */ 85 #define SOURCE_LOG_TEMPLATES (1 << 5) 86 87 #if 0 88 /** 89 * Log flag returned by skpcProbeGetLogFlags() denoting log 90 * messages generated by libfixbuf (Out-of-sequence packets, 91 * missing templates, record count discrepancies, list decoding 92 * issues). This flag is global, since setting it for ANY probe 93 * causes it to apply to all probes. 94 */ 95 #define SOURCE_LOG_LIBFIXBUF (1 << 6) 96 #endif /* 0 */ 97 98 /** 99 * Value returned by skpcProbeGetLogFlags() denoting the values for 100 * the default log messages. (Since SiLK 3.10.0.) 101 */ 102 #define SOURCE_LOG_DEFAULT \ 103 (SOURCE_LOG_MISSING | SOURCE_LOG_BAD | SOURCE_LOG_SAMPLING) 104 105 /** 106 * Value returned by skpcProbeGetLogFlags() when all log messages 107 * should be printed. 108 */ 109 #define SOURCE_LOG_ALL 0xff 110 111 112 113 /** 114 * Number of bytes we want to split between socket buffers 115 */ 116 #define SOCKETBUFFER_NOMINAL_TOTAL 0x800000 /* 8M */ 117 118 /** 119 * Environment variable to modify SOCKETBUFFER_NOMINAL_TOTAL 120 */ 121 #define SOCKETBUFFER_NOMINAL_TOTAL_ENV "SK_SOCKETBUFFER_TOTAL" 122 123 /** 124 * Minimum number of bytes to attempt to allocate to a socket buffer 125 */ 126 #define SOCKETBUFFER_MINIMUM 0x20000 /* 128K */ 127 128 /** 129 * Environment variable to modify SOCKETBUFFER_MINIMUM 130 */ 131 #define SOCKETBUFFER_MINIMUM_ENV "SK_SOCKETBUFFER_MINIMUM" 132 133 134 typedef union skFlowSourceParams_un { 135 uint32_t max_pkts; 136 const char *path_name; 137 } skFlowSourceParams_t; 138 139 140 /** 141 * Structure used to report the statistics of packets processed by 142 * a flow source. 143 */ 144 typedef struct skFlowSourceStats_st { 145 /** Number of processed packets */ 146 uint64_t procPkts; 147 /** Number of completely bad packets */ 148 uint64_t badPkts; 149 /** Number of good records processed */ 150 uint64_t goodRecs; 151 /** Number of records with bad data */ 152 uint64_t badRecs; 153 /** Number of missing records; NOTE: signed int to allow for out of 154 * seq pkts */ 155 int64_t missingRecs; 156 } skFlowSourceStats_t; 157 158 /** 159 * Macro to print the statistics. 160 */ 161 #define FLOWSOURCE_STATS_INFOMSG(source_name, source_stats) \ 162 INFOMSG(("'%s': Pkts %" PRIu64 "/%" PRIu64 \ 163 ", Recs %" PRIu64 ", MissRecs %" PRId64 \ 164 ", BadRecs %" PRIu64), \ 165 (source_name), \ 166 ((source_stats)->procPkts - (source_stats)->badPkts), \ 167 (source_stats)->procPkts, (source_stats)->goodRecs, \ 168 (source_stats)->missingRecs, (source_stats)->badRecs) 169 170 171 172 /*** PDU SOURCES ********************************************************/ 173 174 /** 175 * A PDU source is a flow record source based on NetFlow v5 PDU 176 * records. Once created, records can be requested of it via a 177 * pull mechanism. 178 */ 179 typedef struct skPDUSource_st skPDUSource_t; 180 181 182 /** 183 * Creates a PDU source based on a skpc_probe_t. 184 * 185 * If the source is a network-based probe, this function also 186 * starts the collection process. 187 * 188 * When creating a source from a network-based probe, the 'params' 189 * union should have the 'max_pkts' member specify the maximum 190 * number of packets to buffer in memory for this source. 191 * 192 * When creating a source from a probe that specifies either a file 193 * or a directory that is polled for files, the 'params' union must 194 * have the 'path_name' specify the full path of the file to 195 * process. 196 * 197 * Return the new source, or NULL on error. 198 */ 199 skPDUSource_t * 200 skPDUSourceCreate( 201 const skpc_probe_t *probe, 202 const skFlowSourceParams_t *params); 203 204 205 /** 206 * Stops processing of packets. This will cause a call to any 207 * skPDUSourceGetGeneric() function to stop blocking. Meant to be 208 * used as a prelude to skPDUSourceDestroy() in threaded code. 209 */ 210 void 211 skPDUSourceStop( 212 skPDUSource_t *source); 213 214 215 /** 216 * Destroys the PDU source. This will also cause a call to any 217 * skPDUSourceGetGeneric() function to stop blocking. In threaded 218 * programs, it is best to call skPDUSourceStop() first, wait for 219 * any consumers of the packets to notice that the source has 220 * stopped, then call skPDUSourceDestroy(). 221 */ 222 void 223 skPDUSourceDestroy( 224 skPDUSource_t *source); 225 226 227 /** 228 * Requests a SiLK Flow record from the PDU source. For a 229 * network-based source, this function will block if there are no 230 * records available. Returns 0 on success, -1 on error. 231 */ 232 int 233 skPDUSourceGetGeneric( 234 skPDUSource_t *source, 235 rwRec *rwrec); 236 237 238 /** 239 * Logs statistics associated with a PDU source. 240 */ 241 void 242 skPDUSourceLogStats( 243 skPDUSource_t *source); 244 245 246 /** 247 * Logs statistics associated with a PDU source, and then clears 248 * the stats. 249 */ 250 void 251 skPDUSourceLogStatsAndClear( 252 skPDUSource_t *source); 253 254 255 /** 256 * Clears the current statistics for the PDU source. 257 */ 258 void 259 skPDUSourceClearStats( 260 skPDUSource_t *source); 261 262 263 /*** IPFIX SOURCES ******************************************************/ 264 265 266 /** 267 * Values that represent constants used by the IPFIX standard 268 * and/or CISCO devices to represent firewall events: 269 * 270 * firewallEvent is an official IPFIX information element, IE 233 271 * 272 * NF_F_FW_EVENT is Cisco IE 40005 273 * 274 * NF_F_FW_EXT_EVENT is Cisco IE 33002. 275 * 276 * The NF_F_FW_EXT_EVENT provides a subtype for the NF_F_FW_EVENT 277 * type. See the lengthy comment in skipfix.c. 278 */ 279 #define SKIPFIX_FW_EVENT_CREATED 1 280 #define SKIPFIX_FW_EVENT_DELETED 2 281 #define SKIPFIX_FW_EVENT_DENIED 3 282 /* denied due to ingress acl */ 283 #define SKIPFIX_FW_EVENT_DENIED_INGRESS 1001 284 /* denied due to egress acl */ 285 #define SKIPFIX_FW_EVENT_DENIED_EGRESS 1002 286 /* denied due to attempting to contact ASA's service port */ 287 #define SKIPFIX_FW_EVENT_DENIED_SERV_PORT 1003 288 /* denied due to first packet not syn */ 289 #define SKIPFIX_FW_EVENT_DENIED_NOT_SYN 1004 290 #define SKIPFIX_FW_EVENT_ALERT 4 291 #define SKIPFIX_FW_EVENT_UPDATED 5 292 293 /** 294 * Return true if value in 'sfedcv_val' is recognized as a 295 * NF_F_FW_EXT_EVENT sub-value for "Denied" firewall events. 296 */ 297 #define SKIPFIX_FW_EVENT_DENIED_CHECK_VALID(sfedcv_val) \ 298 (SKIPFIX_FW_EVENT_DENIED_INGRESS <= (sfedcv_val) \ 299 && SKIPFIX_FW_EVENT_DENIED_NOT_SYN >= (sfedcv_val)) 300 301 302 /** 303 * An IPFIX source is a flow record source based on IPFIX or 304 * NetFlow V9 records. Once created, records can be requested of 305 * it via a pull mechanism. 306 */ 307 typedef struct skIPFIXSource_st skIPFIXSource_t; 308 309 310 /** 311 * Performs any initialization required prior to creating the IPFIX 312 * sources. Returns 0 on success, or -1 on failure. 313 */ 314 int 315 skIPFIXSourcesSetup( 316 void); 317 318 319 /** 320 * Free any state allocated by skIPFIXSourcesSetup(). This 321 * function is not thread safe. 322 */ 323 void 324 skIPFIXSourcesTeardown( 325 void); 326 327 328 /** 329 * Creates a IPFIX source based on an skpc_probe_t. 330 * 331 * If the source is a network-based probe, this function also 332 * starts the collection process. 333 * 334 * When creating a source from a network-based probe, the 'params' 335 * union should have the 'max_pkts' member specify the maximum 336 * number of packets to buffer in memory for this source. 337 * 338 * When creating a source from a probe that specifies either a file 339 * or a directory that is polled for files, the 'params' union must 340 * have the 'path_name' specify the full path of the file to 341 * process. 342 * 343 * Return the new source, or NULL on error. 344 */ 345 skIPFIXSource_t * 346 skIPFIXSourceCreate( 347 const skpc_probe_t *probe, 348 const skFlowSourceParams_t *params); 349 350 351 /** 352 * Stops processing of packets. This will cause a call to any 353 * skIPFIXSourceGetGeneric() function to stop blocking. Meant to 354 * be used as a prelude to skIPFIXSourceDestroy() in threaded code. 355 */ 356 void 357 skIPFIXSourceStop( 358 skIPFIXSource_t *source); 359 360 361 /** 362 * Destroys a IPFIX source. 363 */ 364 void 365 skIPFIXSourceDestroy( 366 skIPFIXSource_t *source); 367 368 369 /** 370 * Requests a SiLK Flow record from the IPFIX source 'source'. 371 * 372 * This function will block if there are no IPFIX flows available 373 * from which to create a SiLK Flow record. 374 * 375 * Returns 0 on success, -1 on failure. 376 */ 377 int 378 skIPFIXSourceGetGeneric( 379 skIPFIXSource_t *source, 380 rwRec *rwrec); 381 382 383 /** 384 * Logs statistics associated with a IPFIX source, and then clears 385 * the stats. 386 */ 387 void 388 skIPFIXSourceLogStatsAndClear( 389 skIPFIXSource_t *source); 390 391 392 393 394 #ifdef __cplusplus 395 } 396 #endif 397 #endif /* _LIBFLOWSOURCE_H */ 398 399 /* 400 ** Local Variables: 401 ** mode:c 402 ** indent-tabs-mode:nil 403 ** c-basic-offset:4 404 ** End: 405 */ 406