horst - Highly Optimized Radio Scanning Tool
] [-C channel
] [-t sec
] [-V view
] [-b bytes
] [-M file
] [-n IP
] [-p port
] [-X name
] [-x command
] [-f pkt_name
] [-m mode
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.
- Shows signal values per station.
- Calculates channel utilization ("usage") by
adding up the amount of time the packets actually occupy the medium.
- "Spectrum Analyzer" shows signal levels and usage
- Text-based "graphical" packet history, with
signal, packet type and physical rate
- Shows all stations per ESSID and the live TSF per node as
it is counting.
- Detects IBSS "splits" (same ESSID but different
BSSID - this is a common driver problem).
- Statistics of packets/bytes per physical rate and per
- Has some support for mesh protocols (OLSR and batman).
- Can filter specific packet types, source MAC addresses or
- Client/server support for monitoring on remote nodes.
- Can be controlled via a named pipe.
- See MONITOR MODE below for more information about the
network interface setup.
- Show version.
- Show summary of options.
- Quiet mode. Don't show user interface. This is only useful
in conjunction when running in server mode (-C) or writing to a file
- Show lot's of debugging output, including a full package
dump. Only available when compiled with DEBUG=1.
- Always add virtual monitor interface. Don't try to set
existing interface to monitor mode.
- -c configfile
- Use configfile instead of the default
- -C channel
- Set inital channel (number not frequency).
- -i intf
- Operate on the given network interface instead of the
- -t sec
- Timeout (remove) nodes after not receiving packets from
them for this time in seconds (default: 60 sec).
- -V view
- Display 'view'. Valid view names are "history",
"hist", "essid", "statistics",
"stats", "spectrum", "spec".
- -d ms
- Display update interval. The default value of 100ms can be
increased to reduce CPU load caused by redrawing the screen.
- -b bytes
- Receive buffer size. The receive buffer size can be set to
tune memory consumption and reduce lost packets under load.
- -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).
- Show a poor mans "spectrum analyzer". The same
can be achieved by running horst as normal and pressing the button
's' (Spec); then 'c' (Chan) and 'a' (Automatically change channel).
- Upper channel limit for the automatic channel change.
- Allow client connections. Server mode. Only one client
connection is supported at the moment (default: off).
- -n IP
- Connect to a horst instance running in server-mode
at the specified IP address.
- -p port
- Use the specified port (default: 4444) for client/server
- -o filename
- Write a information about each received packet into file.
Note that you can send to STDOUT by using -o /dev/stdout. See
OUTPUT FILE FORMAT below.
- Accept control commands on a named pipe (default
- -X name
- Accept control commands on a named pipe with given name or
set pipe name used with -x.
- -x command
- Send control command to another horst process who
was started with -X and then exit. Multiple commands can be concatenated
with ';'. Currently implemented commands are:
Pause horst processing
Resume horst processing
Reset all history, statistics and views
- Set channel channel number
- Automatically change channels (1 or 0)
- Set channel dwell time when automatically changing channel
- Set max channel when automatically changing channel
- 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
- -e MAC
- Filter all MAC addresses except these, to show only packets
originating from the specified MAC addresses. This option can be specified
- -f pkt_type
- Filter all packets except these. This option can be
specified multiple times. For valid packet names see NAMES AND
- -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.
- -B BSSID
- Only show/include packets which belong to the given BSSID.
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
- 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
Percentage of this node's packets in relation to all received packets
Percentage of retried frames of all frames this node sent
Signal value (RSSI) in dBm
Physical data rate
- MAC address of sender
Operating Mode (AP, AHD, PRB, STA, WDS), see "NAMES AND
Encryption (WPA1, WPA2, WEP)
Additional info like "BATMAN", IP address...
The lower area shows a scrolling list of packets as they come in:
Signal value (RSSI) in dBm
Physical data rate
- MAC address of sender
Packet type, see "NAMES AND ABBREVIATIONS"
Additional info like ESSID, TFS, IP address...
The lower right box shows bar graphs for:
- of last received packet in green
- Bits per second of all received packets
- 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 horst
or "=" when it is paused, then "F" when any kind of filter
is active, the Channel, the monitor interface in use and the time.
- Pause ('p' or <space>)
Can be used to pause/resume horst. When horst is paused it
will loose packets received in the mean time.
- Reset ('r')
Clears all history and aggregated statistical data.
- 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.
- 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.
- 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
- Spectrum Analyzer ('s')
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
- 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.
- Filters ('f')
This configuration dialog can be used to define the active filters.
- Channel Settings ('c')
This configuration dialog can be used to change the channel changing
behaviour of horst or to change to a different channel manually.
- 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.
- 802.11 standard frames
||Action No Ack
||Block Ack Request
||CF-End + CF-Ack
||Data + CF-Ack
||Data + CF-Poll
||Data + CF-Ack + CF-Poll
||Null (no data)
||CF-Ack (no data)
||CF-Poll (no data)
||CF-Ack + CF-Poll (no data)
||QoS Data + CF-Ack
||QoS Data + CF-Poll
||QoS Data + CF-Ack + CF-Poll
||QoS Null (no data)
||QoS CF-Poll (no data)
||QoS CF-Ack + CF-Poll (no data)
||Bad frame checksum
- 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,
||WLAN Control frame
||WLAN Management frame
||WLAN Data frame
||WLAN frame checksum (FCS) bad
||WLAN beacon frame
||WLAN probe request or response
||WLAN associaction request/response frame
||WLAN authentication frame
||WLAN RTS or CTS
||WLAN ACK or BlockACK
||WLAN NULL Data frame
||WLAN QoS Data frame (WME/WMM)
||IP ICMP packet
||BATMAND Layer3 or BATMAN-ADV Layer 2 frame
- 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.
||Access Point (AP)
||Station (AP client)
||Sent PROBE requests
||WDS or 4 Address frames
||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
setup it automatically at startup. Usually, root privileges are
required to modify an interface setup.
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
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:
- Using iw:
iw wlan0 interface add mon0 type monitor
sudo iw wlan1 set type monitor
sudo iw wlan1 set channel 6
- Using iwconfig:
iwconfig wlan0 mode monitor
iwconfig wlan0 channel 1
ifconfig wlan0 up
- Using madwifi:
- wlanconfig wlan0 create wlandev wifi0 wlanmode monitor
- Using hostap:
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.
- Local time, including microseconds (e.g. 2015-05-16
- 802.11 MAC packet type name as defined in the section
"NAMES AND ABBREVIATIONS".
- Source MAC address
- Destination MAC address
- Higher level packet name as defined in section "NAMES
- Signal strength in dBm
- Packet length (MAC)
- Physical data rate
- Received while tuned to this frequency.
- TFS timer value
- ESSID, network name
- Operating modes as defined in "NAMES AND
- Channel number
- Encryption in use
- WPA1 Encryption in use
- RSN (WPA2) Encryption in use
- IP source address (if available)
- IP destionation address (if available)
was written by Bruno Randolf <firstname.lastname@example.org>.
This manual page was written by Antoine Beaupré
<email@example.com>, for the Debian project (and may be used by