From a6c9c12a305e6c1277b7346e9b5b4eaa343e142f Mon Sep 17 00:00:00 2001 From: Matteo Cypriani Date: Sun, 23 Jun 2013 21:23:17 -0400 Subject: [PATCH] [doc] Add owlps-listenerd.t2t --- doc/CMakeLists.txt | 1 + doc/owlps-listenerd.t2t | 211 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 212 insertions(+) create mode 100644 doc/owlps-listenerd.t2t diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 039e323..2e59edb 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -56,6 +56,7 @@ add_manpage(owlps 7) add_manpage(owlps-architecture 7) add_manpage(owlps-deployment 7) add_manpage(owlps-client 1) +add_manpage(owlps-listenerd 1) ### Doxygen-generated man pages ### diff --git a/doc/owlps-listenerd.t2t b/doc/owlps-listenerd.t2t new file mode 100644 index 0000000..849392c --- /dev/null +++ b/doc/owlps-listenerd.t2t @@ -0,0 +1,211 @@ +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_ip// ] + [ **-p** //aggregation_port// ] + [ **-A** ] + [ **-I** //autocalibration_ip// ] + [ **-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). It extracts the signal +strength from the captured requests, and forwards them to the +aggregation server (OwlPS Aggregator). 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_ip// + IP address of the aggregation server (default: 127.0.0.1). +: **-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_ip// + Destination IP of the autocalibration requests (default: + //aggregation_ip//). +: **-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? + + + + += 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)