Course12:Advanced - Update Manager

From innovaphone wiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
There are also other versions of this article available: Course11 | Course10 | Course12 (this version)

Explains how to setup the Update Manager on an innovaphone PBX system.

The Update Manager

The update manager (a.k.a update server) is a scripting engine available in each innovaphone device. It periodically retrieves a command script from a web server (usually an innovaphone device with SSD or CF card) and executes the commands found within. The scripting language allows to
  • update the devices firmware
  • save the devices configuration
  • restore device configuration
  • modify device configuration

Overview

The screenshot.png update manager (which used to be called update server before) is a fish-help.png component that is present in all of the innovaphone devices. It consists of 2 modules, a.k.a. UP0 and UP1. UP1 is a scripting engine that is able to process update scripts which include commands towards UP0.

UP1 will periodically retrieve commands from a command file as specified in the fish-help.png Services/Update settings. The URL to retrieve the command file from has an fish-help.png auto-completion mode which appends a device-type specific file name to the URL if it ends with a /. This allows for different per-device-type command files without the need to configure different update-URLs on the devices (which comes handy if for example the URL is deployed via fish-help.png DHCP), as long as all command files are in the same directory.

Limiting Script Execution to specific Time Frames


In normal operation, device maintenance such as backup of firmware update shall be done in non-business hours only. The command file however, is retrieved periodically all around the clock. Special execution time frames can be enforced using the fish-help.png times command. Please note that it is generally a good idea to use it together with the /initial option!

General Syntax of the UP0 Commands


The UP0 commands (those invoked by UP1 doing the actual work) all follow the same paradigm. Each command (scfg, prot, boot, bmc, cfg) has a fish-help.png tag associated with it on each device, a.k.a. the Current Update Serial. It needs to be specified with the command and upon command execution the tag found on the device is compared against the tag present in the command. When both are identical, the command is silently skipped. If not, the command is executed and if successful, the devices tag is set to the one specified in the command (tags are stored in non-volatile memory, a.k.a flash). This ensures that commands like prot (which updates the firmware) are only executed once per device. However, see the /force option of the fish-help.png scfg command for how to enforce a periodical re-execution of the command.

You can see the current update serials on the fish-help.png Services/Update page.




For historical reasons, the commands also require a fish-help.png final command. This is executed if and only if the command itself was executed successfully. For example, for the prot command, a final command ireset would make sense as it would wait for the device to become idle after the firmware update and then do a reset. However, in most cases it is much clearer to use ser (a no-op) as the final command and have an iresetn (which will do an idle reset only if needed) follow as last statement in the script.

Configuration Backup

To save the configuration, you may use the fish-help.png scfg command. It will save the entire configuration to the specified URL. Please note that UP0 needs to have write access to the target URL! This can be done by defining appropriate fish-help.png credentials. However, in most cases it is easier to save the configuration to an URL where there is anonymous write access. If the target web server is an innovaphone device, you can tick the write check mark on the Public compact flash access property list of the target devices fish-help.png Services/HTTP/Server tab.

For obvious reasons, multiple devices should not save their configuration to the same file. There are some fish-help.png special character sequences defined to help constructing individual file names for individual devices.

For the scfg command, the serial is optional (in fact, up to version 7, it was not even possible to specify it). However, omitting it does not make too much sense and creates unnecessary load on both the client running UP0 and the target web server! You should thus always specify one. On the other hand, specifying a serial will inhibit all but the first configuration backup until you change the serial specified in the command file. To handle this situation, use the /force option which takes a number of hours as an argument. When the specified time span has elapsed since the last execution of the scfg command, it will be executed again even though the serial has not changed.

Popular values for the time span include:

Hours
Period
24
daily
168
weekly
720
monthly

Deploying Firmware Updates

You can deploy firmware, boot code and bmc code updates using the fish-help.png prot, fish-help.png boot and fish-help.png bmc commands, respectively (the bmc command is largely obsolete now, as it is only used for the IP1200, which is a discontinued product).

