Howto:PHP based Update Server

From innovaphone-wiki

Jump to: navigation, search

NB: this description is outdated as it applies only to builds prior to build 2000. See Howto:PHP_based_Update_Server_V2 for the current version.

Contents

Applies To

This information applies to

  • all innovaphone devices
  • web server running PHP 5 (e.g. Linux Application Platform)

All Versions.

By default, the Update Server mechanism reads a file that corresponds to the device type (e.g. update-ip222.htm). While this makes sense (update scripts my vary by device type), it is sometimes tedious, as you have to edit a huge amount of files which typically are (at least partly) identical.

Here is a PHP script that can be used as an Update Server that allows you to simplify the handling of update scripts. It also includes a mechanism that makes sure that all devices always have the same firmware installed as a given master device has. Finally, it implements a straight forward configuration backup scheme.

More Information

Requirements

The update server script requires a web server with working PHP 5.3 or higher platform. It has been tested with Apache, IIS and ligHTTPD (on a Linux Application Platform).

The platform running the PHP scripts must have a valid time setting!

To use the backup function, the web server must be able to handle PUT requests using chunked encoding. IIS is known to be not compatible with this requirement. Running the backup code on an IIS requires a workaround on the IIS (see http://stackoverflow.com/questions/27451882/retrieving-chunked-put-data-with-php-on-iis-7-hung) and some changes in the update.php code.

Features

The update server can

  • update all your devices with boot code and firmware that corresponds to the versions running on a reference device of your choice
  • save backups of your devices configuration. Backups are saved only if the configuration changed since the last backup
  • invoke your own update scripts depending on
    • various phases (e.g. you can have staging scripts which are only executed once and normal scripts which are executed in normal operation later on)
    • devices classes (e.g. you can have different scripts for phones and gateways)
    • environments (e.g. you can have scripts for your internal devices and others for devices in home offices)

Installation

To install the tool

  • create a new directory where your web server can run .php scripts
  • copy the files update.php, config.xml and config.dtd in to this directory
  • create a directory named cache in this directory
  • create a directory named backup in this directory
  • make sure your web server can modify the two sub-directories
    • on Linux, either change the directory modes to 0777 or change the ownership of the directory to the web server user-id
    • on Windows, grant modify rights to the web server user (usually something like IUSR_xyz)
  • create a directory named fw in this directory
  • copy firmware and boot code files (such as ipxxx.bin and bootxxx.bin) to sub-directories of the fw directory (so you have e.g. firmware build 12345 for the IP232 in fw/12345/ip232.bin)
  • configure your devices to use an update script (should be done after you have completed the configuration, see below)
    • the Command File URL must be http://url-to-your-new-directory/update.php?type=#t (of course, https will work too)
    • the Interval [min] can be set to any reasonable value. We do not recommend too large values to make sure, update script changes propagate soon through your network
    • you will usually do this using DHCP (see Update URL and Update Poll Interval in Reference12r1:DHCP_client)

On the Linux Application Platform

On the Linux Application Platform, you would

  • open the LAP's file system using a SFTP client such as e.g. WinSCP (if you have not yet changed it, the default credentials will be root/iplinux, see Concept Linux Application Platform). Note that you must use SFTP rather than WebDAV, as WebDAV will not give access to the executable web server files
    • create the new directory called update underneath the /var/www/innovaphone directory. The URL to reach the update script will be http://your-lap/update/update.php
    • copy the update server files (config.xml, update.php etc.) in to this directory
    • create sub-directories backup, cache and fw
  • log in to the LAP's admin UI (if you have not yet changed it, the default credentials will be admin/linux, see Concept Linux Application Platform)
    • go to Administration/WebServer/Change web server properties and public access to the web/webdav
    • add /update/ to Public Web Paths
  • log in the LAP's root shell (using e.g. putty, if you have not yet changed it, the default credentials will be root/iplinux, see Concept Linux Application Platform)
    • cd to /var/www/innovaphone
    • change owner of update and all its sub -directories to www-data (e.g. chown -R www-data update)

Configuration

Basic Parameters

All tweakable parameters are present in config.xml. You should start with just setting the info attribute of the master tag and leave everything else as is.

The following tags are available:

master

Defines the reference device where the firmware and boot code information is taken from.

info 
the URL to the device info data. Set it to an URL like http://your-reference-device/CMD0/box_info.xml. Please note that this device must not have the Password protect all HTTP pages set in Services/HTTP/Server.
expire 
the firmware info cache lifetime. The firmware information is cached in a file (to make sure this information is present even if the reference device is offline)
cache 
the cache file name. The web server must be able to write this file (see Installation above)
<master 
info="http://172.16.0.10/CMD0/box_info.xml"
expire="3600"
cache="cache/master-info.xml"/>
fwstorage

Defines from where the device will retrieve the firmware files for updates.

url 
defines the URL to retrieve the files from. The requested firmware/boot-code build number will be appended followed by a trailing slash (/). The file system the URL points to must therefore contain sub-directories for each firmware build which contain the corresponding firmware builds (e.g, fw/12345/ip232.bin). If url is not an URL (as is the case for the default value fw), it is treated as a sub-directory underneath the script directory
<fwstorage url="fw"/>
backup

Defines where backup files are kept.

dir 
the directory underneath the script directory where backups are stored
nbackups 
the number of different backup files kept
scfg 
the target URL for the scfg command. If this is not an url, it is interpreted relative to the script directory URL. You can add more options for the scfg command, like in scfg="update.php?mode=backup&hwid=#h ser hourly /force 1" (this example will make sure backups are attempted only once per hour, so as to reduce load on the server).
<backup 
dir="backup"
nbackups="10"
scfg="update.php?mode=backup&amp;hwid=#h "
/>
times

Defines the arguments of the times command. If neither allow nor initial is set, no times command is used (that is, the update scripts will be processed at all times).

allow 
the hours to be used in the times command
initial 
the minutes to be used in the times command
check 
if set to true, update scripts will be executed once only (unless their contents change). In this case, the devices will be executed again when you have edited/changed them
polling 
when you are using multiple phases (e.g. staging and update), this defines the number of seconds to wait before the device reads the scripts for the next phase (see provision command)
interval 
polling interval in minutes for normal operation (that is, when all staging s done)
grace 
defines the number of seconds that must expire before update script changes take effect. If grace is set to 900, then update scripts will not be executed until 15 minutes (900/60) have expired since the last edit of a script that normally would be executed for the calling device
<times 
allow="22,23,0,1,2,3,4"
initial="1"
check="true"
polling="5"
interval="15"
grace="900"/>
phases

Defines the scripting phases. In many installations, there are initializations which should be performed once only. This is known as the staging phase. Once this is done, the devices continue with the execution of the normal update scripts (this phase is known as update by default). In the (unlikely) event that you want more or less phases, you can add/remove phase tags.

phase
id 
the name for the phase
<phases>
<!-- sequence is important! -->
<phase id="staging"/>
<phase id="update"/>
</phases>
environments

Defines the distinguished environments. Devices can have zero or more environments associated. The environments a device is considered to be in must be passed as ?env=name1,name2,.. URL query arg in the update url. Update scripts for all environments listed will be applied. The default config file defines the environments intern and homeoffice but you can define your own if you like.

environment

Each environment may have a number of sub-tags of type implies. It contains the id of another environment. If a device is in an environment with an implies sub-tag, it is assumed that it is in the implied environment also.

id 
the name for the environment
<environments>
<environment id='hq'>
<implies>intranet</implies>
</environment>
<environment id='intranet'/>
<environment id='homeoffice'/>
</environments>
classes

Defines the available device classes. Devices of different classes (e.g. phones and gateways) can have different update scripts. The device class is derived from the #t (device type) query arg of the update script URL (which is why you must configure it in the update URL, see above). By default, the classes phone and gw are recognized. A given device can be in multiple classes and will execute all update scripts available for these classes.

<classes>
<class id="gw">
<model>ip0010</model>
...
</class>
<class id="phone">
<model>ip110</model>
...
</class>
</classes>
class

Each class has a number of sub-tags of type model. It contains the value replaced for the #t query arg.

id 
the name of the class
stdargs

Better don't touch :-)

Testing

To test your installation, you can simply use your browser simulating your device (it is convenient to use your browsers view source function to inspect the result).

Cache

Open the update URL with the #t argument replaced by the simulated device type (e.g. http://172.16.10.65/update/update.php?type=ip222). You will see an update script. The first line will look like

# failed to use cached data (cache not current), retrieving info online
# phase: ...

This is normal, as there is no cache yet. Now simply open the URL again (by hitting F5 e.g.). You will now see

# firmware build info cache is current

If so, your firmware info retrieval and your cache works.

if not, there is something wrong with your master/info URL or your web server has no write access to the cache sub-directory.

Update Scripts

You should now see a line like

# phase: staging, nextphase: update, environment: intern, type: ip222, classes: phone

in the update script. This shows that the scripts for the first phase staging, the default (i.e. first) environment intern and for devices of class phone will be delivered.

The next lines will list the potential update scripts for this situation:

# possible files (from C:\sources\wiki-src\sample\php-update-server\sample\sources):
# staging-phone-intern.txt (does not exist)
# staging-phone-all.txt (does not exist)
# staging-all-intern.txt (does not exist)
# staging-all-all.txt (does not exist)
# all-phone-intern.txt (does not exist)
# all-phone-all.txt (does not exist)
# all-all-intern.txt (does not exist)
# all-all-all.txt (does not exist)

Of course, as you have no scripts yet, all options are tagged as (does not exist). If one or more of such scripts exist, they will be executed in the order listed.

Backup

The next lines show you where the device backup will be sent to:

# backup
mod cmd UP0 scfg http://172.16.10.65/update.php?mode=backup&hwid=#h ser hourly /force 1

You can see that the backups are sent every hour (/force 1) if this has been configured in the backup tag (see above).

Firmware

The next block shows the required update of the firmware or boot code:

# current firmware (unknown) does not match required firmware (120663)
mod cmd UP0 prot http://172.16.10.65/fw/120663/ ser 120663
# current boot code (unknown) does not match required boot code (120502)
mod cmd UP0 boot http://172.16.10.65/fw/120502/ ser 120502
# make sure remaining update scripts are executed with up-to-date firmware
iresetn

In this example, the reference device is running firmware build 120663 and boot code build 120502. The update server does not know the devices current firmware, so it creates an update command for both. You can now add a &PROT=120663 query arg to the URL. This tells the update server the firmware your device is running (a real life device will include this argument automatically, so there is no need to configure it anywhere). When you retrieve the script again, no update command for the firmware will be included:

# current boot code (unknown) does not match required boot code (120502)
mod cmd UP0 boot http://172.16.10.65/fw/120502/ ser 120502
# make sure remaining update scripts are executed with up-to-date firmware
iresetn

Next Phase Switching

As you have 2 phases defined in your config file, the script will instruct the device to switch to the next phase (update):

# warping from 'staging' to 'update' (url=http://172.16.10.65/update.php?type=#t&phase=update)
config add UP1 /url http%3A%2F%2F172.16.10.65%2Fupdate.php%3Ftype%3D%2523t%26phase%3Dupdate
config add UP1 /no-dhcp
config write
config activate

# turn on fast polling
mod cmd UP1 provision 5

This is done by re-writing the update URL in the client. You can simulate this by adding the &phase=update query argument to your browser URL. You will see then:

# 'update' is last phase

Config File Re-Execution

In the last (that is, standard) phase, the config files will be executed only when changed. This is done using a check command :

# skip remainder if there were no changes in config files
mod cmd UP1 check ser d41d8cd98f00b204e9800998ecf8427e

The serial d41d8cd98f00b204e9800998ecf8427e is a hash code computed from the content of all script files that are valid for the calling device. We can see how this works when we create an update script that is valid for the device. You create a file called all-all-all.txt in the update server directory and place something (e.g. a comment in it):

You will now see that the script retrieved changes:

# skip remainder if there were no changes in config files
mod cmd UP1 check ser 1e906fd3737281ebd4edbdf60a196fb3

# 1 config files follow:
# { begin script 'all-all-all.txt' 
# my first update script

# end script 'all-all-all.txt' }

The new serial 1e906fd3737281ebd4edbdf60a196fb3 differs from the previous one. As a result, the devices will execute their update scripts whenever they change.

Debugging

To debug update script execution in your real devices, you can

  • open the devices debug.xml page (e.g. http://x.x.x.x/debug.xml)
  • check the Update/Polling, Update/Execution, HTTP/Client and HTTP/verbose check marks
  • force the update client in the device to run using the mod cmd UP1 poll command (e.g. http://x.x.x.x/!mod cmd UP1 poll)
  • look at the traces (best with wireshark)

You can easily see the current status of your update server and scripts by calling the URL http://your-update-server/update/update.php?show

Your own Update Scripts

As you have seen, the update server will do some meaningful things (updating the device firmware and creating backups) even with no user supplied update scripts at all.

Feel free now to add your own update scripts. All update script names must have the form phase-class-environment.txt (e.g. update-phone-intern.txt). If the word all is used for any of the components, the file is executed for all phases, classes or environments respectively.

When you retrieve the update script URL manually (e.g. using your browser), it will list all the potential update script files:

# possible files (from C:\sources\wiki-src\sample\php-update-server\sample\sources):
# staging-phone-intern.txt (does not exist)
# staging-phone-all.txt (does not exist)
# staging-all-intern.txt (does not exist)
# staging-all-all.txt (does not exist)
# all-phone-intern.txt (does not exist)
# all-phone-all.txt (does not exist)
# all-all-intern.txt (does not exist)
# all-all-all.txt (does not exist)

Note that this list depends on

  • the device's class (inferred from the ?type=#t query arg in the update URL)
  • the device's environment (as specified by the optional &env=environment-name query arg in the update URL)

Download

Related Articles

Personal tools