<sect1 id="wireless">

    <sect1info>

      <authorgroup>

        <author>

          <firstname>Eric</firstname>

          <surname>Anderson</surname>

          <contrib>Written by </contrib>

        </author>

      </authorgroup>

    </sect1info>

    <title>Wireless</title>

   <sect2>

      <title>Introduction</title>

      <para>It can be very useful to be able to use a computer without the 

      annoyance of having a network cable attached at all times.  FreeBSD can

      be used as a wireless client, and even as a wireless <quote>access 

      point</quote>.</para>

   </sect2>

   <sect2>

     <title>Wireless Devices</title>

     <para>There are two main types of wireless devices: access points, and clients.<para>

     <sect3>

       <title>Access Points</title>

       <para>Access points are wireless networking devices that allow one or more wireless 

        clients to use the device as a central hub.  When using an access point, all 

        clients communicate through the access point.  Multiple access points are often 

        used to cover a complete area such as a house, business, or park with a wireless 

        network.</para>

       <para>Access points typically have multiple network connections: the wireless card,

       and one or more wired ethernet adapters for connection to the rest of the network.

       </para>

       <para>Access points can either be purchased prebuilt, or you can build 

        your own with FreeBSD and a supported wireless card.  Several vendors make 

        wireless access points and wireless cards with various features.</para>

     </sect3>

     <sect3>

       <title>Building a FreeBSD Access Point</title>

       <sect4><title>Requirements</title>

         <para>In order to set up a wireless access point with FreeBSD, you need to have 

          a compatible wireless card.  Currently, only cards with the Prism chipset are 

          supported. You'll also need a wired network card that is also supported by FreeBSD 

          (this shouldn't be difficult to find, FreeBSD supports a lot of different 

          devices).  For this guide, we'll assume you want to &man.bridge.4; all traffic between 

          the wireless device and the network attached to the wired network card.</para>

       </sect4>

       <sect4>

         <title>Setting it up</title>

         <para>First, make sure your system can see the wireless card:</para>

         <screen>&prompt.root; <userinput>ifconfig -a</userinput>

