Provided by: ap-utils_1.5-2build1_i386 bug

NAME

       ap-tftp - TFTP client for upgrading ATMEL AT76C510 WiSOC-based APs

       Please read the entire manpage prior using this utility. It may prevent
       you from problems arising later.

SYNOPSIS

       ap-tftp -i IP -f firmware.rom [-c community ]

DESCRIPTION

       The ap-tftp utility is used to upgrade or downgrade firmware in  Access
       Points  based on ATMEL AT76C510 VNET-B WiSOC (Wireless System On Chip).
       It should work for  most  (if  not  all)  models  with  INTERSIL  radio
       chipset,  as  well as those based on RFMD radio. However, so far it has
       only been tested on the following hardware: WLink  WEN-2021,  i-Tec  AP
       GOLD,  smartBridges  airPOINT PRO (all with INTERSIL radio), and Tellus
       A14 (RFMD radio). If you have an AP  with  ATMEL  AT76C510  and  either
       INTERSIL  or  RFMD radio chipset, there's near 100% chance it will work
       for you, too.

PREFACE: FIRMWARE TYPES

       Functionally, there basically exist 2 types of firmware for ATMEL-based
       APs:  an  "  Access Point firmware (often referred to as AP firmware ),
       and Wireless Adapter firmware (referred  to  as  WA  firmware  ).  Many
       hardware  vendors  produce  their  own  more  or less modified firmware
       derivatives, but usually they keep up with the naming scheme introduced
       by ATMEL:

   APs with INTERSIL radios
       For  APs  with  INTERSIL  radios,  the  AP firmware file typically uses
       naming  scheme  such  as  "1.4x.y.rom"   (for   example   "1.4j.1.rom",
       "1.4k.2.rom",  etc.), while the WA firmware files typically exist under
       names such as "0.01.ab.rom" (for example "0.01.09.rom",  "0.01.11.rom",
       etc.). The values "x", "y", and "ab" indicate the firmware revision.

   APs with RFMD radios
       For  APs  with RFMD radios, the AP firmware files are known under names
       like "0.2.x.yz.rom" (such  as  "0.2.2.11.rom",  "0.2.2.18.rom",  etc.),
       while  the  WA  firmware  uses  names  as  "0.3.b.c.rom"  (for  example
       "0.3.2.5.rom", "0.3.2.6.rom"), or "0.4.b.c.rom" for WA+ firmware (which
       is  a  variant  of  WA  firmware  that  offers  limited  multiple  MACs
       transparency in client mode) - for example  "0.4.2.7.rom".  Again,  the
       numbers change according to the firmware revision.

       To  descend in even greater complexity, there usually exist 2 files for
       each firmware revision in the ATMEL+RFMD world: one  so-called  primary
       firmware (the bigger file of the two; it contains base firmware as well
       as the embedded webserver), and a second  file  with  so-called  backup
       firmware  (the  smaller  file  of  the  two,  it contains just the base
       firmware).  The name of secondary firmware always uses '0' in the third
       number  field  (such as "0.2.0.18.rom").  You'll always need to upgrade
       with backup firmware FIRST, unless its manufacturer states otherwise.

