innovaphone wiki - User contributions [en]

Reference16r1:Concept myApps

2026-06-29T09:01:53Z

Ckl: /* Storage and format */

[[Category:Concept|myApps]]
[[Category:Concept_myApps]]
==Applies To==
This information applies to
* innovaphone PBX from version 16r1
= Overview =
innovaphone myApps is the client software for innovaphone users and administrators. The base functionality is provided by a web application that is loaded from the PBX. Additionally there are [[{{NAMESPACE}}:Concept_myApps_platform_services|installable versions for Windows, Android, macOS and iOS]] that come with an integrated browser and implement adaptations to the local operating system.

The purpose of myApps is to organize and run apps. All productive functionality is provided by additional apps that run inside myApps.
== Requirements ==
=== Web version ===
For opening myApps in the web browser you need the most recent version of one of the following browsers:
* Chrome
* Firefox
* Safari
* or Edge
The following browser features are required and must not be disabled:
* JavaScript
* HTML5 Local Storage

=== Native versions ===
myApps can also run as native executables on Windows (myApps for Windows), iOS (myApps for iOS), macOS (myApps for macOS) and Android (myApps for Android). In this case, myApps platform services are available and provide additional features. The myApps Web version then runs in a web view window embedded in this native client. See [[{{NAMESPACE}}:Concept myApps platform services|myApps platform services overview]] for more information.

=== Licenses ===
* No license needed for myApps itself
* Apps might require licenses

=== Account ===
* A user account (user object) on the PBX is needed in order to use myApps.

=== Reverse proxy ===
For access from the public internet, the reverse proxy must be configured to allow access to the following paths on the PBX.
; /PBX0/APPCLIENT/appclient.htm
: The myApps client itself
; /PBX0/session
: Needed for two-factor authentication using email
; /PBX0/APPS
: Needed for apps loaded from the PBX (e.g. softphone and chat) and for apps that use PBX APIs
; /OAUTH2/oauth2_login
: Needed for OAuth2 authentication

== Features ==
myApps comes with the following features:
* User login including two-factor authentication.
* Display and set the own presence (on the home screen and when the focus app is shown).
* List of all available apps including search functionality.
* Running apps (inside an iframe).
* Apps can be pinned to the main window. Pinned apps are always running and can't be closed. They are also started automatically when the myApps client is loaded.
* The "app focus" can be used to define a default app for the user. It is started and shown automatically when myApps is loaded. When closing other apps the app is shown instead of the home screen.
* Detaching apps in myApps for Windows and myApps for macOS. Detached apps are opened in a separate window.
* Home screen with user-selected apps and app items that can be organized in collapsible groups.
* Push notifications sent by app services.
* List of all myApps-Logins. Unused or suspicious sessions can be logged out remotely.
* Color scheme selection (light, dark).
* Configuration of standard apps for certain functions (like phone calls or chat).
* Link to account specific settings provided by a separate app (profile).
* Dialogue guidance in following languages: Català, Ceština, Deutsch, English, Español, Euskara, Français, Italiano, Nederlands, Polski, Português, Româna, ??????? ????, Slovenšcina, Türkçe
* Screen reader compatiblity and keyboard control
* Interactive, clickable onboarding tour to guide users through the client's structure and key features.

All other functionality is provided by apps. For example phone calls require a phone app. Chats require a chat app.

= Details =
== Connecting to the PBX ==
The myApps web application is loaded from the PBX. The corresponding URL for opening myApps in a browser is
https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm
The installable versions ask for the "server name" on the first startup. Enter the host name of the PBX to proceed to the login screen.
You can change the server afterwards by logging out and clicking the "Change server" link on the login screen.

== Supported URL Parameters ==
Some parameters can be specified with the URL in both the query string or fragment identifier. Those parameters are intended for internal use in the myApps launcher and automated testing. However they could be useful for special applications.

https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm?lang=de

https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm#lang=it

Supported parameters:

;lang:The two-letter code of the desired myApps language ("en", "it", "fr", "de", ...)
;scheme:The color scheme ("light", "dark").
;app:An app link to be started (e.g. "chat").
;usr:The user name for login. Note that this will create a new permanent session at the user object. Should only be used in the fragment identifier.
;pwd:The password for login. Note that this will create a new permanent session at the user object. Should only be used in the fragment identifier.
;inactiveTimeout:Overrides the general timeout for the "auto appear offline" feature in browsers. Sets a timeout in milliseconds that shall be used before the user goes offline. Setting it to 0 disables the "auto appear offline". Browser version only. Available from 13r2 SR11.
;phys: User defined physical location for Softphone Apps

Example:

https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm?lang=de&scheme=light&app=chat#usr=john.doe&pwd=secret

== Redirect to the user's PBX==
If the logged-in user is not on the current PBX, myApps will be redirected to the user's PBX (as configured in the pbx attribute of the user). The following rules apply:
===Master-Slave scenario===
* Slave PBXes redirect to the master PBX.
* The master PBX redirects to the correct slave PBX.

Note: If the current PBX has no registration to the redirect target PBX but knows the user, it will act as a standby and keep the connection, until the registration is up gain.

===Standby scenario===
See [[Reference16r1:Concept_myApps_Redundancy]]

== Deployment of settings ==
The administrator can deploy some general settings to be used as a default by all myApps clients. This can be done in the admin UI on page PBX/Config/myApps. See [[Reference13r1:PBX/Config/myApps]] for details.

== Authentication and security ==
For using myApps you need an account (user object) on the pbx with a password. For logging-in you need to enter the username (SIP-URI) or email address and the password.

=== Permanent sessions ===
On each successful login on a new browser or new device a permanent session is created that is defined by a session id and a session password. Those are stored both in the local storage of the browser and at the user object in the PBX. If the user closes myApps and opens it again, the stored session is used. Only when logging-out the session is deleted in both places and the login screen is shown again.

Notes:
* The user password is never transmitted over the network or permanently stored in the browser.
* The PBX stores up to 12 persistent sessions per user. When the limit is reached, creating a new session removes the session with the oldest login timestamp.

The user can keep track of all his permanent sessions in the myApps menu under "Account security". Sessions that are not needed anymore can be deleted here. The corresponding browser or device is logged out on-the-fly.

=== Two-factor authentication ===
The purpose of two-factor authentication is to maintain an additional level of security that prevents attackers form logging-in even if they compromised a users password. Therefore we strongly recommend to use it.

It can be activated during installation of the PBX or in the admin UI under PBX/Config/Authentication. If activated, the password alone is not sufficient for logging-in but the user must also verify the new session by
* Confirming it in a dialog displayed on any existing myApps session.
* Clicking a link that is sent to the email address configured at the user object.

In both cases a security code is displayed that should be compared to the one that is shown on the login screen of the new session. If it is the same the user can be sure that he is confirming his own login but not the possible concurrent login of an attacker.

The email account for sending the verification emails can be configured during installation of the PBX, in the PBX Manager plugin "Email" or in the admin UI under PBX/Config/Authentication.

If a user is notified about a login attempt he did not do, it means that the user password is compromised. The following should be done in such cases:
* Reject the session (email link or displayed dialog)
* Inform the administrator
* Change the user password

=== Using Windows passwords ===
Instead of using the passwords configured at the user object, the Windows account can be used.
; OAuth2 (recommended) : See [[Reference16r1:Concept_OAuth2_Windows_Authentication]] for details.
; NTLM : See [[Reference16r1:Concept_Netlogon_and_myPBX_Windows_Authentication]] for details.

=== Logging out ===
A logout can be done in the myApps menu at "Account security" / "Current session" (all versions).
In the browser version there is also separate menu item "Logout".

=== Resetting passwords ===
If the user has forgotten the password, he or she can set a new one by clicking the "Forgot password?" link on the login screen and completing an email verification process. This function can be activated or deactivated by the admin by configuring the link at "PBX"/"Config"/"myApps"/"Reset Password Page" or - more conveniently - using the PBX manager plugin of the innovaphone Users App that provides the functionality to change the configuration by pressing OK and then Enable or Disable various options like the password reset option.

=== Brute force protection ===
myApps does several things to mitigate and detect brute force attacks on user accounts.
* After an attempt to log-in using a wrong password, the corresponding user account is locked for 0, 0, 8, 16, 32, 64, 128, 256, 512, 1024 seconds. In that time no more user logins with that account are possible. Logins using sessions that have been established before, are not affected.
* If there is a login attempt with a wrong password, the user is notified inside all existing myApps sessions. There the user can tell that it was him in order to reset the counters and unlock the account.
* From the third login attempt with a wrong password, events are generated to notify the administrator.
** Event Code 0x0002000b
** Severity Major
** Example Text: 3 rejected login attempts for user johndoe from 192.168.0.53
== Syslog ==
The log flag '''Maintenance / Diagnostics / Logging / myApps''' can be used to write information about the myApps connections to the syslog.
=== Example ===
<pre>
A B C D E F G H I J

20250113-165252 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 - - - Connect
20250113-165256 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) - - Login FAILED "admin" (Authentication failed)
20250113-165301 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) - - Login FAILED "admin" (Authentication failed)
20250113-165303 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin Login OK "admin"
20250113-165308 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin AppGetLogin OK "chat"
20250113-165311 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin AppGetLogin OK "calllist"
20250113-165318 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin Logout OK
20250113-165914 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 - - - Disconnect
</pre>

=== Logging format ===
;A:Date and time
;B:PBX module name
;C:Serial number of connection object
;D:Memory address of connection object
;E:Transport protocol of the connection
;F:IP address of the client
;G:User agent of the client
;H:Session ID
;I:User name
;J:Action

=== Logged actions ===
;Connect: A new connection has been established.
;Disconnect: The connection was closed.
;Login FAILED "username" (error): A user login failed.
;Login FAILED "sessionid" (error): A session login for a resumed session failed.
;Login AUTHORIZE "username": The user was asked to authorize a login over another channel (2FA).
;Login REDIRECT "username": Redirect to another PBX.
;Login REDIRECT "sessionid": Redirect to another PBX.
;Login OK "username": A user login was successful.
;Login OK "sessionid": A session login was successful for a resumed session.
;Logout OK: The user has logged-out and the session is deleted.
;StandbyBack: Redirected from the standby PBX to the actual PBX.
;AuthorizeSession OK "sessionid": The user authorized a login for another session (2FA).
;AuthorizeSession FAILED "sessionid": The user rejected a login for another session (2FA).
;ResetInvalidLogins OK": The user told that a failed login attempt was done by himself (2FA).
;DeleteSession OK "sessionid": The user deleted the access for another session.
;DeleteSession FAILED "sessionid": Deleting another session failed.
;AppGetLogin OK "appname": Access to an app was granted.
;AppGetLogin FAILED "appname": Access to an app was denied.

== Apps ==
=== App runtime ===
All apps are web applications that consist of
* An HTML page
* Javascript files
* An app icon
myApps starts apps by opening the HTML page in an iframe. All communication between the apps and the myApps client is done using HTML5 window messaging. For example if the user changes the color scheme, myApps sends a window message to all open apps, so they can also switch colors.

=== App objects ===
All apps that appear in the myApps client must be configured in the PBX. For apps that are loaded from the innovaphone App Platform or any other external server an App object is used that contains all the needed parameters.

;Name:An ID that must be unique per PBX domain. The ID is only used internally to reference that app and is not shown to the user.
;Long Name:The display name of the app.
;Password:The shared secret between the app instance and the PBX. It corresponds to the password configured at the app instance. This secret is used when a user is authenticated against the app.
;URL:The base URL of the app. myApps appends .htm to get the URL of the HTML page and .png to get the URL of the app icon.
;Icon URL:If configured this URL is used for the app icon, instead of deriving it from the URL.
;Hidden:Some apps don't have a user interface. Their only purpose is to provide functionality (Client APIs) for myApps or other apps using window messaging. They have the "Hidden" flag checked at the app object and are not shown to the user.

