Provided by: horst_4.2-1build1_i386 bug

NAME

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

SEE ALSO

       tcpdump(1),          wireshark(1),          kismet(1),          README,
       http://br1.einfach.org/tech/horst

AUTHOR

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

                              September 23, 2014                      HORST(8)