Owl Positioning System Listener
OwlPS {{OWLPS_VERSION}}
June 2013


%%%
% Man title & section:
%!postproc(man): "^(\.TH.*) 1 "  ".TH owlps-listenerd 1 "
% Fix .TH, add NAME section and TABLE OF CONTENTS title:
%!postproc(man): "^(\.TH.*)$"  "\1 OwlPS\ User\ Manual\n.SH NAME\nowlps-listenerd - capture OwlPS positioning requests"
% Man "links":
%!preproc(man): "(owlps)\.t2t" "//\1//(7)"
%!preproc(man): "(owlps-architecture)\.t2t" "//\1//(7)"
%!preproc(man): "(owlps-deployment)\.t2t" "//\1//(7)"
%!preproc(man): "(owlps-[^ ]*)\.t2t" "//\1//(1)"
%!preproc(man): "(owlps[^ ]*\.h)" "//\1//(3)"
%%%




= Synopsis =

**owlps-listenerd** [ **-f** //config_file// ] [ **-G** ]
                [ **-D** ] [ **-v**[**v**[**v**[**v**]] ] | **-q** ]
                < **-r** //rtap_iface// [ **-w** //wifi_iface// ] | **-R** //pcap_file// >
                [ **-K** ] [ **-m** //mode// ]
                [ **-l** //listening_port// ]
                [ **-i** //aggregation_host// ]
                [ **-p** //aggregation_port// ]
                [ **-A** ]
                [ **-I** //autocalibration_host// ]
                [ **-P** //autocalibration_request_port// ]
                [ **-O** //autocalibration_order_port// ]
                [ **-H** //hello_port// ]
                [ **-T** //hello_delay// ]
                [ **-t** //autocalibration_delay// ]
                [ **-n** //autocalibration_nb_packets// ]
                [ //direction// //x// //y// //z// ]




= Description =

**OwlPS Listener** is the program that captures the positioning requests
sent by the mobile terminals (with OwlPS Client, see owlps-client.t2t).
It extracts the signal strength from the captured requests, and forwards
them to the aggregation server (OwlPS Aggregator, see
owlps-aggregatord.t2t). The message sent to the Aggregator is a
structure of type ``owl_captured_request``, as defined in owlps.h.

Technically speaking, OwlPS Listener uses the //pcap// library to
capture IEEE 802.11 frames from a network interface, and the frames'
//radiotap// headers to read the signal strength. Therefore, the capture
interface's driver must be radiotap-enabled; some additional
considerations about hardware choice are given in owlps-deployment.t2t.

The most important and only mandatory parameter to be set by the user is
the capture interface (``-r`` option). Depending on the operating system
and the driver used, this capture interface can be a virtual interface.
In this case, the name of the underlying physical interface must also be
provided (``-w`` option), so that the MAC address and other parameters
can be extracted. The capture interface (or the underlying interface)
must be in monitor mode in order to capture the radio traffic correctly.

Alternatively, OwlPS Listener can “capture” packets from a capture file
in the //pcap// format (``-R`` option), created by a network sniffer
such as //tcpdump// or //Wireshark//. This can be useful for testing,
debugging and to replay scenarios.




= Options =

== Main options ==

: **-h**
  Print help message and exit.
: **-V**
  Print version information and exit.
: **-f** //config_file//
  Use //config_file// instead of the default configuration file. This
  option is available only if the program was compiled with support of
  configuration files.
: **-G**
  Dump the configuration on the standard output and exit. This is useful
  to generate a configuration file with default values, possibly
  modified from the current set of options. The configuration file
  (either the default one if it exists or specified with the **-f**
  option) is read and the options it contains will be taken into
  account.
: **-D**
  Daemon mode (fork to the background).
: **-v**
  Be verbose. You can use this option up to 4 times to increase the
  level of verbosity:
  - 0 = errors and important warnings
  - 1 = more warnings
  - 2 = useful information
  - 3 = a lot of information
  - 4 = display each captured packet corresponding to a request
: **-q**
  Quiet mode (default): sets the verbose level to 0 (cf. verbose levels
  above).


== Capture options ==

: **-m** //mode//
  Capture mode (please note that this feature is in an experimental
  shape and is implemented only as a proof of concept or to help
  debugging). The mode can be //a// (default), //p// or //m//:
  - In //a(ctive)// mode, only explicit requests sent by the mobiles
    (and the other capture points) are captured.
  - In //p(assive)// mode, all the packets sent by every device
    connected to the network are captured; the information contained in
    potential explicit requests are not parsed, all the packets are
    considered alike.
  - In //m(ixed)// mode, all the packets sent by every device are
    captured, like in passive mode, but the explicit requests are parsed
    like in active mode.
: **-l** //listening_port//
  Port to which explicit positioning requests are sent by the mobiles
  (default: 9900).
: **-i** //aggregation_host//
  Host name or IP address of the aggregation server (default:
  localhost).
: **-p** //aggregation_port//
  Port to which the captured requests are transmitted to the aggregation
  server (default: 9901).
: **-r** //rtap_iface//
  Radiotap-enabled capture interface.
: **-w** //wifi_iface//
  Physical interface corresponding to //rtap_iface//, in case the
  capture interface is a virtual interface (default: //rtap_iface//).
: **-R** //pcap_file//
  Pcap file to read packets from.


== Autocalibration options ==

These options are available only if the program was compiled with
support of the POSIX threads.

: **-A**
  Enable autocalibration (default: disabled).
: **-I** //autocalibration_host//
  Host name or IP address of the destination of the autocalibration
  requests (default: //aggregation_host//).
: **-P** //autocalibration_request_port//
  Port to which autocalibration requests are sent (default:
  //listening_port//).
: **-O** //autocalibration_order_port//
  Port on which autocalibration orders are received from the aggregation
  server (default: 9904).
: **-H** //hello_port//
  Port to which hello messages are sent to the aggregation server
  (default: 9903).
: **-T** //hello_delay//
  Time between two hello messages sent to the aggregation server, in
  seconds (default: 15 s).
: **-t** //autocalibration_delay//
  Time between the packets' transmissions of an autocalibration request,
  in milliseconds (default: 25 ms).
: **-n** //nb_packets//
  Number of packets transmitted for one autocalibration request
  (default: 20).
: //direction// //x// //y// //z//
  The coordinates of the capture point, to be transmitted in
  autocalibration requests. //direction// is an integer;
  //x//, //y//, //z// are floating-point numbers. This is absolutely
  optional, and actually the preferred way of dealing with capture
  points' coordinates is in the positioning server itself.


== Miscelanneous options ==

: **-K**
  Force the monitor mode to stay active on //wifi_iface//. Use this with
  buggy drivers that disable the monitor mode periodically. This option
  is available only if the program was compiled with the adequate
  compilation-time option and linked against //iwlib//; it is therefore
  Linux-specific, but BSD systems don't have buggy drivers, right?




= Files =

: //{{INSTALL_PREFIX}}/etc/owlps/owlps-listener.conf//
  Default configuration file (when compiled with support of
  configuration files).




= Copying =

This documentation is part of the Owl Positioning System (OwlPS)
project. It is subject to the copyright notice and license terms
in the COPYRIGHT.t2t file found in the top-level directory of the
OwlPS distribution and at
https://code.lm7.fr/mcy/owlps/src/master/COPYRIGHT.t2t




= Online ressources =

- Radiotap website:
  http://www.radiotap.org/




= See also =

owlps.t2t, owlps-architecture.t2t, owlps-deployment.t2t,
//pcap//(3), //ieee80211_radiotap//(9)
