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)