Documentation/ap-tftp.8

   1 .\"      Manpage for ap-tftp utility
   2 .\"   from Wireless Access Point Utilitess for Unix
   3 .\"
   4 .\"  Copyright (c) 2004-2005 Jan Rafaj <jr-aputils at cedric dot unob dot cz>
   5 .\"
   6 .\"  This program is free software; you can redistribute it and/or modify
   7 .\"  it under the terms of the GNU General Public License Version 2 from
   8 .\"  June 1991 as published by the Free Software Foundation.
   9 .\"
  10 .\"  This program is distributed in the hope that it will be useful, but
  11 .\"  WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 .\"  GNU General Public License for more details.
  14 .\"
  15 .\"  You should have received a copy of the GNU General Public License along
  16 .\"  with this program; if not, write to the Free Software Foundation, Inc.,
  17 .\"  59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  18 .TH ap-tftp 8 "Wireless Access Point Utilites for Unix"
  19 .SH NAME
  20 ap-tftp \- TFTP client for upgrading ATMEL AT76C510 WiSOC-based APs
  21 .TP
  22 .B Please read the entire manpage prior using this utility. It may prevent you from problems arising later.
  23 .SH SYNOPSIS
  24 .B ap-tftp
  25 .B -l
  26 .IR firmware.rom
  27 .B IP
  28 .SH DESCRIPTION
  29 The
  30 .B ap-tftp
  31 utility is used to upgrade 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 (both 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.
  32 .SH PREFACE: FIRMWARE TYPES
  33 Functionally, there basically exist 2 types of firmware for ATMEL-based APs: an "
  34 .B Access Point
  35 firmware (often referred as
  36 .B AP
  37 firmware), and
  38 .B Wireless Adapter
  39 firmware (referred to as
  40 .B WA
  41 firmware). Many hardware vendors produce their own more or less modified firmware derivatives, but usually they keep up with naming scheme introduced by ATMEL:
  42 .SS APs with INTERSIL radios
  43 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, ab, and the letter x change according to firmware revision.
  44 .SS APs with RFMD radios
  45 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"). Again, the numbers change according to firmware revision.
  46
  47 To descend in even greater complexity, there usually exist 2 files for each firmware revision in the ATMEL+RFMD world: one so-called
  48 .B primary
  49 firmware (the bigger file of the two; it contains base firmware as well as the embedded webserver), and a second file with so-called
  50 .B backup
  51 firmware (the smaller file of the two, it contains just the base firmware).
  52 The name of secondary firmware always uses '0' in the third number field.
  53 .B You'll always need to upgrade with
  54 .B backup firmware FIRST, unless manufacturer states otherwise.
  55 .TP
  56 .RE 4
  57 .B WARNING!!! WARNING!!! WARNING!!! WARNING!!! WARNING!!!
  58 .RS 4
  59 .IP o 3
  60 .B WA
  61 firmwares
  62 .B ARE _NOT_ SUPPORTED
  63 by ap-utils!!! They may appear to partially work with ap-utils, but you
  64 can cause harm to your AP if you use ap-config with such firmware. Do not
  65 complain if you use ap-config with such firmware and it damages your AP!
  66 .IP o
  67 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
  68 .B exactly the same name and sometimes even the length
  69 (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
  70 .B 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!
  71 .IP o
  72 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:
  73 .RS 3
  74 .IP \- 3
  75 .B 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).
  76 .IP \-
  77 .B 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.
  78 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.
  79 .RE 1
  80 .RS 4
  81 .IP o 3
  82 .B Users of ATMEL+RFMD APs:
  83 If you are running
  84 .B primary
  85 firmware < 0.2.2.20, you
  86 .B should upgrade as soon as possible! AP
  87 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.
  88 .TP
  89 .RE 1
  90 .B GENERAL HINTS AND RECOMMENDATIONS PRIOR UPGRADING
  91 .RS 4
  92 .IP \- 3
  93 IF POSSIBLE, PLACE YOUR AP BEHIND A FIREWALL SO THAT YOU PREVENT ACCESS TO ITS MANAGEMENT IP FOR UNWANTED THIRD PARTIES
  94 .IP \-
  95 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.
  96 .IP \-
  97 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).
  98 .IP \-
  99 In case when firmware upgrade fails,
 100 .B ap-tftp
 101 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.
 102 .IP \-
 103 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, 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.
 104 .IP \-
 105 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:
 106 .RS 3
 107 .IP 1\. 4
 108 From the IP range your AP is connected to, pick up an unused IP you want to set on the AP using 'arp ping'.
 109 .IP 2\.
 110 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 this differs for you.
 111 .IP 3\.
 112 Right after the AP boots, run 'ping required_AP_IP'. You need to wait few seconds prior seeing first AP response.
 113 .RE 1
 114 .RS 4
 115 .IP \- 3
 116 .B Users of ATMEL+RFMD APs:
 117 To
 118 .B DOWNGRADE
 119 to
 120 .B AP
 121 firmware with lower number than the one thats currently in the device, you'll need to temporarily 'upgrade' to any
 122 .B WA
 123 firmware available for your AP (as step-in-the-middle). This will 'unlock' your device for downgrading to previous
 124 .B AP
 125 firmware version.
 126 .SH OPTIONS
 127 .TP
 128 .B -l firmware.rom
 129 Full path to and name of the firmware file for your AP.
 130 .TP
 131 .B IP
 132 IP address of the AP you want upgrade firmware in.
 133 .RE
 134 .SH EXAMPLES OF USE
 135 .PD 0
 136
 137 .SS Upgrading "AP" firmware in AP with INTERSIL radio:
 138 .BR
 139 .TP
 140 ap-tftp -l 1.4j.3.rom 192.168.0.1
 141
 142 .SS Upgrading "AP" firmware in AP with RFMD radio:
 143 .BR
 144 .TP
 145 ap-tftp -l 0.2.0.20.rom 192.168.1.100
 146 .TP
 147 ap-tftp -l 0.2.2.20.rom 192.168.1.100
 148
 149 .SS Downgrading "AP" firmware in AP with RFMD radio:
 150 .BR
 151 .TP
 152 ap-tftp -l 0.3.0.6.rom 192.168.1.100
 153 .TP
 154 ap-tftp -l 0.3.2.6.rom 192.168.1.100
 155 .TP
 156 ap-tftp -l 0.2.0.19.rom 192.168.1.100
 157 .TP
 158 ap-tftp -l 0.2.2.19.rom 192.168.1.100
 159
 160 .SH AUTHOR
 161 Jan Rafaj <jr-aputils at cedric dot unob dot cz>
 162 .br
 163 http://ap-utils.polesye.net
 164
 165 .SH SEE ALSO
 166 ap-config(8), ap-trapd(8), ap-auth(8), ap-mrtg(8)
 167