ongrep

A cleaned up fork of ngrep for OpenBSD
git clone git://git.sgregoratto.me/ongrep
Log | Files | Refs | README | LICENSE

ngrep.8 (5892B)


      1 .\" Copyright (c) 2017 Jordan Ritter <jpr5@darkridge.com>
      2 .\" Copyright (c) 2020 Stephen Gregoratto <dev@sgregoratto.me>
      3 .\" Please refer to the LICENSE file for more information.
      4 .Dd June 17, 2020
      5 .Dt NGREP 8
      6 .Os
      7 .Sh NAME
      8 .Nm ngrep
      9 .Nd network packet search
     10 .Sh SYNOPSIS
     11 .Nm
     12 .Op Fl CDeilMNpqtTvwxX
     13 .Op Fl A Ar num
     14 .Op Fl c Ar cols
     15 .Op Fl d Ar dev
     16 .Op Fl F Ar file
     17 .Op Fl I Ar pcap_dump
     18 .Op Fl n Ar num
     19 .Op Fl O Ar pcap_dump
     20 .Op Fl P Ar char
     21 .Op Fl S Ar limitlen
     22 .Op Fl s Ar snaplen
     23 .Op Fl W Cm normal | byline | single | none
     24 .Op Ar expression
     25 .Op Ar filter
     26 .Sh DESCRIPTION
     27 The
     28 .Nm
     29 utility prints out packets on a network interface that both match
     30 .Ar expression
     31 and
     32 .Ar filter .
     33 You must have read-write access to
     34 .Pa /dev/bpf .
     35 .Pp
     36 The options are as follows:
     37 .Bl -tag -width Ds
     38 .It Fl A Ar num
     39 Dump
     40 .Ar num
     41 packets of trailing context after matching a packet.
     42 .It Fl C
     43 Highlight the first occurence of
     44 .Ar expression
     45 in bright red.
     46 Enable highlighting of matched data.
     47 .It Fl c Ar cols
     48 Explicitly set the console width to
     49 .Ar cols .
     50 Note that this is the console width, and not the full width of what
     51 .Nm
     52 prints out as payloads; depending on the output mode
     53 .Nm
     54 may print less than
     55 .Ar cols
     56 bytes per line for indentation.
     57 .It Fl D
     58 When reading pcap dump files, replay them at their recorded time
     59 intervals (mimic realtime).
     60 .It Fl d Ar dev
     61 Listen on interface
     62 .Ar dev .
     63 If unspecified,
     64 .Nm
     65 will listen on the default system interface.
     66 .It Fl e
     67 Show empty packets.
     68 Normally empty packets are discarded because they have no payload to search.
     69 If specified, empty packets will be shown,
     70 regardless of
     71 .Ar expression .
     72 .It Fl F Ar file
     73 Read in the bpf filter from
     74 .Ar file .
     75 This is a compatibility option for users familiar with
     76 .Xr tcpdump 8 .
     77 Overrides the
     78 .Ar filter
     79 argument.
     80 .It Fl i
     81 Ignore case in
     82 .Ar expression .
     83 Incompatible with
     84 .Fl X .
     85 .It Fl I Ar pcap_dump
     86 Input file
     87 .Ar pcap_dump
     88 into
     89 .Nm .
     90 Works with any pcap-compatible dump file format.
     91 .It Fl l
     92 Force output to be line buffered.
     93 .It Fl M
     94 Make
     95 .Ar expression
     96 match single lines.
     97 Incompatible with
     98 .Fl X .
     99 .It Fl N
    100 Show sub-protocol number along with single-character identifier
    101 (useful when observing raw or unknown protocols).
    102 .It Fl n Ar num
    103 Match only
    104 .Ar num
    105 packets total, then exit.
    106 .It Fl O Ar pcap_dump
    107 Write matched packets to
    108 .Ar pcap_dump
    109 in a pcap-compatible dump format.
    110 This feature does not interfere with normal output to standard output.
    111 .It Fl p
    112 Don't put the interface into promiscuous mode.
    113 .It Fl P Ar char
    114 Use
    115 .Ar char
    116 to signify non-printable characters when displayed.
    117 The default is a dot
    118 .Pq Ql \&. .
    119 .It Fl q
    120 Don't output any information other than packet headers and
    121 their payloads (if relevant).
    122 .It Fl S Ar limitlen
    123 Set the upper limit on the size of packets that
    124 .Nm
    125 will look at to
    126 .Ar limitlen .
    127 Useful for looking at only the first N bytes of packets without
    128 changing the BPF snaplen.
    129 .It Fl s Ar snaplen
    130 Set the bpf caplen to
    131 .Ar snaplen .
    132 Defaults to 65536.
    133 .It Fl t
    134 Print a timestamp in the form of
    135 .Ql YYYY/MM/DD HH:MM:SS.UUUUUU
    136 every time a packet is matched.
    137 .It Fl T
    138 Print a timestamp in the form of
    139 .Ql +S.UUUUUU ,
    140 indicating the delta between packet matches.
    141 Specify a second time to indicate the delta since the first packet
    142 match.
    143 .It Fl v
    144 Display packets that
    145 .Em do not
    146 match
    147 .Ar expression .
    148 .It Fl w
    149 Match
    150 .Ar expression
    151 as a word.
    152 Incompatible with
    153 .Fl X .
    154 .It Fl W Cm normal | byline | single | none
    155 Specify an alternate manner for displaying packets.
    156 The
    157 .Cm byline
    158 mode honors embedded linefeeds,
    159 wrapping text only when a linefeed is encountered.
    160 The
    161 .Cm none
    162 mode doesn't wrap under any circumstance,
    163 with the entire payload displayed on one line.
    164 The
    165 .Cm single
    166 mode is conceptually the same as
    167 .Cm none ,
    168 except that everything including IP and source/destination header
    169 information is all on one line.
    170 .Cm normal
    171 is the default mode and is only included for completeness.
    172 .Pp
    173 This option is incompatible with
    174 .Fl x .
    175 .It Fl x
    176 Dump packet contents in canonical hex+ASCII form,
    177 similar to the same form in
    178 .Xr hexdump 1 .
    179 .It Fl X
    180 Treat the match expression as a hexadecimal string.
    181 .El
    182 .Pp
    183 .Ar expression
    184 is either a PCRE pattern as specfied in
    185 .Xr pcrepattern 3 ,
    186 or a hexadecimal string if
    187 .Fl X
    188 is specified.
    189 Hexadecimal strings can optionally be preceded by
    190 .Ql 0x .
    191 .Pp
    192 .Ar filter
    193 selects which packets will be matched.
    194 If no
    195 .Ar filter
    196 is given,
    197 all IP packets seen on the selected interface will be matched.
    198 Otherwise, only packets satisfying
    199 .Ar filter
    200 will be matched.
    201 The syntax for
    202 .Ar filter
    203 can be found in
    204 .Xr pcap-filter 5
    205 and
    206 .Xr tcpdump 8 .
    207 .Sh EXIT STATUS
    208 The
    209 .Nm
    210 utility exits with one of the following values:
    211 .Bl -tag -width Ds
    212 .It 0
    213 One or more frames were matched.
    214 .It 1
    215 No frames were matched.
    216 .It 2
    217 An error occurred.
    218 .El
    219 .Sh EXAMPLES
    220 Print all syslog messages that contain the word
    221 .Dq error
    222 in them.
    223 .Pp
    224 .Dl # ngrep 'error' port syslog
    225 .Pp
    226 Print FTP packets that contain the words
    227 .Dq user
    228 or
    229 .Dq pass ,
    230 case-insensitive.
    231 .Pp
    232 .Dl # ngrep -wi -d any 'user|pass' port 21
    233 .Pp
    234 Print all HTTP packets and wrap on newlines:
    235 .Pp
    236 .Dl # ngrep -W byline port 80
    237 .Pp
    238 Print HTTP data containing a specific hexadecimal value in hex+ASCII
    239 form:
    240 .Pp
    241 .Dl # ngrep -xX '0xc5d5e5f55666768696a6b6c6d6e6' port 80
    242 .Sh SEE ALSO
    243 .Xr grep 1 ,
    244 .Xr hexdump 1 ,
    245 .Xr pcrepattern 3 ,
    246 .Xr pcap-filter 5 ,
    247 .Xr tcpdump 8
    248 .Sh AUTHORS
    249 .An -nosplit
    250 The
    251 .Nm
    252 utility was written by
    253 .An Jordan Ritter Aq Mt jpr5@darkridge.com ,
    254 and is maintained by
    255 .An Stephen Gregoratto Aq Mt dev@sgregoratto.me .
    256 .Sh CAVEATS
    257 .Nm
    258 can get confused about which arguments make up the
    259 .Ar expression
    260 or the
    261 .Ar filter .
    262 For example:
    263 .Pp
    264 .Dl # ngrep not port 80
    265 .Pp
    266 Here
    267 .Nm
    268 will print all packets on port 80 containing the word
    269 .Dq not ,
    270 instead of printing all packets that are not on port 80.
    271 In cases like this, you will need to specify a blank match expression:
    272 .Pp
    273 .Dl # ngrep '' not port 80