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)