source: lib/libtrace.h @ 68667ee

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 68667ee was 68667ee, checked in by Perry Lorier <perry@…>, 16 years ago

Merged in a whole heap of useful features

  • Property mode set to 100644
File size: 15.9 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2004 The University of Waikato, Hamilton, New Zealand.
5 * Authors: Daniel Lawson
6 *          Perry Lorier
7 *         
8 * All rights reserved.
9 *
10 * This code has been developed by the University of Waikato WAND
11 * research group. For further information please see http://www.wand.net.nz/
12 *
13 * libtrace is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
17 *
18 * libtrace is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21 * GNU General Public License for more details.
22 *
23 * You should have received a copy of the GNU General Public License
24 * along with libtrace; if not, write to the Free Software
25 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26 *
27 * $Id$
28 *
29 */
30
31#ifndef LIBTRACE_H
32#define LIBTRACE_H
33
34#include <sys/types.h>
35#include <netinet/in.h>
36
37#ifdef __cplusplus
38extern "C" { 
39#endif
40/** @file
41 *
42 * @brief Trace file processing library header
43 *
44 * @author Daniel Lawson
45 * @author Perry Lorier
46 *
47 * @version $Id$
48 *
49 * This library provides a per packet interface into a trace file, or a live
50 * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
51 * pcap etc.
52 *
53 * @par Usage
54 * <ol>
55 * <li> include "libtrace.h"
56 * <li> call create_trace with the uri of the trace you're interested in.<br>
57 * This is usually passed in as argv[1] to your program.
58 * <li> call libtrace_read_packet(), passing in the libtrace_t returned from
59 * create trace and a buffer (and the buffer length)
60 * <li> call getIP() on the buffer, and do whatever you need
61 * <li> loop back to step 3, until libtrace_read_packet() returns -1
62 * </ol>
63 * @par Linking
64 * To use this library you need to link against libtrace by passing -ltrace
65 * to your linker. You may also need to link against a version of libpcap
66 * and of zlib which are compiled for largefile support (if you wish to access
67 * traces larger than 2 GB). This is left as an exercise for the reader. Debian
68 * Woody, at least, does not support large file offsets.
69 *
70 */
71
72#define COLLECTOR_PORT 3435
73
74/** Opaque structure holding information about a trace */
75struct libtrace_t;
76       
77/** Opaque structure holding information about a bpf filter */
78struct libtrace_filter_t;
79
80/** Opaque structure holding information about a packet */
81#define LIBTRACE_PACKET_BUFSIZE 65536
82struct libtrace_packet_t {
83        struct libtrace_t *trace;
84        //void *buffer;
85        char buffer[LIBTRACE_PACKET_BUFSIZE];
86        size_t size;
87        uint8_t status;
88};
89
90/** Structure for dealing with IP packets */
91struct libtrace_ip
92  {
93#if BYTE_ORDER == LITTLE_ENDIAN
94    unsigned int ip_hl:4;               /**< header length */
95    unsigned int ip_v:4;                /**< version */
96#elif BYTE_ORDER == BIG_ENDIAN
97    unsigned int ip_v:4;                /**< version */
98    unsigned int ip_hl:4;               /**< header length */
99#else
100#   error "Adjust your <bits/endian.h> defines"
101#endif
102    u_int8_t ip_tos;                    /**< type of service */
103    u_short ip_len;                     /**< total length */
104    u_short ip_id;                      /**< identification */
105    u_short ip_off;                     /**< fragment offset field */
106#define IP_RF 0x8000                    /**< reserved fragment flag */
107#define IP_DF 0x4000                    /**< dont fragment flag */
108#define IP_MF 0x2000                    /**< more fragments flag */
109#define IP_OFFMASK 0x1fff               /**< mask for fragmenting bits */
110    u_int8_t ip_ttl;                    /**< time to live */
111    u_int8_t ip_p;                      /**< protocol */
112    u_short ip_sum;                     /**< checksum */
113    struct in_addr ip_src;              /**< source address */
114    struct in_addr ip_dst;              /**< dest address */
115  };
116
117/** Structure for dealing with TCP packets */
118struct libtrace_tcp
119  {
120    u_int16_t source;           /**< Source Port */
121    u_int16_t dest;             /**< Destination port */
122    u_int32_t seq;              /**< Sequence number */
123    u_int32_t ack_seq;          /**< Acknowledgement Number */
124#  if BYTE_ORDER == LITTLE_ENDIAN
125    u_int16_t res1:4;           /**< Reserved bits */
126    u_int16_t doff:4;           
127    u_int16_t fin:1;            /**< FIN */
128    u_int16_t syn:1;            /**< SYN flag */
129    u_int16_t rst:1;            /**< RST flag */
130    u_int16_t psh:1;            /**< PuSH flag */
131    u_int16_t ack:1;            /**< ACK flag */
132    u_int16_t urg:1;            /**< URG flag */
133    u_int16_t res2:2;           /**< Reserved */
134#  elif BYTE_ORDER == BIG_ENDIAN
135    u_int16_t doff:4;           
136    u_int16_t res1:4;           /**< Reserved bits */
137    u_int16_t res2:2;           /**< Reserved */
138    u_int16_t urg:1;            /**< URG flag */
139    u_int16_t ack:1;            /**< ACK flag */
140    u_int16_t psh:1;            /**< PuSH flag */
141    u_int16_t rst:1;            /**< RST flag */
142    u_int16_t syn:1;            /**< SYN flag */
143    u_int16_t fin:1;            /**< FIN flag */
144#  else
145#   error "Adjust your <bits/endian.h> defines"
146#  endif
147    u_int16_t window;           /**< Window Size */
148    u_int16_t check;            /**< Checksum */
149    u_int16_t urg_ptr;          /**< Urgent Pointer */
150};
151
152/** UDP Header for dealing with UDP packets */
153struct libtrace_udp {
154  u_int16_t     source;         /**< Source port */
155  u_int16_t     dest;           /**< Destination port */
156  u_int16_t     len;            /**< Length */
157  u_int16_t     check;          /**< Checksum */
158};
159
160/** ICMP Header for dealing with icmp packets */
161struct libtrace_icmp
162{
163  u_int8_t type;                /**< message type */
164  u_int8_t code;                /**< type sub-code */
165  u_int16_t checksum;           /**< checksum */
166  union
167  {
168    struct
169    {
170      u_int16_t id;
171      u_int16_t sequence;
172    } echo;                     /**< echo datagram */
173    u_int32_t   gateway;        /**< gateway address */
174    struct
175    {
176      u_int16_t unused;
177      u_int16_t mtu;
178    } frag;                     /**< path mtu discovery */
179  } un;
180};
181
182
183
184
185/** Create a trace file from a URI
186 *
187 * @returns opaque pointer to a libtrace_t
188 *
189 * Valid URI's are:
190 *  - erf:/path/to/erf/file
191 *  - erf:/path/to/erf/file.gz
192 *  - erf:/path/to/rtclient/socket
193 *  - erf:-  (stdin)
194 *  - dag:/dev/dagcard                  (implementd?)
195 *  - pcap:pcapinterface                (eg: pcap:eth0)
196 *  - pcap:/path/to/pcap/file
197 *  - pcap:/path/to/pcap/file.gz
198 *  - pcap:/path/to/pcap/socket         (implemented?)
199 *  - pcap:-
200 *  - rtclient:hostname
201 *  - rtclient:hostname:port
202 *  - wag:/path/to/wag/file
203 *  - wag:/path/to/wag/file.gz
204 *  - wag:/path/to/wag/socket
205 *  - wag:/dev/device
206 *
207 *  If an error occured why attempting to open the trace file, NULL is returned
208 *  and an error is output to stdout.
209 */
210struct libtrace_t *trace_create(char *uri);
211
212/** Close a trace file, freeing up any resources it may have been using
213 *
214 */
215void trace_destroy(struct libtrace_t *trace);
216
217/** Read one packet from the trace into buffer
218 *
219 * @param libtrace      the libtrace opaque pointer
220 * @param packet        the packet opaque pointer
221 * @returns false if it failed to read a packet
222 *
223 */
224int trace_read_packet(struct libtrace_t *trace, struct libtrace_packet_t *packet);
225
226/** get a pointer to the link layer
227 * @param packet        the packet opaque pointer
228 *
229 * @returns a pointer to the link layer, or NULL if there is no link layer
230 *
231 * @note you should call getLinkType() to find out what type of link layer
232 * this is
233 */
234void *trace_get_link(struct libtrace_packet_t *packet);
235
236/** get a pointer to the IP header (if any)
237 * @param packet        the packet opaque pointer
238 *
239 * @returns a pointer to the IP header, or NULL if there is not an IP packet
240 */
241struct libtrace_ip *trace_get_ip(struct libtrace_packet_t *packet);
242
243/** get a pointer to the TCP header (if any)
244 * @param packet        the packet opaque pointer
245 *
246 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
247 */
248struct libtrace_tcp *trace_get_tcp(struct libtrace_packet_t *packet);
249
250/** get a pointer to the TCP header (if any) given a pointer to the IP header
251 * @param ip            The IP header
252 * @param[out] skipped  An output variable of the number of bytes skipped
253 *
254 * @returns a pointer to the TCP header, or NULL if this is not a TCP packet
255 *
256 * Skipped can be NULL, in which case it will be ignored by the program.
257 *
258 * @author Perry Lorier
259 */
260struct libtrace_tcp *trace_get_tcp_from_ip(struct libtrace_ip *ip,int *skipped);
261
262/** get a pointer to the UDP header (if any)
263 * @param packet        the packet opaque pointer
264 *
265 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
266 */
267struct libtrace_udp *trace_get_udp(struct libtrace_packet_t *packet);
268
269/** get a pointer to the UDP header (if any) given a pointer to the IP header
270 * @param       ip      The IP header
271 * @param[out]  skipped An output variable of the number of bytes skipped
272 *
273 * @returns a pointer to the UDP header, or NULL if this is not an UDP packet
274 *
275 * Skipped may be NULL, in which case it will be ignored by this function.
276 */
277struct libtrace_udp *trace_get_udp_from_ip(struct libtrace_ip *ip,int *skipped);
278
279/** get a pointer to the ICMP header (if any)
280 * @param packet        the packet opaque pointer
281 *
282 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
283 */
284struct libtrace_icmp *trace_get_icmp(struct libtrace_packet_t *packet);
285
286/** get a pointer to the ICMP header (if any) given a pointer to the IP header
287 * @param ip            The IP header
288 * @param[out] skipped  An output variable of the number of bytes skipped
289 *
290 * @returns a pointer to the ICMP header, or NULL if this is not an ICMP packet
291 *
292 * Skipped may be NULL, in which case it will be ignored by this function
293 */
294struct libtrace_icmp *trace_get_icmp_from_ip(struct libtrace_ip *ip,int *skipped);
295
296/** parse an ip or tcp option
297 * @param[in,out] ptr   the pointer to the current option
298 * @param[in,out] len   the length of the remaining buffer
299 * @param[out] type     the type of the option
300 * @param[out] optlen   the length of the option
301 * @param[out] data     the data of the option
302 *
303 * @returns bool true if there is another option (and the fields are filled in)
304 *               or false if this was the last option.
305 *
306 * This updates ptr to point to the next option after this one, and updates
307 * len to be the number of bytes remaining in the options area.  Type is updated
308 * to be the code of this option, and data points to the data of this option,
309 * with optlen saying how many bytes there are.
310 *
311 * @note Beware of fragmented packets.
312 */
313int trace_get_next_option(unsigned char **ptr,int *len,
314                        unsigned char *type,
315                        unsigned char *optlen,
316                        unsigned char **data);
317
318
319/** Get the current time in DAG time format
320 * @param packet        the packet opaque pointer
321 *
322 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
323 * past 1970-01-01, the lower 32bits are partial seconds)
324 * @author Daniel Lawson
325 */
326uint64_t trace_get_erf_timestamp(const struct libtrace_packet_t *packet);
327
328/** Get the current time in struct timeval
329 * @param packet        the packet opaque pointer
330 *
331 * @returns time that this packet was seen in a struct timeval
332 * @author Daniel Lawson
333 * @author Perry Lorier
334 */ 
335struct timeval trace_get_timeval(const struct libtrace_packet_t *packet);
336
337/** Get the current time in floating point seconds
338 * @param packet        the packet opaque pointer
339 *
340 * @returns time that this packet was seen in 64bit floating point seconds
341 * @author Perry Lorier
342 */
343double trace_get_seconds(const struct libtrace_packet_t *packet);
344
345/** Get the size of the packet in the trace
346 * @param packet        the packet opaque pointer
347 * @returns the size of the packet in the trace
348 * @author Perry Lorier
349 * @note Due to this being a header capture, or anonymisation, this may not
350 * be the same size as the original packet.  See get_wire_length() for the original
351 * size of the packet.
352 * @note This can (and often is) different for different packets in a trace!
353 * @par
354 *  This is sometimes called the "snaplen".
355 */
356
357int trace_get_capture_length(const struct libtrace_packet_t *packet);
358
359/** Get the size of the packet as it was seen on the wire.
360 * @param packet        the packet opaque pointer
361 * @returns the size of the packet as it was on the wire.
362 * @author Perry Lorier
363 * @author Daniel Lawson
364 * @note Due to the trace being a header capture, or anonymisation this may
365 * not be the same as the Capture Len.
366 */ 
367
368int trace_get_wire_length(const struct libtrace_packet_t *packet);
369
370/** Link layer types
371 */
372typedef enum { 
373       TRACE_TYPE_LEGACY, 
374       TRACE_TYPE_HDLC_POS, 
375       TRACE_TYPE_ETH,
376       TRACE_TYPE_ATM,
377       TRACE_TYPE_80211,
378     } libtrace_linktype_t;
379
380/** Get the type of the link layer
381 * @param packet        the packet opaque pointer
382 * @returns libtrace_linktype_t
383 * @author Perry Lorier
384 * @author Daniel Lawson
385 */
386
387inline libtrace_linktype_t trace_get_link_type(const struct libtrace_packet_t *packet);
388
389/** Get the destination MAC addres
390 * @param packet        the packet opaque pointer
391 * @returns a pointer to the destination mac, (or NULL if there is no
392 * destination MAC)
393 * @author Perry Lorier
394 */
395uint8_t *trace_get_destination_mac(const struct libtrace_packet_t *packet);
396
397/** Get the source MAC addres
398 * @param packet        the packet opaque pointer
399 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
400 * @author Perry Lorier
401 */
402uint8_t *trace_get_source_mac(const, struct libtrace_packet_t *packet);
403
404/** Truncate the packet at the suggested length
405 * @param packet        the packet opaque pointer
406 * @param len           the new length of the packet
407 * @returns the new length of the packet, or the original length of the
408 * packet if unchanged
409 * @author Daniel Lawson
410 */
411size_t trace_truncate_packet(struct libtrace_packet_t *packet, size_t size);
412
413/** Set the direction flag, if it has one
414 * @param packet        the packet opaque pointer
415 * @param direction     the new direction (0,1,2,3)
416 * @returns a signed value containing the direction flag, or -1 if this is not supported
417 * @author Daniel Lawson
418 */
419int8_t trace_set_direction(struct libtrace_packet_t *packet, int8_t direction);
420
421/** Get the direction flag, if it has one
422 * @param packet        the packet opaque pointer
423 * @returns a signed value containing the direction flag, or -1 if this is not supported
424 * @author Daniel Lawson
425 */
426int8_t trace_get_direction(const struct libtrace_packet_t *packet);
427
428/** Event types */
429typedef enum {
430        TRACE_EVENT_IOWAIT,
431        TRACE_EVENT_SLEEP,
432        TRACE_EVENT_PACKET
433} libtrace_event_t;
434
435/** structure returned by libtrace_event explaining what the current event is */
436struct libtrace_eventobj_t {
437        libtrace_event_t type; /**< event type (iowait,sleep,packet */
438        int fd;                /**< if IOWAIT, the fd to sleep on */
439        double seconds;        /**< if SLEEP, the amount of time to sleep for */
440};
441
442/** process a libtrace event
443 * @param trace the libtrace opaque pointer
444 * @param packet the libtrace_packet opaque pointer
445 * @param fd a pointer to a file descriptor to listen on
446 * @param seconds a pointer the time in seconds since to the next event
447 * @returns libtrace_event struct containing the type, and potential
448 *      fd or seconds to sleep on
449 *
450 * Type can be:
451 *  TRACE_EVENT_IOWAIT  Waiting on I/O on <fd>
452 *  TRACE_EVENT_SLEEP   Next event in <seconds>
453 *  TRACE_EVENT_PACKET  Packet arrived in <buffer> with size <size>
454 */
455struct libtrace_eventobj_t trace_event(struct libtrace_t *trace,
456                struct libtrace_packet_t *packet);
457
458/** setup a BPF filter
459 * @param filterstring a char * containing the bpf filter string
460 * @returns opaque pointer pointer to a libtrace_filter_t object
461 * @author Daniel Lawson
462 */
463struct libtrace_filter_t *trace_bpf_setfilter(const char *filterstring);
464
465/** apply a BPF filter
466 * @param filter        the filter opaque pointer
467 * @param packet        the packet opaque pointer
468 * @returns 0 if the filter fails, 1 if it succeeds
469 * @author Daniel Lawson
470 */
471int trace_bpf_filter(struct libtrace_filter_t *filter,
472                struct libtrace_packet_t *packet);
473
474
475typedef enum {USE_DEST, USE_SOURCE} serverport_t;
476
477/** hint at the server port in specified protocol
478 * @param protocol      the IP layer protocol, eg 6 (tcp), 17 (udp)
479 * @param source        the source port from the packet
480 * @param dest          the destination port from the packet
481 * @returns one of USE_SOURCE or USE_DEST depending on which one you should use
482 * @author Daniel Lawson
483 */
484int8_t trace_get_server_port(uint8_t protocol, uint16_t source, uint16_t dest);
485
486#ifdef __cplusplus
487} // extern "C"
488#endif // #ifdef __cplusplus
489#endif // LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.