innovaphone wiki - User contributions [en]

Howto13r1:LDAP IP Phones Directory Services via Reverse Proxy

2020-02-13T20:23:00Z

Peter.seyringer: /* Reverse Proxy manual modifications */

== Summary ==

This article is about How to enable LDAP search at innovaphone IP Phones via Reverse Proxy.

== Status per default after Install ==
Currently by default IP phones registered via Reverse Proxy are NOT able to search in the PBX users and in the external LDAP resource (for example the Contacts database)
To enable the LDAP search on the Phones we have to do some manual modification.
== Steps to do ==

# Create an LDAP user in the PBX under services, LDAP
# Retrieve the Contacts App username and password.
# Modify the IP Phone or the Template used for the IP Phones that register via the Reverse Proxy.
# Modify the Reverse Proxy entries manual!

=== Create a LDAP user ===
Steps to do: Under Services, LDAP, Server

* 1. Create a ldapuser account under Services, LDAP, Server (for example pbx.system.com/ldap-guest)
* 2. Define a secret password and store it in a save place. You need it later on. And press OK to save. You can also use the same password as used in step B. because this is the same as used in the default ldap-guest

[[Image:LDAPuser.png|LDAP user]]

=== Find your Contacts ldap password ===

Steps to do: In PBX manager, Plugin AP contacts.

* 1. Click on AP contacts plugin and click in the right pane on configuration.
* 2. Check the Display Password(LDAP).
* 3. Copy the Password and store it for later use. This password is the same as used for the default ldap-guest

[[Image:contacts ldap password.png|Plugin AP Contacts]]

=== Create Phone Template or change phone settings ===

Steps to do: Under Phone, Directories or Template, config, Phone, Directories.

* 1. Check Enable and Use TLS and change the PBX section server to pbx.system.com (of course use your own pbx, domain and systemnames, pbx.yoursystemname.com 😉)
* 2. Port 636 for LDAPS
* 3. Username change it to pbx.system.com/ldapuser (the user created in section a.)
* 4. Enter the password off the ldapuser (created in the section a.)
* 5. External LDAP Server, Check enable and Use TLS and enter the Servers dnsname apps.system.com
* 6. Port 636 for LDAPS
* 7. LDAP username which is the username contacts from the App contacts
* 8. The password, which is the password copied from the Plugin AP contacts

[[Image:LDAP phone or template OK.png|LDAP phone or template config]]

If you created a new template, make sure you assign this template to the appropriate users!

=== Reverse Proxy manual modifications ===

In the Reverse Proxy we have to do some manual changes.
(After these changes make a backup and DO NOT use the PBX manager plugin for the Reverse Proxy anymore. Otherwise your manual changes will be broken when saving via the RP plugin)

This has to be verified because it seems to be OK in V13r1sr8

In this example the Reverse Proxy runs on the PBX itself and listens to the standard default ports +10
Make sure that on your router/firewall the default ports will be redirected to these defaults ports +10

Steps to do in the Reverse Proxy:

* 1. Change the apps.system.com line and add LDAPS port 636 and redirect it to the IP address of the App Platform. This redirection is used for the external LDAP users search in the App Platform, Contacts database.
* 2. Change the line with pbx.system.com and add LDAPS port 636 and redirect it to the IP address of the PBX. This redirection is used for the search internal LDAP database, PBX users.
* 3. Change the line with system.com add LDAPS port 636 and redirect it to the IP address of the App Platform (original: "PBX" but this is not correct). This redirection is used for the authentication and bind request to the Contacts App.

[[Image:ReverseProxy System OK.png|ReverseProxy config|1280px]]

When opening the Reverse Proxy via the PBXmanger Plugin it will be shown as in the following picture.

[[Image:ReverseProxy Plugin OK.png|ReverseProxy Plugin|1280px]]

== Directory search on the IP phone ==

A directory search on the IP Phone should now result in a search within the PBX internal users and in the Contacts database with External Contacts.

In example 1 a search is done to kpe which shows the results from the PBX (upper result) and the results from the Contacts (other lines)

In example 2 the search is done to almost the complete name to show only the line from the external contacts.

The examples shows you also how you can make a LCD dump of the Phone, this is also possible remotely via the Devices App, Admin UI of the Phone.

example 1: [[Image:KPEresult.png|Directory Result KPE]] example2: [[Image:KCresult.png|Directory Result KC]]

