Reference13r3:Concept Update Server
Use of the Update Server in v13r3 and later
From version 13r1 the update server is deprecated and the Devices App is used instead. However, if you still want to use it (e.g. because you have working update scripts), you can still do this from version 13r3 on.
In order not to interfere with Devices' provisioning scheme, you must not deploy the update server URL using DHCP (nor use the project specific update server URL setting in my.innovaphone.com). Instead you would set both the update script URL and the polling frequency as part of the Expert configuration . The update script would then be executed for the first time right after the device is provisioned by Devices and all the configuration jobs set forth in Devices have been applied. Please take note of the limitations mentioned in the Expert configuration section.
If convenient, you can use the Files App to store the update scripts. However, keep in mind that it requires either authenticated access or access using a files key (see Where to store media files for an example how to obtain it).
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 Services/HTTP/Server. 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 Services/Update.
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 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 as a web 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, 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 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 (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 time 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.
This command creates a persistent variable in the flash memory. The value of this variable can be substituted in the URL part of other commands:
mod cmd UP1 setvar <name> <value>
As well <name> as <value> must not contain space characters and <name> must not exceed 16 characters. The <value> will be stored under the name UPDATE/USER/<name>. In an URL it is referred to by #(<name>).
By default, variable substitution (as described in SCFG Command) is done within the URL parameter of UP0/1 commands only. You can enable variable substitution in all parts of all lines within the update script using the
mod cmd UP1 replace all
command. The default can be restored using
mod cmd UP1 replace url
Please note that variable substitution never takes place in files read with the mod cmd UP0 cfg command.
Evaluates a variable and writes the result into the same variable.
mod cmd UP1 setvar var-x xval mod cmd UP1 setvar var-y yval mod cmd UP1 setvar mytype y # a mod cmd UP1 setvar var ##(var-#(mytype)) # b mod cmd UP1 eval var
Line a will evaluate
##(var-#(mytype)) and thus set variable
var to value
#(var-y). Line b will then evaluate
#(var-y) (the value of
var) and thus set
yval (the value of
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. 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, IP1202.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 IP1200 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:
|#F||kernel build number||09-7030014|
|#fn||first n digits of kernel build number after the dash||70300|
|#B||boot code build number||09-7030012|
|#m||MAC address of the device||00-90-33-03-0d-f0|
|#d||Current date and time (plain UTC without daylight saving and timezone adjustments)||20051010-170130|
|#bn||rolling backup index||3|
|#i||(one of) the local IP address(es)||192.168.0.1|
|#N||network (that is, IP address with host bits set to 0)||192.168.0.0|
|#(var)||value of variable var as set by setvar||log-file-5.txt|
|#p||provisioning code typed in by the user||012-345-678-901 or p-unsupported (for pre-v13r1 devices)|
|##||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 1..n and will be stored in the Phone variable CFG-BACKUP-NUM. That means if you use more than one SCFG commands in a script the rolling backup index will be splittet over all commands. Example: rolling backup index = 6 / first SCFG command - 1,3,5 / second SCFG command - 2,4,6.
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. If there is no <save-serial>, the command is executed unconditionally.
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. 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
note that persistent assignments (such with a
p flag) will always trigger a reset needed condition - even if the value did not change.
During staging, the normal poll interval (which is long) may not be sufficient, as you probably want to have multiple scripts executed in sequence (via
config add UP1 /url url):
mod cmd UP1 provision <seconds>
sets the poll interval for the next poll cycle after completion of the current script to the given number of seconds (max. 60). This interval is duplicated after each failing poll to avoid continued fast re-polls when the URL cannot be reached. Setting it to 0 disables fast poll and restores the value set with the
/poll command line option.
Note however that this setting is lost in a reset. To have a similar effect after a reset (that is, have the device poll the next update script soon), you can do
config add UP1 /provision <seconds> config write
Be sure to remove this setting in your last script using something like
# last script - turn off fast polling mod cmd UP1 provision 0 config rem UP1 /provision config add UP1 /poll 15 config write config activate
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 reset 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
A manual update can be forced by the following command:
mod cmd UP1 poll
The Services/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). Also, when HTTPS is used and fails (e.g. due to untrusted certificates), this error code is generated. Finally, when using DNS names in the URL, this may indicate a DNS failure
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 .
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 card or SSD installed can serve as web server platform to read update scripts, firmware files, configuration files or to save configurations.
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.