222 lines
7.7 KiB
Plaintext
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
|
|
http://code.lm7.fr/p/owlps/source/tree/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)
|