wi0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500

        inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7 

        inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255

        ether 00:09:2d:2d:c9:50

        media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)

        status: no carrier

        ssid ""

        stationname "FreeBSD Wireless node"

        channel 10 authmode OPEN powersavemode OFF powersavesleep 100

        wepmode OFF weptxkey 1</screen>

         <para>Don't worry about the details now, just make sure it shows you 

          something to indicate you have a wireless card installed.</para>

         <para>Next, you'll need to load a module in order to get the bridging part 

          of FreeBSD ready for the access point.  In order to load the &man.bridge.4; module, 

          simply run the following command:</para>

         <screen>&prompt.root; <userinput>kldload bridge</userinput></screen>

         <para>It should not have produced any errors when loading the module.  If it 

          did, you may need to compile the &man.bridge.4; code into your kernel.  The 

          (<xref linkend="bridging">) Handbook should be able 

          to help you accomplish that task.</para>

         <para>Now that you have the bridging stuff done, we need to tell the FreeBSD 

          kernel which interfaces to bridge together.  We do that by using sysctl:</para>

         <screen>&prompt.root; <userinput>sysctl net.link.ether.bridge=1</userinput></screen>

          <screen>&prompt.root; <userinput>sysctl net.link.ether.bridge_cfg="wi0 xl0"</userinput></screen>

          <screen>&prompt.root; <userinput>sysctl net.inet.ip.forwarding=1</userinput></screen>

         <para>Now it's time for the wireless card setup.</para>

         <para>The following commands will set the card into BSS mode (turning it 

          into an access point):</para>

         <screen>&prompt.root; <userinput>wicontrol -s "FreeBSD AP" -t 3 -n "my_net"</userinput></screen>

          <screen>&prompt.root; <userinput>ifconfig wi0 inet up ssid my_net mediaopt hostap</userinput></screen>

          <screen>&prompt.root; <userinput>wicontrol -p 6</userinput></screen>

         <para>The first &man.wicontrol.8; command tells FreeBSD that the name of this access point 

          is FreeBSD AP by using the -s FreeBSD AP flags, to use auto rate selection at the 

          highest rate (11Mbps) with the -t 3 flags, and the SSID (station ID) is set to 

          my_net with the -n flag. Check out &man.wicontrol.8; for more information.</para>

         <para>The &man.ifconfig.8; line brings the wi0 interface up, and sets its SSID to my_net.  

          This is a little redundant, but it's shown here to emphasize that you can do 

          these settings in either place.  You'll also notice a mediaopt hostap setting; 

          this setting is to tell &man.ifconfig.8; to put the interface into access point mode.</para>

         <para>The second &man.wicontrol.8; line turns the interface into access point mode, instead 

          of the default IBSS (ad-hoc) mode.</para>

         <para>Now you should have a complete functioning access point up and running.  You 

          are encouraged to read &man.wicontrol.8;, &man.ifconfig.8;, and &man.wi.4; for further information.

         </para>

         <para>It is also suggested that you read the section on encryption that follows.</para>

       </sect4>

     </sect3>

     <sect3>

       <title>Clients</title>

       <para>A wireless client is a system that accesses an access point or another client

       directly. </para>

       <para>Typically, wireless clients only have one network device, the wireless 

       networking card.<para>

       <para>There are a few different ways to configure a wireless client.  These are based 

        on the different wireless modes, generally BSS (infrastructure mode, which requires an 

        access point), and IBSS (ad-hoc, or peer-to-peer mode).  In our example, we'll use the 

        most popular of the two, BSS mode, to talk to an access point.</para>

       <sect4>

       <title>Requirements</title>

       <para>There is only one real requirement for setting up FreeBSD as a wireless client.  

        You'll need a wireless card that is supported by FreeBSD.</para>

       </sect4>

       <sect4>

       <title>Setting Up A Wireless FreeBSD Client</title>

       <para>You'll need to know a few things about the wireless network you are joining before 

        you start.  In this example, we are joining a network that has a name of my_net, and 

        encryption turned off.</para>

       <para>Note:  In this example, we are not using encryption, which is a dangerous situation.  

        In the next section, you'll learn how to turn on encryption, and why it is important to 

         do so, and why some encryption technologies still don't completely protect you.</para>

       <para>Make sure your card is recognized by FreeBSD:</para>

       <screen>&prompt.root; <userinput>ifconfig -a</userinput>

