JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 1 | <HTML><HEAD> |
| 2 | <STYLE type="text/css"> |
| 3 | <!-- |
| 4 | A { text-decoration:none } |
| 5 | --> |
| 6 | </STYLE> |
| 7 | </HEAD> |
| 8 | <BODY> |
| 9 | |
| 10 | <TABLE WIDTH=100%><TR> |
| 11 | <TD ALIGN=LEFT VALIGN=TOP> |
| 12 | <FONT SIZE=+0 FACE="COURIER"><B>A "Distributed Pcap" for<BR>Remote Monitoring LANs & WANs</B><BR> |
| 13 | (Design Notes for the SITA ACN device)</FONT> |
| 14 | </TD> |
| 15 | <TD ALIGN=RIGHT VALIGN=TOP> |
| 16 | Fulko Hew<BR>SITA INC Canada, Inc.<BR>Revised: October 2, 2007 |
| 17 | </TD> |
| 18 | </TR></TABLE> |
| 19 | |
| 20 | |
| 21 | <H3>SUMMARY</H3> |
| 22 | <UL> |
| 23 | <STRONG>Note:</STRONG> This document is part of the libpcap Git and was derived from 'pcap.3' (circa Aug/07). |
| 24 | <P> |
| 25 | The ACN provides a customized/distributed version of this library that alows SMPs to |
| 26 | interact with the various IOPs within the site providing a standard mechanism |
| 27 | to capture LAN and WAN message traffic. |
| 28 | <P> |
| 29 | <CENTER> |
| 30 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3 WIDTH=75%> |
| 31 | <TR> |
| 32 | <TH VALIGN=TOP>SMP</TH> |
| 33 | <TD VALIGN=TOP>The Supervisory Management Processor where Wireshark (or equivalent) |
| 34 | runs in conjuction with a libpcap front-end.</TD> |
| 35 | </TR> |
| 36 | <TR> |
| 37 | <TH VALIGN=TOP>IOP</TH> |
| 38 | <TD VALIGN=TOP>I/O Processors where the monitored ports exist in conjunction |
| 39 | with a custom device driver/libpcap back-end.</TD> |
| 40 | </TR> |
| 41 | </TABLE> |
| 42 | </CENTER> |
| 43 | <P> |
| 44 | Each IOP will be capable of supporting multiple connections from an SMP |
| 45 | enabling monitoring of more than one interface at a time, each through |
| 46 | its own seperate connection. The IOP is responsible to ensure and report |
| 47 | an error if any attempt is made to monitor the same interface more than once. |
| 48 | <P> |
| 49 | There are three applications that will be supported by the ACN version of libpcap. |
| 50 | They each use a slightly different mode for looping/capturing and termination |
| 51 | as summarized in the following table: |
| 52 | <P> |
| 53 | <CENTER> |
| 54 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 55 | <TR><TH>Application</TH> <TH>Capture</TH> <TH>Termination</TH></TR> |
| 56 | <TR><TH VALIGN=TOP NOWRAP>wireshark</TH> |
| 57 | <TD VALIGN=TOP>pcap_dispatch(all packets in one buffer of capture only)</TD> |
| 58 | <TD VALIGN=TOP>pcap_breakloop()</TD> |
| 59 | </TR> |
| 60 | <TR><TH VALIGN=TOP NOWRAP>tshark</TH> |
| 61 | <TD VALIGN=TOP>pcap_dispatch(one buffer of capture only)</TD> |
| 62 | <TD VALIGN=TOP>Since a CTRL-C was used to terminate the application, pcap_breakloop() is never called.</TD> |
| 63 | </TR> |
| 64 | <TR><TH VALIGN=TOP NOWRAP>tcpdump</TH> |
| 65 | <TD VALIGN=TOP>pcap_loop(all packets in the next buffer, and loop forever)</TD> |
| 66 | <TD VALIGN=TOP>pcap_breakloop()</TD> |
| 67 | </TR> |
| 68 | </TABLE> |
| 69 | </CENTER> |
| 70 | <P> |
| 71 | <B>Note: </B>In all cases, the termination of capturing is always (apparently) followed by |
| 72 | pcap_close(). Pcap_breakloop() is only used to stop/suspend looping/processing, |
| 73 | and upon close interpretation of the function definitions, it is possible to resume |
| 74 | capturing following a pcap_breakloop() without any re-initialization. |
| 75 | <P> |
| 76 | <H4>ACN Limitations</H4> |
| 77 | <OL> |
| 78 | <LI>Monitoring of backup IOPs is not currently supported. |
| 79 | <LI>Ethernet interfaces cannot be monitored in promiscuous mode. |
| 80 | </OL> |
| 81 | |
| 82 | </UL> |
| 83 | |
| 84 | <H3>ROUTINES</H3> |
| 85 | <UL> |
| 86 | The following list of functions is the sub-set of Pcap functions that have been |
| 87 | altered/enhanced to support the ACN remote monitoring facility. The remainder of the Pcap |
| 88 | functions continue to perform their duties un-altered. Libpcap only supports this |
| 89 | mode of operation if it has been configured/compiled for SITA/ACN support. |
| 90 | <P> |
| 91 | <UL><FONT FACE=COURIER> |
| 92 | pcap_findalldevs<BR> |
| 93 | pcap_freealldevs<BR> |
| 94 | pcap_open_live<BR> |
| 95 | pcap_close<BR> |
| 96 | pcap_setfilter<BR> |
| 97 | pcap_dispatch<BR> |
| 98 | pcap_loop<BR> |
| 99 | pcap_next<BR> |
| 100 | pcap_next_ex<BR> |
| 101 | pcap_stats<BR> |
| 102 | </FONT></UL> |
| 103 | |
| 104 | These subroutines have been modified for the ACN specific distributed and remote monitoring |
| 105 | ability perform the following basic functions. More detail is provided in the |
| 106 | "SMP/IOP Inter-Process Communication Protocol" section. |
| 107 | <P> |
| 108 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 109 | <TR> |
| 110 | <TD VALIGN=TOP ROWSPAN=2><B>pcap_open_live()</B></TD> |
| 111 | <TD VALIGN=TOP>Used to obtain a packet capture descriptor to look at packets on the network.</TD> |
| 112 | </TR> |
| 113 | <TR><TD><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH=100%> |
| 114 | <TR><TH VALIGN=TOP NOWRAP>SMP -> IOP</TH> |
| 115 | <TD> |
| 116 | The SMP will open a connection to the selected IOP on its 'sniffer' port |
| 117 | to ensure it is available. It sends a null terminated string identifying |
| 118 | the interface to be monitored. |
| 119 | </TD> |
| 120 | </TR> |
| 121 | <TR><TH VALIGN=TOP NOWRAP>IOP -> SMP</TH> |
| 122 | <TD> |
| 123 | After any required processing is complete, the IOP will return a |
| 124 | null terminated string containing an error message if one occured. |
| 125 | If no error occured, a empty string is still returned. |
| 126 | Errors are: |
| 127 | <UL> |
| 128 | <LI>"Interface (xxx) does not exist." |
| 129 | <LI>"Interface (xxx) not configured." |
| 130 | <LI>"Interface (xxx) already being monitored." |
| 131 | </UL> |
| 132 | </TD> |
| 133 | </TR> |
| 134 | </TABLE></TD></TR> |
| 135 | |
| 136 | <TR> |
| 137 | <TD VALIGN=TOP ROWSPAN=2><B>pcap_findalldevs()</B></TD> |
| 138 | <TD VALIGN=TOP>It constructs a list of network devices that can be opened with pcap_open_live().</TD> |
| 139 | </TR> |
| 140 | <TR><TD><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH=100%> |
| 141 | <TR><TH VALIGN=TOP NOWRAP>SMP</TH> |
| 142 | <TD> |
| 143 | It obtains a list of IOPs currently available (via /etc/hosts). |
| 144 | </TD> |
| 145 | </TR> |
| 146 | <TR><TH VALIGN=TOP NOWRAP>SMP -> IOP</TH> |
| 147 | <TD> |
| 148 | The SMP will sequentially open a connection to each IOP on its 'sniffer' port to ensure |
| 149 | the IOP is available. |
| 150 | It sends a null terminated empty interface ID followed by the query request command. |
| 151 | </TD> |
| 152 | </TR> |
| 153 | <TR><TH VALIGN=TOP NOWRAP>IOP -> SMP</TH> |
| 154 | <TD>The IOP returns an error response and its list of devices. |
| 155 | </TD> |
| 156 | </TR> |
| 157 | <TR><TH VALIGN=TOP NOWRAP>SMP -> IOP</TH> |
| 158 | <TD> |
| 159 | The SMP closes the TCP connection with each IOP. |
| 160 | </TD> |
| 161 | </TR> |
| 162 | <TR><TH VALIGN=TOP NOWRAP>SMP</TH> |
| 163 | <TD> |
| 164 | The SMP adds the received information to its internal structure. |
| 165 | </TD> |
| 166 | </TR> |
| 167 | </TABLE></TD></TR> |
| 168 | |
| 169 | <TR> |
| 170 | <TD VALIGN=TOP ROWSPAN=2><B>pcap_freealldevs()</B></TD> |
| 171 | <TD VALIGN=TOP>Used to free a list allocated by pcap_findalldevs().</TD> |
| 172 | </TR> |
| 173 | <TR><TD><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH=100%> |
| 174 | <TR><TH VALIGN=TOP NOWRAP>SMP</TH> |
| 175 | <TD> |
| 176 | The SMP frees the structure it built as a result of the previous |
| 177 | invocation of pcap_findalldevs(). |
| 178 | </TD> |
| 179 | </TR> |
| 180 | </TABLE></TD></TR> |
| 181 | |
| 182 | <TR> |
| 183 | <TD VALIGN=TOP ROWSPAN=2><B>pcap_dispatch()</B></TD> |
| 184 | <TD VALIGN=TOP>Used to collect and process packets.</TD> |
| 185 | </TR> |
| 186 | <TR><TD><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH=100%> |
| 187 | <TR><TH VALIGN=TOP NOWRAP>SMP -> IOP</TH> |
| 188 | <TD> |
| 189 | On the first invocation of pcap_dispatch(), pcap_loop(), or pcap_next(), or pcap_next_ex() following a pcap_open_live(), |
| 190 | the SMP will pass down the monitor start command and various parameters the IOP should use. |
| 191 | </TD> |
| 192 | </TR> |
| 193 | <TR><TH VALIGN=TOP NOWRAP>IOP -> SMP</TH> |
| 194 | <TD> |
| 195 | The IOP now sends a stream of captured data. |
| 196 | </TD> |
| 197 | </TR> |
| 198 | <TR><TH VALIGN=TOP NOWRAP>SMP</TH> |
| 199 | <TD> |
| 200 | The SMP will read the reverse channel of the connection between the SMP and the |
| 201 | IOP that provides the captured data (via 'p->read_op' which is 'pcap_read_linux()' |
| 202 | until the select() call returns a 'no more data' indication. |
| 203 | It will the process (at most) the next 'cnt' packets and invoke the specified |
| 204 | callback function for each packet processed. |
| 205 | </TD> |
| 206 | </TR> |
| 207 | <TR><TH VALIGN=TOP NOWRAP>IOP</TH> |
| 208 | <TD> |
| 209 | The IOP continues to listen for additional commands as well as capturing and forwarding data to the SMP. |
| 210 | </TD> |
| 211 | </TR> |
| 212 | </TABLE></TD></TR> |
| 213 | |
| 214 | <TR> |
| 215 | <TD VALIGN=TOP ROWSPAN=2><B>pcap_loop()</B></TD> |
| 216 | <TD VALIGN=TOP> |
| 217 | Is similar to pcap_dispatch() except it keeps reading packets until |
| 218 | the requested number of packets are processed or an error occurs. |
| 219 | </TD> |
| 220 | </TR> |
| 221 | <TR><TD><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH=100%> |
| 222 | <TR><TH VALIGN=TOP NOWRAP>SMP -> IOP</TH> |
| 223 | <TD> |
| 224 | On the first invocation of pcap_dispatch(), pcap_loop(), or pcap_next(), or pcap_next_ex() following a pcap_open_live(), |
| 225 | the SMP will pass down the monitor start command and various parameters the IOP should use. |
| 226 | </TD> |
| 227 | </TR> |
| 228 | <TR><TH VALIGN=TOP NOWRAP>IOP -> SMP</TH> |
| 229 | <TD> |
| 230 | The IOP now sends a stream of captured data. |
| 231 | </TD> |
| 232 | </TR> |
| 233 | <TR><TH VALIGN=TOP NOWRAP>SMP</TH> |
| 234 | <TD> |
| 235 | The SMP continuously reads the next packet from the reverse channel of the connection |
| 236 | between the SMP and the IOP that provides the captured data (via 'p->read_op' |
| 237 | which is 'pcap_read_linux()' until 'cnt' packets have been received. |
| 238 | The specified callback function will be invoked for each packet received. |
| 239 | </TD> |
| 240 | </TR> |
| 241 | <TR><TH VALIGN=TOP NOWRAP>IOP</TH> |
| 242 | <TD> |
| 243 | The IOP continues to listen for additional commands as well as capturing and forwarding data to the SMP. |
| 244 | </TD> |
| 245 | </TR> |
| 246 | </TABLE></TD></TR> |
| 247 | |
| 248 | <TR> |
| 249 | <TD VALIGN=TOP ROWSPAN=2><B>pcap_next()</B></TD> |
| 250 | <TD VALIGN=TOP> |
| 251 | It reads the next packet (by calling pcap_dispatch() with a count of 1) |
| 252 | and returns a pointer to the data in that packet. |
| 253 | </TD> |
| 254 | </TR> |
| 255 | <TR><TD><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH=100%> |
| 256 | <TR><TH VALIGN=TOP NOWRAP>SMP -> IOP</TH> |
| 257 | <TD> |
| 258 | On the first invocation of pcap_dispatch(), pcap_loop(), or pcap_next(), or pcap_next_ex() following a pcap_open_live(), |
| 259 | the SMP will pass down the monitor start command and various parameters the IOP should use. |
| 260 | </TD> |
| 261 | </TR> |
| 262 | <TR><TH VALIGN=TOP NOWRAP>IOP -> SMP</TH> |
| 263 | <TD> |
| 264 | The IOP now sends a stream of captured data. |
| 265 | </TD> |
| 266 | </TR> |
| 267 | <TR><TH VALIGN=TOP NOWRAP>SMP</TH> |
| 268 | <TD> |
| 269 | The SMP reads only the next packet from the reverse channel of the connection |
| 270 | between the SMP and the IOP that provides the captured data (via calling pcap_dispatch() |
| 271 | with a count of 1) and returns a pointer to that data by invoking an internal callback. |
| 272 | </TD> |
| 273 | </TR> |
| 274 | <TR><TH VALIGN=TOP NOWRAP>IOP</TH> |
| 275 | <TD> |
| 276 | The IOP continues to listen for additional commands as well as capturing and forwarding data to the SMP. |
| 277 | </TD> |
| 278 | </TR> |
| 279 | </TABLE></TD></TR> |
| 280 | |
| 281 | <TR> |
| 282 | <TD VALIGN=TOP ROWSPAN=2><B>pcap_next_ex()</B></TD> |
| 283 | <TD VALIGN=TOP>Reads the next packet and returns a success/failure indication.</TD> |
| 284 | </TR> |
| 285 | <TR><TD><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH=100%> |
| 286 | <TR><TH VALIGN=TOP NOWRAP>SMP -> IOP</TH> |
| 287 | <TD> |
| 288 | On the first invocation of pcap_dispatch(), pcap_loop(), or pcap_next(), or pcap_next_ex() following a pcap_open_live(), |
| 289 | the SMP will pass down the monitor start command and various parameters the IOP should use. |
| 290 | </TD> |
| 291 | </TR> |
| 292 | <TR><TH VALIGN=TOP NOWRAP>IOP -> SMP</TH> |
| 293 | <TD> |
| 294 | The IOP now sends a stream of captured data. |
| 295 | </TD> |
| 296 | </TR> |
| 297 | <TR><TH VALIGN=TOP NOWRAP>SMP</TH> |
| 298 | <TD> |
| 299 | The SMP reads only the next packet from the reverse channel of the connection |
| 300 | between the SMP and the IOP that provides the captured data (via calling pcap_dispatch() |
| 301 | with a count of 1) and returns seperate pointers to both the |
| 302 | packet header and packet data by invoking an internal callback. |
| 303 | </TD> |
| 304 | </TR> |
| 305 | <TR><TH VALIGN=TOP NOWRAP>IOP</TH> |
| 306 | <TD> |
| 307 | The IOP continues to listen for additional commands as well as capturing and forwarding data to the SMP. |
| 308 | </TD> |
| 309 | </TR> |
| 310 | </TABLE></TD></TR> |
| 311 | |
| 312 | <TR> |
| 313 | <TD VALIGN=TOP ROWSPAN=2><B>pcap_setfilter()</B></TD> |
| 314 | <TD VALIGN=TOP>Used to specify a filter program.</TD> |
| 315 | </TR> |
| 316 | <TR><TD><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH=100%> |
| 317 | <TR><TH VALIGN=TOP NOWRAP>SMP -> IOP</TH> |
| 318 | <TD> |
| 319 | The SMP sends a 'set filter' command followed by the BPF commands. |
| 320 | </TD> |
| 321 | </TR> |
| 322 | <TR><TH VALIGN=TOP NOWRAP>IOP -> SMP</TH> |
| 323 | <TD> |
| 324 | The IOP returns a null terminated error string if it failed to accept the filter. |
| 325 | If no error occured, then a NULL terminated empty string is returned instead. |
| 326 | Errors are: |
| 327 | <UL> |
| 328 | <LI>"Invalid BPF." |
| 329 | <LI>"Insufficient resources for BPF." |
| 330 | </UL> |
| 331 | </TD> |
| 332 | </TR> |
| 333 | </TABLE></TD></TR> |
| 334 | |
| 335 | <TR> |
| 336 | <TD VALIGN=TOP ROWSPAN=2><B>pcap_stats()</B></TD> |
| 337 | <TD VALIGN=TOP>Fills in a pcap_stat struct with packet statistics.</TD> |
| 338 | </TR> |
| 339 | <TR><TD><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH=100%> |
| 340 | <TR><TH VALIGN=TOP NOWRAP>SMP -> IOP</TH> |
| 341 | <TD> |
| 342 | The SMP sends a message to the IOP requesting its statistics. |
| 343 | </TD> |
| 344 | </TR> |
| 345 | <TR><TH VALIGN=TOP NOWRAP>IOP -> SMP</TH> |
| 346 | <TD> |
| 347 | The IOP returns the statistics. |
| 348 | </TD> |
| 349 | </TR> |
| 350 | <TR><TH VALIGN=TOP NOWRAP>SMP</TH> |
| 351 | <TD> |
| 352 | The SMP fills in the structure provided with the information retrieved from the IOP. |
| 353 | </TD> |
| 354 | </TR> |
| 355 | </TABLE></TD></TR> |
| 356 | |
| 357 | <TR> |
| 358 | <TD VALIGN=TOP ROWSPAN=2><B>pcap_close()</B></TD> |
| 359 | <TD VALIGN=TOP>Closes the file and deallocates resources.</TD> |
| 360 | </TR> |
| 361 | <TR><TD><TABLE BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH=100%> |
| 362 | <TR><TH VALIGN=TOP NOWRAP>SMP -> IOP</TH> |
| 363 | <TD> |
| 364 | The SMP closes the file descriptor, and if the descriptor is that of |
| 365 | the comminucation session with an IOP, it too is terminated. |
| 366 | </TD> |
| 367 | </TR> |
| 368 | <TR><TH VALIGN=TOP NOWRAP>IOP</TH> |
| 369 | <TD> |
| 370 | If the IOP detects that its communication session with an SMP |
| 371 | has closed, it will terminate any monitoring in progress, |
| 372 | release any resources and close its end of the session. |
| 373 | It will not maintain persistance of any information or prior mode of operation. |
| 374 | </TD> |
| 375 | </TR> |
| 376 | </TABLE></TD></TR> |
| 377 | </TABLE> |
| 378 | </UL> |
| 379 | |
| 380 | <P> |
| 381 | <H3>SMP/IOP Inter-Process Communication Protocol</H3> |
| 382 | |
| 383 | <UL> |
| 384 | <LI><P>Communications between an SMP and an IOP consists of a TCP session |
| 385 | between an ephemeral port on the SMP and the well known port of 49152 |
| 386 | (which is the first available port in the 'dynamic and/or private port' |
| 387 | range) on an IOP. |
| 388 | <LI><P>Following a TCP open operation the IOP receives a null terminated |
| 389 | 'interface ID' string to determine the type of operation that follows: |
| 390 | <LI><P>Every command received by an IOP implies a 'stop trace/stop forwarding' operation must |
| 391 | occur before executing the received command. |
| 392 | <LI><P>A session is closed when the SMP closes the TCP session with the IOP. |
| 393 | Obviously monitoring and forwarding is also stopped at that time. |
| 394 | |
| 395 | <B>Note: </B>All multi-octet entities are sent in network neutral order. |
| 396 | <P> |
| 397 | |
| 398 | <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=5> |
| 399 | <TR><TH COLSPAN=3><HR WIDTH=100%></TH></TR> |
| 400 | <TR> |
| 401 | <TD VALIGN=TOP ROWSPAN=6>pcap_findalldevs()</TD> |
| 402 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>SMP -> IOP</TD> |
| 403 | <TD VALIGN=TOP>Open socket (to each IOP), and sends: |
| 404 | <P> |
| 405 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 406 | <TR> |
| 407 | <TH VALIGN=TOP ALIGN=CENTER>Name/<BR>Purpose</TH> |
| 408 | <TH VALIGN=TOP ALIGN=CENTER NOWRAP>Size<BR>(in bytes)</TH> |
| 409 | <TH VALIGN=TOP ALIGN=CENTER>Description</TH> |
| 410 | </TR> |
| 411 | <TR> |
| 412 | <TD VALIGN=TOP>Interface ID</TD> |
| 413 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 414 | <TD VALIGN=TOP>A NULL to indicate an an empty 'interface ID'.</TD> |
| 415 | </TR> |
| 416 | </TABLE> |
| 417 | </TD> |
| 418 | </TR> |
| 419 | <TR> |
| 420 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>IOP -> SMP</TD> |
| 421 | <TD VALIGN=TOP>Send its (possibly empty) NULL terminated error response string.</TD> |
| 422 | </TR> |
| 423 | <TR> |
| 424 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>SMP -> IOP</TD> |
| 425 | <TD VALIGN=TOP>Sends the 'interface query request': |
| 426 | <P> |
| 427 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 428 | <TR> |
| 429 | <TH VALIGN=TOP ALIGN=CENTER>Name/<BR>Purpose</TH> |
| 430 | <TH VALIGN=TOP ALIGN=CENTER NOWRAP>Size<BR>(in bytes)</TH> |
| 431 | <TH VALIGN=TOP ALIGN=CENTER>Description</TH> |
| 432 | </TR> |
| 433 | <TR> |
| 434 | <TD VALIGN=TOP>Interface ID</TD> |
| 435 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 436 | <TD VALIGN=TOP>A 'Q' (indicating 'interface query request').</TD> |
| 437 | </TR> |
| 438 | </TABLE> |
| 439 | </TD> |
| 440 | </TR> |
| 441 | <TR> |
| 442 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>IOP -> SMP</TD> |
| 443 | <TD VALIGN=TOP>The IOP returns a list of sequences of information as |
| 444 | defined by the return parameter of this function call (as shown in the following table). |
| 445 | Elements are specified by providing an unsigned byte preceeding the actual data that contains length information. |
| 446 | <P> |
| 447 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 448 | <TR> |
| 449 | <TH VALIGN=TOP ALIGN=CENTER>Notes:</TH> |
| 450 | <TH VALIGN=TOP ALIGN=CENTER>Name/<BR>Purpose</TH> |
| 451 | <TH VALIGN=TOP ALIGN=CENTER NOWRAP>Size<BR>(in bytes)</TH> |
| 452 | <TH VALIGN=TOP ALIGN=CENTER>Description</TH> |
| 453 | </TR> |
| 454 | <TR> |
| 455 | <TD ROWSPAN=7> </TD> |
| 456 | <TD VALIGN=TOP ALIGN=RIGHT>length</TD> |
| 457 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 458 | <TD VALIGN=TOP>The number of octets in the name field that follows.</TD> |
| 459 | </TR> |
| 460 | <TR><TD VALIGN=TOP ALIGN=LEFT>Name</TD> |
| 461 | <TD VALIGN=TOP ALIGN=CENTER>1-255</TD> |
| 462 | <TD VALIGN=TOP>The name of the interface. The format of the name is an alphabetic string (indicating |
| 463 | the type of interface) followed by an optional numeric string (indicating the interface's |
| 464 | sequence number). |
| 465 | Sequence numbers (if needed) will begin at zero and progress monotonically upwards. |
| 466 | (i.e. 'eth0', 'lo', 'wan0', etc.) |
| 467 | <P> |
| 468 | For an IOP, the alphabetic string will be one of: 'eth', 'wan', and 'lo' |
| 469 | for Ethernet, WAN ports and the IP loopback device respectively. |
| 470 | An IOP currently supports: 'eth0', 'eth1', 'lo', 'wan0' ... 'wan7'. |
| 471 | <P> |
| 472 | <B>Note:</B> IOPs and ACNs will not currently support the concept of 'any' interface.</TD> |
| 473 | </TR> |
| 474 | <TR><TD VALIGN=TOP ALIGN=RIGHT>length</TD> |
| 475 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 476 | <TD VALIGN=TOP>The number of octets in the interface description field that follows.</TD> |
| 477 | </TR> |
| 478 | <TR><TD VALIGN=TOP ALIGN=LEFT>Interface Description</TD> |
| 479 | <TD VALIGN=TOP ALIGN=CENTER>0-255</TD> |
| 480 | <TD VALIGN=TOP>A description of the interface or it may be an empty string. (i.e. 'ALC')</TD> |
| 481 | </TR> |
| 482 | <TR><TD VALIGN=TOP ALIGN=LEFT>Interface Type</TD> |
| 483 | <TD VALIGN=TOP ALIGN=CENTER>4</TD> |
| 484 | <TD VALIGN=TOP>The type of interface as defined in the description for pcap_datalink() (in network neutral order).</TD> |
| 485 | </TR> |
| 486 | <TR><TD VALIGN=TOP ALIGN=LEFT>Loopback Flag</TD> |
| 487 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 488 | <TD VALIGN=TOP>1 = if the interface is a loopback interface, zero = otherwise.</TD> |
| 489 | </TR> |
| 490 | <TR><TD VALIGN=TOP ALIGN=RIGHT>count</TD> |
| 491 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 492 | <TD VALIGN=TOP># of address entries that follow. |
| 493 | Each entry is a series of bytes in network neutral order. |
| 494 | See the parameter definition above for more details.</TD> |
| 495 | </TR> |
| 496 | <TR> |
| 497 | <TD ALIGN=CENTER ROWSPAN=8 WIDTH=1%>Repeated 'count' number of times.</TD> |
| 498 | <TD VALIGN=TOP ALIGN=RIGHT>length</TD> |
| 499 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 500 | <TD VALIGN=TOP>The number of octets in the address field that follows.</TD> |
| 501 | </TR> |
| 502 | <TR><TD VALIGN=TOP ALIGN=LEFT>Address</TD> |
| 503 | <TD VALIGN=TOP ALIGN=CENTER>1-255</TD> |
| 504 | <TD VALIGN=TOP>The address of this interface (in network neutral order).</TD> |
| 505 | </TR> |
| 506 | <TR><TD VALIGN=TOP ALIGN=RIGHT>length</TD> |
| 507 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 508 | <TD VALIGN=TOP>The number of octets in the netmask field that follows.</TD> |
| 509 | </TR> |
| 510 | <TR><TD VALIGN=TOP ALIGN=LEFT>Network Mask</TD> |
| 511 | <TD VALIGN=TOP ALIGN=CENTER>0-255</TD> |
| 512 | <TD VALIGN=TOP>The network mask used on this interface (if applicable) (in network neutral order).</TD> |
| 513 | </TR> |
| 514 | <TR><TD VALIGN=TOP ALIGN=RIGHT>length</TD> |
| 515 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 516 | <TD VALIGN=TOP>The number of octets in the broadcast address field that follows.</TD> |
| 517 | </TR> |
| 518 | <TR><TD VALIGN=TOP ALIGN=LEFT>Broadcast Address</TD> |
| 519 | <TD VALIGN=TOP ALIGN=CENTER>0-255</TD> |
| 520 | <TD VALIGN=TOP>The broadcast address of this interface (if applicable) (in network neutral order).</TD> |
| 521 | </TR> |
| 522 | <TR><TD VALIGN=TOP ALIGN=RIGHT>length</TD> |
| 523 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 524 | <TD VALIGN=TOP>The number of octets in the destination address field that follows.</TD> |
| 525 | </TR> |
| 526 | <TR><TD VALIGN=TOP ALIGN=LEFT>Destination Address</TD> |
| 527 | <TD VALIGN=TOP ALIGN=CENTER>0-255</TD> |
| 528 | <TD VALIGN=TOP>The destination address of this interface (if applicable) (in network neutral order).</TD> |
| 529 | </TR> |
| 530 | </TABLE> |
| 531 | </TR> |
| 532 | <TR> |
| 533 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>SMP -> IOP</TD> |
| 534 | <TD VALIGN=TOP>Close the socket.</TD> |
| 535 | </TR> |
| 536 | <TR> |
| 537 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>IOP -> SMP</TD> |
| 538 | <TD VALIGN=TOP>Close the socket.</TD> |
| 539 | </TR> |
| 540 | <TR><TH COLSPAN=3><HR WIDTH=100%></TH></TR> |
| 541 | <TR> |
| 542 | <TD VALIGN=TOP ROWSPAN=2>pcap_open_live()</TD> |
| 543 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>SMP -> IOP</TD> |
| 544 | <TD VALIGN=TOP>Open socket, and sends: |
| 545 | <P> |
| 546 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 547 | <TR> |
| 548 | <TH VALIGN=TOP ALIGN=CENTER>Name/<BR>Purpose</TH> |
| 549 | <TH VALIGN=TOP ALIGN=CENTER NOWRAP>Size<BR>(in bytes)</TH> |
| 550 | <TH VALIGN=TOP ALIGN=CENTER>Description</TH> |
| 551 | </TR> |
| 552 | <TR> |
| 553 | <TD VALIGN=TOP>Interface ID</TD> |
| 554 | <TD VALIGN=TOP ALIGN=CENTER>'n'</TD> |
| 555 | <TD VALIGN=TOP>'n' octets containing a NULL terminated interface name string.</TD> |
| 556 | </TR> |
| 557 | </TABLE> |
| 558 | </TD> |
| 559 | </TR> |
| 560 | <TR> |
| 561 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>IOP -> SMP</TD> |
| 562 | <TD VALIGN=TOP>Send its NULL terminated error response string.</TD> |
| 563 | </TR> |
| 564 | <TR><TH COLSPAN=3><HR WIDTH=100%></TH></TR> |
| 565 | <TR> |
| 566 | <TD VALIGN=TOP NOWRAP ROWSPAN=2>pcap_dispatch()<BR>pcap_loop()<BR>pcap_next()<BR>pcap_next_ex()</TD> |
| 567 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>SMP -> IOP</TD> |
| 568 | <TD VALIGN=TOP>On the first invocation following a pcap_open_live() or pcap_breakloop() additional information is sent: |
| 569 | <P> |
| 570 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 571 | <TR> |
| 572 | <TH VALIGN=TOP ALIGN=CENTER>Name/<BR>Purpose</TH> |
| 573 | <TH VALIGN=TOP ALIGN=CENTER NOWRAP>Size<BR>(in bytes)</TH> |
| 574 | <TH VALIGN=TOP ALIGN=CENTER>Description</TH> |
| 575 | </TR> |
| 576 | <TR> |
| 577 | <TD VALIGN=TOP>command</TD> |
| 578 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 579 | <TD VALIGN=TOP>'M' (indicating 'monitor start')</TD> |
| 580 | </TR> |
| 581 | <TR> |
| 582 | <TD VALIGN=TOP>snaplen</TD> |
| 583 | <TD VALIGN=TOP ALIGN=CENTER>4</TD> |
| 584 | <TD VALIGN=TOP>snaplen</TD> |
| 585 | </TR> |
| 586 | <TR> |
| 587 | <TD VALIGN=TOP>timeout</TD> |
| 588 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 589 | <TD VALIGN=TOP>timeout value (in milliseconds)</TD> |
| 590 | </TR> |
| 591 | <TR> |
| 592 | <TD VALIGN=TOP>promiscuous</TD> |
| 593 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 594 | <TD VALIGN=TOP>A flag indicating that the interface being monitored show operate |
| 595 | in promiscuous mode. [off(0) / on(NZ)]</TD> |
| 596 | </TR> |
| 597 | <TR> |
| 598 | <TD VALIGN=TOP>direction</TD> |
| 599 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 600 | <TD VALIGN=TOP>A flag indicating the direction of traffic that should be captuted [both(0) / in(1) / out(2)]</TD> |
| 601 | </TR> |
| 602 | </TABLE> |
| 603 | </TD> |
| 604 | </TR> |
| 605 | <TR> |
| 606 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>IOP -> SMP</TD> |
| 607 | <TD VALIGN=TOP>Sends captured packets.</TD> |
| 608 | </TR> |
| 609 | <TR><TH COLSPAN=3><HR WIDTH=100%></TH></TR> |
| 610 | <TR> |
| 611 | <TD VALIGN=TOP ROWSPAN=2>pcap_setfilter()</TD> |
| 612 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>SMP -> IOP</TD> |
| 613 | <TD VALIGN=TOP>At any time, the SMP can issue a set filter command which contains |
| 614 | an indicator, a count of the number of statements in the filter, |
| 615 | followed by the sequence of filter commands represented as a sequence |
| 616 | of C-style structures. |
| 617 | <P> |
| 618 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 619 | <TR> |
| 620 | <TH VALIGN=TOP ALIGN=CENTER>Name/<BR>Purpose</TH> |
| 621 | <TH VALIGN=TOP ALIGN=CENTER NOWRAP>Size<BR>(in bytes)</TH> |
| 622 | <TH VALIGN=TOP ALIGN=CENTER>Description</TH> |
| 623 | </TR> |
| 624 | <TR> |
| 625 | <TD VALIGN=TOP>command</TD> |
| 626 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 627 | <TD VALIGN=TOP>'F' (indicating 'filter')</TD> |
| 628 | </TR> |
| 629 | <TR> |
| 630 | <TD VALIGN=TOP>count</TD> |
| 631 | <TD VALIGN=TOP ALIGN=CENTER>4</TD> |
| 632 | <TD VALIGN=TOP>The number of command in the Berkeley Packet Filter that follow.</TD> |
| 633 | </TR> |
| 634 | <TR> |
| 635 | <TD VALIGN=TOP>BPF program</TD> |
| 636 | <TD VALIGN=TOP ALIGN=CENTER>'n'</TD> |
| 637 | <TD VALIGN=TOP>8 bytes of each command (repeated 'n' times).<BR> |
| 638 | Each command consists of that C-style structure which contains: |
| 639 | <P> |
| 640 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 641 | <TR> |
| 642 | <TH VALIGN=TOP ALIGN=CENTER>Name/<BR>Purpose</TH> |
| 643 | <TH VALIGN=TOP ALIGN=CENTER NOWRAP>Size<BR>(in bytes)</TH> |
| 644 | <TH VALIGN=TOP ALIGN=CENTER>Description</TH> |
| 645 | </TR> |
| 646 | <TR> |
| 647 | <TD VALIGN=TOP>opcode</TD> |
| 648 | <TD VALIGN=TOP ALIGN=CENTER>2</TD> |
| 649 | <TD VALIGN=TOP>The command's opcode.</TD> |
| 650 | </TR> |
| 651 | <TR> |
| 652 | <TD VALIGN=TOP>'jt'</TD> |
| 653 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 654 | <TD VALIGN=TOP>The 'jump if true' program counter offset.</TD> |
| 655 | </TR> |
| 656 | <TR> |
| 657 | <TD VALIGN=TOP>'jf'</TD> |
| 658 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 659 | <TD VALIGN=TOP>The 'jump if false' program counter offset.</TD> |
| 660 | </TR> |
| 661 | <TR> |
| 662 | <TD VALIGN=TOP>'k'</TD> |
| 663 | <TD VALIGN=TOP ALIGN=CENTER>4</TD> |
| 664 | <TD VALIGN=TOP>The 'other' data field.</TD> |
| 665 | </TR> |
| 666 | </TABLE> |
| 667 | <P> |
| 668 | Refer to the bpf(4) man page for more details. |
| 669 | </TD> |
| 670 | </TR> |
| 671 | </TABLE> |
| 672 | </TD> |
| 673 | </TR> |
| 674 | <TR> |
| 675 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>IOP -> SMP</TD> |
| 676 | <TD VALIGN=TOP>In return the IOP will send its (possibly empty) NULL terminated error response string.</TD> |
| 677 | </TR> |
| 678 | <TR><TH COLSPAN=3><HR WIDTH=100%></TH></TR> |
| 679 | <TR> |
| 680 | <TD VALIGN=TOP ROWSPAN=2>pcap_stats()</TD> |
| 681 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>SMP -> IOP</TD> |
| 682 | <TD VALIGN=TOP>At any time, the SMP can issue a 'retrieve statistics' command which contains:<BR> |
| 683 | <P> |
| 684 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 685 | <TR> |
| 686 | <TH VALIGN=TOP ALIGN=CENTER>Name/<BR>Purpose</TH> |
| 687 | <TH VALIGN=TOP ALIGN=CENTER NOWRAP>Size<BR>(in bytes)</TH> |
| 688 | <TH VALIGN=TOP ALIGN=CENTER>Description</TH> |
| 689 | </TR> |
| 690 | <TR> |
| 691 | <TD VALIGN=TOP>command</TD> |
| 692 | <TD VALIGN=TOP ALIGN=CENTER>1</TD> |
| 693 | <TD VALIGN=TOP>'S' (indicating 'request statistics')</TD> |
| 694 | </TR> |
| 695 | </TABLE> |
| 696 | </TD> |
| 697 | </TR> |
| 698 | <TR> |
| 699 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>IOP -> SMP</TD> |
| 700 | <TD VALIGN=TOP>In return the IOP will send: |
| 701 | <P> |
| 702 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 703 | <TR> |
| 704 | <TH VALIGN=TOP ALIGN=CENTER>Name/<BR>Purpose</TH> |
| 705 | <TH VALIGN=TOP ALIGN=CENTER NOWRAP>Size<BR>(in bytes)</TH> |
| 706 | <TH VALIGN=TOP ALIGN=CENTER>Description</TH> |
| 707 | </TR> |
| 708 | <TR> |
| 709 | <TD VALIGN=TOP>ps_recv</TD> |
| 710 | <TD VALIGN=TOP ALIGN=CENTER>4</TD> |
| 711 | <TD VALIGN=TOP>The number of packets that passed the filter.</TD> |
| 712 | </TR> |
| 713 | <TR> |
| 714 | <TD VALIGN=TOP>ps_drop</TD> |
| 715 | <TD VALIGN=TOP ALIGN=CENTER>4</TD> |
| 716 | <TD VALIGN=TOP>The number of packets that were dropped because the input queue was full, |
| 717 | regardless of whether they passed the filter.</TD> |
| 718 | </TR> |
| 719 | <TR> |
| 720 | <TD VALIGN=TOP>ps_ifdrop</TD> |
| 721 | <TD VALIGN=TOP ALIGN=CENTER>4</TD> |
| 722 | <TD VALIGN=TOP>The number of packets dropped by the network inteface |
| 723 | (regardless of whether they would have passed the input filter).</TD> |
| 724 | </TR> |
| 725 | </TABLE> |
| 726 | </TD> |
| 727 | </TR> |
| 728 | <TR><TH COLSPAN=3><HR WIDTH=100%></TH></TR> |
| 729 | <TR> |
| 730 | <TD VALIGN=TOP ROWSPAN=1>pcap_close()</TD> |
| 731 | <TD VALIGN=TOP ALIGN=CENTER NOWRAP>SMP -> IOP</TD> |
| 732 | <TD VALIGN=TOP>At any time, the SMP can close the TCP session with the IOP.</TD> |
| 733 | </TR> |
| 734 | <TR><TH COLSPAN=3><HR WIDTH=100%></TH></TR> |
| 735 | </TABLE> |
| 736 | </UL> |
| 737 | |
| 738 | <H3>Interface ID Naming Convention</H3> |
| 739 | <UL> |
| 740 | Each interface within an IOP will be referred to uniquely. Since an currently contains |
| 741 | 8 monitorable WAN ports and a monitorable Ethernet port, the naming convention is: |
| 742 | <P> |
| 743 | <CENTER> |
| 744 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 745 | <TR><TH>Interface #</TH> <TH>Type</TH> <TH>Name</TH></TR> |
| 746 | <TR><TD ALIGN=CENTER>1</TD> <TD ALIGN=CENTER>WAN</TD> <TD ALIGN=CENTER>wan0</TD></TR> |
| 747 | <TR><TD ALIGN=CENTER>2</TD> <TD ALIGN=CENTER>WAN</TD> <TD ALIGN=CENTER>wan1</TD></TR> |
| 748 | <TR><TD ALIGN=CENTER>3</TD> <TD ALIGN=CENTER>WAN</TD> <TD ALIGN=CENTER>wan2</TD></TR> |
| 749 | <TR><TD ALIGN=CENTER>4</TD> <TD ALIGN=CENTER>WAN</TD> <TD ALIGN=CENTER>wan3</TD></TR> |
| 750 | <TR><TD ALIGN=CENTER>5</TD> <TD ALIGN=CENTER>WAN</TD> <TD ALIGN=CENTER>wan4</TD></TR> |
| 751 | <TR><TD ALIGN=CENTER>6</TD> <TD ALIGN=CENTER>WAN</TD> <TD ALIGN=CENTER>wan5</TD></TR> |
| 752 | <TR><TD ALIGN=CENTER>7</TD> <TD ALIGN=CENTER>WAN</TD> <TD ALIGN=CENTER>wan6</TD></TR> |
| 753 | <TR><TD ALIGN=CENTER>8</TD> <TD ALIGN=CENTER>WAN</TD> <TD ALIGN=CENTER>wan7</TD></TR> |
| 754 | <TR><TD ALIGN=CENTER>9</TD> <TD ALIGN=CENTER>Ethernet</TD> <TD ALIGN=CENTER>eth0</TD></TR> |
| 755 | <TR><TD ALIGN=CENTER>10</TD> <TD ALIGN=CENTER>Ethernet</TD> <TD ALIGN=CENTER>eth1</TD></TR> |
| 756 | </TABLE> |
| 757 | </CENTER> |
| 758 | </UL> |
| 759 | |
| 760 | <H3>Packet Trace Data Format</H3> |
| 761 | <UL> |
| 762 | The format of the trace data that is sent to the SMP follows a portion of the libpcap file format |
| 763 | and is summarized here. This format specifies the generic requirements needed to |
| 764 | be able to decode packets, but does not cover ACN specifics such as custom MAC addressing |
| 765 | and WAN protocol support. |
| 766 | <P> |
| 767 | |
| 768 | Although a libpcap file begins with a global header followed by zero or |
| 769 | more records for each captured packet, trace data sent to the SMP does NOT begin with a global header. |
| 770 | A trace sequence looks like this: |
| 771 | <P> |
| 772 | <TABLE> |
| 773 | <TR> |
| 774 | <TD STYLE="background-color: #c0FFc0"> [Packet Header] </TD> |
| 775 | <TD STYLE="background-color: #c0FFc0"> [Packet Data] </TD> |
| 776 | <TD STYLE="background-color: #c0c0FF"> [Packet Header] </TD> |
| 777 | <TD STYLE="background-color: #c0c0FF"> [Packet Data] </TD> |
| 778 | <TD STYLE="background-color: #e0c0c0"> [Packet Header] </TD> |
| 779 | <TD STYLE="background-color: #e0c0c0"> [Packet Data] </TD> |
| 780 | <TD>...</TD> |
| 781 | </TR> |
| 782 | </TABLE> |
| 783 | |
| 784 | <H4>Packet Header</H4> |
| 785 | <UL> |
| 786 | Each captured packet starts with a header that contains the following values |
| 787 | (in network neutral order): |
| 788 | |
| 789 | <FONT SIZE=-1> |
| 790 | <PRE> |
| 791 | uint32 tv_sec; /* timestamp seconds */ |
| 792 | uint32 tv_usec; /* timestamp microseconds */ |
| 793 | uint32 caplen; /* number of octets in the following packet */ |
| 794 | uint32 len; /* original length of packet on the wire */ |
| 795 | </PRE> |
| 796 | </FONT> |
| 797 | |
| 798 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 799 | <TR> |
| 800 | <TD VALIGN=TOP>tv_sec</TD> |
| 801 | <TD>The date and time when this packet was captured. |
| 802 | This value is in seconds since January 1, 1970 00:00:00 GMT; |
| 803 | this is also known as a UN*X time_t. You can use the ANSI C |
| 804 | <em>time()</em> function from <em>time.h</em> to get this value, |
| 805 | but you might use a more optimized way to get this timestamp value. |
| 806 | If this timestamp isn't based on GMT (UTC), use <em>thiszone</em> |
| 807 | from the global header for adjustments.</TD> |
| 808 | </TR> |
| 809 | <TR> |
| 810 | <TD VALIGN=TOP>tv_usec</TD> |
| 811 | <TD>The microseconds when this packet was captured, as an offset to <em>ts_sec</em>. |
| 812 | <B>Beware: </B>this value must never reach 1 second (1,000,000), |
| 813 | in this case <em>ts_sec</em> must be increased instead!</TD> |
| 814 | </TR> |
| 815 | <TR> |
| 816 | <TD VALIGN=TOP>caplen</TD> |
| 817 | <TD>The number of bytes actually provided in the capture record. |
| 818 | This value should never become larger than <em>len</em> or the |
| 819 | <em>snaplen</em> value specified during the capture.</TD> |
| 820 | </TR> |
| 821 | <TR> |
| 822 | <TD VALIGN=TOP>len</TD> |
| 823 | <TD>The length of the packet "on the wire" when it was captured. |
| 824 | If <em>caplen</em> and <em>len</em> differ, the actually |
| 825 | saved packet size was limited by the value of <em>snaplen</em> specified |
| 826 | during one of the capture directives such as pcap_dispatch().</TD> |
| 827 | </TR> |
| 828 | </TABLE> |
| 829 | </UL> |
| 830 | |
| 831 | <H4>Packet Data</H4> |
| 832 | <UL> |
| 833 | The actual packet data will immediately follow the packet header as a sequence of <em>caplen</em> octets. |
| 834 | Depending on the DLT encoding number assigned to the interface, the packet data will contain an additional |
| 835 | custom header used to convey WAN port related information. |
| 836 | </UL> |
| 837 | |
| 838 | <H4>ACN Custom Packet Header</H4> |
| 839 | <UL> |
| 840 | PCAP, Wireshark and Tcpdump enhancements have been added to the ACN to support |
| 841 | monitoring of its ports, however each of these facilities were focused on capturing |
| 842 | and displaying traffic from LAN interfaces. The SITA extentions to these facilities |
| 843 | are used to also provide the ability to capture, filter, and display information from |
| 844 | an ACN's WAN ports. |
| 845 | <P> |
| 846 | Although each packet follows the standard libpcap format, since there are |
| 847 | two types of interfaces that can be monitored, the format of the data |
| 848 | packet varies slightly. |
| 849 | <P> |
| 850 | <UL TYPE=DISC> |
| 851 | <LI>For Ethernet (like) devices, the packet format is unchanged from the standard Pcap format. |
| 852 | <LI>For WAN devices, the packet contains a 5 byte header that preceeds the actual captured data |
| 853 | described by the following table: |
| 854 | </UL> |
| 855 | <P> |
| 856 | <CENTER> |
| 857 | <TABLE BORDER=1 CELLSPACING=0 CELLPADDING=3> |
| 858 | <TR> <TH>Octet</TH> |
| 859 | <TH>Name</TH> |
| 860 | <TH>Mask/Value</TH> |
| 861 | <TH COLSPAN=2>Definition</TH> </TR> |
| 862 | |
| 863 | <TR> <TH VALIGN=TOP ALIGN=CENTER ROWSPAN=3>0</TH> |
| 864 | <TH VALIGN=TOP ALIGN=CENTER ROWSPAN=3>Control / Status</TH> |
| 865 | |
| 866 | <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxxxx0</FONT></TD> |
| 867 | <TD>Transmitted by capture device</TD> |
| 868 | <TD ROWSPAN=2 ALIGN=CENTER>(see 'Errors' octets)</TD> </TR> |
| 869 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxxxx1</FONT></TD> |
| 870 | <TD>Received by capture device</TD> </TR> |
| 871 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">1xxxxxxx</FONT></TD> |
| 872 | <TD COLSPAN=2>No buffer was available during capture of previous packet.</TD> </TR> |
| 873 | |
| 874 | <TR> <TH VALIGN=TOP ALIGN=CENTER ROWSPAN=8>1</TH> |
| 875 | <TH VALIGN=TOP ALIGN=CENTER ROWSPAN=8>Signals</TH> |
| 876 | |
| 877 | <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxxxx1</FONT></TD> <TD COLSPAN=2>DSR asserted</TD> </TR> |
| 878 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxxx1x</FONT></TD> <TD COLSPAN=2>DTR asserted</TD> </TR> |
| 879 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxx1xx</FONT></TD> <TD COLSPAN=2>CTS asserted</TD> </TR> |
| 880 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxx1xxx</FONT></TD> <TD COLSPAN=2>RTS asserted</TD> </TR> |
| 881 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxx1xxxx</FONT></TD> <TD COLSPAN=2>DCD asserted</TD> </TR> |
| 882 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xx1xxxxx</FONT></TD> <TD COLSPAN=2>Undefined</TD> </TR> |
| 883 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">x1xxxxxx</FONT></TD> <TD COLSPAN=2>Undefined</TD> </TR> |
| 884 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">1xxxxxxx</FONT></TD> <TD COLSPAN=2>Undefined</TD> </TR> |
| 885 | |
| 886 | <TR> <TH VALIGN=TOP ALIGN=CENTER ROWSPAN=9>2</TH> |
| 887 | <TH VALIGN=TOP ALIGN=CENTER ROWSPAN=9>Errors<BR>(octet 1)</TH> |
| 888 | |
| 889 | <TH> </TH> <TH>Tx</TH> <TH>Rx</TH> </TR> |
| 890 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxxxx1</FONT></TD> <TD>Underrun</TD> <TD>Framing</TD> </TR> |
| 891 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxxx1x</FONT></TD> <TD>CTS Lost</TD> <TD>Parity</TD> </TR> |
| 892 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxx1xx</FONT></TD> <TD>UART Error</TD> <TD>Collision</TD> </TR> |
| 893 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxx1xxx</FONT></TD> <TD>Re-Tx Limit Reached</TD> <TD>Long Frame</TD> </TR> |
| 894 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxx1xxxx</FONT></TD> <TD>Undefined</TD> <TD>Short Frame</TD> </TR> |
| 895 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xx1xxxxx</FONT></TD> <TD>Undefined</TD> <TD>Undefined</TD> </TR> |
| 896 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">x1xxxxxx</FONT></TD> <TD>Undefined</TD> <TD>Undefined</TD> </TR> |
| 897 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">1xxxxxxx</FONT></TD> <TD>Undefined</TD> <TD>Undefined</TD> </TR> |
| 898 | |
| 899 | <TR> <TH VALIGN=TOP ALIGN=CENTER ROWSPAN=9>3</TH> |
| 900 | <TH VALIGN=TOP ALIGN=CENTER ROWSPAN=9>Errors<BR>(octet 2)</TH> |
| 901 | |
| 902 | <TH> </TH> <TH>Tx</TH> <TH>Rx</TH> </TR> |
| 903 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxxxx1</FONT></TD> <TD>Undefined</TD> <TD>Non-Octet Aligned</TD> </TR> |
| 904 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxxx1x</FONT></TD> <TD>Undefined</TD> <TD>Abort Received</TD> </TR> |
| 905 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxxx1xx</FONT></TD> <TD>Undefined</TD> <TD>CD Lost</TD> </TR> |
| 906 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxxx1xxx</FONT></TD> <TD>Undefined</TD> <TD>Digital PLL Error</TD> </TR> |
| 907 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xxx1xxxx</FONT></TD> <TD>Undefined</TD> <TD>Overrun</TD> </TR> |
| 908 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">xx1xxxxx</FONT></TD> <TD>Undefined</TD> <TD>Frame Length Violation</TD> </TR> |
| 909 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">x1xxxxxx</FONT></TD> <TD>Undefined</TD> <TD>CRC Error</TD> </TR> |
| 910 | <TR> <TD VALIGN=TOP ALIGN=CENTER><FONT FACE="COURIER">1xxxxxxx</FONT></TD> <TD>Undefined</TD> <TD>Break Received</TD> </TR> |
| 911 | |
| 912 | <TR> <TH VALIGN=TOP ALIGN=CENTER ROWSPAN=12>4</TH> |
| 913 | <TH VALIGN=TOP ALIGN=CENTER>Protocol</TH> |
| 914 | |
| 915 | <TD COLSPAN=3> |
| 916 | <CENTER> |
| 917 | <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0> |
| 918 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x01</TD> <TD>-</TD> <TD>LAPB (BOP) <SUP> </SUP> </TD> </TR> |
| 919 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x02</TD> <TD>-</TD> <TD>Ethernet <SUP>1</SUP> </TD> </TR> |
| 920 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x03</TD> <TD>-</TD> <TD>Async (Interrupt IO) <SUP> </SUP> </TD> </TR> |
| 921 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x04</TD> <TD>-</TD> <TD>Async (Block IO) <SUP> </SUP> </TD> </TR> |
| 922 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x05</TD> <TD>-</TD> <TD>IPARS <SUP> </SUP> </TD> </TR> |
| 923 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x06</TD> <TD>-</TD> <TD>UTS <SUP> </SUP> </TD> </TR> |
| 924 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x07</TD> <TD>-</TD> <TD>PPP (HDLC) <SUP> </SUP> </TD> </TR> |
| 925 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x08</TD> <TD>-</TD> <TD>SDLC <SUP> </SUP> </TD> </TR> |
| 926 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x09</TD> <TD>-</TD> <TD>Token Ring <SUP>1</SUP> </TD> </TR> |
| 927 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x10</TD> <TD>-</TD> <TD>I2C <SUP> </SUP> </TD> </TR> |
| 928 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x11</TD> <TD>-</TD> <TD>DPM Link <SUP> </SUP> </TD> </TR> |
| 929 | <TR VALIGN=BOTTOM><TD ALIGN=CENTER>0x12</TD> <TD>-</TD> <TD>Frame Relay (BOP) <SUP> </SUP> </TD> </TR> |
| 930 | </TABLE> |
| 931 | </CENTER> |
| 932 | <P> |
| 933 | <STRONG>Note 1:</STRONG> |
| 934 | Ethernet and Token Ring frames will never be sent as DLT_SITA (with the 5 octet header), |
| 935 | but will be sent as their corresponding DLT types instead. |
| 936 | </TD> |
| 937 | </TR> |
| 938 | </TABLE> |
| 939 | </CENTER> |
| 940 | </UL> |
| 941 | <P> |
| 942 | </UL> |
| 943 | </UL> |