ap-tftp -i IP -f firmware.rom
[-c community ]
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.
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:
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.
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.
- -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
This utility has not been verified on and will probably not work
on big-endian architectures. Its use is discouraged in such environment.
Jan Rafaj <jr-aputils at cedric dot unob dot cz>
http://ap-utils.polesye.net