<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kwifimanager "<application>KWiFiManager</application>">
  <!ENTITY LAN "<acronym>LAN</acronym>">
  <!ENTITY kappname "&kwifimanager;">
  <!ENTITY package "kdenetwork">
  <!ENTITY % English "INCLUDE"> <!-- change language only here -->
  <!ENTITY % addindex "IGNORE">
]>

<book lang="&language;">

<bookinfo>
<title>The &kwifimanager;-handbook</title>

<authorgroup>
<author> <firstname>Stefan</firstname> <surname>Winter</surname>
<affiliation> <address><email>mail@stefan-winter.de</email>
</address> </affiliation> </author>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<legalnotice>&FDLNotice;</legalnotice>

<copyright>
<year>2002</year>
<holder>Stefan Winter</holder>
</copyright>

<date>2003--10-22</date>
<releaseinfo>1.0.0</releaseinfo>

<abstract>
<para>The &kwifimanager; suite can be used to configure and monitor wireless &LAN; cards.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>wireless</keyword>
<keyword>Wi-Fi</keyword>
<keyword>wlan</keyword>
<keyword>wlan-ng</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>
The &kwifimanager; suite is a set of tools which allows you to manage
your wireless &LAN; PC-Card under the K Desktop Environment. It
provides information about your current connection and lets you set up
up to four independent configurations which can be loaded
automatically when &kde; is started. &kwifimanager; supports every
wireless &LAN; card that uses the wireless extensions interface. This
includes many cards that are supported by the wlan-ng project.
</para>
</chapter>

<chapter id="using">
<title>Using the &kwifimanager; suite</title>

<sect1 id="kwifimanager-application">
<title>The &kwifimanager; application</title>
<para>
Purpose of the main &kwifimanager; application is to show the currently
set configuration and to display connection quality and access
points.
</para>

<para>The main application is launched by either typing
<userinput>kwifimanager</userinput> at the command prompt of a console
window or via the K Menu, where it is located by default in the
<guisubmenu>Applications</guisubmenu> group. Finally, a third way to
launch &kwifimanager; is by clicking once on the <link
linkend="panel-applet">panel applet</link>.  The &GUI; elements of the
application are explained in the following subsections.
</para>

<sect2 id="kwifimanager-main">
<title>Main window</title>

<para>
The &kwifimanager; main window consists of four major parts:
</para>

<sect3 id="signalquality">
<title>Signal quality display</title>
<para>
Here you can see the quality and type of the active
connection. The uppermost icon displays the general state of the wireless
network via a set of pictograms:
<itemizedlist>
<listitem><para>
a PC-Card with a question tag means that no card was detected
</para></listitem>
<listitem><para>
a single laptop means that a PC-Card is inserted and in Infrastructure mode, but there is no radio signal from access-points. The card is out of range.
</para></listitem>
<listitem><para>
a laptop that is connected to a white box means that a connection to an access point is established.
</para></listitem>
<listitem><para>
two laptops mean that your system is in Ad-Hoc mode without access points
</para></listitem>
</itemizedlist>
</para>
<para>
Below these pictograms is a small quality meter. It displays, in a
cellular-like manner, the quality level of the current connection.
This information is only available in Infrastructure mode. In Ad-Hoc
mode, the level is always 0.
</para><para>
This graphical information is supplemented by an integer value below the
icon. It shows the signal quality, and is computed in the following way:
<literal>signal strength in dBm - noise level in dBm</literal>
If your card is out of range, the value is 0; if no card is inserted it
will show N/A.
</para>
</sect3>
<sect3 id="speed">
<title>Connection speed</title>
<para>
A indicator for the current connection speed is shown at the right-hand side of
the main window above the configuration info. If the speed settings are set to
AUTO, the value will change once in a while as the card adjusts the connection
speed according to the signal quality.
</para>
</sect3>
<sect3 id="current-config">
<title>Current configuration</title>

<para>Here you can find information about your card configuration. It
displays the following information:</para>

