Reference:Update Server

Configuration of the Update-Server

It is possible to update the firmware and configuration of a large number of innovaphone devices in a distributed environment by automated means.

This is done by storing the configuration and firmware information on a standard Web server, which in turn is called up the individual devices.

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 poll a given website for changed configuration information. If certain conditions are met, UP1 will issue commands to UP0 to perform the requested updates.

System requirements

• 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.

Installation

To be able to transfer device configurations onto the Webserver, the latter must allow HTTP PUT requests. All other functions require HTTP GET authorisation.

Since all HTTP requests are executed unauthenticated, the Web server must allow anonymous reading and possibly also anonymous writing.

To allow HTTP PUT commands on a MS IIS, the read and write check box must be enabled in the configuration of the relevant virtual directory.

Configuration

Detailed information on how the URL parameter of the update server is configured on the innovaphone devices may be found in the chapter entitled "Configuration/General/Update".

Note here that the URL parameter must point precisely to the location of the file with the contained maintenance commands. It is also to be noted that this URL (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://1.2.3.4/configs/ , then it is extended in the case of an IP1200 as follows: http://1.2.3.4/configs/update-ip1200.htm . The product name is specified in the first line in chapter "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.

Running maintenance

The update file is immediately read and also immediately executed. After a device restart, the update server is automatically queried periodically in accordance with the interval set.

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.

Maintenance commands

Additional commands implemented specially for the update server are available. The maintenance file is executed every time (depending on the interval set), as soon as it is received.

Check command

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>

• ireset: Resets the device as soon as it is not being actively used.
• reset: Resets the device immediately.
• iresetn: Resets the device as soon as it is not being actively used and a reset is required.
• resetn: Resets the device immediately if a reset is required.
• ser: no-op

Times command

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 cancelled.

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.

Prot command

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

The command

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.

Boot command

With the boot command, the boot code is updated and this is done in the same way as with the prot command.

mod cmd UP0 boot <url> <final-command> <built-serial>

The command

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.

Since V6.00 sr2-hotfix3 the commands "reboot" and "ireboot" are available and should be used to reset the device after boot code update to activate it. 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 this command doesn't work with 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).
The command

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.

SCFG command

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:

Sequence	Replaces	Example
#F	kernel build number	08-12345
#B	boot code build number	401
#H	hardware build	102
#h	Device hardware number	IP1200-03-0d-f0
#m	MAC address of the device	00-90-33-03-0d-f0
#d	Current date and time	20051010-170130
#bn	rolling backup index	3
#i	(one of) the local ip-address(es)	192.168.0.1

This meta character strings are available in the URL of SCFG command and in the Update Server URL only.

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.

CFG command

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 UP0-commands cannot be nested. As a result, a script read by mod cmd UP0 cfg cannot contain other mod cmd UP0 cfg commands.

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

Example

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.

Synchronous operation

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.

Manual Update

An manual update can be forced by the following command:

mod cmd UP1 poll

Common Problems

The Reference: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)

Generally, numeric error codes in parantheses (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 .