Course12:Advanced - Update Manager
Explains how to setup the Update Manager on an innovaphone PBX system.
The Update Manager
- update the devices firmware
- save the devices configuration
- restore device configuration
- modify device configuration
Overview
UP1 will periodically retrieve commands from a command file as specified in the Services/Update settings. The URL to retrieve the command file from has an 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 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 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 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 scfg command for how to enforce a periodical re-execution of the command.
You can see the current update serials on the
For historical reasons, the commands also require a 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
For obvious reasons, multiple devices should not save their configuration to the same file. There are some 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 prot, boot and 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 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
Please note that the file names inferred by the boot and 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
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 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
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
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
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
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
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 Web Server chapter of the LAP's concept article. The 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
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