WARNING!!! WARNING!!! WARNING!!! WARNING!!! WARNING!!!


    o  WA firmwares and their derivatives ARE _NOT_ SUPPORTED  by  ap-utils!!!
       They may appear to partially work with ap-utils, but you can cause harm
       to your AP if you use ap-config with such firmware. Do not complain  if
       you use ap-config with such firmware and it damages your AP!

    o  Since  some  hardware  vendors keep up the bad habit of producing their
       own firmwares using the original ATMEL firmware naming  scheme,  it  is
       easy  to find firmwares from different hardware vendors for ATMEL-based
       APs with exactly the same name  and  sometimes  even  the  length  (for
       example,  firmware  "1.4j.1.rom" exists in many incarnations, but their
       content differs). They may use different  structures  and  offsets  for
       reading configuration data in the flash memory without content validity
       checks, so NEVER EVER USE FIRMWARE FROM ANOTHER  HARDWARE  VENDOR  THAN
       THE  ONE  THAT  IS  MANUFACTURING  YOUR  AP,  UNLESS  EXPLICITLY STATED
       OTHERWISE! IF YOU DO SO, YOU MAY IRREVERSIBLY DAMAGE YOUR AP!

    o  BEWARE! AP boards from several  vendors  may  contain  hardware  design
       bugs,  that  will  totally  prevent  it  from successfull upgrade.  Any
       attempt to upgrade such device, either via TFTP  or  DFU  utility  will
       fail  and  irreversibly  damage  content  of  its flash memory! If your
       vendor does NOT provide ANY firmware nor tools to perform  upgrade  for
       your  device,  it means (unless stated otherwise), that IT IS UNSAFE TO
       TRY UPGRADING and YOU SHOULD NOT ATTEMPT TO UPGRADE YOUR DEVICE AT ALL!
       Example  of  such board with bug in hardware design is Tellus A13 (also
       sold as i-Tec AP GOLD with blue front).

    o  ATMEL AT76C510-based APs  are  notoriously  known  for  their  firmware
       upgrade   design   flaw:  firmware  validation  checks  and  subsequent
       permission for upgrade are not performed by the AP itself, but  in  the
       TFTP  upgrade  client.  This means that anyone with proper TFTP client,
       having access to your AP via its ethernet port,  may  _try_  to  upload
       incorrect  firmware  (or  even  no-firmware  file!) to your AP, causing
       irreversible damage to your AP. Hence:

       -  SECURE YOUR AP ON IP (LAYER 3)  BASIS!  SET  UP  YOUR  AP  (AND  ITS
          WIRELESS  CLIENTS)  WITH IP FROM A DIFFERENT IP SEGMENT THAN THE ONE
          IT IS PHYSICALLY ON. TO ACCESS AP ON SUCH DIFFERENT SEGMENT, YOU MAY
          USE IP-ALIAS INTERFACE (on Linux).

       -  FOR APs IN Access Point client MODE, USE ap-config AND IN 'Config ->
          Bridge' MENU, CHANGE THE VALUE OF  'Configuration-enabled  port(s):'
          TO 'Wireless'. THIS WAY, USER BEHIND Access Point client DEVICE WONT
          BE ABLE TO REACH ITS MANAGEMENT IP, AND SUBSEQUENTLY (S)HE  WONT  BE
          ABLE TO CAUSE ANY DAMAGE WITH TFTP.  Note that setting Conf.-enabled
          port to 'Wireless' may be risky if you  intend  to  reconfigure  the
          device through Wireless media (bad values could be written to the AP
          due to wireless media unreliability). You should choose what  is  of
          greater risk for you.

    o  Users  of ATMEL+INTERSIL devices: If your AP firmware vendor extensions
       are auto-detected as SBRIDGES by ap-config, it means that your AP  uses
       firmware  made  by  smartBridges  PTE:  you will need to pass extra '-c
       community' to ap-tftp in order  to  perform  actual  upgrade.   BY  ALL
       MEANS,  AVOID  UPGRADE  OF  DEVICE THAT CONTAINS smartBridges FIRMWARE,
       with non-smartBridges FIRMWARE, AND VICE VERSA, even  if  the  firmware
       names  may  look  similar  (see the warning above).  Although there are
       checks in ap-tftp, that should avoid something such, be careful, and DO
       NOT  TRY,  UNDER  ANY CIRCUMSTANCES, to circumvent this protection - if
       you do, you'd most likely end up with damaged  flash  content  in  your
       device. You got the warning.

       Remember:  All  firmware  files with revision "1.4j.4" onwards are from
       smartBridges: unless you possess a device  that  is  autodetected  with
       'SBRIDGES'  vendor  extension,  DO  NOT  TRY TO UPGRADE TO smartBridges
       FIRMWARE!

    o  Users of ATMEL+RFMD devices: If you  are  running  primary  firmware  <
       0.2.2.20,  you  should  upgrade  as  soon  as  possible! AP firmware of
       version 0.2.2.19 and lower contains serious 'death by  reconfiguration'
       bug,  which,  if  triggered,  may  irreversibly damage content in flash
       memory of your AP. The event to trigger is usually changing  &  writing
       some settings in the 'Bridge' menu. So if you run such firmware, please
       upgrade. You may  also  look  into  README  to  see  whether  'Firmware
       available  free of charge for ATMEL12350 MIB devices' (section) applies
       to your AP.

