sys/man/8/snoopy

   1 .TH SNOOPY 8
   2 .SH NAME
   3 snoopy \- spy on network packets
   4 .SH SYNOPSIS
   5 .B snoopy
   6 [
   7 .B -CDdpst
   8 ] [
   9 .B -M
  10 .I m
  11 ] [
  12 .B -N
  13 .I n
  14 ] [
  15 .B -f
  16 .I filter-expression
  17 ] [
  18 .B -h
  19 .I first-header
  20 ] [
  21 .I packet-source
  22 ]
  23 .PP
  24 .B snoopy
  25 .B -?
  26 [
  27 .I proto...
  28 ]
  29 .SH DESCRIPTION
  30 .I Snoopy
  31 reads packets from a
  32 .I packet-source
  33 (default
  34 .BR /net/ether0 ),
  35 matches them to a filter (by default anything matches), and writes
  36 matching packets to standard output either in human readable form (default)
  37 or in a binary trace format that can be later read by
  38 .IR snoopy .
  39 .I Packet-source
  40 can be the name of an Ethernet
  41 (e.g.,
  42 .BR /net/ether0 ),
  43 an interface
  44 (e.g.,
  45 .BR /net/ipifc/0 ),
  46 or a file of captured packets.
  47 .PP
  48 The human readable format consists of multiple lines per packet.
  49 The first line contains the milliseconds since the
  50 trace was started.  Subsequent ones are indented with a tab
  51 and each contains the dump of a single protocol header.  The last line
  52 contains the dump of any contained data.  For example, a
  53 .SM BOOTP
  54 packet would look like:
  55 .IP
  56 .EX
  57 324389 ms
  58         ether(s=0000929b1b54 d=ffffffffffff pr=0800 ln=342)
  59         ip(s=135.104.9.62 d=255.255.255.255 id=5099 frag=0000...
  60         udp(s=68 d=67 ck=d151 ln= 308)
  61         bootp(t=Req ht=1 hl=16 hp=0 xid=217e5f27 sec=0 fl=800...
  62         dhcp(t=Request clientid=0152415320704e7266238ebf01030...
  63 .EE
  64 .PP
  65 The binary format consists of:
  66 .IP
  67 2 bytes of packet length, msb first
  68 .IP
  69 8 bytes of nanosecond time, msb first
  70 .IP
  71 the packet
  72 .PP
  73 Filters are expressions specifying protocols to be traced
  74 and specific values for fields in the protocol headers.
  75 The grammar is:
  76 .IP
  77 .EX
  78 \fIexpr\fP:       \fIprotocol\fP
  79         | \fIfield\fP '=' \fIvalue\fP
  80         | \fIfield\fP '!=' \fIvalue\fP
  81         | \fIprotocol\fP '(' \fIexpr\fP ')'
  82         | '(' \fIexpr\fP ')'
  83         | \fIexpr\fP '||' \fIexpr\fP
  84         | \fIexpr\fP '&&' \fIexpr\fP
  85         | '!' \fIexpr\fP
  86 .EE
  87 .PP
  88 The values for
  89 .I protocol
  90 and
  91 .I field
  92 can
  93 be obtained using the
  94 .B -?
  95 option.  With no arguments, it lists the known protocols.
  96 Otherwise it prints, for each protocol specified,
  97 which subprotocols it can multiplex to,
  98 and which fields can be used for filtering.
  99 For example, the listing for ethernet is currently:
 100 .IP
 101 .EX
 102 ether's filter attributes:
 103   s  - source address
 104   d  - destination address
 105   a  - source|destination address
 106   sd - source|destination address
 107   t  - type
 108 ether's subprotos:
 109   0x0800 ip               0x8863 pppoe_disc
 110   0x0806 arp              0x8864 pppoe_sess
 111   0x0806 rarp             0x888e eapol
 112   0x86dd ip6
 113 .EE
 114 .PP
 115 The format of
 116 .I value
 117 depends on context.  In general,
 118 ethernet addresses are entered as a string of hex
 119 digits; IP numbers in the canonical `.' format for v4 and `:' format
 120 for v6; and ports in decimal.
 121 .PP
 122 .IR Snoopy 's
 123 options are:
 124 .TP
 125 .B -C
 126 compute the correct checksum for each packet;
 127 on mismatch, add a field
 128 .B !ck=\fIxxxx\fP
 129 where
 130 .I xxxx
 131 is the correct checksum.
 132 .TP
 133 .B -D
 134 output will be a binary trace file in Unix pcap format.
 135 .TP
 136 .B -d
 137 output will be a binary trace file.
 138 .TP
 139 .B -t
 140 input is a binary trace file as generated with the
 141 .B -d
 142 option.
 143 .TP
 144 .B -p
 145 do not enter promiscuous mode.  Only packets to
 146 this interface will be seen.
 147 .TP
 148 .B -s
 149 force one output line per packet.  The
 150 default is multiline.
 151 .TP
 152 .B -M
 153 discard all but the first
 154 .I m
 155 bytes of each packet.  The default is to keep the entire packet.
 156 This option is most useful when writing packets to a file with the
 157 .B -d
 158 option.
 159 .TP
 160 .B -N
 161 dump
 162 .I n
 163 data bytes per packet.  The default is 32.
 164 .TP
 165 .B -f
 166 use
 167 .I filter-expression
 168 to filter the packet stream.  The default is
 169 to match all packets.
 170 .TP
 171 .B -h
 172 assume the first header per packet to be of the
 173 .I first-header
 174 protocol.
 175 The default is
 176 .LR ether .
 177 .SH EXAMPLES
 178 To display only
 179 .SM BOOTP
 180 and
 181 .SM ARP
 182 packets:
 183 .IP
 184 .EX
 185 % snoopy -f 'arp || bootp'
 186 after optimize: ether(arp || ip(udp(bootp)))
 187 .EE
 188 .PP
 189 The first line of output shows the completed filter
 190 expression.
 191 .I Snoopy
 192 will fill in other protocols as necessary to complete
 193 the filter and then optimize to remove redundant
 194 comparisons.
 195 .PP
 196 To save all packets between 135.104.9.2 to 135.104.9.6 and
 197 later display those to/from TCP port 80:
 198 .IP
 199 .EX
 200 % ramfs
 201 % snoopy -df 'ip(s=135.104.9.2 && d=135.104.9.6) ||\\
 202         ip(s=135.104.9.6 && d=135.104.9.2)' > /tmp/quux
 203 <interrupt from the keyboard>
 204 % snoopy -tf 'tcp(sd=80)' /tmp/quux
 205 .EE
 206 .SH FILES
 207 .TP
 208 .B /net/ether0
 209 Ethernet device
 210 .SH SOURCE
 211 .B /sys/src/cmd/ip/snoopy
 212 .SH BUGS
 213 .I Snoopy
 214 only dumps ethernet packets, because there's
 215 no device to get IP packets without a media header.