ap-tftp(8)						      System Manager's Manual							ap-tftp(8)

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  de-
       rivatives, 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  pri-
       mary  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 oth-
       erwise.

	      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 dam-
	      ages 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  struc-
	      tures  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  SUBSE-
		 QUENTLY (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  unreliabil-
		 ity). 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  some-
	      thing 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 corre-
	      spond 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 cur-
	      rently 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)