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)