== Debugging ==

For Debugging if you get no search results, use Wireshark and trace for example on the IP Phone.

Open the Phones Admin UI, Maintenance, Diagnostic, Tracing and tick the boxes All IPv4 TCP/UDP Traffic, All IPv4 TLS Traffic, Enable RPCAP.

Open the Webpage of the IP Phone https://x.x.x.x/debug.xml and tick the checkbox, Directories.

Start the wireshark trace and capture a Directory request from your IP Phone.

Filter the data with the filter: tcp.port==636 Find a packet containing the destination port 636 and right-click, choose decode-as and add the source and destination port to the ldap protocol.

Now you should be also able to filter also directly on the ldap protocol.

An example of a succesfull LDAP request is shown in the picture below.

example: [[Image:LDAPrequest.png|Directory request|1280px]]

== Related Articles ==

* [[Reference13r1:Concept_Number_Resolution_and_LDAP|Concept Number Resolution and LDAP]]

[[Category:Howto]]

Howto:PHP based Update Server

2016-08-28T18:26:43Z

Peter.seyringer: /* Cache */

==Applies To==
This information applies to

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

All Versions.

By default, the [[Reference10:Concept_Update_Server | Update Server]] mechanism reads a file that corresponds to the device type (e.g. <code>update-ip222.htm</code>). 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 [[Reference10:Concept Linux Application Platform | 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 <code>update.php</code> 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 <code>update.php</code>, <code>config.xml</code> and <code>config.dtd</code> in to this directory
* create a directory named <code>cache</code> in this directory
* create a directory named <code>backup</code> in this directory
* make sure your web server can modify the two sub-directories
** on Linux, either change the directory modes to <code>0777</code> 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 <code>fw</code> in this directory
* copy firmware and boot code files (such as ''ipxxx.bin'' and ''bootxxx.bin'') to sub-directories of the <code>fw</code> directory (so you have e.g. firmware build 12345 for the IP232 in <code>fw/12345/ip232.bin</code>)
* 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 <code>http://</code>''url-to-your-new-directory''<code>/update.php?type=#t</code> (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 <code>admin/linux</code>, see [[Reference10:Concept_Linux_Application_Platform#Default_Credentials | 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 <code>update</code> underneath the <code>/var/www/innovaphone</code> directory. The URL to reach the update script will be <code>http://</code>''your-lap''<code>/update/update.php</code>
** copy the update server files (<code>config.xml</code>, <code>update.php</code> etc.) in to this directory
** create sub-directories <code>backup</code>, <code>cache</code> and <code>fw</code>
* log in to the LAP's admin UI (if you have not yet changed it, the default credentials will be <code>admin/linux</code>, see [[Reference10:Concept_Linux_Application_Platform#Default_Credentials | Concept Linux Application Platform]])
** go to ''Administration/WebServer/Change web server properties and public access to the web/webdav''
** add <code>/update/</code> 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 <code>root/iplinux</code>, see [[Reference10:Concept_Linux_Application_Platform#Default_Credentials | Concept Linux Application Platform]])
** <code>cd</code> to <code>/var/www/innovaphone</code>
** change owner of <code>update</code> and all its sub -directories to <code>www-data</code> (e.g. <code>chown -R www-data update</code>)

===Configuration===
==== Basic Parameters ====
All tweakable parameters are present in <code>config.xml</code>. 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 <code>http://</code>''your-reference-device''<code>/CMD0/box_info.xml</code>. 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 | ''Installation'' ]] above)

<code xml>
<master
info="http://172.16.0.10/CMD0/box_info.xml"
expire="3600"
cache="cache/master-info.xml"/>
</code>

===== 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 (<code>/</code>). 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 <code>fw</code>), it is treated as a sub-directory underneath the script directory

<code xml>
<fwstorage url="fw"/>
</code>

===== 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 <code>scfg="update.php?mode=backup&hwid=#h ser hourly /force 1"</code> (this example will make sure backups are attempted only once per hour, so as to reduce load on the server).

<code xml>
<backup
dir="backup"
nbackups="10"
scfg="update.php?mode=backup&hwid=#h "
/>
</code>

===== times =====
Defines the arguments of the [[Reference10:Concept_Update_Server#Times_command | 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 [[Reference10:Concept_Update_Server#Provision_command | 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

<code xml>
<times
allow="22,23,0,1,2,3,4"
initial="1"
check="true"
polling="5"
interval="15"
grace="900"/>
</code>

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

<code xml>
<phases>

<phase id="staging"/>
<phase id="update"/>
</phases>
</code>

===== 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 <code>?env=</code>''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

<code xml>
<environments>
<environment id='hq'>
<implies>intranet</implies>
</environment>
<environment id='intranet'/>
<environment id='homeoffice'/>
</environments>
</code>

===== 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 <code>#t</code> (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.

<code xml>
<classes>
<class id="gw">
<model>ip0010</model>
...
</class>
<class id="phone">
<model>ip110</model>
...
</class>
</classes>
</code>
====== class ======
Each ''class'' has a number of sub-tags of type ''model''. It contains the value replaced for the <code>#t</code> 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 <code>#t</code> argument replaced by the simulated device type (e.g. <code>http://172.16.10.65/update/update.php?type=ip222</code>). 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 <code>cache</code> 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 phasem ''staging'', the default (i.e. first) environment ''intern'' and for devices of class ''phone''.

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 <code>backup</code> 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 <code>&PROT=120663</code> 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 <code>&phase=update</code> 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 done using a [[Reference10:Concept_Update_Server#Check_command | check command ]]:

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

The ''serial'' <code>d41d8cd98f00b204e9800998ecf8427e</code> 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 <code>all-all-all.txt</code> 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'' <code>1e906fd3737281ebd4edbdf60a196fb3</code> 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 <code>debug.xml</code> 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 <code>mod cmd UP1 poll</code> command (e.g. <code>http://x.x.x.x/!mod cmd UP1 poll</code>)
* look at the traces (best with wireshark)
<hr>
You can easily see the current status of your update server and scripts by calling the URL <code>http://</code>''your-update-server''<code>/update.php?show</code>

===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''<code>-</code>''class''<code>-</code>''environment''<code>.txt</code> (e.g. update-phone-intern.txt). If the word <code>all</code> 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 <code>?type=#t</code> query arg in the update URL)
* the device's ''environment'' (as specified by the optional <code>&env=</code>''environment-name'' query arg in the update URL)

== Download ==
*[http://download.innovaphone.com/ice/wiki-src#php-update-server http://download.innovaphone.com/ice/wiki-src/] - download the complete file package of scripts and files described in this article

== Related Articles ==
* [[Reference10:Concept_Update_Server]]
* [[Reference12r1:DHCP_client]]
* [[Reference10:Concept_Linux_Application_Platform]]
* [[Reference10:Concept_Provisioning]]

[[Category:Sample|{{PAGENAME}}]]

Howto:PHP based Update Server

2016-08-28T18:24:33Z

Peter.seyringer: /* On the Linux Application Platform */

==Applies To==
This information applies to

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

All Versions.

By default, the [[Reference10:Concept_Update_Server | Update Server]] mechanism reads a file that corresponds to the device type (e.g. <code>update-ip222.htm</code>). 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 [[Reference10:Concept Linux Application Platform | 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 <code>update.php</code> 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 <code>update.php</code>, <code>config.xml</code> and <code>config.dtd</code> in to this directory
* create a directory named <code>cache</code> in this directory
* create a directory named <code>backup</code> in this directory
* make sure your web server can modify the two sub-directories
** on Linux, either change the directory modes to <code>0777</code> 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 <code>fw</code> in this directory
* copy firmware and boot code files (such as ''ipxxx.bin'' and ''bootxxx.bin'') to sub-directories of the <code>fw</code> directory (so you have e.g. firmware build 12345 for the IP232 in <code>fw/12345/ip232.bin</code>)
* 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 <code>http://</code>''url-to-your-new-directory''<code>/update.php?type=#t</code> (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 <code>admin/linux</code>, see [[Reference10:Concept_Linux_Application_Platform#Default_Credentials | 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 <code>update</code> underneath the <code>/var/www/innovaphone</code> directory. The URL to reach the update script will be <code>http://</code>''your-lap''<code>/update/update.php</code>
** copy the update server files (<code>config.xml</code>, <code>update.php</code> etc.) in to this directory
** create sub-directories <code>backup</code>, <code>cache</code> and <code>fw</code>
* log in to the LAP's admin UI (if you have not yet changed it, the default credentials will be <code>admin/linux</code>, see [[Reference10:Concept_Linux_Application_Platform#Default_Credentials | Concept Linux Application Platform]])
** go to ''Administration/WebServer/Change web server properties and public access to the web/webdav''
** add <code>/update/</code> 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 <code>root/iplinux</code>, see [[Reference10:Concept_Linux_Application_Platform#Default_Credentials | Concept Linux Application Platform]])
** <code>cd</code> to <code>/var/www/innovaphone</code>
** change owner of <code>update</code> and all its sub -directories to <code>www-data</code> (e.g. <code>chown -R www-data update</code>)

===Configuration===
==== Basic Parameters ====
All tweakable parameters are present in <code>config.xml</code>. 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 <code>http://</code>''your-reference-device''<code>/CMD0/box_info.xml</code>. 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 | ''Installation'' ]] above)

<code xml>
<master
info="http://172.16.0.10/CMD0/box_info.xml"
expire="3600"
cache="cache/master-info.xml"/>
</code>

===== 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 (<code>/</code>). 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 <code>fw</code>), it is treated as a sub-directory underneath the script directory

<code xml>
<fwstorage url="fw"/>
</code>

===== 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 <code>scfg="update.php?mode=backup&hwid=#h ser hourly /force 1"</code> (this example will make sure backups are attempted only once per hour, so as to reduce load on the server).

<code xml>
<backup
dir="backup"
nbackups="10"
scfg="update.php?mode=backup&hwid=#h "
/>
</code>

===== times =====
Defines the arguments of the [[Reference10:Concept_Update_Server#Times_command | 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 [[Reference10:Concept_Update_Server#Provision_command | 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

<code xml>
<times
allow="22,23,0,1,2,3,4"
initial="1"
check="true"
polling="5"
interval="15"
grace="900"/>
</code>

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

<code xml>
<phases>

<phase id="staging"/>
<phase id="update"/>
</phases>
</code>

===== 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 <code>?env=</code>''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

<code xml>
<environments>
<environment id='hq'>
<implies>intranet</implies>
</environment>
<environment id='intranet'/>
<environment id='homeoffice'/>
</environments>
</code>

===== 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 <code>#t</code> (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.

<code xml>
<classes>
<class id="gw">
<model>ip0010</model>
...
</class>
<class id="phone">
<model>ip110</model>
...
</class>
</classes>
</code>
====== class ======
Each ''class'' has a number of sub-tags of type ''model''. It contains the value replaced for the <code>#t</code> 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 <code>#t</code> argument replaced by the simulated device type (e.g. <code>http://172.16.10.65/update.php?type=ip222</code>). 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 <code>cache</code> 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 phasem ''staging'', the default (i.e. first) environment ''intern'' and for devices of class ''phone''.

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 <code>backup</code> 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 <code>&PROT=120663</code> 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 <code>&phase=update</code> 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 done using a [[Reference10:Concept_Update_Server#Check_command | check command ]]:

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

The ''serial'' <code>d41d8cd98f00b204e9800998ecf8427e</code> 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 <code>all-all-all.txt</code> 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'' <code>1e906fd3737281ebd4edbdf60a196fb3</code> 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 <code>debug.xml</code> 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 <code>mod cmd UP1 poll</code> command (e.g. <code>http://x.x.x.x/!mod cmd UP1 poll</code>)
* look at the traces (best with wireshark)
<hr>
You can easily see the current status of your update server and scripts by calling the URL <code>http://</code>''your-update-server''<code>/update.php?show</code>

===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''<code>-</code>''class''<code>-</code>''environment''<code>.txt</code> (e.g. update-phone-intern.txt). If the word <code>all</code> 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 <code>?type=#t</code> query arg in the update URL)
* the device's ''environment'' (as specified by the optional <code>&env=</code>''environment-name'' query arg in the update URL)

== Download ==
*[http://download.innovaphone.com/ice/wiki-src#php-update-server http://download.innovaphone.com/ice/wiki-src/] - download the complete file package of scripts and files described in this article

== Related Articles ==
* [[Reference10:Concept_Update_Server]]
* [[Reference12r1:DHCP_client]]
* [[Reference10:Concept_Linux_Application_Platform]]
* [[Reference10:Concept_Provisioning]]

[[Category:Sample|{{PAGENAME}}]]