<itemizedlist>
<listitem><para>
the network with which the card is connected / tries to connect (<guilabel>Searching for network:</guilabel> or <guilabel>Connected to network:</guilabel>)
</para></listitem>
<listitem><para>
the <acronym>MAC</acronym> address of the access point to which the card is connected.</para><para>
If the card is in Infrastructure mode but out of range, the value
<computeroutput>44:44:44:44:44:44</computeroutput> is displayed to indicate that no connection
is established.</para><para>
In Ad-Hoc mode, the field shows an address that is associated with one of the cards in the Ad-Hoc network.
It differs from the MAC address of that card in the second digit: it
is raised by the value of <quote>2</quote>.</para>
<informalexample>
<para>
Your card is the first card that enters Ad-Hoc mode. Then all other
cards entering Ad-Hoc mode will see your MAC-address, slightly
modified: instead of
<computeroutput>00:xx:yy:zz:aa:bb</computeroutput> it will show
<computeroutput>02:xx:yy:zz:aa:bb</computeroutput>. This behavior is
intentional.
</para>
</informalexample>
</listitem>
<listitem><para>
on most cards, the frequency on which the card is transmitting data and
the corresponding channel number is displayed.
</para></listitem>
<listitem><para>
your local IP address, if available.
</para></listitem>
<listitem><para>
encryption status (only if you have started &kwifimanager; as
<systemitem class="username">root</systemitem>)
</para></listitem>
</itemizedlist>

</sect3>
<sect3 id="ap-info">
<title>Access Point information (bottom area)</title>
<para>
The last line of the main window shows information about your AccessPoint.
This requires that your system administrator provided a list of MAC addresses
with a corresponding information. An example for such a list can be found
in
<filename>$<envar>KDEDIR</envar>/share/apps/kwifimanager/locations/DE_BW_Karlsruhe_University.loc</filename></para>

<para>If you want to set up a new list, simply copy your file into the
folder <filename
class="directory">$<envar>KDEDIR</envar>/share/apps/kwifimanager/locations/</filename></para>

<para>It will be automatically parsed at the next start of
&kwifimanager; after a successful installation. If you have
a list and want to have it included in future releases of
&kwifimanager;, simply send it to <email>mail@stefan-winter.de</email>
</para>
</sect3>
</sect2>
<sect2 id="statistics">
<title>Statistics Viewer</title>
<para>
Optionally, by selecting <guimenuitem>Connection
statistics</guimenuitem> in the <guimenu>File</guimenu> menu, a
separate window can be shown which displays the signal level and noise
level graphs of the last 240 seconds. The signal level is displayed in
blue and the noise level in red. The difference (SIGNAL minus NOISE)
is the connection quality which is displayed in the main window.
</para>
</sect2>
<sect2 id="config-edit">
<title>Configuration Editor</title>
<para>
By selecting
<menuchoice><guimenu>Config</guimenu><guimenuitem>Configuration
Editor</guimenuitem></menuchoice> you are taken to the <link
linkend="control-center">control center module</link> of
&kwifimanager;. In case you are not the <systemitem
class="username">root</systemitem> user, a window will pop up
requesting the <systemitem class="username">root</systemitem>
password. This is because the configuration module contains sensitive
information such as the encryption key for <acronym>WEP</acronym>
cryptography.</para>

</sect2>
<sect2 id="misc">
<title>Miscellaneous</title>
<para>There are some minor additional things to be said.</para>

<para>First, there is a feature named <guilabel>Acoustic
Scanning</guilabel>. If this option is enabled, the connection quality
is converted into an acoustic signal. A higher signal quality leads to
a higher frequency of the <quote>beep</quote> output and to a more
rapid beeping. If you've ever seen the Star Trek(tm) series you will
see some parallels to their <quote>tricorders</quote></para>

<para>A second feature is <guilabel>silent logging</guilabel>. It just
means that &kwifimanager; will log the name of the network you are
connecting to every time your network changes. This option is most
useful when searching for the special network name <quote>ANY</quote>.
In this mode, the card will log into any network it finds. The
logfile's position is <filename
class="directory">$<envar>HOME</envar>/.wireless-log</filename></para>

