Howto:PHP based Update Server V2

From innovaphone wiki
Revision as of 19:04, 21 November 2016 by Ckl (talk | contribs) (→‎master)
Jump to navigation Jump to search

Applies To

Tools clipart.png FIXME: "work in progress"

This information applies to

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

All Versions.

By default, the Update Manager mechanism reads a file that corresponds to the device type (e.g. update-ip222.htm). While this makes sense (update scripts may 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.

This article describes version 2 of this update server. The previous version is described in Howto:PHP_based_Update_Server. The enhancements are

  • Status user interface showing all known devices
  • Ability to roll out custom device certificates
  • Ability to provide configuration files to MTLS-authenticated devices only (e.g. in order to keep certain configuration settings secure)
  • Hide configuration files from public read access

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 and ligHTTPD (on a Linux Application Platform). On IIS, neither the certificate roll-out nor the MTLS authentication or configuration backup works with IIS.

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

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)
    • the device serial number
  • roll out customer specific device certificates
  • roll out update scripts to devices only that have identified themselves with a valid device certifictae (MTLS)

Installation

On the Linux Application Platform

Here is how you would install it on the LAP. Some of the steps may not be necessary if you don't want to use all features.

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 a new directory underneath /var/www/innovaphone/mtls, e.g. /var/www/innovaphone/mtls/update
  • copy the following files in to this directory
    • update.php
    • config.xmlconfig.dtd
    • user-config.xml
  • create s sub-directory called web, copy the following files in to this directory
    • cer.png
    • hide.jpg
    • touch.gif
    • trash.gif
    • update.png
    • style.css
  • create a sub-directory called admin, copy the following files in to this directory
    • admin.php
  • change owner and group of all files and directories to www-data
  • 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) and open the its Administration/Web Server/Change web server properties and public access to the web/webdav configuration UI. Add the following paths to Public Web Paths (assuming your base directory is called update):
    • /mtls/nupdate
    • /mtls/web
make sure that no other sub-directories of update are listed
make sure you have no trailing '/' in any of these paths
this will make sure the update server's admin user interface is not accessible to the public

On an Apache Server running on the Windows Operating System

Tools clipart.png FIXME: "to be done"

Configuration

Preparation

If you intend to deliver your update scripts with MTLS (that is, with HTPS und mutual certificate check), you will need to have the full name of your certificate Authority (CA) as it is noted as Common Name (CN) in your CA's certificate. Also, you will need a PEM version of your CA's public key (a PEM version of a certificate is a text file that begins with a line like -----BEGIN CERTIFICATE-----).

Basic Parameters

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


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)

Complete Parameter Reference

Note: attributes are marked with an at (@) prefix. So master/@info refers to the info attribute in the master tag.

The following tags and attributes are available:

master

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

/master/@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.
/master/@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 off-line). The cache will not be refreshed before the expire time (in seconds) is expired
/master/@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.

xxtagxx/@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.

xxtagxx/@dir
the directory underneath the script directory where backups are stored
xxtagxx/@nbackups
the number of different backup files kept
xxtagxx/@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&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).

xxtagxx/@allow
the hours to be used in the times command
xxtagxx/@initial
the minutes to be used in the times command
xxtagxx/@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
xxtagxx/@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)
xxtagxx/@interval
polling interval in minutes for normal operation (that is, when all staging s done)
xxtagxx/@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
xxtagxx/@id
the name for the phase

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

xxtagxx/@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.

xxtagxx/@id
the name of the class

stdargs

Better don't touch :-)


Download

  • not yet available to the public

Related Articles

Retrieved from "https://wiki.innovaphone.com/index.php?title=Howto:PHP_based_Update_Server_V2&oldid=44887"