innovaphone wiki - User contributions [en]

Reference10:Concept Linux Application Platform

2020-07-16T15:47:37Z

Odawid: /* Manual Debian 8 (jessie) Upgrade */

==Introduction==

The innovaphone Linux Application Platform permits to install innovaphone or custom applications for certain purposes, like Reporting or a Fax Server. 
It also allows to backup/restore configuration files, uninstall applications or see and backup logs. 
 
The Linux distribution Debian 7.1 (Wheezy) is used and linux kernel is 3.4.10 (IPxx10) and 3.2.0.4 (VM) 
 
The architecture of the platform is armel. 
 

==Requirements==

There are three ways to use the innovaphone Linux Application Platform:

===On an IPxx10 Gateway===
* An IP810, IP0010, IP3010 or IP6010 Gateway
* Firmware Version 10
* A compact flash card with UDMA support (minimum 8 GB)
** We recommend SanDisk Extreme with UDMA and 90 MB/s or above

===On an IPx11 Gateway===
* An IP0011, IP311, IP411, IP811 or IP3011 Gateway
* Firmware Version 11r2
* An SSD mSATA

===As a Virtual Machine===
* VMWare Player, VMWare Workstation, VMWare vSphere, Microsoft HyperV ([[Howto:Convert_a_V10_LinuxAP_to_VHDX_to_run_on_Hyper-V]])

