From bcb704366cb5e333a626c18c308c7e0448a8e69f Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/kwifimanager/Makefile.am | 4 + doc/kwifimanager/index.docbook | 549 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 553 insertions(+) create mode 100644 doc/kwifimanager/Makefile.am create mode 100644 doc/kwifimanager/index.docbook (limited to 'doc/kwifimanager') diff --git a/doc/kwifimanager/Makefile.am b/doc/kwifimanager/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/kwifimanager/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kwifimanager/index.docbook b/doc/kwifimanager/index.docbook new file mode 100644 index 00000000..07cc908d --- /dev/null +++ b/doc/kwifimanager/index.docbook @@ -0,0 +1,549 @@ + +KWiFiManager"> + LAN"> + + + + +]> + + + The &kwifimanager; Handbook + + + Stefan + Winter + +
+ swinter@kde.org +
+ + + + + &FDLNotice; + + 2002-05 + Stefan Winter + + 2005--05-11 + 3.5.0 + + The &kwifimanager; suite can be used to configure and monitor wireless &LAN; + cards. It consists of a stand-alone application and a module for the &kde; Control + Center. + + + KDE + wireless + Wi-Fi + wlan + WEP + wlan-ng + + + + Introduction + The &kwifimanager; suite is a set of tools which allows you to manage your wireless + &LAN; Network Interface card (PC-Card, PCI or miniPCI) under the K Desktop Environment. It + provides information about your current connection and lets you set up up to ten independent + configurations and use up to four configrations that are pre-configured by distribution-specific + scripts. If you are in a place where none of your preconfigured networks is available, + you can also dynamically switch to an available network with almost no configuration effort. + &kwifimanager; supports every wireless &LAN; card that uses the wireless extensions + interface. This includes virtually all wireless &LAN; cards that are operational at all + under the &Linux; operating system. + + + Using the &kwifimanager; suite + + The &kwifimanager; application + Purpose of the main &kwifimanager; application is to show the currently active + network configuration and to display connection quality and access points. + The main application is launched by either typingkwifimanager at + the command prompt of a console window or via the K Menu, where it is located by default in + theApplications group. If &kwifimanager; is already running + but minimised to the system tray then it can be restored by clicking once on the system tray icon. If there is more than one wireless &LAN; + card in your system, just open more than one instance of &kwifimanager;: every instance + will show information about a different card automatically. + The &GUI; elements of the application + are explained in the following subsections. + + Main window + The &kwifimanager; main window consists of five parts: + + Signal quality display + 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: + + a wireless &LAN; card with a question tag means that no card was detected + or its state could not be determined + + + a single laptop means that a wireless &LAN; card is inserted and in + Infrastructure mode, but there is no radio signal from access-points. The card is + out of range and can not communicate to the infrastructure network. + + + a laptop that is connected to an access point means that a connection to an + access point is established. + + + two laptops mean that your system is in Ad-Hoc mode without access points. It + may or may not have established a Peer-to-Peer connection. + + + + 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. + This graphical information is supplemented by an integer value below the icon. It + shows the signal quality, and is computed in one of two ways: + + a directly reported value from the card if the card supports + Quality reporting + + + + (signal strength in dBm) - (noise level in dBm) for cards that + do not support that. + + You can manually change the method used by turning + File, Use alternate strength calculation + on or off. Turning the option on means to use the second method. If your card is out of + range, the value is 0; if no card is inserted or your card is in Ad-Hoc mode it will + show N/A. + + + Connection speed + An 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. The scale of the bar graph will automatically adjust to up to 108 + MBit/s when the current connection speed exceeds 11 MBit/s. + + + Current configuration + Here you can find information about your card configuration. It displays the + following information: + + + the network with which the card is connected to / tries to connect to + (Searching for network: or Connected to + network:) + + + the MAC address of the access point to which the card is + connected. + If the card is in Infrastructure mode but out of range, an appropriate warning + (- no access point -) is displayed to indicate + that no connection is established. + In Ad-Hoc mode, the field shows an address that is associated with one of the + cards in the Ad-Hoc network. It displays a MAC address that has a non-global scope: + its second bit is set to 1, which often results in a prefix of 02: + instead of 00:. Many people think this is an error, but in fact it is + done on purpose to show that the cell you are connected to is not an actual physical + device, but rather an imaginary access point without a real physical address. + + Your card is the first card that enters Ad-Hoc mode with a given SSID. Then all other cards + entering Ad-Hoc mode with the same SSID will see your MAC-address, slightly modified: instead + of00:xx:yy:zz:aa:bb it will + show02:xx:yy:zz:aa:bb. This behavior is + intentional. + + + + on most cards (those that have the capability to report it), the frequency on + which the card is transmitting data and the corresponding channel number is + displayed. + + + your local IP (version 4) address, if available. If no address could be + retrieved from the networking subsystem, the word unavailable + is displayed. + + + encryption status (only if you have started &kwifimanager; asroot). The display will only show + off or active, but never the real key. + This is intentional in order to not reveal the WEP key to people + passing by the users screen. + + + + + Access Point information (bottom area) + 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$KDEDIR/share/apps/kwifimanager/locations/DE_BW_Karlsruhe_University.loc + + If you want to set up a new list, simply create a file in the same format and copy + it into the folder $KDEDIR/share/apps/kwifimanager/locations/ + + It will be automatically parsed at the next start of &kwifimanager;. If you have + a list and want to have it included in future releases of &kwifimanager;, simply + send it to the author or current maintainer. + + + Information about available networks + The lower-left area of the main window contains a button named Scan for + networks.... If you click on this button, &kwifimanager; will attempt + to retrieve a list of all networks that are in range of your card. The outcome of this + scan depends on two factors: + + the overall ability of your card and driver to perform network scans + + + if you have root permissions or not + + If your card or driver arent able to scan the network, your scanning + results will always be empty. If you are not the root user, the list may be incomplete + or outdated. + In order to receive a reliable, current list of access points you will need to + start the scan with root privileges, for example by using the &kdesu; utility to + start &kwifimanager; + If at least one network was found, you are presented with a table showing details + of the network. It has four columns that inform you about + + the network name (or the string (hidden cell) if the name + is not disclosed by the access point during the scan) + + + the type (whether is a Managed or an + Ad-Hoc network) + + + the signal strength of the network + + + and whether or not WEP encryption is used + + In case of an active WEP encryption, you can click on + that column and enter the network key. &kwifimanager; will automatically try to + guess if the key is a hexadecimal number or a string. + If the network information for the highlighted network is complete (&ie; all + columns contain meaningful information), you can use the button Switch to + network to enter the selected network. If &kwifimanager; has no root + privileges, you will be prompted with a password prompt to enter the root password in + order to change the network. + Clicking on Close dismisses the network information screen + without changes to the existing settings. + + + + Statistics Viewer + Optionally, by selecting Connection statistics in the + File 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. + Some cards do not report meaningful noise information. If this is the case for your + card and you get annoyed by the irrelevant red line, you can disable showing the noise + level in the statistics window by unselecting + Config + Show noise level in statistics + in the &kwifimanager; main window. + + + Configuration Editor + By selecting + Config + Configuration Editor + you are taken to the control center + module of &kwifimanager;. In case you are not the root user, a window will pop up requesting the root password. This is because the configuration module + allows you to change network connectivity und uses ifconfig to make + changes, which requires root privileges. + + + Miscellaneous + There are some minor additional features worth of being mentioned. + + Acoustic Scanning + First, there is a feature named Acoustic Scanning. 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 beep output and to a + more rapid beeping. If you've ever seen the Star Trek(tm) series you will see some + parallels to their tricorders + + + + Network logging + A second feature is network logging. 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 + any. In this mode, the card will log into any network it finds. The + logfile's position is $HOME/.kde/share/apps/kwifimanager/wireless-log + + + + Disabling the wireless network + You can completely disable the card by selecting the option File + Disable radio. Using this option will turn off the cards + transmitter which effectively turns it off and saves a little bit of energy. This will + only work for your card if it accepts changes to its + txpower property. + + + + + The system tray icon + When &kwifimanager; is launched, it installs a small icon in the system tray. The icon contains + parts of the information of the main window, namely the bar graph and optionally the signal strength + number. If you hover over the icon with the mouse for a few seconds, a tooltip will appear that + contains the currently connected network name. Whether or not the strength number shall be + shown can be configured via Config, + Show Strength Number in System Tray. + If you have configured &kwifimanager; to stay in the system tray when clicking on the + X button, the icon will stay in the tray persistently unless you really exit + the application by clicking on File, Quit. + You can always hide the main application to the system tray by clicking on the tray icon. Similarly, + to restore the main application from the tray, just click on it once. + + + The Control Center module + 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 ten independent configurations for the + card. If you dont need that many configurations, you can reduce the number of configs + shown at any time by changing the Number of Configurations entry. + If you have configured your wireless settings with a distribution-specific tool, chances are good + that the &kcontrolcenter; module will automatically detect this and also read in and show that + configuration. In any case these configurations will be read-only, because it is the distribution's + job to handle updating these settings and the module should not interfere with their internal magic. + Up to five additional preset configurations can be shown in addition to the ten + that are self-definable. These configurations will have the name Vendor x + to distinguish them from the others. + The &kcontrolcenter; can even automatically set your card up whenever you start the module. + Since establishing (or bringing down) a network connection is a security sensitive operation, + any changes to the configuration can only be done by root. + + The Configuration Tabs + The configurations are split up in three parts: + + general configuration settings (like the network name) + + + encryption settings + + + power saving settings + + + These parts are explained in the following sections. + + + General settings + The upper part of the control center module consists of one to ten tabs labelled + Config 1 through Config 10. Each of these tabs + can hold a configuration for your WLAN card. In addition (as explained above) up to five vendor-specific + configurations may be visible, labelled Vendor 1 through Vendor 5. + 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 fieldNetwork name. 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 + any. + In addition to the network name, you have to specify the type of network to log into. + That's the purpose of the button groupOperation mode. The + optionManaged means that the network consists of designated + base stations, so-called access points or sometimes residential + gateways. This is the most common operation mode for company networks. The second + option,Ad-hoc means that your network is just a direct + connection between computers, without access points. The three other options + (Repeater, Master and Secondary) + are only very seldomly used. If you want to use them, please be aware that these settings are simply + passed to the iwconfig program and have not been tested extensively. In case something doesnt + work as expected, you are welcome to send a bug report. + You can optionally set the connection speed for your connection. The setting + auto 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. + Below these configuration items you will find a field namedExecute script on + connect:. Here you can enter the name of a script to execute after setting up + the network connection. It will be + executed whenever you hit the Activate configuration 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 + kdesu + + USERNAME + + COMMAND + . Or, you can instruct your X server to also allow connections coming from + root. You can do this with the xhost program. + + + Cryptography settings + The checkbox Use encryption determines whether or not encryption + shall be activated. If it is checked, a button labelled Configure... becomes + available which allows you to configure the details of encryption. + After pushing the button, you are presented the following settings in a new dialog: + + + + Key to use: + + + You can define up to four secret keys for each configuration; in this field you + can set which one you want to use to send encrypted packets. The card can always + receive packets that are encrypted with any of the keys. + You can achieve asymetrical encryption (different keys for sending and receiving) + if you configure your access point to send packets with a different key than the card. Just make + sure that the partner station has the required key in any one of its key slots. + + + + + Crypto mode: + + + When encryption is activated, there are two ways to deal with incoming + non-encrypted packets: discard or allow. When you set your card for Open, + the card will also listen to non-encrypted packets. + Restricted will only allow encrypted network packets, + any other packets are discarded. + + + + + Crypto keys: + + + This box lets you specify the secret keys to use for cryptography. To protect + your passwords, only asterisks will be shown when you enter a password. The &kcontrolcenter; + module will automatically try to guess whether you want to set an encryption string + or a hexadecimal number by checking the input length: string keys are usually 5 or 13 + characters long (for 64- or 128-Bit key lengths) whereas hex values are 10 or 26 characters + long (please do not put a 0x in front of hex keys). + + + + Be aware that the built-in cryptography support (named WEP for Wired Equivalent + Privacy) is not very safe at all. See for details. + + + Power saving settings + The last configuration element that remains to be described is the power management. + When checking the box Enable Power Management a button for the + configuration of the setting will become active. After clicking this button, a new dialog will open + and you will be presented + some options that can help you save energy. The first two input fields named + Sleep timeout and Wakeup period + describe the periodicity of network online times for your wireless &LAN; card. The card will + turn the radio antenna off for the time period (in seconds) specified in + Sleep timeout. Afterwards it will be active for Wakeup + period and will in that time establish the network connection and send/receive + packets that queued up during the sleep time. If no network + connection is found, it will go to sleep again immediately and the cycle begins again. The box named + Receive packets below lets you specify which packets the card + should listen to when awaken. You can either select Unicast only + (which will only let your card listen to packets sent specifically to your card), + Multi/Broadcast only (will only listen to packets sent to multiple + machines and discard packets directed to your card) or Both. Most + people should select the default value Both. + + + + Auto-configuration on &kcontrolcenter; Module startup + If you wish, you can make &kwifimanager; initialize your wireless &LAN; card + whenever you start the &kcontrolcenter; module. To do so, check the box Load + preset configuration on startup and select 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 Activate + configuration. + + + Autodetecting your device + &kwifimanager; needs to know the interface name of your wireless &LAN; card to + apply any settings. You can either enter the information (⪚ + eth1 orwlan0) manually in the input field + on the right-hand side ofSettings apply to interface:, or let &kwifimanager; + auto-detect the interface. To do so, push the buttonAutodetect + interface. This will perform a scan on all interfaces listed in /proc/net/dev 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. In the case that there are multiple wireless LAN cards present on the system, + scanning stops after the first card found. So, if you want to apply the settings to a different + card than the one that was detected during the scan, you need to enter its interface name + by hand. + + + + + License and contributors + Documentation copyright © Stefan + Wintermail@stefan-winter.de. &underFDL; &underGPL; + + + + Further Information + This appendix contains some extra information of items concerning wireless &LAN; that + are not directly related to &kwifimanager;. + + Notes on the MAC address display in Ad-hoc mode + At first glance, the MAC address in the field Access Point seems to + be wrong in Ad-hoc mode because it changes the first two digits of the MAC address + to02. But actually, this is a hardcoded feature in + wireless &LAN; cards. + Usually a card is connected to a real access point. Then the correct MAC + address is shown. If you change to Ad-hoc (or Peer-to-peer) 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 + real 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 (rare) occasions: MAC addresses that are + not globally valid have a bit set to one that shows that these addresses are + locally administered. This bit is the second bit in transmit order, and the seventh + bit in logical order and will hence raise the number of the MAC's first digit block from 00 to 02. + You can compare this sort of address to the non-global IP addresses like192.168.*.*. + + So, the implementors of wireless networking agreed to give thesevirtual + network servers a MAC address that is within the locally administered scope. + To keep this virtual MAC address unique, they used a little trick: they only changed the + first segment of the MAC address of the wireless &LAN; card, and since the remaining + segments are still unique in the world, they have a unique address to use as network + server. + + + Security considerations on <acronym>WEP</acronym> cryptography + + WEP cryptography is not very secure at all. A paper from + cryptography analysts called the encryption algorithm kindergarten + cryptography. 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 because some packets are + particularly weak because they carry a bad so-called initialisation vector (IV). Recent access + points try to avoid these bad IVs, so it is getting harder to exploit the hole. + If you are truly concerned about your security, donot use plain + WEP. If you are just setting up a two-computer home network, well, then + I guessWEP should do. + There are many alternatives to WEP encryption. Its successors WPA and + WPA2 are better designed and do a better job protecting your traffic, for example by dynamically changing + the keys after a while. + If you dont want to rely on the basic safety of the network link you could use + SSH to communicate over the network. SSH is a + program suite that encrypts data with its own algorithm, which is very secure. Another + option is to use PPTP, the Point-to-Point-Tunneling protocol. However, + even PPTP seems to be a bit leaky concerning encryption security. And + finally, you could set up an IPSec tunnel (VPN connection) for your encrypted connections. As of yet, this + encryption seems to be very safe and flexible. + + + + Compilation and Installation &install.intro.documentation; + &install.compile.documentation; &documentation.index; -- cgit v1.2.1