Please note that the rules defined for the update serial and described in the previous chapters do apply to firmware too. That is, the commands are executed whenever the update serial specified in the command does not match with the update serial stored in the device in question. Using the firmware's construction number (e.g. 09-12345678) as update serial is common and comes in handy. However, the UP0 process will still not verify the device's current firmware version against the update serial. So if the serials do not match, the firmware is downloaded even if it in fact is already in place. Likewise, to make sure a new firmware is installed, you must change both the source URL for the firmware and the update serial!

When updating the firmware, you can use one of the reset commands as fish-help.png final command (usually ireset will do best) or you can use ser (which is a no-op) and have an iresetn command at the end of the script.

When updating the boot code, you need to power cycle the device as a normal reset will not activate the new boot code. For this, you must use reboot or ireboot as final command. The commands rebootn and irebootn have been available since v7hotfix6, so you can use ser as the final command and finish the script with an irebootn, avoiding multiple reboots in a single script.

Please note that in a firmware download on download.png download.innovaphone.com, e.g. for an IP240, the file ip240.bin will include the firmware, whereas the file boot240.bin includes both the mini-firmware and the real boot code (in version 7 downloads though old and new boot code versions may required to upgrade from version 6, so both boot codes are provided as e.g. boot7ip200a.bin and prev7boot200a.bin). mini-firmware and boot code are loaded together by the boot UP0 command. However, before writing it to flash memory, the boot code itself will be compared against the boot code that is currently installed. This way, the risk of damaging a device with a failed boot code update is minimized.

Please note that the file names inferred by the fish-help.png boot and fish-help.png prot commands by adding a trailing slash ('/') to the URL are boot811.bin and ip811.bin, respectively (for an IP811). So you need to make sure the files are named properly on your web server or CF/SSD drive.

Version 10 and later

Please note: since Version 10 - due to restricted flash and DRAM on some older phone models - we generate several new firmware versions providing a subset of functionality. This applies to IP110, IP150, IP200A, IP230, IP240.

Example IP110:

  • IP110.bin includes H.323 and PPP as protocol, but not SIP
  • IP110-sip.bin includes SIP and PPP as protocol, but not H.323
  • IP110-no-ppp.bin includes H.323 and SIP as protocol, but not PPP

ip110.bin (sip-excluded) ==> 10.00 beta6 IP110[10.0734], Bootcode[100734], Hardware[110]

ip110-sip.bin (h323 excluded) ==> 10.00 beta6 IP110[10.0734]ps,Bootcode[100734], Hardware[110] ps = ppp&SIP

ip110-no-ppp.bin (ppp excluded) ==> 10.00 beta6 IP110[10.0734]hs,Bootcode[100734], Hardware[110] hs = H323&SIP


We will eventually release update hardware with enhanced DRAM/Flash. There will be new firmware then which includes all functionality again (e.g. ip240a.bin).

The "old" models will continue to report themselves as e.g. "ip110", so the default firmware file used for the prot command will be ip110.bin. Such phones will then update with a firmware that runs no SIP stack.

Deploying Configurations

You can deploy configuration files using the fish-help.png cfg command. This will load and apply the specified configuration file.

Configuration files can be partial. Configuration settings that are not present in the file are left untouched. This may be useful to deploy generic partial settings to a number of devices.

Some configuration settings can be activated without a reset, some others cannot. To avoid unnecessary resets, you should always use ser as the final command and then end the script with a config activate and an iresetn command.

Deploying Configuration Settings from within the Script


