source: lib/libtrace.h @ a79ddbe

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivegetfragoffhelplibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since a79ddbe was a79ddbe, checked in by Daniel Lawson <dlawson@…>, 17 years ago

added license information

  • Property mode set to 100644
File size: 13.1 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/** @file
34 *
35 * @brief Trace file processing library header
36 *
37 * @author Daniel Lawson
38 * @author Perry Lorier
39 *
40 * @version $Id$
41 *
42 * This library provides a per packet interface into a trace file, or a live
43 * captures.  It supports ERF, DAG cards, WAG cards, WAG's event format,
44 * pcap etc.
45 *
46 * @par Usage
47 * <ol>
48 * <li> include "libtrace.h" (found in /usr/local/wand/include
49 * on voodoo and chasm).
50 * <li> call create_trace with the uri of the trace you're interested in.<br>
51 * This is usually passed in as argv[1] to your program.
52 * <li> call libtrace_read_packet(), passing in the libtrace_t returned from
53 * create trace and a buffer (and the buffer length)
54 * <li> call getIP() on the buffer, and do whatever you need
55 * <li> loop back to step 3, until libtrace_read_packet() returns -1
56 * </ol>
57 * @par Linking
58 * To use this library you need to link against -ltrace, -lpcapl and -lzl
59 * which are the versions of these libraries that support >2G files.  (grr!)
60 * These can be found in /usr/local/wand/lib on voodoo and chasm.
61 *
62 *
63 */
64
65#define COLLECTOR_PORT 3435
66
67/** Opaque structure holding information about a trace */
68struct libtrace_t;
69       
70/** Opaque structure holding information about a bpf filter */
71
72struct libtrace_filter_t;
73/** Structure for dealing with IP packets */
74struct libtrace_ip
75  {
76#if __BYTE_ORDER == __LITTLE_ENDIAN
77    unsigned int ip_hl:4;               /**< header length */
78    unsigned int ip_v:4;                /**< version */
79#endif
80#if __BYTE_ORDER == __BIG_ENDIAN
81    unsigned int ip_v:4;                /**< version */
82    unsigned int ip_hl:4;               /**< header length */
83#endif
84    u_int8_t ip_tos;                    /**< type of service */
85    u_short ip_len;                     /**< total length */
86    u_short ip_id;                      /**< identification */
87    u_short ip_off;                     /**< fragment offset field */
88#define IP_RF 0x8000                    /**< reserved fragment flag */
89#define IP_DF 0x4000                    /**< dont fragment flag */
90#define IP_MF 0x2000                    /**< more fragments flag */
91#define IP_OFFMASK 0x1fff               /**< mask for fragmenting bits */
92    u_int8_t ip_ttl;                    /**< time to live */
93    u_int8_t ip_p;                      /**< protocol */
94    u_short ip_sum;                     /**< checksum */
95    struct in_addr ip_src, ip_dst;      /**< source and dest address */
96  };
97
98/** Structure for dealing with TCP packets */
99struct libtrace_tcp
100  {
101    u_int16_t source;           /**< Source Port */
102    u_int16_t dest;             /**< Destination port */
103    u_int32_t seq;              /**< Sequence number */
104    u_int32_t ack_seq;          /**< Acknowledgement Number */
105#  if __BYTE_ORDER == __LITTLE_ENDIAN
106    u_int16_t res1:4;           /**< Reserved bits */
107    u_int16_t doff:4;           
108    u_int16_t fin:1;            /**< FIN */
109    u_int16_t syn:1;            /**< SYN flag */
110    u_int16_t rst:1;            /**< RST flag */
111    u_int16_t psh:1;            /**< PuSH flag */
112    u_int16_t ack:1;            /**< ACK flag */
113    u_int16_t urg:1;            /**< URG flag */
114    u_int16_t res2:2;           /**< Reserved */
115#  elif __BYTE_ORDER == __BIG_ENDIAN
116    u_int16_t doff:4;           
117    u_int16_t res1:4;
118    u_int16_t res2:2;
119    u_int16_t urg:1;
120    u_int16_t ack:1;
121    u_int16_t psh:1;
122    u_int16_t rst:1;
123    u_int16_t syn:1;
124    u_int16_t fin:1;
125#  else
126#   error "Adjust your <bits/endian.h> defines"
127#  endif
128    u_int16_t window;           /**< Window Size */
129    u_int16_t check;            /**< Checksum */
130    u_int16_t urg_ptr;          /**< Urgent Pointer */
131};
132
133/** UDP Header for dealing with UDP packets */
134struct libtrace_udp {
135  u_int16_t     source;         /**< Source port */
136  u_int16_t     dest;           /**< Destination port */
137  u_int16_t     len;            /**< Length */
138  u_int16_t     check;          /**< Checksum */
139};
140
141/** ICMP Header for dealing with icmp packets */
142struct libtrace_icmp
143{
144  u_int8_t type;                /* message type */
145  u_int8_t code;                /* type sub-code */
146  u_int16_t checksum;
147  union
148  {
149    struct
150    {
151      u_int16_t id;
152      u_int16_t sequence;
153    } echo;                     /* echo datagram */
154    u_int32_t   gateway;        /* gateway address */
155    struct
156    {
157      u_int16_t __unused;
158      u_int16_t mtu;
159    } frag;                     /* path mtu discovery */
160  } un;
161};
162
163
164
165
166/** Create a trace file from a URI
167 *
168 * @returns opaque pointer to a libtrace_t
169 *
170 * Valid URI's are:
171 *  - erf:/path/to/erf/file
172 *  - erf:/path/to/erf/file.gz
173 *  - erf:/path/to/rtclient/socket
174 *  - erf:-  (stdin)
175 *  - dag:/dev/dagcard                  (implementd?)
176 *  - pcap:pcapinterface                (eg: pcap:eth0)
177 *  - pcap:/path/to/pcap/file
178 *  - pcap:/path/to/pcap/file.gz
179 *  - pcap:/path/to/pcap/socket         (implemented?)
180 *  - pcap:-
181 *  - rtclient:hostname
182 *  - rtclient:hostname:port
183 *  - wag:/path/to/wag/file
184 *  - wag:/path/to/wag/file.gz
185 *  - wag:/path/to/wag/socket
186 *  - wag:/dev/device
187 *
188 *  If an error occured why attempting to open the trace file, NULL is returned
189 *  and an error is output to stdout.
190 */
191struct libtrace_t *create_trace(char *uri);
192
193/** Close a trace file, freeing up any resources it may have been using
194 *
195 */
196void destroy_trace(struct libtrace_t *rtclient);
197
198/** Read one packet from the trace into buffer
199 *
200 * @param libtrace      the trace to read from
201 * @param buffer        the buffer to read into
202 * @param len           the length of the buffer
203 * @param status        status of the trace (only used for RTClients)
204 * @returns number of bytes copied, -1 on error, or 0 at EOF
205 *
206 * @note the buffer must be at least as large as the largest packet (plus
207 * link layer, and trace packet metadata overhead)
208 */
209int libtrace_read_packet(struct libtrace_t *rtclient, void *buffer, size_t len, int *status);
210
211/** get a pointer to the link layer
212 * @param libtrace      a pointer to the trace object returned from gettrace
213 * @param buffer        a pointer to a filled in buffer
214 * @param buflen        a pointer to the size of the buffer
215 *
216 * @returns a pointer to the link layer, or NULL if there is no link layer
217 *
218 * @note you should call getLinkType() to find out what type of link layer
219 * this is
220 */
221void *get_link(struct libtrace_t *libtrace, void *buffer, int buflen);
222
223/** get a pointer to the IP header (if any)
224 * @param libtrace      a pointer to the trace object returned from gettrace
225 * @param buffer        a pointer to a filled in buffer
226 * @param buflen        a pointer to the size of the buffer
227 *
228 * @returns a pointer to the IP header, or NULL if there is not an IP packet
229 */
230struct libtrace_ip *get_ip(struct libtrace_t *libtrace, void *buffer, int buflen);
231
232/** get a pointer to the TCP header (if any)
233 * @param libtrace      a pointer to the trace object returned from gettrace
234 * @param buffer        a pointer to a filled in buffer
235 * @param buflen        a pointer to the size of the buffer
236 *
237 * @returns a pointer to the TCP header, or NULL if there is not a TCP packet
238 */
239struct libtrace_tcp *get_tcp(struct libtrace_t *libtrace, void *buffer, int buflen);
240
241/** get a pointer to the UDP header (if any)
242 * @param libtrace      a pointer to the trace object returned from gettrace
243 * @param buffer        a pointer to a filled in buffer
244 * @param buflen        a pointer to the size of the buffer
245 *
246 * @returns a pointer to the UDP header, or NULL if this is not a UDP packet
247 */
248struct libtrace_udp *get_udp(struct libtrace_t *libtrace, void *buffer, int buflen);
249
250/** get a pointer to the ICMP header (if any)
251 * @param libtrace      a pointer to the trace object returned from gettrace
252 * @param buffer        a pointer to a filled in buffer
253 * @param buflen        a pointer to the size of the buffer
254 *
255 * @returns a pointer to the ICMP header, or NULL if this is not a ICMP packet
256 */
257struct libtrace_icmp *get_icmp(struct libtrace_t *libtrace, void *buffer, int buflen);
258
259/** Get the current time in DAG time format
260 * @param libtrace the libtrace opaque pointer
261 * @param buffer a pointer to a filled in buffer
262 * @param buflen the length of the buffer
263 * @returns a 64 bit timestamp in DAG ERF format (upper 32 bits are the seconds
264 * past 1970-01-01, the lower 32bits are partial seconds)
265 * @author Daniel Lawson
266 */
267uint64_t get_erf_timestamp(struct libtrace_t *libtrace, void *buffer, int buflen);
268
269/** Get the current time in struct timeval
270 * @param libtrace the libtrace opaque pointer
271 * @param buffer a pointer to a filled in buffer
272 * @param buflen the length of the buffer
273 * @returns time that this packet was seen in a struct timeval
274 * @author Daniel Lawson
275 * @author Perry Lorier
276 */ 
277
278struct timeval get_timeval(struct libtrace_t *libtrace, void *buffer, int buflen);
279
280/** Get the current time in floating point seconds
281 * @param libtrace the libtrace opaque pointer
282 * @param buffer a pointer to a filled in buffer
283 * @param buflen the length of the buffer
284 * @returns time that this packet was seen in 64bit floating point seconds
285 * @author Perry Lorier
286 */
287double get_seconds(struct libtrace_t *libtrace, void *buffer, int buflen);
288
289/** Get the size of the packet in the trace
290 * @param libtrace the libtrace opaque pointer
291 * @param buffer a pointer to a filled in buffer
292 * @param buflen the length of the buffer
293 * @returns the size of the packet in the trace
294 * @author Perry Lorier
295 * @note Due to this being a header capture, or anonymisation, this may not
296 * be the same size as the original packet.  See get_wire_length() for the original
297 * size of the packet.
298 * @note This can (and often is) different for different packets in a trace!
299 * @par
300 *  This is sometimes called the "snaplen".
301 */
302
303int get_capture_length(struct libtrace_t *libtrace, void *buffer, int buflen);
304
305/** Get the size of the packet as it was seen on the wire.
306 * @param libtrace the libtrace opaque pointer
307 * @param buffer a pointer to a filled in buffer
308 * @param buflen the length of the buffer
309 * @returns the size of the packet as it was on the wire.
310 * @author Perry Lorier
311 * @author Daniel Lawson
312 * @note Due to the trace being a header capture, or anonymisation this may
313 * not be the same as the Capture Len.
314 */ 
315
316int get_wire_length(struct libtrace_t *libtrace, void *buffer, int buflen);
317
318/** Link layer types
319 */
320typedef enum { 
321       TRACE_TYPE_LEGACY, 
322       TRACE_TYPE_HDLC_POS, 
323       TRACE_TYPE_ETH,
324       TRACE_TYPE_ATM,
325       TRACE_TYPE_80211,
326     } libtrace_linktype_t;
327
328/** Get the type of the link layer
329 * @param libtrace the libtrace opaque pointer
330 * @param buffer a pointer to a filled in buffer
331 * @param buflen the length of the buffer
332 * @returns libtrace_linktype_t
333 * @author Perry Lorier
334 * @author Daniel Lawson
335 */
336
337inline libtrace_linktype_t get_link_type(
338                struct libtrace_t *libtrace,
339                void *buffer,
340                int buflen);   
341
342/** Get the destination MAC addres
343 * @param libtrace the libtrace opaque pointer
344 * @param buffer a pointer to a filled in buffer
345 * @param buflen the length of the buffer
346 * @returns a pointer to the destination mac, (or NULL if there is no
347 * destination MAC)
348 * @author Perry Lorier
349 */
350uint8_t *get_destination_mac(struct libtrace_t *libtrace,
351                        void *buffer,
352                        int buflen);
353
354/** Get the source MAC addres
355 * @param libtrace the libtrace opaque pointer
356 * @param buffer a pointer to a filled in buffer
357 * @param buflen the length of the buffer
358 * @returns a pointer to the source mac, (or NULL if there is no source MAC)
359 * @author Perry Lorier
360 */
361uint8_t *get_source_mac(struct libtrace_t *libtrace,
362                        void *buffer,
363                        int buflen);
364
365/** Event types */
366typedef enum {
367        TRACE_EVENT_IOWAIT,
368        TRACE_EVENT_SLEEP,
369        TRACE_EVENT_PACKET
370} libtrace_event_t;
371
372/** process a libtrace event
373 * @returns
374 *  TRACE_EVENT_IOWAIT  Waiting on I/O on <fd>
375 *  TRACE_EVENT_SLEEP   Next event in <seconds>
376 *  TRACE_EVENT_PACKET  Packet arrived in <buffer> with size <size>
377 */
378libtrace_event_t libtrace_event(struct libtrace_t *trace,
379                        int *fd,double *seconds,
380                        void *buffer, int *size);
381
382/** setup a BPF filter
383 * @param filterstring a char * containing the bpf filter string
384 * @returns opaque pointer pointer to a libtrace_filter_t object
385 * @author Daniel Lawson
386 */
387struct libtrace_filter_t *libtrace_bpf_setfilter(const char *filterstring);
388
389/** apply a BPF filter
390 * @param libtrace the libtrace opaque pointer
391 * @param filter the filter opaque pointer
392 * @param buffer a pointer to a filled buffer
393 * @param buflen the length of the buffer
394 * @returns the return value from bpf_filter
395 * @author Daniel Lawson
396 */
397int libtrace_bpf_filter(struct libtrace_t *trace,
398                        struct libtrace_filter_t *filter,
399                        void *buffer, 
400                        int buflen);
401
402
403#endif // _LIBTRACE_H_
Note: See TracBrowser for help on using the repository browser.