Provided by: horst_5.1-2_amd64 bug

NAME

       horst - Highly Optimized Radio Scanning Tool

SYNOPSIS

       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]

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.

       See MONITOR MODE below for more information about the network interface setup.

OPTIONS

       -v     Show version.

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

       -a     Always add virtual monitor interface.  Don't  try  to  set  existing  interface  to
              monitor mode.

       -c configfile
              Use configfile instead of the default "/etc/horst.conf".

       -C channel
              Set inital channel (number not frequency).

       -i intf
              Operate on the given network interface instead of the default "wlan0".

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

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

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

       -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
                     Pause horst processing

              resume
                     Resume horst 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.

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

       -B BSSID
              Only show/include packets which belong to the given BSSID.

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

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

                                       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

       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.

                            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

MONITOR MODE

       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:

       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

NOTES

       Signal values and ranges may differ between wireless drivers and versions.

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.

       timestamp
              Local time, including microseconds (e.g. 2015-05-16 15:05:44.338806 +0300)

       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

       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)

SEE ALSO

       horst.conf(5),        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).

                                          July 22, 2015                                  HORST(8)