wi0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500

        inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7 

        inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255

        ether 00:09:2d:2d:c9:50

        media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)

        status: no carrier

        ssid ""

        stationname "FreeBSD Wireless node"

        channel 10 authmode OPEN powersavemode OFF powersavesleep 100

        wepmode OFF weptxkey 1</screen>

       <para>Now, we'll set the card to the correct settings for our network:</para>

       <screen>&prompt.root; <userinput>ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net</userinput></screen>

       <para>Replace 192.168.0.20 and 255.255.255.0 with a valid IP address and netmask on 

        your wired network.  Remember, our access point is bridging the data between the 

        wireless network, and the wired network, so it will appear to the other devices on 

        your network that you are on the wired network just as they are.</para>

       <para>Once you have done that, you should be able to ping hosts on the wired network 

        just as if you were connected using a standard wired connection.</para>

       <para>If you are experiencing problems with your wireless connection, check to make 

        sure that your are associated (connected) to the access point:

       <screen>&prompt.root; <userinput>ifconfig wi0</userinput></screen>

       should return some information, and you should see:</para>

       <screen>status: associated</screen>

       <para>If it does not show associated, then you may be out of range of the access point, don't have 

       encryption on, or possibly have a configuration problem.</para>

       </sect4>

     </sect3>

     <sect3>

      <title>Encryption</title>

      <para>Encryption on a wireless network is important because you no longer have the 

       ability to keep the network contained in a well protected area.  Your wireless data 

       will be broadcast across your entire neighborhood, so anyone who cares to read it 

       can.  This is where encryption comes in.  By encrypting the data that is sent over 

       the air waves, you make it much more difficult for any interested party to grab your 

       data right out of the air. </para>

     <para>The two most common ways to encrypt the data between your client and the access 

      point, are WEP, and &man.ipsec.4;.</para>

     <sect4>

     <title>WEP</title>

      <para>WEP is an abbreviation for Wired Equivalency Protocol.  WEP is an attempt to 

       make wireless networks as safe and secure as a wired network.  Unfortunately, it 

       has been cracked, and is fairly trivial to break.  This also means it isn't something 

       to rely on when it comes to encrypting sensitive data.  </para>

      <para>It's better than nothing, so here's how to turn on WEP on your new FreeBSD 

       access point:</para>

      <screen>&prompt.root; <userinput>ifconfig wi0 inet up ssid my_net wepkey 0x1234567890 mediaopt hostap</userinput></screen>

      <para>And here's how you turn on WEP on a client:</para>

      <screen>&prompt.root; <userinput>ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net wepkey 0x1234567890</userinput></screen>

      <para>Note that you should replace the 0x1234567890 with a more unique key.</para>

     </sect4>

     <sect4>

     <title>IPsec</title>

      <para>&man.ipsec.4; is a much more robust and powerful tool for encrypting data across a 

       network.  This is definitely the preferred way to encrypt wireless data over a 

       network.  You can read more about &man.ipsec.4; security and how to implement it in the 

       (<xref linkend="ipsec">) handbook.</para>

     </sect4>

    </sect3>

    <sect3>

    <title>Tools</title>

    <para>There are a small number of tools available for use in debugging and setting 

    up your wireless network, and here we'll attempt to describe some of them and what 

    they do.</para>

    <sect4>

    <title>bsd-airtools</title>

    <para>bsd-airtools is a package that includes wireless auditing tools for wep key 

    cracking, access point detection, etc.</para>

    <para>bsd-airtools can be installed from the ports collection.  Information on 

    installing ports can be found in (<xref linkend="ports">) the handbook.<para>

    <para>dstumbler is the packaged tool that allows for access point discovery and 

    signal to noise ratio graphing.  If you are having a hard time getting your access 

    point up and running, dstumbler may help you get started.</para>

    <para>To test your wireless network security, you may choose to use dweputils to 

    help you determine if wep is the right solution to your wireless security needs.</para>

    </sect4>

    <sect4>

    <title>wicontrol, ancontrol, raycontrol</title>

    <para>These are the tools you use to control how your wireless card behaves on the 

    wireless network.  In the examples above, we've chosen to use &man.wicontrol.8;, since our 

    wireless card is a wi0 interface.  If you had a Cisco wireless device, it would come 

    up as an0, and therefore you would use &man.ancontrol.8;.<para>

    </sect4>

    <sect4>

    <title>ifconfig</title>

    <para>&man.ifconfig.8; can be used to do many of the same options as &man.wicontrol.8;, however it 

    does lack a few options.  Check &man.ifconfig.8; for command line parameters and options.</para>

    </sect4>

    </sect3>

    <sect3>

    <title>Supported Cards</title>

    <sect4>

    <title>Access Points</title>

    <para>The only cards that are currently supported for BSS (as an access point) mode are 

    devices based on the Prism (or Prism 2, 2.5) chipset. For a complete list, look 

    at &man.wi.4;.</para>

    </sect4>

    <sect4>

    <title>Clients</title>

    <para>Almost all 802.11b wireless cards are currently supported under FreeBSD.  Most 

     cards based on Prism, Spectrum24, Hermes, Aironet, and Raylink will work as a wireless

     network card in IBSS (ad-hoc, peer-to-peer, and BSS) mode.</para>

    </sect4>

    </sect3>

   </sect2>

  </sect1>