path: root/wavemon.1

.TH wavemon 1 "March 2012" Linux "User Manuals"
.SH NAME
wavemon \- a wireless network monitor
.SH SYNOPSIS
.B wavemon [-h] [-i
.I ifname
.B ] [-l] [-r] [-v]
.SH DESCRIPTION
\fIwavemon\fR is a ncurses-based monitoring application for wireless network
devices. It plots levels in real-time as well as showing wireless and network
related device information. Currently, wavemon is still based on the wireless
extensions by Jean Tourrilhes <jt@hpl.hp.com>.

The \fIwavemon\fR interface splits into different "screens".
Each screen presents information in a specific manner. For example, the
"info" screen shows current levels as bargraphs, whereas the "level" screen
represents the same levels as a moving histogram.

On startup, you'll see (depending on configuration) one of the different
monitor screens. At the bottom, you'll find a \fImenu-bar\fR listing the
screens and their function key names.  The following screens can be selected:
.TP
.B Info (F1)
This is the most comprehensive screen. It displays a condensed overview of
wireless-specific parameters and network statistics, as well as bar graphs.
The layout is arranged into several sub-sections.

The
.B Interface
section at the top shows information about the monitoring interface,
including interface name, type, ESSID, and available encryption formats.

Below, in the
.B Levels
section, you can see up to four bargraphs showing (1) relative signal quality
and (2) signal level in dBm. If the wireless driver also supports noise level
information, additionally (3) noise level in dBm and (4) Signal-Noise-Ratio
(SNR) in dB are shown.  The colour of the signal level bargraph changes
from red to yellow and green at fixed levels. If thresholds have been set,
two arrows on the signal level graph will show the positions of the current
thresholds.

The
.B Statistics
section displays packet and byte counters and a few other packet-related
statistics.

The subsequent
.B Info
subsection lists the current operational mode and configuration of the
wireless interface. What parameters are actually shown depends on the
capabilities and selected mode of your network device.

Lastly, the
.B Network
section shows network-level parameters. The MAC-address is resolved from
\fBethers\fR(5). The IPv4 address is shown in CIDR notation (RFC\ 4632
\fIaddress\fR\fB/\fR\fIprefix_len\fR format). Since often those two values
also determine the broadcast address (last 32 \- \fIprefix_len\fR bits set
to 1), that address is shown only if it does not derive from the interface
address and prefix length. Likewise, the interface MTU is shown only if it
differs from the default Ethernet MTU of 1500 bytes.

Another keyboard shortcut for this screen is '\fIi\fR'.
.TP
.B Level histogram (F2)
This is a full-screen histogram plot showing the evolution of levels with time.
The screen is partitioned into a grid, with dBm levels shown in green at
the right hand side (depending on configuration).  At the very minimum,
the evolution of the signal-level is shown. If the wireless driver also
supports noise-level information, additionally a noise graph and associated
SNR graph appear.
.TP
.B Scan window (F3)
A periodically updated network scan, showing access points and other
wireless clients, ordered by frequency and then descending order of signal
quality. Each entry starts with the ESSID, followed by the colour-coded MAC
address and the signal/channel information. A green/red MAC address indicates
an (un-)encrypted access point, the colour changes to yellow for non-access
points (in this case the mode is shown at the end of the line). The
uncoloured information following the MAC address lists relative and
absolute signal strengths, channel, frequency, and the mode if the node
is not an access point.

Please note that gathering meaningful scan data can take several seconds. Partly
for this reason, the Scan window is the only screen that can not be suspended
(CTRL-Z).
.TP
.B Preferences (F7)
This screen allows you to change all program options such as interface and
level scale parameters, and to save the new settings to the configuration
file. Select a parameter with <up> and <down>, then change the value with
<left> and <right>. Please refer to \fBwavemonrc\fR(5) for an in-depth
description of applicable settings.
.TP
.B Help (F8)
This page might show an online-help.
.TP
.B About (F9)
Release information and contact URLs.
.TP
\fBQuit (F10)
Exit \fIwavemon\fR. An alternative shortcut for quitting is '\fIq\fR'.
.LP
\fBNote:\fR some operations, such as displaying encryption information or performing scans, require
\fBCAP_NET_ADMIN\fR privileges (see \fBcapabilities\fR(7)). For non-root users, these can be
enabled by installing \fIwavemon\fR setuid-root.
.SH "OPTIONS"
.IP "\fB\-i \fIinterface\fR\fR"
override autodetection and use the specified \fIinterface\fR.
.IP "\fB\-d\fR"
dump interface parameters to stdout and exit.
.IP "\fB\-g\fR"
check screen \fIgeometry\fR: a minimum size is required for proper display; this flag
adds a check to ensure it is sufficiently large. Enable this if window does not display
properly.
.IP "\fB\-r\fR"
generate random levels (for testing purposes).
.IP "\fB\-h\fR"
print help and exit.
.IP "\fB\-v\fR"
print version information and exit.

.SH "ENVIRONMENT VARIABLES"
.IP "LC_NUMERIC"
Influences the grouping of numbers if set. See also \fBlocale\fR(1).
.SH FILES
.IP $HOME/.wavemonrc
The local per-user configuration file.
.SH "AUTHOR"
Written by Jan Morgenstern <jan@jm-music.de>.
.SH "REPORTING BUGS"
Send bug reports and/or suggestions to Gerrit Renker <gerrit@erg.abdn.ac.uk>.
.SH "COPYRIGHT"
This is free software with ABSOLUTELY NO WARRANTY. See file COPYING for details.
.SH "SEE ALSO"
.BR wavemonrc (5),
.BR wireless (7),
.BR ethers (5),
.BR locale (1),
.BR capabilities (7)