* Minimal Requirements for the Virtual Machine:
1vCPU ( we run 800 MHZ CPU on our IPXX10 Gateways, so similar speed or higher it's enough, nevertheless depending on the operations/load you could need more CPU speed/vCPU)
512 MB RAM
8GB Disk

==Installation==

Download the latest Linux Application Platform from [https://download.innovaphone.com download.innovaphone.com ]. 
You can download and install two different packages: The IPxx10/IPx11 package to run on the gateways or a VMware image for VMware

===Default Credentials===
* Web/Webdav: '''admin'''/'''linux'''
* Root-Login (e.g. with Putty): '''root'''/'''iplinux'''

===Disk space calculation===
See [[Reference10:Concept_Reporting#Calculation_of_required_disk_space]].


It is strongly recommended that you try to precalculate the needed disk space and that you choose a suiting disk size.


===Disk space usage after first time installation===

====IPxx10/IPx11 Gateways====

* /dev/sda1: 32 MB (fat32 partition with two kernels, which are started by the IPxx10 or IPx11)
* /dev/sda2: 524 MB (ext2 initial installation partition)
* /dev/sda3: 120 MB (swap partition)
* /dev/sda4: 620 MB / xx GB depending of the size of the used CF card (ext4 partition, which is actually booted)

All in all about 1.3 GB are already in use after the initial installation.

====VMWare====

* /dev/sda1: 674 MB (ext2 initial installation partition)
* /dev/sda2: 120 MB (swap partition)
* /dev/sda3: 767 MB / xx GB depending of your pre installation configuration (ext3 partition, which is actually booted)

All in all about 1.6 GB are already in use after the initial installation.

===Linux Application Platform (IPxx10 or IPx11 Gateways)===

It is recommended to use CF-Cards with sizes of 8GB or more and the card '''must''' support UDMA! 
* Enable Linux under Linux General.
[[image:IPxx10_Linux_-_enable.png]]
* Be sure that "Autostart Linux" is disabled until the installation process is finished.
* You need to enable Proxy-ARP on ETH0 or ETH1 [[ Reference:Configuration/ETH/IP|here ]], so your gateway and the linux appliance will share the same physical interface. Simply go to '''IP4 > ETH0 (if used) > IP''' and check '''Proxy ARP'''
* Decompress the downloaded package. You should have an image file like <code>linux_ipxx10_armel.img</code> now. This works for both '''IPxx10''' and '''IPx11''' hardware!
* Upload the decompressed file over the gateways web interface under [[ Reference10:General/Compact-Flash/Image ]] (IPxx10) or [[ Reference12:General/SSD/Image ]] (IPx11). Unmount the CF card/SSD if necessary. Select "Part 1" before starting the upload!
[[image:IPxx10_Linux_-_upload_image.jpg]]
* Reset the box (which also activates the config change of step 1).
* Configure IP under [[ Reference10:Linux/IP ]]: select either "Disabled" to assign a static IP or ETH0/ETH1 to receive an IP-Address from DHCP-Server behind ETH0 or ETH1.
* Configure the kernel file, which you find under [[ Reference10:General/Compact-Flash/General#Browse_CF_Content ]] on [[ Reference10:Linux/General ]] '''Linux kernel file'''
** IPxx10 hardware: <code>Image-6010-3.4.10</code>
** IPx11 hardware: <code>Image-IPx11-4.4.0</code>
* Configure <code>root=/dev/sda2</code> under [[ Reference10:Linux/General ]] '''Kernel command line'''.
* If you want, configure the autostart flag.
* Submit your changes.
* Click the [[ Reference10:Linux/General ]] '''Start'''-Link. The page refreshes until Linux gets an IP and then tries to get a link to the Linux Web Server, which can take some time for the first time installation (~ 5 minutes to 2 hours, for a IP411 ~15 minutes).
[[Image:device_conf.jpg]]
* Open the Linux Web Server to see the installation progress (which might take several minutes too). The default credentials are '''admin'''/'''linux''' for both platforms.
[[Image:installation.jpg]]
* The output of the installation log is stored on the Linux AP under <code>/var/log/init_install.log</code>. In case you have no access to the web server but a console or SSH access, you can check the installation progress in this log file. E.g. login to the console with root/iplinux and run follwong command: <code>more /var/log/init_install.log</code>. In case you have an SSH connection to the Linux AP, you can download this file using [http://winscp.net WinSCP] tool.
* Enter the innovaphone device IP address (optional port allowed) and admin credentials when the installation has finished. Now wait until the page refrehses. The web server credentials are now the innovaphone device admin credentials, e.g. '''admin'''/'''ip6010'''.
** If the device couldn't be reconfigured, you will get an error message '''Command line at the PBX could not be changed...''' In this case, you have to open [[ Reference10:Linux/General ]] on your device, click stop and enter <code>root=/dev/sda4</code> under '''Kernel command line'''. Then start again. Your Linux webserver credentials will be '''admin'''/'''linux''' in this case.
* Linux install has finished.
* You will see now <code>root=/dev/sda4</code> under [[ Reference10:Linux/General ]] since Linux is running in on the fourth partition. You shouldn't change that unless you want to install Linux again.

===Linux Application Platform (VMWare)===

* Decompress the downloaded archive. You should have two files: '''IP-Debian.vmx''' and '''IP-Debian.vmdk'''.
* We can open using Vmware Player/Workstation, if you wish to run on Vsphere 4.x or later please convert it by the same method it's done with the IPVA (see [[Reference10:Concept_Innovaphone_Virtual_Appliance#VMware_vSphere | Using VMware vSphere]])
* Now you have two possibilities (example for VMWare Player, VMWare Workstation should be similar):
** If you want to assign more than 8 GB virtual flash:
*** Do '''not''' directly start/doubleclick the vmx file!
*** Start the VMware Player and Open the vmx file with '''Open a Virtual Machine'''.
*** Open '''Edit virtual machine settings'''.
*** Select the hard disk and '''Expand''' it under '''Utilities''' to the wished size.
*** Apply the change and klick '''Play virtual machine'''.
** If 8 GB are enough, simply double click the vmx file and Linux will start.
* The first time, a script will automatically configure a new partition, the web server etc., which will take some time. The waiting time depends on the CPU of the computer running the vmware player. In some cases the waiting time can be up to 30 minutes, in most cases the installation finishes in about 2-5 minutes.
* In the meantime, fetch your IP from the VMWare Player screen or login as root and get your IP address with the command '''ifconfig'''.
* Login to the web server to see the installation progress (it may take some minutes until the web server is up).
* Linux will restart automatically after the first time installation has finished.
* Linux install has finished.

===Hotfix Installation===
If you have already installed the latest version of the Linux Application Platform, simply download the Linux...HotfixIncremental for your platform (VM or IPxx10/IPx11) or if you have missed some hotfixes, download the Linux...HotfixCumulative archive, which contains all hotfixes since hotfix1.
 
 
Upload this hotfix archive [[Reference10:Concept_Linux_Application_Platform#Upload.2FUpdate|here]].

====Refreshing issue on installation====
You might get a PHP error when the browser is refreshing during the installation. Just refresh (F5) the page and you'll get the installation progress again.

=== Upgrade from a previous major Release ===
For instructions how to upgrade from a previous major release (such as V9 to V10), see ''Upgrading Linux Application Platform'' in [[Howto:Firmware_Upgrade_V9_V10|Firmware Upgrade V9 V10]].

===Static IP===
The Linux itself '''must''' be running in DHCP client mode on an IPxx10/IPxx11 gateway to run properly. If you want to assign a static IP address, do it like this:

* On an IPxx10/IPxx11: assign a static IP under [[Reference10:Linux/IP]], this will do an internal DHCP response to the Linux that's running as DHCP client mode.
* On a VMWare: assign a static IP in your local DHCP server for your MAC address defined in the *.vmx file or configure a static IP address under [[ #Configure_IP | Configure IP ]].

===IPxx10/IPxx11 Transit network for Linux===
When running Linux on an innovaphone device IPxx10/IPxx11 there is no dedicated network interface for the Linux machine. Instead we have a special transit network between the Linux and the device. The Linux will always operate as DHCP Client mode.

Any ARP request done by the Linux machine will always get the same ARP result that will be the internal "NIC" inside the device, so all packets are always sent to the same IPxx10/IPxx11 device that works as a router. When the packet sent by the Linux machine arrives the innovaphone device, it will follow the IP routing table of the device itself.

In case we have a single network (voice) we will have no problem since the default gateway is just one. However, if we wish to split into two networks (voice and data) and the Linux machine should have a different default gateway, this has no effect since IP routing is based on the innovaphone device IP routing table, because we can't have two default gateways at the same time.

==Administration==

===General===

====Configure IP====

The IP configuration on the Linux Application Platform is '''only''' available on a '''VM'''! A static IP for a Linux Application Platform for an IPxx10/IPxx11 can be configured on your gateway under Linux/IP.

* Mode: either DHCP Client or Static
* [IP Address]: the desired static IP address
* [Subnet Mask]
* [Gateway]
* [DNS Server]
* [Alternate DNS Server]

The optional parameters in [] can be only configured, if '''Static''' is selected as mode.

====Change the root credentials====

Here you can change the credentials of the Linux root user. 
Default password: '''iplinux'''

====Configure Authenticated URLs====

Configure credentials for authenticated URLs. These credentials will be used in automatic backups. 
You can add/remove Urls with the '''+''' and '''-''' at the right side of the list.

* URL: the URL, e.g. https://172.16.123.123/backup
* User: the user for this URL
* Password: the password for this URL

====Configure NTP server====

Configures a NTP server.

* NTP Server: the IP of the NTP Server

====Change Timezone====

Default is Europe/Berlin but you can change that to a valid timezone (an error is given if timezone not present). 

====Change postgresql admin password====

If innovaphone Reporting is installed, you can configure another password for the postgres admin user. 
Default password: '''postgres'''.

===Web Server===

We use lighttpd version 1.4.32. The linux web server user is '''www-data''' and group user also '''www-data'''. Root directory for the web-server is '''/var/www/innovaphone'''. This information is mainly relevant if you plan to develope custom applications and integrate them into linux application platform.

Default users and password for the different levels on the Linux application plattform (see figure below):
[[image:Linux_Application_hierarki.PNG]]

====Change web server properties and public access to the web/webdav====
* Force HTTPS: enables redirection for HTTP to HTTPS
* Public Web Paths: these paths are not password protected, e.g. '/ap'
* Public Webdav Paths: these webdav paths are not password protected, e.g. '/backup'
** These paths are by default readonly. You can set the 'Write' flag to make the path also writable. This flag will be anyway ignored if credentials are provided. 

''<IPadr>''<code>/webdav/</code> is the root directory for webdav files. If you want to access a directory/file without credentials you have to add this directory to the Public Webdav Paths.

Example: <code>/webdav/background/</code> Here you have the background pictures for your Phones. 
Public Webdav Paths: <code>/background</code> or <code>/background/a</code> 
Now you have a public access to the folder background. 

* Enter a single '<code>/</code>' for a public root directory. All sub directories and files will be also public then. 
* If you enter e.g. '<code>/update/</code>', the directory 'update' and all sub directories/files will be public. 
* If you enter e.g. '<code>/update</code>', only the directory 'update' and its files will be public.

Important: Linux file names are case sensitive (so <code>/Update</code> is not equal <code>/update</code>)!.

====Change the Linux web server credentials====

Here you can change the credentials for Web Server access.

If running VMWare, default password is '''linux'''. If running IPXX10, password is the one entered at the end of first installation (admin password of the device where linux is running)

====Change the Linux webdav access credentials====

Here you can change the credentials for webdav access.

If running VMWare, default password is '''linux'''. If running IPXX10, password is the one entered at the end of first installation (admin password of the device where linux is running)

====Change application access credentials====

If you have installed an application, which has the lighttpd-auth property set in its configuration file, you can configure a separate user/password for the applications web site. 
If you want to disable the separate authentication, leave the '''user''' field empty and enter the currently configured password. The authentication will be the same as the root web server authentication afterwards. 
One can just login on the application web site with this access.

A configured access overrides a configured public web path to '/apps/application-name'!

====Configure mutual TLS====

If you need mutual TLS for innovaphone devices with a certificate signed by innovaphone, you can activate mutual TLS for a configurable '''port'''. 
Currently we're just supporting client certificates signed by innovaphone's ''innovaphone Device Certification Authority''. 
 
The physical mutual TLS path is '''/var/www/innovaphone/mtls'''. Here you can put your script files, e.g. mtls.php. 
You then call this script file by '''https://linux-ip:mtls-port/mtls.php''', as this path is the document root for the configured port.

'''How to upload the script:'''

Using a webdav client (like NetDrive) upload the script to the webdav folder.
Afterwards connect with Putty to the linux.

The uploaded file is under /var/www/innovaphone/webdav and we must move it to /var/www/innovaphone/mtls

===Certificates===

The current server certificate installed on the web server is shown here. A self signed certificate, innovaphone-linux, is installed by default. It is recommended to change it with your own certificate.

It is also possible to trust or reject other certificates.

'''Note''': Currently the LAP doesn't support the upload of a password protected certificate. As a workaround it is possible to convert the certificate with OpenSSL (on windows or Linux) to PEM format without password and upload this one.

With the following openssl command, the password protected certificate can be changed into an unprotected certificate.

<code>openssl pkcs12 -in</code> ''CertificateWithPasswort'' <code>-out</code> ''CertificateWithoutPasswort''.pem <code>-nodes</code>

The unprotected certificate should be deleted directly after upload for security reasons.

If you want to create a private, unsigned certificate you can do this with the following commands on the Linux AP CLI.
It is best to go in a folder which can be reached via http later as <code>/var/www/innovaphone/webdav/...</code>

Enter the following command:

<code>openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days xxxx (insert number)</code>

Add <code>-nodes</code> if you don't want to protect your private key with a passphrase.

You now will be asked for certificate information.

To merge the certificate and key you can enter the following command:

<code>cat cert.pem >> key.pem</code>

The file key.pem can now be uploaded via the web interface of the Linux AP.

===Backup===

The web server can be configured to poll a Command File URL (on a web server). 
The backup process is similar to [[Reference10:Services/Update]]. 

An alarm server can be also configured to receive alarms during an automatic backup: [[ #Alarm_Server | Alarm Server under Diagnostics ]].

At the bottom you will see a list of the current automatic backup serials from the Command File URL and the log of the last automatic backups.

[[Image:backup_restore.jpg]]

====Command File====

Example:
saveinnovaphonecfgs http://172.16.123.123/webdav/backup/cfgs-#i-#b10.tar.gz

The available default commands are:

=====saveinnovaphonecfgs=====

Saves all neccessary configuration files (no application specific files) as a tar gz archive (so you should use .tar.gz as ending).

=====saveinnovaphonelogs=====

Saves all available (also application related) log files as a tar gz archive (so you should use .tar.gz as ending).

=====saveinnovaphone-applicationnamelogs=====

Saves log files as a tar gz archive (so you should use .tar.gz as ending) for applicationname (reporting, exchange or faxserver)
'''saveinnovaphone-reportinglogs'''

=====saveinnovaphone-applicationnamecfgs=====

Saves all neccessary configuration files as a tar gz archive (so you should use .tar.gz as ending) for applicationname (reporting, exchange or faxserver)
'''saveinnovaphone-reportingcfgs'''

=====saveinnovaphone-applicationnamedb=====

Saves ddbb if existing as a tar gz archive (so you should use .tar.gz as ending) for applicationname (reporting, exchange or faxserver)
'''saveinnovaphone-reportingdb'''

=====times=====
Executes the following command(s) only, if the specified time matches and only once per hour (independent of poll timeout value). 
Example:

<pre>
# both commands always executed
saveinnovaphonelogs http://xxx.xxx.xxx.xxx.xxx/webdav/backup/linux-logs-#i-#m-#b10.tar.gz
saveinnovaphonecfgs http://xxx.xxx.xxx.xxx.xxx/webdav/backup/linux-cfg-#i-#m-#b10.tar.gz
# commands only from monday till saturday at 10am and 11am executed.
times day:1,2,3,4,5 hour:10,11
saveinnovaphone-reportingcfgs http://xxx.xxx.xxx.xxx.xxx/webdav/backup/linux-innovaphone-reporting-cfgs-#i-#d-#b10.tar.gz
saveinnovaphone-reportinglogs http://xxx.xxx.xxx.xxx.xxx/webdav/backup/linux-innovaphone-reporting-logs-#i-#d-#b10.tar.gz
# commands only Saturdays and Sundays at 00am executed.
times day:6,7 hour:00
saveinnovaphone-reportingcfgs http://xxx.xxx.xxx.xxx.xxx/webdav/backup/linux-innovaphone-reporting-cfgs-#i-#d-#b10.tar.gz
saveinnovaphone-reportinglogs http://xxx.xxx.xxx.xxx.xxx/webdav/backup/linux-innovaphone-reporting-logs-#i-#d-#b10.tar.gz
</pre>

* day goes from 1 (Monday) to 7 (Sunday). 
* hour goes from 00 to 23. 

You can specify multiple times commands to override the last one. 

=====Backup file name macros=====

You can use some macros for the backup filename:

* #i - will be replaced with the current IP address
* #m - will be replaced with the current MAC address
* #d - will be replaced with date/time in format Ymd-His (20110231-111010)
* #bxx - will be replaced with the current backup index, whilst xx is the maximum index

====Save configuration files/data====

Open this link to see all available files/data/logs to download them manually.

Password files for web server authentication won't be saved!

====Restore configuration files/data====

Open this link to restore all available files/data.

Password files for web server authentication won't be restored!

===Relay Hosts===

The Application Platform contains a mail client which speaks SMTP.
The SMTP daemon (postfix) looks up by default the DNS MX record of the recipient email address. 
Relay SMTP hosts can also be configured to deliver the mails. Each relay host is related to a '''sender''' mail address or a '''sender''' mail domain. TLS is used if the host supports it. 
Examples of the server entry:
; mydomain.com: MX record to the domain
; smtphost: host name with MX record lookup
; [gateway.example.com]: host name with DNS lookup
; [an.ip.add.ress]: IP address without DNS lookup
The form [hostname] turns off MX lookups. See also [http://www.postfix.org/postconf.5.html#relayhost the postfix documentation]. 
If anonymous SMTP is to be used, user and password must be left empty.
 

[[Image:relay_hosts.jpg]]

'''Note:''' Important to use "[]" like in the picture.

Currently innovaphone Reporting and innovaphone Faxserver are using these relay hosts, if entered.

===Database===

The innovaphone database is created to store e.g. relay hosts.
PostgreSQL is also available for other applications and any of them could create its own database.

====Password====

The database user is '''innovaphone''' with default password '''innovaphone'''.
This password may be changed here.

====Remote Access====

There are tools (PgAdmin III) that allow to connect to application databases remotely.
It is first needed to configure the IP you are connecting from here. (Only Single-IP entry it's allowed, no submask or wildcard for multiple IPs)

For the PgAdmin III it is imporant to use innovaphone as Service-DB (Wartungs-DB). Default login credentials - User: innovaphone - Password: innovaphone

===Announcements===

You can upload a 16bit,8khz,mono wave file, which will be converted to G711U/G711A/G723/G729 . 
The converted files will be stored inside the webdav/announcements folder, e.g. http://172.16.111.111/webdav/announcements/test.g7xx 
 
If you check the '''Return files as ZIP file''' flag, you will get a ZIP file, which contains the converted files. These files are not stored locally then! 
For the new Codec G722, OPUS-NB and OPUS-WB you have to use the online converter available on my.innovaphone portal (login necessary first): https://my.innovaphone.com/support.php or on our website https://www.innovaphone.com/en/support/convert.html. No Conversion of new codecs is possible with Linux AP !

==Applications==

===List===

A list of all currently installed applications. 
If an application has an own web interface, you can reach it by using the application name link. 

====Uninstall====
Use the uninstall link in the list to uninstall an application.

===Upload/Update===

Here all new applications, application updates and application platform updates are installed. 
After uploading the file, the installation will start automatically and the installation process will be shown. The page refreshes until the installation has finished.

==Diagnostics==

===Logs===

Here you can view, download or clear the available log files from the application platform or from installed applications. 
You can also download all log files at once (this archiv also contains older versions from the log files).

===RPCAP===

Enable/disable RPCAP for use with Wireshark. 
A link will be displayed, which you can use within Wireshark.

===Alarm Server===

Configure an innovaphone device as alarm server:

* '''ip''': IP address of the innovaphone device
* ['''port''']
* ['''user''']: user for authentication to the alarm server
* ['''password''']
* ['''https''']: use https to send the alarm

Options in '''[]''' are optional.

Alarms from installed applications or the application platform itself will be sent to this configured server.

===Status===

View the disk usage.

===Reset===
====IPxx10====

Shutdown the application platform. You'll have to restart it over the IPxx10 gateway.

====VMWare====

Shutdown the application platform or reboot it.

===Status PHP script===
http://LinuxAP/status.php returns an XML file containing the output from the following linux commands: 
* df -H
* free -h
* uptime
* ps -wwweo pid,lstart,time,etime,pcpu,pmem,rsz,vsz,args
* ss -A inet -ap
* top -b -n 1

==Use as Log or Alarm Server==

You can use the application platform as a server for innovaphone logs. 
Configure Local-AP(-s)/Remote-AP(-s) on [[Reference10:Services/Logging]].
 
The following scripts are used to retrieve the logs/alarms:
* logs: /ap/log.fcgi
* alarms: /ap/alarm.fcgi

So you can make the path '''/ap''' public on the ''Linux Web Server'' or you configure an authenticated URL for these files/this path on your ''innovaphone gateway''. 

If you configure an authenticated URL, don't forget to configure port 80 or port 443 for secure transport (Remote-AP-S) like
https://111.111.111.111:443/ap or http://111.111.111.111:80/ap

The log and alarm files will be saved unter http://LAP/webdav/log or /alarm. The files are rotated after 1 MB size and four times, so you'll have max 5 files.

==Use as File/VM-Server==

You can use the application platform as file server, e.g. for udpate scripts, voicemail etc. 
You can access the server with a webdav client via '''http(s)://Linux-IP/webdav''' 
Public access to certain paths etc. can be configured under the [[Reference10:Concept_Linux_Application_Platform#Web_Server | web server configuration]].

Keep in mind that the Linux Filesystem(ext3) is case sensetive. The PBX will always search for lowercase letters. If you name your file ‘greetings.G711A’ it won’t be found. You have to name the file ‘greetings.g711a’.

==Enable further Tracing==
There are different trace options, which can be enabled by calling a certain php script: 
https://LINUX-IP/trace.php?level=127

The level is calculated by the addition of one or multiple of the following trace options:

{| border=1
|| '''Option''' || '''To add'''
|-
|| TRACE_STD || 1
|-
|| TRACE_DB || 2
|-
|| TRACE_TIME || 4
|-
|| TRACE_CALL_FLOW_TOTAL || 8
|-
|| TRACE_CALL_FLOW || 16
|-
|| TRACE_PARSE_CFG || 32
|-
|| TRACE_LDAP || 64
|-
|| TRACE_XML || 128
|-
|}

So currently all trace options are enabled with the level '''255'''.

Default trace level are "0"

==Appendix==
===Creating own applications===
See [[Reference10:Concept Linux Application]]

===Tools===

====WinSCP====

[https://winscp.net WinSCP] is a usefull webdav client, which can be used to access webdav of the innovaphone application platform.

====Putty====

[http://www.putty.org/ Putty] is SSH client to connect to the linux application platform.

===Configuring a new Kernel===
If you have installed a hotfix with a new kernel, you will see a warning message on your application platform. Something like:

<code type="text">
You're not running the latest kernel Image-6010-3.4.10!
Take a look at our wiki to see, what you have to do now!
</code>

To change to the new kernel, you have to reconfigure something on your device, where the CF card is plugged in.
* First shutdown your Linux (see [[ Reference10:Concept_Linux_Application_Platform#IPxx10 ]])
* Stop Linux under [[ Reference10:Linux/General ]]
* Configure the latest kernel file (currently <code>Image-6010-3.4.10</code>) under [[ Reference10:Linux/General ]] '''Linux kernel file'''
* Start Linux under [[ Reference10:Linux/General ]]

===Alarms of the Application Platform===
If you have configured an [[ #Alarm_Server | Alarm Server]], you will receive certain alarms. 
Currently, the following alarms exist:

* Disk Usage >= 90%
* read-only mounted partition
* bad blocks on CF cards
* Alarms for the innovaphone Reporting Application, if installed
* Alarms for the innovaphone Exchange Calendar Connector Application, if installed
* Alarms for the innovaphone Faxserver Application, if installed

===Initially installed packages===

The following packages are already installed without any application:

* adduser
* apt
* apt-utils
* aptitude
* aptitude-common
* base-files
* base-passwd
* bash
* binutils
* bsdmainutils
* bsdutils
* bzip2
* ca-certificates
* comerr-dev
* coreutils
* cpio
* cpp
* cpp-4.7
* cpp-4.6
* cron
* curl
* dash
* db-util
* db5.1-util
* debconf
* debconf-i18n
* debian-archive-keyring
* debianutils
* diffutils
* dmidecode
* dmsetup
* dos2unix
* dovecot-common
* dovecot-core
* dovecot-pgsql
* dovecot-pop3d
* dovecot-sieve
* dpkg
* e2fslibs
* e2fsprogs
* file
* findutils
* gamin
* gcc
* gcc-4.7
* gcc-4.6
* gcc-4.6-base
* gcc-4.7-base
* gettext-base
* gnupg
* gpgv
* grep
* groff-base
* grub-common
* grub-legacy
* gzip
* hdparm
* hostname
* ifupdown
* info
* initramfs-tools
* initscripts
* insserv
* install-info
* iproute
* iptables
* iputils-ping
* isc-dhcp-client
* isc-dhcp-common
* klibc-utils
* kmod
* krb5-multidev
* libacl1
* libapt-inst1.5
* libapt-pkg4.12
* libasprintf0c2
* libattr1
* libblkid1
* libboost-iostreams1.49.0
* libbsd0
* libbz2-1.0
* libbz2-dev
* libc-bin
* libc-client2007e
* libc-dev-bin
* libc6
* libc6-dev
* libcap2
* libclass-isa-perl
* libcomerr2
* libcurl3
* libcurl4-openssl-dev
* libcwidget3
* libdb5.1
* libdevmapper1.02.1
* libedit2
* libept1.4.12
* libexpat1
* libfcgi-dev
* libfcgi0ldbl
* libffi5
* libfreetype6
* libfuse2
* libgamin-dev
* libgamin0
* libgcc1
* libgcrypt11
* libgcrypt11-dev
* libgdbm-dev
* libgdbm3
* libglib2.0-0
* libgmp10
* libgnutls-dev
* libgnutls-openssl27
* libgnutls26
* libgnutlsxx27
* libgomp1
* libgpg-error-dev
* libgpg-error0
* libgpgme11
* libgpm2
* libgssapi-krb5-2
* libgssrpc4
* libidn11
* libidn11-dev
* libitm1
* libk5crypto3
* libkadm5clnt-mit8
* libkadm5srv-mit8
* libkdb5-6
* libkeyutils1
* libklibc
* libkmod2
* libkrb5-3
* libkrb5-dev
* libkrb5support0
* libldap-2.4-2
* libldap2-dev
* liblocale-gettext-perl
* liblzma5
* libmagic1
* libmemcache-dev
* libmemcache0
* libmount1
* libmpc2
* libmpfr4
* libmysqlclient18
* libncurses5
* libncursesw5
* libnewt0.52
* libnfnetlink0
* libonig2
* libopts25
* libp11-kit-dev
* libp11-kit0
* libpam-modules
* libpam-modules-bin
* libpam-pgsql
* libpam-runtime
* libpam0g
* libpam0g-dev
* libparted0debian1
* libpcre3
* libpcre3-dev
* libpcrecpp0
* libpipeline1
* libpng12-0
* libpng12-dev
* libpopt0
* libpq-dev
* libpq5
* libprocps0
* libpth20
* libqdbm14
* libquadmath0
* libreadline6
* librtmp-dev
* librtmp0
* libsasl2-2
* libsasl2-modules
* libselinux1
* libsemanage-common
* libsemanage1
* libsepol1
* libsigc++-2.0-0c2a
* libslang2
* libsqlite3-0
* libsqlite3-dev
* libss2
* libssh2-1
* libssh2-1-dev
* libssl-dev
* libssl1.0.0
* libstdc++6
* libtasn1-3
* libtasn1-3-dev
* libtext-charwidth-perl
* libtext-iconv-perl
* libtext-wrapi18n-perl
* libtinfo5
* libtokyocabinet9
* libudev0
* libusb-0.1-4
* libustr-1.0-1
* libuuid-perl
* libuuid1
* libwrap0
* libxapian22
* libxml2
* libxml2-dev
* libxml2-utils
* linux-base
* linux-image-3.2.0-4-686-pae
* linux-libc-dev
* locales
* login
* logrotate
* lsb-base
* lsb-release
* make
* makedev
* man-db
* manpages
* manpages-dev
* mawk
* mime-support
* mlock
* module-init-tools
* mount
* multiarch-support
* mysql-common
* nano
* ncurses-base
* ncurses-bin
* net-tools
* netbase
* netcat-traditional
* ntp
* ntpdate
* openssh-client
* openssh-server
* openssl
* parted
* passwd
* patch
* perl-base
* php-pear
* php-xml-parser
* php-xml-serializer
* php5-cgi
* php5-cli
* php5-common
* php5-curl
* php5-imap
* php5-pgsql
* php5-xcache
* pkg-config
* postfix
* postfix-pcre
* postfix-pgsql
* postgresql-9.1
* postgresql-client-9.1
* postgresql-client-common
* postgresql-common
* procps
* psmisc
* python
* python-minimal
* python2.7
* python2.7-minimal
* rdate
* readline-common
* rsyslog
* sasl2-bin
* sed
* sensible-utils
* shared-mime-info
* ssh
* ssl-cert
* sudo
* sysv-rc
* sysvinit
* sysvinit-utils
* tar
* tasksel
* tasksel-data
* traceroute
* tzdata
* ucf
* udev
* util-linux
* uuid-dev
* vim
* vim-common
* vim-runtime
* vim-tiny
* wget
* whiptail
* xz-utils
* zlib1g
* zlib1g-dev
* lighttpd-mod-webdav
* lighttpd

==Known Issues==
=== Do not update Debian Packages ===
The Linux application platform comes with the tested set of required Debian packages. ''It is not recommended to do a manual update of those packages'' (or the kernel itself). We have seen situations where updated packages had been changed in a non-downward compatible fashion - resulting in the applications running on the Linux application platform not working properly an more!

===Separate authentication for innovaphone applications===
If you configured a separate authentication, it depends on the used browser, whether you have to re-authenticate on switching between the root web and the innovaphone application web access or not.

===Refreshing issue on hotfix installation===
[[ Reference10:Concept_Linux_Application_Platform#Refreshing_issue_on_installation | See here. ]]

===Kernel Update in VM Platform===
The installation of a new kernel fails and this process leaves the system unstable, not being able to install any more debian packages. Hotfix installations will probably fail.

===Outdated packages? Debian Upgrade?===
From time to time we will deliver upgraded debian packages with a new hotfix. As we have to insure compatibility with our applications, we won't perform an upgrade for each hotfix! 
 
Please do '''not''' perform an update/upgrade yourself, as this will break future hotfix/application releases. Sometimes we deliver debian packages in our hotfixes and dependencies might be broken if you update/upgrade yourself.

====I want to do it anyway!!!====
Ok, save your application/ap configuration and data files and install our latest '''FULL''' release without any hotfix. Restore the configuration/data files and perform your update/upgrade. Now you can be happy, if everything still works fine... 
Perform these steps for each new hotfix release, as you might not be able to apply a new hotfix.

====Manual Debian 8 (jessie) Upgrade====

'''Make a backup first and innovaphone won't be able to support manually upgraded installations'''!

If you want an update to Debian 8 (jessie), you can do this via the command line interface (CLI).
But there are a few steps necessary.

Install or update all innovaphone applications (Reporting, Faxserver, Exchange Calendar Connector) that should be run on the Linux Application Platform.

;Important
;*Subsequently, no Innovaphone applications may be installed or uninstalled!
;*Future Innovaphone Service Releases can not be installed after this step.

[[ #Hotfix_Installation | Update ]] the Linux Application Platform and all applications to the latest version (at least Service Release 53).

Make a [[ #Backup | Backup ]] of the Linux Application Platform and all applications.

Make sure, your Linux Application Platform has internet access.

* Login with a terminal client like Putty.

* Enter the Debian 8 (jessie) sources in the sources.list to perform the update. 
<code>echo "deb http://ftp.de.debian.org/debian jessie main" >> /etc/apt/sources.list
echo "deb http://security.debian.org jessie/updates main" >> /etc/apt/sources.list</code>
* Perform the update. 
<code>apt-get update
apt-get dist-upgrade</code>

The following questions answer as follows.
<code>Configuration file '/etc/sysctl.conf': N => keep the current version 
Configuration file '/etc/vim/vimrc': N => keep the current version</code>

* Restart the Linux Application Platform.
<code>reboot</code>

* Remove the paket php5-xcache, as the new PHP comes with an own opcode cache which creates conflicts. 
<code>apt-get remove php5-xcache</code>

* Disable php zend extension, which is now incompatible and restart the webserver. 
<code>sed -i 's/zend_extension/;zend_extension/g' /etc/php5/cgi/php.ini
/etc/init.d/lighttpd restart</code>

* Change /bin/sh shell. 
<code>ln -sf /bin/bash /bin/sh</code>

* Apply unoconv patch which comes with latest service release. 
<code>cp /usr/bin/unoconv /var/www/innovaphone/apps/innovaphone-faxserver
cd /var/www/innovaphone/apps/innovaphone-faxserver
patch < /var/www/innovaphone/apps/innovaphone-faxserver/unoconv.patch
chown innovaphone-faxserver:www-data unoconv
/etc/init.d/innovaphone-faxserver restart
</code>
 
Important, you cannot upgrade the Linux Application Platform to Debian 9 (stretch).



=== Database Performance Issues ===
When you run many applications on your LAP (for example, Reporting or Fax for many PBXs), you may run into database performance issues. In this case, you will see messages like

LOG: checkpoints are occurring too frequently (29 seconds apart)
HINT: Consider increasing the configuration parameter "checkpoint_segments".

in the postgresql log file. To fix this, you may carefully increase the setting of <code>checkpoint_segments</code> in <code>/etc/postgresql/9.1/main/postgresql.conf</code>. By default, this value is not set (commented out):

#checkpoint_segments = 3 # in logfile segments, min 1, 16MB each

You can change this to 10

checkpoint_segments = 10 # in logfile segments, min 1, 16MB each

(note the removed comment introducer at the beginning of the line). Please note that this will take 112MB more disk space on the LAP, so be sure you have enough.

For more details on postgresql tuning, see https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server.

Note that you may need to re-apply this change when you have installed a LAP update.

==How To==
===Reset webserver/webdav passwords===
In case you have lost your webserver or webdav password, but you still have the root credentials, you can login with SSH and execute the following commands:

<code type="bash">
echo "admin:Linux Web Server:c33c4d3f554367d5d1c3c9bf36803024" > /home/lighttpd/lighttpd_htdigest.user
echo "admin:Linux Webdav:7182e328a0531dd2d44d225f36da6b87" > /home/lighttpd/webdav_htdigest.user
/etc/init.d/lighttpd restart
</code>

Afterwards you can access your webserver/webdav with '''admin'''/'''linux'''

The same can be done for application specific passwords, e.g. Reporting.
In this case, use the file '''/home/lighttpd/innovaphone-reporting-htdigest.user'''

===Convert the Linux AP to VMware vSphere ===
If you are using a VMware vSphere 4.x or later you need to use the VM Ware Standalone Converter to convert the Linux Application Platform.
You'll find a step by step guide [https://kb.swivelsecure.com/wiki/index.php/VMWare_Converter_How_to_Guide here]

==TroubleShooting==

===Installation process failed===

When the installation process stuck either because it doesn't get IP or services are not refresh/finished there is some additional information we could get from the Compact Flash that could help us understanding what is failing and if necessary open a support ticket and include this information in the ticket to innovaphone.

* Stop the linux and check General->Compact Flash "Browse files". All files in there might be helpfull (all but the kernel, of course).
* Start the linux and check if you can connect to the configured/expected IP address via Putty after ~1 minute.

Note: The file /var/log/init_install.log might help us to get a clue of the failure.

===Howto save and restore Linux AP data/database if the webgui is not available===

If the linux ap webgui is not reachable a common reason is that the harddisc is full.
If a full hd is the case, maybe your first thought is to increase the harddisc.
It could be a solution but there are some traps to increase the partition in linux which can be ended in complete data loss

The fastest way to get linux ap working with a new harddsik size is to install a new one.

'''How can you save the data without get access over the webgui?'''
If you can reach linux via putty it could be possible :)

Here are some possibilities how to do that over the shell:
'''(But keep in the back of you head that you are working as root and therefore typing errors can lead to undesirable behaviours!)'''

1. Delete at first all the logfiles. Sometimes a few MByte are enough to get all the stopped services running again and you could reach liunx over the webgui.
i.e. the reporting logfiles are under "''/var/www/innovaphone/apps/innovaphone-reporting/log''", the fax server logfiles are under
"''/var/www/innovaphone/apps/innovaphone-faxserver/log''"
-> '''Don't delete the 'log' directory itself!''' Delete only the content:

root@vmware-debian: cd /var/www/innovaphone/apps/innovaphone-reporting/log/
root@vmware-debian: rm *

Is the linux ap after a restart running and over http reachable, download all the config and databases and restore them on the new linux ap (2.2).

[[image:save.png]]

2. In case the reason for the unreachable webgui was not a full harddisk you can save the config/database (only reporting and exchange connector at the moment)
over the shell.

root@vmware-debian:/# cd /home/postgres/
''for reporting type:''
root@vmware-debian:/# sudo -u postgres /usr/bin/pg_dump --encoding=utf8 --schema=public -Fc -U postgres innovaphone-reporting | gzip -fc6 > innovaphone-reporting-db.gz

root@vmware-debian:/# cd /home/postgres/
''for exchange connector type:''
root@vmware-debian:/# sudo -u postgres /usr/bin/pg_dump --encoding=utf8 --schema=public -Fc -U postgres innovaphone-exchange | gzip -fc6 > innovaphone-exchange-db.gz

2.1 Access linux with winscp '''(protocol: scp / user: root)''' and download the .gz (don't unzip)

[[image:reporting.png]]

(BTW: you can '''download''' with '''scp''' also the complete webdav files. But for the '''upload''' use as user 'admin' and as protocol "'''webdav'''".
Otherwise the owner is still root and this ends in authorization problems)

[[image:webdav.png]]

2.2. on the new linux ap upload this .gz

[[image:restore.png]]

3. The steps mentioned above should be only the last try to get the data and could work or not.
To be always on the save site use a standby Linux (for reporting), save configs (update server) and delete (automatic) old cdr's to avoid a full hd.

=== How to recover from a broken File System ===
Sometimes you may find messages in the ''kern.log'' log file (in ''var/log'') like

Aug 15 10:45:31 ip6010-debian kernel: EXT4-fs (sda4): initial error at 1500329378: ext4_journal_start_sb:328
Aug 15 10:45:31 ip6010-debian kernel: EXT4-fs (sda4): last error at 1500329378: ext4_journal_start_sb:328

This indicates a file system failure on the Linux Installation.

When the Linux file system is broken, you can try to repair it using some command line Linux tools.

* Open the WebGUI of the gateway running your LAP and proceed to ''Linux/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/sda4'' to <code>root=/dev/sda2</code>
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line
** on the command prompt, use <code>e2fsck -p -f /dev/sda4</code>
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''Linux/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/sda2'' to <code>root=/dev/sda4</code>
** start Linux again
:: This will run Linux on the original partition.

If this doesn't fix your issue, you need to replace the SSD with a new one, re-install the LAP and any applications and restore your backups.

<internal>
Internal: How to recover from a disk-is-full Condition: [http://wiki-intern.innovaphone.com/index.php?title=Reporting#Vergr.C3.B6.C3.9Fern_der_Partition_.28VM.29]
</internal>

== Related Articles ==
* [[Howto:Convert a V10 LinuxAP to VHDX to run on Hyper-V]]
* [[Howto:Extend V10 LinuxAP HDD Size (VM)]]
* [[Howto:Tested_mSata_modules]]
* [[Howto:MSATA Placement]]

[[Category:Concept|Linux Application Platform]]

Howto:IQM Statistical CSV Data for Agent and Queue

2019-08-27T08:04:59Z

Odawid: /* More information */

In previous releases (before build 80160) the iQM server did a data logging using Excel sheets. While this method has the great advantage that the output is a ready to use Excel Chart including formulas, front pages and different sheets there are also some limitations. For example it is very difficult support all kind of OS and all kind of Excel and Office Versions on the iQM Server while the real typically is done on “normal” PC´s where Excel is installed.

Therefore the Data logging is done writing data in a CSV format. This format can be natively loaded from Excel. The difference is that there are no single sheets for days, but all data are of a month in one single Excel Sheet. Also Formulas or filter if required can be added, but there are not included in the source file.

==Applies To==
This information applies to

iQM Build 80160 or higher

Excel is not required on the iQM Server



==More information==
QM provide two type of statistical data, data regarding individual Agents and data regarding the general status of the WQ. The usage is different: while individual Agent data are used to evaluate the operating of the single Agents, the WQ data are used for resource planning. See more details and explanation in the following chapters.
Statistical data are transmitted via Email to the supervisor automatically (daily or monthly). The can also be requested manually pressing the relative button on the iQM server:

[[image:IQM214.png‎]]

If requested on demand the actual data of today of cause will be just from midnight until the moment of the request. During transmission the relative buttons will shown:

[[image:IQM215.png‎]]

Please note that MS has timeouts in all applications and therefore it could take some time until you will find the statistic in your mailbox.
Note: if in the setup a valid IP-Adress is indicated in the e-mail server (iQM does no control if not) iQM performs a ping check before processing the email. If like in the example the Ping result is negative warning message is displayed, each 20 seconds are done further checks.

[[image:IQM209.png‎]]

The e-mails are buffered (max. 6), also in case of other email error a relative warning message is displayed (and stored in the log file).
Statistical data can also be transmitted automatically each day at midnight and at the end of the month.
Please note that a IQM Server tracks always data form “his” primary WQ while the data of the second WQ and processed by the second iQM Server.

==Files==
Each time a file is send, regardless if automatically or requested by a user, a copy of the original file is stored in a directory created automatically by the iQM server. The directory named “CSV” is a sub-directory where the log files are in.

Example: if Your logfile path is “c:\asdf\“ the CSV data are stored in “c:\asdf\CSV”

Please note that a copy of files is done even if no email address is indicated.

Therefore also a logging without email is possible, just working with files.

As usual it is recommended to work only with the file in the CSV subdirectory and not with the original files in the log directory.

The files stored in the CSV subdirectory and received via email can be opened with any software, in the following examples we open with Excel for further processing.

Please note that the csv files in the logging directory should not be opened and they have a write protection switched on while the files in the CSV subdirectory and the one attached to the emails have no write protection.

Once opened the file could be processed, modified, stored and renamed as you like, see later chapters.

===File Names===

The filename of automatic generated files (typically at the beginning of the month) is the following:

The CSV filename has the format “iQM_SS_L_YYYY_MM_DD_HHMMSS.csv” where:

SS = source (“AG” for agent and “WQ” for Waiting queue”)

L = Labe of the iQM sever

YYYY = Year

MM = month

DD = Day

HHMMSS = hour, minute, second

If a file is send automatically by email the file name of the attached file is “iQM_SS_ll_YYYY_MM.csv”, so no day and timestamp is in the filename.

Examples:

“iQM_AG_MyFinanceGroup_2016_04_18_152709.csv” filename of the file stored in the CSV subdirectory at time 15:27:09.

“iQM_AG_MyFinanceGroup_2016_04.csv” automatic created file attached to the email

“iQM_AG__2016_04_000009.csv” filename of the file stored in the CSV subdirectory. Note that there is no label in this example and the 00:00:09 indicated that this file was stored automatically at midnight at the end of the month.

===e-mail format===

The email shows in the object field the type and source of the Statistic in the format iQM-Report, “AG” for the Agent Statistics and “WQ” for the Waiting queue Statistic. On top the name of the iQM server is in the object, usefully if more iQM are operating.

Example of email Subject:

“iQM-Report Statistic WQ MyFinanceGroup” data of the Waiting Queue of the iQM Server “MyFinanceGroup”

iQM-Report Statistic AG MyFinanceGroup” data of the Agent of the iQM Server “MyFinanceGroup”

The e-mail body shows the source path of the attached file and name of the attached file.

Example for email body:

C:\asdf\iQM_AG_Myxlabel_2016_04.csv
Automatic generated report - Do NOT answer!

The CSV Data Files are attached in the mail.

===Manual data dump===

If a statistic File is dumped (requested) manually the data are partial. If for example Agent data are requested in day 6.12 at 14:00, data will be complete for the days 1-6, but data of the day 6 are just logged from 00:00 to 14:00. Similar happens to the queue data: if a request is done at 12:35 the quarterly hour from 12:30 to 12:45 will contain partial data.

Note: In agent data, where for each day a line for each agent is stored, a manual dump cause double lines in the day where the system starts up the very first time. On further days this will not happen.

Example:

“iQM_AG_MyFinanceGroup_2016_04_18_152709.csv” indicate that the request was done day 18, hour 15:27:09

In the Queue Table the minute of the snapshot is indicated:

[[image:iQMcsv01.png‎]]

In the example the data dump was done at 15:33 and therefore line 4 contains partial data.

==Excel Import==

The CSV Data can be imported in Excel, the CSV character is semi column (“;”).

===Agent Data===

The headline (localized, in all examples in English) indicates the following columns:

[[image:IQM_N_14.png‎]]

A: Day of month

B: Month

C: Name of Agent. Numbers in a line regards this single agent: a call is counted as such if the phone of the agent rings, not if a call is in the queue.

D: Number of incoming calls. If in the setup of the iQM server is flagged “log only calls from WQ” just incoming calls form the Waiting Queue are counted: if not checked all calls (even if not from the Waiting Queue) are counted.

E: Number of outgoing calls

F: Time in seconds of the phone in ringing status. You can calculate the average time of answer for this agent divide this value with the number of calls in (F/D). If in the setup of the iQM server is flagged “log only calls from WQ” just incoming calls form the Waiting Queue are counted: if not checked all calls (even if not from the Waiting Queue) are counted.

G: Number of abandoned calls = calls not answered while the agent phone rings. This means that the phone has to ring and the agent did not answer. If a caller gives up during the queuing in the Waiting queue (ando no Phone is ringing) this is not counted. Note that the abandoned calls counter in the iQM Server (that count abandoned calls in any situation) cannot be compared with this counter.

H: Conversation time in seconds for incoming calls.If in the setup of the iQM server is flagged “log only calls from WQ” just incoming calls form the Waiting Queue are counted: if not checked all calls (even if not from the Waiting Queue) are counted.

I: Conversation time in seconds of outgoing calls. Outgoing calls are all calls done in a active mode (so even internal active calls)

J: Wrap up Time in seconds. Shows how long a Agent was in the wrap up status.

K: Time in seconds being in Group, shows how long a Agent was logged in the group.

L: Number of threshold overflow. Each time the phone rings longer than the seconds indicated in the iQM Setup “Ring TH” (the agent phone is ringing longer than) this counter is increased.

Description Example (assuming that in the setup “only calls from Waiting Queue” is flagged).

The Phone of Agent Valentina (line 3) in day 19 October (the year is indicated in the filename) rings 14 times for calls coming from the WQ, 4 times longer than 10 Seconds before answering the call. 3 calls where not answered unless the phone rings, the total time of phone ringing was 72 seconds, the conversation time for the incoming calls 154 seconds. The Agent was 70 seconds in wrap up and logged in the group 11884 seconds. Valentina did 1 outgoing call speaking 36 seconds.

Please note that the format of the counters is generally well done, for example the value “month” is in two digit format (in the example “04”): but the view in Excel depends on the setup of your Excel sheet.

====Loggin rules====

The following rules regard the iQM statistics for second’s calls. A “second call” is a call done from agent while the first call is on hold. A typical situation is a consultation with another extension.

Please note that an outgoing call is a call from the agent to a destination, regardless if the called number is, from the PBX point of view, an extension or an external destination.

Observe also that the iQM is not a reporting and the following described rules can cause different counter status if compared. While a reporting is simple tracing each call as an independent event the iQM statistics follow a callcenter logic. If the independent call counting is requested simple use the reporting tool.

'''1. incoming call'''

When the incoming call comes in the queue statistic incoming call counter is increased, if the agent answers the agent incoming call counter; a timestamp for call duration is saved.

If the agent put this first call on hold and is doing an outgoing call the agent client will show the second number while a timestamp for the second call is saved.
The agent talks with the second destination and transfers the call. In the Queue Statistic the call transfer counter is increased. In the agent statistic the outgoing call counter is not increased, the entire call duration is booked on the incoming call duration timer.

The same behaviour is given if the call is transferred without consultation (the agent just transfer the call without waiting that the far destination answers the call).
The wrap up will trigger when the call is transferred.

If the agent transfers the call to the Waiting Queue the call duration will continue to count on that agent until the call is answered. Please note that the client will show the pending call. If group wrap up is on the agent will not be logged in the group until the call is answered or the agent picks up the phone, then wrap up will trigger. If queue wrap up in switched on wrap up will trigger, after the wrap up the call is offered again to the agent.

A second option is that the agent releases the second call and speaks again with the first original incoming call. The outgoing call counter is increased when the agent releases the second call and the outgoing call duration is increased using the timestamp of the second call. Please note that the client will show the second number until the call is terminated. Wrap up will trigger at the end of the call.

A third option is that the agent toggles between the two calls and release the first (the incoming) call.

The wrap up will just trigger when the second call is released. The outgoing call counter is not increased; the entire call duration is assigned to the incoming call.
If the first incoming caller releases while the agent is in conversation with the second outgoing call the entire call is considered as incoming, the total time amount is booked on the incoming call and the outgoing call counter is not increased.

'''2. Outgoing call'''
All operation described before are possible also doing as first call an outgoing call, then put that call on hold and do a second outgoing call. Outgoing calls without involvement of the waiting queue will not cause any wrap up.

In case of an Call transfer there is just one call add in the statistic, the entire call duration is add to the outgoing call duration.

If the second call is released the outgoing counter is increased, so when the agent released two outgoing calls are counted. The entire call duration is added.

If the agent toggles between the calls the display on the client will not follow but showing always the second call. If the agent releases the first call the counter of outgoing call will not be increased while the entire call duration is added to the outgoing call duration timer.

If the first called user releases while the agent is in conversation with the second outgoing call the entire call is considered as one single outgoing call, the total time amount is booked on the outgoing time counter.

'''3. Short Calls'''

In the iQM Setup it is possible to set a minimum duration time in seconds. Calls shorter that the seconds defines are not logged in the missed call list of the agent. Calls also not are considered as valid calls for the statistic. Please note that short calls are not counted in the statistics if:

- The ringing time is shorter the the threshold and the agent will not answer.

- The ringing time is shorter that e threshold, the agent answer the call but the conversation time is shorter than the threshold. This is valid independently if the caller or the agent releases the call.

Please note that the reporting tool will not track very short calls (<=1 second) while a threshold in the iQM could cause that the reporting reports the call while the iQM will not.

Please note also that the counter of the waiting queue are not affected by this filter option, therefore the queue counter will count all calls, even the short one.

====Formulas====

Being native Excel sheets any type of formulas (for example sums) can be added and also Filter can be applied with a few klick (marking all and adding “Filter”).

In the Excel format there are some columns not available automatically in the CSV logging, but it is easy to add a column with the relative formulas.

Here some example for additional formulas:

Time in Minutes = time in Seconds / 60

Average Time to Answer = F: Time to answer in seconds / D: Number of incoming calls

Average duration of incoming calls = H: Conversation time in seconds of incoming calls / D: Number of incoming calls

Average duration of outgoing calls = I: Conversation time in seconds of outgoing calls / E: Number of outgoing calls

Average duration of calls = (H: Conversation time in seconds of incoming calls + I: Conversation time in seconds of outgoing calls) / ( D: Number of incoming calls + E: Number of outgoing calls)

===Queue Data===

Queue Data are data regarding the waiting Queue and the group of agents, not single agents.For example there is no difference for a call being queued or ringing on a phone.

Queue data are stored in 15 Minutes intervals. Therefore each hour has 4 entries: 00, 15, 30 and 45. Please note that always the past quarter is indicated. For example in “10:00” are data from 09:45 to 10:00, in “10:15” are in data from “10:00” to “10:15”.

If a queue report is requested manually an odd timestamp will appear (for example “10:04”) indicating the snapshot time for the current quarter.

The headline (localized, in the example in English) indicates the following columns:

[[image:IQM_N_15.png‎]]

A: Day of month

B: Month

C: Hour

D: Minute

E: Number of incoming calls on the Waiting Queue

F: Number of abandoned calls (in any situation)

G: Percentage of served calls (calls answered)

H: Percentage of abandoned calls (calls not answered)

I: Waiting time in seconds = total waiting time of calls in the waiting queue

J: Number of agents logged in the group (Agent Group)

K: Number of transferred calls: If an Agent does not terminate the call but is doing a call transfer this counter is incremented.

L: Peak call duration in seconds = longest waiting time

M: Average Waiting time of calls in seconds (I/E)

N: Number of threshold overflow. Each time a calls waits longer than the seconds indicated in the iQM Setup “Waiting TH” this counter is increased.

O: Number of active calls done from the agents (Build 80178)

In the time frame from 16:30 to 16:45 the 19 October (the year is indicated in the filename) 10 calls came in to the Waiting Queue, 2 calls where not served (abandoned), so 80% of the calls are served while 20% not. The total waiting time of those 10 calls was 167 seconds, at 16:30 there where 2 Agents logged into the group. 1 call was transferred to other destinations while 9 calls served from the Agent. The Peak Waiting time in this period was 36 seconds, the average waiting time 17 seconds. One time a call waits longer than 30 seconds. The Agents did 2 outgoing calls in this time frame.

Please note that all columns refer to the waiting queue except column O: this column shows the number of outgoing calls of the agents during the quarter hour timeframe. This value is interesting to evaluate the activity of the call enter during the timeframe.

===Known Problems===
Some customer wants additional columns (for example adding two cells or doing other type of mathematical calculation), hiding columns, modify header, using filter and similar. In Excel all that is very simple and can be done in an automatic mode with one click. This Wiki is not a Excel tutorial, anyway some hint you can find here:

[[ Howto:IQM_Server#Data_processing | Howto:IQM_Server#Data_processing]]



==Related Articles==

[[Howto:IQM_Statistical_Excel_Data_for_Agent_and_Queue]]

[[Howto:Queue_Monitor_-_Overview]]

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

Howto:PHP based Update Server V2

2018-08-14T11:41:54Z

Odawid: /* Configuration */

==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 Manager]] mechanism reads a file that corresponds to the device type (e.g. <code>update-ip222.htm</code>). 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 (build 2006 and up). 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 [[Reference10:Concept Linux Application Platform | 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 certificate (MTLS)
* maintain a list of devices in your installation along with some vital information about each individual device

=== Installation ===

==== On the Linux Application Platform ====
Here is how you would install it on the [[Reference10:Concept_Linux_Application_Platform|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. [https://winscp.net/eng/index.php WinSCP] (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]]). Note that you must use SFTP rather than WebDAV, as WebDAV will not give access to the executable web server files
* create a new root directory underneath <code>/var/www/innovaphone/mtls</code>, e.g. <code>/var/www/innovaphone/mtls/update</code>
* download the complete file package of scripts and files here: http://download.innovaphone.com/ice/wiki-src/
* copy all files and directories in to this new directory
* change owner and group of all files and directories to <code>www-data</code>, change mode to 0600 for all files and 0700 for all directories (see [[#Migrating_from_build_2000_an_newer | below]] for how to do this with WinSCP)

* 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]]) and open 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 <code>update</code>):
** <code>/mtls/update</code>
** <code>/mtls/update/web</code>
** <code>/mtls/update/admin</code>
** <code>/mtls/update/fw/</code> (note the trailing slash!)
: make sure that no other sub-directories of ''update'' are listed
: make sure you have no trailing '/' in any of these paths (except ''fw/')
: this will make sure the update server's admin user interface is not accessible to the public

At this point, you should be able to access the update server's admin user interface, e.g. <code>http://update.yourcompany.com/mtls/update/admin/admin.php</code>. However, the only thing you see is a login page. Please note that your browser should ask you for a password for this page (unless you already entered it before). Cookies must be enabled for the login page to work properly.

===== If you want to provide HTTPS Acess to the Update Server =====
For HTTPS access to the update server, you may want to install your own server certificate under ''Administration/Certificates/Current server certificate''. However, this is not strictly required (you will experience some warning messages when using your browser to access the update server, however, calling devices will work just fine).

===== If you want to setup MTLS-restricted Delivery of Update Scripts =====
If you think you have sensitive information in your update scripts, you should make sure to deliver such scripts to your own verified devices only. This can be done by authenticating calling devices with ''mutual TLS'' (MTLS). In this case, the calling device must use HTTPS to retrieve the update script and present a trusted client certificate that identifies itself as the calling device (that is, has the device serial as the certificate's ''common name'' (CN)).

For this feature, you need to ''Configure mutual TLS'' in the LAP's ''Administration/Web Server'' panel. Simply tick the ''Active'' check-mark and select an appropriate ''MTLS Port''. The port must not conflict with any other TCP port used on the LAP, so neither 80 nor 443 is a good choice. 444 is a good choice. Although it [http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?&page=8 is assigned to the snpp protocol] by IANA, it is not used by the LAP (and probably rarely used anyway).

If MTLS is already activated on your LAP, simply take note of the currently configured ''MTLS Port''.

 
Please note that MTLS access is ''not possible'' through a ''reverse proxy'' (RP). This is because the RP always will terminate the incoming TLS connection and establish its own to the target. Therefore, the client certificate presented to the target server is the RP's certificate, not the original clients certificate. In our context - where MTLS is used to verify the identity of the original caller - clients must not access the update server through an RP.

You can either expose your update server directly to the internet (and carefully think through the security implications) or create specific TCP port forwarding towards the update server in your NAT-router/firewall. In this case, we recommend to use non-standard HTTP and HTTPS ports on the NAT router (cause this will already keep most of the HTTP port scanners out there in the internet from functioning).

 
Also, you will need the public key of all the CAs you will trust. These must be configured in to the web server so it can trust the certificates your devices will present to it. See [[#Enforcing_Trust]] for details.

==== On an Apache Server running on the Windows Operating System ====
The update server will run on Apache too. However, as we did not test this setup thoroughly, we recommend to use the LAP's LigHTTPD instead.

* For hints on using MTLS on an Apache Web Server, see [[Reference10:Concept_Provisioning#Enforcing_mutual_TLS_on_Apache | Enforcing mutual TLS on Apache]]
* For hints on getting the ''innovaphone device certificate authority'' public keys (which you may or may not need), see [[Reference10:Concept_Provisioning#How_to_get_inno-dev-ca-certificate.crt | How to get inno-dev-ca-certificate.crt ]]

==== On Microsoft's IIS ====
We do not recommend to use IIS as
* it does not support PUT easily
* it is not compatible with the innovaphone device's MTLS implementation

===Configuration===

If you intend to deliver your update scripts with MTLS (that is, with HTTPS and 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 <code>-----BEGIN CERTIFICATE-----</code>)

Also, you need to know the ''MTLS Port'' configured in your LAP (see [[#If_you_want_to_setup_MTLS-restricted_Delivery_of_Update_Scripts| If you want to setup MTLS-restricted Delivery of Update Scripts ]] above).

All tweakable parameters are set in <code>user-config.xml</code>. You may want to use an XML-capable editor such as notepad++, netbeans or Visual-Studio for editing. if your editor supports it, you benefit from the ''document type description'' (DTD) provided in <code>full-config.dtd</code>.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config debugmerge="false" debugcerts="false" debugscript="false">
</config>
</code>

The attributes of the <code>config</code> tag control some aspects of debugging. For now, simply set all 3 to <code>"true"</code> instead of <code>"false"</code>. Do not forget to revert them back to <code>"false"</code> when everything runs smoothly, large log files will result if not.

==== Securing Access ====
To control access to the update server's data, you should set a login. This can be done in the ''master'' tag by specifying both ''user'' and ''password'':

<code xml>
<master ... user="myadmin" password="mysecret"/>
</code>
Default username and password are admin/password.

==== Delivering Firmware and Boot Code ====
At this point, you can simulate a device by requesting an update script using an URL like <code>http://update.yourcompany.com/mtls/update/update.php?type=IP232&sn=00-90-33-00-00-00&hwid=IP232-00-00-00&ip=1.2.3.4</code> in your browser (please note that this URL should not ask you for a password). Most likely, your browser will wait a little while and then say something like:

...
# failed to use cached data (cache not current), retrieving info online
# cannot get PBX info: cannot access http://yourmasterdevice.youdomain.tld/CMD0/box_info.xml, reading cache
# cannot get cached PBX info: cannot access cache/master-info.xml - exit

This is because you did not yet specify the ''master device'' which always runs the reference firmware.

The idea here is that you have one innovaphone device in your system where the firmware is always manually updated. All other devices shall follow this reference firmware. The update server will deliver the firmware that runs on the master device to calling devices. For this to work, you need to set the ''info'' attribute of the [[#master|''master'']] tag and leave everything else ''as is''.

Remember that you do all your local configuration changes in <code>user-config.xml</code>.

As ''master'' is a first level tag, you can add it directly underneath the opening ''<config>'' tag. The only thing we need to define right now is the path to read the firmware information from your master device. Let's say your reference device has the IP address <code>172.16.0.10</code>, you end up with

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config debugmerge="true" debugcerts="true" debugscript="true">
<master info="http://172.16.0.10/CMD0/box_info.xml" user="myadmin" password="mysecret"/>
</config>
</code>
(you could use a DNS name instead of the IP address of course).
The ''info'' URL is used by the update server itself only, it is never used by devices requesting an update script.

When you refresh the page that simulates a device requesting an update script, the output should now change to something like

...
# failed to use cached data (cache not current), retrieving info online
# current firmware (unknown) does not match required firmware (130178)
...

This is to say that your master device runs firmware 130178 and the calling device does not (actually, as the calling client is simulated by your browser, it does not transmit its current firmware to the update server so it is ''(unknown)'').

In order to actually update the clients with firmware and boot code, the files must be made available to the calling client somehow. This is done by specifying an URL in the [[Reference10:Concept_Update_Server#Prot_command | prot ]] and [[Reference10:Concept_Update_Server#Boot_command | boot ]] commands sent to the calling device:

...
# current firmware (unknown) does not match required firmware (130178)
mod cmd UP0 prot http://update.yourcompany.com/mtls/update/fw/130178/ ser 130178
# current boot code (unknown) does not match required boot code (130112)
mod cmd UP0 boot http://update.yourcompany.com/mtls/update/fw/130112/ ser 130112
...

By default, the URL generated points to a sub-directory of your update server called ''fw'': <code>http://update.yourcompany.com/mtls/update/fw/130178/</code>. Note that this default URL expects sub-directories underneath the ''fw'' directory which correspond to the firmware and boot code build number. The file structure thus would be like

/var/www/innovaphone/mtls/update/fw
/130178
/ip232.bin
/130112
/boot232.bin

Note that the URL ends with a slash (<code>/</code>). This instructs the calling device to append the appropriate file name itself when retrieving the file (see [[Reference10:Concept_Update_Server#Prot_command | the prot command ]] for details).

However, you can also specify any other URL by setting the ''url'' attribute in the ''fwstorage'' tag of your <code>user-config.xml</code>. In this attribute, certain meta words will be replaced (see [[#fwstorage | the ''fwstorage'' tag ]] for details). The default setting for example is <code>fw/{build}/</code>.

You can disable firmware and boot code updates altogether by setting the ''info'' attribute in the ''master'' tag to an empty value.

==== Your own Update Script Files ====
The update server will deliver update scripts to calling devices which are synthesized from a number of ''update script snippets'' which you define yourself. The idea is that many devices share parts of their configuration while other parts are different. This depends on
* the device ''class'' (e.g. a phone or a gateway)
: the device class is automatically derived from its model. In fact, a single device may be in multiple classes. For example, an IP232 is in these classes: ''phone, pre_opus_phone, phone_newui'' which basically says that its a phone and has no OPUS codec yet but a "new" user interface (as opposed to the old one found e.g. on an IP110). A number of useful classes are pre-defined, but you can add your own in <code>user-config.xml</code>.
* the device's environment (e.g. ''home-office'', ''branch-office'')
: These reflect that fact that devices may need different configuration if they are in different locations (or environments). The update server does not know about a device's environment, which is why you need to configure it in to the devices update URL if you need this. By default, there is a single environment defined called ''default'', but of course, you can add your own
* phase
: configuring devices may need multiple phases to go through. If more than one phase is defined, the device will go through all phases sequentially, which is why a ''phase'' has a numerical ''seq'' attribute. Phases are went through in order of this attribute. When the device has reached the last phase, it will stay there. By default, there is only one phase called ''update''

You can define update script snippets for any combination of device, environment and phase. You do so simply by placing appropriate files in to the ''scripts'' directory on your update server.

Let's have a closer look at the web page we used to simulate a device calling for an update script before (<code>http://update.yourcompany.com/mtls/update/update.php?type=IP232&sn=00-90-33-00-00-00&hwid=IP232-00-00-00&ip=1.2.3.4</code>). It will show you all the possible files it would deliver to the device:

# possible files (from scripts):
# scripts/update-all-00_90_33_00_00_00.txt does not exist
# scripts/update-all-default.txt does not exist
# scripts/update-phone-00_90_33_00_00_00.txt does not exist
# scripts/update-phone-default.txt does not exist
# scripts/update-pre_opus_phone-00_90_33_00_00_00.txt does not exist
# scripts/update-pre_opus_phone-default.txt does not exist
# scripts/update-phone_newui-00_90_33_00_00_00.txt does not exist
# scripts/update-phone_newui-default.txt does not exist

The update script snippet files need to have proper names to define when they should be delivered. As you can see, they all start with <code>update-</code> which means that they apply to devices which are in the ''update'' phase. As by default there is only a single phase defined, all possible file names start with <code>update-</code>.

The next part here is either <code>phone-</code>, <code>pre_opus_phone-</code>, <code>phone_newui-</code> or <code>all-</code>. This is because the calling IP232 is in three classes, so all respective snippets will be delivered to it. ''all'' however is a wild-card. That is, such files will be delivered to all devices, no matter what class they are in. You may wonder why there was no ''all'' for the phase. This is because there is only a single phase defined. If there would be more, the ''all''-variation of the phase-part of the file name would be appear.

The third part finally is either <code>default</code> or <code>00_90_33_00_00_00</code> in our case. ''default'' is the name of the only ''environment'' that is defined by default. ''00_90_33_00_00_00'' is the device's serial number which is treated as an implicitly defined environment name. This allows you to deliver certain snippets to a single device only.

Now let's create an update script snippet that is delivered to all phones in the default environment when they are in the update phase. The file name (which looks like ''phase''<code>-</code>''class''<code>-</code>''environment''<code>.txt</code>) has to be <code>update-phone-default.txt</code> therefore. Just for an exercise, let us set the device name (as shown in the browser's title bar) to ''This is a Phone!''.
The command to do so is <code>config add CMD0 /name This+is+a+Phone%21</code>, so your file may look like this

# set the device name
config add CMD0 /name This+is+a+Phone%21

(btw: did you observe that config line arguments need to be url-encoded?). Now create the file and upload it in to the ''scripts'' directory of you update server. When you now refresh the page which simulates the device calling for an update script, you will see something like this:

...
# newest script (scripts/update-phone-default.txt) 11s old
# files being updated (scripts/update-phone-default.txt 11s old, waiting for at least 90s to expire)

When you update multiple script snippets, it is often undesirable that a device retrieves an inconsistent state of the scripts you are working on (e.g. if you already have saved one but not yet the other). To avoid this, the update server will look at the files modification dates and if one of those that needs to be delivered to the device is younger than 90 seconds, it will not send any of them at all.

So when you wait for the 90 seconds to pass and refresh the page again, you will see something like this:

# firmware build info cache is current
# phase: update, nextphase: , environment: default, type: IP232, classes: phone+pre_opus_phone+phone_newui
# possible files (from scripts):
...
# scripts/update-phone-default.txt 4.1 mins
...
# scripts/update-phone-default.txt
# { begin script 'scripts/update-phone-default.txt'
# set the device name
config add CMD0 /name This+is+a+Phone%21

# end script 'scripts/update-phone-default.txt' }

# trigger reset if required
config write
config activate
iresetn

As you can see, your snippet has been delivered by the update script. However, the update server has also added some trailing commands which write back the config to the devices flash memory (<code>config write</code>), activate it (<code>config activate</code>) and trigger a reset if needed (<code>iresetn</code>).

If there are multiple snippets available for a calling device, all of them are concatenated in the sequence shown in the header of the returned script (where the possible file names are listed)

==== Device Status ====
When you have a lot of devices which are served by the update server, you may want to have a list of these devices along with some useful information regarding each devices.

You can enable this by defining the ''status'' tag in your <code>user-config.xml</code>. So open the file and add the tag right next to the ''master'' tag you added before:

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config>
<master info="http://172.16.0.10/CMD0/box_info.xml"/>
<status
dir="status"
/>
</config>
</code>

When you have done so, please refresh the page that simulates your calling device and then open <code>http://update.yourcompany.com/mtls/update/admin/admin.php?mode=status</code>. You will now see a device list (well, a list with a single device, the one you simulated using your browser). The list will show some information regarding the devices that requested an update script lately. For more options, see [[#status]].

==== Device Backup ====
It is generally useful to have recent backups of all of your device configurations. The update server supports that if you enable it by defining the ''backup'' tag in your <code>user-config.xml</code>. Simply put it right next to the ''master'' or ''status'' tag you added before:

<code xml>
...
<backup
dir="backup"
/>
</code>

If you have done so and then refresh the page that simulates your calling device, you will now see

...
# scripts/update-phone_newui-default.txt does not exist

mod cmd UP0 scfg http://update.yourcompany.com/mtls/update/update.php?mode=backup&hwid=#h&sn=#m

instead of

...
# scripts/update-phone_newui-default.txt does not exist

# Backups not enabled in config

When a client requests an update script the next time, this will initiate a configuration backup which is stored underneath the ''backup'' directory. For each device, a sub-directory is created and all backup files are stored therein. By default, the last 10 differing configuration backups are kept.

==== Controlling the Time-frames when Snippets are delivered ====
The update client built-in to innovaphone devices allows to restrict updates to certain time frames (e.g. only during the night). This can be controlled using the [[Reference10:Concept_Update_Server#Times_command | times ]] command.

You can configure the update server to use the time commands by setting the ''allow'' and ''initial'' attributes in the ''times'' tag in your <code>user-config.xml</code>.

<code xml>
<times
allow="22,23,0,1,2,3,4"
initial="1"/>
</code>

If either the ''allow'' or ''initial'' attribute is present, the update script will contain a line like

...
# Restricted times
mod cmd UP1 times /allow 22,23,0,1,2,3,4 /initial 1

In the example above, all update script activity will occur only between 10pm and 5am (local device time). For more details, see [[Reference10:Concept_Update_Server#Times_command | Concept Update Server]]

==== Using and Enforcing HTTPS ====
Your devices can either use HTTP or HTTPS to access the update server. In normal operation, the update server will generate URLs (e.g. the URLs used to retrieve firmware or to backup configurations) for the same protocol.

However, you can enforce use of HTTPS by setting the ''forcehttps'' attribute in the [[Howto:PHP_based_Update_Server_V2#times | ''times'' ]] tag to <code>true</code>. If so, a device calling in with HTTP will be re-configured to use HTTPS:

...
# using HTTP and 'forcehttps' is set -> need to switch to HTTPS

# changed state query args: polling, phase
# new url=https://update.yourcompany.com/mtls/update/update.php?polling=5&phase=&type=#t&sn=#m&hwid=#h&ip=#i
...
(note that if you are using a non-standard port for HTTPS, you must define it using the ''httpsport'' attribute).

==== Delivering Custom Certificates ====
innovaphone devices come with pre-defined, trustworthy device certificates. However, all ''soft'' devices (such as the softwarephone, myPBX for Android/iOS or the IPVA) do not. Also, in many scenarios customers run their own ''public key infrastructure'' (PKI) and request their own certificates to be used instead of the pre-defined. This is why there is a need to roll-out custom certificates to devices.

The update server supports this task to an extend. It can
* check if a calling device has a proper certificate
* instruct a calling device without proper certificate to create a ''certificate signing request'' (CSR)
* download the CSR to the update server for easy access by the administrator
* upload a signed CSR to the device
* upload the public key(s) of the CA in to the device's trust list

In order to roll-out custom certificates with the update server, the administrator needs to
* run his own PKI (a.k.a. ''certificate authority'' (CA))
* monitor CSRs that appear in the update server's device list
* approve the request by manually submitting it to his own CA
* upload the signed CSR to the update server

Also, all devices must run ''V12r1 SR8'' or newer before the new certificate can be uploaded. Devices with older firmware will be updated automatically (see [[#Delivering_Firmware_and_Boot_Code]] above). However, the new firmware must be ''V12r1 SR8'' or later.

To learn how you can create proper device certificates with your own windows CA, see [[Howto:Creating custom Certificates using a Windows Certificate Authority]].

By default, custom certificates are turned off and you will see a note like

# certificates: either certificate handling or state tracking not enabled - not doing any certificate checking

in the delivered update script.

Custom certificates are turned on by adding a ''customcerts'' tag to your <code>user-config.xml</code>:

<code xml>
...
<customcerts
dir="certs"
/>
...
</code>

The the page that simulates your calling device will now include a line saying:

# certificates: we dont know anything about the current certificate state - not doing any certificate checking

In order to decide if or if not a calling device has a valid certificate, the device needs to send its current public key to the update server. This is done by enabling ''queries'' in your <code>user-config.xml</code>. ''Queries'' is a means to have the device submit certain information to the update server. In the update server's default configuration, two queries are defined but not enabled:

* the query ''certificates'' sends the current certificate state
* the query ''admin'' sends the current device name (as set in ''General/Admin'')

To enable a query, you must specify the class a calling device must be in in order to execute the query. This is done by adding an ''applies'' tag for the respective query in your configuration:

<code xml>
...
<queries>
<query id="admin">
<applies>*</applies>
</query>
<query id="certificates">
<applies>*</applies>
</query>
</queries>
...
</code>

This basically says that both queries should be executed by devices of just any class. Unless you enable queries, your update script will include lines such as:

# no queries defined for any of callers classes: phone+pre_opus_phone+phone_newui

Once you have enabled them, you will see something like

...
# query 'certificates'
mod cmd UP0 scfg https://update.yourcompany.com/mtls/update/update.php?mode=query&sn=#m&id=certificates ser nop /always mod%20cmd%20X509%20xml-info
# query 'admin'
mod cmd UP0 scfg https://update.yourcompany.com/mtls/update/update.php?mode=query&sn=#m&id=admin ser nop /always mod%20cmd%20CMD0%20xml-info
...

You can display the data sent by a query in the device status display. To do so, you need to define one or more ''show'' tags as part of the respective ''query'' tag:

<code xml>
...
<query id="certificates">
<applies>*</applies>

<show title="Subject">/state/queries/certificates/info/servercert/certificate/@subject_cn</show>
<show title="Issuer">/state/queries/certificates/info/servercert/certificate/@issuer_cn</show>
</query>
...
</code>

Two steps however are still missing:

* a) you need to tell the update server the names of all the CAs you consider trustworthy. This is done by listing their names in the ''CAname'' attribute of the ''customcerts'' tag:

<code xml>
...
<customcerts
dir="certs"
CAname="innovaphone Device Certification Authority,innovaphone Device Certification Authority 2,innovaphone-INNO-DC-W2K8-Zertifizierungsserver"
/>
...
</code>

: The example shown defines that you will accept both of innovaphone's device certificate authorities and also your own CA called ''innovaphone-INNO-DC-W2K8-Zertifizierungsserver''. Devices with device certificates issued by one of these CAs will be left untouched. For all other devices (for example, any ''myPBX for Android/iOS'' device that has a self-signed certificate), the generation of a custom certificate will be initiated.

* And b) you need to provide the public key of your CA (so it can be uploaded to the calling device's trust list). You need to place the DER (not PEM) encoded public key in to a file called <code>certs/CAkey-01.cer</code> on your update server (if you want to upload the whole certificate chain, put all of the public keys in the chain in to separate additional files called <code>certs/CAkey-02.cer</code> and so forth.

For more details on how to approve certificate signing requests, see [[#Approving Certificate Signing Requests]] below.

==== Enforcing Trust ====
Update script snippets may include sensitive information which you do not want to disclose to the public. Even though you can force the use of HTTPS (see above), this still does not keep your data secure. After all, an attacker could simply request an update script from your update server using HTTPS. To secure your data, you need to make sure that snippets are only sent to devices which identify themselves using a trusted certificate with a correct ''common name'' (CN). This is done using ''mutual transport layer security'' (MTLS). Therefore, you need to configure MTLS in the LAP (see [[#If_you_want_to_setup_MTLS-restricted_Delivery_of_Update_Scripts | If you want to setup MTLS-restricted Delivery of Update Scripts]] above).

You can enable this by setting ''forcetrust'' to <code>true</code> and ''httpsport'' to the port configured as ''MTLS Port'' in your web server. This is done in the ''times'' tag of your <code>user-config.xml</code>.
<code xml>
<times
...
forcehttps="true"
httpsport="444"
forcetrust="true"
/>
</code>
Please note that ''forcetrust'' does nothing unless ''forcehttps'' is also set!

If so, the update server will deliver update script snippets only to clients which identify themselves with a proper certificate. For this to work, you will need to add the public key of your certificate authority to your web server's list of trusted certificates.

When using the ''Linux Application Platform'' (LAP), you need to add the PEM-encoded public key of your certificate authority to the ''innovaphone-ca.pem'' file in <code>/home/root/ssl_cert</code>. When you have installed the LAP, this file will contain the PEM-encoded public keys of the 2 innovaphone device certificate authorities. You can simply add the public key of your CA to the end of this file:

-----BEGIN CERTIFICATE-----
...inno-ca public key...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...inno-ca2 public key...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...your-ca public key...
-----END CERTIFICATE-----

You will need to restart the LigHTTPD then (most easily done by restarting the entire LAP (''Diagnose/Reset'') or by issuing the command <code>/etc/rc2.d/S02lighttpd restart</code> from the linux root command prompt). Finally, you must set the ''forcetrust'' attribute.
(Note that the ''innovaphone-ca.pem'' file may be overwritten when a new LAP version is installed. It is thus a good idea to keep a copy and check it after an upgrade).

When ''forcetrust'' is effective and the calling device does not use HTTPS, it will be reconfigured to do so:

# using HTTP and 'forcehttps' is set -> need to switch to HTTPS
...
# new url=https://update.yourcompany.com:444/update/update.php?polling=5&phase=&type=#t&sn=#m&hwid=#h&ip=#i&env=default

If the calling device uses HTTPS but sends no certificate, you will see a message like

# cannot verify CN with HTTPS: SSL_CLIENT_S_DN_CN not present - fix web server configuration or use MTLS-enabled port!

This is probably because it is using a non-MTLS enabled port for HTTPS (e.g. the standard port 443) although MTLS is configured for a different port.

If the calling device uses HTTPS and sends a certificate but the CN does not match the serial number of the device, you will see a message such as

# Device claims to be 'IP232-30-00-af' but identifies as 'CKL-CELSIUS-W10.innovaphone.sifi' by TLS

If the calling device uses HTTPS and sends a certificate but the certificate is not trusted because its issuer is not listed in ''innovaphone-ca.pem'' (see above), the connection will be refused

In all such cases, no snippet will be delivered. If the certificate is good, you will see a message like

# good certificate(CN='IP232-30-00-af')

followed by the appropriate snippets.

==== Using multiple Phases ====
When you configure multiple phases, all phases up to the final phase are stepped through and when all associated update script snippets for all phases are done, the device will ultimately stay in the final phase. This can be used e.g. to implement update script snippets which are executed once only when the device is initialized. Settings made in all but the last phase can later be overridden by the user or an administrator. The settings done in the update script settings for the final phase however are re-executed whenever one of your update script files for this phase changes.
The process of deploying some initial settings is often called ''staging''.

To enable staging, you therefore create a new phase that comes before the default phase (which is ''update''). Phases are sorted numerical by an attribute called ''seq''. As the default phase ''update'' is defined with ''seq=200'', your new staging phase must be defined with a lower seq value:

<code xml>
...
<phases>
<phase id="staging" seq="100"/>
</phases>
...
</code>

When you define such a phase, there will be new possible update script snippet file names:

# phase: staging, nextphase: update, environment: default, type: IP232, classes: phone+pre_opus_phone+phone_newui
# possible files (from scripts):
# scripts/all-all-00_90_33_30_00_af.txt does not exist
# scripts/all-all-default.txt does not exist
# scripts/all-phone-00_90_33_30_00_af.txt does not exist
# scripts/all-phone-default.txt does not exist
# scripts/all-pre_opus_phone-00_90_33_30_00_af.txt does not exist
# scripts/all-pre_opus_phone-default.txt does not exist
# scripts/all-phone_newui-00_90_33_30_00_af.txt does not exist
# scripts/all-phone_newui-default.txt does not exist
# scripts/staging-all-00_90_33_30_00_af.txt does not exist
# scripts/staging-all-default.txt does not exist
# scripts/staging-phone-00_90_33_30_00_af.txt does not exist
# scripts/staging-phone-default.txt does not exist
# scripts/staging-pre_opus_phone-00_90_33_30_00_af.txt does not exist
# scripts/staging-pre_opus_phone-default.txt does not exist
# scripts/staging-phone_newui-00_90_33_30_00_af.txt does not exist
# scripts/staging-phone_newui-default.txt does not exist

First of all, there are new names for this particular phase. Furthermore, as we now have multiple phases, the new wild-card name ''all'' is possible.

An example for a staging script snippet might be a file called <code>staging-all-all.txt</code>:

# change admin password
config add CMD0 /user admin,my-admin-password
config activate
config rem CMD0 /user

This will set the admin password to <code>my-admin-password</code> during staging (it should be obvious that such staging should only be done in combination with [[#Enforcing_Trust|Enforcing Trust]], see above).

=== A complete <code>user-config.xml</code> Sample ===
Here is a complete sample of a configuration file.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config debugmerge="true">
<master info="http://172.16.0.10/CMD0/box_info.xml"/>
<status
dir="status"
missing="1000"
/>
<backup
dir="backup"
/>
<times
allow="22,23,0,1,2,3,4"
initial="1"
forcehttps="true"
httpsport="444"
forcetrust="true"
/>
<customcerts
dir="certs"
CAname="innovaphone Device Certification Authority,innovaphone Device Certification Authority 2"
CSRsan-dns-1="{name}.company.com"
CSRsan-dns-2="{hwid}.company.com"
CSRsan-dns-3="{rdns}"
CSRsan-ip-1="{realip}"
/>
<phases>
<phase id="staging" seq="100"/>
</phases>
<environments>
<environment id="intranet"/>
<environment id='sifi'>
<implies>intranet</implies>
</environment>
<environment id='berlin'>
<implies>intranet</implies>
</environment>
<environment id='verona'>
<implies>intranet</implies>
</environment>
<environment id='homeoffice'/>
<environment id='mobile'/>
</environments
<queries>
<query id="admin">
<applies>*</applies>
</query>
<query id="certificates">
<applies>*</applies>
<show title="Subject">/state/queries/certificates/info/servercert/certificate/@subject_cn</show>
<show title="Issuer">/state/queries/certificates/info/servercert/certificate/@issuer_cn</show>
</query>
</queries>
</config>
</code>

=== Operation ===

==== Configuring and Debugging a real Device ====
To configure your device for use with the update server, you simply set <code>http://update.yourcompany.com/mtls/update/update.php</code> as ''Command File URL'' in ''Services/Update'' (you can optionally add a <code>?env=envname1,envname2</code> query argument if you want to set one or more specific environments for your device). The update server will re-configure the device later on so that it uses all the required query arguments.

Generally, there are the following methods to set the ''Command File URL''
* configure it manually using the admin GUI
* provide it to the device using DHCP (this will however not work for the softwarephone or ''myPBX for Android/iOS'')
* use the innovaphone provisioning service (see [[Reference10:Concept_Provisioning|Reference10:Concept Provisioning]] for details)

Once the ''Command File URL'' is set on the device, you can debug what the update client in the device does, using the normal trace mechanism. For this, you will want to open the ''Debug'' page (<code>http://x.x.x.x/debug.xml</code>) and set the ''Update/Polling'' and ''Update/Execution'' check-marks. When the update client queries the update server, you will see lines like

0:0826:465:5 - upd_poll: state IDLE -> RECV
0:0826:465:7 - IP.0 -> UPD-POLL.0 : SOCKET_GET_LOCAL_ADDR_RESULT(172.16.100.201,255.255.0.0,0,'',ANY)
0:0826:466:0 - IP.0 -> UPD-POLL.0 : SOCKET_GET_LOCAL_ADDR_RESULT(172.16.100.201,255.255.0.0,0,'',ANY)
0:0826:695:0 - upd_poll: state=RECV sent()
0:0826:752:0 - upd_poll: status 200 headercomplete=1 contentlength=0
0:0826:754:0 - upd_poll: recv_data(2199)
0:0826:754:1 - upd_poll: recv_data(0) EOF
0:0826:754:1 - upd_poll: GET EOF - state=RECV http-status=200 length=2199
0:0826:754:1 - upd_poll: do commands
0:0826:754:1 - upd_poll: state RECV -> EXEC

in the trace. Commands included in the update script will look like

0:0826:754:5 - script::get_line: >line(mod cmd UP0 scfg https://update.yourcompany.com/mtls/update/update.php?mode=backup&hwid=#h&sn=#m)
0:0826:754:5 - upd_poll: pass 'mod cmd UP0 /sync scfg https://update.yourcompany.com/mtls/update/update.php?mode=backup&hwid=#h&sn=#m')

Finally, you do not need to wait for the next time the device decides to contact the update server. Instead, you can force this by sending an <code>http://</code>''your-device-ip<code>/!mod cmd UP1 poll</code> to the device.

==== The Device Status Update Page ====
If status tracking is enabled (see [[#Device_Status | Device Status]] above), the update server will keep a list of devices it knows of. You can see this list by calling <code>http://update.yourcompany.com/mtls/update/admin/admin.php?mode=status</code>.

By default, the list will not be updated unless you refresh the page. However, if you set the ''refresh'' attribute in the ''status'' tag in your ''use-config.xml'' file tp <code>60</code>, all entries in this list will be refreshed every 60 seconds (however, the list itself will not be reloaded, so to see new devices, your need to refresh the entire page). Devices that have not been seen for more than 7 days are shown in a different colour. Devices that have not been seen for longer than 90 days will be silently removed from the list.

===== Filtering =====
From build 2011, you can filter the devices shown using the ''device filter'' field in the ''Device'' column header. The filter string is matched against ip-address, serial number, type, name, phase, class, environment, firmware and bootcode. Also, you can filter by using the keywords ''present'' and ''missing'' (based on the ''missing'' attribute of the ''status'' tag in your configuration file). If one of these attributes match your filter expression, the device is shown.

A filter expression must match a complete ''word''. For example, if you filter by <code>16</code> this would match the ip-address <code>172.</code>16<code>.0.20</code> but it would not match <code>192.</code>16<code>8.0.1</code>.

If you specify multiple filter expressions (separated by white space), only devices which match all of the expressions will be shown. For example, if you filter by <code>172.16. ip222</code> this might match all IP222 in your 172.16.*.* network. Filter expressions are case insensitive.

==== Approving Certificate Signing Requests ====
When you use custom certificate roll-out, you will see a column ''Certificates'' in the device status list, showing the devices certificate status.

[[Image:PHP_based_Update_Server_V2_Device_Status.png]]

If a CSR has been created on the device, this will be available for download in the ''Files'' section of the ''Info'' column. You can submit the CSR to your CA and then upload the signed request (using the ''Upload'' button in the ''Files'' section of the ''Info'' column). The signed request will eventually be uploaded to the device then. On the device itself, the CSR is shown in ''General/Certificates''.

[[Image:PHP_based_Update_Server_V2_CSR.png]]

==== Certificate Errors ====
When a signed certificate request uploaded to the device can not be installed on the device, you will see a message like <code>Certificate upload error - certificate handling stopped</code> in the ''Certificates'' columns for the device. In this case, any further processing will be stopped. Most likely, the reason is that you uploaded the wrong file as signed certificate request (either not a signed certificate at all or a signed request for another device).

In this case
* remove any certificate request from the device
* remove the <code>X509/REQUESTERROR</code> from the device configuration (i.e. <code>vars del X509/REQUESTERROR</code>)
: these 2 steps can be easily done by resetting the device to factory defaults and then set the ''Update URL'' again
* remove any stored files for the device on the update server (shown in the ''Certificates'' column)

The normal process will start all over again then.

=== Migrating old PHP Update Server Installations ===
==== Migrating from build 2000 an newer ====
* Copy all files and folders, '''except''' the ''scripts'' and ''config'' folder, from the source to your destination
* make sure all files and directories have correct owner (''www-data''), group (''www-data'') and mode (''read''/''write'' plus ''execute'' for directories)
: for example, in WinSCP you can use the ''Properties (F9)'' dialogue on the installations root folder:
: [[Image:PHP based Update Server V2-WinSCP-Properties.png]]
* open the ''StatusPage'' and make sure you refresh all cached files in your browser (depending on your browser, this may happen with Ctrl-R or Ctrl-F5)

==== Migrating from build 1011 and older ====
To upgrade from the [http://download.innovaphone.com/ice/wiki-src/index.php?urloffset=php-update-server%2F&name=php-update-server+%28all+available+builds%29&reverselevel=0&maxbuilds=999&root=c%3A%2Finetpub%2Fwwwroot%2Fdownload%2Fice%2Fdownload%2Fp%2Fwiki-src%2Fphp-update-server%2F1010+%28PHP+based+Update+Server+final%29%2F.. old version (builds up to 1011)] of the PHP based update server (as described in [[Howto:PHP based Update Server]]), do the following

* diff your <code>config.xml</code> to the one originally shipped (you can download it at [http://download.innovaphone.com/ice/download/p/wiki-src/php-update-server/1011%20(PHP%20based%20Update%20Server%20final)/php-update-server-1011.zip download.innovaphone.com/ice/wiki-src])
: take note of all the changes you made to it
* install the new version of the update server to a different URL
* configure it according to your needs by modifying <code>user-config.xml</code>. Do not modify the new <code>config.xml</code>!
** apply all modifications you did to your old <code>config.xml</code> to your new <code>user-config.xml</code>
** if you have used a custom setting for fwstorage/@url, you need to change it a bit. Change for example <code>url="http://myfwserver.mycompany.com</code> to <code>http://myfwserver.mycompany.com/{build}/</code> (note the trailing slash!)
* copy all your update script snippet files from the old server (these are all the .txt files in the old server's root directory) to the <code>scripts</code> directory of your new server
* copy the complete <code>fw</code> tree from the old server to the <code>fw</code> directory of your new server
* thoroughly test your new installation with some test devices
* when satisfied, edit <code>update-migrate.php</code> and change the code as described in the comment inside the file
* copy <code>update-migrate.php</code> from the new installation to the old installation
* on one of the devices which are currently served by the old update server, change the ''Command File URL'' so that it points to <code>update-migrate.php</code> instead of <code>update.php</code>. Do not change anything else in the URL. So if it currently is set to e.g.
: <code>https://172.16.0.90/update/update.php?type=#t&env=sifi&polling=0&phase=update</code>, change it to
: <code>https://172.16.0.90/update/update-migrate.php?type=#t&env=sifi&polling=0&phase=update</code>
* verify that this device properly switches to your new installation
** the ''Command File URL'' is changed so that it points to the new installation
** the device shows up in the device status page of your new server

* rename <code>update.php</code> to <code>update-old.php</code> in your old update server
* rename <code>update-migrate.php</code> to <code>update.php</code> in your old update server
* verify that all of your devices start showing up in the new server's status page

=== Complete Parameter Reference ===
Note: attributes are marked with an ''at'' (<code>@</code>) prefix. So ''master/@info'' refers to the ''info'' attribute in the ''master'' tag.

The following tags and attributes are available in the <code>user-config.xml</code> file, their default values are configured in <code>config.xml</code> (which you should not modify):

==== 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 <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''. If you use the literal <code>none</code>, the master device will not be queried
; 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 | ''Installation'' ]] above)
; master/@user : if non-empty, this is the user name required to access the update server's web ui
; master/@password : the password

From build 2009, you can control the firmware and bootcode version to use on update:
; master/@firmware : if set, it may be one of
:: <code>master</code> (default if not set) : the firmware version is derived from the master device
:: <code>none</code> : the firmware update is generally disabled
:: ''build-number'' : the firmware is set to a certain ''build-number'' regardless of the firmware running on the master device
; master/@bootcode: if set, it may be one of
:: <code>master</code> (default if not set) : the bootcode version is derived from the master device
:: <code>firmware</code> : the bootcode version is set to the firmware version. This may be useful if the master device has no bootcode (e.g. the ipva)
:: <code>none</code> : the bootcode update is generally disabled
:: ''build-number'' : the bootcode is set to a certain ''build-number'' regardless of the bootcode running on the master device

<code xml>
<master
info="http://172.16.0.10/CMD0/box_info.xml"
expire="3600"
cache="cache/master-info.xml"
user="myadmin"
password="mysecret"
firmware="4711"
bootcode="firmware"
/>
</code>

==== master/applies ====
Available from build 2009.

Boot code and firmware updates are only executed by devices which match all of the given <applies> conditions. A condition is met if the device belongs to the class that is given as tag content. If the ''env'' attribute is set, the tag content is interpreted as an ''environment'' name which has to match.

; master/applies/@env : if this attribute exists, the tag content is compared with the environments the device is in. Otherwise, it is compared with the classes it is in
<code xml>
<master
info="http://172.16.0.10/CMD0/box_info.xml"
expire="3600"
cache="cache/master-info.xml"
user="myadmin"
password="mysecret"
firmware="4711"
bootcode="firmware">

<applies>phone</applies>
<applies env="">berlin</applies>
</master>
</code>

==== fwstorage ====
Defines from where the device will retrieve the firmware files for updates.
; fwstorage/@url : defines the URL to retrieve the files from. In this URL, the following meta words will be replaced as follows:
:* <code>{build}</code> - the requested firmware or boot-code
:* <code>{model}</code> - the devices type (e.g. <code>IP232</code>). This is derived from the ''type'' query argument used in the update URL which is set to the value <code>#t</code> which in turn is expanded to the [[Reference10:Concept_Update_Server#Scfg_command|''device type'']] of the device requesting the update script
:* <code>{filetype}</code> - the type of the required file, either <code>boot</code> or <code>prot</code>
:* <code>{filename}</code> - (from build 2014) the boot code or firmware filename for the device in lower case. Required if you use the LAP as firmware storage and firmware files are falsely requested in uppercase letters (as URLs on the LAP are case sensitive and if the files are requested with upper case names, the original files with lowercase name are not found). This also allows you to use alternate firmware file names (such as e.g. <code>ip110-sip.bin</code>). See the ''filenames'' tag
Note that if the ''url'' ends with a slash (<code>/</code>), the calling device will automatically [[Reference10:Concept_Update_Server#Prot_command|append the name of the requested file]]. In this case, 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/{build}/</code>), it is treated as a sub-directory underneath the update server's root directory

<code xml>
<fwstorage url="fw/{build}/"/>
</code>

===== Loading firmware files from innovaphone.com =====
You can also load firmware from the innovaphone.com web site. To do so, set ''url'' like so:

<code xml>
<fwstorage url="http://webbuild.innovaphone.com/{build}/"/>
</code>

Please note that ''this is a voluntary service, no guarantee of availability, no service level agreement''.

==== backup ====
Defines where backup files are kept.
; backup/@dir : the directory underneath the script directory where backups are stored
; backup/@nbackups : the number of different backup files kept
; backup/@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&sn=#m 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&sn=#m"
/>
</code>

==== status ====
Defines details regarding the state kept for a device requesting an update script.
; status/@dir : the directory the status files are kept in (e.g. <code>status</code>). Used as the name for a sub-directory underneath your install directory on your web server. You must make sure that files in this directory cannot be read by anyone without proper authentication, as such files may contain sensitive information.
; status/@expire : if set and not empty, devices which have not requested an update script will be removed from the inventory after ''n'' seconds. For example, ''expire="7776000"'' will forget about devices after 90 days with no contact
; status/@missing : devices are shown in a different colour (indicating that they are ''missing'') after ''n'' seconds. For example, ''missing="604800"'' will flag devices as missing after 7 days with no contact
; status/@refresh : if set and not empty and larger than zero, the admin user interface showing the known devices will refresh the status of all shown devices each ''n'' seconds
; status/@logkeep : number of seconds log messages for individual devices will be kept
; status/usehttpsdevlinks : if set to true, links to devices in the status page are created using the https:// scheme
<code xml>
<status
dir="status"
expire="7776000"
missing="200"
refresh="10"
logkeep="90"
usehttpsdevlinks="true"
/>
</code>

==== times ====
Defines details regarding the delivery of update scripts to requesting devices.

; times/@dir : the directory the update scripts are stored in. For security reasons, you may want to make sure that files in this directory cannot be read without proper authentication.

These attributes define 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).
; times/@allow : the hours to be used in the ''times'' command (as in <code>mod cmd UP1 times /allow </code>''hours'')
; times/@initial : the minutes to be used in the ''times'' command (as in <code>mod cmd UP1 times /initial </code>''minutes'')

Delivered update scripts can include a [[Reference10:Concept_Update_Server#Check_command | check command ]] if the ''check'' attribute is set to <code>true</code>. . In this case, the devices will executed the scripts again only when you have edited/changed them.
; times/@check : if set to true, update scripts will be executed once only (unless their contents change)

When editing a number of update scripts, it is often not desirable if one changed script is already executed before another is changed too. When the ''grace'' attribute is set to a positive value, no script at all is delivered to requesting devices unless ''n'' seconds have expired since the last edit. For example, setting ''grace'' to 90 gives you one and a half minute to finish all your edits.

; times/@grace : defines the number of seconds that must expire before update script changes take effect

The update server works in either ''fast'' or ''normal'' mode. In ''fast'' mode, update scripts have to be requested more frequently, for example to step through multiple staging phases faster. This is enforced by modifying the calling device's ''Interval'' setting in [[Reference11r1:Services/Update | ''Services/Update '']] and setting it to 1 in ''fast'' mode.

; times/@interval : polling interval in minutes for normal operation (that is, when all staging s done)
; times/@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]]) (please do not modify the default value)

In some installations it may be desired to deliver update scripts with HTTPS only or even only to calling devices which have identified themselves with a proper TLS certificate.

; times/@forcehttps : if set to <code>true</code>, update scripts will only be delivered if the device call in with HTTPS. If the device is ready to receive an update script and still calls in with HTTP only, its ''Command File URL'' will be re-configured to use HTTPS automatically.
; times/@httpsport : if you use a non-standard port for HTTPS access to update scripts, it can be defined here
; times/@httpsurlmod : if your HTTPS URL differs from the HTTP URL, you can specifiy a ''modifier''. It has the form <code>!</code>''pattern''<code>!</code>''replacement''<code>!</code> where ''pattern'' is a [http://docs.php.net/manual/en/pcre.pattern.php PHP PCRE pattern]. For example, <code>!mtls/!!i</code> will remove the string <code>mtls/</code> from the URL used by the device to create the HTTPS URL to use. The delimiter (in this case "!") can be changed according to your own wishes, the first character defines the delimiter. The "i" at the end ignores uppercase.

Note: If you want to change the hostname of your URL, you have to add the Port 444 to your hostname. The code should then look like this: <code>!hostname1:444/mtls/!hostname2:444/!i</code>.
; times/@forcetrust : if set to <code>true</code>, update scripts will only be delivered if the device call in with HTTPS and a valid and trusted client certificate that identifies itself as the devices it claims to be
; times/@forcestaging : before build 2009, the restrictions imposed by the times/@allow settings affected all update ''phases''. This however makes staging cumbersome, as you usually want to restrict normal configuration changes to off-working-hours. Now you can set the ''forcestaging'' attribute to <code>true</code>. If so, the restriction will be applied only to the last phase (that is, the ''staging'' phases will execute immediately). Also, the final phase will be executed once by staged devices.

<code xml>
<times
dir="scripts"
allow=""
initial=""
check="true"
polling="5"
interval="15"
grace="90"
forcehttps="true"
httpsport="444"
forcetrust="false"
httpsurlmod="!mtls/!!i"
forcestaging="true"
/>
</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.
==== phases/phase ====
; phases/phase/@id : the name for the phase
; phases/phase/@seq: the sequential number for the phase. Phases are stepped-through in the numeric order defined by their ''seq'' atribute.

By virtue if the ''seq'' attribute, you can insert phases in to the set of phases defined by default, which is
<code xml>
<phases>

<phase id="staging" seq="100"/>
<phase id="update" seq="200"/>
</phases>
</code>
For example,
<code xml>
<phases>
<phase id="phase" seq="150"></phase>
</phases>
</code>
will insert a custom phase ''myphase'' as second phase.

==== 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.
==== environments/environment ====
; environments/environment/@id : the name for the environment

==== environments/environment/implies ====
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.
<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). By default, the classes ''phone'', ''opus_phone'', ''pre_opus_phone'', ''phone_oldui'', ''phone_newui'', ''mobile'', ''gw'', ''fxogw'', ''fxsgw'', ''brigw'', ''prigw'' are recognized (newer versions may include more and/or updated class definitions). Also, any device is considered to be member of a class that has the device type as class-name. For example, an IP112 is in a class called ''ip112''.

A given device can be in multiple classes and will execute all update scripts available for these classes.

==== classes/class ====
Each ''class'' has a number of sub-tags of type ''model''. It contains the value replaced for the <code>#t</code> query arg. The models listed belong to the class.
; classes/class/@id : the name of the class

<code xml>
<classes>
<class id="gw">
<model>ip0010</model>
...
</class>
<class id="phone">
<model>ip110</model>
<model>ip232</model>
...
</class>
<class id="phone_oldui">
<model>ip110</model>
...
</class>
<class id="phone_newui">
<model>ip232</model>
...
</class>
</classes>
</code>

==== nobootdev ====
Device types listed here do not receive boot code updates.
===== nobootdev/model =====
Each model tag defines a device type that shall not receive boot code updates.

<code xml>
<nobootdev>
<model>ipva</model>
<model>ipvadec</model>
<model>swphone</model>
<model>mypbxa</model>
<model>mypbxi</model>
</nobootdev>
</code>

==== nofirmdev ====
Device types listed here do not receive firmware updates.
===== nobootdev/model =====
Each model tag defines a device type that shall not receive firmware updates.

<code xml>
<nofirmdev>
<model>swphone</model>
<model>mypbxi</model>
</nofirmdev>
</code>

==== filenames ====
Available from build 2014. Allows you to define alternate firmware and boocode names for use with the <code>{filename}</code> replacement (see the ''fwstorage'' tag), if required.

===== filenames/model =====
Each mode defines a set of alternative file names for a certain device type.
; filenames/model/@id : the (lowercase) device type identfier (e.g. <code>ip112</code>). If this matches the device type of the calling device, the alternate file names are replaced
; filenames/model/@prot: the alternate firmware file name
; filenames/model/@boot: the alternate boot file name
<code xml>
<filenames>
<model id="mypbxa" prot="mypbx.apk"/>
</filenames>
</code>

defines the firmware file name <code>mypbx.apk</code> for the device type <code>mypbxa</code>.

==== stdargs ====
Better don't touch :-)

==== customcerts ====
innovaphone hardware devices come with a device specific, trust-able ''device certificate''. However, in many situations it is desirable to roll-out customer-created ''custom certificates'' to all devices. The update server can do this. This will replace the shipped devices certificates both on hardware devices (where all such certificates are derived from innovaphone's certificate authority) as well as on soft devices which run with a self.-signed certificate by default (such as the software-phone or ''myPBX for Android/iOS'').

; customcerts/@dir : the name of the directory underneath your installation directory which stores device certificates. you should make sure that this directory cannot be accessed without proper authentication
; customcerts/@CAkeys : a file name pattern (e.g. <code>CAkey*</code>). All files in ''customcerts/@dir'' which match the pattern must contain DER or PEM encoded public keys which form the ''certificate chain'' of your CA (usually it is only one and the public key of your CA). One key per file. The files, when sorted by name, must contain the CA key itself in the last file (any intermediate certificates, if any, in the other files in correct order)
; customcerts/@CAtype : must be <code>manual</code> currently
; customcerts/@CAname : a comma-separated list of CA names. Devices presenting a certificate signed by one of these CAs will be considered as having a valid certificate. Otherwise, they wil be instructed to create a ''certificate signing request'' (CSR) for subsequent submission to your CA
; customcerts/@CAnamesep : defines the name separator for ''customcerts/@CAname''. The default is '<code>,</code>' and you must change it to a different value if one of your CAs includes a comma in its name
; customcerts/@renew : if set and not 0, certificates are replaced by new ones ''n'' days before they expire
; customcerts/@CAwildcard : normally, the update server will accept a certificate only if its CN matches the device's serial number. However, sometimes, so-called ''wildcard certificates'' such as <code>*.innovaphone.com</code> are used on a device (e.g. on a PBX or on a ''reverse proxy''). If set, the update server will also accept a certificate that contains a CN which equals the value of ''customcerts/@CAwildcard''. Note that the CN must match literally. For example, if ''''customcerts/@CAwildcard'' is set to <code>*.innovaphone.com</code> a CN like <code>host.innovaphone.com</code> is not accepted

When the update server determines that a device calls in with an un-trusted or expired certificate, it will have it create a signing-request for a new certificate. The requested certificate properties can be defined:

; customcerts/@CSRkey : the key size, e.g. <code>2048-bit</code>. Note that we do not recommend keys larger than 2048 bit (see [[Reference7:Certificate_management#Certificate_Key_Length_and_CPU_Usage]] for details)
; customcerts/@CSRsignature : the signature algorithm, e.g. <code>SH256</code>
; customcerts/@CSRdn-cn : the CN (''common name'') part used for the DN
; customcerts/@CSRdn-ou : the OU (''organizational unit'') part used for the DN
; customcerts/@CSRdn-o : the O (''organization'') part used for the DN
; customcerts/@CSRdn-l : the L (''locality'') part used for the DN
; customcerts/@CSRdn-st : the ST (''state or province'') part used for the DN
; customcerts/@CSRdn-c : the C (''country'') part used for the DN (note: ''CSRdn'' for many CAs, must be a 2-letter ISO country code)
; customcerts/@CSRsan-dns-1 : the first of up to three DNS names
; customcerts/@CSRsan-ip-1 : the first of up to two IP addresses

Within the set of CSR attributes, the following meta-words will be replaced:

* <code>{realip}</code> : the real IP address of the device as reported in the <code>ip=#i</code> query argument
* <code>{ip}</code> : the IP address of the device as seen by the update server
* <code>{proxy}</code> : the IP address of the reverse proxy the device used to reach the update server
* <code>{sn}</code> : the serial number of the device as reported in the <code>sn=#m</code> query argument (e.g. <code>009033030df0</code>)
* <code>{hwid}</code> : the hardware-id of the device as reported in the <code>sn=#m</code> query argument (e.g. <code>IP1200-03-0d-f0</code>)
* <code>{name}</code> : the ''Device Name'' (set in ''General/Admin'') of the device
* <code>{rdns}</code> : the DNS name found in a reverse DNS lookup for the real-ip address reported by the device (see ''{realip}'') above

<code xml>
<customcerts
dir="certs"
CAkeys="CAkey*"
CAtype="manual"
CAname="innovaphone-INNO-DC-W2K8-Zertifizierungsserver"
CAnamesep=","
CAwildcard="*.innovaphone.com"
CSRkey="2048-bit"
CSRsignature="SH256"
CSRdn-cn="{hwid}"
CSRdn-ou=""
CSRdn-o=""
CSRdn-l=""
CSRdn-st=""
CSRdn-c=""
CSRsan-dns-1="{name}.company.com"
CSRsan-dns-2="{hwid}.company.com"
CSRsan-dns-3="{rdns}"
CSRsan-ip-1="{realip}"
CSRsan-ip-2=""
renew="90" />
</code>

==== queries ====
If queries are defined and applicable for the calling device, it will be instructed to send certain information to the update server which will be stored in the device status file kept on the server. Each piece of such information is defined usign a separate ''query'' tag.

; queries/@scfg : defines to URL used by the device to send the information. Normally not changed from the default
==== queries/query ====
Defines one piece of information to be submitted to the update server.

; queries/query/@id : a unique name for the query
; queries/query/@title : a title for this piece of information shown in the device status

<code xml>.

<query id="media" title="Media">
<cmd>mod cmd MEDIA xml-info</cmd>
<applies>*</applies>
<show title="NAT">concat(/state/queries/media/info/nat/@result, ' (', /state/queries/media/info/nat/@public-addr, ')')</show>
<show title="Server">concat('STUN: ', /state/queries/media/info/@stun, ' TURN: ', /state/queries/media/info/@turn, ' (', /state/queries/media/info/@turn-user, ')')</show>
</query>


<query id="registration" title="Registration">
<cmd>mod cmd PHONE/USER phone-regs /cmd phone-regs</cmd>
<applies>phone</applies>
<show title="State: User/Number">concat(/state/queries/registration/info/reg[@id = "0"]/@state, ': ' , /state/queries/registration/info/reg[@id = "0"]/@h323, '/', /state/queries/registration/info/reg[@id = "0"]/@e164)</show>
<show title="PBX/ID">concat(/state/queries/registration/info/reg[@id = "0"]/@gk-addr, '/', /state/queries/registration/info/reg[@id = "0"]/@gk-id)</show>
</query>
</code>

==== queries/query/cmd ====
The content of this tag defines the command to be executed on the device which outputs the requested information. These are ''mod cmd''s typically.

<code xml>

<cmd>mod cmd X509 xml-info</cmd>
</code>

See [[Howto:Effect_arbitrary_Configuration_Changes_using_a_HTTP_Command_Line_Client_or_from_an_Update#Using_the_Mechanism_for_Device_Status_Queries ]] for details on how to find out whicgh commands to use.

==== queries/query/applies ====
Defined queries are only executed by devices which belong to the class that is given as tag content. If the ''env'' atribute is set, the tag content is interpreted as an ''environment'' name which has to match.

; queries/query/applies/@env : if this attribute exists, the tag content is compared with the environments the device is in. Otherwise, it is compared with the classes it is in (unfortunately, you can not combine bith)
<code xml>

<applies>phone</applies>
</code>

==== queries/query/show====
If one or more ''show'' tags are defined for the ''query'' tag, the data will be shown in the device status page. The values shown are defined by the tag content which is an XPath expression selecting the data from the device state. The XPath expression always begins with <code>/state/queries/</code>''query-id'' (as defined by the ''id'' attribute in the query tag).

; queries/query/show/@title : used as title when the values are displayed in the status page

<code xml>
<show title="NAT">concat(/state/queries/media/info/nat/@result, ' (', /state/queries/media/info/nat/@public-addr, ')')</show>
</code>

== 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
: you need to use build 2000 or higher. Older versions are described in [[Howto:PHP_based_Update_Server]]

== Hints for writing your update snippets ==
Writing update scripts is largely undocumented and sometimes tricky. Here are some general guidelines.

=== Using <code>config add/del</code> ===
Many setting are done using <code>config change</code> commands. So these are very useful in update scripts too.

The straight forward method to find out which commands you need is as follows:
* get a device of the type in question and do factory reset
* save the configuration to a file
* do the desired settings using the normal web admin UI
* save the resulting configuration to another file
* compare the saved files

Usually, you want to set only specific parts of the configuration line. For example, assume you want to set the default coder to ''OPUS-WB''. Your saved configuration line might look like

config change PHONE SIG /prot SH323 /gk-addr pbx.innovaphone.com /gk-id innovaphone.com /tones 0 /lcoder OPUS-WB,20, /coder OPUS-WB,20,k1

To set only the coder settings, you would set the relevant options with the <code>config add</code> command as follows:

config add PHONE SIG /lcoder OPUS-WB,20,
config add PHONE SIG /coder OPUS-WB,20,k1

You can also remove specific options, as in

config rem PHONE SIG /tones

which would remove the <code>/tones 0</code> from the configuration line for <code>PHONE SIG</code>.

Note that the PHP update server will add the

config write
config activate
iresetn

at the end of the delivered script automatically, so you do not need to do it yourself. In fact, it is not recommended to have any reset command in your snippets.

==== <code>config change</code> Lines with associated Passwords ====
Sometimes, there is a password associated with certain configurations. Consider the STUN/TURN configuration:

config change MEDIA /stun stun.innovaphone.com /turn turn.innovaphone.com /turn-user innovaphone /turn-pwd 2 /nat-detect 61

The TURN password, being sensitive, needs to be encrypted in your configuration. This is why it is stored as a ''VAR'', which provides encryption support (see below):

vars create MEDIA/TURN-PWD pc ....

Unfortunately, the relationship between an option and an associated VAR needs to be guessed. You can be sure that the module name in the <code>config changey</code> matches the modules name in the <code>vars create</code> command. However, the variable name mist be guessed.

You can also set the password in your script using the <code>vars create</code>, however, you may also consider using a <code>mod cmd</code> (see below) such as e.g.

mod cmd MEDIA form /cmd form /del %2Fstun-slow /stun stun.innovaphone.com /turn turn.innovaphone.com /turn-user innovaphone /turn-pwd my-turn-pw /nat-detect 61

=== Using <code>vars create</code> ===

Sometimes it makes sense to use <code>vars create</code> commands. The syntax is

<code> vars create </code>''<name> <flags> <value>''

A ''<name>'' is a module name followed by a variable name, optionally followed by an index. For example, a phone will store the currently selected main registration as <code>vars create PHONE/ACTIVE-USER p </code>''<index>''. So the module is <code>PHONE</code> and the variable name is <code>ACTIVE-USER</code>. When the variable is multi-valued, an index is added to the name. For example, the registration settings for all but the first registration are stored as indexed variable, as in <code>vars create PHONE/USER-REG/00001 p </code>''<settings>'', where <code>00001</code> is the index (registrations count from 0 in this case).

There are a number of flags which can be combined, the most prominent used in update scripts are:
; p : permanent. The var is stored in flash memory (you will almost always use this flag in update scripts)
; c : crypted. The var value needs to be encrypted and the ''<value>'' given is crypted
; x : crypted, plain value. The var needs to be encrypted but the ''<value>'' is given as plain (that is, un-encrypted) text. This allows you to set an encrypted variable without encrypting the desired value
; b : binary. The var value is binary. Its ''<value>'' is given as a bin2hex string

Please note that using <code>vars create</code> will ''always'' set the internal ''reset needed condition'' in the device (regardless which ''<value>'' is set). This means that a subsequent <code>resetn</code> or <code>iresetn</code> will always trigger a reset. So if you use it, make sure that you use the ''times/@check'' ([[#times | see above]]) to protect your script from re-executing the snippet (and thus rebooting the device) all the time.


=== Using <code>mod cmd</code> ===
See [[Howto:Effect arbitrary Configuration Changes using a HTTP Command Line Client or from an Update]] for a discussion of how to use <code>mod cmd</code> in update scripts.

=== Writing your own Dynamic Scripting Code ===
NB: this feature is available from build 2020.

By default, the update server delivers update scripts which are composed from a number of static files (so-called ''snippets''). Sometimes it makes sense however, to create such snippets dynamically (e.g. based on a database lookup). Here is how to do this.

Dynamic scripting is implemented by a user-supplied custom <code>class CustomUpdateSnippet</code>. The code for this class must be placed in to the file <code>config/scripting.class.php</code>. As a starter, sample class code is available in <code>config/sample.scripting.class.php</code>.

<code php>
<?php

/**
* to provide your own runtime generated snippets, rename this file to 'scripting.class.php' and
* implement the member functions
* $property will have one member called
*/

class CustomUpdateSnippet extends UpdateSnippet {

/**
* snippet to deliver after standard text snippets
* @return array of string
*/
public function getPostSnippet() {
return parent::getPostSnippet();
}

/**
* snippet to deliver before standard text snippets
* @return array of strings
*/
public function getPreSnippet() {
return parent::getPreSnippet();
}

/**
* do we want to suppress the standard text snippets?
* @return boolean
*/
public function sendStandardSnippets() {
return parent::sendStandardSnippets();
}
}
?>
</code>

The sample code overrides of the classes member functions just call the base classes which do nothing at all. So if you just copy the sample code into <code>scripting.class.php</code>, nothing will change. However, if <code>getPreSnippet()</code> returns an array of strings (the parent class function returns an empty array), each array member will be sent to the calling device ''before'' the standard snippets are sent. Likewise, if <code>getPostSnippet()</code> returns an array of strings (the parent class function returns an empty array), each array member will be sent to the calling device ''after'' the standard snippets are sent. If <code>sendStandardSnippets()</code> returns false, the standard snippets will not be sent.

To determine the dynamic snippets to send, the user-provided <code>class CustomUpdateSnippet</code> has access to the members of its base <code>class UpdateSnippet</code>, namely the <code>var $statexml</code> member. This member contains a <code>SimpleXMLElement</code> object with all state information available for the calling device.

Here is a sample state found in <code>$statexml</code> (as output by the <code>dump()</code> member function):

<code xml>
<?xml version="1.0"?>
<state seen="1522065435" requested="130774bootcode" phase="update">
<device sn="00-90-33-3e-0c-57" type="IP112" classes="phone, opus_phone, phone_newui, hstrace, ip112" ip="127.0.0.1" rp="false" phase="update" environments="sifi, 172net" certstat="either certificate handling or state tracking not enabled - not doing any certificate checking" hwid="IP222-46-5c-77" realip="172.16.80.241" requestDownloaded="false"/>
<firmware requested="130986" requested-at="1522065435"/>
<bootcode requested-at="1522065435"/>
<config filename="scripts/all-all-all.txt" delivered="1522065426" version="1486559970"/>
</state>
</code>

The most interesting elements in this XML are probably the attributes of the <code>state</code> and the <code>device</code> tags.

== Optional Configurations on the Linux Application Platform ==
===Support for more Connections===
By default the LAP's web server lighttpd allows for 512 concurrent connections with 1024 open file descriptors. When you serve a huge number of devices with the update server, then this might be too low. You will see some devices not being able to contact the update server for a while. This should not be a real issue as the devices will retry. However, updating all devices may take long due to this.

In the lighttpd log (in <code>/var/log/lighttpd</code> on the LAP), you will see entries like this:

2017-10-16 13:45:18: (network_linux_sendfile.c.140) open failed: Too many open files
2017-10-16 13:45:18: (mod_fastcgi.c.3075) write failed: Too many open files 24
2017-10-16 13:45:18: (server.c.1434) [note] sockets disabled, out-of-fds
2017-10-16 16:23:25: (response.c.634) file not found ... or so: Too many open files /mtls/updatev2/web/innovaphone_logo_claim_fisch.png ->
2017-10-16 17:57:45: (server.c.1432) [note] sockets disabled, connection limit reached

If you experience such issues, proceed as follows:

* connect to the LAP with SFTP (e.g. using WinSCP)
* change directory to <code>/etc/lighttpd</code>
* edit <code>lighttpd.conf</code>
* search for the 2 lines which set <code>server.max-fds</code> and <code>server.max-connections</code>
* replace the standard values. We recommend to set the number of file descriptors to 4 times the number of requests when using the update server, e.g.
: old
:: server.max-fds = 1024
:: server.max-connections = 512
: new
:: server.max-fds = 8000
:: server.max-connections = 2000
* save the file
* restart linux (''Diagnostics/Reset/Reboot'')

Be sure to closely monitor the ''Diagnostics/Status'' page for a while after such configuration.

Also, when you update the LAP, you will have to re-do the changes (as always when you change something ''under the hood'').

=== Debug files rotation based on logrotate ===
If you have to debug during operation and a lot of devices access the PHP Update Server V2, you have to keep track of the debug files or automatically limit them. For this you can use logrotate on the innovaphone Linux AP. With logrotate you can apply time-based or size-based rules when files are packed and when they are deleted.
* open the LAP's file system using a SFTP client such as e.g. [https://winscp.net/eng/index.php WinSCP] (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]]). Note that you must use SFTP rather than WebDAV, as WebDAV will not give access to the executable web server files.
* Under the path <code>/etc/logrotate.d</code> create a file e.g. <code>updateserver</code>.

<code>/etc/logrotate.d/updateserver</code>

In this file now enter the following content and save it.

<code>
/var/www/innovaphone/mtls/update/debug/*.txt {
size 5M
missingok
rotate 2
compress
delaycompress
notifempty
create 644 www-data www-data
}
</code>

This will include all *.txt files from the debug directory of the PHP Update Server V2 in the logrotate process of the operating system.

; size 5M : means every 5MB the file is rotated or zipped
; size 5k : means every 5kB the file is rotated or zipped
Alternatively, you can also rotate the file based on time
; daily : means that every day the file is rotated or zipped
; weekly : means that the file is rotated or zipped daily

; missingok : if a debug file does not exist, it will be ignored
; rotate n : files are removed before the last ones are deleted.
; compress : compresses the old debug files
; delaycompress : compresses the debug data only after it has been moved once
; notifempty : empty log files are not rotated
; create 644 www-data www-data : creates a new, empty debug file with appropriate permissions

== Update Server and Reverse Proxy ==
It is possible to implement access to the update server through a ''reverse proxy'' (RP). However, you have to keep some issues in mind:
* ''Mutual Transport Layer Security'' (MTLS) is not possible
: MTLS requires a direct TLS connection between the two parties. An RP however would terminate the TLS connection and entertain two independent connections to the parties. This breaks MTLS. If you want to use MTLS and serve external clients, you must therefore provide a direct access to the update server (that is an external IP address either directly or through port forwarding)
: see [[#If_you_want_to_setup_MTLS-restricted_Delivery_of_Update_Scripts]] for details
* When using the RP, you can choose to forward encrypted traffic (HTTPS) arriving from external to the update server using HTTP (unencrypted). The update server however eventually rewrites the update URL in the calling devices configuration. In order to do this, it determines the type of the internal connection. So if the connection from the RP to the update server is using HTTP, it would create a ''http://...'' URL. Otherwise it would create an ''https://..'' URL (also, it would be using the same port). This way, if the RP forwards requests to the update server with HTTP, the synthesized new URL for the calling client would use HTTP too, even though the original request was sent with HTTPS. This may or may not be what you want (as all of your clients would end up using non-encrypted traffic). Even worse, it might not work at all, if the RP does not accept HTTP for example.

== Related Articles ==
* [[Reference10:Concept_Update_Server]]
* [[Reference12r1:DHCP_client]]
* [[Reference10:Concept_Linux_Application_Platform]]
* [[Reference10:Concept_Provisioning]]
* [[Howto:PHP_based_Update_Server]] (old version)
* [[Howto:Creating custom Certificates using a Windows Certificate Authority]]
* [[Howto:Effect arbitrary Configuration Changes using a HTTP Command Line Client or from an Update]]

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

Howto:PHP based Update Server V2

2018-08-14T11:41:35Z

Odawid: /* Configuration */

==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 Manager]] mechanism reads a file that corresponds to the device type (e.g. <code>update-ip222.htm</code>). 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 (build 2006 and up). 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 [[Reference10:Concept Linux Application Platform | 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 certificate (MTLS)
* maintain a list of devices in your installation along with some vital information about each individual device

=== Installation ===

==== On the Linux Application Platform ====
Here is how you would install it on the [[Reference10:Concept_Linux_Application_Platform|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. [https://winscp.net/eng/index.php WinSCP] (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]]). Note that you must use SFTP rather than WebDAV, as WebDAV will not give access to the executable web server files
* create a new root directory underneath <code>/var/www/innovaphone/mtls</code>, e.g. <code>/var/www/innovaphone/mtls/update</code>
* download the complete file package of scripts and files here: http://download.innovaphone.com/ice/wiki-src/
* copy all files and directories in to this new directory
* change owner and group of all files and directories to <code>www-data</code>, change mode to 0600 for all files and 0700 for all directories (see [[#Migrating_from_build_2000_an_newer | below]] for how to do this with WinSCP)

* 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]]) and open 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 <code>update</code>):
** <code>/mtls/update</code>
** <code>/mtls/update/web</code>
** <code>/mtls/update/admin</code>
** <code>/mtls/update/fw/</code> (note the trailing slash!)
: make sure that no other sub-directories of ''update'' are listed
: make sure you have no trailing '/' in any of these paths (except ''fw/')
: this will make sure the update server's admin user interface is not accessible to the public

At this point, you should be able to access the update server's admin user interface, e.g. <code>http://update.yourcompany.com/mtls/update/admin/admin.php</code>. However, the only thing you see is a login page. Please note that your browser should ask you for a password for this page (unless you already entered it before). Cookies must be enabled for the login page to work properly.

===== If you want to provide HTTPS Acess to the Update Server =====
For HTTPS access to the update server, you may want to install your own server certificate under ''Administration/Certificates/Current server certificate''. However, this is not strictly required (you will experience some warning messages when using your browser to access the update server, however, calling devices will work just fine).

===== If you want to setup MTLS-restricted Delivery of Update Scripts =====
If you think you have sensitive information in your update scripts, you should make sure to deliver such scripts to your own verified devices only. This can be done by authenticating calling devices with ''mutual TLS'' (MTLS). In this case, the calling device must use HTTPS to retrieve the update script and present a trusted client certificate that identifies itself as the calling device (that is, has the device serial as the certificate's ''common name'' (CN)).

For this feature, you need to ''Configure mutual TLS'' in the LAP's ''Administration/Web Server'' panel. Simply tick the ''Active'' check-mark and select an appropriate ''MTLS Port''. The port must not conflict with any other TCP port used on the LAP, so neither 80 nor 443 is a good choice. 444 is a good choice. Although it [http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?&page=8 is assigned to the snpp protocol] by IANA, it is not used by the LAP (and probably rarely used anyway).

If MTLS is already activated on your LAP, simply take note of the currently configured ''MTLS Port''.

 
Please note that MTLS access is ''not possible'' through a ''reverse proxy'' (RP). This is because the RP always will terminate the incoming TLS connection and establish its own to the target. Therefore, the client certificate presented to the target server is the RP's certificate, not the original clients certificate. In our context - where MTLS is used to verify the identity of the original caller - clients must not access the update server through an RP.

You can either expose your update server directly to the internet (and carefully think through the security implications) or create specific TCP port forwarding towards the update server in your NAT-router/firewall. In this case, we recommend to use non-standard HTTP and HTTPS ports on the NAT router (cause this will already keep most of the HTTP port scanners out there in the internet from functioning).

 
Also, you will need the public key of all the CAs you will trust. These must be configured in to the web server so it can trust the certificates your devices will present to it. See [[#Enforcing_Trust]] for details.

==== On an Apache Server running on the Windows Operating System ====
The update server will run on Apache too. However, as we did not test this setup thoroughly, we recommend to use the LAP's LigHTTPD instead.

* For hints on using MTLS on an Apache Web Server, see [[Reference10:Concept_Provisioning#Enforcing_mutual_TLS_on_Apache | Enforcing mutual TLS on Apache]]
* For hints on getting the ''innovaphone device certificate authority'' public keys (which you may or may not need), see [[Reference10:Concept_Provisioning#How_to_get_inno-dev-ca-certificate.crt | How to get inno-dev-ca-certificate.crt ]]

==== On Microsoft's IIS ====
We do not recommend to use IIS as
* it does not support PUT easily
* it is not compatible with the innovaphone device's MTLS implementation

===Configuration===

If you intend to deliver your update scripts with MTLS (that is, with HTTPS 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 <code>-----BEGIN CERTIFICATE-----</code>)

Also, you need to know the ''MTLS Port'' configured in your LAP (see [[#If_you_want_to_setup_MTLS-restricted_Delivery_of_Update_Scripts| If you want to setup MTLS-restricted Delivery of Update Scripts ]] above).

All tweakable parameters are set in <code>user-config.xml</code>. You may want to use an XML-capable editor such as notepad++, netbeans or Visual-Studio for editing. if your editor supports it, you benefit from the ''document type description'' (DTD) provided in <code>full-config.dtd</code>.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config debugmerge="false" debugcerts="false" debugscript="false">
</config>
</code>

The attributes of the <code>config</code> tag control some aspects of debugging. For now, simply set all 3 to <code>"true"</code> instead of <code>"false"</code>. Do not forget to revert them back to <code>"false"</code> when everything runs smoothly, large log files will result if not.

==== Securing Access ====
To control access to the update server's data, you should set a login. This can be done in the ''master'' tag by specifying both ''user'' and ''password'':

<code xml>
<master ... user="myadmin" password="mysecret"/>
</code>
Default username and password are admin/password.

==== Delivering Firmware and Boot Code ====
At this point, you can simulate a device by requesting an update script using an URL like <code>http://update.yourcompany.com/mtls/update/update.php?type=IP232&sn=00-90-33-00-00-00&hwid=IP232-00-00-00&ip=1.2.3.4</code> in your browser (please note that this URL should not ask you for a password). Most likely, your browser will wait a little while and then say something like:

...
# failed to use cached data (cache not current), retrieving info online
# cannot get PBX info: cannot access http://yourmasterdevice.youdomain.tld/CMD0/box_info.xml, reading cache
# cannot get cached PBX info: cannot access cache/master-info.xml - exit

This is because you did not yet specify the ''master device'' which always runs the reference firmware.

The idea here is that you have one innovaphone device in your system where the firmware is always manually updated. All other devices shall follow this reference firmware. The update server will deliver the firmware that runs on the master device to calling devices. For this to work, you need to set the ''info'' attribute of the [[#master|''master'']] tag and leave everything else ''as is''.

Remember that you do all your local configuration changes in <code>user-config.xml</code>.

As ''master'' is a first level tag, you can add it directly underneath the opening ''<config>'' tag. The only thing we need to define right now is the path to read the firmware information from your master device. Let's say your reference device has the IP address <code>172.16.0.10</code>, you end up with

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config debugmerge="true" debugcerts="true" debugscript="true">
<master info="http://172.16.0.10/CMD0/box_info.xml" user="myadmin" password="mysecret"/>
</config>
</code>
(you could use a DNS name instead of the IP address of course).
The ''info'' URL is used by the update server itself only, it is never used by devices requesting an update script.

When you refresh the page that simulates a device requesting an update script, the output should now change to something like

...
# failed to use cached data (cache not current), retrieving info online
# current firmware (unknown) does not match required firmware (130178)
...

This is to say that your master device runs firmware 130178 and the calling device does not (actually, as the calling client is simulated by your browser, it does not transmit its current firmware to the update server so it is ''(unknown)'').

In order to actually update the clients with firmware and boot code, the files must be made available to the calling client somehow. This is done by specifying an URL in the [[Reference10:Concept_Update_Server#Prot_command | prot ]] and [[Reference10:Concept_Update_Server#Boot_command | boot ]] commands sent to the calling device:

...
# current firmware (unknown) does not match required firmware (130178)
mod cmd UP0 prot http://update.yourcompany.com/mtls/update/fw/130178/ ser 130178
# current boot code (unknown) does not match required boot code (130112)
mod cmd UP0 boot http://update.yourcompany.com/mtls/update/fw/130112/ ser 130112
...

By default, the URL generated points to a sub-directory of your update server called ''fw'': <code>http://update.yourcompany.com/mtls/update/fw/130178/</code>. Note that this default URL expects sub-directories underneath the ''fw'' directory which correspond to the firmware and boot code build number. The file structure thus would be like

/var/www/innovaphone/mtls/update/fw
/130178
/ip232.bin
/130112
/boot232.bin

Note that the URL ends with a slash (<code>/</code>). This instructs the calling device to append the appropriate file name itself when retrieving the file (see [[Reference10:Concept_Update_Server#Prot_command | the prot command ]] for details).

However, you can also specify any other URL by setting the ''url'' attribute in the ''fwstorage'' tag of your <code>user-config.xml</code>. In this attribute, certain meta words will be replaced (see [[#fwstorage | the ''fwstorage'' tag ]] for details). The default setting for example is <code>fw/{build}/</code>.

You can disable firmware and boot code updates altogether by setting the ''info'' attribute in the ''master'' tag to an empty value.

==== Your own Update Script Files ====
The update server will deliver update scripts to calling devices which are synthesized from a number of ''update script snippets'' which you define yourself. The idea is that many devices share parts of their configuration while other parts are different. This depends on
* the device ''class'' (e.g. a phone or a gateway)
: the device class is automatically derived from its model. In fact, a single device may be in multiple classes. For example, an IP232 is in these classes: ''phone, pre_opus_phone, phone_newui'' which basically says that its a phone and has no OPUS codec yet but a "new" user interface (as opposed to the old one found e.g. on an IP110). A number of useful classes are pre-defined, but you can add your own in <code>user-config.xml</code>.
* the device's environment (e.g. ''home-office'', ''branch-office'')
: These reflect that fact that devices may need different configuration if they are in different locations (or environments). The update server does not know about a device's environment, which is why you need to configure it in to the devices update URL if you need this. By default, there is a single environment defined called ''default'', but of course, you can add your own
* phase
: configuring devices may need multiple phases to go through. If more than one phase is defined, the device will go through all phases sequentially, which is why a ''phase'' has a numerical ''seq'' attribute. Phases are went through in order of this attribute. When the device has reached the last phase, it will stay there. By default, there is only one phase called ''update''

You can define update script snippets for any combination of device, environment and phase. You do so simply by placing appropriate files in to the ''scripts'' directory on your update server.

Let's have a closer look at the web page we used to simulate a device calling for an update script before (<code>http://update.yourcompany.com/mtls/update/update.php?type=IP232&sn=00-90-33-00-00-00&hwid=IP232-00-00-00&ip=1.2.3.4</code>). It will show you all the possible files it would deliver to the device:

# possible files (from scripts):
# scripts/update-all-00_90_33_00_00_00.txt does not exist
# scripts/update-all-default.txt does not exist
# scripts/update-phone-00_90_33_00_00_00.txt does not exist
# scripts/update-phone-default.txt does not exist
# scripts/update-pre_opus_phone-00_90_33_00_00_00.txt does not exist
# scripts/update-pre_opus_phone-default.txt does not exist
# scripts/update-phone_newui-00_90_33_00_00_00.txt does not exist
# scripts/update-phone_newui-default.txt does not exist

The update script snippet files need to have proper names to define when they should be delivered. As you can see, they all start with <code>update-</code> which means that they apply to devices which are in the ''update'' phase. As by default there is only a single phase defined, all possible file names start with <code>update-</code>.

The next part here is either <code>phone-</code>, <code>pre_opus_phone-</code>, <code>phone_newui-</code> or <code>all-</code>. This is because the calling IP232 is in three classes, so all respective snippets will be delivered to it. ''all'' however is a wild-card. That is, such files will be delivered to all devices, no matter what class they are in. You may wonder why there was no ''all'' for the phase. This is because there is only a single phase defined. If there would be more, the ''all''-variation of the phase-part of the file name would be appear.

The third part finally is either <code>default</code> or <code>00_90_33_00_00_00</code> in our case. ''default'' is the name of the only ''environment'' that is defined by default. ''00_90_33_00_00_00'' is the device's serial number which is treated as an implicitly defined environment name. This allows you to deliver certain snippets to a single device only.

Now let's create an update script snippet that is delivered to all phones in the default environment when they are in the update phase. The file name (which looks like ''phase''<code>-</code>''class''<code>-</code>''environment''<code>.txt</code>) has to be <code>update-phone-default.txt</code> therefore. Just for an exercise, let us set the device name (as shown in the browser's title bar) to ''This is a Phone!''.
The command to do so is <code>config add CMD0 /name This+is+a+Phone%21</code>, so your file may look like this

# set the device name
config add CMD0 /name This+is+a+Phone%21

(btw: did you observe that config line arguments need to be url-encoded?). Now create the file and upload it in to the ''scripts'' directory of you update server. When you now refresh the page which simulates the device calling for an update script, you will see something like this:

...
# newest script (scripts/update-phone-default.txt) 11s old
# files being updated (scripts/update-phone-default.txt 11s old, waiting for at least 90s to expire)

When you update multiple script snippets, it is often undesirable that a device retrieves an inconsistent state of the scripts you are working on (e.g. if you already have saved one but not yet the other). To avoid this, the update server will look at the files modification dates and if one of those that needs to be delivered to the device is younger than 90 seconds, it will not send any of them at all.

So when you wait for the 90 seconds to pass and refresh the page again, you will see something like this:

# firmware build info cache is current
# phase: update, nextphase: , environment: default, type: IP232, classes: phone+pre_opus_phone+phone_newui
# possible files (from scripts):
...
# scripts/update-phone-default.txt 4.1 mins
...
# scripts/update-phone-default.txt
# { begin script 'scripts/update-phone-default.txt'
# set the device name
config add CMD0 /name This+is+a+Phone%21

# end script 'scripts/update-phone-default.txt' }

# trigger reset if required
config write
config activate
iresetn

As you can see, your snippet has been delivered by the update script. However, the update server has also added some trailing commands which write back the config to the devices flash memory (<code>config write</code>), activate it (<code>config activate</code>) and trigger a reset if needed (<code>iresetn</code>).

If there are multiple snippets available for a calling device, all of them are concatenated in the sequence shown in the header of the returned script (where the possible file names are listed)

==== Device Status ====
When you have a lot of devices which are served by the update server, you may want to have a list of these devices along with some useful information regarding each devices.

You can enable this by defining the ''status'' tag in your <code>user-config.xml</code>. So open the file and add the tag right next to the ''master'' tag you added before:

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config>
<master info="http://172.16.0.10/CMD0/box_info.xml"/>
<status
dir="status"
/>
</config>
</code>

When you have done so, please refresh the page that simulates your calling device and then open <code>http://update.yourcompany.com/mtls/update/admin/admin.php?mode=status</code>. You will now see a device list (well, a list with a single device, the one you simulated using your browser). The list will show some information regarding the devices that requested an update script lately. For more options, see [[#status]].

==== Device Backup ====
It is generally useful to have recent backups of all of your device configurations. The update server supports that if you enable it by defining the ''backup'' tag in your <code>user-config.xml</code>. Simply put it right next to the ''master'' or ''status'' tag you added before:

<code xml>
...
<backup
dir="backup"
/>
</code>

If you have done so and then refresh the page that simulates your calling device, you will now see

...
# scripts/update-phone_newui-default.txt does not exist

mod cmd UP0 scfg http://update.yourcompany.com/mtls/update/update.php?mode=backup&hwid=#h&sn=#m

instead of

...
# scripts/update-phone_newui-default.txt does not exist

# Backups not enabled in config

When a client requests an update script the next time, this will initiate a configuration backup which is stored underneath the ''backup'' directory. For each device, a sub-directory is created and all backup files are stored therein. By default, the last 10 differing configuration backups are kept.

==== Controlling the Time-frames when Snippets are delivered ====
The update client built-in to innovaphone devices allows to restrict updates to certain time frames (e.g. only during the night). This can be controlled using the [[Reference10:Concept_Update_Server#Times_command | times ]] command.

You can configure the update server to use the time commands by setting the ''allow'' and ''initial'' attributes in the ''times'' tag in your <code>user-config.xml</code>.

<code xml>
<times
allow="22,23,0,1,2,3,4"
initial="1"/>
</code>

If either the ''allow'' or ''initial'' attribute is present, the update script will contain a line like

...
# Restricted times
mod cmd UP1 times /allow 22,23,0,1,2,3,4 /initial 1

In the example above, all update script activity will occur only between 10pm and 5am (local device time). For more details, see [[Reference10:Concept_Update_Server#Times_command | Concept Update Server]]

==== Using and Enforcing HTTPS ====
Your devices can either use HTTP or HTTPS to access the update server. In normal operation, the update server will generate URLs (e.g. the URLs used to retrieve firmware or to backup configurations) for the same protocol.

However, you can enforce use of HTTPS by setting the ''forcehttps'' attribute in the [[Howto:PHP_based_Update_Server_V2#times | ''times'' ]] tag to <code>true</code>. If so, a device calling in with HTTP will be re-configured to use HTTPS:

...
# using HTTP and 'forcehttps' is set -> need to switch to HTTPS

# changed state query args: polling, phase
# new url=https://update.yourcompany.com/mtls/update/update.php?polling=5&phase=&type=#t&sn=#m&hwid=#h&ip=#i
...
(note that if you are using a non-standard port for HTTPS, you must define it using the ''httpsport'' attribute).

==== Delivering Custom Certificates ====
innovaphone devices come with pre-defined, trustworthy device certificates. However, all ''soft'' devices (such as the softwarephone, myPBX for Android/iOS or the IPVA) do not. Also, in many scenarios customers run their own ''public key infrastructure'' (PKI) and request their own certificates to be used instead of the pre-defined. This is why there is a need to roll-out custom certificates to devices.

The update server supports this task to an extend. It can
* check if a calling device has a proper certificate
* instruct a calling device without proper certificate to create a ''certificate signing request'' (CSR)
* download the CSR to the update server for easy access by the administrator
* upload a signed CSR to the device
* upload the public key(s) of the CA in to the device's trust list

In order to roll-out custom certificates with the update server, the administrator needs to
* run his own PKI (a.k.a. ''certificate authority'' (CA))
* monitor CSRs that appear in the update server's device list
* approve the request by manually submitting it to his own CA
* upload the signed CSR to the update server

Also, all devices must run ''V12r1 SR8'' or newer before the new certificate can be uploaded. Devices with older firmware will be updated automatically (see [[#Delivering_Firmware_and_Boot_Code]] above). However, the new firmware must be ''V12r1 SR8'' or later.

To learn how you can create proper device certificates with your own windows CA, see [[Howto:Creating custom Certificates using a Windows Certificate Authority]].

By default, custom certificates are turned off and you will see a note like

# certificates: either certificate handling or state tracking not enabled - not doing any certificate checking

in the delivered update script.

Custom certificates are turned on by adding a ''customcerts'' tag to your <code>user-config.xml</code>:

<code xml>
...
<customcerts
dir="certs"
/>
...
</code>

The the page that simulates your calling device will now include a line saying:

# certificates: we dont know anything about the current certificate state - not doing any certificate checking

In order to decide if or if not a calling device has a valid certificate, the device needs to send its current public key to the update server. This is done by enabling ''queries'' in your <code>user-config.xml</code>. ''Queries'' is a means to have the device submit certain information to the update server. In the update server's default configuration, two queries are defined but not enabled:

* the query ''certificates'' sends the current certificate state
* the query ''admin'' sends the current device name (as set in ''General/Admin'')

To enable a query, you must specify the class a calling device must be in in order to execute the query. This is done by adding an ''applies'' tag for the respective query in your configuration:

<code xml>
...
<queries>
<query id="admin">
<applies>*</applies>
</query>
<query id="certificates">
<applies>*</applies>
</query>
</queries>
...
</code>

This basically says that both queries should be executed by devices of just any class. Unless you enable queries, your update script will include lines such as:

# no queries defined for any of callers classes: phone+pre_opus_phone+phone_newui

Once you have enabled them, you will see something like

...
# query 'certificates'
mod cmd UP0 scfg https://update.yourcompany.com/mtls/update/update.php?mode=query&sn=#m&id=certificates ser nop /always mod%20cmd%20X509%20xml-info
# query 'admin'
mod cmd UP0 scfg https://update.yourcompany.com/mtls/update/update.php?mode=query&sn=#m&id=admin ser nop /always mod%20cmd%20CMD0%20xml-info
...

You can display the data sent by a query in the device status display. To do so, you need to define one or more ''show'' tags as part of the respective ''query'' tag:

<code xml>
...
<query id="certificates">
<applies>*</applies>

<show title="Subject">/state/queries/certificates/info/servercert/certificate/@subject_cn</show>
<show title="Issuer">/state/queries/certificates/info/servercert/certificate/@issuer_cn</show>
</query>
...
</code>

Two steps however are still missing:

* a) you need to tell the update server the names of all the CAs you consider trustworthy. This is done by listing their names in the ''CAname'' attribute of the ''customcerts'' tag:

<code xml>
...
<customcerts
dir="certs"
CAname="innovaphone Device Certification Authority,innovaphone Device Certification Authority 2,innovaphone-INNO-DC-W2K8-Zertifizierungsserver"
/>
...
</code>

: The example shown defines that you will accept both of innovaphone's device certificate authorities and also your own CA called ''innovaphone-INNO-DC-W2K8-Zertifizierungsserver''. Devices with device certificates issued by one of these CAs will be left untouched. For all other devices (for example, any ''myPBX for Android/iOS'' device that has a self-signed certificate), the generation of a custom certificate will be initiated.

* And b) you need to provide the public key of your CA (so it can be uploaded to the calling device's trust list). You need to place the DER (not PEM) encoded public key in to a file called <code>certs/CAkey-01.cer</code> on your update server (if you want to upload the whole certificate chain, put all of the public keys in the chain in to separate additional files called <code>certs/CAkey-02.cer</code> and so forth.

For more details on how to approve certificate signing requests, see [[#Approving Certificate Signing Requests]] below.

==== Enforcing Trust ====
Update script snippets may include sensitive information which you do not want to disclose to the public. Even though you can force the use of HTTPS (see above), this still does not keep your data secure. After all, an attacker could simply request an update script from your update server using HTTPS. To secure your data, you need to make sure that snippets are only sent to devices which identify themselves using a trusted certificate with a correct ''common name'' (CN). This is done using ''mutual transport layer security'' (MTLS). Therefore, you need to configure MTLS in the LAP (see [[#If_you_want_to_setup_MTLS-restricted_Delivery_of_Update_Scripts | If you want to setup MTLS-restricted Delivery of Update Scripts]] above).

You can enable this by setting ''forcetrust'' to <code>true</code> and ''httpsport'' to the port configured as ''MTLS Port'' in your web server. This is done in the ''times'' tag of your <code>user-config.xml</code>.
<code xml>
<times
...
forcehttps="true"
httpsport="444"
forcetrust="true"
/>
</code>
Please note that ''forcetrust'' does nothing unless ''forcehttps'' is also set!

If so, the update server will deliver update script snippets only to clients which identify themselves with a proper certificate. For this to work, you will need to add the public key of your certificate authority to your web server's list of trusted certificates.

When using the ''Linux Application Platform'' (LAP), you need to add the PEM-encoded public key of your certificate authority to the ''innovaphone-ca.pem'' file in <code>/home/root/ssl_cert</code>. When you have installed the LAP, this file will contain the PEM-encoded public keys of the 2 innovaphone device certificate authorities. You can simply add the public key of your CA to the end of this file:

-----BEGIN CERTIFICATE-----
...inno-ca public key...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...inno-ca2 public key...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...your-ca public key...
-----END CERTIFICATE-----

You will need to restart the LigHTTPD then (most easily done by restarting the entire LAP (''Diagnose/Reset'') or by issuing the command <code>/etc/rc2.d/S02lighttpd restart</code> from the linux root command prompt). Finally, you must set the ''forcetrust'' attribute.
(Note that the ''innovaphone-ca.pem'' file may be overwritten when a new LAP version is installed. It is thus a good idea to keep a copy and check it after an upgrade).

When ''forcetrust'' is effective and the calling device does not use HTTPS, it will be reconfigured to do so:

# using HTTP and 'forcehttps' is set -> need to switch to HTTPS
...
# new url=https://update.yourcompany.com:444/update/update.php?polling=5&phase=&type=#t&sn=#m&hwid=#h&ip=#i&env=default

If the calling device uses HTTPS but sends no certificate, you will see a message like

# cannot verify CN with HTTPS: SSL_CLIENT_S_DN_CN not present - fix web server configuration or use MTLS-enabled port!

This is probably because it is using a non-MTLS enabled port for HTTPS (e.g. the standard port 443) although MTLS is configured for a different port.

If the calling device uses HTTPS and sends a certificate but the CN does not match the serial number of the device, you will see a message such as

# Device claims to be 'IP232-30-00-af' but identifies as 'CKL-CELSIUS-W10.innovaphone.sifi' by TLS

If the calling device uses HTTPS and sends a certificate but the certificate is not trusted because its issuer is not listed in ''innovaphone-ca.pem'' (see above), the connection will be refused

In all such cases, no snippet will be delivered. If the certificate is good, you will see a message like

# good certificate(CN='IP232-30-00-af')

followed by the appropriate snippets.

==== Using multiple Phases ====
When you configure multiple phases, all phases up to the final phase are stepped through and when all associated update script snippets for all phases are done, the device will ultimately stay in the final phase. This can be used e.g. to implement update script snippets which are executed once only when the device is initialized. Settings made in all but the last phase can later be overridden by the user or an administrator. The settings done in the update script settings for the final phase however are re-executed whenever one of your update script files for this phase changes.
The process of deploying some initial settings is often called ''staging''.

To enable staging, you therefore create a new phase that comes before the default phase (which is ''update''). Phases are sorted numerical by an attribute called ''seq''. As the default phase ''update'' is defined with ''seq=200'', your new staging phase must be defined with a lower seq value:

<code xml>
...
<phases>
<phase id="staging" seq="100"/>
</phases>
...
</code>

When you define such a phase, there will be new possible update script snippet file names:

# phase: staging, nextphase: update, environment: default, type: IP232, classes: phone+pre_opus_phone+phone_newui
# possible files (from scripts):
# scripts/all-all-00_90_33_30_00_af.txt does not exist
# scripts/all-all-default.txt does not exist
# scripts/all-phone-00_90_33_30_00_af.txt does not exist
# scripts/all-phone-default.txt does not exist
# scripts/all-pre_opus_phone-00_90_33_30_00_af.txt does not exist
# scripts/all-pre_opus_phone-default.txt does not exist
# scripts/all-phone_newui-00_90_33_30_00_af.txt does not exist
# scripts/all-phone_newui-default.txt does not exist
# scripts/staging-all-00_90_33_30_00_af.txt does not exist
# scripts/staging-all-default.txt does not exist
# scripts/staging-phone-00_90_33_30_00_af.txt does not exist
# scripts/staging-phone-default.txt does not exist
# scripts/staging-pre_opus_phone-00_90_33_30_00_af.txt does not exist
# scripts/staging-pre_opus_phone-default.txt does not exist
# scripts/staging-phone_newui-00_90_33_30_00_af.txt does not exist
# scripts/staging-phone_newui-default.txt does not exist

First of all, there are new names for this particular phase. Furthermore, as we now have multiple phases, the new wild-card name ''all'' is possible.

An example for a staging script snippet might be a file called <code>staging-all-all.txt</code>:

# change admin password
config add CMD0 /user admin,my-admin-password
config activate
config rem CMD0 /user

This will set the admin password to <code>my-admin-password</code> during staging (it should be obvious that such staging should only be done in combination with [[#Enforcing_Trust|Enforcing Trust]], see above).

=== A complete <code>user-config.xml</code> Sample ===
Here is a complete sample of a configuration file.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE config SYSTEM "full-config.dtd">

<config debugmerge="true">
<master info="http://172.16.0.10/CMD0/box_info.xml"/>
<status
dir="status"
missing="1000"
/>
<backup
dir="backup"
/>
<times
allow="22,23,0,1,2,3,4"
initial="1"
forcehttps="true"
httpsport="444"
forcetrust="true"
/>
<customcerts
dir="certs"
CAname="innovaphone Device Certification Authority,innovaphone Device Certification Authority 2"
CSRsan-dns-1="{name}.company.com"
CSRsan-dns-2="{hwid}.company.com"
CSRsan-dns-3="{rdns}"
CSRsan-ip-1="{realip}"
/>
<phases>
<phase id="staging" seq="100"/>
</phases>
<environments>
<environment id="intranet"/>
<environment id='sifi'>
<implies>intranet</implies>
</environment>
<environment id='berlin'>
<implies>intranet</implies>
</environment>
<environment id='verona'>
<implies>intranet</implies>
</environment>
<environment id='homeoffice'/>
<environment id='mobile'/>
</environments
<queries>
<query id="admin">
<applies>*</applies>
</query>
<query id="certificates">
<applies>*</applies>
<show title="Subject">/state/queries/certificates/info/servercert/certificate/@subject_cn</show>
<show title="Issuer">/state/queries/certificates/info/servercert/certificate/@issuer_cn</show>
</query>
</queries>
</config>
</code>

=== Operation ===

==== Configuring and Debugging a real Device ====
To configure your device for use with the update server, you simply set <code>http://update.yourcompany.com/mtls/update/update.php</code> as ''Command File URL'' in ''Services/Update'' (you can optionally add a <code>?env=envname1,envname2</code> query argument if you want to set one or more specific environments for your device). The update server will re-configure the device later on so that it uses all the required query arguments.

Generally, there are the following methods to set the ''Command File URL''
* configure it manually using the admin GUI
* provide it to the device using DHCP (this will however not work for the softwarephone or ''myPBX for Android/iOS'')
* use the innovaphone provisioning service (see [[Reference10:Concept_Provisioning|Reference10:Concept Provisioning]] for details)

Once the ''Command File URL'' is set on the device, you can debug what the update client in the device does, using the normal trace mechanism. For this, you will want to open the ''Debug'' page (<code>http://x.x.x.x/debug.xml</code>) and set the ''Update/Polling'' and ''Update/Execution'' check-marks. When the update client queries the update server, you will see lines like

0:0826:465:5 - upd_poll: state IDLE -> RECV
0:0826:465:7 - IP.0 -> UPD-POLL.0 : SOCKET_GET_LOCAL_ADDR_RESULT(172.16.100.201,255.255.0.0,0,'',ANY)
0:0826:466:0 - IP.0 -> UPD-POLL.0 : SOCKET_GET_LOCAL_ADDR_RESULT(172.16.100.201,255.255.0.0,0,'',ANY)
0:0826:695:0 - upd_poll: state=RECV sent()
0:0826:752:0 - upd_poll: status 200 headercomplete=1 contentlength=0
0:0826:754:0 - upd_poll: recv_data(2199)
0:0826:754:1 - upd_poll: recv_data(0) EOF
0:0826:754:1 - upd_poll: GET EOF - state=RECV http-status=200 length=2199
0:0826:754:1 - upd_poll: do commands
0:0826:754:1 - upd_poll: state RECV -> EXEC

in the trace. Commands included in the update script will look like

0:0826:754:5 - script::get_line: >line(mod cmd UP0 scfg https://update.yourcompany.com/mtls/update/update.php?mode=backup&hwid=#h&sn=#m)
0:0826:754:5 - upd_poll: pass 'mod cmd UP0 /sync scfg https://update.yourcompany.com/mtls/update/update.php?mode=backup&hwid=#h&sn=#m')

Finally, you do not need to wait for the next time the device decides to contact the update server. Instead, you can force this by sending an <code>http://</code>''your-device-ip<code>/!mod cmd UP1 poll</code> to the device.

==== The Device Status Update Page ====
If status tracking is enabled (see [[#Device_Status | Device Status]] above), the update server will keep a list of devices it knows of. You can see this list by calling <code>http://update.yourcompany.com/mtls/update/admin/admin.php?mode=status</code>.

By default, the list will not be updated unless you refresh the page. However, if you set the ''refresh'' attribute in the ''status'' tag in your ''use-config.xml'' file tp <code>60</code>, all entries in this list will be refreshed every 60 seconds (however, the list itself will not be reloaded, so to see new devices, your need to refresh the entire page). Devices that have not been seen for more than 7 days are shown in a different colour. Devices that have not been seen for longer than 90 days will be silently removed from the list.

===== Filtering =====
From build 2011, you can filter the devices shown using the ''device filter'' field in the ''Device'' column header. The filter string is matched against ip-address, serial number, type, name, phase, class, environment, firmware and bootcode. Also, you can filter by using the keywords ''present'' and ''missing'' (based on the ''missing'' attribute of the ''status'' tag in your configuration file). If one of these attributes match your filter expression, the device is shown.

A filter expression must match a complete ''word''. For example, if you filter by <code>16</code> this would match the ip-address <code>172.</code>16<code>.0.20</code> but it would not match <code>192.</code>16<code>8.0.1</code>.

If you specify multiple filter expressions (separated by white space), only devices which match all of the expressions will be shown. For example, if you filter by <code>172.16. ip222</code> this might match all IP222 in your 172.16.*.* network. Filter expressions are case insensitive.

==== Approving Certificate Signing Requests ====
When you use custom certificate roll-out, you will see a column ''Certificates'' in the device status list, showing the devices certificate status.

[[Image:PHP_based_Update_Server_V2_Device_Status.png]]

If a CSR has been created on the device, this will be available for download in the ''Files'' section of the ''Info'' column. You can submit the CSR to your CA and then upload the signed request (using the ''Upload'' button in the ''Files'' section of the ''Info'' column). The signed request will eventually be uploaded to the device then. On the device itself, the CSR is shown in ''General/Certificates''.

[[Image:PHP_based_Update_Server_V2_CSR.png]]

==== Certificate Errors ====
When a signed certificate request uploaded to the device can not be installed on the device, you will see a message like <code>Certificate upload error - certificate handling stopped</code> in the ''Certificates'' columns for the device. In this case, any further processing will be stopped. Most likely, the reason is that you uploaded the wrong file as signed certificate request (either not a signed certificate at all or a signed request for another device).

In this case
* remove any certificate request from the device
* remove the <code>X509/REQUESTERROR</code> from the device configuration (i.e. <code>vars del X509/REQUESTERROR</code>)
: these 2 steps can be easily done by resetting the device to factory defaults and then set the ''Update URL'' again
* remove any stored files for the device on the update server (shown in the ''Certificates'' column)

The normal process will start all over again then.

=== Migrating old PHP Update Server Installations ===
==== Migrating from build 2000 an newer ====
* Copy all files and folders, '''except''' the ''scripts'' and ''config'' folder, from the source to your destination
* make sure all files and directories have correct owner (''www-data''), group (''www-data'') and mode (''read''/''write'' plus ''execute'' for directories)
: for example, in WinSCP you can use the ''Properties (F9)'' dialogue on the installations root folder:
: [[Image:PHP based Update Server V2-WinSCP-Properties.png]]
* open the ''StatusPage'' and make sure you refresh all cached files in your browser (depending on your browser, this may happen with Ctrl-R or Ctrl-F5)

==== Migrating from build 1011 and older ====
To upgrade from the [http://download.innovaphone.com/ice/wiki-src/index.php?urloffset=php-update-server%2F&name=php-update-server+%28all+available+builds%29&reverselevel=0&maxbuilds=999&root=c%3A%2Finetpub%2Fwwwroot%2Fdownload%2Fice%2Fdownload%2Fp%2Fwiki-src%2Fphp-update-server%2F1010+%28PHP+based+Update+Server+final%29%2F.. old version (builds up to 1011)] of the PHP based update server (as described in [[Howto:PHP based Update Server]]), do the following

* diff your <code>config.xml</code> to the one originally shipped (you can download it at [http://download.innovaphone.com/ice/download/p/wiki-src/php-update-server/1011%20(PHP%20based%20Update%20Server%20final)/php-update-server-1011.zip download.innovaphone.com/ice/wiki-src])
: take note of all the changes you made to it
* install the new version of the update server to a different URL
* configure it according to your needs by modifying <code>user-config.xml</code>. Do not modify the new <code>config.xml</code>!
** apply all modifications you did to your old <code>config.xml</code> to your new <code>user-config.xml</code>
** if you have used a custom setting for fwstorage/@url, you need to change it a bit. Change for example <code>url="http://myfwserver.mycompany.com</code> to <code>http://myfwserver.mycompany.com/{build}/</code> (note the trailing slash!)
* copy all your update script snippet files from the old server (these are all the .txt files in the old server's root directory) to the <code>scripts</code> directory of your new server
* copy the complete <code>fw</code> tree from the old server to the <code>fw</code> directory of your new server
* thoroughly test your new installation with some test devices
* when satisfied, edit <code>update-migrate.php</code> and change the code as described in the comment inside the file
* copy <code>update-migrate.php</code> from the new installation to the old installation
* on one of the devices which are currently served by the old update server, change the ''Command File URL'' so that it points to <code>update-migrate.php</code> instead of <code>update.php</code>. Do not change anything else in the URL. So if it currently is set to e.g.
: <code>https://172.16.0.90/update/update.php?type=#t&env=sifi&polling=0&phase=update</code>, change it to
: <code>https://172.16.0.90/update/update-migrate.php?type=#t&env=sifi&polling=0&phase=update</code>
* verify that this device properly switches to your new installation
** the ''Command File URL'' is changed so that it points to the new installation
** the device shows up in the device status page of your new server

* rename <code>update.php</code> to <code>update-old.php</code> in your old update server
* rename <code>update-migrate.php</code> to <code>update.php</code> in your old update server
* verify that all of your devices start showing up in the new server's status page

=== Complete Parameter Reference ===
Note: attributes are marked with an ''at'' (<code>@</code>) prefix. So ''master/@info'' refers to the ''info'' attribute in the ''master'' tag.

The following tags and attributes are available in the <code>user-config.xml</code> file, their default values are configured in <code>config.xml</code> (which you should not modify):

==== 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 <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''. If you use the literal <code>none</code>, the master device will not be queried
; 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 | ''Installation'' ]] above)
; master/@user : if non-empty, this is the user name required to access the update server's web ui
; master/@password : the password

From build 2009, you can control the firmware and bootcode version to use on update:
; master/@firmware : if set, it may be one of
:: <code>master</code> (default if not set) : the firmware version is derived from the master device
:: <code>none</code> : the firmware update is generally disabled
:: ''build-number'' : the firmware is set to a certain ''build-number'' regardless of the firmware running on the master device
; master/@bootcode: if set, it may be one of
:: <code>master</code> (default if not set) : the bootcode version is derived from the master device
:: <code>firmware</code> : the bootcode version is set to the firmware version. This may be useful if the master device has no bootcode (e.g. the ipva)
:: <code>none</code> : the bootcode update is generally disabled
:: ''build-number'' : the bootcode is set to a certain ''build-number'' regardless of the bootcode running on the master device

<code xml>
<master
info="http://172.16.0.10/CMD0/box_info.xml"
expire="3600"
cache="cache/master-info.xml"
user="myadmin"
password="mysecret"
firmware="4711"
bootcode="firmware"
/>
</code>

==== master/applies ====
Available from build 2009.

Boot code and firmware updates are only executed by devices which match all of the given <applies> conditions. A condition is met if the device belongs to the class that is given as tag content. If the ''env'' attribute is set, the tag content is interpreted as an ''environment'' name which has to match.

; master/applies/@env : if this attribute exists, the tag content is compared with the environments the device is in. Otherwise, it is compared with the classes it is in
<code xml>
<master
info="http://172.16.0.10/CMD0/box_info.xml"
expire="3600"
cache="cache/master-info.xml"
user="myadmin"
password="mysecret"
firmware="4711"
bootcode="firmware">

<applies>phone</applies>
<applies env="">berlin</applies>
</master>
</code>

==== fwstorage ====
Defines from where the device will retrieve the firmware files for updates.
; fwstorage/@url : defines the URL to retrieve the files from. In this URL, the following meta words will be replaced as follows:
:* <code>{build}</code> - the requested firmware or boot-code
:* <code>{model}</code> - the devices type (e.g. <code>IP232</code>). This is derived from the ''type'' query argument used in the update URL which is set to the value <code>#t</code> which in turn is expanded to the [[Reference10:Concept_Update_Server#Scfg_command|''device type'']] of the device requesting the update script
:* <code>{filetype}</code> - the type of the required file, either <code>boot</code> or <code>prot</code>
:* <code>{filename}</code> - (from build 2014) the boot code or firmware filename for the device in lower case. Required if you use the LAP as firmware storage and firmware files are falsely requested in uppercase letters (as URLs on the LAP are case sensitive and if the files are requested with upper case names, the original files with lowercase name are not found). This also allows you to use alternate firmware file names (such as e.g. <code>ip110-sip.bin</code>). See the ''filenames'' tag
Note that if the ''url'' ends with a slash (<code>/</code>), the calling device will automatically [[Reference10:Concept_Update_Server#Prot_command|append the name of the requested file]]. In this case, 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/{build}/</code>), it is treated as a sub-directory underneath the update server's root directory

<code xml>
<fwstorage url="fw/{build}/"/>
</code>

===== Loading firmware files from innovaphone.com =====
You can also load firmware from the innovaphone.com web site. To do so, set ''url'' like so:

<code xml>
<fwstorage url="http://webbuild.innovaphone.com/{build}/"/>
</code>

Please note that ''this is a voluntary service, no guarantee of availability, no service level agreement''.

==== backup ====
Defines where backup files are kept.
; backup/@dir : the directory underneath the script directory where backups are stored
; backup/@nbackups : the number of different backup files kept
; backup/@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&sn=#m 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&sn=#m"
/>
</code>

==== status ====
Defines details regarding the state kept for a device requesting an update script.
; status/@dir : the directory the status files are kept in (e.g. <code>status</code>). Used as the name for a sub-directory underneath your install directory on your web server. You must make sure that files in this directory cannot be read by anyone without proper authentication, as such files may contain sensitive information.
; status/@expire : if set and not empty, devices which have not requested an update script will be removed from the inventory after ''n'' seconds. For example, ''expire="7776000"'' will forget about devices after 90 days with no contact
; status/@missing : devices are shown in a different colour (indicating that they are ''missing'') after ''n'' seconds. For example, ''missing="604800"'' will flag devices as missing after 7 days with no contact
; status/@refresh : if set and not empty and larger than zero, the admin user interface showing the known devices will refresh the status of all shown devices each ''n'' seconds
; status/@logkeep : number of seconds log messages for individual devices will be kept
; status/usehttpsdevlinks : if set to true, links to devices in the status page are created using the https:// scheme
<code xml>
<status
dir="status"
expire="7776000"
missing="200"
refresh="10"
logkeep="90"
usehttpsdevlinks="true"
/>
</code>

==== times ====
Defines details regarding the delivery of update scripts to requesting devices.

; times/@dir : the directory the update scripts are stored in. For security reasons, you may want to make sure that files in this directory cannot be read without proper authentication.

These attributes define 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).
; times/@allow : the hours to be used in the ''times'' command (as in <code>mod cmd UP1 times /allow </code>''hours'')
; times/@initial : the minutes to be used in the ''times'' command (as in <code>mod cmd UP1 times /initial </code>''minutes'')

Delivered update scripts can include a [[Reference10:Concept_Update_Server#Check_command | check command ]] if the ''check'' attribute is set to <code>true</code>. . In this case, the devices will executed the scripts again only when you have edited/changed them.
; times/@check : if set to true, update scripts will be executed once only (unless their contents change)

When editing a number of update scripts, it is often not desirable if one changed script is already executed before another is changed too. When the ''grace'' attribute is set to a positive value, no script at all is delivered to requesting devices unless ''n'' seconds have expired since the last edit. For example, setting ''grace'' to 90 gives you one and a half minute to finish all your edits.

; times/@grace : defines the number of seconds that must expire before update script changes take effect

The update server works in either ''fast'' or ''normal'' mode. In ''fast'' mode, update scripts have to be requested more frequently, for example to step through multiple staging phases faster. This is enforced by modifying the calling device's ''Interval'' setting in [[Reference11r1:Services/Update | ''Services/Update '']] and setting it to 1 in ''fast'' mode.

; times/@interval : polling interval in minutes for normal operation (that is, when all staging s done)
; times/@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]]) (please do not modify the default value)

In some installations it may be desired to deliver update scripts with HTTPS only or even only to calling devices which have identified themselves with a proper TLS certificate.

; times/@forcehttps : if set to <code>true</code>, update scripts will only be delivered if the device call in with HTTPS. If the device is ready to receive an update script and still calls in with HTTP only, its ''Command File URL'' will be re-configured to use HTTPS automatically.
; times/@httpsport : if you use a non-standard port for HTTPS access to update scripts, it can be defined here
; times/@httpsurlmod : if your HTTPS URL differs from the HTTP URL, you can specifiy a ''modifier''. It has the form <code>!</code>''pattern''<code>!</code>''replacement''<code>!</code> where ''pattern'' is a [http://docs.php.net/manual/en/pcre.pattern.php PHP PCRE pattern]. For example, <code>!mtls/!!i</code> will remove the string <code>mtls/</code> from the URL used by the device to create the HTTPS URL to use. The delimiter (in this case "!") can be changed according to your own wishes, the first character defines the delimiter. The "i" at the end ignores uppercase.

Note: If you want to change the hostname of your URL, you have to add the Port 444 to your hostname. The code should then look like this: <code>!hostname1:444/mtls/!hostname2:444/!i</code>.
; times/@forcetrust : if set to <code>true</code>, update scripts will only be delivered if the device call in with HTTPS and a valid and trusted client certificate that identifies itself as the devices it claims to be
; times/@forcestaging : before build 2009, the restrictions imposed by the times/@allow settings affected all update ''phases''. This however makes staging cumbersome, as you usually want to restrict normal configuration changes to off-working-hours. Now you can set the ''forcestaging'' attribute to <code>true</code>. If so, the restriction will be applied only to the last phase (that is, the ''staging'' phases will execute immediately). Also, the final phase will be executed once by staged devices.

<code xml>
<times
dir="scripts"
allow=""
initial=""
check="true"
polling="5"
interval="15"
grace="90"
forcehttps="true"
httpsport="444"
forcetrust="false"
httpsurlmod="!mtls/!!i"
forcestaging="true"
/>
</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.
==== phases/phase ====
; phases/phase/@id : the name for the phase
; phases/phase/@seq: the sequential number for the phase. Phases are stepped-through in the numeric order defined by their ''seq'' atribute.

By virtue if the ''seq'' attribute, you can insert phases in to the set of phases defined by default, which is
<code xml>
<phases>

<phase id="staging" seq="100"/>
<phase id="update" seq="200"/>
</phases>
</code>
For example,
<code xml>
<phases>
<phase id="phase" seq="150"></phase>
</phases>
</code>
will insert a custom phase ''myphase'' as second phase.

==== 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.
==== environments/environment ====
; environments/environment/@id : the name for the environment

==== environments/environment/implies ====
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.
<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). By default, the classes ''phone'', ''opus_phone'', ''pre_opus_phone'', ''phone_oldui'', ''phone_newui'', ''mobile'', ''gw'', ''fxogw'', ''fxsgw'', ''brigw'', ''prigw'' are recognized (newer versions may include more and/or updated class definitions). Also, any device is considered to be member of a class that has the device type as class-name. For example, an IP112 is in a class called ''ip112''.

A given device can be in multiple classes and will execute all update scripts available for these classes.

==== classes/class ====
Each ''class'' has a number of sub-tags of type ''model''. It contains the value replaced for the <code>#t</code> query arg. The models listed belong to the class.
; classes/class/@id : the name of the class

<code xml>
<classes>
<class id="gw">
<model>ip0010</model>
...
</class>
<class id="phone">
<model>ip110</model>
<model>ip232</model>
...
</class>
<class id="phone_oldui">
<model>ip110</model>
...
</class>
<class id="phone_newui">
<model>ip232</model>
...
</class>
</classes>
</code>

==== nobootdev ====
Device types listed here do not receive boot code updates.
===== nobootdev/model =====
Each model tag defines a device type that shall not receive boot code updates.

<code xml>
<nobootdev>
<model>ipva</model>
<model>ipvadec</model>
<model>swphone</model>
<model>mypbxa</model>
<model>mypbxi</model>
</nobootdev>
</code>

==== nofirmdev ====
Device types listed here do not receive firmware updates.
===== nobootdev/model =====
Each model tag defines a device type that shall not receive firmware updates.

<code xml>
<nofirmdev>
<model>swphone</model>
<model>mypbxi</model>
</nofirmdev>
</code>

==== filenames ====
Available from build 2014. Allows you to define alternate firmware and boocode names for use with the <code>{filename}</code> replacement (see the ''fwstorage'' tag), if required.

===== filenames/model =====
Each mode defines a set of alternative file names for a certain device type.
; filenames/model/@id : the (lowercase) device type identfier (e.g. <code>ip112</code>). If this matches the device type of the calling device, the alternate file names are replaced
; filenames/model/@prot: the alternate firmware file name
; filenames/model/@boot: the alternate boot file name
<code xml>
<filenames>
<model id="mypbxa" prot="mypbx.apk"/>
</filenames>
</code>

defines the firmware file name <code>mypbx.apk</code> for the device type <code>mypbxa</code>.

==== stdargs ====
Better don't touch :-)

==== customcerts ====
innovaphone hardware devices come with a device specific, trust-able ''device certificate''. However, in many situations it is desirable to roll-out customer-created ''custom certificates'' to all devices. The update server can do this. This will replace the shipped devices certificates both on hardware devices (where all such certificates are derived from innovaphone's certificate authority) as well as on soft devices which run with a self.-signed certificate by default (such as the software-phone or ''myPBX for Android/iOS'').

; customcerts/@dir : the name of the directory underneath your installation directory which stores device certificates. you should make sure that this directory cannot be accessed without proper authentication
; customcerts/@CAkeys : a file name pattern (e.g. <code>CAkey*</code>). All files in ''customcerts/@dir'' which match the pattern must contain DER or PEM encoded public keys which form the ''certificate chain'' of your CA (usually it is only one and the public key of your CA). One key per file. The files, when sorted by name, must contain the CA key itself in the last file (any intermediate certificates, if any, in the other files in correct order)
; customcerts/@CAtype : must be <code>manual</code> currently
; customcerts/@CAname : a comma-separated list of CA names. Devices presenting a certificate signed by one of these CAs will be considered as having a valid certificate. Otherwise, they wil be instructed to create a ''certificate signing request'' (CSR) for subsequent submission to your CA
; customcerts/@CAnamesep : defines the name separator for ''customcerts/@CAname''. The default is '<code>,</code>' and you must change it to a different value if one of your CAs includes a comma in its name
; customcerts/@renew : if set and not 0, certificates are replaced by new ones ''n'' days before they expire
; customcerts/@CAwildcard : normally, the update server will accept a certificate only if its CN matches the device's serial number. However, sometimes, so-called ''wildcard certificates'' such as <code>*.innovaphone.com</code> are used on a device (e.g. on a PBX or on a ''reverse proxy''). If set, the update server will also accept a certificate that contains a CN which equals the value of ''customcerts/@CAwildcard''. Note that the CN must match literally. For example, if ''''customcerts/@CAwildcard'' is set to <code>*.innovaphone.com</code> a CN like <code>host.innovaphone.com</code> is not accepted

When the update server determines that a device calls in with an un-trusted or expired certificate, it will have it create a signing-request for a new certificate. The requested certificate properties can be defined:

; customcerts/@CSRkey : the key size, e.g. <code>2048-bit</code>. Note that we do not recommend keys larger than 2048 bit (see [[Reference7:Certificate_management#Certificate_Key_Length_and_CPU_Usage]] for details)
; customcerts/@CSRsignature : the signature algorithm, e.g. <code>SH256</code>
; customcerts/@CSRdn-cn : the CN (''common name'') part used for the DN
; customcerts/@CSRdn-ou : the OU (''organizational unit'') part used for the DN
; customcerts/@CSRdn-o : the O (''organization'') part used for the DN
; customcerts/@CSRdn-l : the L (''locality'') part used for the DN
; customcerts/@CSRdn-st : the ST (''state or province'') part used for the DN
; customcerts/@CSRdn-c : the C (''country'') part used for the DN (note: ''CSRdn'' for many CAs, must be a 2-letter ISO country code)
; customcerts/@CSRsan-dns-1 : the first of up to three DNS names
; customcerts/@CSRsan-ip-1 : the first of up to two IP addresses

Within the set of CSR attributes, the following meta-words will be replaced:

* <code>{realip}</code> : the real IP address of the device as reported in the <code>ip=#i</code> query argument
* <code>{ip}</code> : the IP address of the device as seen by the update server
* <code>{proxy}</code> : the IP address of the reverse proxy the device used to reach the update server
* <code>{sn}</code> : the serial number of the device as reported in the <code>sn=#m</code> query argument (e.g. <code>009033030df0</code>)
* <code>{hwid}</code> : the hardware-id of the device as reported in the <code>sn=#m</code> query argument (e.g. <code>IP1200-03-0d-f0</code>)
* <code>{name}</code> : the ''Device Name'' (set in ''General/Admin'') of the device
* <code>{rdns}</code> : the DNS name found in a reverse DNS lookup for the real-ip address reported by the device (see ''{realip}'') above

<code xml>
<customcerts
dir="certs"
CAkeys="CAkey*"
CAtype="manual"
CAname="innovaphone-INNO-DC-W2K8-Zertifizierungsserver"
CAnamesep=","
CAwildcard="*.innovaphone.com"
CSRkey="2048-bit"
CSRsignature="SH256"
CSRdn-cn="{hwid}"
CSRdn-ou=""
CSRdn-o=""
CSRdn-l=""
CSRdn-st=""
CSRdn-c=""
CSRsan-dns-1="{name}.company.com"
CSRsan-dns-2="{hwid}.company.com"
CSRsan-dns-3="{rdns}"
CSRsan-ip-1="{realip}"
CSRsan-ip-2=""
renew="90" />
</code>

==== queries ====
If queries are defined and applicable for the calling device, it will be instructed to send certain information to the update server which will be stored in the device status file kept on the server. Each piece of such information is defined usign a separate ''query'' tag.

; queries/@scfg : defines to URL used by the device to send the information. Normally not changed from the default
==== queries/query ====
Defines one piece of information to be submitted to the update server.

; queries/query/@id : a unique name for the query
; queries/query/@title : a title for this piece of information shown in the device status

<code xml>.

<query id="media" title="Media">
<cmd>mod cmd MEDIA xml-info</cmd>
<applies>*</applies>
<show title="NAT">concat(/state/queries/media/info/nat/@result, ' (', /state/queries/media/info/nat/@public-addr, ')')</show>
<show title="Server">concat('STUN: ', /state/queries/media/info/@stun, ' TURN: ', /state/queries/media/info/@turn, ' (', /state/queries/media/info/@turn-user, ')')</show>
</query>


<query id="registration" title="Registration">
<cmd>mod cmd PHONE/USER phone-regs /cmd phone-regs</cmd>
<applies>phone</applies>
<show title="State: User/Number">concat(/state/queries/registration/info/reg[@id = "0"]/@state, ': ' , /state/queries/registration/info/reg[@id = "0"]/@h323, '/', /state/queries/registration/info/reg[@id = "0"]/@e164)</show>
<show title="PBX/ID">concat(/state/queries/registration/info/reg[@id = "0"]/@gk-addr, '/', /state/queries/registration/info/reg[@id = "0"]/@gk-id)</show>
</query>
</code>

==== queries/query/cmd ====
The content of this tag defines the command to be executed on the device which outputs the requested information. These are ''mod cmd''s typically.

<code xml>

<cmd>mod cmd X509 xml-info</cmd>
</code>

See [[Howto:Effect_arbitrary_Configuration_Changes_using_a_HTTP_Command_Line_Client_or_from_an_Update#Using_the_Mechanism_for_Device_Status_Queries ]] for details on how to find out whicgh commands to use.

==== queries/query/applies ====
Defined queries are only executed by devices which belong to the class that is given as tag content. If the ''env'' atribute is set, the tag content is interpreted as an ''environment'' name which has to match.

; queries/query/applies/@env : if this attribute exists, the tag content is compared with the environments the device is in. Otherwise, it is compared with the classes it is in (unfortunately, you can not combine bith)
<code xml>

<applies>phone</applies>
</code>

==== queries/query/show====
If one or more ''show'' tags are defined for the ''query'' tag, the data will be shown in the device status page. The values shown are defined by the tag content which is an XPath expression selecting the data from the device state. The XPath expression always begins with <code>/state/queries/</code>''query-id'' (as defined by the ''id'' attribute in the query tag).

; queries/query/show/@title : used as title when the values are displayed in the status page

<code xml>
<show title="NAT">concat(/state/queries/media/info/nat/@result, ' (', /state/queries/media/info/nat/@public-addr, ')')</show>
</code>

== 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
: you need to use build 2000 or higher. Older versions are described in [[Howto:PHP_based_Update_Server]]

== Hints for writing your update snippets ==
Writing update scripts is largely undocumented and sometimes tricky. Here are some general guidelines.

=== Using <code>config add/del</code> ===
Many setting are done using <code>config change</code> commands. So these are very useful in update scripts too.

The straight forward method to find out which commands you need is as follows:
* get a device of the type in question and do factory reset
* save the configuration to a file
* do the desired settings using the normal web admin UI
* save the resulting configuration to another file
* compare the saved files

Usually, you want to set only specific parts of the configuration line. For example, assume you want to set the default coder to ''OPUS-WB''. Your saved configuration line might look like

config change PHONE SIG /prot SH323 /gk-addr pbx.innovaphone.com /gk-id innovaphone.com /tones 0 /lcoder OPUS-WB,20, /coder OPUS-WB,20,k1

To set only the coder settings, you would set the relevant options with the <code>config add</code> command as follows:

config add PHONE SIG /lcoder OPUS-WB,20,
config add PHONE SIG /coder OPUS-WB,20,k1

You can also remove specific options, as in

config rem PHONE SIG /tones

which would remove the <code>/tones 0</code> from the configuration line for <code>PHONE SIG</code>.

Note that the PHP update server will add the

config write
config activate
iresetn

at the end of the delivered script automatically, so you do not need to do it yourself. In fact, it is not recommended to have any reset command in your snippets.

==== <code>config change</code> Lines with associated Passwords ====
Sometimes, there is a password associated with certain configurations. Consider the STUN/TURN configuration:

config change MEDIA /stun stun.innovaphone.com /turn turn.innovaphone.com /turn-user innovaphone /turn-pwd 2 /nat-detect 61

The TURN password, being sensitive, needs to be encrypted in your configuration. This is why it is stored as a ''VAR'', which provides encryption support (see below):

vars create MEDIA/TURN-PWD pc ....

Unfortunately, the relationship between an option and an associated VAR needs to be guessed. You can be sure that the module name in the <code>config changey</code> matches the modules name in the <code>vars create</code> command. However, the variable name mist be guessed.

You can also set the password in your script using the <code>vars create</code>, however, you may also consider using a <code>mod cmd</code> (see below) such as e.g.

mod cmd MEDIA form /cmd form /del %2Fstun-slow /stun stun.innovaphone.com /turn turn.innovaphone.com /turn-user innovaphone /turn-pwd my-turn-pw /nat-detect 61

=== Using <code>vars create</code> ===

Sometimes it makes sense to use <code>vars create</code> commands. The syntax is

<code> vars create </code>''<name> <flags> <value>''

A ''<name>'' is a module name followed by a variable name, optionally followed by an index. For example, a phone will store the currently selected main registration as <code>vars create PHONE/ACTIVE-USER p </code>''<index>''. So the module is <code>PHONE</code> and the variable name is <code>ACTIVE-USER</code>. When the variable is multi-valued, an index is added to the name. For example, the registration settings for all but the first registration are stored as indexed variable, as in <code>vars create PHONE/USER-REG/00001 p </code>''<settings>'', where <code>00001</code> is the index (registrations count from 0 in this case).

There are a number of flags which can be combined, the most prominent used in update scripts are:
; p : permanent. The var is stored in flash memory (you will almost always use this flag in update scripts)
; c : crypted. The var value needs to be encrypted and the ''<value>'' given is crypted
; x : crypted, plain value. The var needs to be encrypted but the ''<value>'' is given as plain (that is, un-encrypted) text. This allows you to set an encrypted variable without encrypting the desired value
; b : binary. The var value is binary. Its ''<value>'' is given as a bin2hex string

Please note that using <code>vars create</code> will ''always'' set the internal ''reset needed condition'' in the device (regardless which ''<value>'' is set). This means that a subsequent <code>resetn</code> or <code>iresetn</code> will always trigger a reset. So if you use it, make sure that you use the ''times/@check'' ([[#times | see above]]) to protect your script from re-executing the snippet (and thus rebooting the device) all the time.


=== Using <code>mod cmd</code> ===
See [[Howto:Effect arbitrary Configuration Changes using a HTTP Command Line Client or from an Update]] for a discussion of how to use <code>mod cmd</code> in update scripts.

=== Writing your own Dynamic Scripting Code ===
NB: this feature is available from build 2020.

By default, the update server delivers update scripts which are composed from a number of static files (so-called ''snippets''). Sometimes it makes sense however, to create such snippets dynamically (e.g. based on a database lookup). Here is how to do this.

Dynamic scripting is implemented by a user-supplied custom <code>class CustomUpdateSnippet</code>. The code for this class must be placed in to the file <code>config/scripting.class.php</code>. As a starter, sample class code is available in <code>config/sample.scripting.class.php</code>.

<code php>
<?php

/**
* to provide your own runtime generated snippets, rename this file to 'scripting.class.php' and
* implement the member functions
* $property will have one member called
*/

class CustomUpdateSnippet extends UpdateSnippet {

/**
* snippet to deliver after standard text snippets
* @return array of string
*/
public function getPostSnippet() {
return parent::getPostSnippet();
}

/**
* snippet to deliver before standard text snippets
* @return array of strings
*/
public function getPreSnippet() {
return parent::getPreSnippet();
}

/**
* do we want to suppress the standard text snippets?
* @return boolean
*/
public function sendStandardSnippets() {
return parent::sendStandardSnippets();
}
}
?>
</code>

The sample code overrides of the classes member functions just call the base classes which do nothing at all. So if you just copy the sample code into <code>scripting.class.php</code>, nothing will change. However, if <code>getPreSnippet()</code> returns an array of strings (the parent class function returns an empty array), each array member will be sent to the calling device ''before'' the standard snippets are sent. Likewise, if <code>getPostSnippet()</code> returns an array of strings (the parent class function returns an empty array), each array member will be sent to the calling device ''after'' the standard snippets are sent. If <code>sendStandardSnippets()</code> returns false, the standard snippets will not be sent.

To determine the dynamic snippets to send, the user-provided <code>class CustomUpdateSnippet</code> has access to the members of its base <code>class UpdateSnippet</code>, namely the <code>var $statexml</code> member. This member contains a <code>SimpleXMLElement</code> object with all state information available for the calling device.

Here is a sample state found in <code>$statexml</code> (as output by the <code>dump()</code> member function):

<code xml>
<?xml version="1.0"?>
<state seen="1522065435" requested="130774bootcode" phase="update">
<device sn="00-90-33-3e-0c-57" type="IP112" classes="phone, opus_phone, phone_newui, hstrace, ip112" ip="127.0.0.1" rp="false" phase="update" environments="sifi, 172net" certstat="either certificate handling or state tracking not enabled - not doing any certificate checking" hwid="IP222-46-5c-77" realip="172.16.80.241" requestDownloaded="false"/>
<firmware requested="130986" requested-at="1522065435"/>
<bootcode requested-at="1522065435"/>
<config filename="scripts/all-all-all.txt" delivered="1522065426" version="1486559970"/>
</state>
</code>

The most interesting elements in this XML are probably the attributes of the <code>state</code> and the <code>device</code> tags.

== Optional Configurations on the Linux Application Platform ==
===Support for more Connections===
By default the LAP's web server lighttpd allows for 512 concurrent connections with 1024 open file descriptors. When you serve a huge number of devices with the update server, then this might be too low. You will see some devices not being able to contact the update server for a while. This should not be a real issue as the devices will retry. However, updating all devices may take long due to this.

In the lighttpd log (in <code>/var/log/lighttpd</code> on the LAP), you will see entries like this:

2017-10-16 13:45:18: (network_linux_sendfile.c.140) open failed: Too many open files
2017-10-16 13:45:18: (mod_fastcgi.c.3075) write failed: Too many open files 24
2017-10-16 13:45:18: (server.c.1434) [note] sockets disabled, out-of-fds
2017-10-16 16:23:25: (response.c.634) file not found ... or so: Too many open files /mtls/updatev2/web/innovaphone_logo_claim_fisch.png ->
2017-10-16 17:57:45: (server.c.1432) [note] sockets disabled, connection limit reached

If you experience such issues, proceed as follows:

* connect to the LAP with SFTP (e.g. using WinSCP)
* change directory to <code>/etc/lighttpd</code>
* edit <code>lighttpd.conf</code>
* search for the 2 lines which set <code>server.max-fds</code> and <code>server.max-connections</code>
* replace the standard values. We recommend to set the number of file descriptors to 4 times the number of requests when using the update server, e.g.
: old
:: server.max-fds = 1024
:: server.max-connections = 512
: new
:: server.max-fds = 8000
:: server.max-connections = 2000
* save the file
* restart linux (''Diagnostics/Reset/Reboot'')

Be sure to closely monitor the ''Diagnostics/Status'' page for a while after such configuration.

Also, when you update the LAP, you will have to re-do the changes (as always when you change something ''under the hood'').

=== Debug files rotation based on logrotate ===
If you have to debug during operation and a lot of devices access the PHP Update Server V2, you have to keep track of the debug files or automatically limit them. For this you can use logrotate on the innovaphone Linux AP. With logrotate you can apply time-based or size-based rules when files are packed and when they are deleted.
* open the LAP's file system using a SFTP client such as e.g. [https://winscp.net/eng/index.php WinSCP] (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]]). Note that you must use SFTP rather than WebDAV, as WebDAV will not give access to the executable web server files.
* Under the path <code>/etc/logrotate.d</code> create a file e.g. <code>updateserver</code>.

<code>/etc/logrotate.d/updateserver</code>

In this file now enter the following content and save it.

<code>
/var/www/innovaphone/mtls/update/debug/*.txt {
size 5M
missingok
rotate 2
compress
delaycompress
notifempty
create 644 www-data www-data
}
</code>

This will include all *.txt files from the debug directory of the PHP Update Server V2 in the logrotate process of the operating system.

; size 5M : means every 5MB the file is rotated or zipped
; size 5k : means every 5kB the file is rotated or zipped
Alternatively, you can also rotate the file based on time
; daily : means that every day the file is rotated or zipped
; weekly : means that the file is rotated or zipped daily

; missingok : if a debug file does not exist, it will be ignored
; rotate n : files are removed before the last ones are deleted.
; compress : compresses the old debug files
; delaycompress : compresses the debug data only after it has been moved once
; notifempty : empty log files are not rotated
; create 644 www-data www-data : creates a new, empty debug file with appropriate permissions

== Update Server and Reverse Proxy ==
It is possible to implement access to the update server through a ''reverse proxy'' (RP). However, you have to keep some issues in mind:
* ''Mutual Transport Layer Security'' (MTLS) is not possible
: MTLS requires a direct TLS connection between the two parties. An RP however would terminate the TLS connection and entertain two independent connections to the parties. This breaks MTLS. If you want to use MTLS and serve external clients, you must therefore provide a direct access to the update server (that is an external IP address either directly or through port forwarding)
: see [[#If_you_want_to_setup_MTLS-restricted_Delivery_of_Update_Scripts]] for details
* When using the RP, you can choose to forward encrypted traffic (HTTPS) arriving from external to the update server using HTTP (unencrypted). The update server however eventually rewrites the update URL in the calling devices configuration. In order to do this, it determines the type of the internal connection. So if the connection from the RP to the update server is using HTTP, it would create a ''http://...'' URL. Otherwise it would create an ''https://..'' URL (also, it would be using the same port). This way, if the RP forwards requests to the update server with HTTP, the synthesized new URL for the calling client would use HTTP too, even though the original request was sent with HTTPS. This may or may not be what you want (as all of your clients would end up using non-encrypted traffic). Even worse, it might not work at all, if the RP does not accept HTTP for example.

== Related Articles ==
* [[Reference10:Concept_Update_Server]]
* [[Reference12r1:DHCP_client]]
* [[Reference10:Concept_Linux_Application_Platform]]
* [[Reference10:Concept_Provisioning]]
* [[Howto:PHP_based_Update_Server]] (old version)
* [[Howto:Creating custom Certificates using a Windows Certificate Authority]]
* [[Howto:Effect arbitrary Configuration Changes using a HTTP Command Line Client or from an Update]]

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

Howto:Multiple faxserver instances sharing a FAX interface

2017-10-30T12:36:32Z

Odawid: /* Configuration */

This document explains the configuration of multiple faxserver instances of the [[Reference10:Concept_Faxserver | innovaphone fax]] solution using the same FAX Interface at an Innovaphone Gateway.

== Summary ==
In case you have multiple faxserver instances but just a single FAX Interface and those faxserver instances should share this FAX Interface you might run into the problem of receiving the error message “sfftobmp failed, exit code 2”. This wiki article should explain how to salvage the situation.

== Applies To ==
This information applies to the Linux application [[Reference10:Concept_Faxserver | innovaphone Fax]] V10 and innovaphone firmware V10 and later.

== Configuration==
First of all let’s take a look at the Linux AP. In my case I have three different faxserver instances.

[[Image:Multiple faxserver - one FAX interface 1.png]]

Each faxserver instance is monitoring a different faxserver gateway object in the PBX. In the case of the screenshot it’s the Faxserver1 gateway object.

[[Image:Multiple faxserver - one FAX interface 2.png]]

The next steps have to be done at the PBX. We need to create the corresponding faxserver gateway object. As you see in the screenshot they have an active internal registration. 3 different GW Interface are registered at those gateway object. (don’t forget to turn on T38).

[[Image:Multiple faxserver - one FAX interface 3.png]]

Furthermore the Query User (_TAPI_) needs to be active in the same group as the faxserver gateway objects.
The tricky part is done in the routing table as you can see in the screenshot. We are adding prefixes in the route to the FAX Interface and we are subtracting the prefix of the CGPN in the outbound route. Verify CGPN needs to be active to route those calls correctly.

[[Image:Multiple faxserver - one FAX interface 4.png]]

In the end don’t forget to set T38 or Audio FAX support at the FAX interface.

== Related Articles ==
[[Reference10:Concept_Linux_Application_Platform | Reference: Linux Application Platform]]

[[Reference10:Concept_Faxserver | Reference: Faxserver]]

[[Howto:Step-by-step_faxserver_installation | Howto: Step-by-step faxserver installation]]

[[Howto:Faxserver_with_Exchange | Howto: Faxserver with Exchange]]

Howto:A rough estimate of IPVA Performance

2014-03-05T15:08:26Z

Odawid: /* Releated Articles */

==Applies To==
This information applies to

* IPVA



==More Information==
===Problem Details===
In many projects, the potential performance of an IPVA running on a PC hardware needs to be calculated. Here are some thoughts.

Of course it all depends on what you are doing on the machine. So there is no easy answer to it.

But, if you compare a PC-box to an IP6010, then

* RAM on the 6010 is .5 Gig, so spend 1GB for an equivalent IPVA (so as to have room for overhead etc.)
* Flash is not an issue as it is mapped on disk space (which we probably have plenty of)
* leaving us with CPU. Just assume an IP6010 runs with 800MHz, a standard Quad Core runs on 2.66GHz. Assume it has really 4 independent cores (not just those pseudo-cores), then this amounts to 13 times the cycles of an IP6010

Looking at the available CPU cycles, it looks as if we can run 13 IP6010 on a PC platform. To be a little conservative and to account for overhead that may be caused by running mutliple IPVA on this one box (which may or may not be appropriate, depedning on your scenario), lets estimate the overall performance as 10 times an IP6010. Cross check: 1GB RAM times 10 is 10GB, fits in your PC RAM.

One thing to take into account is that the innovaphone operating system is a single-processor OS. So it will always run on a single CPU. It is thus impossible to utilize 4 cores with a single IPVA.

So here is your limit, ''if you utilize the full resources that a 6010 would give you'', then you may run 10 VMWare instances where each of them does the job of a single IP6010. Or, you can create 4 IPVAs with each 2.5 times the performance of an IP6010.

This of course is a little rough (as we compare Intel CISC and MIPS RISC CPU cycles here, we ignore memory performance, ...). But - given the fact that it is anyway a rough estimate as it really depends on the usage - it is good enough.

Of course, we have left out some parameters, e.g. network performance and bandwidth. Although you may use a PC box which has slightly better Ethernet performance than an IP6010, it will not be significant. Assume even it is 50% better, this is nothing compared to the ''times 10'' factor we have otherwise. So do we have a bandwidth problem? Now, in a normal use-case, Ethernet bandwidth is simply not an issue, as call signalling (that's what a PBX does) is neglect-able from a bandwidth perspective. However, if it comes to media streams, things are different. Assume we have a media stream using G.722 or G.711, both use 64k net bandwidth per direction. This makes for approximately 100k effectively (that is, including protocol overhead) for one direction. Now let us do the maths: an IP6010 has an 100Mb interface (full duplex, so 200Mb for both directions). This is good for 1000 calls. 10 times more makes for 10000 calls. Can we do this? First of all, a PC box will sport a Gigabit interface, so yes, we could. More important: no IP6010 will ever run 1000 parallel media streams (we recommend no more than 72), so the bottom line is: not an issue.

So then, you could ask: is it better to run a single IPVA with huge memory or split it up in several smaller ones? Well, good question!
The answer is: hmmm.

There are limits to the sheer number of VMware instances on a single system, but they are changing. So consult your VMware/VSphere documentation. Otherwise, we recommend to base your decision on the usage scenario. If it is benefitial to have multiple PBXs (e.g. cause you are supporting separate customers with distinct numbering plans), then do so. If you merely think you should split up PBXs (e.g. in masters/slaves) cause you needed to do so when using IP6010, then no, you should not do so any more. After all, having 2.5 times the performance of an IP6010, you may support a single PBX with 8.000 registered users on our reference PC, or a master and 3 slaves with a total of 32.000 users. That should suffice for a while. And no, we have not yet seen such an installation in practice...

Finally, if you can run a single huge PBX, can you also run a huge number of small PBXs? Again, this mainly depends on the VMware platform. According to the VMware documentation (this is based on VSphere 4.1), there is a limit of ''320 Virtual machines per host''. But there are other limits also (such as ''Virtual CPUs per core'' etc.). Another approach is to consider that a single PBX should not have less CPU performance available than, say, half of an IP30x. This would amount to 75MHz. On our reference PC (2.66GHz times 4) this would indicate to run no more than 140 IPVAs. This seems to be a reasonable load for VMware.

=== Releated Articles ===
* [[Reference10:Concept Innovaphone Virtual Appliance]]
* [[Howto:Implement PBX with zero downtime using IPVA and VMWare Fault Tolerance]]
* [[Howto:Hosting]]
* [[Howto:How to implement large PBXs]]

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

Reference9:Phone/Preferences

2011-06-08T12:58:55Z

Odawid:

* '''Background Image''': Only on phones with colour display supported. A URL to a picture - in '''png''' format with the size of the Display - stored at a web server (e.g CF card) must be entered. The IP241 and IP222 having a display size of 320px (width) and 240px (height). The IP232 has a display size of 480 x 272. '''Important is that you need a png file with exactly the size from the display. Otherwise the phone does not display the customized background.'''
* '''No Call Transfer on Hook-On''': By default going on hook or pressing the speaker or the headset key initiates a call transfer when there exist both an active call and a connected call on hold. If this checkmark is set both calls are released when going on hook. A call transfer can be initiated by the R-4 key sequence then ('R' (flash) key immediately followed by the digit 4).
* '''No Local Conference Tone''': By default a conference tone is merged into conversation when a conference is established. Frequency, volume and pattern of this tone depend on the configured dial tone scheme. If this checkmark is set no conference tone is generated when the phone itself establishes a conference.
* '''No Local Intrusion Tone''': By default an intrusion tone is generated to notify the user about a call intrusion. If this checkmark is set no intrusion tone is generated the phone itself.
* '''Display Name on Pickup/Partner Key''': By default the number of the calling/called/connected party is displayed in the label field of a partner or pickup function key. If this checkmark is set the 'Name' attribute from the PBX user object (if available) is displayed instead.
* '''Start Outbound Call on Electronic Hook Switch (EHS) Signal''': A wireless headset usually has an Electronic Hook Switch button. If the base station of the headset is attached to the phone via the DHSG interface the phone receives a hook switch signal whenever the button is pressed. By default this signal is ignored when the phone is in idle mode. When sitting in front of phone it's quite inconvenient to set up a call by pressing this button, when being far from phone no digits can be dialled. But in some cases it can be useful to set up a call, for example when the phone is configured for direct dialling. If this checkmark is set the Electronic Hook Switch Signal will set up an outbound call when the phone is in idle mode.

Freeedit:Wiki Edit Sandbox

2010-06-10T17:39:32Z

Odawid:

This is a dummy article to safely try editing wiki articles.

Marc Bau '''Voxtron'''

Burbuqe Kadriu '''EFG Financial Products AG'''

Michael Scheer '''Innovaphone AG'''

Patrick Montaine '''Ball Packaging Europe'''

Christoph Anhorn- '''swisspro AG'''

= Wiki Syntax ([[Help:Formatting|more about formatting]], [[Help:Contents|generic help]]): =

Italic ''word'': <code>''word''</code> 
Bold '''word''': <code>'''word'''</code> 
:Indented line: <code>:line</code> 

# numbered list item: <code># list item</code>
## numbered list sub item: <code>## list item</code>

* dotted list item: <code>* list item</code>
** dotted list sub item: <code>** list item</code>

hidden search tag:  <code></code>

= Play Arena =

Mathias Kropf, '''Ascom Deutschland''' 
Dirk Pedina, '''Telekommunikation Mittleres Ruhrgebiet GmbH''' 
Andre Lippitz, '''Sec Com GmbH Recklinghausen''' 
Manfred Mauler, '''ACP IT Solutions GmbH, Innsbruck''' 
Christoph Nyffenegger, '''Ascom Schweiz AG''' 
John Larsen '''Ascom Denmark A/S'''

Johann Kiss, '''Triple AcceSSS IT GmbH, Austria''' 
Marco Koch, '''Wrocklage Intermedia GmbH Germany''' 
Frank Schneebeck, '''ETe Datentechnik GmbH Germany''' 
Christoph Hanken, Paragon Data GmbH
Jonas Teckentrup, Paragon Data GmbH
Porretta Mauro, '''SARTE S.p.A. Italy''' 
Kevin Edmonds, '''Consult Partner GmbH''' 
Karsten Otto, '''westko network service GmbH''' 
Arne Stark, '''westko network service GmbH''' 
Henk Schuurman, '''Soft Solutions''' 
Marko Röhncke, '''Kevag-Telekom GmbH''' 
Kristijan Fabina, '''Datentechnik d.o.o.''' 
Dirk Lange, '''Nachrichtentechnik Bielefeld GmbH''' 
Ludwig Kempter, '''LEWTelNet GmbH''' 
Sakari Aaltonen, '''DigiCenter''' 
Jukka Somiska, '''Daimler Finland''' 
Gisbert Cremerius, '''Hack-Attack''' 
Massimiliano Tamaro '''Test s.p.a Italy''' 
Marco Boschi '''Eksaip Vicenza''' 
Stig Aune, '''Stig Aune Consulting''' 
Sandro Haas, '''KufGem EDV GmbH''' 
Daniel Haidacher, '''KufGem EDV GmbH''' 
Marc Steiner, '''Inikon AG''' 
Johan de Jong, '''trizwo GmbH''' 
René Scholz, '''Ascom''' 
Rocco Schmidt, '''ATS Ascom''' 
Marcel Britten, '''Connect GmbH''' 
Hans-Joachim Haun, '''VB OLD''' 
Marco Falger, '''Koch Media GmbH''' 
Swen Angelstein,'''ST.AG''' 
Arne Schmidt, '''TELCAT Multicom GmbH''' 
Liang Zhang, '''Koch Media GmbH''' 
Dirk-Jan van Dalen, '''Telematch BV''' 
Edwin Lansbergen, '''Telematch BV''' 
Benjamin Köhler, '''iits GmbH & Co. KG''' 
Christian Bengtsson, '''COBS AB. Sweden''' 
Sebastian Lutz, '''Oberberg-Online Informationssysteme GmbH''' 
Paul Schrok, '''Ascom Suisse SA''' 
Andreas Moser, '''EFG Financial Products AG''' 
Paul Schrok, '''Ascom Suisse SA''' 
Dennis Moller '''Ascom Denmark''' 
Andre Pooschke '''Fundamental Consulting GmbH & Co. KG''' 
Roman Pietrowski '''Bohnen Computer-Technik GmbH''' 
Oliver Dawid '''ComNet GmbH'''

Freeedit:Wiki Edit Sandbox

2010-06-10T17:38:38Z

Odawid:

This is a dummy article to safely try editing wiki articles.

Marc Bau '''Voxtron'''

Burbuqe Kadriu '''EFG Financial Products AG'''

Michael Scheer '''Innovaphone AG'''

Patrick Montaine '''Ball Packaging Europe'''

Christoph Anhorn- '''swisspro AG'''

Oliver Dawid '''ComNet GmbH'''

= Wiki Syntax ([[Help:Formatting|more about formatting]], [[Help:Contents|generic help]]): =

Italic ''word'': <code>''word''</code> 
Bold '''word''': <code>'''word'''</code> 
:Indented line: <code>:line</code> 

# numbered list item: <code># list item</code>
## numbered list sub item: <code>## list item</code>

* dotted list item: <code>* list item</code>
** dotted list sub item: <code>** list item</code>

hidden search tag:  <code></code>

= Play Arena =

Mathias Kropf, '''Ascom Deutschland''' 
Dirk Pedina, '''Telekommunikation Mittleres Ruhrgebiet GmbH''' 
Andre Lippitz, '''Sec Com GmbH Recklinghausen''' 
Manfred Mauler, '''ACP IT Solutions GmbH, Innsbruck''' 
Christoph Nyffenegger, '''Ascom Schweiz AG''' 
John Larsen '''Ascom Denmark A/S'''

Johann Kiss, '''Triple AcceSSS IT GmbH, Austria''' 
Marco Koch, '''Wrocklage Intermedia GmbH Germany''' 
Frank Schneebeck, '''ETe Datentechnik GmbH Germany''' 
Christoph Hanken, Paragon Data GmbH
Jonas Teckentrup, Paragon Data GmbH
Porretta Mauro, '''SARTE S.p.A. Italy''' 
Kevin Edmonds, '''Consult Partner GmbH''' 
Karsten Otto, '''westko network service GmbH''' 
Arne Stark, '''westko network service GmbH''' 
Henk Schuurman, '''Soft Solutions''' 
Marko Röhncke, '''Kevag-Telekom GmbH''' 
Kristijan Fabina, '''Datentechnik d.o.o.''' 
Dirk Lange, '''Nachrichtentechnik Bielefeld GmbH''' 
Ludwig Kempter, '''LEWTelNet GmbH''' 
Sakari Aaltonen, '''DigiCenter''' 
Jukka Somiska, '''Daimler Finland''' 
Gisbert Cremerius, '''Hack-Attack''' 
Massimiliano Tamaro '''Test s.p.a Italy''' 
Marco Boschi '''Eksaip Vicenza''' 
Stig Aune, '''Stig Aune Consulting''' 
Sandro Haas, '''KufGem EDV GmbH''' 
Daniel Haidacher, '''KufGem EDV GmbH''' 
Marc Steiner, '''Inikon AG''' 
Johan de Jong, '''trizwo GmbH''' 
René Scholz, '''Ascom''' 
Rocco Schmidt, '''ATS Ascom''' 
Marcel Britten, '''Connect GmbH''' 
Hans-Joachim Haun, '''VB OLD''' 
Marco Falger, '''Koch Media GmbH''' 
Swen Angelstein,'''ST.AG''' 
Arne Schmidt, '''TELCAT Multicom GmbH''' 
Liang Zhang, '''Koch Media GmbH''' 
Dirk-Jan van Dalen, '''Telematch BV''' 
Edwin Lansbergen, '''Telematch BV''' 
Benjamin Köhler, '''iits GmbH & Co. KG''' 
Christian Bengtsson, '''COBS AB. Sweden''' 
Sebastian Lutz, '''Oberberg-Online Informationssysteme GmbH''' 
Paul Schrok, '''Ascom Suisse SA''' 
Andreas Moser, '''EFG Financial Products AG''' 
Paul Schrok, '''Ascom Suisse SA''' 
Dennis Moller '''Ascom Denmark''' 
Andre Pooschke '''Fundamental Consulting GmbH & Co. KG''' 
Roman Pietrowski '''Bohnen Computer-Technik GmbH'''