usr.sbin/raycontrol/raycontrol.8

   1 .\"
   2 .\"Copyright (C) 2000
   3 .\"Dr. Duncan McLennan Barclay, dmlb@ragnet.demon.co.uk.
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\"Redistribution and use in source and binary forms, with or without
   8 .\"modification, are permitted provided that the following conditions
   9 .\"are met:
  10 .\"1. Redistributions of source code must retain the above copyright
  11 .\"   notice, this list of conditions and the following disclaimer.
  12 .\"2. Redistributions in binary form must reproduce the above copyright
  13 .\"   notice, this list of conditions and the following disclaimer in the
  14 .\"   documentation and/or other materials provided with the distribution.
  15 .\"3. Neither the name of the author nor the names of any co-contributors
  16 .\"   may be used to endorse or promote products derived from this software
  17 .\"   without specific prior written permission.
  18 .\"
  19 .\"THIS SOFTWARE IS PROVIDED BY DUNCAN BARCLAY AND CONTRIBUTORS ``AS IS'' AND
  20 .\"ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\"IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\"ARE DISCLAIMED.  IN NO EVENT SHALL DUNCAN BARCLAY OR CONTRIBUTORS BE LIABLE
  23 .\"FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\"DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\"OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\"HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\"LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\"OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\"SUCH DAMAGE.
  30 .\"
  31 .\" Copyright (c) 1997, 1998, 1999
  32 .\"     Bill Paul <wpaul@ctr.columbia.edu> All rights reserved.
  33 .\"
  34 .\" Redistribution and use in source and binary forms, with or without
  35 .\" modification, are permitted provided that the following conditions
  36 .\" are met:
  37 .\" 1. Redistributions of source code must retain the above copyright
  38 .\"    notice, this list of conditions and the following disclaimer.
  39 .\" 2. Redistributions in binary form must reproduce the above copyright
  40 .\"    notice, this list of conditions and the following disclaimer in the
  41 .\"    documentation and/or other materials provided with the distribution.
  42 .\" 3. All advertising materials mentioning features or use of this software
  43 .\"    must display the following acknowledgement:
  44 .\"     This product includes software developed by Bill Paul.
  45 .\" 4. Neither the name of the author nor the names of any co-contributors
  46 .\"    may be used to endorse or promote products derived from this software
  47 .\"   without specific prior written permission.
  48 .\"
  49 .\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND
  50 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  51 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  52 .\" ARE DISCLAIMED.  IN NO EVENT SHALL Bill Paul OR THE VOICES IN HIS HEAD
  53 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  54 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  55 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  56 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  57 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  58 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  59 .\" THE POSSIBILITY OF SUCH DAMAGE.
  60 .\"
  61 .\" $FreeBSD: src/usr.sbin/raycontrol/raycontrol.8,v 1.5.2.5 2003/03/11 22:31:31 trhodes Exp $
  62 .\" $DragonFly: src/usr.sbin/raycontrol/Attic/raycontrol.8,v 1.2 2003/06/17 04:30:02 dillon Exp $
  63 .\"
  64 .Dd March 21, 2000
  65 .Dt RAYCONTROL 8
  66 .Os
  67 .Sh NAME
  68 .Nm raycontrol
  69 .Nd configure Raytheon Raylink/Webgear Aviator devices
  70 .Sh SYNOPSIS
  71 .Nm
  72 .Fl i Ar iface Op Fl o
  73 .Nm
  74 .Fl i Ar iface Fl t Ar tx rate
  75 .Nm
  76 .Fl i Ar iface Fl n Ar network name
  77 .Nm
  78 .Fl i Ar iface Fl c Ar ap status
  79 .Nm
  80 .Fl i Ar iface Fl p Ar port type
  81 .Nm
  82 .Fl i Ar iface Fl m Ar mac address
  83 .Nm
  84 .Fl i Ar iface Fl d Ar max data length
  85 .Nm
  86 .Fl i Ar iface Fl r Ar RTS threshold
  87 .Nm
  88 .Fl i Ar iface Fl f Ar hopset
  89 .Nm
  90 .Fl i Ar iface Fl P Ar 0|1
  91 .Nm
  92 .Fl i Ar iface Fl S Ar max_sleep_duration
  93 .Nm
  94 .Fl i Ar iface Fl Z Ar zero signal cache
  95 .Nm
  96 .Fl i Ar iface Fl C Ar display signal cache
  97 .Sh DESCRIPTION
  98 The
  99 .Nm
 100 utility controls the operation of Raylink/Webgear wireless networking
 101 devices via the
 102 .Xr ray 4
 103 driver.
 104 Most of the parameters that can be changed relate to the
 105 IEEE 802.11 protocol which the card implements.
 106 This includes
 107 the station name, whether the station is operating in ad-hoc
 108 or infrastructure mode, and the network name of a service
 109 set to join - the BSS in ad-hoc mode or ESS if infrastructure mode is enabled.
 110 The
 111 .Nm
 112 utility can also be used to view the current settings of these parameters
 113 and to dump out the values of the card's statistics counters.
 114 .Pp
 115 The
 116 .Ar iface
 117 argument given to
 118 .Nm
 119 should be the logical interface name associated with the Raylink/Webgear
 120 device (ray0, ray1, ...).
 121 .Sh OPTIONS
 122 The options are as follows:
 123 .Bl -tag -width Fl
 124 .It Fl i Ar iface Op Fl o
 125 Display the current settings of the specified Raylink/Webgear interface.
 126 This retrieves the current card settings from the driver and prints them
 127 out.
 128 The results from this command are a snapshot of the card settings.
 129 Using the additional
 130 .Fl o
 131 flag will cause
 132 .Nm
 133 to print out the statistics counters instead of the card settings.
 134 .It Fl i Ar iface Fl t Ar tx rate
 135 Set the transmit rate of the specified interface.
 136 The
 137 NICs support a maximum transmit rate of 2Mbps.
 138 The following table shows the
 139 legal transmit rate settings and the corresponding transmit speeds:
 140 .Bl -column "TX rate " "NIC speed " -offset indent
 141 .Em "TX rate    NIC speed"
 142 1       Very Low (0.5Mbps)
 143 2       Low (1Mbps)
 144 3       Medium (1.5Mbps)
 145 4       High (2Mbps)
 146 .El
 147 .Pp
 148 The version 4 firmware may ignore this setting.
 149 Note, that the IEEE 802.11
 150 standard
 151 only allows 1Mbps or 2Mbps operation, and that the generally accepted
 152 reading of the IEEE 802.11 standard is that 2Mbps is only allowed in
 153 infrastructure mode.
 154 .It Fl i Ar iface Fl n Ar network name
 155 Set the name of the service set that this station wishes to
 156 join.
 157 The
 158 .Ar network name
 159 can be any text string up to 32 characters in length.
 160 The default name
 161 is the string "NETWORK_NAME" which should allow the station to connect to
 162 the default Webgear ad-hoc network.
 163 .It Fl i Ar iface Fl p Ar port type
 164 Set the
 165 .Ar port type
 166 for a specified interface.
 167 The legal values for
 168 .Ar port type
 169 are 0 (ad-hoc mode) and 1 (infrastructure mode).
 170 In ad-hoc mode, the station can
 171 communicate directly with any other stations within direct radio range
 172 (provided that they are also operating in ad-hoc mode).
 173 In infrastructure mode,
 174 hosts must associate with a service set controlled by an access point,
 175 that relays traffic between end stations.
 176 The default setting is 0
 177 (ad-hoc mode).
 178 .Pp
 179 When in ad-hoc mode the station will create a BSS with the network name
 180 specified by the
 181 .Fl n
 182 option if it cannot find an existing network of that name on the
 183 currently configured hopset (see the
 184 .Fl f
 185 option).
 186 .It Fl i Ar iface Fl m Ar mac address
 187 Set the station address for the specified interface.
 188 The
 189 .Ar mac address
 190 is specified as a series of six hexadecimal values separated by colons,
 191 e.g.: 00:60:1d:12:34:56.
 192 This programs the new address into the card
 193 and updates the interface as well.
 194 .It Fl i Ar iface Fl d Ar max_data_length
 195 Set the maximum transmit frame size for a specified interface.
 196 The
 197 .Ar max data length
 198 can be any number from 350 to 2304 or -1 to disable fragmentation.
 199 The default is -1.
 200 .It Fl i Ar iface Fl r Ar RTS threshold
 201 Set the RTS/CTS threshold for a given interface.
 202 This controls the
 203 number of bytes used for the RTS/CTS handshake boundary.
 204 The
 205 .Ar RTS threshold
 206 can be any value between -1 and 2047.
 207 The default is -1 (disable).
 208 .It Fl i Ar iface Fl f Ar hopset
 209 Set the radio hopset of a given interface.
 210 The
 211 .Ar hopset
 212 should be specified as a country code as shown in the table below.
 213 The
 214 hopset varies both the number of RF channels and their frequencies
 215 and is dependent on radio regulations specified
 216 by regional authorities.
 217 .Bl -column "Hopset ID " "Country " -offset indent
 218 .Em "Hopset ID  Country"
 219 1       USA
 220 2       Europe
 221 3       Japan
 222 4       Korea
 223 5       Spain
 224 6       France
 225 7       Israel
 226 8       Australia
 227 9       Japan Test
 228 .El
 229 .Pp
 230 Whilst the card can be programmed to work with any hopset it makes
 231 sense to use the hopset for your own region to avoid interference from
 232 and interfering with other users of the RF spectrum (in places like
 233 France this is the military).
 234 .Pp
 235 Note that all stations must be set to the same hopset in order to
 236 communicate.
 237 .It Fl i Ar iface Fl P Ar 0|1
 238 Enable or disable power management on a given interface.
 239 Enabling
 240 power management uses an alternating sleep/wake protocol to help
 241 conserve power on mobile stations, at the cost of some increased
 242 receive latency.
 243 Power management is off by default.
 244 .Pp
 245 Note that power
 246 management requires the cooperation of an access point in order to
 247 function; it is not functional in ad-hoc mode.
 248 Legal
 249 values for this parameter are 0 (off) and 1 (on).
 250 .It Fl i Ar iface Fl S Ar max_sleep_interval
 251 Specify the sleep interval to use when power management is enabled.
 252 The
 253 .Ar max_sleep_interval
 254 is specified in milliseconds.
 255 The default is 100.
 256 .It Fl i Ar iface Fl Z
 257 Clear the signal strength cache maintained internally by the
 258 .Xr ray 4
 259 driver.
 260 .It Fl i Ar iface Fl C
 261 Display the cached signal strength information maintained by the
 262 .Xr ray 4
 263 driver.
 264 The driver retains information about signal strength and
 265 noise level for packets received from different hosts.
 266 For
 267 infrastructure networks the cache stores the signal strength of the
 268 access point.
 269 .Pp
 270 The driver also uses the cache to pick the best antenna when
 271 transmitting.
 272 .El
 273 .Sh SEE ALSO
 274 .Xr ray 4 ,
 275 .Xr ifconfig 8
 276 .Sh HISTORY
 277 The
 278 .Nm
 279 utility first appeared in
 280 .Fx 4.0 .
 281 .Sh AUTHORS
 282 .An -nosplit
 283 The
 284 .Nm
 285 utility was written by
 286 .An Duncan Barclay Aq dmlb@ragnet.demon.co.uk
 287 and based on the
 288 .Nm wicontrol
 289 utility by
 290 .An Bill Paul Aq wpaul@ctr.columbia.edu .
 291 .Sh BUGS
 292 The
 293 .Fl m ,
 294 .Fl P ,
 295 .Fl S
 296 and
 297 .Fl Z
 298 options aren't implemented yet.
 299 No access point was available for testing
 300 against.
 301 .Pp
 302 Not tested with Version 5 firmware.
 303 .Pp
 304 Hopset changing may not work with version 4 firmware.
 305 .Pp
 306 The
 307 .Fl W
 308 option is un-documented on purpose.