Provided by: ap-utils_1.5-2_amd64 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)