Reference10:Concept Update Server: Difference between revisions

From innovaphone wiki
Jump to navigation Jump to search
Line 281: Line 281:


<code>mod cmd UP1 poll</code>
<code>mod cmd UP1 poll</code>
==== Error Messages ===
The [[Reference10:Services/Update|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. <code>http:172.31.2.3/drive/cf0/update/update-all.txt</code>).  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 <code>failed(401)</code>) are taken from the last HTTP error code received by the update client.  More about HTTP error codes can be found in the [http://de.wikipedia.org/wiki/HTTP-Statuscode German] and [http://en.wikipedia.org/wiki/List_of_HTTP_status_codes English] wikipedia .


=== Example ===
=== Example ===

Revision as of 13:21, 28 May 2019

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.

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

Configuration

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://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 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).

Running maintenance

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


Maintenance commands

Additional commands implemented specially for the update server are available.

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, 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

Attention:
If one of the commands following the check command starts a reset sequence (reset, 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.

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

Setvar command

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

Replace command

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.

Eval 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 var to yval (the value of var-y).

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

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. It works in the same way as the prot command for the firmware.

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.

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).
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 09-7030014
#fn first n digits of kernel build number after the dash 70300
#B boot code build number 09-7030012
#H hardware build 102
#h hardware number IP1200-03-0d-f0
#n device name RadioOne
#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
#t device type IP1200
#(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. 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.

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 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 from version 9 on, persistant assignements (such with a p flag) will always trigger a reset needed condition - even if the value did not change.

Provision command

During staging, the normal poll interval (which is long) may not be sufficiant, 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 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

Debugging

A manual update can be forced by the following command:

mod cmd UP1 poll

= Error Messages

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 .

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.