forked from br101/horst
-
Notifications
You must be signed in to change notification settings - Fork 0
/
horst.1
468 lines (403 loc) · 15.2 KB
/
horst.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
.\" Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH HORST 8 "September 23, 2014"
.\" Please adjust this date whenever revising the manpage.
.SH NAME
horst \- Highly Optimized Radio Scanning Tool
.SH SYNOPSIS
.B horst
.RB [\| \-h \|]
.RB [\| \-q \|]
.RB [\| \-D \|]
.RB [\| \-c
.IR file \|]
.RB [\| \-C
.IR channel \|]
.RB [\| \-i
.IR interface \|]
.RB [\| \-t
.IR sec \|]
.RB [\| \-V
.IR view \|]
.RB [\| \-d
.IR ms \|]
.RB [\| \-b
.IR bytes \|]
.RB [\| \-M
.IR file \|]
.RB [\| \-s \|]
.RB [\| \-u \|]
.RB [\| \-N \|]
.RB [\| \-n
.IR IP \|]
.RB [\| \-p
.IR port \|]
.RB [\| \-o
.IR file \|]
.RB [\| \-X
.IR name \|]
.RB [\| \-x
.IR command \|]
.RB [\| \-e
.IR mac \|]
.RB [\| \-f
.IR pkt_name \|]
.RB [\| \-m
.IR mode \|]
.RB [\| \-B
.IR BSSID \|]
.SH DESCRIPTION
\fBhorst\fP is a small, lightweight IEEE802.11 wireless LAN analyzer
with a text interface. Its basic function is similar to tcpdump,
Wireshark or Kismet, but it's much smaller and shows different,
aggregated information which is not easily available from other
tools. It is mainly targeted at debugging wireless LANs with a focus
on ad\-hoc (IBSS) mode in larger mesh networks. It can be useful to get
a quick overview of what's going on on all wireless LAN channels and
to identify problems.
.IP \[bu] 2
Shows signal values per station.
.IP \[bu] 2
Calculates channel utilization ("usage") by adding up the amount of time the packets actually occupy the medium.
.IP \[bu] 2
"Spectrum Analyzer" shows signal levels and usage per channel.
.IP \[bu] 2
Text-based "graphical" packet history, with signal, packet type and physical rate
.IP \[bu] 2
Shows all stations per ESSID and the live TSF per node as it is counting.
.IP \[bu] 2
Detects IBSS "splits" (same ESSID but different BSSID \- this is a common driver problem).
.IP \[bu] 2
Statistics of packets/bytes per physical rate and per packet type.
.IP \[bu] 2
Has some support for mesh protocols (OLSR and batman).
.IP \[bu] 2
Can filter specific packet types, source MAC addresses or BSSIDs.
.IP \[bu] 2
Client/server support for monitoring on remote nodes.
.IP \[bu] 2
Can be controlled via a named pipe.
.SH OPTIONS
.TP
.BI \-h
Show summary of options.
.TP
.BI \-q
Quiet mode. Don't show user interface. This is only useful in conjunction when running in server mode (\-C) or writing to a file (\-o).
.TP
.BI \-D
Show lot's of debugging output, including a full package dump. Only available when compiled with DEBUG=1.
.TP
.BI \-c\ configfile
Use configfile instead of the default "/etc/horst.conf".
.TP
.BI \-C\ channel
Set inital channel (number not frequency).
.TP
.BI \-i\ intf
Operate on given network interface instead of the default "wlan0". Note that the interface is assumed to be in monitor mode already. See MONITOR MODE below for more information about preparing the network interface.
.TP
.BI \-t\ sec
Timeout (remove) nodes after not receiving packets from them for this time in seconds (default: 60 sec).
.TP
.BI \-V\ view
Display 'view'. Valid view names are "history", "hist", "essid", "statistics", "stats", "spectrum", "spec".
.TP
.BI \-d\ ms
Display update interval. The default value of 100ms can be increased to reduce CPU load caused by redrawing the screen.
.TP
.BI \-b\ bytes
Receive buffer size. The receive buffer size can be set to tune memory consumption and reduce lost packets under load.
.TP
.BI "\-M"filename
MAC address to host name mapping file. The file can either be a dhcp.leases file from dnsmasq or contain mappings in the form "MAC<space>name" (e.g.: "00:01:02:03:04:05 test") line by line (default filename: /tmp/dhcp.leases).
.TP
.BI \-s
Show a poor mans "spectrum analyzer". The same can be achieved by running \fBhorst\fP as normal and pressing the button 's' (Spec); then 'c' (Chan) and 'a' (Automatically change channel).
.TP
.BI \-u
Upper channel limit for the automatic channel change.
.TP
.BI \-N
Allow client connections. Server mode. Only one client connection is supported at the moment (default: off).
.TP
.BI \-n\ IP
Connect to a \fBhorst\fP instance running in server-mode at the specified IP address.
.TP
.BI \-p\ port
Use the specified port (default: 4444) for client/server connections.
.TP
.BI \-o\ filename
Write a information about each received packet into file. Note that you can send to STDOUT by using \fB-o /dev/stdout\fP. See OUTPUT FILE FORMAT below.
.TP
.BI \-X
Accept control commands on a named pipe (default /tmp/horst).
.TP
.BI "\-X"name
Accept control commands on a named pipe with given name or set pipe name used with -x.
.TP
.BI \-x\ command
Send control command to another \fBhorst\fP process who was started with -X and then exit. Multiple commands can be concatenated with ';'. Currently implemented commands are:
pause Pause \fBhorst\fP processing
resume Resume \fBhorst\fP processing
reset Reset all history, statistics and views
channel=X Set channel channel number
channel_scan=X Automatically change channels (1 or 0)
channel_dwell=X Set channel dwell time when automatically changing channel (ms)
channel_upper=X Set max channel when automatically changing channel
outfile=X Write to outfile named X.
If the file is already open, it is cleared and re-openend.
If filename is not specified ("outfile=") any existing file
is closed and no file is written.
And some, but not all options which can be used in the configuration file.
.TP
.BI \-e\ MAC
Filter all MAC addresses except these, to show only packets originating from the specified MAC addresses. This option can be specified multiple times.
.TP
.BI \-f\ pkt_type
Filter all packets except these. This option can be specified multiple times. For valid packet names see NAMES AND ABBREVIATIONS below.
.TP
.BI \-m\ (AP|STA|ADH|PRB|WDS|UNKNOWN)
Only show/include packets and nodes of this mode. Note that the mode is infered by the information of packets we received and it may take some time until a node is properly classified. This option can be specified multiple times.
.TP
.BI \-B\ BSSID
Only show/include packets which belong to the given BSSID.
.SH TEXT USER INTERFACE
The ncurses-based text interface tries to display a lot of information, so it may look confusing at first. Below we describe the different screens and options.
.TP
Main screen
The initial (main) screen is split into three parts. The upper area shows a list of aggregated "node" information, the most useful information about each sender which was discovered, one per line:
/ "Spinner" to show activity
Pk Percentage of this node's packets in relation to all received packets
Re% Percentage of retried frames of all frames this node sent
Cha Channel number
Sig Signal value (RSSI) in dBm
RAT Physical data rate
TRANSMITTER MAC address of sender
MODE Operating Mode (AP, AHD, PRB, STA, WDS), see "NAMES AND ABBREVIATIONS"
ENCR Encryption (WPA1, WPA2, WEP)
ESSID ESSID
INFO Additional info like "BATMAN", IP address...
The lower area shows a scrolling list of packets as they come in:
Cha Channel number
Sig Signal value (RSSI) in dBm
RAT Physical data rate
TRANSMITTER MAC address of sender
BSSID BSSID
TYPE Packet type, see "NAMES AND ABBREVIATIONS"
INFO Additional info like ESSID, TFS, IP address...
The lower right box shows bar graphs for:
Signal of last received packet in green
bps Bits per second of all received packets
Usage Percentage of channel use
The lower edge is the menu and status bar, it shows which keys to press for other screens. The status shows ">" when \fBhorst\fP is running or "=" when it is paused, then "F" when any kind of filter is active, the Channel, the monitor interface in use and the time.
.TP
Pause ('p' or <space>)
Can be used to pause/resume \fBhorst\fP. When \fBhorst\fP is paused it will loose packets received in the mean time.
.TP
Reset ('r')
Clears all history and aggregated statistical data.
.TP
History ('h')
The history screen scrolls from right to left and shows a bar for each packet indicating the signal level. In the line below that, the packet type is indicated by one character (See NAMES AND ABBREVIATIONS below) and the rough physical data rate is indicated below that in blue.
.TP
ESSID ('e')
The ESSID screen groups information by ESSID and shows the mode (AP, IBSS), the MAC address of the sender, the BSSID, the TSF, the beacon interval, the channel, the signal, a "W" when encrytoion is used and the IP address if known.
.TP
Statistics ('a')
The statistics screen groups packets by physical rate and by packet type and shows other kinds of aggregated and statistical information based on packets.
.TP
Spectrum Analyzer ('s')
The "poor mans spectrum analyzer" screen is only really useful when \fBhorst\fP is started with the -s option or the "Automatically change channel" option is selected in the "Chan" settings, or the config option channel_scan is set.
It shows the available channels horizontally and vertical bars for each channel:
Signal in green
Physical rate in blue
Channel usage in orange/brown
By pressing the 'n' key, the display can be changed to show only the average signal level on each channel and the last 4 digits of the MAC address of the individual nodes at the level (height) they were received. This can give a quick graphical overview of the distance of nodes.
.TP
Filters ('f')
This configuration dialog can be used to define the active filters.
.TP
Channel Settings ('c')
This configuration dialog can be used to change the channel changing behaviour of \fBhorst\fP or to change to a different channel manually.
.TP
Sort ('o')
Only active in the main screen, can be used to sort the node list in the upper area by Signal, Time, BSSID or Channel.
.SH NAMES AND ABBREVIATIONS
.TP
802.11 standard frames
Management frames:
a ASOCRQ Association request
A ASOCRP Associaion response
a REASRQ Reassociation request
A REASRP Reassociation response
p PROBRQ Probe request
P PROBRP Probe response
T TIMING Timing Advertisement
B BEACON Beacon
t ATIM ATIM
D DISASC Disassociation
u AUTH Authentication
U DEAUTH Deauthentication
C ACTION Action
c ACTNOA Action No Ack
Control frames:
w CTWRAP Control Wrapper
b BACKRQ Block Ack Request
B BACK Block Ack
s PSPOLL PS-Poll
R RTS RTS
C CTS CTS
K ACK ACK
f CFEND CF-End
f CFENDK CF-End + CF-Ack
Data frames:
D DATA Data
F DCFACK Data + CF-Ack
F DCFPLL Data + CF-Poll
F DCFKPL Data + CF-Ack + CF-Poll
n NULL Null (no data)
f CFACK CF-Ack (no data)
f CFPOLL CF-Poll (no data)
f CFCKPL CF-Ack + CF-Poll (no data)
Q QDATA QoS Data
F QDCFCK QoS Data + CF-Ack
F QDCFPL QoS Data + CF-Poll
F QDCFKP QoS Data + CF-Ack + CF-Poll
N QDNULL QoS Null (no data)
f QCFPLL QoS CF-Poll (no data)
f QCFKPL QoS CF-Ack + CF-Poll (no data)
* BADFCS Bad frame checksum
.TP
Packet types
Similar to 802.11 frames above but higher level and as a bit field (types can overlap, e.g. DATA + IP) and including more information, like IP, ARP, BATMAN, OLSR...
CTRL 0x000001 WLAN Control frame
MGMT 0x000002 WLAN Management frame
DATA 0x000004 WLAN Data frame
BADFCS 0x000008 WLAN frame checksum (FCS) bad
BEACON 0x000010 WLAN beacon frame
PROBE 0x000020 WLAN probe request or response
ASSOC 0x000040 WLAN associaction request/response frame
AUTH 0x000080 WLAN authentication frame
RTSCTS 0x000100 WLAN RTS or CTS
ACK 0x000200 WLAN ACK or BlockACK
NULL 0x000400 WLAN NULL Data frame
QDATA 0x000800 WLAN QoS Data frame (WME/WMM)
ARP 0x001000 ARP packet
IP 0x002000 IP packet
ICMP 0x004000 IP ICMP packet
UDP 0x008000 IP UDP
TCP 0x010000 IP TCP
OLSR 0x020000 OLSR protocol
BATMAN 0x040000 BATMAND Layer3 or BATMAN-ADV Layer 2 frame
MESHZ 0x080000 MeshCruzer protocol
.TP
Operating modes
Bit field of operating mode type which is infered from received packets. Modes may overlap, i.e. it is common to see STA and PRB at the same time.
AP 0x01 Access Point (AP)
ADH 0x02 Ad-hoc node
STA 0x04 Station (AP client)
PRB 0x08 Sent PROBE requests
WDS 0x10 WDS or 4 Address frames
UNKNOWN 0x20 Unknown e.g. RTS/CTS or ACK
.SH MONITOR MODE
\fBhorst\fP should work with any wireleass LAN card and driver which supports monitor mode, with either "prism2" or "radiotap" headers. This includes most modern mac80211-based drivers.
You have to put your card in monitor mode and set the channel manually before
you start \fBhorst\fP. Usually this has to be done as root.
Note that depending on the wireless driver capabilities and versions, signal values and ranges may be different. Also, if the monitor interface is added to an existing interface, the driver does not allow the channel to be changed.
.TP
Using iw:
.nf
iw wlan0 interface add mon0 type monitor
or
sudo iw wlan1 set type monitor
sudo iw wlan1 set channel 6
.fi
.TP
Using iwconfig:
.nf
iwconfig wlan0 mode monitor
iwconfig wlan0 channel 1
ifconfig wlan0 up
.fi
.TP
Using madwifi:
wlanconfig wlan0 create wlandev wifi0 wlanmode monitor
.TP
Using hostap:
.nf
iwconfig wlan0 mode monitor
iwpriv wlan0 monitor_type 1
.fi
.SH OUTPUT FILE FORMAT
The format of the output file (-o flag) is a comma separated list of the following fields in the following order, one packet each line.
.TP
timestamp
Local time, including microseconds (e.g. 2015-05-16 15:05:44.338806)
.TP
packet_type
802.11 MAC packet type name as defined in the section "NAMES AND ABBREVIATIONS".
.TP
wlan_src
Source MAC address
.TP
wlan_dst
Destination MAC address
.TP
wlan_bssid
BSSID
.TP
pkt_types
Higher level packet name as defined in section "NAMES AND ABBREVIATIONS".
.TP
phy_signal
Signal strength in dBm
.TP
wlan_len
Packet length (MAC)
.TP
phy_rate
Physical data rate
.TP
phy_freq
Received while tuned to this frequency.
.TP
wlan_tsf
TFS timer value
.TP
wlan_essid
ESSID, network name
.TP
wlan_mode
Operating modes as defined in "NAMES AND ABBREVIATIONS".
.TP
wlan_channel
Channel number
.TP
wlan_wep
Encryption in use
.TP
wlan_wpa
WPA1 Encryption in use
.TP
wlan_rsn
RSN (WPA2) Encryption in use
.TP
ip_src
IP source address (if available)
.TP
ip_dst
IP destionation address (if available)
.SH SEE ALSO
.BR tcpdump (1),
.BR wireshark (1),
.BR kismet (1),
.BR README,
.BI http://br1.einfach.org/tech/horst
.SH AUTHOR
\fBhorst\fP was written by Bruno Randolf <[email protected]>.
.PP
This manual page was written by Antoine Beaupré <[email protected]>,
for the Debian project (and may be used by others).