path: root/man/waproamd.8.xml.in

<?xml version="1.0" standalone='no'?>
<!DOCTYPE manpage SYSTEM "xmltoman.dtd">
<?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>

<!-- $Id$ -->

<!-- 
  This file is part of waproamd.

  waproamd is free software; you can redistribute it and/or modify it under
  the terms of the GNU General Public License as published by the Free
  Software Foundation; either version 2 of the License, or (at your
  option) any later version.

  waproamd is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
  for more details.

  You should have received a copy of the GNU General Public License
  along with waproamd; if not, write to the Free Software Foundation,
  Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 
-->

<manpage name="waproamd" section="8" desc="Wireless Access Point Roaming Daemon for WLAN IEEE 802.11">

  <synopsis>
    <cmd>waproamd [<arg>options</arg>]</cmd>
  </synopsis>
  
  <description> 

    <p>waproamd is a roaming daemon for wireless NICs supporting the
    Linux wireless extensions. It is intended to configure the WEP
    keys according to the networks found.</p>

    <p>As long as the local NIC is not associated to any wireless
    network waproamd scans iteratively for them. If one is detected, a
    script in <file>@sysconfdir@/waproamd/scripts/</file> named after
    the MAC address of the access point is called. (First lowercase,
    than uppercase is checked) If a script like this is not found a
    script named <tt>essid:&lt;ESSID&gt;</tt> in the same directory is
    used. Special characters are escape in an HTTP URL like
    fashion. If this script is not existent,
    <file>@sysconfdir@/waproamd/scripts/default</file> is called
    instead. The first argument to this script is "start". If the
    association is lost, the same script is run with the argument
    "stop". While the NIC is associated no scans are issued.</p>

    <p>waproamd is intended to be used together with ifplugd. Whenever
    an association succeeds, ifplugd detects it and runs further
    configuration commands for it.</p>

    <p>If multiple WLANs are detected at the same time, the network
    which is detected by the hardware first is selected. However,
    networks where a matching script exists take precedence.</p>

    <p>waproamd requires a network driver supporting the Linux
    wireless extensions v15 or newer. The driver needs to support
    scanning for wireless networks, which may be tested by running
    "iwlist scan". If the driver supports the wireless event
    subsystem, waproamd may use it to improve latency behaviour. It is
    not required, however.</p>

    <p>waproamd supports the host_roaming ioctl() defined by the
    hostap driver.</p>

  </description>
  
  <options>
    
    <option>
      <p><opt>-n | --no-daemon</opt></p>
      <optdesc><p>
      Do not daemonize (for debugging) (default: off)
      </p></optdesc>
    </option>
    
    <option>
      <p><opt>-s | --no-syslog</opt></p>
      <optdesc><p>
      Do not use syslog, use stdout instead (for debugging) (default: off).
      </p></optdesc>
    </option>
    
    <option>
      <p><opt>-i | --iface=</opt><arg>IFACE</arg></p>
      <optdesc><p>
      Specify the wireless network interface (default: wlan0)
      </p></optdesc>
    </option>
    
    <option>
      <p><opt>-w | --wait-on-fork</opt></p> 

      <optdesc><p> When daemonizing, wait until the background
      process finished with the initial association detection.
      </p></optdesc>
    </option>

    <option>
      <p><opt>-W | --wait-on-kill</opt></p> 
      
      <optdesc><p> When killing a running daemon (with -k) wait
      until the daemon died.
      </p></optdesc>
    </option>
    
    <option> <p><opt>-M | --monitor</opt></p> <optdesc><p>Don't fail
    when the network interface is not available, instead use
    NETLINK to monitor device avaibility. The is useful for PCMCIA
    devices and similar.</p></optdesc> </option>

    <option> <p><opt>-e | --no-event</opt></p> <optdesc><p>Don't use
    the wireless event API (as used by <manref name="iwevent"
    section="8"/>), instead poll for association information. Some
    network drivers do not support this relatively new feature of
    the Linux wireless extension. Sadly the support of this feature
    cannot be detected automatically.</p></optdesc> </option>

    <option>
      <p><opt>-t | --scan-interval=</opt><arg>SECS</arg></p>
      <optdesc><p>Specify the time between scans for wireless networks.</p></optdesc>
    </option>

    <option>
      <p><opt>-p | --poll-intervall=</opt><arg>SECS</arg></p>
      <optdesc><p>When using -e, specify the time between association status polls.</p></optdesc>
    </option>

    <option>
      <p><opt>-h | --help</opt></p>
      <optdesc><p>
      Show help
      </p></optdesc>
    </option>
    
    <option>
      <p><opt>-k | --kill</opt></p>
      <optdesc><p>
      Kill a running daemon (Specify -i to select the daemon instance to kill)
      </p></optdesc>
    </option>

    <option>
      <p><opt>-c | --check-running</opt></p>
      <optdesc><p>
      Check if a daemon is running for a given network interface. Sets the return value to 0 if a daemon is already running or to 255 if not.
      </p></optdesc>
    </option>
    
    <option>
      <p><opt>-S | --supend</opt></p> <optdesc><p> Suspend a running
      daemon. The daemon will no longer check the link status until
      it is resumed (-R) again. (Specify -i to select the daemon instance
      to suspend.)  </p></optdesc>
    </option>
    
    <option>
      <p><opt>-R | --resume</opt></p> <optdesc><p> Resume a suspended
      daemon. (Specify -i to select the daemon instance
      to resume.)  </p></optdesc>
    </option>
    
    <option>
      <p><opt>-v | --version</opt></p>
      <optdesc><p>
      Show version
      </p></optdesc>
    </option>
    
    <option>
      <p><opt>-r | --issue-scan</opt></p>
      <optdesc><p>
      Tell a running daemon to issue an immediate scan for new networks
      </p></optdesc>
    </option>

    <option>
      <p><opt>-U | --no-userspace-roaming</opt></p>
      <optdesc><p> Don't enable userspace roaming as supported by
      certain drivers (e.g. hostap). Normaly, waproamd tries to enable
      this special feature, doing effectively the same as "iwpriv
      wlan0 host_roaming 2". If the driver supports this private ioctl
      the robustness of waproamd's operation is increased. However, it
      is not required for successful use. See your driver documentation for
      mor information on this topic.</p></optdesc>
    </option>

  </options>
  
  <section name="Files">
    
    <p><file>@sysconfdir@/waproamd/waproamd.conf</file>: this file is sourced
    by the init script <file>@sysconfdir@/init.d/waproamd</file> and
    contains the interface to be monitored and the options to be
    used.</p>

    <p><file>@sysconfdir@/waproamd/scripts/&lt;AP MAC
    address&gt;</file>: this is called whenever a wireless network
    controlled by an AP with a matching address is detected. The file
    is first tried with the MAC address formatted lowercase. If no
    script with that name exists waproamd looks for a file with the
    MAC address formatted uppercase. Only scripts marked executable are considered. Networks with non-executable scripts are always ignored. You may use this to "disable" specific networks from being selected. Takes the same arguments as the
    following script:</p>

    <p><file>@sysconfdir@/waproamd/scripts/essid:&lt;ESSID&gt;</file>:
    This is called whenever a wireless AP is detected but no script
    named after the AP MAC exists (See above). If the ESSID contains
    special chracters (ASCII code &lt; 32, &gt;= 127, '/', '%') they are
    replaced by a character % and the hexadecimal ASCII number of the
    character in uppercase. This is similar to the HTTP URL
    encoding. Only scripts marked executable are considered. Takes the same arguments as the following script:</p>
    
    <p><file>@sysconfdir@/waproamd/scripts/default</file>: this is the
    script which is called when neither a script named after the
    AP MAC address, nor a script named after the ESSID is found. It
    takes a single argument: either "start" or "stop". An environment
    variable AP is set to the MAC address of the access point
    found. An environment variable IFACE is set to the network
    interface name. An environment variable ESSID contains the ESSID
    of the WLAN network. ESSID_ESCAPED contains the ESSID with all
    special chracters escaped the same way as described above. The
    default implementation of this script looks for a file
    <file>@sysconfdir@/waproamd/keys/&lt;AP MAC address&gt;.wep</file>
    (or named after the ESSID, following the same scheme as the script
    selection described above). If it exists its contents is used to
    set the WEP key of the NIC. Otherwise the script looks for a file
    <file>@sysconfdir@/waproamd/keys/&lt;AP MAC
    address&gt;.aes</file>. If it exists the AES WEP rekeying daemon
    <manref name="aeswepd" section="8"/> is called. Otherwise WEP
    encryption is disabled.</p>
    
    <p><file>/var/run/waproamd.&lt;iface&gt;.pid</file>: the pid file
    for waproamd.</p>
    
  </section>
  <section name="Signals">
    <p><arg>SIGINT, SIGTERM, SIGQUIT</arg> waproamd will quit. This is issued by passing -k to waproamd.</p>
    <p><arg>SIGHUP</arg> waproamd will rescan for available networks immediately.</p>
  </section>

  <section name="Author">
    <p>waproamd was written by Lennart Poettering
    &lt;@PACKAGE_BUGREPORT@&gt;. waproamd is available
    at <url
    href="@PACKAGE_URL@"/>
    </p>
  </section>
  
  <section name="See also">
    <p>
      <manref name="ifplugd" section="8"/>, <manref name="aeswepd" section="8"/>, <manref name="iwconfig" section="8"/>, <manref name="iwlist" section="8"/>
    </p>
  </section>
  
  <section name="Comments">
    <p>This man page was written using <manref name="xmltoman" section="1"
    href="http://masqmail.cx/xml2man/"/> by Oliver Kurth.</p>
  </section>
  
</manpage>