GENERAL HINTS AND RECOMMENDATIONS PRIOR UPGRADING


    -  IF POSSIBLE, PLACE YOUR AP BEHIND A FIREWALL SO THAT YOU PREVENT ACCESS
       TO ITS MANAGEMENT IP FOR UNWANTED THIRD PARTIES

    -  Avoid  upgrading your AP via its wireless port, if possible. Due to the
       unreliable nature of wireless media and UDP protocol used for  upgrade,
       anything  could  happen  -  although  there  is  CRC-like  check in the
       firmware, that prevents flashing of (firmware) file that  has  possibly
       been  altered  during  transmission, upgrade process interruption might
       cause damage (but even this is not very likely). You may upgrade AP via
       its  wireless  port only if you're 101% sure the wireless connection to
       the target device is reliable.

    -  If you experience upgrade  timeout  in  the  'middle'  of  the  upgrade
       progress,  it  is usually ok to wait until the utility completely times
       out, and repeat the command afterwards. You may also experience  'catch
       up'  (very  short  network  break,  so  utility  will  resume uploading
       firmware to your AP).

    -  In case when firmware upgrade fails, ap-tftp will show  an  error  code
       returned  by the TFTP server in AP. Note that although RFC 1350 defines
       8 TFTP error messages, the TFTP server in the AP is  not  compliant  to
       this  RFC  and  the  error  codes  returned may NOT correspond to those
       messages (but ap-tftp will  always  display  corresponding  RFC-defined
       error  message,  if possible, although it may really have nothing to do
       with the returned error code meaning). In  the  case  the  message  for
       error  code  returned  is  not defined in RFC 1350, just the error code
       alone will be displayed.

    -  If you want to upgrade firmware in an AP on a  network  where  no  DHCP
       server  is  available,  it is advisable to assign static IP address and
       disable DHCP option on the device, so that you can verify,  whether  it
       is  alive,  using 'ping' command immediately after the upgrade succeeds
       (generally immediately after the device boots up), and you dont have to
       wait  until AP's attempts to contact DHCP server time out. This is also
       especially useful if you need to do 2-step upgrade (using 'backup'  and
       'primary' firmware) - see above.

    -  Firmware  of  APs based on ATMEL AT76C510 provides an interresting 'arp
       ping' feature. After  AP  boot-up,  it  is  possible  to  remotely  and
       TEMPORARILY  (to  next  AP reboot) reconfigure its IP address, provided
       that within certain time period (several tens of  seconds  after  boot-
       up), the AP receives ICMP ECHO request with target MAC address equal to
       its own. To set up IP in the AP using this method, do the following:

       1.  From the IP range your AP is connected to, pick up an unused IP you
           want to set on the AP using 'arp ping'.

       2.  Set up static ARP entry associating the MAC address of your AP with
           the IP you selected in paragraph 1. Typically, you  need  to  issue
           (as  root)  something like: 'arp -s required_AP_IP AP_MAC'. Consult
           manpage for 'arp' utility, if your  'arp'  utility  uses  different
           syntax.

       3.  Right  after  the  AP boots, run 'ping required_AP_IP'. You need to
           wait few seconds prior seeing first AP response.

    -  Users of ATMEL+RFMD devices: To DOWNGRADE to  AP  firmware  with  lower
       revision number than the one thats currently in the device, you'll need
       to temporarily 'upgrade' to any WA firmware available for  your  device
       (as step-in-the-middle). This will 'unlock' your device for downgrading
       to previous AP firmware version.

OPTIONS

       -i IP  IP address of the AP you want upgrade firmware in.

       -f firmware.rom
              Full path to and name of the firmware file for your AP.

       -c community
              To be used ONLY with APs manufactured by smartBridges  PTE.  The
              given  community  must match with any of three three communities
              currently defined in the AP  configuration  -  firmware  upgrade
              will be allowed only upon the match.  matches

EXAMPLES OF USE

   Upgrading  AP firmware in a device with INTERSIL radio and non-smartBridges
       firmware

       ap-tftp -i 192.168.0.1 -f 1.4j.3.rom

   Upgrading AP firmware in a device  with  INTERSIL  radio  and  smartBridges
       firmware

       ap-tftp -i 192.168.0.24 -f 1.4k.5.rom -c private

   Upgrading AP firmware in a device with RFMD radio:

       ap-tftp -i 192.168.1.100 -f 0.2.0.20.rom
       ap-tftp -i 192.168.1.100 -f 0.2.2.20.rom

   Downgrading AP firmware in a device with RFMD radio:

       ap-tftp -i 192.168.1.100 -f 0.3.0.6.rom
       ap-tftp -i 192.168.1.100 -f 0.3.2.6.rom
       ap-tftp -i 192.168.1.100 -f 0.2.0.19.rom
       ap-tftp -i 192.168.1.100 -f 0.2.2.19.rom

KNOWN BUGS

       This  utility  has  not  been verified on and will probably not work on
       big-endian architectures. Its use is discouraged in such environment.

AUTHOR

       Jan Rafaj <jr-aputils at cedric dot unob dot cz>
       http://ap-utils.polesye.net

SEE ALSO

       ap-config(8), ap-trapd(8), ap-auth(8), ap-mrtg(8)

                    Wireless Access Point Utilites for Unix         ap-tftp(8)