;Plain website
:Checked if the HTML page is not an actual app that requires login and processes the window messages used for apps, but if it is just a regular website. This flag can be used to integrate websites into myApps via iframe.
:Please note that this feature is meant for having a possibility to create simple content pages and integrate them into myApps without the need to develop a full-fledged app.
:''Note: Most existing websites cannot be integrated in this way because they do not allow you to load them into an iframe. Check [https://en.wikipedia.org/wiki/Cross-origin_resource_sharing Cross-origin resource sharing] and [https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-same-site-00#section-4.1 Cookies SameSite] settings with the owner of the website. If you miss some configuration, you should see an error message in your browser console.''

;Websocket:Some apps need a websocket connection from the PBX. This can be used to exchange additional information or to use APIs on the PBX. Those apps need the Websocket flag checked.

Some other PBX objects also provide apps, like the Boolean object.

=== App permissions ===
In order to use an app the administrator must grant the permission to the user. This can be done using templates of at the specific user object ("Edit Object"/"Apps"). The same setting can be done in the PBX manager plugin "Templates". The user will find the apps he has access to in the "All apps" view in myApps.

==== Special case: phone apps ====
If a user has access to the "phone" or "softphone" app, it will not automatically appear in "All apps". Those apps need to be assigned to a device at the user object and will then be used for the registration on those devices. The admin can configure the app name at the individual devices in the admin UI. The user can assign the app during provisioning of phones in "Edit profile".

=== Client APIs and default apps ===
Some apps provide APIs that allow communication with other apps. An app providing an API is called an API provider. Communication is done using HTML5 window messages sent to the myApps client that dispatches them to the right app.

If there are many providers for the same API, the app can send messages to specific provider, to all providers or let the user decide. In the latter case, myApps displays a selection dialog to the user. The user can also mark an app as the default app for an API that will then be used without asking again.

Additionally the user can configure the standard apps in the myApps menu.

The default apps are stored locally on each browser / device. So the user can have a different setting on each device.

==== Special case: phone API (com.innovaphone.phone) ====
The phone apps provide a phone API that can be used by other apps to start calls. If a phone app is selected as the default phone app it has the following effects:
* When dialing a phone number (in a contacts app) the default phone app will be used for the call.
* On incoming calls the phone app is started and displayed automatically, to handle the call.

If no default phone app is selected on a device
* The user will be asked what phone app shall be used when dialing (in a contacts app)
* On incoming calls no phone app will be started

Regardless of the setting, the user can open any phone to start or receive calls.

The standard phone app can be also selected by longpressing the app tile on the home screen.

== Home screen ==
The home screen contains tiles that represent apps or items from apps - generally speaking links to apps. For example the user can place his phone app next to a contact from a contact app. Those tiles can be organized in named groups that can be collapsed, if they are currently not needed.

The presentation of a tile contains an icon, the name of the app or item and optionally a presence and a badge count provided by the app.

There are two ways for the user to add new items to the home screen:
* Click the home symbol at an app in the "All apps" view.
* Click an attach icon at an item inside an app.

Apps can be removed again the same way or by longpressing the tile and clicking "Remove from home".

=== Storage and format ===
The home screen is stored at the user object in the PBX and is synchronized over all sessions of the user.

The admin can see and configure it in the admin UI at "Edit User"/"User"/"Home Screen Apps". It is a comma-separated string of app links.

The string is limited to 8KB. If the limit is reached no more items or groups can be added to the home screen.

Format: Items starting with a colon are groups. Items starting with two colons are collapsed groups.

For example <code>:Apps,chat,users,::Contacts,users?id=jdo#d=John%20Doe&s=jdo</code>.

corresponds to
* Apps (group)
** Chat
** Users
* Contacts (collapsed group)
** "John Doe" from the app "users"

Individual app links are URL-encoded. An App link must not appear twice.

== All apps ==
This page in myApps shows all apps that the user has access to (see: [[#App permissions|App permissions]]). Apps that are often used can be attached to the home screen.

== App Notifications ==
From version 14r1 app services can send notifications to users. Those notifications will be transmitted to and displayed by all myApps sessions of the user that have app notifications enabled. Clicking the notification will open the app with optional parameters.

=== Prerequisites ===
Launcher
* myApps for Windows from version 14r1
* myApps for macOS from version 14r1
* myApps Android from version 14r1
* myApps for iOS from version 14r1

Browser
* Supported browser with the following features enabled:
** [https://developer.mozilla.org/en-US/docs/Web/API/Push_API Push API]
** [https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API Notifications API]
** [https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API Service Worker API]
** [https://developer.mozilla.org/en-US/docs/Web/API/Client Client API]
* myApps opened using https:

PBX
* Trusted certificate with a valid DNS name. Self-signed certificates don't work.
* Push enabled, otherwise notifications will only be sent to connected myApps sesssions.

Reverse Proxy
* Trusted certificate with a valid DNS name. Self-signed certificates don't work.

=== Configuration ===
* If the feature is supported, the user can enable / disable app notifications in the hamburger menu of the myApps home screen ("App notifications").
* The setting is per device. So the user can choose on which devices he or she likes to receive notifications.
* By default app notifications are enabled in the launcher and disabled in browser sessions.
* For enabling app notifications in the browser the user needs to grant the permission for Web Notifications.

=== Some examples for apps supporting app notifications ===
* The Chat App in 14r1 uses app notifications for incoming chat messages.
* The Working App in 14r1 uses app notifications for warnings.

=== Documentation for app developers ===
[https://sdk.innovaphone.com/16r1/doc/appwebsocket/PbxApi.htm#AppNotify https://sdk.innovaphone.com/16r1/doc/appwebsocket/PbxApi.htm#AppNotify]

== Accessibility ==
For information regarding accessibility see following Article: https://wiki.innovaphone.com/index.php?title=Reference:Concept_Accessibility

== Edit profile ==
An app for managing the user profile can be configured in the admin UI at "PBX"/"Config"/"myApps"/"Edit Profile App". Typically the profile app provided by the innovaphone Users app is used for that. If configured, a menu item "Edit profile" appears in the myApps menu.

== Onboarding ==
The administrator can configure a web page that shall be displayed as an intro when a user opens myApps for the first time. The user can see the intro again by clicking "Intro" in the hamburger menu of myApps.

Configuration:
* The URL of the onboarding page can be configured at: PBX / Config / myApps / Onboarding URL. The corresponding command line attribute is <code>PBX0 /onboarding</code>. The default URL configured during install is: https://www.innovaphone.com/en/services/intro-video.html?embedded=1
* The information whether a user has already seen the onboarding is stored at the user object or template (User / Onboarding seen). The corresponding LDAP attribute is <code>onboarded</code>.

The following parameters are passed to the page using URL parameters:
;name: "onboarding"
;title: The title as shown in the hamburger menu of myApps (depending on the e.g. "Intro")
;scheme:The color scheme ("light" or "dark")
;size:The size setting of the home screen items ("0", "1" or "2")
;lang: The myApps language (e.g. "de" or "en")
;ver: The version of the PBX (e.g. "16r1")
;build: The build of the PBX (e.g. "1510335)

Requirements for the configured page:
* Must work inside an IFrame.
* Should follow the language given in the URL parameters, defaulting to "en" if no contents are available for the language.
* Should follow the collor scheme ("dark" or "light") given in the URL parameters.
* Must be responsive to work in different orientations (landscape or portrait) and on different screen sizes (Desktop and Smartphone).
* Must reserve a space (width 306px, height 102px) for an overlay button that is displayed by myApps in the bottom right corner.

== Tutorials app ==
The administrator can define an app providing tutorials or other help for end users. That app will appear in the hamburger menu of myApps as "Tutorials".

Requirements:
* Create an app object pointing to the corresponding web page (eg. https://www.innovaphone.com/myapps/tutorial.htm) via the Adv.GUI, PBX, Objects, create new App Object with a name (eg. Tutorials)
* Give users access to that app, preferably using templates (eg. Conf Users).
* Configure the app name in the admin UI "PBX"/"Config"/"myApps"/"Tutorial App" with the previous created name (eg. Tutorials).

Note: This configuration is synchronized with the client when the connection is established. So a restart of myApps is needed for the tutorials app to appear in the hamburger menu.

When installing a new PBX, a tutorial app provided by innovaphone is configured by default. It points to https://www.innovaphone.com/myapps/tutorial.htm and shows videos about the usage of myApps.

== Privacy and Datastorage ==

myApps will store the following data on your local device:

* appclient-username / appclient-password
: Auth token from the user session on this device (This is not the password itself, only a random token).
* appclient-model
: Offline-files from myApps which contains the personal user data (eg. Home screen configuration and Push tokens).
* appclient-config
: URLs and credentials for local services (credentials will be new generated randomly on every startup)
* appclient-usr-XXXXXXXXXXXXXXXXXXX
: anonymized environment settings of all historical user sessions (eg. theme, element size of home screen elements, language)

Additionally, it is allowed to every App to create own offline files or create local settings which will be stored also.

The Chromium Cache and DOM Storage (myApps for Windows) will be stored in <code>%appdata%\innovaphone\myApps\chromium\cache</code>

= Idle Bandwidth =
== myApps ==
The myApps client opens a single Websocket connection to the PBX. When the connection is idle, the PBX sends just a Websocket PING/PONG every 60s. Note that the PING/PONG exchange prevents TCP KeepAlive Messages, so there is no additional load for it.

Message IP header TCP header TLS payload Total bytes
PING 20 bytes 20 bytes 31 bytes 71 bytes
PONG 20 bytes 20 bytes 35 bytes 75 bytes
ACK 20 bytes 20 bytes - 40 bytes
------------------------------------------------------------------
186 bytes / min
11.160 bytes / h
267.840 bytes / d

== Apps ==
Most apps also open a Websocket connection to the PBX or App Platform and also use the PING/PONG mechanism. So the idle load is identical to myApps.

Message IP header TCP header TLS payload Total bytes
PING 20 bytes 20 bytes 31 bytes 71 bytes
PONG 20 bytes 20 bytes 35 bytes 75 bytes
ACK 20 bytes 20 bytes - 40 bytes
------------------------------------------------------------------
186 bytes / min
11.160 bytes / h
267.840 bytes / d

There are some apps - like the phone apps - send a Websocket message {"mt":"KeepAlive"} on application layer every 60s to the PBX to dectect connection problems faster. Note that sending the message both prevents PING/PONG by the server and TCP KeepAlive, so there is no additonal load for it. In that case the idle bandwith can be calculated like follows.

Message IP header TCP header TLS payload Total bytes
KeepAlive 20 bytes 20 bytes 53 bytes 93 bytes
ACK 20 bytes 20 bytes - 40 bytes
------------------------------------------------------------------
133 bytes / min
7.980 bytes / h
191.520 bytes / d

= Troubleshooting =

Client-side
*The myApps web uses the logging facilities provided by the browser it runs in (i.e. JavaScript function <code>console.log</code>). In most browser this is available as ''Console'' after pressing F12.
*The myApps platform services provide more elaborate tracing mechanisms. See ''Troubleshooting'' in [[{{NAMESPACE}}:Concept_myApps_platform_services#Troubleshooting|Concept myApps platform services]].

PBX-side
*The Syslog can be used to log all connections to the PBX. See [[Reference16r1:Concept_myApps#Syslog]].
*You can activate the trace flag Servlets to see all websocket messages from and to the PBX. <code>!config add HTTP0 /servlet-trace on</code>

= Related Articles =
* [[{{NAMESPACE}}:Concept myApps platform services]]

= Known Problems =

[[:Category:Problem_myApps|Known Problems]]

Reference16r1:Concept myApps

2026-06-29T09:01:30Z

Ckl: /* Storage and format */

[[Category:Concept|myApps]]
[[Category:Concept_myApps]]
==Applies To==
This information applies to
* innovaphone PBX from version 16r1
= Overview =
innovaphone myApps is the client software for innovaphone users and administrators. The base functionality is provided by a web application that is loaded from the PBX. Additionally there are [[{{NAMESPACE}}:Concept_myApps_platform_services|installable versions for Windows, Android, macOS and iOS]] that come with an integrated browser and implement adaptations to the local operating system.

The purpose of myApps is to organize and run apps. All productive functionality is provided by additional apps that run inside myApps.
== Requirements ==
=== Web version ===
For opening myApps in the web browser you need the most recent version of one of the following browsers:
* Chrome
* Firefox
* Safari
* or Edge
The following browser features are required and must not be disabled:
* JavaScript
* HTML5 Local Storage

=== Native versions ===
myApps can also run as native executables on Windows (myApps for Windows), iOS (myApps for iOS), macOS (myApps for macOS) and Android (myApps for Android). In this case, myApps platform services are available and provide additional features. The myApps Web version then runs in a web view window embedded in this native client. See [[{{NAMESPACE}}:Concept myApps platform services|myApps platform services overview]] for more information.

=== Licenses ===
* No license needed for myApps itself
* Apps might require licenses

=== Account ===
* A user account (user object) on the PBX is needed in order to use myApps.

=== Reverse proxy ===
For access from the public internet, the reverse proxy must be configured to allow access to the following paths on the PBX.
; /PBX0/APPCLIENT/appclient.htm
: The myApps client itself
; /PBX0/session
: Needed for two-factor authentication using email
; /PBX0/APPS
: Needed for apps loaded from the PBX (e.g. softphone and chat) and for apps that use PBX APIs
; /OAUTH2/oauth2_login
: Needed for OAuth2 authentication

== Features ==
myApps comes with the following features:
* User login including two-factor authentication.
* Display and set the own presence (on the home screen and when the focus app is shown).
* List of all available apps including search functionality.
* Running apps (inside an iframe).
* Apps can be pinned to the main window. Pinned apps are always running and can't be closed. They are also started automatically when the myApps client is loaded.
* The "app focus" can be used to define a default app for the user. It is started and shown automatically when myApps is loaded. When closing other apps the app is shown instead of the home screen.
* Detaching apps in myApps for Windows and myApps for macOS. Detached apps are opened in a separate window.
* Home screen with user-selected apps and app items that can be organized in collapsible groups.
* Push notifications sent by app services.
* List of all myApps-Logins. Unused or suspicious sessions can be logged out remotely.
* Color scheme selection (light, dark).
* Configuration of standard apps for certain functions (like phone calls or chat).
* Link to account specific settings provided by a separate app (profile).
* Dialogue guidance in following languages: Català, Ceština, Deutsch, English, Español, Euskara, Français, Italiano, Nederlands, Polski, Português, Româna, ??????? ????, Slovenšcina, Türkçe
* Screen reader compatiblity and keyboard control
* Interactive, clickable onboarding tour to guide users through the client's structure and key features.

All other functionality is provided by apps. For example phone calls require a phone app. Chats require a chat app.

= Details =
== Connecting to the PBX ==
The myApps web application is loaded from the PBX. The corresponding URL for opening myApps in a browser is
https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm
The installable versions ask for the "server name" on the first startup. Enter the host name of the PBX to proceed to the login screen.
You can change the server afterwards by logging out and clicking the "Change server" link on the login screen.

== Supported URL Parameters ==
Some parameters can be specified with the URL in both the query string or fragment identifier. Those parameters are intended for internal use in the myApps launcher and automated testing. However they could be useful for special applications.

https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm?lang=de

https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm#lang=it

Supported parameters:

;lang:The two-letter code of the desired myApps language ("en", "it", "fr", "de", ...)
;scheme:The color scheme ("light", "dark").
;app:An app link to be started (e.g. "chat").
;usr:The user name for login. Note that this will create a new permanent session at the user object. Should only be used in the fragment identifier.
;pwd:The password for login. Note that this will create a new permanent session at the user object. Should only be used in the fragment identifier.
;inactiveTimeout:Overrides the general timeout for the "auto appear offline" feature in browsers. Sets a timeout in milliseconds that shall be used before the user goes offline. Setting it to 0 disables the "auto appear offline". Browser version only. Available from 13r2 SR11.
;phys: User defined physical location for Softphone Apps

Example:

https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm?lang=de&scheme=light&app=chat#usr=john.doe&pwd=secret

== Redirect to the user's PBX==
If the logged-in user is not on the current PBX, myApps will be redirected to the user's PBX (as configured in the pbx attribute of the user). The following rules apply:
===Master-Slave scenario===
* Slave PBXes redirect to the master PBX.
* The master PBX redirects to the correct slave PBX.

Note: If the current PBX has no registration to the redirect target PBX but knows the user, it will act as a standby and keep the connection, until the registration is up gain.

===Standby scenario===
See [[Reference16r1:Concept_myApps_Redundancy]]

== Deployment of settings ==
The administrator can deploy some general settings to be used as a default by all myApps clients. This can be done in the admin UI on page PBX/Config/myApps. See [[Reference13r1:PBX/Config/myApps]] for details.

== Authentication and security ==
For using myApps you need an account (user object) on the pbx with a password. For logging-in you need to enter the username (SIP-URI) or email address and the password.

=== Permanent sessions ===
On each successful login on a new browser or new device a permanent session is created that is defined by a session id and a session password. Those are stored both in the local storage of the browser and at the user object in the PBX. If the user closes myApps and opens it again, the stored session is used. Only when logging-out the session is deleted in both places and the login screen is shown again.

Notes:
* The user password is never transmitted over the network or permanently stored in the browser.
* The PBX stores up to 12 persistent sessions per user. When the limit is reached, creating a new session removes the session with the oldest login timestamp.

The user can keep track of all his permanent sessions in the myApps menu under "Account security". Sessions that are not needed anymore can be deleted here. The corresponding browser or device is logged out on-the-fly.

=== Two-factor authentication ===
The purpose of two-factor authentication is to maintain an additional level of security that prevents attackers form logging-in even if they compromised a users password. Therefore we strongly recommend to use it.

It can be activated during installation of the PBX or in the admin UI under PBX/Config/Authentication. If activated, the password alone is not sufficient for logging-in but the user must also verify the new session by
* Confirming it in a dialog displayed on any existing myApps session.
* Clicking a link that is sent to the email address configured at the user object.

In both cases a security code is displayed that should be compared to the one that is shown on the login screen of the new session. If it is the same the user can be sure that he is confirming his own login but not the possible concurrent login of an attacker.

The email account for sending the verification emails can be configured during installation of the PBX, in the PBX Manager plugin "Email" or in the admin UI under PBX/Config/Authentication.

If a user is notified about a login attempt he did not do, it means that the user password is compromised. The following should be done in such cases:
* Reject the session (email link or displayed dialog)
* Inform the administrator
* Change the user password

=== Using Windows passwords ===
Instead of using the passwords configured at the user object, the Windows account can be used.
; OAuth2 (recommended) : See [[Reference16r1:Concept_OAuth2_Windows_Authentication]] for details.
; NTLM : See [[Reference16r1:Concept_Netlogon_and_myPBX_Windows_Authentication]] for details.

=== Logging out ===
A logout can be done in the myApps menu at "Account security" / "Current session" (all versions).
In the browser version there is also separate menu item "Logout".

=== Resetting passwords ===
If the user has forgotten the password, he or she can set a new one by clicking the "Forgot password?" link on the login screen and completing an email verification process. This function can be activated or deactivated by the admin by configuring the link at "PBX"/"Config"/"myApps"/"Reset Password Page" or - more conveniently - using the PBX manager plugin of the innovaphone Users App that provides the functionality to change the configuration by pressing OK and then Enable or Disable various options like the password reset option.

=== Brute force protection ===
myApps does several things to mitigate and detect brute force attacks on user accounts.
* After an attempt to log-in using a wrong password, the corresponding user account is locked for 0, 0, 8, 16, 32, 64, 128, 256, 512, 1024 seconds. In that time no more user logins with that account are possible. Logins using sessions that have been established before, are not affected.
* If there is a login attempt with a wrong password, the user is notified inside all existing myApps sessions. There the user can tell that it was him in order to reset the counters and unlock the account.
* From the third login attempt with a wrong password, events are generated to notify the administrator.
** Event Code 0x0002000b
** Severity Major
** Example Text: 3 rejected login attempts for user johndoe from 192.168.0.53
== Syslog ==
The log flag '''Maintenance / Diagnostics / Logging / myApps''' can be used to write information about the myApps connections to the syslog.
=== Example ===
<pre>
A B C D E F G H I J

20250113-165252 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 - - - Connect
20250113-165256 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) - - Login FAILED "admin" (Authentication failed)
20250113-165301 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) - - Login FAILED "admin" (Authentication failed)
20250113-165303 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin Login OK "admin"
20250113-165308 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin AppGetLogin OK "chat"
20250113-165311 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin AppGetLogin OK "calllist"
20250113-165318 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin Logout OK
20250113-165914 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 - - - Disconnect
</pre>

=== Logging format ===
;A:Date and time
;B:PBX module name
;C:Serial number of connection object
;D:Memory address of connection object
;E:Transport protocol of the connection
;F:IP address of the client
;G:User agent of the client
;H:Session ID
;I:User name
;J:Action

=== Logged actions ===
;Connect: A new connection has been established.
;Disconnect: The connection was closed.
;Login FAILED "username" (error): A user login failed.
;Login FAILED "sessionid" (error): A session login for a resumed session failed.
;Login AUTHORIZE "username": The user was asked to authorize a login over another channel (2FA).
;Login REDIRECT "username": Redirect to another PBX.
;Login REDIRECT "sessionid": Redirect to another PBX.
;Login OK "username": A user login was successful.
;Login OK "sessionid": A session login was successful for a resumed session.
;Logout OK: The user has logged-out and the session is deleted.
;StandbyBack: Redirected from the standby PBX to the actual PBX.
;AuthorizeSession OK "sessionid": The user authorized a login for another session (2FA).
;AuthorizeSession FAILED "sessionid": The user rejected a login for another session (2FA).
;ResetInvalidLogins OK": The user told that a failed login attempt was done by himself (2FA).
;DeleteSession OK "sessionid": The user deleted the access for another session.
;DeleteSession FAILED "sessionid": Deleting another session failed.
;AppGetLogin OK "appname": Access to an app was granted.
;AppGetLogin FAILED "appname": Access to an app was denied.

== Apps ==
=== App runtime ===
All apps are web applications that consist of
* An HTML page
* Javascript files
* An app icon
myApps starts apps by opening the HTML page in an iframe. All communication between the apps and the myApps client is done using HTML5 window messaging. For example if the user changes the color scheme, myApps sends a window message to all open apps, so they can also switch colors.

=== App objects ===
All apps that appear in the myApps client must be configured in the PBX. For apps that are loaded from the innovaphone App Platform or any other external server an App object is used that contains all the needed parameters.

;Name:An ID that must be unique per PBX domain. The ID is only used internally to reference that app and is not shown to the user.
;Long Name:The display name of the app.
;Password:The shared secret between the app instance and the PBX. It corresponds to the password configured at the app instance. This secret is used when a user is authenticated against the app.
;URL:The base URL of the app. myApps appends .htm to get the URL of the HTML page and .png to get the URL of the app icon.
;Icon URL:If configured this URL is used for the app icon, instead of deriving it from the URL.
;Hidden:Some apps don't have a user interface. Their only purpose is to provide functionality (Client APIs) for myApps or other apps using window messaging. They have the "Hidden" flag checked at the app object and are not shown to the user.

;Plain website
:Checked if the HTML page is not an actual app that requires login and processes the window messages used for apps, but if it is just a regular website. This flag can be used to integrate websites into myApps via iframe.
:Please note that this feature is meant for having a possibility to create simple content pages and integrate them into myApps without the need to develop a full-fledged app.
:''Note: Most existing websites cannot be integrated in this way because they do not allow you to load them into an iframe. Check [https://en.wikipedia.org/wiki/Cross-origin_resource_sharing Cross-origin resource sharing] and [https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-same-site-00#section-4.1 Cookies SameSite] settings with the owner of the website. If you miss some configuration, you should see an error message in your browser console.''

;Websocket:Some apps need a websocket connection from the PBX. This can be used to exchange additional information or to use APIs on the PBX. Those apps need the Websocket flag checked.

Some other PBX objects also provide apps, like the Boolean object.

=== App permissions ===
In order to use an app the administrator must grant the permission to the user. This can be done using templates of at the specific user object ("Edit Object"/"Apps"). The same setting can be done in the PBX manager plugin "Templates". The user will find the apps he has access to in the "All apps" view in myApps.

==== Special case: phone apps ====
If a user has access to the "phone" or "softphone" app, it will not automatically appear in "All apps". Those apps need to be assigned to a device at the user object and will then be used for the registration on those devices. The admin can configure the app name at the individual devices in the admin UI. The user can assign the app during provisioning of phones in "Edit profile".

=== Client APIs and default apps ===
Some apps provide APIs that allow communication with other apps. An app providing an API is called an API provider. Communication is done using HTML5 window messages sent to the myApps client that dispatches them to the right app.

If there are many providers for the same API, the app can send messages to specific provider, to all providers or let the user decide. In the latter case, myApps displays a selection dialog to the user. The user can also mark an app as the default app for an API that will then be used without asking again.

Additionally the user can configure the standard apps in the myApps menu.

The default apps are stored locally on each browser / device. So the user can have a different setting on each device.

==== Special case: phone API (com.innovaphone.phone) ====
The phone apps provide a phone API that can be used by other apps to start calls. If a phone app is selected as the default phone app it has the following effects:
* When dialing a phone number (in a contacts app) the default phone app will be used for the call.
* On incoming calls the phone app is started and displayed automatically, to handle the call.

If no default phone app is selected on a device
* The user will be asked what phone app shall be used when dialing (in a contacts app)
* On incoming calls no phone app will be started

Regardless of the setting, the user can open any phone to start or receive calls.

The standard phone app can be also selected by longpressing the app tile on the home screen.

== Home screen ==
The home screen contains tiles that represent apps or items from apps - generally speaking links to apps. For example the user can place his phone app next to a contact from a contact app. Those tiles can be organized in named groups that can be collapsed, if they are currently not needed.

The presentation of a tile contains an icon, the name of the app or item and optionally a presence and a badge count provided by the app.

There are two ways for the user to add new items to the home screen:
* Click the home symbol at an app in the "All apps" view.
* Click an attach icon at an item inside an app.

Apps can be removed again the same way or by longpressing the tile and clicking "Remove from home".

=== Storage and format ===
The home screen is stored at the user object in the PBX and is synchronized over all sessions of the user.

The admin can see and configure it in the admin UI at "Edit User"/"User"/"Home Screen Apps". It is a comma-separated string of app links.

The string is limited to 8KB. If the limit is reached no more items or groups can be added to the home screen.

Format: Items starting with a colon are groups. Items starting with two colons are collapsed groups.

For example <code>:Apps,chat,users,::Contacts,users?id=jdo#d=John%20Doe&s=jdo</code>.

corresponds to
* Apps (group)
** Chat
** Users
* Contacts (collapsed group)
** "John Doe" from the app "users"

Indivisual App links are URL-encoded. An App link must not appear twice.

== All apps ==
This page in myApps shows all apps that the user has access to (see: [[#App permissions|App permissions]]). Apps that are often used can be attached to the home screen.

== App Notifications ==
From version 14r1 app services can send notifications to users. Those notifications will be transmitted to and displayed by all myApps sessions of the user that have app notifications enabled. Clicking the notification will open the app with optional parameters.

=== Prerequisites ===
Launcher
* myApps for Windows from version 14r1
* myApps for macOS from version 14r1
* myApps Android from version 14r1
* myApps for iOS from version 14r1

Browser
* Supported browser with the following features enabled:
** [https://developer.mozilla.org/en-US/docs/Web/API/Push_API Push API]
** [https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API Notifications API]
** [https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API Service Worker API]
** [https://developer.mozilla.org/en-US/docs/Web/API/Client Client API]
* myApps opened using https:

PBX
* Trusted certificate with a valid DNS name. Self-signed certificates don't work.
* Push enabled, otherwise notifications will only be sent to connected myApps sesssions.

Reverse Proxy
* Trusted certificate with a valid DNS name. Self-signed certificates don't work.

=== Configuration ===
* If the feature is supported, the user can enable / disable app notifications in the hamburger menu of the myApps home screen ("App notifications").
* The setting is per device. So the user can choose on which devices he or she likes to receive notifications.
* By default app notifications are enabled in the launcher and disabled in browser sessions.
* For enabling app notifications in the browser the user needs to grant the permission for Web Notifications.

=== Some examples for apps supporting app notifications ===
* The Chat App in 14r1 uses app notifications for incoming chat messages.
* The Working App in 14r1 uses app notifications for warnings.

=== Documentation for app developers ===
[https://sdk.innovaphone.com/16r1/doc/appwebsocket/PbxApi.htm#AppNotify https://sdk.innovaphone.com/16r1/doc/appwebsocket/PbxApi.htm#AppNotify]

== Accessibility ==
For information regarding accessibility see following Article: https://wiki.innovaphone.com/index.php?title=Reference:Concept_Accessibility

== Edit profile ==
An app for managing the user profile can be configured in the admin UI at "PBX"/"Config"/"myApps"/"Edit Profile App". Typically the profile app provided by the innovaphone Users app is used for that. If configured, a menu item "Edit profile" appears in the myApps menu.

== Onboarding ==
The administrator can configure a web page that shall be displayed as an intro when a user opens myApps for the first time. The user can see the intro again by clicking "Intro" in the hamburger menu of myApps.

Configuration:
* The URL of the onboarding page can be configured at: PBX / Config / myApps / Onboarding URL. The corresponding command line attribute is <code>PBX0 /onboarding</code>. The default URL configured during install is: https://www.innovaphone.com/en/services/intro-video.html?embedded=1
* The information whether a user has already seen the onboarding is stored at the user object or template (User / Onboarding seen). The corresponding LDAP attribute is <code>onboarded</code>.

The following parameters are passed to the page using URL parameters:
;name: "onboarding"
;title: The title as shown in the hamburger menu of myApps (depending on the e.g. "Intro")
;scheme:The color scheme ("light" or "dark")
;size:The size setting of the home screen items ("0", "1" or "2")
;lang: The myApps language (e.g. "de" or "en")
;ver: The version of the PBX (e.g. "16r1")
;build: The build of the PBX (e.g. "1510335)

Requirements for the configured page:
* Must work inside an IFrame.
* Should follow the language given in the URL parameters, defaulting to "en" if no contents are available for the language.
* Should follow the collor scheme ("dark" or "light") given in the URL parameters.
* Must be responsive to work in different orientations (landscape or portrait) and on different screen sizes (Desktop and Smartphone).
* Must reserve a space (width 306px, height 102px) for an overlay button that is displayed by myApps in the bottom right corner.

== Tutorials app ==
The administrator can define an app providing tutorials or other help for end users. That app will appear in the hamburger menu of myApps as "Tutorials".

Requirements:
* Create an app object pointing to the corresponding web page (eg. https://www.innovaphone.com/myapps/tutorial.htm) via the Adv.GUI, PBX, Objects, create new App Object with a name (eg. Tutorials)
* Give users access to that app, preferably using templates (eg. Conf Users).
* Configure the app name in the admin UI "PBX"/"Config"/"myApps"/"Tutorial App" with the previous created name (eg. Tutorials).

Note: This configuration is synchronized with the client when the connection is established. So a restart of myApps is needed for the tutorials app to appear in the hamburger menu.

When installing a new PBX, a tutorial app provided by innovaphone is configured by default. It points to https://www.innovaphone.com/myapps/tutorial.htm and shows videos about the usage of myApps.

== Privacy and Datastorage ==

myApps will store the following data on your local device:

* appclient-username / appclient-password
: Auth token from the user session on this device (This is not the password itself, only a random token).
* appclient-model
: Offline-files from myApps which contains the personal user data (eg. Home screen configuration and Push tokens).
* appclient-config
: URLs and credentials for local services (credentials will be new generated randomly on every startup)
* appclient-usr-XXXXXXXXXXXXXXXXXXX
: anonymized environment settings of all historical user sessions (eg. theme, element size of home screen elements, language)

Additionally, it is allowed to every App to create own offline files or create local settings which will be stored also.

The Chromium Cache and DOM Storage (myApps for Windows) will be stored in <code>%appdata%\innovaphone\myApps\chromium\cache</code>

= Idle Bandwidth =
== myApps ==
The myApps client opens a single Websocket connection to the PBX. When the connection is idle, the PBX sends just a Websocket PING/PONG every 60s. Note that the PING/PONG exchange prevents TCP KeepAlive Messages, so there is no additional load for it.

Message IP header TCP header TLS payload Total bytes
PING 20 bytes 20 bytes 31 bytes 71 bytes
PONG 20 bytes 20 bytes 35 bytes 75 bytes
ACK 20 bytes 20 bytes - 40 bytes
------------------------------------------------------------------
186 bytes / min
11.160 bytes / h
267.840 bytes / d

== Apps ==
Most apps also open a Websocket connection to the PBX or App Platform and also use the PING/PONG mechanism. So the idle load is identical to myApps.

Message IP header TCP header TLS payload Total bytes
PING 20 bytes 20 bytes 31 bytes 71 bytes
PONG 20 bytes 20 bytes 35 bytes 75 bytes
ACK 20 bytes 20 bytes - 40 bytes
------------------------------------------------------------------
186 bytes / min
11.160 bytes / h
267.840 bytes / d

There are some apps - like the phone apps - send a Websocket message {"mt":"KeepAlive"} on application layer every 60s to the PBX to dectect connection problems faster. Note that sending the message both prevents PING/PONG by the server and TCP KeepAlive, so there is no additonal load for it. In that case the idle bandwith can be calculated like follows.

Message IP header TCP header TLS payload Total bytes
KeepAlive 20 bytes 20 bytes 53 bytes 93 bytes
ACK 20 bytes 20 bytes - 40 bytes
------------------------------------------------------------------
133 bytes / min
7.980 bytes / h
191.520 bytes / d

= Troubleshooting =

Client-side
*The myApps web uses the logging facilities provided by the browser it runs in (i.e. JavaScript function <code>console.log</code>). In most browser this is available as ''Console'' after pressing F12.
*The myApps platform services provide more elaborate tracing mechanisms. See ''Troubleshooting'' in [[{{NAMESPACE}}:Concept_myApps_platform_services#Troubleshooting|Concept myApps platform services]].

PBX-side
*The Syslog can be used to log all connections to the PBX. See [[Reference16r1:Concept_myApps#Syslog]].
*You can activate the trace flag Servlets to see all websocket messages from and to the PBX. <code>!config add HTTP0 /servlet-trace on</code>

= Related Articles =
* [[{{NAMESPACE}}:Concept myApps platform services]]

= Known Problems =

[[:Category:Problem_myApps|Known Problems]]

Reference16r1:Concept myApps

2026-06-29T09:01:00Z

Ckl: /* Storage and format */

[[Category:Concept|myApps]]
[[Category:Concept_myApps]]
==Applies To==
This information applies to
* innovaphone PBX from version 16r1
= Overview =
innovaphone myApps is the client software for innovaphone users and administrators. The base functionality is provided by a web application that is loaded from the PBX. Additionally there are [[{{NAMESPACE}}:Concept_myApps_platform_services|installable versions for Windows, Android, macOS and iOS]] that come with an integrated browser and implement adaptations to the local operating system.

The purpose of myApps is to organize and run apps. All productive functionality is provided by additional apps that run inside myApps.
== Requirements ==
=== Web version ===
For opening myApps in the web browser you need the most recent version of one of the following browsers:
* Chrome
* Firefox
* Safari
* or Edge
The following browser features are required and must not be disabled:
* JavaScript
* HTML5 Local Storage

=== Native versions ===
myApps can also run as native executables on Windows (myApps for Windows), iOS (myApps for iOS), macOS (myApps for macOS) and Android (myApps for Android). In this case, myApps platform services are available and provide additional features. The myApps Web version then runs in a web view window embedded in this native client. See [[{{NAMESPACE}}:Concept myApps platform services|myApps platform services overview]] for more information.

=== Licenses ===
* No license needed for myApps itself
* Apps might require licenses

=== Account ===
* A user account (user object) on the PBX is needed in order to use myApps.

=== Reverse proxy ===
For access from the public internet, the reverse proxy must be configured to allow access to the following paths on the PBX.
; /PBX0/APPCLIENT/appclient.htm
: The myApps client itself
; /PBX0/session
: Needed for two-factor authentication using email
; /PBX0/APPS
: Needed for apps loaded from the PBX (e.g. softphone and chat) and for apps that use PBX APIs
; /OAUTH2/oauth2_login
: Needed for OAuth2 authentication

== Features ==
myApps comes with the following features:
* User login including two-factor authentication.
* Display and set the own presence (on the home screen and when the focus app is shown).
* List of all available apps including search functionality.
* Running apps (inside an iframe).
* Apps can be pinned to the main window. Pinned apps are always running and can't be closed. They are also started automatically when the myApps client is loaded.
* The "app focus" can be used to define a default app for the user. It is started and shown automatically when myApps is loaded. When closing other apps the app is shown instead of the home screen.
* Detaching apps in myApps for Windows and myApps for macOS. Detached apps are opened in a separate window.
* Home screen with user-selected apps and app items that can be organized in collapsible groups.
* Push notifications sent by app services.
* List of all myApps-Logins. Unused or suspicious sessions can be logged out remotely.
* Color scheme selection (light, dark).
* Configuration of standard apps for certain functions (like phone calls or chat).
* Link to account specific settings provided by a separate app (profile).
* Dialogue guidance in following languages: Català, Ceština, Deutsch, English, Español, Euskara, Français, Italiano, Nederlands, Polski, Português, Româna, ??????? ????, Slovenšcina, Türkçe
* Screen reader compatiblity and keyboard control
* Interactive, clickable onboarding tour to guide users through the client's structure and key features.

All other functionality is provided by apps. For example phone calls require a phone app. Chats require a chat app.

= Details =
== Connecting to the PBX ==
The myApps web application is loaded from the PBX. The corresponding URL for opening myApps in a browser is
https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm
The installable versions ask for the "server name" on the first startup. Enter the host name of the PBX to proceed to the login screen.
You can change the server afterwards by logging out and clicking the "Change server" link on the login screen.

== Supported URL Parameters ==
Some parameters can be specified with the URL in both the query string or fragment identifier. Those parameters are intended for internal use in the myApps launcher and automated testing. However they could be useful for special applications.

https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm?lang=de

https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm#lang=it

Supported parameters:

;lang:The two-letter code of the desired myApps language ("en", "it", "fr", "de", ...)
;scheme:The color scheme ("light", "dark").
;app:An app link to be started (e.g. "chat").
;usr:The user name for login. Note that this will create a new permanent session at the user object. Should only be used in the fragment identifier.
;pwd:The password for login. Note that this will create a new permanent session at the user object. Should only be used in the fragment identifier.
;inactiveTimeout:Overrides the general timeout for the "auto appear offline" feature in browsers. Sets a timeout in milliseconds that shall be used before the user goes offline. Setting it to 0 disables the "auto appear offline". Browser version only. Available from 13r2 SR11.
;phys: User defined physical location for Softphone Apps

Example:

https://<pbx-hostname>/PBX0/APPCLIENT/appclient.htm?lang=de&scheme=light&app=chat#usr=john.doe&pwd=secret

== Redirect to the user's PBX==
If the logged-in user is not on the current PBX, myApps will be redirected to the user's PBX (as configured in the pbx attribute of the user). The following rules apply:
===Master-Slave scenario===
* Slave PBXes redirect to the master PBX.
* The master PBX redirects to the correct slave PBX.

Note: If the current PBX has no registration to the redirect target PBX but knows the user, it will act as a standby and keep the connection, until the registration is up gain.

===Standby scenario===
See [[Reference16r1:Concept_myApps_Redundancy]]

== Deployment of settings ==
The administrator can deploy some general settings to be used as a default by all myApps clients. This can be done in the admin UI on page PBX/Config/myApps. See [[Reference13r1:PBX/Config/myApps]] for details.

== Authentication and security ==
For using myApps you need an account (user object) on the pbx with a password. For logging-in you need to enter the username (SIP-URI) or email address and the password.

=== Permanent sessions ===
On each successful login on a new browser or new device a permanent session is created that is defined by a session id and a session password. Those are stored both in the local storage of the browser and at the user object in the PBX. If the user closes myApps and opens it again, the stored session is used. Only when logging-out the session is deleted in both places and the login screen is shown again.

Notes:
* The user password is never transmitted over the network or permanently stored in the browser.
* The PBX stores up to 12 persistent sessions per user. When the limit is reached, creating a new session removes the session with the oldest login timestamp.

The user can keep track of all his permanent sessions in the myApps menu under "Account security". Sessions that are not needed anymore can be deleted here. The corresponding browser or device is logged out on-the-fly.

=== Two-factor authentication ===
The purpose of two-factor authentication is to maintain an additional level of security that prevents attackers form logging-in even if they compromised a users password. Therefore we strongly recommend to use it.

It can be activated during installation of the PBX or in the admin UI under PBX/Config/Authentication. If activated, the password alone is not sufficient for logging-in but the user must also verify the new session by
* Confirming it in a dialog displayed on any existing myApps session.
* Clicking a link that is sent to the email address configured at the user object.

In both cases a security code is displayed that should be compared to the one that is shown on the login screen of the new session. If it is the same the user can be sure that he is confirming his own login but not the possible concurrent login of an attacker.

The email account for sending the verification emails can be configured during installation of the PBX, in the PBX Manager plugin "Email" or in the admin UI under PBX/Config/Authentication.

If a user is notified about a login attempt he did not do, it means that the user password is compromised. The following should be done in such cases:
* Reject the session (email link or displayed dialog)
* Inform the administrator
* Change the user password

=== Using Windows passwords ===
Instead of using the passwords configured at the user object, the Windows account can be used.
; OAuth2 (recommended) : See [[Reference16r1:Concept_OAuth2_Windows_Authentication]] for details.
; NTLM : See [[Reference16r1:Concept_Netlogon_and_myPBX_Windows_Authentication]] for details.

=== Logging out ===
A logout can be done in the myApps menu at "Account security" / "Current session" (all versions).
In the browser version there is also separate menu item "Logout".

=== Resetting passwords ===
If the user has forgotten the password, he or she can set a new one by clicking the "Forgot password?" link on the login screen and completing an email verification process. This function can be activated or deactivated by the admin by configuring the link at "PBX"/"Config"/"myApps"/"Reset Password Page" or - more conveniently - using the PBX manager plugin of the innovaphone Users App that provides the functionality to change the configuration by pressing OK and then Enable or Disable various options like the password reset option.

=== Brute force protection ===
myApps does several things to mitigate and detect brute force attacks on user accounts.
* After an attempt to log-in using a wrong password, the corresponding user account is locked for 0, 0, 8, 16, 32, 64, 128, 256, 512, 1024 seconds. In that time no more user logins with that account are possible. Logins using sessions that have been established before, are not affected.
* If there is a login attempt with a wrong password, the user is notified inside all existing myApps sessions. There the user can tell that it was him in order to reset the counters and unlock the account.
* From the third login attempt with a wrong password, events are generated to notify the administrator.
** Event Code 0x0002000b
** Severity Major
** Example Text: 3 rejected login attempts for user johndoe from 192.168.0.53
== Syslog ==
The log flag '''Maintenance / Diagnostics / Logging / myApps''' can be used to write information about the myApps connections to the syslog.
=== Example ===
<pre>
A B C D E F G H I J

20250113-165252 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 - - - Connect
20250113-165256 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) - - Login FAILED "admin" (Authentication failed)
20250113-165301 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) - - Login FAILED "admin" (Authentication failed)
20250113-165303 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin Login OK "admin"
20250113-165308 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin AppGetLogin OK "chat"
20250113-165311 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin AppGetLogin OK "calllist"
20250113-165318 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 myApps (Chrome) 2dc5f5df36856701b333009033410fcb admin Logout OK
20250113-165914 PBX0 APPCLIENT 0 1699138 tcp 192.168.0.200 - - - Disconnect
</pre>

=== Logging format ===
;A:Date and time
;B:PBX module name
;C:Serial number of connection object
;D:Memory address of connection object
;E:Transport protocol of the connection
;F:IP address of the client
;G:User agent of the client
;H:Session ID
;I:User name
;J:Action

=== Logged actions ===
;Connect: A new connection has been established.
;Disconnect: The connection was closed.
;Login FAILED "username" (error): A user login failed.
;Login FAILED "sessionid" (error): A session login for a resumed session failed.
;Login AUTHORIZE "username": The user was asked to authorize a login over another channel (2FA).
;Login REDIRECT "username": Redirect to another PBX.
;Login REDIRECT "sessionid": Redirect to another PBX.
;Login OK "username": A user login was successful.
;Login OK "sessionid": A session login was successful for a resumed session.
;Logout OK: The user has logged-out and the session is deleted.
;StandbyBack: Redirected from the standby PBX to the actual PBX.
;AuthorizeSession OK "sessionid": The user authorized a login for another session (2FA).
;AuthorizeSession FAILED "sessionid": The user rejected a login for another session (2FA).
;ResetInvalidLogins OK": The user told that a failed login attempt was done by himself (2FA).
;DeleteSession OK "sessionid": The user deleted the access for another session.
;DeleteSession FAILED "sessionid": Deleting another session failed.
;AppGetLogin OK "appname": Access to an app was granted.
;AppGetLogin FAILED "appname": Access to an app was denied.

== Apps ==
=== App runtime ===
All apps are web applications that consist of
* An HTML page
* Javascript files
* An app icon
myApps starts apps by opening the HTML page in an iframe. All communication between the apps and the myApps client is done using HTML5 window messaging. For example if the user changes the color scheme, myApps sends a window message to all open apps, so they can also switch colors.

=== App objects ===
All apps that appear in the myApps client must be configured in the PBX. For apps that are loaded from the innovaphone App Platform or any other external server an App object is used that contains all the needed parameters.

;Name:An ID that must be unique per PBX domain. The ID is only used internally to reference that app and is not shown to the user.
;Long Name:The display name of the app.
;Password:The shared secret between the app instance and the PBX. It corresponds to the password configured at the app instance. This secret is used when a user is authenticated against the app.
;URL:The base URL of the app. myApps appends .htm to get the URL of the HTML page and .png to get the URL of the app icon.
;Icon URL:If configured this URL is used for the app icon, instead of deriving it from the URL.
;Hidden:Some apps don't have a user interface. Their only purpose is to provide functionality (Client APIs) for myApps or other apps using window messaging. They have the "Hidden" flag checked at the app object and are not shown to the user.

;Plain website
:Checked if the HTML page is not an actual app that requires login and processes the window messages used for apps, but if it is just a regular website. This flag can be used to integrate websites into myApps via iframe.
:Please note that this feature is meant for having a possibility to create simple content pages and integrate them into myApps without the need to develop a full-fledged app.
:''Note: Most existing websites cannot be integrated in this way because they do not allow you to load them into an iframe. Check [https://en.wikipedia.org/wiki/Cross-origin_resource_sharing Cross-origin resource sharing] and [https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-cookie-same-site-00#section-4.1 Cookies SameSite] settings with the owner of the website. If you miss some configuration, you should see an error message in your browser console.''

;Websocket:Some apps need a websocket connection from the PBX. This can be used to exchange additional information or to use APIs on the PBX. Those apps need the Websocket flag checked.

Some other PBX objects also provide apps, like the Boolean object.

=== App permissions ===
In order to use an app the administrator must grant the permission to the user. This can be done using templates of at the specific user object ("Edit Object"/"Apps"). The same setting can be done in the PBX manager plugin "Templates". The user will find the apps he has access to in the "All apps" view in myApps.

==== Special case: phone apps ====
If a user has access to the "phone" or "softphone" app, it will not automatically appear in "All apps". Those apps need to be assigned to a device at the user object and will then be used for the registration on those devices. The admin can configure the app name at the individual devices in the admin UI. The user can assign the app during provisioning of phones in "Edit profile".

=== Client APIs and default apps ===
Some apps provide APIs that allow communication with other apps. An app providing an API is called an API provider. Communication is done using HTML5 window messages sent to the myApps client that dispatches them to the right app.

If there are many providers for the same API, the app can send messages to specific provider, to all providers or let the user decide. In the latter case, myApps displays a selection dialog to the user. The user can also mark an app as the default app for an API that will then be used without asking again.

Additionally the user can configure the standard apps in the myApps menu.

The default apps are stored locally on each browser / device. So the user can have a different setting on each device.

==== Special case: phone API (com.innovaphone.phone) ====
The phone apps provide a phone API that can be used by other apps to start calls. If a phone app is selected as the default phone app it has the following effects:
* When dialing a phone number (in a contacts app) the default phone app will be used for the call.
* On incoming calls the phone app is started and displayed automatically, to handle the call.

If no default phone app is selected on a device
* The user will be asked what phone app shall be used when dialing (in a contacts app)
* On incoming calls no phone app will be started

Regardless of the setting, the user can open any phone to start or receive calls.

The standard phone app can be also selected by longpressing the app tile on the home screen.

== Home screen ==
The home screen contains tiles that represent apps or items from apps - generally speaking links to apps. For example the user can place his phone app next to a contact from a contact app. Those tiles can be organized in named groups that can be collapsed, if they are currently not needed.

The presentation of a tile contains an icon, the name of the app or item and optionally a presence and a badge count provided by the app.

There are two ways for the user to add new items to the home screen:
* Click the home symbol at an app in the "All apps" view.
* Click an attach icon at an item inside an app.

Apps can be removed again the same way or by longpressing the tile and clicking "Remove from home".

=== Storage and format ===
The home screen is stored at the user object in the PBX and is synchronized over all sessions of the user.

The admin can see and configure it in the admin UI at "Edit User"/"User"/"Home Screen Apps". It is a comma-separated string of app links.

The string is limited to 8KB. If the limit is reached no more items or groups can be added to the home screen.

Format: Items starting with a colon are groups. Items starting with two colons are collapsed groups.

For example <code>:Apps,chat,users,::Contacts,users?id=jdo#d=John%20Doe&s=jdo</code>.

corresponds to
* Apps (group)
** Chat
** Users
* Contacts (collapsed group)
** "John Doe" from the app "users"

App links are URL-encoded. An App link must not appear twice.

== All apps ==
This page in myApps shows all apps that the user has access to (see: [[#App permissions|App permissions]]). Apps that are often used can be attached to the home screen.

== App Notifications ==
From version 14r1 app services can send notifications to users. Those notifications will be transmitted to and displayed by all myApps sessions of the user that have app notifications enabled. Clicking the notification will open the app with optional parameters.

=== Prerequisites ===
Launcher
* myApps for Windows from version 14r1
* myApps for macOS from version 14r1
* myApps Android from version 14r1
* myApps for iOS from version 14r1

Browser
* Supported browser with the following features enabled:
** [https://developer.mozilla.org/en-US/docs/Web/API/Push_API Push API]
** [https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API Notifications API]
** [https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API Service Worker API]
** [https://developer.mozilla.org/en-US/docs/Web/API/Client Client API]
* myApps opened using https:

PBX
* Trusted certificate with a valid DNS name. Self-signed certificates don't work.
* Push enabled, otherwise notifications will only be sent to connected myApps sesssions.

Reverse Proxy
* Trusted certificate with a valid DNS name. Self-signed certificates don't work.

=== Configuration ===
* If the feature is supported, the user can enable / disable app notifications in the hamburger menu of the myApps home screen ("App notifications").
* The setting is per device. So the user can choose on which devices he or she likes to receive notifications.
* By default app notifications are enabled in the launcher and disabled in browser sessions.
* For enabling app notifications in the browser the user needs to grant the permission for Web Notifications.

=== Some examples for apps supporting app notifications ===
* The Chat App in 14r1 uses app notifications for incoming chat messages.
* The Working App in 14r1 uses app notifications for warnings.

=== Documentation for app developers ===
[https://sdk.innovaphone.com/16r1/doc/appwebsocket/PbxApi.htm#AppNotify https://sdk.innovaphone.com/16r1/doc/appwebsocket/PbxApi.htm#AppNotify]

== Accessibility ==
For information regarding accessibility see following Article: https://wiki.innovaphone.com/index.php?title=Reference:Concept_Accessibility

== Edit profile ==
An app for managing the user profile can be configured in the admin UI at "PBX"/"Config"/"myApps"/"Edit Profile App". Typically the profile app provided by the innovaphone Users app is used for that. If configured, a menu item "Edit profile" appears in the myApps menu.

== Onboarding ==
The administrator can configure a web page that shall be displayed as an intro when a user opens myApps for the first time. The user can see the intro again by clicking "Intro" in the hamburger menu of myApps.

Configuration:
* The URL of the onboarding page can be configured at: PBX / Config / myApps / Onboarding URL. The corresponding command line attribute is <code>PBX0 /onboarding</code>. The default URL configured during install is: https://www.innovaphone.com/en/services/intro-video.html?embedded=1
* The information whether a user has already seen the onboarding is stored at the user object or template (User / Onboarding seen). The corresponding LDAP attribute is <code>onboarded</code>.

The following parameters are passed to the page using URL parameters:
;name: "onboarding"
;title: The title as shown in the hamburger menu of myApps (depending on the e.g. "Intro")
;scheme:The color scheme ("light" or "dark")
;size:The size setting of the home screen items ("0", "1" or "2")
;lang: The myApps language (e.g. "de" or "en")
;ver: The version of the PBX (e.g. "16r1")
;build: The build of the PBX (e.g. "1510335)

Requirements for the configured page:
* Must work inside an IFrame.
* Should follow the language given in the URL parameters, defaulting to "en" if no contents are available for the language.
* Should follow the collor scheme ("dark" or "light") given in the URL parameters.
* Must be responsive to work in different orientations (landscape or portrait) and on different screen sizes (Desktop and Smartphone).
* Must reserve a space (width 306px, height 102px) for an overlay button that is displayed by myApps in the bottom right corner.

== Tutorials app ==
The administrator can define an app providing tutorials or other help for end users. That app will appear in the hamburger menu of myApps as "Tutorials".

Requirements:
* Create an app object pointing to the corresponding web page (eg. https://www.innovaphone.com/myapps/tutorial.htm) via the Adv.GUI, PBX, Objects, create new App Object with a name (eg. Tutorials)
* Give users access to that app, preferably using templates (eg. Conf Users).
* Configure the app name in the admin UI "PBX"/"Config"/"myApps"/"Tutorial App" with the previous created name (eg. Tutorials).

Note: This configuration is synchronized with the client when the connection is established. So a restart of myApps is needed for the tutorials app to appear in the hamburger menu.

When installing a new PBX, a tutorial app provided by innovaphone is configured by default. It points to https://www.innovaphone.com/myapps/tutorial.htm and shows videos about the usage of myApps.

== Privacy and Datastorage ==

myApps will store the following data on your local device:

* appclient-username / appclient-password
: Auth token from the user session on this device (This is not the password itself, only a random token).
* appclient-model
: Offline-files from myApps which contains the personal user data (eg. Home screen configuration and Push tokens).
* appclient-config
: URLs and credentials for local services (credentials will be new generated randomly on every startup)
* appclient-usr-XXXXXXXXXXXXXXXXXXX
: anonymized environment settings of all historical user sessions (eg. theme, element size of home screen elements, language)

Additionally, it is allowed to every App to create own offline files or create local settings which will be stored also.

The Chromium Cache and DOM Storage (myApps for Windows) will be stored in <code>%appdata%\innovaphone\myApps\chromium\cache</code>

= Idle Bandwidth =
== myApps ==
The myApps client opens a single Websocket connection to the PBX. When the connection is idle, the PBX sends just a Websocket PING/PONG every 60s. Note that the PING/PONG exchange prevents TCP KeepAlive Messages, so there is no additional load for it.

Message IP header TCP header TLS payload Total bytes
PING 20 bytes 20 bytes 31 bytes 71 bytes
PONG 20 bytes 20 bytes 35 bytes 75 bytes
ACK 20 bytes 20 bytes - 40 bytes
------------------------------------------------------------------
186 bytes / min
11.160 bytes / h
267.840 bytes / d

== Apps ==
Most apps also open a Websocket connection to the PBX or App Platform and also use the PING/PONG mechanism. So the idle load is identical to myApps.

Message IP header TCP header TLS payload Total bytes
PING 20 bytes 20 bytes 31 bytes 71 bytes
PONG 20 bytes 20 bytes 35 bytes 75 bytes
ACK 20 bytes 20 bytes - 40 bytes
------------------------------------------------------------------
186 bytes / min
11.160 bytes / h
267.840 bytes / d

There are some apps - like the phone apps - send a Websocket message {"mt":"KeepAlive"} on application layer every 60s to the PBX to dectect connection problems faster. Note that sending the message both prevents PING/PONG by the server and TCP KeepAlive, so there is no additonal load for it. In that case the idle bandwith can be calculated like follows.

Message IP header TCP header TLS payload Total bytes
KeepAlive 20 bytes 20 bytes 53 bytes 93 bytes
ACK 20 bytes 20 bytes - 40 bytes
------------------------------------------------------------------
133 bytes / min
7.980 bytes / h
191.520 bytes / d

= Troubleshooting =

Client-side
*The myApps web uses the logging facilities provided by the browser it runs in (i.e. JavaScript function <code>console.log</code>). In most browser this is available as ''Console'' after pressing F12.
*The myApps platform services provide more elaborate tracing mechanisms. See ''Troubleshooting'' in [[{{NAMESPACE}}:Concept_myApps_platform_services#Troubleshooting|Concept myApps platform services]].

PBX-side
*The Syslog can be used to log all connections to the PBX. See [[Reference16r1:Concept_myApps#Syslog]].
*You can activate the trace flag Servlets to see all websocket messages from and to the PBX. <code>!config add HTTP0 /servlet-trace on</code>

= Related Articles =
* [[{{NAMESPACE}}:Concept myApps platform services]]

= Known Problems =

[[:Category:Problem_myApps|Known Problems]]

Courseware:IT Plus Overview

2026-05-19T08:29:33Z

Ckl:

''innovaphone Plus'' is a series of courses, each covering advanced aspects of the configuration of innovaphone devices in separate topics. Each topic can be worked through on individually or in any order. Further topics will be added over time. Each topic is based on the latest firmware at the time of creation. All topics based on the same firmware version (e.g. 14r2) are included in the same course of the series.

Access to ''innovaphone Plus'' requires a valid innovaphone ''Plus'' corporate subscription. See [https://www.innovaphone.com/en/partner/training/innovaphone-plus-training.html innovaphone Plus Training] for details.

The rest of this article gives you an overview of the topics covered and in which course they can be found.
__NOEDITSECTION__
{{#invoke-url: https://class.innovaphone.com/moodle2/itplus-overview.php?wiki=true}}

Reference13r2:Concept Talking to the v13 Application Platform using PHP

2025-07-09T10:49:09Z

Ckl: /* PBX / App Platform */

This is a slight rewrite of the [[Reference13r1:Concept Talking to the v13 Application Platform using PHP | older article]] in the Reference13r1 namespace. While there is nothing technically wrong with the old article, some of the authentication methods described there are no longer recommended for use with scripts. In particular, it is not recommended that a script authenticate as a PBX user. Instead, it should always authenticate against a PBX ''App'' type object. If the script needs to access other App services, it should use the ''Services'' API described in https://sdk.innovaphone.com/13r2/doc/appwebsocket/Services.htm.

==Applies To==
This information applies to

* innovaphone platform running the 13r2 (or later) ''App Platform ''
* PBX running 13r2 (or later) firmware
* PHP script accessing the ''App Services'' available on the ''App Platform''

==More Information==
===Problem Details===
The v13 App Platform runs several ''App Services'' that provide services used by ''Apps'' running in the context of the ''myApps'' client. Apps (written in JavaScript) are loaded from the App Platform and launched by the myApps client. They communicate with the App Services using a JSON-based WebSocket protocol. ''Apps'' can also be loaded from the PBX (so called ''PBX Apps'').

The ''vanilla'' way to go when it comes to 3rd party integration is to write a ''custom App Service'' and install it on the ''App Platform''. The creation of such ''App Services'' is facilitated by the [https://sdk.innovaphone.com/13r2/doc/sdk.htm ''v13 SDK''].

Note: The mechanisms described here are available in the 13r2 SDK, so all links to the SDK are given for the 13r2 version. To access other versions of the SDK as they become available, go to [https://sdk.innovaphone.com SDK root] and follow the links to the version of interest.

[[Image:app-platform-php-appplatform-simplified.png]]

However, in some scenarios you may want to talk to the PBX or existing App Services directly from your own application (i.e. not via an App running in the myApps client). This article describes how to do this. General considerations are given that apply to all programming languages, and some sample code is given in PHP.

[[Image:app-platform-php-appplatform-simplified-3rd-party.png]]

==== Authentication ====
To talk to the PBX or another ''App Service'', your application (written in PHP or any other language that can talk to a WebSocket) needs to be logged in to the PBX. While an ''App'' does not need to worry about this, as the ''myApps'' client (which is the context in which all ''Apps'' run) would take care of this, an App Service needs to implement the protocol itself.

The process is as follows:
* An ''App'' type object must be created on the PBX for your application.
* The ''App'' object defines the authentication credentials (''Name'' and ''Password'') as well as the access rights of your application (i.e., the APIs in the ''App'' tab, the licenses in the ''License'' tab, and the Apps in the ''Apps'' tab)
* The application must log in to the PBX using the credentials configured for the ''App'' type object that corresponds to the application. In other words, it logs in as the App, not as a specific user
* The application can then use the allowed PBX APIs (according to the definitions in the ''Grant access to APIs'' section in the ''App'' tab of the ''App'' object).
* The application can authenticate to other allowed App services (as defined in the ''Apps'' tab of the ''App'' object) using the PBX ''Services'' API. It can then request services from these App Services

==== WebSocket ====
''App Services'' (as well as the aforementioned PBX APIs) communicate using messages sent through WebSockets. The content of those messages has JSON syntax.

Although WebSockets are based on the HTTP protocol (for example, they usually use ports 80/443), they behave fundamentally different than HTTP connections in that they are ''asynchronous''. With HTTP, all requests are synchronous, that is, each request is responded to by an answer. Also, only the HTTP client can send requests, not the server. With WebSocket however, both sides can (once they have agreed to upgrade the HTTP connection to a WebSocket connection) send messages at any time. Such messages may trigger 0, 1 or more response messages, depending on the application protocol. The protocol itself does not define a relation between a message and its response messages. As there is no such thing as a synchronous ''request/response'' cycle with WebSocket, an asynchronous programming model is required to take full advantage of the WebSocket approach.

==== JSON ====
JSON stands for ''J''ava''S''cript''O''bject''N''otation. It is a subset of the syntax JavaScript uses to denote (complex) data constants. Here is an example: <code >{"mystring":"a","myint":42}</code>. As such, it allows to store the value of an object as a string and also to set the value of an object from a string (a process known as ''serialization/unserialization'' in many programming languages). JSON allows us to put the value of an object in to a WebSocket message and also of course to retrieve such value from a WebSocket message. Compared to XML (which more or less allows the same), it is much more compact.

Although JSON is related to JavaScript, most programming languages can deal with it. For example, PHP has the <code>json_encode()</code> and <code>json_decode()</code> functions, C# has the <code> DataContractJsonSerializer</code> class.

Here is a full example of the JSON message that might be used to authenticate towards the PBX
<syntaxhighlight lang="json">
{
"mt": "AppLogin",
"digest": "955da4b8351557c54c25b99fa8aad9e8b4ba7a4090ac5c2664e7ef7a301e6586",
"domain": "",
"sip": "",
"guid": "",
"dn": "",
"app": "myapplication",
"info": {}
}
</syntaxhighlight>

When working with ''App Services'', there are three message members which are somehow special for all such services.
; mt (string) : the ''m''essage ''t''ype. Each message must have an <code>mt</code> member which denotes the message type
; api (string, optional) : some App services (and in particular the PBX) support different defined sets of messages (referred to as ''api''). In this case, the ''mt'' message member is not sufficient to specify the type of message. Instead, the API identifier must be given in the ''api'' message member. The [https://sdk.innovaphone.com/13r2/doc/appwebsocket/RCC.htm RCC api] provided by the PBX would be an example where all messages sent to or received from the PBX for this API must have an ''api'' message member with the (string) value <code>"RCC"</code>
; src (string, optional) : this member may be sent along with messages sent to an ''App Service''. If the message triggers responses, the ''App Service'' will copy the <code>src</code> member in to the responses. This allows the client to associate responses to the message that initiated them.
All other members (if any) are defined by the application protocol.

==== Definition of Application Protocols ====
Message types, their members and the message flow are part of the documentation in the [https://sdk.innovaphone.com/13r2 software development kit (SDK)] that comes with the ''App Platform''. In this article, we only touch them for educational purposes.

=== PHP Sample Code ===
These scripts use a configuration from a file called ''my-pbx-data.php''.

To provide proper data for your environment to the scripts, create the file ''my-pbx-data.php'' as follows:
<syntaxhighlight lang="php">
<?php
$pbxdns = "your-pbx-dns-or-ip";
$pbxapp = "your-app-object-name";
$pbxpw = "your-pbx-app-password";
</syntaxhighlight>

Our little example (available in <code>application.php</code>) will connect to 2 ''App Services'' on the ''App Platform'', ''Devices'' and ''Users'' to retrieve some configuration data. To authenticate towards the App service instances, a dedicated PBX ''App'' object in the PBX with appropriate rights is used.

===== PBX configuration =====
You will need a PBX which has been set up using the standard ''Install'' procedure (http://$pbxdns /install.htm).

On that PBX, you additionally need to create an ''App'' type object
* whose ''Name'' property is equal to the value of ''$pbxapp''
* whose ''Password'' is equal to the value of ''$pbxpw''
* that has ticked ''Services'' in the ''Grant access to APIs'' section of the ''App'' tab
* that has ticked ''devices-api'' and ''users-admin'' in the ''Apps'' tab

===== Login =====
Logging-in to the PBX requires the following steps:
* request a challenge from the PBX using the ''AppChallenge'' message
: <syntaxhighlight lang="json">sent->PBXWS {"mt":"AppChallenge"}</syntaxhighlight >
* receive the challenge from the PBX
: <syntaxhighlight lang="json">received<-PBXWS {"mt":"AppChallengeResult","challenge":"8b7d8a1a3a281efd"}</syntaxhighlight >
* compute the digest based on the App data, the secret and the challenge
: <syntaxhighlight lang="json">sent->PBXWS
{
"mt": "AppLogin",
"digest": "1a07f3c20d2a4f6b117c64d845b9bed7b884b49b82868f0e2b73200553c40e2d",
"domain": "",
"sip": "",
"guid": "",
"dn": "",
"app": "myapplication",
"info": {}
}</syntaxhighlight >
* receive the confirmation from the PBX
<syntaxhighlight lang="json">received<-PBXWS {"mt":"AppLoginResult","ok":true}</syntaxhighlight >

This handshake is implemented in the ''AppPlatform\AppLoginAutomaton'' class available in classes\websocket.class.php. The thing that needs to be added is the WebSocket connection to the PBX (an ''AppPlatform\WSClient'' object required as constructor argument for the ''AppPlatform\AppLoginAutomaton'' class). We do this using a derived class named ''PbxAppLoginAutomaton'':

<syntaxhighlight lang="php">
class PbxAppLoginAutomaton extends AppLoginAutomaton {

function __construct($pbx, AppServiceCredentials $cred, $useWS = false) {
$this->pbxUrl = (strpos($pbx, "s://") !== false) ? $pbx :
$this->pbxUrl = ($useWS ? "ws" : "wss") . "://$pbx/PBX0/APPS/websocket";
// create websocket towards the well known PBX URI
$this->pbxWS = new WSClient("PBXWS", $this->pbxUrl);
parent::__construct($this->pbxWS, $cred);
}
}
</syntaxhighlight>

This class takes the URL to the PBX and the credentials (wrapped in an object of class ''AppPlatform\AppServiceCredentials'') as constructor arguments:

<syntaxhighlight lang="php">
$app = new PbxAppLoginAutomaton($pbxdns, new AppPlatform\AppServiceCredentials($pbxapp, $pbxpw));
</syntaxhighlight>

Our new class ultimately is a derivative of the ''AppPlattform\FinitStateAutomaton'' class, so we can run the automaton like:

<syntaxhighlight lang="php">
$app->run();
</syntaxhighlight>

The automaton will do the authentication towards the PBX as shown above and then terminate (which causes the ''run()'' member function to return).

The code then verifies that the log-in to the PBX succeeded:

<syntaxhighlight lang="php">
if (!$app->getIsLoggedIn()) {
die("login to the PBX failed - check credentials");
}
</syntaxhighlight>

Eh voilà, we are connected to the PBX.

That was the easy part :-)

Note that the code for the ''PbxAppLoginAutomaton'' can be found in the classes/websocket.class.php file.

===== Determination of available services =====
Now that we are successfully connected to the PBX, we can determine the services that are available to our application. This is done using the ''Services'' API available in the PBX (which is described in the SDK's [https://sdk.innovaphone.com/13r3/doc/appwebsocket/Services.htm ''Services'' page]).

Only a few steps are required:
* subscribe to the available services information
: <syntaxhighlight lang="json">sent->PBXWS {"mt":"SubscribeServices","api":"Services"}</syntaxhighlight>
: note the additional <code>api</code> member
* receive the respones
: <syntaxhighlight lang="json">received<-PBXWS {"api":"Services","mt":"SubscribeServicesResult"}</syntaxhighlight>
: note that there is no further information in this message. The actual list of services will be received later on
* unsubscribe from the list of services as we do not need dynamic updates
: <syntaxhighlight lang="json">sent->PBXWS {"mt":"UnsubscribeServices","api":"Services"}</syntaxhighlight>
* receive the actual list of services available to us
: <code>received< - PBXWS </code>
: <syntaxhighlight lang="json">
{
"api": "Services",
"mt": "ServicesInfo",
"services": [{
"name": "devices-api",
"title": "DevicesApi",
"url": "https://192.168.178.71/sample.dom/devices/innovaphone-devices-api",
"info": {
"apis": {
"com.innovaphone.devices": {}
}
}
}, {
"name": "users-admin",
"title": "Users Admin",
"url": "https://192.168.178.71/sample.dom/usersapp/innovaphone-usersadmin"
}]
}
</syntaxhighlight>
: note that the actual list of services depends on the configuration of the ''Apps'' tab in the ''App'' object for our application

Life was easy so far as we have derived the ''PbxAppLoginAutomaton'' utility class which simply did what we wanted so far, except for the initialization in its constructor. Now we want to implement further conversation with the PBX, which requires some more fundamental understanding of the finite state automaton classes.

===== The finite state automaton classes =====
Generally, to talk to the PBX or any App service, you can of course use just any WebSocket library directly. We are using (and recommending) a derivative of the [https://github.com/Textalk/websocket-php Textalk] websocket classes. We simplified the code a bit and also added support for receiving WebSocket messages asynchronously. You will find this code in <code>classes/textalk.class.php</code>.

However, solely using the textalk classes leaves you with quite a bit of work to do. As discussed above, there are some challenges:
* websocket is async by nature
: you will need some support for receiving messages asynchronously at least. Aside from the support for asynchronous receipt of messages added to the Textalk classes, the sample code has some classes which allow you to easily create ''event driven'' code which processes messages whenever they come in and not when you expect them to come in
* PBX login requires some fiddling with encryption schemes

The sample code includes some classes to create ''finite state automatons''. Also it has some classes derived from this, which actually implement the protocols required to log-in to the PBX and the ''App Services''

Those extensions can be found in <code>classes/websocket.class.php</code>.

===== The asynchronous programming model =====
PHP is not really nicely prepared for asynchronous programming. To deal with that, we have created a utility class called ''FinitStateAutomaton''. This class handles the communication to a single ''App Service''. This is why it has a WebSocket connection as argument to the constructor (our WebSocket implementation is actually called ''WSClient''). The class will use this WebSocket to talk to the ''App Service''. As we have seen above, the ''PbxAppLoginAutomaton'' utility class creates such an ''WSClient'' object and passes it to the ''AppLoginAutomaton'' (which extends the ''FinitStateAutomaton'' class).

However, if you try to instantiate such a class (like <syntaxhighlight lang="php">$mya = new FinitStateAutomaton($mywebsocket)</syntaxhighlight> you will see that this is not possible, as the class is ''abstract''. This means that there are some member functions missing which must be implemented by a derived class. These functions are those which know how to handle messages received from the ''App Service''.

Let us look at how the ''AppLoginAutomaton '' class does this:

<syntaxhighlight lang="php">
class AppLoginAutomaton extends FinitStateAutomaton {
public function ReceiveInitialStart(Message $msg) {

$this->log("requesting challenge");
$this->sendMessage(new Message("AppChallenge"));

}
}
</syntaxhighlight>
It defines an override for the abstract ''ReceiveInitialStart'' member function. This function, as all functions whose name begins with ''Receive'' is called when an event is fed into the automaton. Usually, this event is a message (of type ''AppPlatform\Message'') received from an app service. In this special case however, it is a pseudo event generated by the system indicating that the automaton should start (hence the name ''ReceiveInitial'''Start'''''). So it implements the first action the automaton performs.

In our case, as discussed above, it sends an ''AppChallenge'' message to the PBX. Recall that such an automaton is always instantiated with a single ''WSClient'' argument, which is the WebSocket connection used to talk to the App service (or the PBX which behaves like an App service). In other words, a single instance of a ''FinitStateAutomaton'' always talks to a single App service only. This is why we can simply say

<syntaxhighlight lang="php">
$this->sendMessage(new Message("AppChallenge"));
</syntaxhighlight>
without specifying a destination and resulting in an AppChallenge message
<syntaxhighlight lang="json">
sent->PBXWS {"mt":"AppChallenge"}
</syntaxhighlight>
sent to the PBX.

Eventually, the PBX will respond with an ''AppChallengeResult'' message.
<syntaxhighlight lang="json">
received<-PBXWS {"mt":"AppChallengeResult","challenge":"95ed003a24c3fc89"}
</syntaxhighlight>
When this happens, the system will call the ''ReceiveInitial'''AppChallengeResult''''' member function:

<syntaxhighlight lang="php">
public function ReceiveInitialAppChallengeResult(Message $msg) {
$infoObj = new \stdClass();
$infoHashString = json_encode($infoObj, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$hashcode = hash('sha256', $sha = "{$this->cred->app}:::::{$infoHashString}:{$msg->challenge}:{$this->cred->pw}");
// $this->log("computed challenge $sha", "debug"); // do not output in any other category than "debug" coz it includes the password
$this->sessionKey = hash('sha256', "innovaphoneAppSessionKey:{$msg->challenge}:{$this->cred->pw}");
$this->sendMessage($this->loginData = new Message("AppLogin", "digest", $hashcode, "domain", "", "sip", "", "guid", "", "dn", "", "app", $this->cred->app, "info", $infoObj));
}
</syntaxhighlight>

It does some cryptographic magic to compute a digest from the available information and then sends an ''AppLogin'' message to the PBX:

<syntaxhighlight lang="php">
$this->sendMessage($this->loginData = new Message("AppLogin", "digest", $hashcode, "domain", "", "sip", "", "guid", "", "dn", "", "app", $this->cred->app, "info", $infoObj));
</syntaxhighlight>
resulting in a message such as
<syntaxhighlight lang="json">
sent - >PBXWS {
"mt": "AppLogin",
"digest": "955da4b8351557c54c25b99fa8aad9e8b4ba7a4090ac5c2664e7ef7a301e6586",
"domain": "",
"sip": "",
"guid": "",
"dn": "",
"app": "myapplication",
"info": {}
}
</syntaxhighlight>
being sent to the PBX.

The PBX would verify the correctness of the provided digest and then return an ''AppLoginResult'' message.
<syntaxhighlight lang="json">
received<-PBXWS {"mt":"AppLoginResult","ok":true}
</syntaxhighlight>
Due to the reception of such a message, the ''ReceiveInitialAppLoginResult'' member function is called. It does a bit of internal housekeeping and then does two interesting things:
<syntaxhighlight lang="php">
public function ReceiveInitialAppLoginResult(Message $msg) {

$response->setMt("AppLoginSuccess");
$this->postEvent($response);

return "Dead";
}
</syntaxhighlight>
This code creates a ''$response'' message and sets the ''mt'' member to <code>AppLoginSuccess</code>. It returns the string "Dead" then.

The event function (''ReceiveInitialAppChallengeResult'') we looked at so far did not have any explicit return statement. In PHP terms that means that it returns a ''null'' value. When an event returns a string however, it indicates that the automaton shall move to a new state.

In our case, the new state is named "Dead" and it has a special meaning. An automaton in state "Dead" is considered to be terminated. The system will not listen for incoming messages on the automaton's WSClient socket any further.

Note that the initial state of any automaton is named <code>Initial</code>. This is why event member functions are named ''Receive'''Initial'''Start'' for example. If a member function returns a new state name other than <code>Dead</code>, the member functions called upon subsequent incoming messages will be named ''Receive'''NewStateName'''Event''. Also, the first thing the system will do is call the ''Receive'''NewStateName'''Start'' member function.

===== Working with multiple automatons =====
Obviously, applications may want to talk to multiple destinations, e.g. to the PBX for authentication and to one or more other App services. As a single ''FiniteStateAutomaton'' always talks to a single ''WSClient'' connection, we need to instantiate multiple automatons to be able to talk to multiple destinations:

<syntaxhighlight lang="php">
$a1 = new Type1Automaton();
$a2 = new Type2Automaton();
$transitioner = new AppPlatform\Transitioner($a1, $a2);
$transitioner->run();
</syntaxhighlight>

''AppPlatform\Transitioner'' is a helper class that takes a number of automatons (either listed as multiple arguments or wrapped in an array and given as single argument) as constructor arguments. When its ''run'' member function is called, it will in turn call all of the automatons ''ReceiveInitialStart'' member functions and then listen for messages coming in on any of the automatons ''WSClient'' connections.

By the way, the ''FinitStateAutomaton'''s own ''run'' member function is trivial:

<syntaxhighlight lang="php">
/**
* utility function for the simple case you want to run a single (i.e. this) automaton only
*/
public function run($sockettimeout = 5) {
$auto = new Transitioner($this);
$auto->run($sockettimeout);
}
</syntaxhighlight>

The remaining question is how different automaton instances communicate to each other. This is done using the ''FinitStateAutomaton'''s ''postMessage'' member function as in

<syntaxhighlight lang="php">
$this->postEvent($response);
</syntaxhighlight>

shown above in the ''ReceiveInitialAppLoginResult'' event function. When ''postEvent'' is called, the system would call the corresponding event functions in all currently active automatons. Note that these member functions are called synchronously, that is, they are already executed when the ''postEvent'' function returns.

===== Tandems =====
The ''postEvent'' mechanisms allows two or more automatons to work in tandem. To see how that works, we can have a look at the ''Pbx2AppAuthenticator'' class.

<syntaxhighlight lang="php">
/**
* class that authenticates to an App service with help from the PBX
*/
class Pbx2AppAuthenticator extends \AppPlatform\FinitStateAutomaton {
</syntaxhighlight>
This class takes a ''ServiceConnector'' as constructor argument (for example one delivered from the ''PbxAppLoginAutomaton'') and creates a WebSocket connection (actually a ''WSClient'' object) towards the App service described by the ''ServiceConnector''.

<syntaxhighlight lang="php">
public function __construct(ServiceConnector $svc) {
$this->svc = $svc;
parent::__construct($svc->connect(), $svc->name);
}
</syntaxhighlight>
The first thing it then does is to send an ''AppChallenge'' message to the service:
<syntaxhighlight lang="php">
public function ReceiveInitialStart(Message $msg) {
$this->sendMessage(new Message ("AppChallenge"));
}
</syntaxhighlight>
When the service returns the challenge, the class needs help from the ''PbxAppLoginAutomaton'' class (which talks to the PBX as we have seen before). To get help, it posts a ''GotChallenge'' message which includes the challenge received from the service and the name of that service.
<syntaxhighlight lang="php">
public function ReceiveInitialAppChallengeResult(Message $msg) {
$this->postEvent(new Message ("GotChallenge", "from", $this->svc->name, "challenge", $msg->challenge));
}
</syntaxhighlight>

When the ''PbxAppLoginAutomaton'' class (which has already been used to authenticate towards the PBX) is activated again (resulting in a call of its ''ReceiveInitialStart'' event function) it will determine that it already obtained a service list from the PBX (see above) and will therefore move into the new state named ''SvcAuthenticate''.
<syntaxhighlight lang="php">
public function ReceiveInitialStart(Message $msg) {
if (empty($this->services)) {
// initial login to the PBX
return parent::ReceiveInitialStart($msg);
}
else {
// PBX assisted login towards App services
return "SvcAuthenticate";
}
}
</syntaxhighlight>
When the ''GotChallenge'' event is posted, the ''ReceiveSvcAuthenticateGotChallenge'' event function is called
<syntaxhighlight lang="php">
public function ReceiveSvcAuthenticateGotChallenge(Message $msg) {
$this->log("got challenge info from $msg->from");
$this->sendMessage(new Message ("GetServiceLogin", "api", "Services", "app", $msg->from, "challenge", $msg->challenge, "src", $msg->from));
}
</syntaxhighlight>
and sends a ''GetServiceLogin'' message to the PBX which includes the service name and the challenge. It also includes a ''src'' property set to the name of the App. This will instruct the PBX to include the same property when the response is sent, so that the returned information can be associated with the proper service later on.

The PBX will eventually respond with a ''GetServiceLoginResult'' message. This needs to be passed to the ''Pbx2AppAuthenticator'' class instance which will send it to the service. This is done using the ''postEvent'' mechanism again:
<syntaxhighlight lang="php">
public function ReceiveSvcAuthenticateGetServiceLoginResult(Message $msg) {
$this->postEvent(new Message ("GotChallengeResult", "for", $msg->src, "msg", $msg));
</syntaxhighlight>
The ''Pbx2AppAuthenticator'' class instance which is interested in exactly this ''GetServiceLoginResult'' response has a ''ReceiveInitialGotChallengeResult'' event function which is called due to this ''postEvent'':
<syntaxhighlight lang="php">
public function ReceiveInitialGotChallengeResult(Message $msg) {
if ($msg->for == $this->svc->name) {
$this->sendMessage(new Message ("AppLogin",
"app", $msg->msg->app,
"domain", $msg->msg->domain,
"sip", $msg->msg->sip,
"guid", $msg->msg->guid,
"dn", $msg->msg->dn,
"digest", $msg->msg->digest,
"pbxObj", $msg->msg->pbxObj,
"info", $msg->msg->info));
}
}
</syntaxhighlight>
The function verifies that it has been called for the challenge result it is actually interested in and then passes it to its service. The service will return an ''AppLoginResult'' message which is processed by the ''ReceiveInitialAppLoginResult'' function:
<syntaxhighlight lang="php">
public function ReceiveInitialAppLoginResult(Message $msg) {
if (empty($msg->ok) || $msg->ok != 1) {
$this->log("FAILED to log in to $msg->app ($this->svc->name", "error");
}
else {
$this->log("logged in to $msg->app ({$this->svc->name})", "runtime");
$this->svc->authenticated = true;
}
return "User";
}
</syntaxhighlight>
The event function checks if the login was successfull (it should have been) and then moves into the new "User" state. This will trigger the ''ReceiveUserStart'' to be called which simply moves to the ''Dead'' state (that is, it terminates the automaton).
<syntaxhighlight lang="php">
/**
* this simply ends the automaton. Override it if you derive a class from this
* @param Message $msg
* @return string
*/
public function ReceiveUserStart(Message $msg) {
//
return "Dead";
}
</syntaxhighlight>

So why is this? This is just convenience. In a real application, we obviously would want to continue talking to the service but the ''Pbx2AppAuthenticator'' class doesn't know how to. So we would certainly create a new class of our own which extends the ''Pbx2AppAuthenticator'' class and overrides the '' event function. A very simple example can be seen in the ''application.php'' script:
<syntaxhighlight lang="php">
class UsersLister extends AppPlatform\Pbx2AppAuthenticator {
public function ReceiveUserStart(\AppPlatform\Message $msg) {
$this->sendMessage(new AppPlatform\Message("UserData",
"maxID", 9999, "offset", 0, "filter", "%", "update", false, "col", "id", "asc", true));
}

public function ReceiveUserUserDataInfo(\AppPlatform\Message $msg) {
$this->log("from {$this->svc->name}: user: id $msg->id, name $msg->username", "runtime");
return "Dead";
}
}
</syntaxhighlight>
This sample class simply sends a ''UserData'' message to the ''users-admin'' service and prints out the user information from the resulting ''UserDataInfo'' response.

So this was an example of how automatons can work in tandem. However, the mechanism can also be used to work with more than two automatons. In the sample code, an instance of the ''Pbx2AppAuthenticator'' class (more precisely, a derived class such as the ''UsersLister'' class above) is created for each of the services listed by the PBX as available to our App. They are pushed into an array of ''FinitStateAutomaton''s in addition to the instance of the ''PbxAppLoginAutomaton'' class used to talk to the PBX:
<syntaxhighlight lang="php">
// connect to services we need
$authenticators = [$app];

// scan list of available app services for those we are interested ion
foreach ($app->getServices() as $svc) {
/* consider if we need this */
switch ($svc->type) {
case "innovaphone-devices-api":
$authenticators[] = new DevicesLister($svc);
break;
case "innovaphone-usersadmin":
$authenticators[] = new UsersLister($svc);
break;
}
}
</syntaxhighlight>
The resulting list of tasks is then run using the ''Transitioner'' helper class:
<syntaxhighlight lang="php">
// tell class talking to PBX how many authentications we need to do
$app->setNumberOfAuthentications(count($authenticators) - 1);

$tr = new AppPlatform\Transitioner($authenticators);
$tr->run();
</syntaxhighlight>

=== More sample code ===
==== Using the PbxAdminApi ====
This is a simple piece of code that uses the [https://sdk.innovaphone.com/13r3/doc/appwebsocket/PbxAdminApi.htm PbxAdminApi] to create a duplicate of the App object we were using in the first sample code (''application.php''). It is available in ''pbxadminapi.php''. Before you can use the sample, you must make sure that the ''Admin'' check-mark is ticked in the ''App'' tab of your App object.

It first uses the ''PbxAppLoginAutomaton'' to log in to the PBX.

<syntaxhighlight lang="php">
// Login to PBX
$app = new AppPlatform\PbxAppLoginAutomaton($pbxdns, new AppPlatform\AppServiceCredentials($pbxapp, $pbxpw));
$app->run();
if (!$app->getIsLoggedIn()) {
die("login to the PBX failed - check credentials");
}
</syntaxhighlight>

It then uses a new derivative of the ''FiniteStateAutomaton'' class to create the cloned object, passing the WSClient object used by the ''PbxAppLoginAutomaton'' class to its constructor:
<syntaxhighlight lang="php">
/**
* class to create a new PBX App object just like the one we use for this application
*/
class AppObjectCreator extends AppPlatform\FinitStateAutomaton {

public function ReceiveInitialStart(AppPlatform\Message $msg) {
//
{
return "CopyObject";
}
}

/**
*
* @global string $pbxapp h323-name of source App object
* @param AppPlatform\Message $msg
*/
public function ReceiveCopyObjectStart(AppPlatform\Message $msg) {
global $pbxapp;
$this->sendMessage(new AppPlatform\Message(
"GetObject",
"api", "PbxAdminApi",
"h323", $pbxapp));
}

public function ReceiveCopyObjectGetObjectResult(AppPlatform\Message $msg) {
// patch $msg so it can be used for object creation
$msg->setMt("UpdateObject");
// a new one shall be created, no update of the exiting one
unset($msg->guid);
// assert unique identifiers
$msg->h323 .= "-clone";
$msg->cn .= " (clone)";
// we don't want any "Devices" entries
unset($msg->devices);

$this->sendMessage($msg);
}

public function ReceiveCopyObjectUpdateObjectResult(AppPlatform\Message $msg) {
if (isset($msg->guid)) {
$this->log("App object clone created with Guid $msg->guid", "runtime");
} else {
$this->log("App object clone could not be created: $msg->error", "runtime");
}
return "Dead";
}
}
$me = new AppObjectCreator($app->getWs());
$me->run();
</syntaxhighlight>

==== Using the RCC API ====
To run this sample code, you must make sure
* there is a waiting queue with ''Name'' (h323/sip) <code>sink</code>
: * it has an ''Alert Timeout'' set to a reasonable number (some seconds, e.g. 3)
: * it has the ''1st Announcement URL'' set to <code>MOH</code>
* there must be a user object
: * it has our application (''myapplication'') check-mark ticked in its ''Apps'' tab
: * it has a phone registered or a softphone provisioned
* the App object for our application (''myapplication'') must have the ''RCC'' check-mark ticked in its ''App'' tab

This sample code demonstrates use of the [http://sdk.innovaphone.com/13r2/doc/appwebsocket/RCC.htm RCC] API. It monitors some PBX user objects and shows all related calls. If a peer named ''sink'' is called, the call is forcefully terminated by our script. It is available in the ''rccapi.php'' sample code file.

The code uses a derivative of the ''FinitStateAutomaton'' class called ''RemoteControlUser''. The first thing it does is to send an ''Initialize'' message to the PBX which initializes the use of the ''RCC'' api.

<syntaxhighlight lang="php">
class RemoteControlUser extends AppPlatform\FinitStateAutomaton {

private $myusers = [];
private $mycalls = [];

public function ReceiveInitialStart(AppPlatform\Message $msg) {
// move to Monitoring state
return "Monitoring";
}

public function ReceiveMonitoringStart(AppPlatform\Message $msg) {
// Initialize RCC Api
$this->sendMessage(new AppPlatform\Message(
"Initialize",
"api", "RCC"
));
}
</syntaxhighlight>

The PBX will send a number of ''UserInfo'' messages in response to the ''Initialize'' message. One message will be sent for each user that has our application check-mark ticked in its ''Apps'' tab. Those users then are said to be monitored by the application using the RCC API.

For each new monitored user that is announced this way, the user information is stored in a class-local array. Also, an ''UserInitialize'' message is sent.

<syntaxhighlight lang="php">
public function ReceiveMonitoringUserInfo(AppPlatform\Message $msg) {
// remember UserInfo and do UserInitialize on the user
if (isset($this->myusers[$msg->h323])) {
$this->log("user '$msg->h323' updated", "runtime");
}
else {
$this->log("new user '$msg->h323'", "runtime");
$this->myusers[$msg->h323] = new stdClass();
$this->sendMessage(new AppPlatform\Message(
"UserInitialize",
"api", "RCC",
"cn", $msg->cn,
"src", $msg->h323 // use "src" to be able to associate response
));
}
$this->myusers[$msg->h323]->info = $msg;
}
</syntaxhighlight>

The ''UserInitializeResponse'' message will include a client-local identifier for the initialized user called ''user''. We remember it in our class-local array of users:

<syntaxhighlight lang="php">
public function ReceiveMonitoringUserInitializeResult(AppPlatform\Message $msg) {
// remember local user id returned from UserInitialize (associated by "src")
$this->myusers[$msg->src]->user = $msg->user;
}
</syntaxhighlight>

When a user object is monitored (that is, when there was a successful ''UserInitializeResponse'' message), the PBX will start to send additional ''CallInfo'' messages for each call related to the user and for all call-state changes.

We look at those messages and determine if the remote party (the ''peer'') is called ''sink''. If so, we remember this call. If such remembered call later announces to be connected (a ''CallInfo'' message with ''msg'' member ''r-conn'' is received, we terminate the call by sending an appropriate ''UserEnd'' message.

<syntaxhighlight lang="php">
public function ReceiveMonitoringCallInfo(AppPlatform\Message $msg) {
// a call state update
$this->log("user $msg->user call $msg->call event $msg->msg", "runtime");
// see if the call is towards the waiting queue "sink"
if (isset($msg->peer) && isset($msg->peer->h323) && $msg->peer->h323 == "sink") {
$this->log("user $msg->user call $msg->call with peer h323=sink (notified with $msg->msg)", "runtime");
// remember this call for monitoring
$this->mycalls[$msg->call] = $msg;
}

// check if we monitor this call and if we are connected
if (isset($this->mycalls[$msg->call])) {
switch ($msg->msg) {
case "r-conn" :
$this->log("call $msg->call connected ($msg->msg) - disconnecting", "runtime");
$this->sendMessage(new AppPlatform\Message(
"UserClear",
"api", "RCC",
"call", $msg->call,
"cause", 88, // "Incompatible destination" see https://wiki.innovaphone.com/index.php?title=Reference:ISDN_Cause_Codes
));
break;
case "del" :
$this->log("call $msg->call ended ($msg->msg) - terminating", "runtime");
return "Dead";
}
}
}
</syntaxhighlight>

There is one other interesting mechanism which is used in this script:
<syntaxhighlight lang="php">
public function timeout() {
$this->log("timeout", "runtime");
}
</syntaxhighlight>

When the system waits for incoming events, there is (by default) a timeout of 5 seconds. If there are no incoming events during this time, an error message is issued and all the automatons are terminated. However, if an automaton implements an override for the ''timeout'' function and it does not return true, the timeout will be ignored. This is why our script waits a long time for the end of the call, occasionally spitting out a log message.

===System Requirements===
To run the sample code, you need
* a platform that is able to run v13r2 PBX firmware (e.g. an IP411, but any other will do too)
* a platform that can run the v13r2 app platform (the same IP411 would do), so if you choose to use a gateway, you will need an SSD
* a web server running PHP 8.x or up (the code has not been tested with PHP 5.6 or 7, but it may run with no problems)
* your favourite PHP IDE

You can download the PBX firmware from [https://store.innovaphone.com/release/download.htm store.innovaphone.com].

===Installation===
The PBX and App Platform is installed using the ''Install''.
==== PBX / ''App Platform'' ====
* if you choose to use a gateway platform, install an SSD
* upgrade your box (or IPVA) to the latest v13r2 (or later)
* you will need two extra IP address. One for the ''App Platform'', one for the PBX
* perform a factory reset
* access the box and you will see the installer (if not, use <code>htps://<ip-of-our-pbx>/install.htm</code>)
* complete the installer using IP addresses instead of DNS names, so that it installs a PBX and a fresh ''App Platform'' (you can of course also use DNS names during the Install if you have them operational for the PBX and App platform IP addresses. For running the sample code, it does not matter)
* be sure to note the ''Admin Password'' shown in the installer
* the installer will ask for the name of an ''admin account''. Be sure to note name and password.
* for convenience, consider to not turn on ''two factor authentication''

==== PHP Script ====
* unpack the sample sources in to your web server's content directories
* make sure PHP scripts can be executed in the ''.../sample/sources'' directory
* configure the PBX according to the hints given with the individual sample code above
* open the file ''application.php'' in your browser

===Known Problems===

====Missing php_openssl extension====
In case following error appears, make sure to enable php_openssl in your php environment configuration:
Fatal error: Uncaught Error: Call to undefined function AppPlatform\openssl_random_pseudo_bytes()

=== Download ===
The sample code can be downloaded [http://wiki.innovaphone.com/index.php?title=Howto:Wiki_Sources#websocketphp8 here ]


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

Reference7:HTTP Request Message Format

2025-06-17T13:55:46Z

Ckl: /* POST */

innovaphone devices will send data to external HTTP servers in various situations. This article describes these situations and the request formats used.

== Log Messages ==
[[Reference7:Configuration/General/Logging|Configuration/General/Logging]]

=== GET ===
When '''Method External(GET)''' is selected, the HTTP server will receive a GET request with the following form data parameters (a.k.a. ''query args''):
{|
| Parameter || Example || Description
|-
| event || syslog || The '''event''' parameter will always have the value '''syslog'''. This allows the receiving script to distinguish it from CDR data.
|-
| time || 1214319593 || The time the log messages was created. Coded as number of seconds since January 1st, 1970. If '''time''' is 0, the internal clock has not (yet) been set.
|-
| date || 20080624-145953 || The same value as '''time''', except that is is coded in a human readable format.
|-
| msg || LOG_HTTP 3 TCP-Up 172.16.10.14:7793 172.16.0.17:471 || The message itself
|}

If the receiving HTTP server is running a scripting engine such as PHP, the individual fields will be received as request query parameters. In PHP they can be accessed via '''$_GET''':

_GET: Array
(
[event] => syslog
[time] => 0
[date] => 19700101-000000
[from] => IP24-1d-00-8d
[msg] => LDIR_SOCK 4 TCP-Out 0.0.0.0:0 0.0.0.0:389
)

=== POST ===
When '''Method External(POST)''' is selected, the HTTP server will receive a POST request. The request body (i.e. the ''post data'') is ''not'' coded as a form-data. Instead, the arguments are put into the request body exactly as the query string when using GET (e.g. <code>?event=syslog&...</code>).

== CDRs ==

== Alarms/Events ==

Reference7:HTTP Request Message Format

2025-06-17T13:55:09Z

Ckl: /* POST */

innovaphone devices will send data to external HTTP servers in various situations. This article describes these situations and the request formats used.

== Log Messages ==
[[Reference7:Configuration/General/Logging|Configuration/General/Logging]]

=== GET ===
When '''Method External(GET)''' is selected, the HTTP server will receive a GET request with the following form data parameters (a.k.a. ''query args''):
{|
| Parameter || Example || Description
|-
| event || syslog || The '''event''' parameter will always have the value '''syslog'''. This allows the receiving script to distinguish it from CDR data.
|-
| time || 1214319593 || The time the log messages was created. Coded as number of seconds since January 1st, 1970. If '''time''' is 0, the internal clock has not (yet) been set.
|-
| date || 20080624-145953 || The same value as '''time''', except that is is coded in a human readable format.
|-
| msg || LOG_HTTP 3 TCP-Up 172.16.10.14:7793 172.16.0.17:471 || The message itself
|}

If the receiving HTTP server is running a scripting engine such as PHP, the individual fields will be received as request query parameters. In PHP they can be accessed via '''$_GET''':

_GET: Array
(
[event] => syslog
[time] => 0
[date] => 19700101-000000
[from] => IP24-1d-00-8d
[msg] => LDIR_SOCK 4 TCP-Out 0.0.0.0:0 0.0.0.0:389
)

=== POST ===
When '''Method External(POST)''' is selected, the HTTP server will receive a POST request. The request body (i.e. the ''post data'') is ''not'' coded as a form-data. Instead, the arguments are put into the request body exactly as the query string when using GET (e.g. <nowiki><code>?event=syslog&...</code></nowiki>).

== CDRs ==

== Alarms/Events ==

Courseware:IT Advanced - Agenda

2025-05-05T19:20:22Z

Ckl:

{{#moodlebook: Master Templates / V15 Templates / Advanced | Agenda | 151}}

Courseware:IT Advanced - 11 How to setup the Application Platform after a factory reset

2025-04-30T09:18:00Z

Ckl: Protected "Courseware:IT Advanced - 11 How to setup the Application Platform after a factory reset" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V15 Templates / Advanced | How to setup the Application Platform after a factory reset | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 11 How to setup the Application Platform after a factory reset

2025-04-30T09:17:51Z

Ckl: Created page with "{{#moodlebook: Master Templates / V15 Templates / Advanced | How to setup the Application Platform after a factory reset | 151 }} {{PAGENAME}}"

{{#moodlebook: Master Templates / V15 Templates / Advanced | How to setup the Application Platform after a factory reset | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 10 Password relations

2025-04-30T08:48:14Z

Ckl: Protected "Courseware:IT Advanced - 10 Password relations" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V15 Templates / Advanced | Password relations | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 10 Password relations

2025-04-30T08:47:52Z

Ckl: Created page with "{{#moodlebook: Master Templates / V15 Templates / Advanced | Password relations | 151 }} {{PAGENAME}}"

{{#moodlebook: Master Templates / V15 Templates / Advanced | Password relations | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 09 Custom certificates

2025-04-30T08:22:56Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | Custom certificates | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 08 Using a custom DNS on your mobile phone

2025-04-30T08:22:03Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | Using a custom DNS on your mobile phone | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 07 Public access to PBX resources (practice)

2025-04-30T08:21:30Z

Ckl:

{{#moodlebook: Master Templates / V15 Templates / Advanced | Public access to PBX resources (practice)| 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 06 Public Access to PBX Resources (theory) - optional

2025-04-30T08:20:36Z

Ckl:

{{#moodlebook: Master Templates / V15 Templates / Advanced | Public Access to PBX Resources (theory) - optional | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 05 Setting up the Apps

2025-04-30T08:20:03Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | Setting up the Apps | 151 }}

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

Courseware:IT Advanced - 04 Setting up the Application Platform

2025-04-30T08:19:26Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | Setting up the Application Platform | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 03 The Application Platform

2025-04-30T08:18:18Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | The Application Platform | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 01 innovaphone overall Product Design

2025-04-30T08:17:11Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | innovaphone overall Product Design | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Courseware:IT Advanced - 02 PBX - initial Configuration

2025-04-30T08:16:25Z

Ckl: updated to 15r1

{{#moodlebook: Master Templates / V15 Templates / Advanced | PBX - initial Configuration | 151 }}
[[Category:IT_Advanced|{{PAGENAME}}]]

Reference13r3:IP4/NAT/General

2025-04-29T07:58:42Z

Ckl:

__NOTOC__
If the device is used as a router, it is able to connect IP terminals from the network with a non-public address to the public Internet. For this, '''NAT''' (Network Address Translation) is necessary. Additional configuration is required on the different IP interfaces (e.g. ETH, PPP, etc.) to define on which interfaces the public and on which interfaces the private network is accessed.

;Enable NAT: If this checkmark is set, NAT is enabled. Without this checkmark being set all other NAT settings are without effect.

;Default forward destination: If all incoming data packets from the public network are to be forwarded to a particular private IP address, the destination IP address must be entered here.

;Disable DNS Forwarding: No DNS requests are answered by this host, if this option is enabled.

===Add new map===
;Port-specific forwarding: To be able to address several internal destinations, different port numbers are assigned to IP addresses of the internal network here.

===STUN/TURN server===
;Enable STUN: If this checkmark is set, a STUN server is started on the box. The STUN server works like a regular STUN server from external. From internal binding requests create a NAT mapping and the binding response contains the public address of the mapping.

;Non standard port: The port that shall be used for the STUN server. If empty the well known port 3478 is used.

;STUN Changed Address: If the ''Enable STUN'' checkmark is ticked, an IP address:port must be configured, which will be used as source address for replies, when the client is asking for a ''changed address''. This is used for the classic STUN NAT detection mechanism. Basically any address/port can be used here. It could be that a IP provider does not forward packets with a wrong address, so it is safer to use an address, which is valid in the network of the device. It is also better to use an address, which is not used for something else, because it could be that the local router uses these packets to update its ARP table. You can use 3480 as port. Note that NAT detection will not work properly if no ''STUN Changed Address'' is configured

;TURN: Up to four TURN accounts can be configured. If a TURN account is configured a TURN server is enabled for this account.

;TURN Public Address: A TURN server can be operated in a private network behind a firewall. In this case port forwarding must be configured on the firewall for the complete RTP port range to the TURN server. On the TURN server the used public address of the firewall has to be configured, so that this can be provided to the remote RTP peer to send the RTP data to.

;Cluster: TURN servers can be operated in a cluster behind a single firewall. Each TURN server within the cluster should be assigned a separate RTP port range. On the firewall port forwarding to the different TURN servers has to be forwarded for the RTP port ranges. To distribute the incoming requests standard TCP or UDP load balancing to the different TURN servers has to be configured.
:If in this setup the other RTP peer use the same TURN cluster, the RTP is forwarded between the two session using the public firewall address, this requires the firewall to support hairpinning. To avoid this, on each TURN server all the TURN servers of the cluster can be configured, with their RTP port ranges (first, last) and their local (internal) addresses. If the RTP peer is identified as belonging to the same cluster, the local address is then used for the RTP.

== Known Issues ==

Note: In v12r1 and higher version it's no longer necessary to enable NAT for the STUN/TURN services be enabled. If NAT is disabled make sure the UDP-NAT port range values are also deleted / not set.

==Related Articles==

* [[Howto:How to configure NAT in V6]]
* [[Howto:Avoid DNS Amplification Attacks]]

Reference15r1:Services/Reverse-Proxy

2025-04-17T07:00:01Z

Ckl: /* SMTP */

[[Category:Concept|Reverse Proxy]]
[[Category:Concept Reverse Proxy]]
The reverse proxy is used to forward H.323, SIP, LDAP, HTTP and SMTP requests it receives to other hosts, based on system information like gatekeeper name host name, path or domain.
This way it can be controlled which services may be accessed thru the reverse proxy.
A reverse proxy may be located at the boundary of an private and a public network, or inside the private network, if the respective ports are forwarded to it by the NAT Router/Firewall.
It can be even configured on the same device as the PBX itself. In this case the other services on the device should use non-standard ports, so that the reverse proxy can receive the requests on the standard port and forward them locally to the non-standard ports.

== General Parameters ==

;No IPv4: Turn off IPv4 for the reverse proxy function
;No IPv6: Turn off IPv6 for the reverse proxy function
;H.323/TCP, H.323/TLS: Ports for incoming H.323 TCP or TLS Connections. Use 1720 and 1300 for the standard ports.
;SIP/TCP, SIP/TLS: Ports for incoming SIP TCP or TLS Connections. Use 5060 and 5061 for the standard ports.
;LDAP, LDAPs: Ports for incoming LDAP TCP or TLS Connections. Use 389 and 636 for the Standard ports.
;HTTP, HTTPS: Ports for incoming HTTP TCP or TLS Connections. Use 80 and 443 for the Standard ports.
;SMTP, SMTPS: Ports for incoming SMTP TCP or TLS Connections. Use 25 and 587 for the Standard ports.
;Log Forwarded Requests: activate protocol dependent logging for successfully forwarded / accepted requests
;Log Rejected Requests: activate protocol dependent logging for rejected / non-accepted requests
;Blacklist Expiration: Time in minutes after which an entry put in the blacklist automatically, will be removed from the blacklist.
;Suspicious Requests/min: Threshold to put an address into the blacklist
;Public NAT router address: Required for SIP if RP is behind NAT. External SIP clients will receive this value in Route header of SIP messages. You can configure DNS name or IP address and port here. If not configured, RP writes it's own local IP address and port into Route header of SIP messages. This works only if RP has a public local IP address.

== Hosts ==

List of configured hosts. Click on the host Name to edit or delete. Use new to add new host

;Out
:Destination IP-Address (IPv4 or IPv6) for this rule, following by the plain text port
:Destination DNS name: must start with '''@''' and is limited to 15 chars. For longer names, you can use a DNS suffix (see below).
;TLS
:Port for encrypted traffic
;Check Certificate
:If the Check Certificate checkmark is set, for the internal connection TLS is used only if the received certificate matches the user name within the protocol. This way a host receiving a request through the Reverse Proxy using TLS can assume that the connection was authenticated using a valid certificate, which matches the user.
;App Login
:Experimental feature to allow access only if a myPBX session has been previously authenticated. Not supported for myApps.
;Default
:This rule will be used if only the Domain without a path or file in the URI was requested. The empty path is then replaced by the specified URL when the request is forwarded (e.g. an entry ''<nowiki>http://</nowiki><host>/web/index.htm'' with the ''Default'' check-mark ticked will match requests with no path and the request is forwarded with the path set to ''/web/index.htm''). Note that also, an implicit rule is created that forwards all requests for files in and beneath the folder where the default document is in (in the example rule, requests to all files under ''<nowiki>http://</nowiki><host>/web'' will be forwarded)
;MTLS:
:Request MTLS on incoming connections. The requesting client has to provide the TLS Server Name on the incoming TLS connection. The Server Name is used to match to the host. If the checkmark is set, MTLS is requested then. If no Server Name is provided or no valid client certificate a connection for this host is rejected. The name od the received and validated certificate is forwarded as X-Remote-Cert HTTP header.
;Network
:''adddr:network'' to restrict a configured protocol to certain networks

=== SMTP ===
The host is searched for using different criteria based on the incoming socket.

The criteria are searched in the order given and the first match wins.

;TLS: the SNI of the TLS handshake
;EHLO: the client hostname send inside the client EHLO SMTP protocol message
;AUTH: the username of an AUTH PLAIN login. The whole username is matched and if no match is found, the domain part after an @ sign if present.
;RCPT-TO: the recipient mail address. The whole mail address is matched and if no match is found, the domain part.

==== STARTTLS ====

* If the EHLO message is already suitable to detect the host, STARTTLS is handled by the server behind the RP and port forwarding must be done to the non TLS port in this case.
* Otherwise the RP itself handles the STARTTLS handshake. It then doesn't matter if you internally forward to the non TLS port or the TLS port but STARTTLS won't be done anymore in any case.

== DNS Suffixes ==

If you want to forward requests to internal DNS names instead of IP addresses and such an internal DNS name is longer than 15 chars, you must use DNS suffixes to reference it. 

;Id: a unique id which is used as reference
;Suffix: a suffix which is used as replacement of #Id

If you want to use such a suffix inside '''Out''' of a host, you must write it like this:
'''@host1.#1''' -> this will be expanded to '''host1.example.com''', if the suffix with Id 1 has the value example.com

== Counter ==

Current top ten address with suspicious requests

== Addresses ==

Blacklist/Whitelist addresses

Reference14r1:Concept Let's Encrypt

2024-11-07T21:54:46Z

Ckl: /* Reverse-Proxy */

[[Category:Concept|Let%27s%20Encrypt]]

Certificates are automatically generated for innovaphone gateways and App Platforms.

== Applies to ==
* innovaphone gateways from version 14r1
* innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

== How it works ==

* Each configured innovaphone client requests a new certificate '''30''' days before it's current certificate expires.
* Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
* The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
* The Connector for Let's Encrypt App Service itself communitates via HTTPs and [https://en.wikipedia.org/wiki/JSON_Web_Token JWT] with Let's Encrypt to request a new certificate.
* Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
** the HTTP challenge always works '''without''' HTTPS on Port 80 on a subpath of '''/.well-known/acme-challenge/''', e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
* After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
* The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

=== Flow without Reverse Proxy ===

[[Image:letsencrypt-flow.png]]

=== Flow with Reverse Proxy ===
[[Image:letsencrypt-flow-rp.png]]

== Requirements ==
=== ACMEv2 compliant certification service ===

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used. 
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

=== Gateways and App Platform ===
* Firmware from version 14r1 or later
* innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
* innovaphone App Connector for Let's Encrypt version 14r1 or higher
* working DNS configuration

=== Reverse-Proxy ===

* Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
* On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path <code>/.well-known/acme-challenge/</code> to the Let's Encrypt App. Of course, an empty rule (such as the one that the reverse proxy PBX Manager plugin creates) will do.
* For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device.
:: For innovaphone devices, such rules are not necessary (except for the AP as outlined above).
* The App Platform must be able to communicate with the Let's Encrypt URLs.

'''Conclusion''': the recommended steps for obtaining certificates are as follows:
* configure the rule that forwards the challenge for your AP DNS name to the AP (''your-ap.example.com''<code>/.well-known/acme-challenge/</code>)
* configure the Connector for Let's Encrypt App on your AP
* configure the Let's Encrypt client on your AP
* configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (''your-3rd-party-device.example.com''<code>/.well-known/acme-challenge/</code>). This step is optional

==Security Consideration==
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

== Limitations ==
* You can configure up to '''100''' DNS entries for a single device. More DNS entries are not supported by Let's Encrypt. 
* You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

== Configuration ==

=== Connector for Let's Encrypt PBX Manager Plugin ===
Configure the [[Reference14r1:Concept_App_Service_Let%27s_Encrypt#Let.27s_Encypt_Config | PBX Manager Plugin]] of the Connector for Let's Encrypt App Service.

=== innovaphone Gateways ===
Configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] on every gateway which shall get a Let's Encrypt certificate.

=== innovaphone App Platform ===
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

=== RP ===
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] here too. 
You must configure all DNS names which are used by the individual devices behind the RP. 
 
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

=== Devices certificate configuration ===
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices. 
You can find this URL in the [[Reference14r1:Apps/PbxManager/App_Connector_for_Let's_Encrypt | PBX Manager Plugin]].

== Tracing and logging ==
=== Gateways ===
The following trace flags can be activated at [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing | Maintenance/Diagnostics/Tracing]].

;Let's Encrypt
: communication between gateway and the Connector for Let's Encrypt App Service
: processing of incoming id_tokens

;HTTP Client
: the HTTPS communication with the Connector for Let's Encrypt App Service

=== App Platform ===

Enable these trace flags for diagnostics:

==== App Platform Manager ====
;App
: requests of new certificates
;AppWebsocket
: communication with the Connector for Let's Encrypt App Service
;Websocket Client
: communication with the Connector for Let's Encrypt App Service

==== Connector for Let's Encrypt App Service ====
;App
: app logs
;HttpClient
: communication with Let's Encrypt itself
;AppWebsocket
: communication with the clients

== Alarms and Events ==
* an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
* an alarm is generated on the corresponding device as long as the certificate creation fails

==Troubleshooting==

=== Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt ===
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore. 
 
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt '''Let's Encrypt App URL''' by using '''ws''' instead of '''wss'''. 
If all your systems have a valid TLS certificate again, don't forget to switch back to '''wss'''!

==Known Issue==
===Geoblocking can prevent confirmation===
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

==Related Articles==
* [[Reference14r1:Services/Letsencrypt]]
* [[Reference14r1:Concept_App_Service_Connector_for_Let%27s_Encrypt]]
* [[Reference14r1:Apps/PbxManager/App_Connector_for_Let%27s_Encrypt]]

Reference14r1:Concept Let's Encrypt

2024-11-06T14:39:21Z

Ckl: /* Reverse-Proxy */

[[Category:Concept|Let%27s%20Encrypt]]

Certificates are automatically generated for innovaphone gateways and App Platforms.

== Applies to ==
* innovaphone gateways from version 14r1
* innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

== How it works ==

* Each configured innovaphone client requests a new certificate '''30''' days before it's current certificate expires.
* Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
* The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
* The Connector for Let's Encrypt App Service itself communitates via HTTPs and [https://en.wikipedia.org/wiki/JSON_Web_Token JWT] with Let's Encrypt to request a new certificate.
* Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
** the HTTP challenge always works '''without''' HTTPS on Port 80 on a subpath of '''/.well-known/acme-challenge/''', e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
* After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
* The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

=== Flow without Reverse Proxy ===

[[Image:letsencrypt-flow.png]]

=== Flow with Reverse Proxy ===
[[Image:letsencrypt-flow-rp.png]]

== Requirements ==
=== ACMEv2 compliant certification service ===

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used. 
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

=== Gateways and App Platform ===
* Firmware from version 14r1 or later
* innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
* innovaphone App Connector for Let's Encrypt version 14r1 or higher
* working DNS configuration

=== Reverse-Proxy ===

* Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
* On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path <code>/.well-known/acme-challenge/</code> to the Let's Encrypt App.
* For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device.
:: For innovaphone devices, such rules are not necessary (except for the AP as outlined above).
* The App Platform must be able to communicate with the Let's Encrypt URLs.

'''Conclusion''': the recommended steps for obtaining certificates are as follows:
* configure the rule that forwards the challenge for your AP DNS name to the AP (''your-ap.example.com''<code>/.well-known/acme-challenge/</code>)
* configure the Connector for Let's Encrypt App on your AP
* configure the Let's Encrypt client on your AP
* configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (''your-3rd-party-device.example.com''<code>/.well-known/acme-challenge/</code>). This step is optional

==Security Consideration==
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

== Limitations ==
* You can configure up to '''100''' DNS entries for a single device. More DNS entries are not supported by Let's Encrypt. 
* You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

== Configuration ==

=== Connector for Let's Encrypt PBX Manager Plugin ===
Configure the [[Reference14r1:Concept_App_Service_Let%27s_Encrypt#Let.27s_Encypt_Config | PBX Manager Plugin]] of the Connector for Let's Encrypt App Service.

=== innovaphone Gateways ===
Configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] on every gateway which shall get a Let's Encrypt certificate.

=== innovaphone App Platform ===
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

=== RP ===
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] here too. 
You must configure all DNS names which are used by the individual devices behind the RP. 
 
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

=== Devices certificate configuration ===
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices. 
You can find this URL in the [[Reference14r1:Apps/PbxManager/App_Connector_for_Let's_Encrypt | PBX Manager Plugin]].

== Tracing and logging ==
=== Gateways ===
The following trace flags can be activated at [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing | Maintenance/Diagnostics/Tracing]].

;Let's Encrypt
: communication between gateway and the Connector for Let's Encrypt App Service
: processing of incoming id_tokens

;HTTP Client
: the HTTPS communication with the Connector for Let's Encrypt App Service

=== App Platform ===

Enable these trace flags for diagnostics:

==== App Platform Manager ====
;App
: requests of new certificates
;AppWebsocket
: communication with the Connector for Let's Encrypt App Service
;Websocket Client
: communication with the Connector for Let's Encrypt App Service

==== Connector for Let's Encrypt App Service ====
;App
: app logs
;HttpClient
: communication with Let's Encrypt itself
;AppWebsocket
: communication with the clients

== Alarms and Events ==
* an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
* an alarm is generated on the corresponding device as long as the certificate creation fails

==Troubleshooting==

=== Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt ===
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore. 
 
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt '''Let's Encrypt App URL''' by using '''ws''' instead of '''wss'''. 
If all your systems have a valid TLS certificate again, don't forget to switch back to '''wss'''!

==Known Issue==
===Geoblocking can prevent confirmation===
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

==Related Articles==
* [[Reference14r1:Services/Letsencrypt]]
* [[Reference14r1:Concept_App_Service_Connector_for_Let%27s_Encrypt]]
* [[Reference14r1:Apps/PbxManager/App_Connector_for_Let%27s_Encrypt]]

Reference14r1:Concept Let's Encrypt

2024-11-06T14:34:55Z

Ckl: /* Reverse-Proxy */

[[Category:Concept|Let%27s%20Encrypt]]

Certificates are automatically generated for innovaphone gateways and App Platforms.

== Applies to ==
* innovaphone gateways from version 14r1
* innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

== How it works ==

* Each configured innovaphone client requests a new certificate '''30''' days before it's current certificate expires.
* Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
* The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
* The Connector for Let's Encrypt App Service itself communitates via HTTPs and [https://en.wikipedia.org/wiki/JSON_Web_Token JWT] with Let's Encrypt to request a new certificate.
* Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
** the HTTP challenge always works '''without''' HTTPS on Port 80 on a subpath of '''/.well-known/acme-challenge/''', e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
* After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
* The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

=== Flow without Reverse Proxy ===

[[Image:letsencrypt-flow.png]]

=== Flow with Reverse Proxy ===
[[Image:letsencrypt-flow-rp.png]]

== Requirements ==
=== ACMEv2 compliant certification service ===

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used. 
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

=== Gateways and App Platform ===
* Firmware from version 14r1 or later
* innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
* innovaphone App Connector for Let's Encrypt version 14r1 or higher
* working DNS configuration

=== Reverse-Proxy ===

* Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
* On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path <code>/.well-known/acme-challenge/</code> to the Let's Encrypt App.
* For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device
: for innovaphone devices, such rules are not necessary (except for the AP as outlined above)
* The App Platform must be able to communicate with the Let's Encrypt URLs.

:: Conclusion: the recommended steps for obtaining certificates are as follows
::* configure the rule that forwards the challenge for your AP DNS name to the AP (''your-ap.example.com''<code>/.well-known/acme-challenge/</code>)
::* configure the Connector for Let's Encrypt App on your AP
::* configure the Let's Encrypt client on your AP
::* configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (''your-3rd-party-device.example.com''<code>/.well-known/acme-challenge/</code>). This step is optional

==Security Consideration==
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

== Limitations ==
* You can configure up to '''100''' DNS entries for a single device. More DNS entries are not supported by Let's Encrypt. 
* You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

== Configuration ==

=== Connector for Let's Encrypt PBX Manager Plugin ===
Configure the [[Reference14r1:Concept_App_Service_Let%27s_Encrypt#Let.27s_Encypt_Config | PBX Manager Plugin]] of the Connector for Let's Encrypt App Service.

=== innovaphone Gateways ===
Configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] on every gateway which shall get a Let's Encrypt certificate.

=== innovaphone App Platform ===
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

=== RP ===
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] here too. 
You must configure all DNS names which are used by the individual devices behind the RP. 
 
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

=== Devices certificate configuration ===
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices. 
You can find this URL in the [[Reference14r1:Apps/PbxManager/App_Connector_for_Let's_Encrypt | PBX Manager Plugin]].

== Tracing and logging ==
=== Gateways ===
The following trace flags can be activated at [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing | Maintenance/Diagnostics/Tracing]].

;Let's Encrypt
: communication between gateway and the Connector for Let's Encrypt App Service
: processing of incoming id_tokens

;HTTP Client
: the HTTPS communication with the Connector for Let's Encrypt App Service

=== App Platform ===

Enable these trace flags for diagnostics:

==== App Platform Manager ====
;App
: requests of new certificates
;AppWebsocket
: communication with the Connector for Let's Encrypt App Service
;Websocket Client
: communication with the Connector for Let's Encrypt App Service

==== Connector for Let's Encrypt App Service ====
;App
: app logs
;HttpClient
: communication with Let's Encrypt itself
;AppWebsocket
: communication with the clients

== Alarms and Events ==
* an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
* an alarm is generated on the corresponding device as long as the certificate creation fails

==Troubleshooting==

=== Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt ===
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore. 
 
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt '''Let's Encrypt App URL''' by using '''ws''' instead of '''wss'''. 
If all your systems have a valid TLS certificate again, don't forget to switch back to '''wss'''!

==Known Issue==
===Geoblocking can prevent confirmation===
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

==Related Articles==
* [[Reference14r1:Services/Letsencrypt]]
* [[Reference14r1:Concept_App_Service_Connector_for_Let%27s_Encrypt]]
* [[Reference14r1:Apps/PbxManager/App_Connector_for_Let%27s_Encrypt]]

Reference14r1:Concept Let's Encrypt

2024-11-06T14:30:50Z

Ckl: /* Reverse-Proxy */

[[Category:Concept|Let%27s%20Encrypt]]

Certificates are automatically generated for innovaphone gateways and App Platforms.

== Applies to ==
* innovaphone gateways from version 14r1
* innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

== How it works ==

* Each configured innovaphone client requests a new certificate '''30''' days before it's current certificate expires.
* Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
* The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
* The Connector for Let's Encrypt App Service itself communitates via HTTPs and [https://en.wikipedia.org/wiki/JSON_Web_Token JWT] with Let's Encrypt to request a new certificate.
* Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
** the HTTP challenge always works '''without''' HTTPS on Port 80 on a subpath of '''/.well-known/acme-challenge/''', e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
* After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
* The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

=== Flow without Reverse Proxy ===

[[Image:letsencrypt-flow.png]]

=== Flow with Reverse Proxy ===
[[Image:letsencrypt-flow-rp.png]]

== Requirements ==
=== ACMEv2 compliant certification service ===

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used. 
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

=== Gateways and App Platform ===
* Firmware from version 14r1 or later
* innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
* innovaphone App Connector for Let's Encrypt version 14r1 or higher
* working DNS configuration

=== Reverse-Proxy ===

* Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
* On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path <code>/.well-known/acme-challenge/</code> to the Let's Encrypt App.
* For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device
* The App Platform must be able to communicate with the Let's Encrypt URLs.

:: Conclusion: the recommended steps for obtaining certificates are as follows
::* configure the rule that forwards the challenge for your AP DNS name to the AP (''your-ap.example.com''<code>/.well-known/acme-challenge/</code>)
::* configure the Connector for Let's Encrypt App on your AP
::* configure the Let's Encrypt client on your AP
::* configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (''your-3rd-party-device.example.com''<code>/.well-known/acme-challenge/</code>). This step is optional

==Security Consideration==
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

== Limitations ==
* You can configure up to '''100''' DNS entries for a single device. More DNS entries are not supported by Let's Encrypt. 
* You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

== Configuration ==

=== Connector for Let's Encrypt PBX Manager Plugin ===
Configure the [[Reference14r1:Concept_App_Service_Let%27s_Encrypt#Let.27s_Encypt_Config | PBX Manager Plugin]] of the Connector for Let's Encrypt App Service.

=== innovaphone Gateways ===
Configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] on every gateway which shall get a Let's Encrypt certificate.

=== innovaphone App Platform ===
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

=== RP ===
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] here too. 
You must configure all DNS names which are used by the individual devices behind the RP. 
 
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

=== Devices certificate configuration ===
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices. 
You can find this URL in the [[Reference14r1:Apps/PbxManager/App_Connector_for_Let's_Encrypt | PBX Manager Plugin]].

== Tracing and logging ==
=== Gateways ===
The following trace flags can be activated at [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing | Maintenance/Diagnostics/Tracing]].

;Let's Encrypt
: communication between gateway and the Connector for Let's Encrypt App Service
: processing of incoming id_tokens

;HTTP Client
: the HTTPS communication with the Connector for Let's Encrypt App Service

=== App Platform ===

Enable these trace flags for diagnostics:

==== App Platform Manager ====
;App
: requests of new certificates
;AppWebsocket
: communication with the Connector for Let's Encrypt App Service
;Websocket Client
: communication with the Connector for Let's Encrypt App Service

==== Connector for Let's Encrypt App Service ====
;App
: app logs
;HttpClient
: communication with Let's Encrypt itself
;AppWebsocket
: communication with the clients

== Alarms and Events ==
* an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
* an alarm is generated on the corresponding device as long as the certificate creation fails

==Troubleshooting==

=== Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt ===
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore. 
 
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt '''Let's Encrypt App URL''' by using '''ws''' instead of '''wss'''. 
If all your systems have a valid TLS certificate again, don't forget to switch back to '''wss'''!

==Known Issue==
===Geoblocking can prevent confirmation===
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

==Related Articles==
* [[Reference14r1:Services/Letsencrypt]]
* [[Reference14r1:Concept_App_Service_Connector_for_Let%27s_Encrypt]]
* [[Reference14r1:Apps/PbxManager/App_Connector_for_Let%27s_Encrypt]]

Reference14r1:Concept Let's Encrypt

2024-11-06T14:29:56Z

Ckl: /* Reverse-Proxy */

[[Category:Concept|Let%27s%20Encrypt]]

Certificates are automatically generated for innovaphone gateways and App Platforms.

== Applies to ==
* innovaphone gateways from version 14r1
* innovaphone App Platform with version 14r1 apps (image version 110036 or higher)

== How it works ==

* Each configured innovaphone client requests a new certificate '''30''' days before it's current certificate expires.
* Therefor an app websocket connection is opened to the Connector for Let's Encrypt App Service.
* The client sends a certificate signing request to the Connector for Let's Encrypt App Service.
* The Connector for Let's Encrypt App Service itself communitates via HTTPs and [https://en.wikipedia.org/wiki/JSON_Web_Token JWT] with Let's Encrypt to request a new certificate.
* Let's Encrypt triggers an HTTP challenge for every DNS entry where the token for the DNS entry is verified. (The Token is saved in the Let's Encrypt App Service)
** the HTTP challenge always works '''without''' HTTPS on Port 80 on a subpath of '''/.well-known/acme-challenge/''', e.g. http://mydns.com/.well-known/acme-challenge/1290378712893z12983
* After successfull HTTP challenges for every DNS name, the new certificate is send back to the client.
* The certificate is installed X days before the old certificate expires, while X can be configured in the PBX Manager Plugin.

=== Flow without Reverse Proxy ===

[[Image:letsencrypt-flow.png]]

=== Flow with Reverse Proxy ===
[[Image:letsencrypt-flow-rp.png]]

== Requirements ==
=== ACMEv2 compliant certification service ===

Our Connector for Let's Encrypt App Service uses the ACMEv2 protocol. So in general every ACMEv2 compliant service could be used. 
Officially tested is Let's Encrypt itself with this URL: https://acme-v02.api.letsencrypt.org

=== Gateways and App Platform ===
* Firmware from version 14r1 or later
* innovaphone App Platform with App Platform Manager version 14r1 or higher and image version 110036 or higher
* innovaphone App Connector for Let's Encrypt version 14r1 or higher
* working DNS configuration

=== Reverse-Proxy ===

* Let's encrypt will send the certificate challenge using HTTP on port 80. On your WAN interface (that is, the interface your DNS name points to), port 80 must be available therefore. Traffic must be forwarded to either the device itself or to a reverse proxy that forwards the certificate challenge to the device.
* On the reverse proxy there must be a rule for the host that corresponds to the DNS name of your AP where the Let's Encrypt App runs on that forwards HTTP path <code>/.well-known/acme-challenge/</code> to the Let's Encrypt App.
* For 3rd-party devices behind the Reverse-Proxy which intend to obtain a certificate from Let's Encrypt (using their own client mechanism), a similar rule must be present that forwards the challenge to the 3rd-party device
* The App Platform must be able to communicate with the Let's Encrypt URLs.

:: Conclusion: the recommended steps for obtaining certificates are as follows
::* configure the rule that forwards the challenge for your AP DNS name to the AP (''your-ap.example.com''/<code>/.well-known/acme-challenge/</code>)
::* configure the Connector for Let's Encrypt App on your AP
::* configure the Let's Encrypt client on your AP
::* configure rules for all 3rd party devices behind the RP that forward the challenge for the respective 3rd-party device's DNS names to the these devices (''your-3rd-party-device.example.com''/<code>/.well-known/acme-challenge/</code>). This step is optional

==Security Consideration==
We do not recommend that a device can be reached directly from the Internet on port 80. Please use the reverse proxy variant described above.

== Limitations ==
* You can configure up to '''100''' DNS entries for a single device. More DNS entries are not supported by Let's Encrypt. 
* You cannot configure DNS entries with wildcards. Such wildcard entries require the so called DNS challenge mechanism which is not supported by our Connector for Let's Encrypt App Service.

== Configuration ==

=== Connector for Let's Encrypt PBX Manager Plugin ===
Configure the [[Reference14r1:Concept_App_Service_Let%27s_Encrypt#Let.27s_Encypt_Config | PBX Manager Plugin]] of the Connector for Let's Encrypt App Service.

=== innovaphone Gateways ===
Configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] on every gateway which shall get a Let's Encrypt certificate.

=== innovaphone App Platform ===
Configure Let's Encrypt in the settings of the App Platform Manager on every App Platform which shall get a Let's Encrypt certificate.

=== RP ===
If your gateways and/or App Platforms are behind an innovaphone reverse proxy, you must configure the [[Reference14r1:Services/Letsencrypt | Let's Encrypt service]] here too. 
You must configure all DNS names which are used by the individual devices behind the RP. 
 
The RP will request a certificate with multiple SAN entries while every individual device will request an own certificate with a single SAN entry (or still multiple if a single device shall have multiple DNS entries).

=== Devices certificate configuration ===
If you want to rollout the Let's Encrypt root certificates to your devices, configure the URL for Let's Encrypt root certificates in a certificates configuration (App Devices -> Domains -> your domain -> Device Configurations) which will then ensure that always the latest root certificates are available in the trust list of your devices. 
You can find this URL in the [[Reference14r1:Apps/PbxManager/App_Connector_for_Let's_Encrypt | PBX Manager Plugin]].

== Tracing and logging ==
=== Gateways ===
The following trace flags can be activated at [[{{NAMESPACE}}:Maintenance/Diagnostics/Tracing | Maintenance/Diagnostics/Tracing]].

;Let's Encrypt
: communication between gateway and the Connector for Let's Encrypt App Service
: processing of incoming id_tokens

;HTTP Client
: the HTTPS communication with the Connector for Let's Encrypt App Service

=== App Platform ===

Enable these trace flags for diagnostics:

==== App Platform Manager ====
;App
: requests of new certificates
;AppWebsocket
: communication with the Connector for Let's Encrypt App Service
;Websocket Client
: communication with the Connector for Let's Encrypt App Service

==== Connector for Let's Encrypt App Service ====
;App
: app logs
;HttpClient
: communication with Let's Encrypt itself
;AppWebsocket
: communication with the clients

== Alarms and Events ==
* an event is generated for every failed certificate creation by the Connector for Let's Encrypt App Service
* an alarm is generated on the corresponding device as long as the certificate creation fails

==Troubleshooting==

=== Not working TLS connection between a reverse proxy/gateway and the app platform with the Connector for Let's Encrypt ===
If a gateway/reverse proxy cannot establish a TLS connection to the app platform where the Connector for Let's Encrypt is running, no new certificate can be created anymore. 
 
As a workaround, you can temporarily switch to a non TLS connection under Services -> Let's Encrypt '''Let's Encrypt App URL''' by using '''ws''' instead of '''wss'''. 
If all your systems have a valid TLS certificate again, don't forget to switch back to '''wss'''!

==Known Issue==
===Geoblocking can prevent confirmation===
To verify the correctness of DNS entries and HTTP Challenge, Let's Encrypt sends DNS/HTTP requests from multiple locations around the world. All of these requests must be successfully answered. If a request is not answered due to geoblocking, Let's Encrypt does not trust the issuer.

==Related Articles==
* [[Reference14r1:Services/Letsencrypt]]
* [[Reference14r1:Concept_App_Service_Connector_for_Let%27s_Encrypt]]
* [[Reference14r1:Apps/PbxManager/App_Connector_for_Let%27s_Encrypt]]

Reference14r1:Settings/Phone settings/Device settings

2024-11-06T10:31:21Z

Ckl: /* Configuration entries for automated deployment */

;Headset
:Enable/Disable headset support
;LCD light
:Set current display brightness. 0 (off) - 15 (max). Default 8.
;LCD light (idle state)
:Display brightness applied 30s after last action. 0 (off) - 15 (max). Default 2.
:To prevent display dimming, set ''LCD light'' and ''LCD light (idle state)'' to same level
;Energy saving
:Time frame in which the display is switched off instead of being dimmed if in idle state. Format <starthours>-<endhours> in 24h-notation with leading zeros. E.g. 17-09 turns off display between 17 o'clock (5pm) until 9 o'clock (9am). Default is 22-06.
:To prevent switching off the display, set ''Energy saving'' to ''00-00''.

===Configuration entries for automated deployment===
;LCD light
;
vars create PHONE/LCD-BACKLIGHT p 8
;LCD light (idle state):
vars create PHONE/LCD-IDLE-BACKLIGHT p 2
;Energy saving:
vars create PHONE/ENERGY-SAVING-TIME p 22-06

'''Example to be used in Devices configuration/Expert configuration'''

Use the [[{{NAMESPACE}}:Concept_Update_Server#Check_command | check command ]] as in the example below to prevent re-execution every 30 seconds

# Use check command to prevent boot loops (after vars create a reset is needed)
mod cmd UP1 check iresetn Energy-Saving

vars create PHONE/LCD-BACKLIGHT p 8
vars create PHONE/LCD-IDLE-BACKLIGHT p 2
vars create PHONE/ENERGY-SAVING-TIME p 22-07

Reference14r1:Settings/Phone settings/Device settings

2024-11-06T10:25:09Z

Ckl:

;Headset
:Enable/Disable headset support
;LCD light
:Set current display brightness. 0 (off) - 15 (max). Default 8.
;LCD light (idle state)
:Display brightness applied 30s after last action. 0 (off) - 15 (max). Default 2.
:To prevent display dimming, set ''LCD light'' and ''LCD light (idle state)'' to same level
;Energy saving
:Time frame in which the display is switched off instead of being dimmed if in idle state. Format <starthours>-<endhours> in 24h-notation with leading zeros. E.g. 17-09 turns off display between 17 o'clock (5pm) until 9 o'clock (9am). Default is 22-06.
:To prevent switching off the display, set ''Energy saving'' to ''00-00''.

===Configuration entries for automated deployment===
;LCD light
;
vars create PHONE/LCD-BACKLIGHT p 8
;LCD light (idle state):
vars create PHONE/LCD-IDLE-BACKLIGHT p 2
;Energy saving:
vars create PHONE/ENERGY-SAVING-TIME p 22-06

'''Example to be used in Devices configuration/Expert configuration'''

Use the check command as in the example below to prevent re-execution every 30 seconds

# Use check command to prevent boot loops (after vars create a reset is needed)
mod cmd UP1 check iresetn Energy-Saving

vars create PHONE/LCD-BACKLIGHT p 8
vars create PHONE/LCD-IDLE-BACKLIGHT p 2
vars create PHONE/ENERGY-SAVING-TIME p 22-07

Howto:PHP based Update Server V2

2024-11-06T10:17:24Z

Ckl: /* Using vars create */

==Applies To==
This information applies to

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

All Versions prior to 13r1 (for 13r1 and later, see [[Reference13r1:Concept App Service Devices]] instead).

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!

PHP 8 is supported from build 2023.

=== 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 [https://github.com/innovaphone/php-update-server here]
* copy all files and directories in to this new directory
** create your local config files. We will never overwrite these in further updates.
***Rename <code>config/user-config-sample.xml</code> to <code>config/user-config.xml</code>
***Rename <code>scripts/all-all-all-sample.txt</code> to <code>scripts/all-all-all.txt</code>
* 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

===Update existing installation===

* download the [https://github.com/innovaphone/php-update-server new sources]
* copy all files and directories to your existing installation folder (overwrite existing files)
* change owner and group of all files and directories to www-data, change mode to 0600 for all files and 0700 for all directories

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

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

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

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'':

<syntaxhighlight lang="html5">
<master ... user="myadmin" password="mysecret"/>
</syntaxhighlight>
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

<syntaxhighlight lang="html5">
<?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>
</syntaxhighlight>
(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 the 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:

<syntaxhighlight lang="html5">
<?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>
</syntaxhighlight>

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:

<syntaxhighlight lang="html5">
...
<backup
dir="backup"
/>
</syntaxhighlight>

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

<syntaxhighlight lang="html5">
<times
allow="22,23,0,1,2,3,4"
initial="1"/>
</syntaxhighlight>

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

<syntaxhighlight lang="html5">
...
<customcerts
dir="certs"
/>
...
</syntaxhighlight>

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:

<syntaxhighlight lang="html5">
...
<queries>
<query id="admin">
<applies>*</applies>
</query>
<query id="certificates">
<applies>*</applies>
</query>
</queries>
...
</syntaxhighlight>

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:

<syntaxhighlight lang="html5">
...
<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>
...
</syntaxhighlight>

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:

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

: 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>.
<syntaxhighlight lang="html5">
<times
...
forcehttps="true"
httpsport="444"
forcetrust="true"
/>
</syntaxhighlight>
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:

<syntaxhighlight lang="html5">
...
<phases>
<phase id="staging" seq="100"/>
</phases>
...
</syntaxhighlight>

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.

<syntaxhighlight lang="html5">
<?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>
</syntaxhighlight>

=== 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 ''user-config.xml'' file to <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, you 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 and 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

<syntaxhighlight lang="html5">
<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"
/>
</syntaxhighlight>

==== 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
<syntaxhighlight lang="html5">
<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>
</syntaxhighlight>

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

<syntaxhighlight lang="html5">
<fwstorage url="fw/{build}/"/>
</syntaxhighlight>

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

<syntaxhighlight lang="html5">
<fwstorage url="http://webbuild.innovaphone.com/{build}/"/>
</syntaxhighlight>

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

[[User:Ckl|ckl]] 15:40, 21 February 2023 (CET) This service has been discontinued. You may consider using <code>https://store.innovaphone.com/release/download/{build}/</code> instead.

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

<syntaxhighlight lang="html5">
<backup
dir="backup"
nbackups="10"
scfg="update.php?mode=backup&hwid=#h&sn=#m"
/>
</syntaxhighlight>

==== 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
<syntaxhighlight lang="html5">
<status
dir="status"
expire="7776000"
missing="200"
refresh="10"
logkeep="90"
usehttpsdevlinks="true"
/>
</syntaxhighlight>

==== 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''). If you want to use initial staging of virgin devices ''forcestaging'' must be <code>true</code>.

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 is 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. If it is <code>true</code>, 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.
: Since build 2021 the standard value was changed to <code>true</code>.

<syntaxhighlight lang="html5">
<times
dir="scripts"
allow=""
initial=""
check="true"
polling="5"
interval="15"
grace="90"
forcehttps="true"
httpsport="444"
forcetrust="false"
httpsurlmod="!mtls/!!i"
forcestaging="true"
/>
</syntaxhighlight>

==== 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'' attribute.

By virtue of the ''seq'' attribute, you can insert phases in to the set of phases defined by default, which is
<syntaxhighlight lang="html5">
<phases>

<phase id="staging" seq="100"/>
<phase id="update" seq="200"/>
</phases>
</syntaxhighlight>
For example,
<syntaxhighlight lang="html5">
<phases>
<phase id="phase" seq="150"></phase>
</phases>
</syntaxhighlight>
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.
First the environment scripts itself, then all implied environments in the same order as the ''implies'' tags are listed in the config.

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.
<syntaxhighlight lang="html5">
<environments>
<environment id='hq'>
<implies>intranet</implies>
</environment>
<environment id='intranet'/>
<environment id='homeoffice'/>
</environments>
</syntaxhighlight>
The <code>implies</code> tag handles no recursion (therefore, in the above example, if ''intranet'' would have an implies, a device in environment ''hq'' would not inherit this implication. Instead, you must list it explicitly for the ''hq'' environment).

If multiple environments will be used they will be applied also in the same order as the ''environment'' tags are listed in the config.

;There are some special things to keep in mind when adding multiple environments in the ''env'' attribute and they use the ''implies'' tag in the config.
:- The first environment specified in the arg ''env'' will be processed as expected with all children.
:- Recursive ''implies'' from an environment added via ''implies'' is not performed. (No children's children)
:- Only the first environment which is specified in the ''env'' arg with implies is processed, all additional values in the arg ''env'' will be ignored.
:- If the environment in the arg ''env'' it is not the first value, then it must also use the ''implies'' config to implies itself. Otherwise only child are processed.

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

<syntaxhighlight lang="html5">
<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>
</syntaxhighlight>

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

<syntaxhighlight lang="html5">
<nobootdev>
<model>ipva</model>
<model>ipvadec</model>
<model>swphone</model>
<model>mypbxa</model>
<model>mypbxi</model>
</nobootdev>
</syntaxhighlight>

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

<syntaxhighlight lang="html5">
<nofirmdev>
<model>swphone</model>
<model>mypbxi</model>
</nofirmdev>
</syntaxhighlight>

==== 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 model 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
<syntaxhighlight lang="html5">
<filenames>
<model id="mypbxa" prot="mypbx.apk"/>
</filenames>
</syntaxhighlight>

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

<syntaxhighlight lang="html5">
<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" />
</syntaxhighlight>

==== 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 using a separate ''query'' tag.

; queries/@scfg : defines the 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

<syntaxhighlight lang="html5">.

<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>
</syntaxhighlight>

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

<syntaxhighlight lang="html5">

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

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 which 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 both)
<syntaxhighlight lang="html5">

<applies>phone</applies>
</syntaxhighlight>

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

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

== 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 change</code> matches the modules name in the <code>vars create</code> command. However, the variable name must 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)
; b : binary. The var value is binary. Its ''<value>'' is given as a bin2hex string
; 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

; l : log. Creates trace output whenever this VAR is modified

; n : no-reset. If the 'n' flag is given, setting the variable will not trigger the 'reset needed' condition. Whether or not setting a variable has an effect without a reset depends on the module using the variable. Unfortunately, there is no documentation on which variables this works for, and we do not intend to provide such documentation. In the end, you have to try it out.

Please note that, unless the 'n' flag is given, using <code>vars create</code> will ''always'' set the internal ''reset needed condition'' in the device (regardless which ''<value>'' is set, even when the current value is set again). 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/scripting.class-sample.php</code>.

<syntaxhighlight lang="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();
}
}
?>
</syntaxhighlight>

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):

<syntaxhighlight lang="html5">
<?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>
</syntaxhighlight>

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

== Hints for using custom SSL Certificates ==

Using your own SSL certificates can be useful depending on the scenario.

We have two methods to accomplish this:

=== Standard scenario as described in this wiki article ===
The idea is that each certificate request is checked manually, edited and the UpdateServer is provided with the new device certificate.

=== Special scenario with automated certificate renewal ===
The idea is that every new/unknown (untrusted) device connects to the staging server. Here the device is released by manual checking/authorization by getting its first certificate. All further extensions can happen automatically afterwards.

'''Important: All important settings concerning file permissions, access and co must be used from the above article and are only skipped in this part!'''

We will create two Update-Server instances with the following configuration.

# Staging Server (HTTPS/443)
#*Put the sources in <code>/var/www/innovaphone/update</code>
#*Use your specific SSL configuration ''<customcerts>'' as described [[#customcerts | above]].
#*Use the following settings in the configuration of ''<times>'':
#*:<code>force https = "true"</code>
#*:<code>httpsport = "444"</code>
#*:<code>force trust = "true"</code>
#*:<code>httpsurlmod = "!update/i!!"</code>
#*Activate the query ''certificates'' as described [[#Delivering_Custom_Certificates | above]]
#*Configure the firmware update via the master tag as described [[#Delivering_Firmware_and_Boot_Code| above]]
#* '''Important''': Do not submit any further customer specific device configurations in the staging Server
# Final MTLS / 444 update server
#*Put the sources in <code>/var/www/innovaphone/mts</code>
#*Use your specific SSL configuration ''<customcerts>'' as described [[#customcerts | above]] with <code>renew = "x"</code>
#*Use the following settings in the configuration of ''<times>'':
#*:<code>force https = "true"</code>
#*:<code>httpsport = "444"</code>
#*:<code>force trust = "true"</code>
#*:<code>httpsurlmod = "!mtls/i!!"</code>
#*Activate the query ''certificates'' as described [[#Delivering_Custom_Certificates | above]]
#*Configure the firmware update via the master tag as described [[#Delivering_Firmware_and_Boot_Code | above]]
#*Store all customer specific device configurations

The meaning of the two different instances is:
*The staging server <code>https://[ip]/update/admin/admin.php</code> will generate the provisioning URLs for new devices.
*All new/unknown (untrusted) devices are only in the staging server.
**Here you can check the devices and provide them a valid certificate after check/authorization.
*With a valid certificate, the UpdateURL is automatically changed to the MTLS instance.
*As soon as a device connects via MTLS we trust this device and we can use an automatic extension of the certificates.
** Waiting CSR requests are in the configured folder ''certs'' in the notation <code>"[mac]-request.p10.pem"</code>
** If you operate your own CA, feel free to automate the reissue of the certificates via a sheduled Cronjob
*** Help for Linux: [[Howto:Creating_custom_Certificates_using_a_OpenSSL_Certificate_Authority]]
*** Help for Windows: [[Howto:Creating_custom_Certificates_using_a_Windows_Certificate_Authority]]
** If a signed certificate with the format <code>"[mac]-signedrequest.cer"</code> is placed in the certs folder, the certificate is automatically updated on the device.

== 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_OpenSSL_Certificate_Authority]]
* [[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}}]]

Reference8:TAPI Service Provider

2024-11-04T17:23:54Z

Ckl: /* Related Articles */

The ''innovaphone PBX V8.0 based TAPI Service Provider'' (TSP) is an enhanced version of the [[ Reference7:Unified Win32 and x64 TAPI Service Provider | previous TSP version ]] that takes advantage of the [[ Reference8:SOAP API | new SOAP features ]] provided with version 8 PBX firmware. It implements - like the previous versions - TAPI Version 3.0 without MSP (Media Service Provider).

The [[Reference7:Unified Win32 and x64 TAPI Service Provider| previous TSP ]] still must be used for V7 PBX systems.

This article describes how to install and use it as well how to configure the PBX in order for the TSP to work properly.

==Applies To==
This information applies to
* innovaphone PBX V8.0 based TAPI Service Provider, Build 8001 and later
* innovaphone PBX V8 and later (that is, this Service Provider runs with PBX Firmware V8 and later)

==More Information==

=== Enhancements ===
; Support for V8 firmware [[Reference8:Administration/PBX/Objects#Devices | devices]] : Each user object device is represented as a TAPI line (all sharing an identical address, the objects extension a.k.a. ''Number'' property). This now allows to select individual registration devices when multiple devices are registered with the same PBX. Please note that in V8, [[ Reference8:Administration/PBX/Objects/Edit_Forks | mobility devices ]] are not shown and thus not represented by TAPI line device. This was introduced in V9 only.
; Support for presence based lines : These are TAPI lines shown which reflect the users presence state. Presence state ''open'' is mapped to a TAPI device status ''in service''. Presence activity ''on-the-phone'' is mapped to a virtual call in state ''connected''.
: '''NB''': V8 PBX Firmware did set presence activity ''on-the-phone'' for each user object having a call. Unfortunately, as this does create performance issues, this behaviour has been removed from V9 PBX Firmware. The ''presence line'' feature may be useless with V9 PBX when the application did rely on this particular V8 PBX behaviour.

===System Requirements===
The TSP will install on any Windows 32bit and x64 platform down to Windows XP/Server 2003. For older systems, you must use a deprecated [[Reference7:TAPI_Service_Provider | previous TSP version]]. For systems running PBX firmware version 6 or earlier, you must use the even older [[Reference:TAPI_Service_Provider | version 5 based TSP]]. Note that there is no x64 version of the version 5 TSP!

The TSP needs to maintain parallel connections to each individual PBX in the system. For larger systems (i.e. systems with a huge number of PBXs), this may create substantial load to the underlying windows machine. The number of parallel activities scheduled by the TSP is thus limited as a function of the available main memory and number of processors. In particular, a maximum of 20 activities per available processor is allowed (up to build 8088, the limit is 60/processor for later builds). If this limit is exceeded, the TSP will issue performance warnings of class WARNINGS in the TSP log file and system TAPI performance will be poor. Use a more capable machine then.

Microsoft Windows operating system version for desktop clients (as opposed to server systems) limit the number and performance of TCP/IP connections. This may lead to bad performance or occasional request failures. We generally recommend to use server operating systems for 3rd party TAPI installations thus.

No special PBX licenses are required to use the innovaphone TSP.

=== Download ===
The TSP will be available on the tab ''Software'' in the [https://store.innovaphone.com/ Store].

===Installation===
Windows cannot run a Win32 TSP on an x64 platform (although it can run Win32 applications on such platforms). This is why there are 2 versions of the setup, the x64 installer (<code>setup64-release.msi</code>) and the Win32 installer (<code>setup32-release.msi</code>.

The ''release'' setup packages provided will install the retail version. This is recommended for production purposes but provides no debug options whatsoever. To track down possible problems, support may instruct you to install the debug version.

The TSP may be installed on each machine where a desired TAPI based
application is to be run. If for example, Outlook is to be used, then
each client PC running Outlook may have the TSP installed. Although
this is typical for a 1st party configuration, all clients may have full
3rd party functionality, that is, they may control all existing lines.

As an alternative, the TSP can be installed on a single machine and a
3rd party TAPI server product (such as the IXI-Call Server available as
a separate product) may be used to provide the network clients with a
TAPI interface. Also, Microsoft’s Remote TAPI Server should work but is not being tested, so you use it on your own risk.

To install,
* select and download the <code>setup32-release.msi</code> install packages on 32bit platforms or the <code>setup64-release.msi</code> install package on 64bit platforms.
* double-click the install package to launch the installer
[[Image:Unified Win32 and x64 TAPI Service Provider - zipcontent.png]]
* accept the license agreement
* select the target folder
* complete the installer

When the installer has copied all files to the target machine, you need to add the TSP to the machine's TAPI system
* open the ''Telephone and Modem'' control panel
* Switch to the rightmost tab (''Extras'')
* Click on the ''Add...'' button
[[Image:Unified Win32 and x64 TAPI Service Provider - Control Panel Add.png]]
* Select the innovaphone TAPI provider driver
* Fill out the configuration dialogue
* Install the provider by clicking ''OK''

==== File Organization ====
Windows forces all TAPI service provider files to reside in Windows' ''System Folder''. This is the <code>system32</code> folder in your windows install directory (usually <code>C:\windows\system32</code>), even if you are running an x64 platform! The installer will thus copy these files (<code>tsp8.tsp</code> and <code>tsp8UI.dll</code>) in to this directory. All other files however will be copied to the <code>innovaphone AG\innovaphone® PBX V8 TAPI Service Provider</code> folder underneath your systems ''Program Files Folder''.

The subdirectories <code>Debug</code> and <code>Logs</code> are created. <code>Debug</code> contains the driver's debug version, <code>Logs</code> will receive the log files when a debug version is used.

On x64 platform systems, the Win32 version of the configuration DLL (<code>tsp8UI.dll</code>) will be installed to the windows ''Windows on Windows64 System Folder'' (<code>SysWOW64</code>).

====Upgrading to a newer Version====
When you attempt to upgrade the TSP from a previous version, the Windows
installer will first remove any previous installation. When the new
software is installed then, the TSP will be installed again into the
TAPI system.

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

====Upgrading from the old Win32-only Version====
If you upgrade from the older Win32-only versions of the TSP (soap-appl/tapi/7.00 or soap-appl/tapi/5.00), you must first remove the old TSP from ''telephone and modem'' control panel and uninstall the old product from the ''Software'' (or ''Programs and Functions'') control panel.

When you upgrade from the old V7 64-bit TSP (soap-appl/tapi/7.00-64), you should first update this older version to the latest build available.

This procedure ensures that during the upgrade your TAPI lines retain their internal identifiers and thus their meaning in your TAPI application's configuration.

==== Uninstalling the TSP ====
To uninstall the TSP proceed as follows
* Remove the TAPI driver from the TAPI system using ''Telephony and Modem Control Panel''
* close ''Telephony and Modem Control Panel''
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* remove the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

You will notice that Windows may fail to remove the driver files from the ''Windows System Directory''. To clean up remove <code>tsp8.tsp</code> and <code>tsp8UI.dll</code> from the <code>system32</code> folder as well as - on x64 systems - from the <code>SysWOW64</code> folder.

Also, if you did file tracing, any remaining debug files in the <code>Logs</code> folder are left over and need to be removed manually.

The TSP will create some entries in the windows registry which will not be removed on uninstall. It is recommended to leave these entries as is. Only if you are sure you will never install the TSP again on this system or you are sure you will never use it with the PBX installation you used so far, you may want to delete them from the registry.

==== Rolling out First Party TSPs to multiple PCs ====
Normally, when multiple users require CTI and hence TAPI functionality, the best way is to use a server based, multi-client 3rd party CTI application. This will share all functions among all client PCs. If this is not an option, e.g. because the TAPI application in use does not support it, you may want to consider using Microsoft's TAPI Server and remote TSP. See Microsoft's [http://technet.microsoft.com/en-us/library/cc786297%28v=ws.10%29.aspx Telephony service providers overview] and [http://technet.microsoft.com/en-us/library/cc770373.aspx Manage Telephony Servers] documents.

If you still want to use the native innovaphone TSP on a number of PCs (instead of once on a server), you can roll out the TSP using some of the [http://support.microsoft.com/kb/816102/EN-US software deployment schemes Microsoft Server provide]. In such a case, you will likely want to deploy identical configurations to all these PCs. While this theoretically can be done by distributing registry settings, there will be a problem with the PBX access credentials. These are stored in encrypted format in the registry and can only be decrypted on the PC on which they have been set. That is, deploying such registry settings to other PCs will result in a non-functional setup.

To work around this problem, you may store the credentials in clear text in the registry. To do so, you would put the ''Password'' in a REG_SZ value named <code>admin1-free</code> and the ''Account'' into a REG_SZ value named <code>admin2-free</code>. If such a value is found in the proper place in the registry, the values configured using the telephony control panel are ignored.

[[Image:TAPI Service Provider-tsp8-nocrypt.png]]

'''Keep in mind that having credentials in clear in the registry presents a security risk!'''

This feature is available in build 8079 and later.

=== Upgrade from Build 8164 or earlier ===
From build 8165, the TAPI configuration has been moved to a different registry location. This has been done because latest windows versions (namely, Windows 10) do not allow the TSP to access registry information in the location used so far (<code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>). To work around this issue, it is now stored in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>.

The TSP configuration dialogue however runs with user privileges (as opposed to the TSP which runs with limited service privileges). It can therefore read the old configuration information and copy it to the new location. From build 8165, the configuration dialogue will thus copy any old configuration information to the new location when it is opened. When you upgrade an existing installation and open the configuration dialogue, you will see no change. However, when the configuration is saved, it is then present in the new location.

'''To upgrade an installation from build 8164 or earlier (that is TAPI 'V8 TAPI Service Provider (32 and 64bit) - hotfix14'' available in the ''V8 applications hotfix20'' package or earlier), proceed as follows:'''
* stop the telephony service (e.g. <code>net stop tapisrv</code>)
* install the new TSP
* open the TSP configuration dialogue
* verify the configuration data
* save the configuration
* (re) start your TAPI application

If you fail to migrate the configuration as described, the TSP will start, but not work!

===Configuration===
The TSP configuration dialogue looks like this:

[[Image:Unified Win32 and x64 TAPI Service Provider - Config UI.png]]

* The ''VERIFY'' button will verify the configuration. Note that the ''Username'' drop down list will only be populated after a successful verify.
* The ''OK'' button will save the configuration.
* The ''CANCEL'' button will quit the configuration without saving any changes. If it is the initial configuration while you add the TSP via the telephone and modem control panel, the TSP will not be added

TAPI talks to the PBX using [[Reference7:SOAP_API | SOAP ]] which in turn uses HTTP for communication. Both secure (https) and non-secure (http) communication is supported. In any case, HTTP basic authentication is used.
To be able to connect to the PBX, the TSP needs to know proper credentials to use during HTTP authentication. These are referred to as ''PBX Account'' and ''PBX Password''. Also, a suitable ''TAPI User'' must be selected.

==== Controlling the Line Devices handled by TAPI ====

TAPI connects to your PBX as a PBX user referred to as ''TAPI User''. It will see all PBX objects that are members of groups in which the ''TAPI User'' is an active member. If the ''TAPI User'' is not an active member in any group, TAPI will see the ''TAPI User'' object only. This may be useful in a [http://en.wikipedia.org/wiki/Telephony_Application_Programming_Interface 1st party TAPI scenario]. PBX objects are represented as TAPI lines.

The PBX object you use as ''TAPI User'' needs to have at least ''Viewing only'' [[Reference:Administration/PBX/Objects/Edit Rights | PBX user rights]]. Its ''Long Name'' property is used as ''TAPI User Username'', its ''Name'' property as ''PBX Account'' and the password as ''PBX Password''. This is why the PBX object used as ''TAPI User'' must have a password configured.

===== 1st Party Configuration =====
In a 1st party scenario, the TSP will only work on a single PBX object. This will typically be a user's phone and thus the user itself will be used as the ''TAPI User''.

[[Image:Unified Win32 and x64 TAPI Service Provider - FirstParty.png ]]

In such a configuration the TSP is typically installed on the users PC and the CTI software is accessing TAPI directly (such as e.g. Microsoft Outlook does).

The TSP configuration dialogue will check for the number of lines seen. If it is only one, then it will issue a warning message:

[[Image:Unified Win32 and x64 TAPI Service Provider - OnlyOne.png]]

This is because 3rd party configurations are much more common and this situation often indicates a configuration problem. In a first party configuration, you can safely ignore this message.

===== 3rd Party Configuration =====
In a 3rd party configuration, the TSP will work with multiple PBX objects.

[[Image:Unified Win32 and x64 TAPI Service Provider - ThirdParty.png]]

Typically, you will share a single TSP instance on a server system for use by several users on their desktop PCs. This is done by virtue of a ''TAPI Server''. There are various TAPI server products available on the market, including but not limit to the Estos ProCall product and the remote TAPI server included in Microsoft Windows server operating systems.

In this scenario, it is recommended to create a pseudo PBX user object for use as the ''TAPI User''. This pseudo user is often called <code>_TAPI_</code>. You would create a dedicated group to control the list of PBX objects the TSP creates a line device for. This group is often called <code>tapi</code>.

==== Selective Call Forwards ====
Many CTI applications support distinct call forwards for internal and/or external calls. The TSP will translate such requests to a call forward on the PBX which has the [[Reference7:Administration/PBX/Objects/Edit_CFs | ''Only'' or ''Only not'' property]] set to the number of the trunk line. For this to work, it needs to know this number. To know the number, the trunk line PBX object must be seen by the TSP (see above). If this is not the case, the TSP configuration dialogue will issue a warning:

[[Image:Unified Win32 and x64 TAPI Service Provider - NoTrunk.png]]

In a vanilla first party scenario, this is obviously not the case. If you don't care, you can safely ignore this issue. Attempts to set such call forward will be rejected then as ''operation unavailable''.

In a Master/Slave PBX scenario where there is no Trunk Line object on the Master PBX, but only on the Slave PBXs, a workaround is required to suppress the warning and enable selective call forwarding on the Slave PBXs. In this case, create a dummy "Trunk Line" object on the Master PBX with the same extension number used by the "Trunk Line" objects on the Slave PBXs (usually 0).

==== Multi Site Configuration ====
In a system with multiple PBXs, the TSP needs to connect to each of the individual PBXs.

[[Image:Unified Win32 and x64 TAPI Service Provider - MultiSite.png]]

In this case, you would specify your master PBX as ''PBX Master''. There is no need to configure the complete PBX tree to the TSP as it is determined dynamically on runtime by analysing the PBX/Node objects in the master PBX and their registration status. If a registered PBX is found, this PBX is added to the list of active PBXs and a new connection is established. The PBX tree is built and maintained dynamically. A reconfiguration or restart of the TSP is not required on changes thus.
For this to work

* the PBX object used as ''TAPI User'' must exist in each PBX with same properties (including name and the password). You may want to use <code>_TAPI_</code> as ''Name''/''Long Name''. This object must be ''active'' member in a group (which you may want to call <code>tapi</code>). A password must be set. The object must have at least ''Viewing only'' rights
* the slave PBX-objects (or in older firmware versions the slave PBX Node-objects) must be visible to the TSP (that is, must be non-active member of the group the ''TAPI User'' object is an active member of, e.g. <code>tapi</code>) so that the slaves are made known to the TSP.

In a replicated scenario, you would create a ''TAPI user'' as recommended above and [[Reference8:Administration/PBX/Objects#Objects_with_empty_node_or_PBX | leave the ''PBX'' and ''Node'' properties empty ]]. This user should then be used as both ''PBX Account'' and ''TAPI User Username'' in the TAPI configuration dialog.

''Further relevant settings'':

You can disable slave detection by checking ''Do not monitor slaves'' property in the TSP configuration dialogue.

TAPI maintains an ''address'' property per line device. This usually is the lines extension. In a multi site configuration, the address property will be set to the ''Number'' property of the node the respective PBX object is configured in, plus the ''Number'' property of the object itself. So if an object has ''Number'' <code>42</code> and lives in node <code>801</code>, then its correspondence line device will have address <code>80142</code>. By checking the ''Use pure node extensions'' property in the TSP configuration dialogue, you change the algorithm so that only the objects own ''Number'' is used (<code>42</code> in our example).

==== Standby Configurations ====
In a system with standby PBX for the master PBX, you need to specify the ''PBX Standby'' IP address. This will be connected if the master is unavailable. Note that there is no need to explicitly configure slave-standby PBXs.

==== Working with multiple, unrelated PBXs ====
When working with multiple, unrelated PBXs (that is, PBXs that do ''not'' form a PBX tree as slaves and masters do), the TSP cannot derive the list of PBXs to track from the registration status. To support such a configuration, you will need to configure the extraneous master PBXs manually using regedit. Please note that using regedit may harm your system and may even cause inability to boot!

To find and edit the right registry entries, proceed as follows:

* open the key <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>
* open its subkey <code>Device</code>''n'' where ''n'' is the provider id of the installed innovaphone TSP (for builds before 8164 only)
* Open the <code>FQDN</code> key and add all extra PBXs
* For those PBXs that have a standby PBX, add a value to the <code>StandbyFQDN</code> key (please note: these are parallel lists. So master and standby need to have the same respective index in the <code>FQDN</code> and <code>StandbyFQDN</code> value lists)

The standard configuration UI will not show these extra values. However, it will also not touch them. So even if you use the standard UI to edit, only the first value in the lists will be changed and the remainder left unchanged. You can thus safely use the standard UI to edit all other values. As with multi site configurations, all PBXs need to be accessible using the same ''TAPI User''.

Please note that this method is deprecated and will likely be removed from future versions of the TSP.

==== Setting the Line Device Name ====
The TSP will derive the line device's name from the properties of the respective PBX object. By default the name will be the objects ''Long Name'' followed by the name of the PBX the user ought to register with in parentheses. So if the users ''Long Name'' is <code>Foo Bar</code> and the registration PBX is <code>branch1</code>, the line device will be called <code>Foo Bar [branch1]</code>. You can specify a different pattern by changing the ''TAPI Line Names'' property of the TSP configuration dialogue. The following replacement characters are available:

{|
|+
| Meta || Replacement
|+
| %c || The objects ''Long Name'' (cn)
|+
| %C || The objects ''Long Name'' (cn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Long Name''
|+
| %d || The objects ''Display Name'' (dn)
|+
| %D || The objects ''Display Name'' (dn) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Display Name''
|+
| %h || The objects ''Name'' (h323 alias)
|+
| %H || The objects ''Name'' (h323 alias) followed by the ''Name'' of the ''Device'' the line represents in braces <code>[name]</code> if it differs from the ''Name''
|+
| %t || The ''Name'' of the ''Device'' the line represents
|+
| %T || The ''Hardware Id'' of the ''Device'' the line represents (from build 8181)
|+
| %e || The objects extension (e164)
|+
| %E || The objects extension (e164) prefixed with the objects node number
|+
| %N || The line address as reported to TAPI
|+
| %n || host name (of master pbx)
|+
| %p || ''':'''''port-number'' (of master pbx's http access, empty if 80)
|+
| %P || raw port number of master pbx
|+
| %u || url-like user name ('''''user''@''host''''')
|+
| %U || user url as per draft-levin-iptel-h323-url-scheme-04 ('''h323:://''user''@''host'':''port''''')
|+
| %X || the PBX name the user is registered with (note that using this pattern may result in a change of the name when a standby situation occurs)
|+
| %x || the PBX name the user is reported by (note that using this pattern may result in a change of the name when the users ''PBX'' attribute changes)
|}

The default pattern is <code>%C (%x)</code>.



==== Miscellaneous Flags ====
; Show full E164 Numbers : when set, the TSP will announce the full calling number from the root when indicated by the PBX in the TAPI ''calling party name'' attribute. The number will be appended to the calling name with a <code>@</code>.
; Do not show parked Calls : will hide parked calls from the TAPI application (as some get confused and don't know how to handle them)
; Map PBX Devices to Lines : if set, the TSP will create one TAPI line for each individual [[Reference9:PBX/Objects#Devices|PBX device]] configured in a user object. See [[#Enhancements]] above. If you do not set this flag, see [[Support:How should TAPI line device be registered?]]
; Map Presence Status to TAPI Lines : if set, the TSP will create one extra TAPI line for each PBX device object. See [[#Enhancements]] above.
; No special Disconnect Behaviour : normally, lines monitored by TAPI will behave slightly different when a call is terminated. With no TAPI on the line, the call will be disconnected immediately (from a PBX point of view). In cases where the phone would play some tones after termination of the call (e.g. a busy tone when the call has never been connected to the far end), this state is simulated by the phone and not visible to TAPI. Therefore, it is not possible to use TAPI functions on this call any more (as it in reality does not exist any more). When this flag is set, monitored lines will not be treated specially. Available from hotfix 6. To prevent the IP-Phone to play any tones after the call is disconnected, the phone preferences option '''Go onhook if final call is released by remote side even if handset is lifted''' can be activated. This is the feature of the IP-Phone is useful in a e.g. call center at agent phones and can be configured here [[Reference11r1:Phone/Preferences]].
: To prevent an innovaphone IP-Phone from playing any tones after a call is disconnected, the phone preferences option '''Go onhook if final call is released by remote side even if handset is lifted''' can be activated. This feature is useful for agent phones in a call center for example and can be configured in [[Reference11r1:Phone/Preferences]]

===Trouble Shooting===
The TSP will (from build 8095) write messages of type INFO (''informational messages'') or WARNING (''Warnings/Errors'') to the windows event log. Such events are always logged to the application log and event source is the provider name (''innovaphone® PBX V8 TAPI Service Provider'').

==== Turning on Debugging ====
There are 2 versions of the TSP, debug and retail, which are both copied to the machine during setup. The retail version is installed into the system directories, whereas the debug version is stored in a separate directory. This is available through a short cut in the Start menu.

The TSP can produce a number of debugging messages which can be helpful to debug issues (in both ''retail'' and ''debug'' builds). By default, debug messages are written to the systems debug buffer mechanism (using OutputDebugString()). Such messages can be examined using standard debugging tools, such as for example <code>dbgview</code> which is [http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx available from Microsoft].

Debug messages have a class associated with it and the amount of messages written can be controlled by enabling or disabling specific classes. This is done by setting a bitmask in the registry value <code>TraceLevel</code> in the <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/> key.

The easiest way to set the TSP's debug level is with the ''TSP Control'' utility (''tsptray.exe'') which is installed with the TSP.

The available classes include

{|
| Bit in <code>TraceLevel</code> || Class
|-
| 0x00000001 || Minimum tracing
|-
| 0x00000002 || TAPI api traces
|-
| 0x00000020 || Basic telephony object creation/destruction
|-
| 0x00000040 || Thread creation/destruction
|-
| 0x00000080 || Request creation/destruction
|-
| 0x00000100 || call related messages
|-
| 0x00000200 || Call id map
|-
| 0x00000400 || Warnings/Errors
|-
| 0x00000800 || Worker thread execution
|-
| 0x00001000 || Full lock/unlock notifications
|-
| 0x00002000 || Win32 Critical section create/destroy
|-
| 0x00004000 || Agent proxy support
|-
| 0x00008000 || constructor/destructor debug
|-
| 0x00010000 || development debugs
|-
| 0x00100000 || verbose debugging
|-
| 0x00200000 || SOAP trace
|-
| 0x00400000 || SOAP message dumps
|-
| 0x01000000 || ATL debug
|-
| 0x02000000 || line related messages
|-
| 0x04000000 || informational messages
|-
| 0x10000000 || dump call infos
|-
| 0x20000000 || dump PBX infos
|-
| 0x80000000 || output log messages to file
|}

If <code>TraceLevel</code> is not set, it defaults to (hex) <code>04000400</code> in retail builds and to (hex) FFFFFFFF in debug builds. A nice value to use is (hex) <code>92200580</code>. The <code>TraceLevel</code> can be changed during runtime of the provider (it may take up to 10 seconds though for the setting to take effect). In normal scenarios there is no need to install the debug version.

Both ''informational messages'' and ''Warnings/Errors'' are always turned on (from build 8095).

: A problem has been reported on Server 2008 x64 systems which may also apply to others. On such systems, the value of <code>TraceLevel</code> may be reset to its default every 10 seconds. A workaround is to change the account the Telephony service is running in from its default (usually ''Network Service'') to e.g. ''Local System''.

===== Crash Dumps =====
From build 8063 the TSP will write crash dumps to the log directory (usually something like <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8 TSP\Logs</code>) in case of a trap. In release installs, these are not very useful. For debug builds though, they include helfpul information. Please provide these files (the can be zipped to a great extent) to support if requested. A crash dump file will be called something like <code>TSP8build-hour#minute-day.month#seqnr.dmp</code>.

===== Forcing a Crash Dump =====
In rare cases, it may be useful to force a TAPI crash for debug reasons. This can be done by issueing a <code>lineMakeCall</code> with called number <code>0815</code>, called-subaddress <code>4711</code> and called-name <code>!crash!</code> or simply calling <code>0815|4711^!crash!</code> from phone.exe.

==== Saving Log Messages to a File ====
The <code>0x80000000</code> value is special, as it does not denote a message class. Instead, it turns on log file writing, both in retail and debug versions. For this to work, the registry value <code>DoTraceFile</code> must be set to <code>1</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/> when the TSP starts. If this value is not present, it defaults to <code>1</code> in both retail and debug builds. Setting it to 0 disables log file writing regardless of any other setting. This may save some CPU cycles for installations with a real large number of lines.

The TSP will keep 24 log files (a days worth) by default. This value can be changed using the <code>NumLogFiles</code> value in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>. Older log files will be removed. Also, when the TSP shuts down, it by default will remove all log files it created so far. However, any TSP will only remove log files created by itself. This ensures that if the TSP or the system terminates prematurely, the log files will be kept even if a new instance is started and terminated later on. Form TSP V8 hotfix 8 on, this behaviour can be tweaked by setting the DWORD registry value <code>KeepLogFiles</code> in <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>:
{|
| 0 || default || remove all log files on termination
|-
| 1 || || keep the last ''n'' log files (depending on <code>NumLogFiles</code>) on termination
|-
| 2 || || keep all log files
|}

Larger systems (500 monitored lines and more) can slow down considerably when writing extensive logs.

==== Installing the Debug Version ====
To install the debug version, you first install the retail version as outlined above. You then copy the debug driver files from the <code>Debug</code> directory to your windows system directory <code>system32</code>. You may want to use the shortcut to the <code>Debug</code> folder which has been installed to the start menu for convenience.

For the copy to work, proceed as follows
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* copy the debug driver files to your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>.(if the copying fails, we recommend to deactivate the telephony service. But don’t forget to reset it to automatically if you are done copying). Overwrite the existing files: <code>installer.dll, installer.pdb, TSP8.pdb, TSP8.tsp</code>
* if the copy does not succeed or the debug driver is not shown n the modem control panel after, it might be that a TAPI application re-starts the windows telephony before you actually to the copy. If so, you can set the ''Startup type'' of the Windows ''Telephony'' service to <code>Disabled</code> instead of ''Manual'' in the services control panel (''services.msc''). You can then ''Stop'' the services, copy the file and finally set the services mode back to <code>Manual</code>

When you open ''Telephony and Modem Control Panel'' again, you should notice that the TSP driver name has changed to the debug version.

==== Switching back to the Retail Version ====
To go back from the debug to the release version, proceed as follows:
* close ''Telephony and Modem Control Panel'' if you have it open
* shut down windows telephony service. This can be done from the Windows ''Service Control Panel'' or by invoking <code>net stop tapisrv</code> from a command prompt
* delete the debug driver files from your system directory. On x64 systems, be sure to use a 64bit application such as ''Windows File Explorer for'' (<code>explorer.exe</code>) for this. Windows will silently redirect any 32bit application to the <code>SysWOW64</code> directory when accessing <code>system32</code>
* repair the installation using windows ''Programs Control Panel'' or by invoking the original .msi again

There is no need to remove the driver from the ''Telephone and Modem Control Panel'', as this would make you loose your driver configuration.

Please note that simply re-installing the driver from the original .msi without removing it from the system directory will not work.

===References===
The test applications provided with this setup comes from [http://www.julmar.com Julmar Technology Inc].

=== Limitations ===

Please note that there currently is a limitation to 2000 users being in
all active groups of a particular user. Thus, you cannot configure more
than 2000 users to be handled by TAPI on a single PBX. This is a PBX
limitation (and applies for all PBX groups).

TAPI has a flat line model. That is, all line numbers (aka
''extensions'') are considered to live in a single name space. As a
result, lines with identical numbers cannot be distinguished in TAPI
(although they can exist). All extensions in all nodes of a PBX
numbering tree are represented as TAPI lines. When the TSP works with a
PBX that implements a hierarchical numbering tree, then some lines may
receive identical numbers (their node-local extension which may overlap
between nodes depending on the setting of the ''Use pure node extensions'' property). When a TAPI application uses these numbers to initiate
calls to such lines, the call will work or not work depending on the
calling lines position in the numbering tree (that is, lines within the
same node as the called line will be fine, others may fail).

The PBX's SOAP interface (on top of which the TSP is built) has no primitives to initiate a directed call pick-up based on a target number. The TSP will reject such requests with ''Operation not available''. Pickup by name (which is understood as a group name) or unspecific is supported though.

==== Citrix Environments ====
What happens is that all Citrix sessions share the same TAPI driver. This allows all users in the Citrix sessions to select "their" line from the set of all TAPI lines. Then everything works as desired. It is important to note that theoretically one user can select the line of another user.
You can use the "Microsoft Remote TAPI Server", to implement access rights for lines for separate Citrix sessions.

===Known Problems===

* The TSP is not tested with Microsoft’s Remote Tapi Server. While some installation have reported this to work fine, others have encountered problems. This scenario is not supported by innovaphone
* The TSP will read its configuration when it is loaded by the system. Thus, configuration changes require a re-load of the TSP. Unfortunately, there is no reliable way to force the system to unload the TSP, so you may have to reboot the system for changes to take effect. See the [[ Howto:Troubleshooting_the_TAPI_service_provider | TAPI trouble shooting article ]] for details
* The TSP will use HTTP basic authentication to talk the PBX. So if you disable basic authentication in the PBX's configuration, the TSP will not work. It is recommended to use HTTPS
* TAPI requires the TSP to assign a unique id to each line device. This ID must not change between re-boots of the system or between upgrades of the TSP. This is done by keeping a persistent table in the windows registry (in the <code>lineGUIDs</code> subkey of <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>) that maps the PBX's line GUID to a fixed integer value (known as ''permanent line id'' in TAPI speak). This key is retained even on uninstall. To get rid of it, you must remove it manually
* Microsoft installer fails to remove driver files installed to the windows system folder. This is why the TSP driver files are still present after an uninstall of the software. To get rid of them, remove <code>TSP8.tsp</code> and <code>TSP8UI.dll</code> from both ''%windir%''<code>\system32</code> and ''%windir%''<code>\sysWOW64</code>
* From Version 9, hotfix 1, the PBX firmware will not list objects tagged as [[Reference9:PBX/Objects#General_Object_Properties | ''hide from LDAP'' ]] in the result of a [[Reference9:Concept_SOAP_API#UserInfo.5B.5D_FindUser.28string_v501.2C_string_v700.2C_string_v800.2C_string_cn.2C_string_h323.2C_string_e164.2C_integer_count.2C_integer_next.29 | FindUser() ]] call. As a result, such objects will not be shown in the TAPI configuration dialogue ''Username'' drop-down. If you want to use such an object as ''TAPI User'' you can simply type in the name without selecting it from the drop down.
* Sometimes, setting configuration with ''TSP Control'' (not the telephone control panel dialogue) does not work due to windows' ''User Access Control (UAC)'', see [[Howto:TAPI_TSP_Control_Windows7]] for Details
* Various users have reported that first party TSP installations do not work reliably with Microsoft Outlook. Symptoms reported are spurious error pop-ups from Outlook although there was no real problem. We do not recommend first party installations anyway (see [[#Rolling_out_First_Party_TSPs_to_multiple_PCs]] for a reasoning), but these issues are related to Microsoft Outlook only. No such problems have been reported with other first party TAPI applications. Consider using solutions like Estos ProCall instead.
* The number of parallel threads used within the TSP is limited to max. 60 per CPU. As each connected PBX (amongst other things) is handled by a separate thread, if you have a large number of PBXs connected and only have a single CPU, you may run out of threads, resulting in a WARNING messages ''about to spawn new workerthread (n requests, m threads) -- but limit l exceeded''. This usually happens when you run the TSP on a virtualized platform such as vmWare and only dedicate a single CPU. Ignoring this warning results in sluggish behaviour.
* The TSP can work with dynamic PBXs too. However, the TSP needs to determine the slave PBXs IP addresses from the master. If the slave is a dynamic PBX and it is hosted on the same device as the master and it is registered to the master using 127.0.0.1, the TSP will only learn the 127.0.0.1 as the slave's IP address. Of course, connection to the slave PBX will fail then.

==== TAPI Operation with 3rd party Phones or innovaphone Phones registered with SIP ====
Various TAPI functions rely on use of the [[Reference:Remote Control Facility|Remote Control Facility]] message. This message is not supported in 3rd party phones and also not fully supported in innovaphone Phones when they are registered to the PBX using SIP. Full TAPI functionality is thus only available for innovaphone phones registered to the PBX using H.323.

Known Limitations:
* Accepting an incoming call (lineAnswer)
* Automatic initiation of an outgoing call in handsfree mode (instead, the calling phone first rings and starts the outgoing call upon of-hook)
* toggle between 2 calls active on a phone (lineSwapHold)
* initiation and termination of a 3PTY (lineCompleteTransfer with mode LINETRANSFERMODE_CONFERENCE, lineDrop on a conference call)

==== TAPI on Windows8 / Server 2012 ====

Windows8 doesn't let you disable ''User Access Control'' (UAC) completely. This has the disadvantage that ''TSP Control'' (tsptray.exe) cannot change system registry entries, which it needs to do to e.g. change debug settings for the TSP.

There are 2 ways around it:
# use the hidden ''Administrator'' account on Windows 8
# elevate the tsptray.exe application

To use the elevated ''Administrator'' account on Windows 8 you first need to un-hide it:
* log in to an account with administrator rights
* use the ''Windows-Key+X'' shortcut and select ''Command Prompt (Administrator)'' (''Eingabeaufforderung (Administrator)''). An elevated cmd prompt appears
* type <code>net user administrator /active:yes</code>
* the fully elevated ''Administrator'' account is now available and you can log-in to this account as usual
* '''Please make sure the account has a password set - by default, it does not!!'''

To elevate the tsptray.exe application;
* log in to an account with administrator rights
* start a windows explorer
* change directory to <code>C:\Program Files\innovaphone AG\innovaphone® PBX V8-x64 TSP</code>
* right click on <code>tsptray.exe</code> and open the ''properties'' (''Eigenschaften'') menu
* switch to the ''Compatibility'' (''Kompatibilität'') tab
* tick the ''Run as administrator'' (''Program als Administrator ausführen'') check mark
* save the settings

Please note that Windows 8 will not let you run any "Metro App" in elevated mode!

===== HTTPS =====
The TSP will not be able to talk to the PBX using HTTPS with Windows8 or Server2012. This [[Reference8:Release_Notes_TAPI_V8#3722_-_HTTPS_SOAP_connections_did_not_work_on_Windows8_.2F_Server_2012|has been fixed]] with V8 TAPI Service Provider (32 and 64bit) - hotfix10.
===== .Net 3.5 missing on Server 2012 =====
Server 2012 has no support for .Net 3.5 by default. Even more, it cannot be installed just by downloading it. Instead, the ''NetFX3 Feature'' needs to be enabled. Here is how:

Microsoft Windows [Version 6.2.9200]
(c) 2012 Microsoft Corporation. Alle Rechte vorbehalten.

C:\Users\Administrator>dism /online /enable-feature /featurename:NetFX3 /all /Source:''<path to windows setup, e.g. d:>''\sources\sxs /LimitAccess

See also
* [http://blogs.technet.com/b/aviraj/archive/2012/08/04/windows-8-enable-net-framework-3-5-includes-net-2-0-and-3-0-i-e-netfx3-feature-in-online-amp-offline-mode.aspx?PageIndex=2 Windows 8: Enable .NET Framework 3.5]
* [http://msdn.microsoft.com/en-us/library/hh506443.aspx Installing the .NET Framework 3.5 on Windows 8]

==== TAPI dialer fails from Outlook when Lync client was/is installed ====
We have received reports that 1st-party TAPI dial-out from Outlook does not work anymore when a Lync client was installed. Some users report that this phenomenon occurred only after an upgrade to Windows 8. Reportedly, this can be [http://support.microsoft.com/kb/959625/en-us fixed by setting a registry key as outlined in Microsoft's knowledge-base]. You may want to give this a try. However, we have not seen this issue ourselves and thus can't comment on it further.

==== Slow Network Performance ====
TAPI is pretty sensitive to slow network performance. While the TSP is multi-threaded, some internal locking must be done so that slow requests to a PBX my block other pending requests, resulting in unpleasant performance. The TSP will create ''Windows Event Log'' entries of type ''slow SOAP call performance'' if this is detected. You should inspect your event log regularly and resolve the reason for such network performance.

Long PBX request round-trips may have a number of reasons:

; slow WAN performance : of course, if the WAN is slow or unstable, bad performance is the result
; inappropriate QoS : SOAP is using HTTP/HTTPS. In a QoS enabled network, call signalling and RTP may work fine, whereas HTTP/HTTPS is considered to be of no importance. You need to keep in mind that such QoS policy may lead to bad TAPI performance, as the SOAP traffic used by the TSP (being based on HTTP/HTTPS) may be delayed. You should assign SOAP traffic a similar priority as you do for VoIP signalling
; overloaded PBX : HTTP traffic is treated on a low priority level in the PBX. If the PBX runs near to 100% CPU load, while all RTP and VoIP signalling will work well still, HTTP traffic may get severely delayed. You should make sure your PBX runs well under 100% CPU load to get good TAPI performance. See [[Reference:Device Health Check]] for more details

==== TAPI on Windows 10 ====
In Windows 10, the TSP is not allowed any longer to read/write its own registry tree. For this reason, it is not possible to store or read the configuration. As a result, the TSP will not work. To fix this, you need to modify the registry access rights so that the TSP has read/write access to <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code><ref name="regkey"/>.

Note on windows registry paths<ref name="regkey">
Due to a change in ''Windows Registry Access Rights'' in Windows 10, from Build 8165, the configuration is stored in
: <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>
(a place that is suitable for Windows 10 too). Before, the configuration was stored in
: <code>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Telephony\innovaphone® PBX V8 TAPI Service Provider</code>

See [[#Upgrade_from_Build_8164_or_earlier| Upgrade from Build 8164 or_earlier ]] above for more details.
</ref>:
<references/>

=== Tweaks ===
There are a few configuration options which should be used rarely. They can be enabled by setting an appropriate registry key.

Since Hotfix 15 the location to set the interop tweaks has been changed to <code>HKEY_LOCAL_MACHINE\SOFTWARE\innovaphone\innovaphone® PBX V8 TAPI Service Provider</code>:

; ProcessorMask : REG_DWORD. If set, the TSP will use <code>SetProcessAffinityMask(GetCurrentProcess(), set)</code> to limit TSP execution to one or more of the existing processors. Set to <code>0xff</code> by default.

; LineTimeOut : REG_DWORD. Can be set to a number of seconds the TSP should wait for the determination of lines to finish (default 90). On a large PBX, or a PBX with slow slaves, the determination might not finish in the default time frame. If this happens, TAPI applications may show ''Line unnamed'' line entries in their line list. If this is a problem, set it to a larger value (e.g. <code>120</code>).

; IgnoreDevStatus : REG_DWORD. Some applications get confused if TAPI reports line to be disconnected or out-of-service dynamically. Setting this to a non-zero value will disable any such notification.

; ClearFwdOnSet : REG_DWORD. If set to a non-zero value, the TSP will clear all current call forward settings before a lineForward request is executed. This implies that all call forward settings are ''replaced'' by the new settings. Standard behaviour is to only modify the settings, that is, replace all current settings of the same type with the settings found in the lineForward request (for example, if there is only one setting in the request that defines a CFU, then the current CFU settings are replaced by the new one provided. All others, such as e.g. CFNR settings, are left untouched).

: Tapi spec is pretty clear on how this should work: ''The provider should "unforward everything" prior to setting the new forwarding instructions''. Even though, for historical reasons, ClearFwdOnSet=0 has been the default in all TAPI versions prior to V8 hotfix 6, from hotfix 6 on, the default changes to 1, as this has turned out to be the widely accepted interpretation.

; No3PTY : REG_DWORD. See [[Reference8:TAPI_Service_Provider#Notes_on_3PTY_Conferences | Notes_on_3PTY_Conferences]] below.

; HiddenRecordingNumber: REG_SZ. Active recording in an innovaphone PBX is implemented as an implicit 3PTY conference with the recording sink as one of the parties. These will be shown as usual in the TAPI callstate. However, some applications get confused as this results in a situation, where a normal endpoint (read: phone) has more than one active (i.e. ''not on hold'') call. To suppress such calls in the TAPI call states, you can set this tweak to the number of the recording sink as configured in the phone's recording configuration tab. If so, any outgoing call from an endpoint that is registered with a PBX user object with a called number that equals the setting of this tweak, will be suppressed. So if your recording sink has the number <code>44</code>, you would set this registry value to <code>44</code> (this is available from TAPI V8 hotfix 8). Please note that this feature actually suppresses any call info for such calls, however, it does not revert previously announced call infos. So if the call is initiated using ''overlapped dialling'', all call states will be shown until the called number matches the value of <code>HiddenRecordingNumber</code> and all subsequent call states will be suppressed. This will probably leave the call shown in ''dialling'' state. The feature should be used for destinations which are called using ''block dialling'' only thus.

; SilentHold : REG_DWORD. When a call is put on hold using <code>lineHold</code>, the held party will hear ''music on hold'' emitted by the PBX. The hold-initiator will hear a dialling tone (PBX firmware v11r2 and up, with older versions the initiator would hear ''music on hold''). When <code>SilentHold</code> is set to a non-zero value, the initiating party will hear silence - i.e. no dialling tone (this is available from TAPI V8 hotfix 8).



; NoDuplicateConnectedCalls : REG_DWORD. If set to 1, the TSP will never show more than one call per line to be active. Extra active calls will be shown as ''on-hold''. The situation occurs e.g. when a user initiates a 3PTY conference on the phone. This essentially is a bug fix for Microsoft's OCS client which forces any extra active call on-hold, thereby disturbing the 3PTY function. If your are using [http://www.estos.de/download/software/eccg.htm ESTOS' Call Control Gateway]: from version ''2.0.1.1474 - 05.11.2008'' there is a fix for this same problem available. This option thus is deprecated.

; UseFirstLeg2 : REG_DWORD. TAPI allows only for a single leg-2 info (redirection information in case of a call forward). If a call is forwarded mutliple times, by default the last redirection is shown in TAPI. If <code>UseFirstLeg2</code> is set to 1 however, the first redirection is shown.

; UseNameForDeviceGuid : REG_DWORD. The TSP will create a TAPI line for each ''Device'' of each PBX object (if ''MapDevices'' is set). The internal unique identifier includes the ''Hardware Id'' found in the ''Device''. If this changes, the TAPI line representing the ''Device'' is considered new and a new TAPI ''permanent line id'' is allocated. This may be annoying cause when a device serial number (e.g. for a telephone) is used as ''Hardware Id'', replacing the device creates a new TAPI line. If ''UseNameForDeviceGuid'' is set to 1, the TSP will use the ''Device''s ''Name'' instead (which usually not changes). While this might be more convenient, be aware that you ''must'' make sure that no PBX object has duplicate ''Name''s! Otherwise, TAPI will get confused. Available from build 8178

; ShowConfGUID : REG_DWORD. If set and not 0, the TSP will implicitly set each call's CallData to a string such as "<code>conf-guid:</code>''call-guid''". ''call-guid'' is a 66-byte Unicode16 string (32 hex characters plus terminating 0). Note that this will interfere with an application's use of the lineSetCallData function (tapi.h) and is therefore disabled by default. Available from build 8190

; NoFix : REG_DWORD. If set and not 0, the TSP will not trigger a full re-synchronization if it receives implausible state messages. Available from build 8197.

===List of supported TSPI functions===

The TSP supports the following TAPI Service Provider Interface Functions. Note that these do not map one to one with TAPI user functions. For more information, see the Microsoft TAPI documentation.

*TSPI_lineAnswer
*TSPI_lineBlindTransfer
*TSPI_lineClose
*TSPI_lineCloseCall
*TSPI_lineCompleteTransfer
*TSPI_lineDevSpecific
*TSPI_lineDevSpecificFeature
*TSPI_lineDial
*TSPI_lineDrop
*TSPI_lineForward
*TSPI_lineGenerateDigits
*TSPI_lineGetAddressCaps
*TSPI_lineGetAddressID
*TSPI_lineGetAddressStatus
*TSPI_lineGetCallAddressID
*TSPI_lineGetCallHubTracking
*TSPI_lineGetCallIDs
*TSPI_lineGetCallInfo
*TSPI_lineGetCallStatus
*TSPI_lineGetDevCaps
*TSPI_lineGetExtensionID
*TSPI_lineGetID
*TSPI_lineGetLineDevStatus
*TSPI_lineGetNumAddressIDs
*TSPI_lineHold
*TSPI_lineMakeCall
*TSPI_lineNegotiateExtVersion
*TSPI_lineNegotiateTSPIVersion
*TSPI_lineOpen
*TSPI_linePark
*TSPI_linePickup
*TSPI_lineRedirect
*TSPI_lineSelectExtVersion
*TSPI_lineSendUserUserInfo
*TSPI_lineSetAppSpecific
*TSPI_lineSetCallData
*TSPI_lineSetCallHubTracking
*TSPI_lineSetCallParams
*TSPI_lineSetCurrentLocation
*TSPI_lineSetDefaultMediaDetection
*TSPI_lineSetMediaMode
*TSPI_lineSetStatusMessages
*TSPI_lineSetupTransfer
*TSPI_lineSwapHold
*TSPI_lineUnhold
*TSPI_lineUnpark

*TSPI_providerConfig
*TSPI_providerCreateLineDevice
*TSPI_providerEnumDevices
*TSPI_providerGenericDialogData
*TSPI_providerInit
*TSPI_providerInstall
*TSPI_providerRemove
*TSPI_providerShutdown
*TSPI_providerUIIdentify
=====Notes on Consultation Calls=====
This TSP supports the <code>lineSetupTransfer</code> function. However, strictly speaking, this function is not needed and should not be used. It is merely intended for applications which do not offer a consultation call interface to the user when this function is not available. Instead, <code>TSPI_lineMakeCall</code> can be used where <code>lineSetupTransfer</code> would be otherwise. The notion of a special ''consultation call'' is an idiosyncrasy forced by legacy PBX technologies which were not able to transfer two arbitrary calls. In these scenarios, a potentially to-be-transferred call needed to be linked to the primary call. The PBX can transfer two arbitrary calls and thus there is no need for <code>lineSetupTransfer</code>. This ability is indicated by the <code>LINEADDRCAPFLAGS_TRANSFERMAKE</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE </code> flags. The transfer is then requested by using <code>TSPI_lineCompleteTransfer</code>.

=====Notes on 3PTY Conferences=====
The TSP supports the management of 3PTY conferences. These can be initiated by using <code>TSPI_lineCompleteTransfer</code> with <code>LINETRANSFERMODE_CONFERENCE</code> instead of <code>LINETRANSFERMODE_TRANSFER</code>. This is indicated by the flags <code>LINEADDRCAPFLAGS_CONFERENCEHELD</code> and <code>LINEADDRCAPFLAGS_CONFERENCEMAKE</code>. The 3PTY function is actually implemented by the innovaphone IP phones (such as IP2xx). Therefore, these capabilities are only advertised if the line is based on a PBX user object. Still, some lines where the capabilities are advertised cannot do 3PTY (such as e.g. DECT lines, analogue lines, 3rd party devices, ...). So the call to <code>TSPI_lineCompleteTransfer</code> will succeed but the conference will not be initiated and the subsequent call states will not indicate a conference (as there is no).

Also, if non-telephone devices are registered with a PBX user object and these device have multiple concurrent calls (e.g. a call center connected with a multi-channel XCapi), these will be viewed as 3PTY calls (as this is the way such calls appear to the TAPI: a line with more than one non-held call). If these calls are in fact no 3PTY, this may lead to confusing call indications from TAPI. It is better to register such objects as a PBX gateway object. Special treatment of 3PTY calls can be disabled by setting the registry flag <code>No3PTY</code> (from build 8087 onwards).

A 3PTY conference will create a new call handle for the conference. The only operation available for such a handle is <code>TSPI_lineDrop</code>. This will terminate the conference and restore the state active before the conference was initiated (that is, the phone that implemented the conference will now have 2 calls, one active and one on hold). This is indicated by not setting <code>LINEADDRCAPFLAGS_CONFDROP</code>.

A <code>lineDrop()</code> on one of the 2 ''real'' calls involved will of course cancel this call and thus remove the 3PTY.

======Notes on Intrusion Calls======
A special case of 3PTY is an intrusion call initiated by a [[Reference9:Phone/User/Function-Keys/Partner | partner function key]]. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the intrusion call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is an intrusion call).

======Notes on Recording Calls======
A special case of 3PTY is a recording call. This effectively creates an user-invisible 3PTY on the phone. To TAPI, this looks like a 3PTY (which it in fact is). However, phones before firmware version 9 hotfix 19 will not be able to release this 3PTY upon request. Thus, you will see a 3PTY in TAPI which cannot be dropped. From phone firmware 9 hotfix 19 on, the request to drop this 3PTY will cancel the recording call. Note that TAPI will nevertheless ''not'' set <code>LINEADDRCAPFLAGS_CONFDROP</code> on such conferences (as TAPI does not know that this is a recording call).

Recording calls are shown as normal conferences (unless <code>No3PTY</code> is set). This might be confusing to applications and/or users. See the <code>HiddenRecordingNumber</code> tweak above for a method to hide such calls.

=====Notes on parked Calls=====
The PBX can park calls from and to any existing PBX object, e.g. by virtue of [[Reference8:Configuration/Registration/Function-Keys/Park | specific feature keys]]. They are parked to/from a numeric ''park position''. In SOAP however, calls are parked to an object by providing the objects '''UserInitialize()''' handle and a park position. Parked calls are then reported as straight calls with a distinct signalling state (8). The park position is not conveyed as part of the '''CallInfo''' record. To unpark, '''[[Reference8:SOAP_API#integer_UserPickup.28int_user.2C_string_cn.2C_integer_call.2C_string_group.2C_int_reg.2C_InfoArray_info.29 | UserPickup]]''' can be used providing the parked calls call handle as '''call''' argument.

The TAPI specification is unclear on how the address information required to '''lineUnpark()''' a call can be obtained by an application (except that it is returned from '''linePark()''' if the call was parked using TAPI). The TSP thus indicates parked calls on a line with a call reason <code>LINECALLREASON_PARKED</code>. The caller id information is set to the parked calls call handle. This way, the application can take the caller id information and provide it to '''lineUnpark()''' to unpark a call. If the appication does not support this mode of operation but supports '''lineUnpark()''' and lets the user input the park identifier, the user can just provide the caller id information.

Some applications do not care for parked calls (by examining the call reason) and just blindly report these calls like ordinary connected calls (thereby confusing the user). To work around this problem, reporting parked calls can be turned off in the TSP configuration dialogue.

=====Notes on sending User to User Information =====
The TAPI specification for sending UserUserInfo closely resembles the way ISDN defines this service. Although the innovaphone PBX supports this service both with H.323 and SIP, it is ''not'' supported in this TSP. Instead, sending user to user information is implemented using H.323/SIP messaging. However, there are some important deviations and limitations caused hereby:
* data is ''not transparent''. That is, the TSP only allows for null-terminated unicode to be sent. The data must be of even length and the last two bytes must be null.
* data is ''not sent within the call'', but by initiating a separate call. This implies that the target number used to send the message carrying the data to is 'guessed' from the available call data. For example, if the call is in a connected state and a connected number is known, the message is sent to the connected number. If the call is in the ringback state, then either the called number or - if available - the redirection number is used and so forth.
* message calls are not indicated by the SOAP CallInfo records. As a result, messages sent with lineSendUserUserInfo cannot be received with TAPI
=====Notes on receiving User to User Information =====
From build 8200, the TSP will deliver incoming UUI on a call. Although lineSendUserUserInfo will still send H.323/SIP messages instead of native UUI, you can now receive incoming UUI (for example from ISDN) in a LINE_CALLINFO message.

=====Notes on sending proprietary innovaphone Remote Control Facilities =====
The SOAP [[Reference10:SOAP_API#UserRc.28integer_call.2C_integer_rc.29|UserRc]] function allows to send various [[Reference:Remote Control Facility|facility messages]] to an innovaphone phone device. In some cases, it is useful to be able to invoke this function through a standard TAPI mechanism. This can be achieved by using the TAPI '''lineBlindTransfer''' function. If the ''called party name'' provided as destination for the ''lineBlindTransfer'' (in ''lpszDestAddress'') has the magic value <code>USERRC</code>, then the ''called subaddress'' is converted to an integer and the result is sent as remote control facility to the call the blind transfer is applied for. For details on how to code the ''called party name'' and the ''called subaddress'' into ''lpszDestAddress'' see [http://msdn.microsoft.com/en-us/library/windows/desktop/ms726017%28v=vs.85%29.aspx Microsoft's ''Canonical Address'' specification]. This works from TAPI8 hotfix 4.

For example, initiating a blind transfer to <code>|16^USERRC</code> (empty address, subaddress 16 (that is, [[Reference:Remote Control Facility|''change to handset mode'']]), called name <code>USERRC</code>) will switch the phone having the call to be transferred into handset mode (and <code>|18^USERRC</code> will switch it back to handsfree mode). Of course, no actual transfer will happen in these cases (''lineBlindTransfer'' is merely used as a vehicle to send the facility to the proper call).

Such proprietary facility message can also be sent with ''lineMakeCall'' (that is, in SOAP's [[Reference10:SOAP_API#integer_UserCall.28integer_user.2C_string_cn.2C_string_e164.2C_string_h323.2C_int_reg.2C_InfoArray_info.2C_int_rc.2C_string_srce164.29|UserCall]] function). For example, setting up a call to <code>123|21^USERRC</code> will send an intrusion call to extension 123 and intrude any call that might be active there. This works from TAPI8 hotfix 6. Please note that the innovaphone TAPI service provider does not support TAPI's ''lineCompleteCall'' function with <code>LINECALLCOMPLMODE_INTRUDE</code> though (as TAPI's call model here does not fit with the PBX's call model). Please also note that intrusion calls look like 3PTY calls to TAPI (see [[#Notes_on_Intrusion_Calls|notes on intrusion calls]] above).

Remote control facilities are implemented by the telephone devices, so these functions are subject to the phone firmware in use.

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

== Related Articles ==
* [[Howto:Troubleshooting the TAPI service provider]]
* [[ReleaseNotes8:TAPI]]

Reference8:TAPI Service Provider

2024-11-04T17:22:55Z

Ckl: /* Notes on sending User to User Information */

Courseware:IT Advanced - 09 Custom certificates

2024-10-16T15:31:43Z

Ckl: Protected "Course14:IT Advanced - 09 Custom certificates" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Custom certificates | 142 }}

Courseware:IT Advanced - 09 Custom certificates

2024-10-16T15:31:34Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Custom certificates | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Custom certificates | 142 }}

Courseware:IT Advanced - 08 Using a custom DNS on your mobile phone

2024-10-16T15:30:29Z

Ckl: Protected "Course14:IT Advanced - 08 Using a custom DNS on your mobile phone" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Using a custom DNS on your mobile phone | 142 }}

Courseware:IT Advanced - 08 Using a custom DNS on your mobile phone

2024-10-16T15:30:19Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Using a custom DNS on your mobile phone | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Using a custom DNS on your mobile phone | 142 }}

Courseware:IT Advanced - 07 Public access to PBX resources (practice)

2024-10-16T15:28:34Z

Ckl: Protected "Course14:IT Advanced - 07 Public access to PBX resources (practice)" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Public access to PBX resources (practice)| 142 }}

Courseware:IT Advanced - 07 Public access to PBX resources (practice)

2024-10-16T15:28:24Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Public access to PBX resources (practice)| 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Public access to PBX resources (practice)| 142 }}

Courseware:IT Advanced - 06 Public Access to PBX Resources (theory) - optional

2024-10-16T15:26:46Z

Ckl: Protected "Course14:IT Advanced - 06 Public Access to PBX Resources (theory) - optional" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Public Access to PBX Resources (theory) - optional | 142 }}

Courseware:IT Advanced - 06 Public Access to PBX Resources (theory) - optional

2024-10-16T15:26:39Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Public Access to PBX Resources (theory) - optional | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Public Access to PBX Resources (theory) - optional | 142 }}

Courseware:IT Advanced - 05 Setting up the Apps

2024-10-16T15:25:02Z

Ckl: Protected "Course14:IT Advanced - 05 Setting up the Apps" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Apps | 142 }}

Courseware:IT Advanced - 05 Setting up the Apps

2024-10-16T15:24:41Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Apps | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Apps | 142 }}

Courseware:IT Advanced - 04 Setting up the Application Platform

2024-10-16T15:21:49Z

Ckl: Protected "Course14:IT Advanced - 04 Setting up the Application Platform" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Application Platform | 142 }}

Courseware:IT Advanced - 04 Setting up the Application Platform

2024-10-16T15:21:39Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Application Platform | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | Setting up the Application Platform | 142 }}

Courseware:IT Advanced - 03 The Application Platform

2024-10-16T15:20:36Z

Ckl: Protected "Course14:IT Advanced - 03 The Application Platform" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | The Application Platform | 142 }}

Courseware:IT Advanced - 03 The Application Platform

2024-10-16T15:20:29Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | The Application Platform | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | The Application Platform | 142 }}

Courseware:IT Advanced - 02 PBX - initial Configuration

2024-10-16T15:18:53Z

Ckl: Protected "Course14:IT Advanced - 02 PBX - initial Configuration" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

{{#moodlebook: Master Templates / V14 Templates / Advanced | PBX - initial Configuration | 142 }}

Courseware:IT Advanced - 02 PBX - initial Configuration

2024-10-16T15:18:45Z

Ckl: Created page with "{{#moodlebook: Master Templates / V14 Templates / Advanced | PBX - initial Configuration | 142 }}"

{{#moodlebook: Master Templates / V14 Templates / Advanced | PBX - initial Configuration | 142 }}