ngrep.8 (5891B)
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 This is the default if standard output is a terminal. 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 .Cm none 161 doesn't wrap under any circumstance, 162 with the entire payload displayed on one line. 163 .Cm single 164 is conceptually the same as 165 .Cm none , 166 except that everything including IP and source/destination header 167 information is all on one line. 168 .Cm normal 169 is the default mode and is only included for completeness. 170 .Pp 171 This option is incompatible with 172 .Fl x . 173 .It Fl x 174 Dump packet contents in canonical hex+ASCII form, 175 similar to the same form in 176 .Xr hexdump 1 . 177 .It Fl X 178 Treat the match expression as a hexadecimal string. 179 .El 180 .Pp 181 .Ar expression 182 is either a PCRE pattern as specfied in 183 .Xr pcrepattern 3 , 184 or a hexadecimal string if 185 .Fl X 186 is specified. 187 Hexadecimal strings can optionally be preceded by 188 .Ql 0x . 189 .Pp 190 .Ar filter 191 selects which packets will be matched. 192 If no 193 .Ar filter 194 is given, 195 all IP packets seen on the selected interface will be matched. 196 Otherwise, only packets satisfying 197 .Ar filter 198 will be matched. 199 The syntax for 200 .Ar filter 201 can be found in 202 .Xr pcap-filter 5 203 and 204 .Xr tcpdump 8 . 205 .Sh EXIT STATUS 206 The 207 .Nm 208 utility exits with one of the following values: 209 .Bl -tag -width Ds 210 .It 0 211 One or more frames were matched. 212 .It 1 213 No frames were matched. 214 .It 2 215 An error occurred. 216 .El 217 .Sh EXAMPLES 218 Print all syslog messages that contain the word 219 .Dq error 220 in them. 221 .Pp 222 .Dl # ngrep 'error' port syslog 223 .Pp 224 Print FTP packets that contain the words 225 .Dq user 226 or 227 .Dq pass , 228 case-insensitive. 229 .Pp 230 .Dl # ngrep -wi -d any 'user|pass' port 21 231 .Pp 232 Print all HTTP packets and wrap on newlines: 233 .Pp 234 .Dl # ngrep -W byline port 80 235 .Pp 236 Print HTTP data containing a specific hexadecimal value in hex+ASCII 237 form: 238 .Pp 239 .Dl # ngrep -xX '0xc5d5e5f55666768696a6b6c6d6e6' port 80 240 .Sh SEE ALSO 241 .Xr grep 1 , 242 .Xr hexdump 1 , 243 .Xr pcrepattern 3 , 244 .Xr pcap-filter 5 , 245 .Xr tcpdump 8 246 .Sh AUTHORS 247 .An -nosplit 248 The 249 .Nm 250 utility was written by 251 .An Jordan Ritter Aq Mt jpr5@darkridge.com , 252 and is maintained by 253 .An Stephen Gregoratto Aq Mt dev@sgregoratto.me . 254 .Sh CAVEATS 255 .Nm 256 can get confused about which arguments make up the 257 .Ar expression 258 or the 259 .Ar filter . 260 For example: 261 .Pp 262 .Dl # ngrep not port 80 263 .Pp 264 Here 265 .Nm 266 will print all packets on port 80 containing the word 267 .Dq not , 268 instead of printing all packets that are not on port 80. 269 In cases like this, you will need to specify a blank match expression: 270 .Pp 271 .Dl # ngrep '' not port 80