<para>The third thing is just a note: In the <guimenu>File</guimenu>
menu, there is an entry <guimenuitem>Disable radio</guimenuitem>. This
option is <emphasis>not implemented</emphasis>. The problem is in the
kernel drivers for Wi-Fi cards. The driver simply doesn't support it
at this time.</para>

</sect2>
</sect1>

<sect1 id="panel-applet">
<title>The panel applet</title>
<para>
The panel applet is the second part of the &kwifimanager; suite. It
can <quote>dock</quote>" into &kde;'s panel (&kicker;). It only
displays the signal quality as icon and as text (see 3.1.1.1 for
details).</para>

<para>With it's light-weight size it is best suitable for
continuous use. If you don't want the &kwifimanager; main application
on your screen all the time, just use the applet.</para>

<sect2 id="applet-launch">
<title>Launching the applet</title>

<para>The panel applet can be added to your panel by &RMB; clicking on
the panel and selecting
<menuchoice><guisubmenu>Add</guisubmenu><guisubmenu>Applet</guisubmenu><guimenuitem>KWiFiManager
applet</guimenuitem></menuchoice>. Another way to start the applet is
to click on its desktop file, which can be found on your disk in the
folder <filename
class="directory">$<envar>KDEDIR</envar>/share/apps/kicker/applets</filename>.
That way it will not dock into the panel but free-float on your
desktop. However, the first method is easier and should be
preferred.</para>

<para>The panel applet can be minimally configured: it can optionally
flash in yellow, orange and red colors when the signal quality level
is very low. To enable or disable this feature, &RMB; click on the
applet's <quote>handle</quote> beside the icon and select
<guimenuitem>Personal Settings</guimenuitem>.</para> 
</sect2>
<sect2 id="applet-tooltip">
<title>Tooltip information</title>
<para>If you hover above the applet for a few seconds, you will be
shown a tooltip with a few additional information, namely:
<itemizedlist>
<listitem><para>your local IP address</para></listitem>
<listitem><para>the network name, if one is set</para></listitem>
</itemizedlist>
</para>
</sect2>
<sect2 id="main-from-applet">
<title>Starting &kwifimanager; main application from the panel applet</title>
<para>
A single click on the applet launches (either with &LMB; or &RMB;
click, as you prefer) the &kwifimanager; main application. 
</para>
</sect2>
</sect1>
<sect1 id="control-center">
<title>The Control Center module</title>

<para>The configuration module in the &kcontrolcenter; is perhaps the
most useful part of the &kwifimanager; suite. Here you can actually
change the basic settings of your wireless &LAN; card. The module can
manage up to four independent configurations for the card, and it can
even automatically set your card up whenever you log into &kde;.
Since establishing a network connection is a possible security hazard,
any changes to the configuration can only be done by <systemitem
class="username">root</systemitem>.</para>

<sect2 id="configuration-tab">
<title>The Configuration Tabs</title>

<para>The upper part of the control center module consists of four
tabs labelled <guilabel>Config 1</guilabel> through <guilabel>Config
4</guilabel>. Each of these tabs can hold a configuration for your
WLAN card.</para> 

<para>The most important settings are always visible, the cryptography
and power management options are only shown when activated.  The
perhaps most important element in each configuration tab is the field
<guilabel>Network name</guilabel>. Here you can specify which network
you would like to log into. You can either specify the name of your
network directly, or you can try a scan on all available networks by
setting the network name to <userinput>ANY</userinput>.</para>

<para>In addition to the network name, you have to specify the type of
network to log into. That's the purpose of the button group
<guilabel>Operation mode</guilabel>.  The option
<guilabel>Infrastructure</guilabel> means that the network consists of
designated base station, so-called <quote>access points</quote> or
<quote>residential gateways</quote>. This is the most common operation
mode for company networks. The second option,
<guilabel>peer-to-peer</guilabel> means that your network is just a
direct connection between computers, without access points.</para>

<para>Yu can optionally set the connection speed for your
connection. The setting <guilabel>auto</guilabel> should do for most
uses, since the card will determine the appropriate speed
itself. However, if you find that the speed changes every few seconds,
for example when you have a weak connection, you can set the speed
manually.</para>

