owlps/doc/owlps-listenerd.t2t

222 lines
7.7 KiB
Plaintext

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)