doc/README.capture

   1 $Id$
   2
   3 This document is an attempt, to bring some light to the things done, when
   4 packet capturing is performed. There might be things missing, and others
   5 maybe wrong :-( The following will concentrate a bit on the win32 gtk
   6 port of ethereal.
   7
   8
   9 XXX: when ongoing file reorganisation will be completed, the following
  10 two lists maybe won't be needed any longer!
  11
  12 libpcap related source files:
  13 -----------------------------
  14 capture-pcap-util.c
  15 capture-pcap-util.h
  16 capture-pcap-util-int.h
  17 capture-pcap-util-unix.c
  18 capture-wpcap.c
  19 capture-wpcap.h
  20 capture_wpcap_packet.c
  21 capture_wpcap_packet.h
  22
  23 Capture related source files:
  24 -----------------------------
  25 capture.c
  26 capture.h
  27 capture_loop.c
  28 capture_loop.h
  29 capture_opts.c
  30 capture-stop-conditions.c
  31 capture-stop-conditions.h
  32 capture_sync.c
  33 capture_ui_utils.c
  34 capture_ui_utils.h
  35 conditions.c (XXX: is conditions generic or capture specific?)
  36 conditions.h
  37
  38
  39 Capture driver
  40 --------------
  41 Etheral doesn't have direct access to the capture hardware. Instead of this,
  42 it uses the Libpcap/Winpcap library to capture data from network cards.
  43
  44 On Win32, in capture-wpcap.c the function g_module_open("wpcap") is called
  45 to load the wpcap.dll. This dll includes all functions needed for
  46 packet capturing.
  47
  48
  49
  50 Capture File
  51 ------------
  52 There are some kinds of targets to put the capture data into:
  53
  54 -temporary file
  55 -user specified "single" capture file
  56 -user specified "ringbuffer" capture file
  57
  58 Which kind of file is used depends on the user settings. In principle there
  59 is no difference in handling these files, so if not otherwise notified,
  60 it will be called the capture file.
  61
  62 The capture file is stored, using the wiretap library.
  63
  64
  65 Overview
  66 --------
  67 Capturing is done using a two task model: the currently running (parent)
  68 process will spawn a child process to do the real capture work, namely
  69 controlling libpcap. This two task model is used because it's necessary
  70 to split the capturing process (which should avoid packet drop) from the parent
  71 process which might need significant time to display the data.
  72
  73 When a capture is started, the parent builds a "command line" and creates a
  74 new child process with it. A pipe from the child to the parent is created
  75 which is used to transfer control messages.
  76
  77 The child will init libpcap and send the parent a "new capture file is used"
  78 control message through the pipe.
  79
  80 The child cyclically takes the packet data from libpcap and saves it to disk.
  81 From time to time it will send the parent a "new packets" control message.
  82
  83 If the parent process receives this "new packets" message and the option
  84 "Update list of packets in real time" is used, it will read the packet data
  85 from the file, dissect and display it.
  86
  87
  88 If the user wants to stop the capture, this can be done in two ways: by
  89 menu/toolbar of the parent process or the Stop button of the child processes
  90 dialog box (which obviously cannot be used it this dialog is hidden).
  91
  92 The Stop button will stop the capture itself, close the control pipe and then
  93 closes itself. The parent will detect this and stop it's part of the capture.
  94
  95 If the menu/toolbar is used, the parent will send a break signal to the child
  96 which will lead to the same sequence as described above.
  97
  98 Win32 only: as the windows implementation of signals simply doesn't work,
  99 another pipe from the parent to the child is used to send a "close capture"
 100 message instead of a signal.
 101
 102
 103 Start capture
 104 -------------
 105 A capture is started, by specifying to start the capture at the command line,
 106 trigger the Ok button in the "Capture Options" dialog box and some more. The
 107 capture start is actually done by calling the capture_start() function in
 108 capture.c.
 109
 110
 111 Capture child (Loop)
 112 --------------------
 113 The capture child will open the target capture file, prepare pcap things,
 114 init stop conditions, init the capture statistic dialog (if not hidden) and
 115 start a loop which is running until the flag ld.go is FALSE.
 116
 117 Inside this loop,
 118
 119 -gtk main things are updated
 120 -pcap_dispatch(capture_pcap_cb) is called
 121 -the capture stop conditions are checked (ld.go is set to FALSE to finish)
 122 -update the capture statistic dialog (if not hidden)
 123
 124 While this loop is running, the pcap_dispatch() will call capture_pcap_cb()
 125 for every packet captured. Inside this, the packet data is converted into
 126 wtap (wiretap) format and saved to file. Beside saving, it is trying to
 127 do some basic dissecting (for the statistic window), by calling the
 128 appropriate capture_xxx function.
 129
 130 When the user triggered a capture stop or one of the capture stop conditions
 131 matched, the ld.go flag is set to FALSE, and the loop will stop shortly after.
 132
 133
 134 Capture parent
 135 --------------
 136 In the capture parent the cap_pipe_input_cb() function is called "cyclically"
 137 (unix:waiting for pipe, win32:timer,1000ms) to read data from the pipe and show it
 138 on the main screen. While the capture is in progress, no other capture file
 139 can be opened.
 140
 141
 142 Updating
 143 --------
 144 The actual packet capturing inside the libpcap is done using it's own task.
 145 Catching and processing the packet data from the libpcap is done using the
 146 pcap_dispatch() function.