man horst (8): Highly Optimized Radio Scanning Tool

SYNOPSIS

horst [-h] [-q] [-D] [-i interface] [-t sec] [-d ms] [-b bytes] [-s] [-u] [-C] [-c IP] [-p port] [-o file] [-X name] [-x command] [-e mac] [-f pkt_name] [-m mode]

DESCRIPTION

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.

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 per channel.
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 packet type.
Has some support for mesh protocols (OLSR and batman).
Can filter specific packet types, source MAC addresses or BSSIDs.
Client/server support for monitoring on remote nodes.
Can be controlled via a named pipe.

OPTIONS

-h

Show summary of options.

-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).

-D

Show lot's of debugging output, including a full package dump. Only available when compiled with DEBUG=1.

-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.

-t sec

Timeout (remove) nodes after not receiving packets from them for this time in seconds (default: 60 sec).

-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.

-s

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).

-u

Upper channel limit for the automatic channel change.

-C

Allow client connections. Server mode. Only one client connection is supported at the moment (default: off).

-c 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 connections.

-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.

-X

Accept control commands on a named pipe (default /tmp/horst).

-Xname

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              Pause horst processing
    resume             Resume horst processing
    channel=X          Set channel channel number
    channel_auto=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.

-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.

-f pkt_type

Filter all packets except these. This option can be specified multiple times. For valid packet names see NAMES AND ABBREVIATIONS below.

-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.

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.

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            Count of packets
        Re%           Percentage of Re-sent frames
        CH            Channel
        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:
        CH            Channel
        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 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.

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 packets.

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.

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.

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.

NAMES AND ABBREVIATIONS

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

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

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

MONITOR MODE

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.

You have to put your card in monitor mode and set the channel manually before you start horst. 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.

Using iw:

iw wlan0 interface add mon0 type monitor
or
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

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.

packet_type

802.11 MAC packet type name as defined in the section "NAMES AND ABBREVIATIONS".

wlan_src

Source MAC address

wlan_dst

Destination MAC address

wlan_bssid

BSSID

pkt_types

Higher level packet name as defined in section "NAMES AND ABBREVIATIONS".

phy_signal

Signal strength in dBm

phy_noise

Noise in dBm (always 0)

phy_snr

Signal to Noise ratio in dB (always 0, redundant)

wlan_len

Packet length (MAC)

phy_rate

Physical data rate

phy_freq

Received while tuned to this frequency.

wlan_tsf

TFS timer value

wlan_essid

ESSID, network name

wlan_mode

Operating modes as defined in "NAMES AND ABBREVIATIONS".

wlan_channel

Channel number

wlan_wep

Encryption in use

wlan_wpa

WPA1 Encryption in use

wlan_rsn

RSN (WPA2) Encryption in use

ip_src

IP source address (if available)

ip_dst

IP destionation address (if available)

olsr_type

OLSR message type (if applicable)

olsr_neigh

OLSR number of neighbours (if applicable)

AUTHOR

horst was written by Bruno Randolf <[email protected]>.

This manual page was written by Antoine Beaupré <[email protected]>, for the Debian project (and may be used by others).