<para>Below these configuration items you will find a field named
<guilabel>Execute script on connect:</guilabel>. Here you can enter
the name of a script to execute. It will be executed whenever you hit
the <guilabel>Activate configuration</guilabel> button and,
optionally, automatically when you start the Control Center
module. The script will have root rights.  This may lead to problems
if you want to start an X application in the script and the X server
belongs to someone else than root. You can make such scripts work
correctly if you execute the X application via
<userinput><command>kdesu</command> <option>-u</option>
<replaceable>USERNAME</replaceable> <option>-c</option>
<replaceable>COMMAND</replaceable></userinput>.</para>

<para>The lower part of each configuration tab holds the cryptography
settings. These settings are only shown if you check the box
<guilabel>Use cryptography?</guilabel>. If shown, you are presented
with numerous options: </para>

<variablelist>
<varlistentry>
<term><guilabel>Key to use:</guilabel></term>
<listitem><para>You can define up to four secret keys for each
configuration, in this field you can set which one you actually want
to use to encrypt network traffic</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Crypto mode:</guilabel></term>
<listitem><para>When encryption is activated, there are two ways to
deal with incoming non-encrypted packets: discard or allow. When you
set your card for <guilabel>Open mode</guilabel>, the card will also
listen to non-encrypted packets. <guilabel>Restricted mode</guilabel>
will only allow encrypted network packets, any other packets are
discarded.</para></listitem> 
</varlistentry>
<varlistentry>
<term><guilabel>Crytpo keys:</guilabel></term>
<listitem><para>This box lets you specify the secret keys to use for
cryptography. The small box <guilabel>String?</guilabel> sets whether
the key you enter to right is either a string like
<userinput>MY_CRYPTO</userinput>, or, if not checked, a hex value like
<userinput>0A2FEE91</userinput>. To protect your passwords, only
asterisks will be shown when you enter a password.</para></listitem>
</varlistentry>
</variablelist>

<para>Be aware that the built-in cryptography support (named WEP for
Wireless Equivalent Privacy) is not very safe at all. See <xref
linkend="wep"/> for details.</para>

<para>The last configuration element that remains to be described is
the power management. When checking the box <guilabel>Enable Power
Management</guilabel> you will be presented some options that can help
you save energy. The first two input fields named <guilabel>Sleep
duration (ms)</guilabel> and <guilabel>Awaken time (ms)</guilabel>
describe the periodicity of network scans for your wireless &LAN;
card. The card will turn the radio antenna off for the time period in
milliseconds specified in <guilabel>Sleep
duration</guilabel>. Afterwards it will be active for <guilabel>Awaken
time</guilabel> and will in that time scan for a network
connection. If no network connection is found, it will go to sleep
again and the cycle begins again.  The box named <guilabel>Receive
packets</guilabel> below lets you specify which packets the card
should listen to when awaken. You can either select <guilabel>Unicast
only</guilabel> (which will only let your card listen to packets sent
specifically to your card), <guilabel>Multi/Broadcast only</guilabel>
(will only listen to packets sent to multiple machines and discard
packets directed to your card) or <guilabel>Both</guilabel>. Most
people should select the default value <guilabel>Both</guilabel>.
</para>

</sect2>

<sect2 id="auto-configuration">
<title>Auto-configuration on &kcontrolcenter; Module startup</title>

<para>
If you wish, you can make &kwifimanager; initialize your wireless
&LAN; card whenever you start the &kcontrolcenter;Module. To do so,
check the box <guilabel>Load preset configuration on Control Center
Module startup</guilabel> and select the number of the configuration
you want to use in the listbox below. If you want to set the card to
these settings at once, push the button <guilabel>Activate
configuration</guilabel>.</para>
</sect2>

<sect2 id="autodetect">
<title>Autodetecting your device</title>

