Configuration of the Update-Server
It is possible to maintain firmware and configuration of a large number of innovaphone devices in a distributed environment automatically. Also, full configuration backups can be done. This is done by storing configuration and firmware information on a standard Web server, which in turn is accessed by the individual devices under control of the so-called update-script.
There are two modules in the device which work in tandem. The first is known as "UP0" and actually executes the upload and download of configuration information as well as the download of updated firmware. UP0 is controlled by commands as detailed below. The second module is known as "UP1". It serves to retrieve the update script from a given URL periodically. If certain conditions are met, UP1 will issue commands to UP0 to perform the requested updates.
- One or more Web server(s) accessible by the devices.
- The Web servers tested were MS IIS and the Apache server. It should, however, also work with all other common Web servers.
- For best results, the Web server should be able to manage a large number of simultaneous HTTP sessions. MS Personal Web Server, for example, is not a suitable Web server, since it manages a maximum of 10 simultaneous HTTP sessions.
To be able to transfer device configurations onto the Web server, the latter must allow HTTP PUT requests. All other functions require HTTP GET authorisation.
HTTP requests issued by the update server may be authenticated using the standard mechanism provided in Configuration/General/HTTP-Client. However, in many cases it is most convenient to allow anonymous access to the Web server as this enables devices with factory default settings (and thus no credentials configured) to use the update server for initial configuration.
To allow HTTP PUT commands on your Web server may require special configuration. Consult the web servers documentation.
Detailed information on how the URL and poll interval parameter of the update server are configured may be found in Configuration/General/Update.
Note the URLs used here (just like all other URLs used by innovaphone devices) does not support host names. Therefore, a valid IP address always has to specified.
If the URL happens to end with a ‘/’, then a standard file name based on the product description is used. If, for example, the URL is http://220.127.116.11/configs/ , then it is extended in the case of an IP1200 as follows: http://18.104.22.168/configs/update-ip1200.htm . The product name is specified in Configuration/General/Info. The file extension is irrelevant here. The extension *.txt or *.htm or no file extension at all is possible. In relation to URL specifications, note that some Web servers differentiate between upper case and lower case letters.
All URLs both in the update server configuration as well as in the update commands (UP0 and UP1) are #-replaced (see scfg command below).
The update script file is read when the update interval has expired. If the file could be retrieved in its entirety, it is executed immediately. The first update interval timer is set when the device re-starts and the first execution of the script will be when the first interval has expired.
When the maintenance file has been successfully received, it is executed sequentially. Theoretically, all commands that can be transmitted to the device in a telnet session or that occur in a configuration file can be used in the maintenance file. Note however that while
UP0 is active, there can be no other command to it. For example, it is not possible to issue a
mod cmd UP0 prot ... in a command script read by
mod cmd UP0 cfg ....
Note that the commands in the update script are executed whenever the file has been retrieved. To make sure commands are executed only when necessary, use the update serials (see below).
Additional commands implemented specially for the update server are available.
In most cases, however, the maintenance file should not be executed every time when it is received, but once only. Assuming that a certain configuration has to be loaded onto several devices, then it is best if this is done from a common source. This can be achieved with the check command:
mod cmd UP1 check <final-command> <serial>
innovaphone devices have an internal variable that is initially empty (or empty if the device was reset to the factory defaults) called UPDATE/CHECK. The check command compares the content of <serial> with the UPDATE/CHECK variable. If both match, all further commands of the maintenance file are skipped.
If they differ, the remaining commands are executed. When the last command has been executed and the script is not interrupted by another commmand, the UPDATE/CHECK variable is set to the value <serial>, and the <final-command> is executed. The following commands can be specified as <final-command>
reset: Resets the device immediately
ireset: Resets the device as soon as it is not being actively used.
resetn: Resets the device immediately if a reset is required
iresetn: Resets the device as soon as it is not being actively used and a reset is required
reboot: power cycles the device immediately
ireboot: power cycles the device as soon as it is not being actively used
rebootn: power cycles the device immediately if a reset is required
irebootn:power cycles the device as soon as it is not being actively used and a reset is required
no-op: no operation
ser: same as no-op
If one of the commands following the check command starts a reset sequence (
ireset, ...) the UPDATE/CHECK variable is NOT updated and the <final-command> is NOT executed. Thus a reset should be initiated only by the <final-command>. Otherwise the maintenance file could be executed again and again after each reset.
Often, configuration changes shall be made only during certain times (e.g. non-working hours). This can be achieved using the times command:
mod cmd UP1 times [/allow <hours>] [/initial <minutes>]
The times command will check the current time against <hours>. If it does not match this restriction, any further processing of the command file is cancelled. <hours> is a comma separated list of hours. Only those hours listed are considered valid times for execution of the command file.
mod cmd UP1 times /allow 12,22,23,0,1,2,3,4
will allow command executions only between 12:00 and 12:59 and 22:00 and 4:59 local time (on a 24h clock). Note that if the device has no time set (yet), all command executions will be canceled.
If the /initial parameter is set, then no commands will be executed within the first <minutes> minutes after the device has been booted. This is done to avoid firmware download and flashing when installing devices.
mod cmd UP1 times /allow 12,22,23,0,1,2,3,4 /initial 6
will suppress any command file processing within the first six minutes after each boot of the device.
If /initial is set, for new devices (or those that have been reset to factory settings), the command file will be retrieved even if it normally would be suppressed by the /allow parameter. This allows new devices to retrieve a site specific standard configuration quickly (a.k.a. staging).
Handling of virgin Devices
Devices in factory default settings state are handled differently in that the
times command may allow further execution of the update script even though the
/allow condition is not met (depending on the setting of
/initial). A device is considered virgin if at boot none of the update serial tags (e.g.
UPDATE/CHECK, see below) is set. If so, the virgin state is set and remembered in persistent flash memory. The virgin state is then kept across re-boot and cleared only after an update script has been fully executed without being interrupted by a re-boot (or reset).
This allows staging update scripts to finish right after installation, even if it takes one or more resets.
To initiate a firmware update, the following command can be executed:
mod cmd UP0 prot <url> <final-command> <build-serial>
This command downloads new firmware (if available) from the specified URL onto the device. Finally, the <final-command> is executed. innovaphone devices have an internal variable that is initially empty (or empty if the device was reset with the standard settings) called UPDATE/PROT. The prot command compares the content of <build-serial> with the UPDATE/PROT variable. If both match, no firmware is downloaded. If the UPDATE/PROT variable is not set (new devices or after a device restart), the content of <build-serial> is compared with the built number of the current firmware. Once the firmware has been successfully downloaded, the UPDATE/PROT variable is overwritten with the content of <build-serial> . Note that the <build-serial> parameter is not compared with the firmware version currently loaded. It is the responsibility of the administrator to keep this standard.
If the <url> parameter ends with a slash (‘/’), a standard firmware file name is appended to the URL depending on the product description (for example, IP1200.bin for an IP DECT system).
mod cmd UP0 prot http://192.168.0.10/firm/ip1200.bin ireset 04-5656
mod cmd UP0 prot http://192.168.0.10/firm/ ireset 04-5656
determines whether the firmware version 04-5656 was already installed. If this is not the case, the current firmware is downloaded from the address 192.168.0.10/firm/ip1200.bin, the UPDATE/PROT internal variable is overwritten with 04-5656 and, finally, the device is reset as soon at it is not being actively used.
With the boot command, the boot code is updated. It works in the same way as the prot command for the firmware.
mod cmd UP0 boot <url> <final-command> <built-serial>
mod cmd UP0 boot http://192.168.0.10/firm/ ireset 205
determines whether the boot code version 205 was already installed. If this is not the case, the current boot code is downloaded from the address 192.168.0.10/firm/boot1200.bin, the UPDATE/BOOT internal variable is overwritten with the version number of the downloaded boot code (205) and, finally, the device is reset as soon as it is not being actively used.
For devices which need a reboot to activate the new bootcode the commands "reboot" and "ireboot" are available and should be used to reboot the device after boot code update. The system is run down the same way as with "reset" and "ireset" but finally a watchdog restart is forced instead of a soft restart. Note that these commands do not work with the IP21!
Bmc command (only for DECT devices)
With the bmc command, the DECT radio code ( aka burst mode controller firmware or BMC code ) is updated and this is done in the same way as with the prot command.
mod cmd UP0 bmc <url> <final-command> <build-serial>
The name of the file to use must be given explicitely here (the file name appended to an <url> parameter ending with a slash (‘/’) has no ".bin" suffix like the delivered file).
mod cmd UP0 bmc http://192.168.0.10/firm/ccfp1200.bin ireset PCS04fd
determines whether the DECT radio code PCS04fd was already installed. If this is not the case, the current DECT radio code is downloaded from the address 192.168.0.10/firm/ccfp1200.bin, the UPDATE/BMC internal variable is overwritten with PCS04fd and, finally, the device is reset as soon at it is not being actively used.
mod cmd UP0 scfg <url> [<final-command> <save-serial> [ /force <hours> ]]
This will cause the device to upload its current configuration to <url>. This will be done using an HTTP PUT command. <url> must be writable thus. Within <url>, some meta character strings are replaced as follows:
|kernel build number
|first n digits of kernel build number after the dash
|boot code build number
|MAC address of the device
|Current date and time
|rolling backup index
|(one of) the local IP address(es)
|network (that is, IP address with host bits set to 0)
|escapes a hash mark
Any unknown #-meta sequence is replaced by meta-unsupported.
This meta character strings are available in the URL of CFG, SCFG, PROT and BOOT command and in the Update Server URL.
The device name provided by #n is the name configured under "Configuration/General/Admin/Device Name" with space-, control- and punctuation characters except '-' replaced by '_'. Because this name is not necessarily unique #n should only be used in combination with one of the unique identifiers #h, #m or #i. If there is no name configured #n is replaced by "noname".
The rolling backup index loops over 0 .. n-1 for each backup and can only be used once in an update script. That means more than one SCFG command in a script with a usage of the rolling backup index will overlap and produce unexpected results.
Beginning with V7.00 the optional Parameters <final-command>, <save-serial> and /force <hours> will be recognized.
- <final-command> defines the command to be executed after successful completion of scfg (typically no-op is used).
- <save-serial> is compared to the UPDATE/SCFG variable. If it is not equal, the command is started. If it is equal and /force is not specified the command is skipped, otherwise /force is evaluated.
- /force <hours> specifies the number of hours after which scfg is executed again even if <save-serial> has not changed.
mod cmd UP0 scfg http://192.168.0.10/configs/saved/#h#b5.txt no-op WEEKLY /force 168
will save the device configuration once per week with a backlog of 5 weeks.
Note: writing files to the CF card is slow. It is thus likely that clients doing so will consume the full TCP window size on the web server. If this is a device with small memory (such as IP302 or IP305), this can easily result in an "out of memory" trap. From Version 7 hotfix6 on, you can reduce the windows size using IP0's
/tcp-bs-small option, e.g.
config add IP0 /tcp-bs-small 4096. The default is 65535.
A configuration file may be loaded using the CFG command:
mod cmd UP0 cfg <url> <final-command> <serial>
The file will be read, all configuration commands in there executed and a final config write appended. Please note that no activation will be done implicitly. Thus, you will likely either use reset as <final-command> or use ser and have a config activate and iresetn follow.
Please note that only
config change statements in <url> will reliably trigger the reset needed condition (if required). Other statements such as
vars create or
mod cmd will not. You can add
nreset to trigger this condition, e.g.
# turn on CLIR vars create PHONE/USER-CLIR/00000 p 1 # as we have changed vars, indicate a reboot needed nreset
Special WiFi (WLAN) IP72 commands
IP72 terminals are operated in different power-save modes, in order to enable longer battery life and reduce charging periods. However, these power-save modes are optimized for VoIP applications and perform rather poorly in a bulk firmware upload scenario. Broken http sessions and hanging and not correctly functioning updates may result.
The solution for the problem is to temporarily deactivate the configured power-save mode until the firmware upload completes.
This is done automatically for the web-based firmware and bootcode upload, but has to be explicitly stated in an update script.
Command to explicitly set active-mode (deactivate power-save):
mod cmd WLANMGR0 activate-pwr
Upon firmware (and bootcode) upload completion, power-save should be enabled again by:
mod cmd WLANMGR0 deactivate-pwr
So here an example:
... mod cmd WLANMGR0 activate-pwr mod cmd UP0 prot http://192.168.0.10/firm/ ireset 04-5656 mod cmd WLANMGR0 deactivate-pwr ...
If firmware upload has been initiated, the terminal is resetted and the deactivate part is not being invoked, this is, however not a problem, because after reboot, the terminal starts in a preconfigured power-save mode anyhow.
A reference to other WLAN commands: Howto:Firmware Upgrade and initial Configuration of IP72 via USB#Other_useful_commands
An manual update can be forced by the following command:
mod cmd UP1 poll
A Web server exists at the address 192.168.0.10 with a subdirectory called configs. In this directory, there are two further subdirectories, in which the current firmware files for all innovaphone devices are stored. Clients provide the DHCP server with the option #215 as http://192.168.0.10/configs/. In this directory, there is a file update-ip1200.htm , which processes the following lines:
mod cmd UP1 times /allow 23,0,1,2,3,4 /initial 6 mod cmd UP0 scfg http://192.168.0.10/configs/saved/#h.txt no-op WEEKLY /force 168 mod cmd UP0 prot http://192.168.0.10/configs/04-5679/ ireset 04-5679
This example demonstrates how the configuration of a device is stored on a Web server; all IP1200 devices are then instructed to load/update the firware version 04-5679 in the time period 23:00 hrs to 04:59 hrs. New devices are updated after a restart and after the specified six minutes have elapsed.
There is also the file update-ip3000.htm, which reads the following two lines:
mod cmd UP1 times /allow 23,0,1,2,3,4 mod cmd UP0 prot http://192.168.0.10/configs/04-5679 /ser 04-5679
IP3000 devices are updated to firmware version 04-5679 in the time period 23:00 hrs to 04:59 hrs.
Using an innovaphone box as web server
Any box with a CF slot and a CF card installed can serve as web server platform to read update scripts, firmware files, configuration files or to save configurations from V6 SR1 on.
All commands issued by UP1 to UP0 (prot, boot, bmc, cfg and scfg) and all other commands (config...) run synchronous, i.e. UP1 wait's for the result of a command before starting the next one.
The Configuration/General/Update tab will show the update client status. Common error message include:
- not polled. The client has not (yet) polled the command script. This is probably because the script is polled the first time only after the interval has expired
- failed(401). The client has no sufficient access right to read the command script from the HTTP server
- failed(404). The update command script does not exist. You probably misspelled the path or name.
- failed(502). Might indicate problems with a proxy server on the far end. However, the HTTP client currently generates 502 for badly formed URLs also (e.g.
http:172.31.2.3/drive/cf0/update/update-all.txt). Please note that URLs must not contain host names (see Configuration). Also, when HTTPS is used and fails (e.g. due to untrusted certificates), this error code is generated.
Generally, numeric error codes in parentheses (such as
failed(401)) are taken from the last HTTP error code received by the update client. More about HTTP error codes can be found in the German and English wikipedia .