| HORST(8) | System Manager's Manual | HORST(8) |
horst - Highly Optimized Radio Scanning Tool
horst [-v] [-h] [-q] [-D] [-a] [-c file] [-C channel] [-i interface] [-t sec] [-V view] [-d ms] [-b bytes] [-M file] [-s] [-u] [-N] [-n IP] [-p port] [-o file] [-X name] [-x command] [-e mac] [-f pkt_name] [-m mode] [-B BSSID]
horst 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.
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.
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:
The lower area shows a scrolling list of packets as they come in:
The lower right box shows bar graphs for:
The lower edge is the menu and status bar, it shows which keys to press for other screens. The status shows ">" when horst 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.
Can be used to pause/resume horst. When horst is paused it will loose packets received in the mean time.
Clears all history and aggregated statistical data.
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.
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.
The statistics screen groups packets by physical rate and by packet type and shows other kinds of aggregated and statistical information based on packets.
The "poor mans spectrum analyzer" screen is only really useful when horst 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:
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.
This configuration dialog can be used to define the active filters.
This configuration dialog can be used to change the channel changing behaviour of horst or to change to a different channel manually.
Only active in the main screen, can be used to sort the node list in the upper area by Signal, Time, BSSID or Channel.
| 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 |
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...
| Packet types | ||
| 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 |
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.
| Operating modes | ||
| 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 |
To capture and analyze 802.11 traffic, the interface needs to be in monitor mode. You can either setup the interface manually beforehand or let horst setup it automatically at startup. Usually, root privileges are required to modify an interface setup.
horst 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.
If the interface is not in monitor mode at startup, horst first tries to put the interface in monitor mode. If it fails (for example when the interface is already in use), a new virtual monitor interface (horst0) is added and used instead. The virtual monitor interface is removed when horst exits. Note that changing the channel via a virtual monitor interface is not allowed by the wireless driver, so options -C and -s do not work when virtual monitor interface is used.
Examples of how to setup an interface manually:
iw wlan0 interface add mon0 type monitor
or
sudo iw wlan1 set type monitor
sudo iw wlan1 set channel 6
iwconfig wlan0 mode monitor iwconfig wlan0 channel 1 ifconfig wlan0 up
iwconfig wlan0 mode monitor iwpriv wlan0 monitor_type 1
Signal values and ranges may differ between wireless drivers and versions.
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.
horst.conf(5), tcpdump(1), wireshark(1), kismet(1), README, http://br1.einfach.org/tech/horst
horst was written by Bruno Randolf <br1@einfach.org>.
This manual page was written by Antoine Beaupré <anarcat@debian.org>, for the Debian project (and may be used by others).
| July 22, 2015 |