<para>&kwifimanager; needs to know the interface name of your wireless
&LAN; card to change any settings. You can either enter the
information (&eg; <userinput>eth1</userinput> or
<userinput>wlan0</userinput>) manually in the input field right of
<guilabel>Settings apply to interface:</guilabel>, or let &kwifimanager;
auto-detect the interface. To do so, push the button 
<guibutton>Autodetect interface</guibutton>. This will perform a scan
on all interfaces listed in <filename
class="directory">/proc/net/dev</filename> to find your card. The
result of the scan will show up in the input field beside the
button. If the field remains empty, no card was found.
Please note that &kwifimanager; uses the wireless extensions to detect
cards. If you use a card controlled by the wlan-ng package,
&kwifimanager; only shows correct results if your driver has a
compatibility layer for the wireless extensions built-in.</para>
</sect2>
</sect1>
</chapter>

<chapter id="credits">
<title>License and contributors</title>
<para>Documentation and application copyright &copy; Stefan Winter
<email>mail@stefan-winter.de</email>.</para>

&underFDL;
&underGPL;

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

</chapter>
<appendix id="further-information">
<title>Further Information</title>

<para>This appendix contains some extra information of items
concerning wireless &LAN; that are not directly related to
&kwifimanager;.</para>

<sect1 id="macaddress">
<title>Notes on the MAC address display in Ad-hoc mode</title>

<para>At first glance, the MAC address in the field <guilabel>Access
Point</guilabel> seems to be wrong in Ad-hoc mode because it changes
the first two bytes of the MAC address to
<computeroutput>02</computeroutput>. But actually, this is a hardcoded
feature in wireless &LAN; cards.</para>

<para>Usually a card is connected to a <quote>real</quote>" access point. Then the correct MAC address is shown. If you change to
Ad-hoc (or <quote>Peer-to-peer</quote>) mode, one of the computers
must act as a server for the other computers. The first computer that
enters a network, will set itself as server. So, all other computers
connecting to the same Ad-hoc network will see that first computer as
network server. But since this computer is not a <quote>real</quote>
server (that is, it is not a permanently available access point),
clients should be aware that the network they are connecting to is not
a permanent one. IEEE standards for MAC addresses have a place
reserved for such occasions: MAC addresses that are not globally valid
have <quote>02</quote> as the first two bytes (these addresses are
called <quote>locally administered</quote> addresses). </para>
<para>You can compare this to the non-global IP addresses like
<quote>192.168.*.*.</quote></para>
<para>So, the implementors of wireless networking agreed to give these
<quote>virtual</quote> network servers a MAC address that is within
the <quote>locally administered</quote> scope. To keep this virtual
MAC address unique, they used a little trick: they only changed the
first two bytes of the MAC address of the wireless &LAN; card, and
since the remaining ten bytes are still unique in the world, they have
a unique address to use as network server.</para>

</sect1>

<sect1 id="wep">
<title>Security considerations on <acronym>WEP</acronym> cryptography</title>

<para><acronym>WEP</acronym> cryptography is not very secure at all. A
recent paper from cryptography analysts called the encryption
algorithm <quote>kindergarten cryptography</quote>. Actually, software
exists that exploits a huge security hole in the encryption
standard. This software listens to the encrypted network traffic,
analyzes it, and after only a few hours it reveals the password to
enter the network in clear text. The more traffic on the network, the
easier it is to find out the password.</para>

<para>If you are truly concerned about your security, do
<emphasis>not</emphasis> use <acronym>WEP</acronym>. If you are just
setting up a two-computer home network, well, then I guess
<acronym>WEP</acronym> should do.</para>

<para>There are many alternatives to <acronym>WEP</acronym>
encryption. You could only use <acronym>SSH</acronym> to communicate
over the network. <acronym>SSH</acronym> is a program suite that
encrypts data with its own algorithm, which is very secure. Another
option is to use <acronym>PPTP</acronym>, the Point-to-Point-Tunneling
protocol. However, even <acronym>PPTP</acronym> seems to be a bit
leaky concerning encryption security. And finally, you could set up an
IPSec tunnel for your encrypted connections. As of yet, this
encryption seems to be very safe and flexible.</para>

</sect1>
</appendix>

<appendix id="compile">
<title>Compilation and Installation</title>

&install.intro.documentation;
&install.compile.documentation;

</appendix>

&documentation.index;
</book>