In fact the command file retrieved by UP1 can execute just any command that is valid in the devices command processor (that is, commands that could be used on a telnet prompt (deprecated) or using the http://x.x.x.x/!cmd URL syntax). This can be used to specify configuration changes directly in the command file.

For example:

config change DHCP1 /mode client
config write
config activate
iresetn

would set ETH1 into DHCP client mode. However, specifying this would do the configuration change and flash update each time the script is retrieved (which is by default every 10 minutes). To avoid this, use the fish-help.png check command. It will check the serial against the check serial on the device. If they match, command file execution is terminated. Otherwise, the remainder of the script is executed, the serial saved and the final command executed.

The above example thus could look like

mod cmd UP1 check iresetn set-eth1-to-dhcp
config change DHCP1 /mode client

config write
config activate

Note that none of the commands that follow the check command should initiate a reset, and if so, the serial will not be written. This will result in an endless re-execution of the commands.

In these examples, config change replaces the respective line within the in-core copy of the config file, config write saves the in-core copy to the flash memory and config activate activates the changes done to the config in the running firmware. Activation may require a restart of the device (if changes can't be done on the fly). This is indicated by a reset needed response (instead of a simple ok).

Modifying Configuration Lines


Unfortunately, when using config change, you need to specify the complete new set of configuration parameters for the configuration line.

Assume for example you have the configuration line config change NTP0 /addr 172.31.0.1 /interval 60 /offset CET-1CEST-2,M3.5.0/2,M10.5.0/3 and want to update the NTP server's IP address. Issuing config change NTP0 /addr 172.31.0.2 will replace the entire configuration line, thereby losing the settings for interval and time zone. You thus always need to know and specify all the parameters.

To simplify this, you can use the config add and config rem directives. config add NTP0 /addr 172.31.0.2 will locate the NTP0 configuration line and replace (or add if it does not yet exist) the current /addr option along with all possible option values. Applied to the above example line, it will yield config change NTP0 /addr 172.31.0.2 /interval 60 /offset CET-1CEST-2,M3.5.0/2,M10.5.0/3. Likewise, the config rem directive will remove the option and all possible option values, so that config rem NTP0 /addr would yield config change NTP0 /interval 60 /offset CET-1CEST-2,M3.5.0/2,M10.5.0/3.


Debugging

Debugging the update server can be quite tedious. To see what is going on, you should first enable tracing on both UP0 and UP1:

config add UP0 /trace
config add UP1 /trace
config activate

Then, instead of waiting for the polling period to elapse, you can force a re-execution of the script using

mod cmd UP1 poll

Backups and Memory Usage


When using an SSD/CF drive as backup device for the update manager (that is, storing the targets of an scfg command), this can cause substantial memory usage on the device hosting the web server. Just a quick calculation: the standard TCP windows size is 64kB. If the whole installation reboots at the same time (e.g. after a power loss), all device will read the update command file time more or less in parallel and thus execute the scfg command in parallel. Each client will push 64kB data to the web server. As the CF card is slow, the buffer will be used for a long time, resulting in n * 64kB memory usage while saving the configuration file. SSD is faster, so the situation is a little more relaxed.

Assume you have a site with 50 devices and are using an IP305 as CF host. The 305 may typically have around 4.5MB free RAM (user http://x.x.x.x/!mem to find out), leaving less than 1.5MB for all other applications. For example, if a PBX is running on it, the box will be likely to run out of memory! 100 devices will pretty sure crash the box right away.

The calculation for an IP810 looks much nicer: it will typically have around 25MB of free memory after boot, so even 100 clients sending 64kB would leave plenty of memory.

Staging

Staging is a process where devices installed in a site are set into a site or customer specific state when installed initially. It is assumed that this step shall be applied to newly installed devices immediately and only once. Typically, staging loads a specific firmware and installs a site (and usually device-type) specific master configuration.

This can be done using the /initial option of the UP1 times command.

Staging differs from deploying the configuration options by DHCP by only setting a default configuration which can be changed manually later on. DHCP options however cannot be changed (other than site-globally) as they always win against manual configuration.

Using a different Command File for Staging


Sometimes a separate command file used for staging only is required. This way, you are completely free to set up a command file just for staging.

This can be done by specifying a staging update URL via DHCP and then setting the /no-dhcp option to UP1 along with a new update URL as last step of the staging process. /no-dhcp will instruct UP1 to disregard the settings received by DHCP and use the configuration found in the device configuration instead (remember that normally, options supplied via DHCP always win against settings defined in the device's local configuration). Then this could look like

config change UP1 /url http://172.31.2.1/DRIVE/CF0/update/ /poll 15 /no-dhcp

To speed up the staging process an UPDATE/VIRGIN variable was introduced with V8. The VIRGIN variable is usually set in the staging script and will trigger the fast execution of the second command file.

Example:

You have a staging setup, the first script is deployed via DHCP and configures global settings on all devices. After its execution a second command file is used as updatescript. The second file does things that are done on a regular basis, e.g. save config files. Usually it is executed during the night to prevent that maintenance procedure interferes with the daily work.

Now imagine you have one device that is malfunctioning and must be replaced. You get a new device, factory reset it and plug it to your network. It will get the first command file URL via DHCP and execute the initial configuration. Afterwards it should wait for the defined Update Interval and poll for the new command file URL. However, it will not be able to execute it since the times command allows execution only at night. Moreover a configured/initial parameter will not trigger either since your device doesn't have factory settings any more. As a result you will have to wait until night for the second script to be executed.

To speed things up you can use the UPDATE/VIRGIN variable. You will configure the device with it in your first command file. Your first improvement is that the device will not wait for the Update Interval to pass but poll for the second after one minute. The second improvement is that the device will execute the second script immediately, ignoring any configured /allow command (the same as if the device would have factory settings).




Backing up the drive

The SSD or CF card's content is exposed to the network as standard WebDAV drive (such as \\x.x.x.x\DRIVE\CF0). This allows other computers to access the files on it over the network, e.g. for backup purposes.

There are 2 points to consider.

Access Rights


Files on the drive are protected. To get access, you need to authenticate towards the device using its admin account and password. From a windows PC, this can be done via Connect Network Drive. From a Linux box, the drive can be mounted remotely (e.g. as davfs or davfs2 volume). In any case, you must specify the appropriate network credentials. You can then use standard backup tools such as tar, cpio, ntbackup etc.

Keep in mind though that on a windows box, programs running in a service context usually do not have access to mounted drives. You may thus need to configure path and network credentials directly to the backup program in use.

Archive Bits


The WebDAV file system does not support the archive file attribute. This is usually used by backup programs to implement incremental or differential backups. As the attribute doesn't work, such type of backups will not work properly either!

Performance

Using the SSD/CF drive for firmware and configuration updates as well as configuration backup can impose substantial load on the device with the drive. When designing a solution, you should carefully look at options where to run the central file storage. Using the central device running the PBX is not always the best option to host the drive. Instead, less intensively used devices such as e.g. trunk line gateway may be the better choice.

Same counts for the aggregation of events and alarms. However, there is no need to aggregate these on the same device that hosts the drive for file storage. In many cases it is most convenient, to use the device running the PBX for this.

As a rule of thumb, you should not allow more clients to backup their configuration to a devices SSD/CF drive than the device would allow to run concurrent users on a PBX.

Also consider using different time slots for each device type, for example all IP222 save their config between 2-3 a.m. and all IP240 between 3-4 a.m.


Using a Linux Application Platform as Web Server

Often, you will simply use the web server built-in to the innovaphone device and store all files on the SSD/CF drive. This is of course also possible if you run a fish-help.png Linux Application Platform (LAP) on the box.

However, in this case, the built-in box web server has no access to the drive, which is then managed by the LAP.

When the LAP is installed, go to Linux/General. You will a link called Webdav folder. This is the space where stuff like update scripts or announcements etc can be stored stored - in addition to the LAP files. This is described in some detail in the fish-help.png Web Server chapter of the LAP's concept article. The fish-help.png NetDrive chapter explains how to access this space with NetDrive.

To control access rights to the WebDav space, go from the LAP's administration UI (you can go there via Linux/General/Linux application platform or application update/upload) to Administration/Web Server/Change web server properties and public access to the web/webdav.

Using the Flash Disk instead of the SSD

The newer gateway platforms (such as IPxx11) feature an additional persistent drive known as Flash Disk. This drive is using flash memory which is built-in to the device. It can be accessed as \\device\DRIVE/FLASH/(or http://device/DRIVE/FLASH/) instead of \\device\DRIVE/CF0/.

This drive is always present (although you have to format and mount it just like the other drive types) and you do not need to install an SSD or CF-card to use it. Also, when you run the LinuxAP on the same box, Linux will us the SSD (or CF) and leave the Flash Disk untouched. So it can run in parallel.

There are two issues to keep in mind though:
  • the size of the Flash Disk is fixed and differs considerably among device types (e.g. IP411: 128 MB, IP811: 1GB)
  • as the Flash Disk is based on internal, built-in flash memory, it's content is removed whenever the box is reset to factory defaults